Cognitive Substrate Backbone
The backbone is WednesdayAI’s Tier 1 message bus — a thin typed contract unifying event fan-out and durable work delivery under one envelope with mandatory privacy and access identity. It generalizes three previously separate mechanisms (diagnostic-events, server-broadcast, and the storage-outbox) without becoming a fourth spine.Two delivery classes
The backbone distinguishes two delivery classes, each with different semantics:
Events are fire-and-forget: handler errors are caught and the event is dropped (never crashes the process). Work is transmit-and-acknowledge: a claimed work item must be acked (success) or nacked (failure → retry with exponential backoff).
The BusMessage envelope
Every message on the backbone — event or work — is aBusMessage<TPayload>. The envelope is the single wire format for both delivery classes.
openclaw/plugin-sdk specifier still loads (ADR 2057).
Mandatory identity fields
The envelope is fail-closed on identity. BothprivacyContext and accessContext are required and enforced at construction time:
privacyContext: NonEmptyArray<string>— a non-empty array of privacy scope tags (e.g.["tenant:t1", "lane:l1"]). An empty array is rejected.accessContext: AccessContext— must be routable: eitheractorId+tenantId, orlaneId, or asystembrand ("core"/"legacy"). A bare{}is rejected.
Optional fields
id?: string— when omitted, a UUID is generated. For work class, set this to your idempotency key to get deduplication.correlationId?: string— reuse shipped runId/turnId identity for tracing.causationId?: string— links a message to the message that caused it.saliency?: number— clamped to 1..5; NaN/Infinity → undefined.
The Backbone interface
TheBackbone type is the transport-agnostic contract. In 0a, only the in-process implementation ships; a concrete broker (NATS/Redis Streams/Postgres LISTEN) is deferred.
publishfans out an event to in-process subscribers. Also bridges toemitDiagnosticEvent(fordiagnostic.*topics) and the gateway broadcaster (if wired).subscriberegisters a handler for a topic glob (e.g."channel.*","memory.lesson"). Returns an unsubscribe function.enqueuedurably persists a work item to thebus_work_itemstable.claimleases a pending work item for a consumer. Returnsnullif no work is available.ackmarks a work item as processed (idempotent).nackmarks a work item as failed and schedules a retry.
Creating a backbone instance
Durable work: BusWorkBackend and dispatcher
Work-class messages are persisted to siblingbus_work_items and bus_work_claims tables inside the existing StorageRuntime (not an extension of the storage-outbox). Both SQLite and Postgres backends are implemented.
BusWorkBackend interface
SessionStorageRuntime.busWork alongside the existing outbox?: StorageOutboxBackend slot. The storage-outbox is untouched (byte-for-byte).
BusWorkDispatcher
The dispatcher is the work-class equivalent ofStorageOutboxDispatcher — a claim/process/ack loop with concurrency, batching, timeout, and retry. It does not poll on its own; the caller drives dispatchOnce().
Exactly-once semantics
- SQLite: SELECT-then-INSERT inside
BEGIN IMMEDIATE. NoON CONFLICT(the index is non-unique). Exactly-once is enforced at the claim layer via a(work_id, consumer_id)subquery in the ready-row SELECT. - Postgres:
ON CONFLICT (idempotency_key) DO NOTHING(full-unique index) +FOR UPDATE SKIP LOCKEDon claim. The claims side-table tracks per-consumer claim state. - Lease recovery: both backends recover expired leases — a
claimedrow whoselease_untilhas passed is eligible for re-claim (mirrors the storage-outbox’s lease-recovery guard).
Claim ID encoding
Claim IDs are encoded as${workId}|${consumerId}|ct:${claimToken} via formatTaskClaimHandle / parseTaskClaimHandle, with a fresh claim token per claim. The row’s lease_owner is <backend>:<gatewayInstanceId>:<consumerId>:<claimToken>, and ack, nack, release and renew compare the full owner. A handle from an earlier claim whose lease expired therefore cannot settle a later claim of the same item, in the same process or in another gateway process. The encoding is internal to the backend; consumers treat the claim ID as an opaque string.
Fail-closed authorization
The backbone enforces symmetric fail-closed authorization across both delivery classes (events + work) and both directions (consume + produce). This is the core security invariant.PluginBackboneGrants
A plugin’s grants are declared in its manifest and constructed by the plugin loader (the loader bindssource / consumerId to the manifest identity — plugins cannot self-assert).
Authorization rules
- Every privacyContext scope must be in the granted set (not “any”, but “all”).
- A grant entry matches a scope exactly, or as
<namespace>:*, which matches any non-empty value in that namespace.["tenant:t1", "lane:*"]therefore covers every current and future lane of tenantt1, whilelane:*does not matchlaneX:l1. Neithertenant:t1on its own nor a bare*implies lanes — a bare*is a literal scope. Pairlane:*withconsumeAccess.lanes: ["*"], since privacyContext and accessContext are gated separately. - The topic must match a granted glob (exact match OR
prefix.*). - The accessContext must fall within the granted access allow-sets for each dimension.
- System/channel/delivery topics (
channel.message,reply.deliver,agent.turn, …) are default-deny unless explicitly granted.
agent.turn. Isolated cron
agentTurn jobs enqueue that topic; the in-process agent-turn runner claims,
executes, and acks. Plugins must not enqueue agent.turn unless the manifest
explicitly grants that produce topic. See Agent-turn runner.
- Empty
privacyContextis rejected (does not pass vacuously). - Non-routable
accessContext({}with no actor+tenant, no lane, no system brand) is rejected.
ScopedBackboneApi
Plugins never interact with the rawBackbone directly. The loader constructs a ScopedBackboneApi that enforces grants on every call:
Consumer-id binding
ack and nack only accept claim IDs that were returned by this scoped API’s claim() or claimSessionWork() — a plugin cannot ack/nack another plugin’s claims. This is enforced via an internal ownedClaims: Set<string>.
Security alerts
Rejected operations emit abackbone.authz.rejected diagnostic event with the plugin ID, reason, and topic. This is wired into the OTEL exporter as openclaw.backbone.authz.rejected counter.
Session-lifecycle reconciler
The reconciler fans out session-lifecycle work (e.g. “session started” → notify all consumers) with a shared idempotency key so the 0s direct-pull path and the 0a backbone fan-out path never double-deliver.materialized Set is a fast-path cutover seam; the durable proof of materialization is the bus_work_items.idempotency_key column (unique index rejects duplicate enqueues).
Channel message publishing
Core publishes all channel traffic (user + assistant) aschannel.message events with mandatory privacy/access context. The publishChannelMessage function constructs the envelope and publishes it through the backbone. The identity argument is fail-closed: sessionId, sessionKey, tenantId and actorId are all required.
BusMessage.payload is a ChannelMessagePayload (exported from
wednesdayai/plugin-sdk) with four fields: role, text, sessionId and sessionKey.
payload.sessionId is the per-reset session id — it changes whenever the session resets.
payload.sessionKey is the stable key that addresses the conversation’s durable state across
resets, so a consumer that keeps per-session state keys on sessionKey, never on sessionId.
Treat sessionKey as opaque: never derive the channel, account, peer, group or user from its
text (ADR 0081).
The enumerateChannelEmitPaths() function statically audits all channel adapter send paths. In 0a, all adapters are whitelisted (migration to route through publishChannelMessage is a separate workstream). The audit function is the gap documentation — it enumerates every path that should eventually set privacy/access context.
WorkerPool / cooperative-yield
TheWorkerPool is an SDK utility for running CPU-heavy handlers without blocking the event loop. It uses cooperative yielding (setImmediate / setTimeout(0)) rather than worker threads.
lagThresholdMs, a gateway.event_loop_lag diagnostic event is emitted with the lag duration, threshold, and pool ID.
Outbound delivery durability
Outbound channel delivery is routed through the backbone’s durable work class (not the storage-outbox). This addresses BACKLOGF-2026-06-15-*.
channel:recipientId:sessionId:seq — distinct from the reconciler’s (consumerId:sessionId:effectKind:schemaVersion) key.
For administrators
Database tables
The backbone adds two sibling tables to the context schema (alongsidectx_storage_outbox, which is untouched):
ctx_bus_work_items— the durable work queue. Columns:work_id,idempotency_key(unique),topic,source,payload(JSONB/TEXT),privacy_context,access_context,correlation_id,causation_id,schema_version,status(pending/claimed/processed/failed),attempts,available_at,lease_owner,lease_until,last_error,created_at,updated_at.ctx_bus_work_claims— per-consumer claim side-table. Columns:claim_id,work_id,consumer_id,lane_id,tenant_id,lease_owner,lease_until,status(pending/claimed/processed/failed),attempt_count,last_error,schema_version,processed_at,created_at,updated_at.
OTEL metrics
The backbone adds two OTEL counters to thediagnostics-otel extension:
Diagnostic events
Two new diagnostic event variants are added to the closedDiagnosticEventPayload union:
gateway.event_loop_lag—{ lagMs, thresholdMs, poolId }— emitted by WorkerPool.backbone.authz.rejected—{ pluginId, reason, topic? }— emitted by ScopedBackboneApi on authz failure.
onDiagnosticEvent listener with an exhaustiveness guard, add a case for these variants.
No new environment variables
The backbone does not introduce any new environment variables. It uses the existingOPENCLAW_* configuration and the configured session storage runtime.