Skip to content
HoloMUSHHoloMUSHHoloMUSH

Substrate Contract

Every plugin in HoloMUSH is a consumer of the substrate. This page is the reference inventory of the surfaces plugins can rely on. For the rules that govern the plugin–substrate relationship and why they exist, see Substrate contract invariants; for the procedure to declare and register emit types, see Register plugin emit types.

Canonical detail lives in the design spec: Substrate Contract Design Spec.

Substrate primitives plugin authors can rely on

Section titled “Substrate primitives plugin authors can rely on”

These surfaces are stable for the lifetime of the spec. You do not need to implement them; the substrate provides them turn-key.

Primitive What it does Where it lives
JetStream event bus Durable per-stream delivery, replay, history fallback, ULID identity, JetStream-seq ordering internal/eventbus/ — Publisher, Subscriber, HistoryReader interfaces
Crypto envelope Per-event-type sensitivity enforcement, KEK/DEK rotation, AuthGuard fence, INV-50 downgrade fence internal/plugin/event_emitter.go, internal/plugin/sensitivity_fence.go
Manifest emit-type validation (INV-S5) Startup-time fail-fast when manifest declared set does not equal code-registered set internal/plugin/manager.go::loadPlugin
ABAC engine Policy evaluation, attribute resolution wiring, default-deny posture internal/access/ — access.Engine interface
Focus coordinator Per-connection subscription state, multi-tab visibility, restore-on-reconnect internal/grpc/focus/, pkg/plugin/focus_client.go
Plugin host RPCs (Go + Lua parity) Emit, QueryHistory, JoinFocus/LeaveFocus/PresentFocus, PluginAuditService.AuditEvent pkg/plugin/ (Go SDK), internal/plugin/hostfunc/ (Lua hostfuncs)
Per-plugin storage Isolated Postgres schema + role, embedded migration runner, search_path scoping internal/store/, plugin’s migrations/
Audit projection Host ack-and-skip for plugin-owned subjects; dispatch to plugin’s AuditEvent RPC internal/eventbus/audit/

For the full substrate inventory with path:line citations, see §1 of the substrate-contract spec.

eventkit and groupkit SDKs (named, not yet built)

Section titled “eventkit and groupkit SDKs (named, not yet built)”

pkg/plugin/eventkit/ and pkg/plugin/groupkit/ are co-designed in the substrate-contract spec but their code lands only after N=2 validation (see Substrate contract invariants). Today, plugins implement event-replay, group-membership, and focus-wire patterns inline (scenes-bespoke, channels-bespoke).

SDK Location Primitives (planned) Who can use it
eventkit pkg/plugin/eventkit/ replay (ABAC-filtered history fan-out), cryptoemit (call-site sensitivity assertion) Any plugin emitting ABAC-gated sensitive events
groupkit pkg/plugin/groupkit/ membership, focuswire, groupabac Uses with explicit member-of-entity state (scenes, channels)

References

Section titled “References”

Specs:

ADRs (theme:social-spaces):