> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cognitive Substrate Backbone

> The backbone message and task bus — the BusMessage envelope, durable work class, fail-closed plugin authorization, and the dispatchers that consume work.

# 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:

| Class | Transport | Durability | Replay | Consumers | Use for |
| - | - | - | - | - | - |
| **event** | In-process fan-out | Volatile (best-effort, at-most-once) | No replay in v1 | Multiple subscribers | Diagnostic events, gateway broadcasts, channel messages |
| **work** | Sibling `bus_work_items` table | Durable (at-least-once + idempotent + retry) | Yes (claim/ack/nack) | Single consumer per work item | Outbound delivery, session-lifecycle fan-out, background jobs |

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.

```ts theme={"dark"}
import { createEvent, createWork } from "wednesdayai/plugin-sdk";

const event = createEvent({
  topic: "channel.message",
  source: "my-plugin",
  payload: { role: "user", text: "hello" },
  privacyContext: ["tenant:t1"],
  accessContext: { actorId: "user-1", tenantId: "t1" },
});

const work = createWork({
  topic: "channel.outbound",
  source: "outbound-delivery:telegram",
  payload: { channel: "telegram", recipientId: "123", sessionId: "s1" },
  privacyContext: ["tenant:t1", "lane:l1"],
  accessContext: { actorId: "user-1", tenantId: "t1", laneId: "l1" },
  id: "telegram:123:s1:1", // optional explicit id = idempotency key
});
```

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.

```ts theme={"dark"}
export type Backbone = {
  publish(message: BusMessage): void;
  subscribe<TPayload = unknown>(
    topic: string,
    handler: BackboneSubscribeHandler<TPayload>,
  ): Unsubscribe;
  enqueue(work: BusMessage): Promise<void>;
  claim<TPayload = unknown>(
    topic: string,
    consumerId: string,
    leaseMs: number,
  ): Promise<BackboneWorkClaim<TPayload> | null>;
  ack(workId: string): Promise<void>;
  nack(workId: string, error?: string, retryAt?: number): Promise<void>;
};
```

* `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

```ts theme={"dark"}
import { createInProcessBackbone, createProductionBackbone } from "wednesdayai/plugin-sdk";

// Events-only backbone (no durable work):
const backbone = createInProcessBackbone({
  broadcastToGateway: gatewayBroadcaster, // optional: bridge to WS clients
});

// Production backbone (events + durable work):
const prodBackbone = createProductionBackbone({
  busWork: sqliteBusWorkBackend, // or postgresBusWorkBackend
  broadcastToGateway: gatewayBroadcaster,
});

// Clean up (unsubscribes the diagnostic-events bridge listener):
backbone.dispose();
```

## 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

```ts theme={"dark"}
export interface BusWorkBackend {
  enqueue(message: BusMessage): Promise<void>;
  claim(topic: string, consumerId: string, leaseMs: number): Promise<BusWorkClaimResult | null>;
  ack(workId: string, result: { ok: true } | { ok: false; error: string }): Promise<void>;
  lease(workId: string, owner: string, leaseUntil: Date): Promise<void>;
}
```

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()`.

```ts theme={"dark"}
import { createBusWorkDispatcher } from "wednesdayai/plugin-sdk";

const dispatcher = createBusWorkDispatcher({
  backend: busWorkBackend,
  topic: "channel.outbound",
  consumerId: "outbound-delivery",
  handler: async (work) => {
    // Process the work item...
    return { ok: true };
  },
  concurrency: 4,
  batchSize: 25,
  hookTimeoutMs: 30_000,
});

await dispatcher.dispatchOnce();
await dispatcher.stop();
```

### 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).

```ts theme={"dark"}
export interface PluginBackboneGrants {
  pluginId: string;
  consumeScopes: string[];   // privacyContext scopes this plugin may read
  produceScopes: string[];   // privacyContext scopes this plugin may write
  consumeTopics: string[];   // topic globs this plugin may subscribe to / claim
  produceTopics: string[];   // topic globs this plugin may publish / enqueue
  consumeAccess?: {           // accessContext allow-sets for consume
    tenants?: string[];
    lanes?: string[];
    actors?: string[];
    system?: ("core" | "legacy")[];
  };
  produceAccess?: { ... };    // same shape for produce
}
```

### 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](https://docs.wednesdayai.dev/developers/plugins/agent-turn-runner.md).

* 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:

```ts theme={"dark"}
import { createScopedBackboneApi } from "wednesdayai/plugin-sdk";

const api = createScopedBackboneApi({
  backbone: productionBackbone,
  grants: {
    pluginId: "my-plugin",
    consumeScopes: ["tenant:t1", "lane:l1"],
    produceScopes: ["tenant:t1"],
    consumeTopics: ["channel.*"],
    produceTopics: ["memory.lesson"],
  },
});

// publish enforces: class=="event", topic in produceTopics, scopes in produceScopes
api.publish(event);

// subscribe enforces: topicGlob in consumeTopics, then re-checks each delivered message
const unsub = api.subscribe("channel.*", (msg) => { ... });

// claim enforces: topicGlob in consumeTopics, message in consumeScopes, claim owned by this plugin
const claim = await api.claim("channel.outbound", 30_000);
if (claim) {
  await api.ack(claim.id);   // only claims returned by THIS api's claim() can be acked
}

// enqueue enforces: class=="work", topic in produceTopics, scopes in produceScopes
await api.enqueue(work);
```

#### 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.

```ts theme={"dark"}
import { createSessionReconciler } from "wednesdayai/plugin-sdk";

const reconciler = createSessionReconciler({
  scopedApi,
  busWork: busWorkBackend,
  consumerId: "session-lifecycle",
});

// Canonical key: (consumerId:sessionId:effectKind:schemaVersion)
const key = reconciler.canonicalIdempotencyKey("sess-1", "session-started");

// fanOutSessionWork is a no-op if already materialized (zero double-delivery)
await reconciler.fanOutSessionWork("sess-1", "session-started", {
  topic: "session.lifecycle",
  source: "reconciler",
  payload: { sessionId: "sess-1" },
  privacyContext: ["tenant:t1"],
  accessContext: { system: "core" },
});
```

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.

```ts theme={"dark"}
import { publishChannelMessage } from "wednesdayai/plugin-sdk";

await publishChannelMessage(
  backbone,
  {
    role: "user",
    text: "hello",
  },
  {
    sessionId: "0f1b7c54-9a21-4a1d-8d5e-2b6c7a8d9e01",
    sessionKey: "agent:main:main",
    tenantId: "t1",
    actorId: "user-1",
    laneId: "l1",
  },
);
```

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.

```ts theme={"dark"}
import { createWorkerPool } from "wednesdayai/plugin-sdk";

const pool = createWorkerPool({
  maxConcurrent: 4,
  lagThresholdMs: 100, // emit gateway.event_loop_lag if a slice exceeds this
  poolId: "my-pool",
});

await pool.run(async () => {
  // CPU-heavy work...
  await pool.yield(); // cooperative yield to let other tasks run
});

await pool.close(); // drains queue + active tasks
```

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-*`.

```ts theme={"dark"}
import { enqueueOutboundDelivery } from "wednesdayai/plugin-sdk";

await enqueueOutboundDelivery(backbone, {
  channel: "telegram",
  recipientId: "chat:123",
  payload: { text: "hello" },
  sessionId: "sess-1",
  tenantId: "t1",
  laneId: "l1",
  actorId: "user-1",
  auditId: "audit-1",
  idempotencyKey: "telegram:chat:123:sess-1:1",
});
```

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:

| Metric | Type | Description |
| - | - | - |
| `openclaw.gateway.event_loop_lag` | Counter | Incremented when a WorkerPool task slice exceeds `lagThresholdMs`. Tags: `poolId`. |
| `openclaw.backbone.authz.rejected` | Counter | Incremented when a backbone authorization check fails (produce or consume). Tags: `pluginId`, `reason`, `topic`. |

### 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.