Skip to main content

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 a BusMessage<TPayload>. The envelope is the single wire format for both delivery classes.
The legacy openclaw/plugin-sdk specifier still loads (ADR 2057).

Mandatory identity fields

The envelope is fail-closed on identity. Both privacyContext 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: either actorId + tenantId, or laneId, or a system brand ("core" / "legacy"). A bare {} is rejected.
These fields are not decorative — they are the basis for fail-closed authorization (see below).

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

The Backbone type is the transport-agnostic contract. In 0a, only the in-process implementation ships; a concrete broker (NATS/Redis Streams/Postgres LISTEN) is deferred.
  • publish fans out an event to in-process subscribers. Also bridges to emitDiagnosticEvent (for diagnostic.* topics) and the gateway broadcaster (if wired).
  • subscribe registers a handler for a topic glob (e.g. "channel.*", "memory.lesson"). Returns an unsubscribe function.
  • enqueue durably persists a work item to the bus_work_items table.
  • claim leases a pending work item for a consumer. Returns null if no work is available.
  • ack marks a work item as processed (idempotent).
  • nack marks a work item as failed and schedules a retry.

Creating a backbone instance

Durable work: BusWorkBackend and dispatcher

Work-class messages are persisted to sibling bus_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

The backend is wired into SessionStorageRuntime.busWork alongside the existing outbox?: StorageOutboxBackend slot. The storage-outbox is untouched (byte-for-byte).

BusWorkDispatcher

The dispatcher is the work-class equivalent of StorageOutboxDispatcher — 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. No ON 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 LOCKED on claim. The claims side-table tracks per-consumer claim state.
  • Lease recovery: both backends recover expired leases — a claimed row whose lease_until has 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 binds source / 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 tenant t1, while lane:* does not match laneX:l1. Neither tenant:t1 on its own nor a bare * implies lanes — a bare * is a literal scope. Pair lane:* with consumeAccess.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.
Core (not plugins) is the only current producer of 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 privacyContext is 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 raw Backbone 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 a backbone.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.
The in-memory 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) as channel.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.
The delivered 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

The WorkerPool 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.
When a task’s wall-clock slice exceeds 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 BACKLOG F-2026-06-15-*.
The idempotency key format is 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 (alongside ctx_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.
Both tables follow the configured storage backend (SQLite for local/jsonl-fs, Postgres for hosted). There is no degraded in-process-only path for work class — a durable backend is required.

OTEL metrics

The backbone adds two OTEL counters to the diagnostics-otel extension:

Diagnostic events

Two new diagnostic event variants are added to the closed DiagnosticEventPayload union:
  • gateway.event_loop_lag — { lagMs, thresholdMs, poolId } — emitted by WorkerPool.
  • backbone.authz.rejected — { pluginId, reason, topic? } — emitted by ScopedBackboneApi on authz failure.
Both are exported by the OTEL extension. If you have a custom 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 existing OPENCLAW_* configuration and the configured session storage runtime.

No new CLI commands

The backbone is an internal infrastructure layer. There are no user-facing CLI commands in 0a. Plugin authors interact with it through the Plugin SDK.