signal_bus_spec - mark-ik/graphshell GitHub Wiki
Doc role: Canonical spec for SignalBus (or equivalent) as the Register layer's cross-registry event fabric.
Status: Active / canonical (planned abstraction; current direct routing remains transitional)
Short label: signal_bus
Related docs:
- register_layer_spec.md (Register layer parent spec)
- register/SYSTEM_REGISTER.md (register-layer hub/index)
- 2026-02-22_registry_layer_plan.md (registry ecosystem and capability model)
Policy authority: This file is the canonical policy authority for SignalBus (or equivalent) behavior and boundaries.
Policy in this file should be distilled from canonical specs and accepted research conclusions.
Adopted standards (see 2026-03-04_standards_alignment_report.md §§3.6, 3.7):
- OpenTelemetry Semantic Conventions — routing-health, drop, queue-pressure, and routing-failure diagnostic channel naming and severity
- OSGi R8 — typed signal/event routing operates within the Register layer; signal envelopes follow OSGi event-model vocabulary
- Signal-not-intent policy: Signals notify observers; they do not request authoritative mutation.
- Emitter-decoupling policy: Publishers must not require knowledge of concrete subscribers.
- Typed-envelope policy: Signals must carry typed payload, source attribution, and routing metadata.
- No-hidden-business-logic policy: Listener handlers must not become undocumented mutation authorities.
- Routing-health policy: Drops, failures, throttling, and queue pressure must be diagnosable.
SignalBus is the typed event-routing fabric for decoupled cross-registry and cross-subsystem notifications.
In scope:
- typed signals and envelopes
- publish/subscribe or equivalent observer-routing contracts
- source metadata, causality, and routing health
- explicit decoupling between emitters and observers
Out of scope:
- direct graph reducer mutations
- tile-tree mutation ownership
- ad hoc business logic hidden in event listeners
Signals are not intents:
- Intents request authoritative state mutation
- Signals notify observers without transferring ownership of mutation authority
The signal fabric belongs to the Register layer because it exists to decouple capabilities and system observers.
- Signals must be typed and attributable to a source.
- Emitters should not need to know concrete observers.
- Signal handling must not become a hidden substitute for explicit mutation authorities.
- Routing failures, drops, and backpressure must be diagnosable.
- concrete routing facade/API replacing transitional direct fanout
- queue depth, latency, and drop diagnostics
- stronger causality metadata for cross-registry workflows
- scoped subscription classes
- priority-aware routing policies
- remote/distributed signal relays for future peer workflows
- Signal semantics are distinguishable from direct calls and intents.
- At least one producer and multiple observers can be described through the same typed routing contract.
- Routing health is observable through diagnostics.