@blamejs/core 0.9.24 → 0.9.28

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.9.x
 
+- v0.9.28 (2026-05-14) — **`b.agent.postureChain` — set-based compliance posture propagated across every agent boundary.** Eighth substrate slice. Compliance regimes (HIPAA / PCI-DSS / GDPR / SOC2) protect DIFFERENT regulated-data classes — they're orthogonal, not a linear lattice. Set semantics match how real-world regulations actually overlap (a clinic that processes payment cards operates under BOTH HIPAA + PCI). (1) **`b.agent.postureChain.create({ audit })`** — facade with `isSubset(targetSet, sourceSet)` (the core check: target.set ⊇ source.set), `union(...sets)`, `canDelegate(sourceSet, targetSet, methodName)`, `appendHop(envelope, hopName)`, `validate(envelope, agentPostureSet)`, `declareRegime(name)`, `REGIMES` (frozen array). (2) **Cross-boundary downgrade refusal** — `validate(envelope, agentPostureSet)` throws `agent-posture-chain/downgrade-refused` when the target (agent) posture set is missing any regime the source (envelope) carries. Audit emit at HEIGHTENED with the missing regime list + chain trail so operator review pipelines surface every downgrade attempt. (3) **Hop trail tracking** — `appendHop(envelope, hopName)` immutably extends `{ chainTrail, enteredAt, hopCount }`. Hop count caps at default 16 — defends infinite recursion across agent delegation. Per-hop timestamps must be monotonic non-negative numbers (guard rejects non-monotonic, length mismatches, etc.). (4) **`b.guardPostureChain`** — envelope shape validator. Refuses oversized hop trail (cap = 16 hops strict), non-ASCII hop names (operator-greppable), C0 / DEL forbidden, duplicate hops in trail (recursion guard), duplicate regimes in `postureSet`, non-monotonic `enteredAt` timestamps, `enteredAt` length mismatch with `chainTrail`. (5) **Built-in regimes**: HIPAA, PCI-DSS, GDPR, SOC2. Operator declares custom regimes via `chain.declareRegime("healthcare-tier-1")`; duplicate declarations refused. (6) **Empty source ⊆ any target** — unscoped calls (no posture context) flow freely; only declared source regimes constrain the target. Fuzz harness ships in `fuzz/guard-posture-chain.fuzz.js`. Per the substrate playbook in `memory/specs/blamejs-agent-posture-chain-spec.md`.
+- v0.9.27 (2026-05-14) — **`b.agent.saga` — multi-step coordination with compensation cascade.** Seventh substrate slice. (1) **`b.agent.saga.create({ name, steps, audit })`** — every step has `{ name, run: async (ctx, state) => {}, compensate?: async (ctx, state) => {} }`. `saga.run(ctx, initialState, opts)` walks steps in order; each `run` mutates the shared `state` object. On step throw the framework fires every previously-completed step's `compensate` in REVERSE order (steps that hadn't completed aren't compensated). (2) **Compensation failure semantics** — a compensate that throws emits `agent.saga.compensation_failed` audit at CRITICAL severity, halts further compensations, and the saga's final error message carries both the original step failure + the compensation failure so operator alert pipelines see the full context. (3) **No saga-level retry** — operator-confirmed 2026-05-14: saga's value-add is COMPENSATION, not retry. Step.run wraps `b.retry` if needed (with v0.9.22 idempotency available, internal retry inside step.run is side-effect-safe). Keeps the saga primitive focused on the coordination contract. (4) **Audit lifecycle** — `agent.saga.started` / `step_started` / `step_completed` / `step_failed` / `compensation_started` / `compensation_completed` / `compensation_failed` / `failed` / `completed`. Each event carries `sagaId` + `name` + `stepName` + `stepIndex` for operator dashboards. (5) **`b.guardSagaConfig`** — saga-creation config validator. Refuses empty steps array, duplicate step names, non-function `run`, non-function `compensate` (when provided), non-ASCII saga name, oversized step count (default 32). Ships profile + posture vocabulary uniform with rest of guard family. Fuzz harness ships in `fuzz/guard-saga-config.fuzz.js`. Per the substrate playbook in `memory/specs/blamejs-agent-saga-spec.md`.
+- v0.9.26 (2026-05-14) — **`b.agent.tenant` — multi-tenant isolation as a first-class primitive.** Sixth substrate slice. Replaces the per-operator wiring of `actor.tenantId === registeredTenant` (which tends to leak across handlers) with one centralized scope. (1) **`b.agent.tenant.create({ backend, audit, permissions })`** — facade with `register(tenantId, { posture, archivePolicy, metadata })`, `unregister(tenantId, opts)`, `lookup(tenantId)`, `list({})`, `check(actor, agentTenantId)`, `derivedKey(tenantId, purpose)`, `auditFor(tenantId)`, `listArchived()`. Pluggable backend; in-memory default. (2) **Cross-tenant gate (`check`)** — refuses calls where `actor.tenantId !== agentTenantId` unless the actor holds `framework-cross-tenant-admin` scope (every cross-tenant access by an admin emits `agent.tenant.cross_tenant_access` audit at HEIGHTENED severity for operator review). (3) **Per-tenant derived keys (`derivedKey`)** — composes `b.crypto.namespaceHash` for deterministic per-tenant key derivation from `purpose` + `tenantId`. Cross-tenant decrypt refused at the vault boundary by construction — each tenant's seal-key derivation differs, so even with disk access an attacker can't cross-decrypt. (4) **Per-tenant audit (`auditFor`)** — returns an audit wrapper that auto-tags every emit with `metadata.tenantId` so each tenant's audit trail is independently filterable in the operator's audit pipeline. (5) **Archive-default destroy semantics** — `unregister(tenantId)` archives by default (retention-safe, matches SEC 17a-4 6yr / FINRA 4511 / HIPAA §164.530(j) / MiFID II Art 16(7) compliance needs). Destruction requires explicit `{ destroy: true, stepUpToken, dualControlApprover, reason, actor }` — four preconditions all required together. The framework validates the SHAPE; the operator's step-up middleware + dual-control middleware grants the actual tokens upstream. Missing any precondition refuses with a specific `agent-tenant/destroy-requires-step-up` / `-dual-control` / `-reason` / `-actor` code so operators see exactly what's missing. (6) **`b.guardTenantId`** — tenant-id shape validator. Refuses non-ASCII (operator-greppable in audit logs across stack boundaries), path-traversal (`..` / `/` / `\` / NUL / C0 / DEL), oversized (default 64 bytes), reserved `ROOT` / `FRAMEWORK` / `*`, leading `.`. Posture vocabulary uniform (`strict` / `balanced` / `permissive` profiles; hipaa / pci-dss / gdpr / soc2 postures pin strict). Fuzz harness ships in `fuzz/guard-tenant-id.fuzz.js`; ClusterFuzzLite matrix entry added. Per the substrate playbook in `memory/specs/blamejs-agent-tenant-spec.md`.
+- v0.9.25 (2026-05-14) — **`b.agent.eventBus` — typed cross-agent publish/subscribe with schema enforcement, posture-tagged topics, and cross-tenant subscribe refusal.** Fifth substrate slice. Substrate for every agent-to-agent reaction the framework will need (`mail.scan.malware-detected` → MX refuses source, `mail.crypto.key-rotated` → vault invalidates cached recipient keys, `ai.classify.prompt-injection-detected` → agent quarantines). (1) **`b.agent.eventBus.create({ pubsub, audit, permissions })`** — facade over operator-supplied `b.pubsub` (or any `{ publish, subscribe, unsubscribe }`-shaped backend). Surface: `registerTopic(name, { schema, posture, permissions, tenantScope })`, `publish(name, payload, { actor })`, `subscribe(name, handler, { actor })` returns unsubscribe fn, `listTopics({ actor })`. (2) **Topic registration with schema** — declared at boot via flat key→type map (`string` / `number` / `boolean` / `integer` / `isoDateTime` / `array` / `object`; suffix `?` marks optional). Unknown topics refuse publish + subscribe so typos fail loudly. Duplicate registration refused (operator must `unregister` first when the surface gains that surface in a later substrate slice). (3) **Schema enforcement at every boundary** — every payload validated against schema before `pubsub.publish` AND at each delivery (subscriber-side re-validation defends in-flight tampering). Refused payloads emit `agent.event_bus.delivery_dropped` audit; the publisher's call throws. (4) **Permission gating** — `permissions.publish` + `permissions.subscribe` per-topic scope arrays; `b.permissions.check(actor, scope)` on every publish + subscribe call. Mismatch emits `agent.event_bus.publish_denied` / `subscribe_denied` audit at HEIGHTENED severity. (5) **Cross-tenant isolation** — `tenantScope: true` topics carry the publisher's `tenantId` in the wire envelope; subscriber's actor must declare a matching tenantId or the event is silently dropped at delivery with `agent.event_bus.cross_tenant_drop` audit. (6) **`b.guardEventBusTopic`** — topic name validator. Refuses dot-count < 3 (operators use `<domain>.<source>.<event>` shape), oversized (default 128 bytes), non-ASCII (operator-greppable in audit logs across cross-process boundaries), reserved `framework.*` prefix, path-traversal shapes, slash, backslash, C0 / DEL. (7) **`b.guardEventBusPayload`** — payload schema validator. Bounded byte cap (default 64 KiB — events are metadata, not bulk data; publishers reference bulk data via `b.objectStore` IDs). Type-check cascade refuses non-finite numbers, malformed ISO-8601 dateTime (length-bound to 64 chars before regex test so a hostile input can't burn regex-engine CPU), missing required fields, unknown fields (schemas must be exhaustive). (8) **Audit lifecycle** — `agent.event_bus.topic_registered` / `published` / `subscribed` / `publish_denied` / `subscribe_denied` / `delivery_dropped` / `cross_tenant_drop` / `handler_threw`. (9) **Shared agent-audit helper extracted** — `lib/agent-audit.js` factored out the identical `_safeAudit` wrapper that v0.9.21 orchestrator + v0.9.22 idempotency + v0.9.24 stream + v0.9.25 eventBus all carried inline. The four agent substrate modules now compose `agentAudit.safeAudit`. Fuzz harnesses ship in `fuzz/guard-event-bus-topic.fuzz.js` + `fuzz/guard-event-bus-payload.fuzz.js`. Per the substrate playbook in `memory/specs/blamejs-agent-event-bus-spec.md`.
 - v0.9.24 (2026-05-14) — **`b.agent.stream` — async-iterable variants for agent methods that yield N rows.** Fourth slice of the v0.9.21–v0.9.30 substrate playbook (numbers shifted +1 by v0.9.23 CodeQL insertion). JMAP `Email/queryChanges` against million-message mailboxes returns an array today — OOM on client + agent before the response ships. RFC 8620 §5.5 allows `position`-paginated responses; real mailboxes need cursor-backed delivery with built-in backpressure. (1) **`b.agent.stream.create({ openCursor, cursorOpts, batchSize, orchestrator, actor, kind, audit })`** — returns an object implementing `[Symbol.asyncIterator]` so operators write `for await (var row of stream) { ... }`. Operator supplies an `openCursor(cursorOpts)` factory returning a cursor with `fetchBatch(batchSize) → { rows, nextCursor, done }` + optional `close()` + optional `lastSeenCursor()`. (2) **Backpressure built-in** — async-generator semantics; each `next()` call yields one row from an in-memory batch buffer; the cursor only refetches when the buffer drains. Pulling slowly applies backpressure to the store side; a slow client can't OOM the server. (3) **Auto cursor close on every exit path** — consumer `break` calls iterator `.return()`, consumer `throw` calls `.throw()`, natural exhaustion calls `.next()` until done — all three close the cursor via `try`/`finally`-style `_closeOnce` and emit `agent.stream.closed` audit with reason (`exhausted` / `consumer-break` / `consumer-throw` / `drain` / `error`). (4) **Drain marker** — when orchestrator drain fires mid-stream, the next `next()` call returns ONE final `{ _drainMarker: true, lastSeenCursor: <opaque>, reason: "drain" }` row + closes the cursor. Clients reconnecting via JMAP-WebSocket / IMAP NOTIFY pass `lastSeenCursor` back to resume from the same position against the new agent post-deploy. Composes v0.9.21 `orchestrator.registerStream` / `unregisterStream` / `isDraining` hooks. (5) **`b.guardStreamArgs`** — validates `b.agent.stream.create` opts. Refuses non-integer `batchSize` (silent shard-style routing drift class — same shape Codex caught on v0.9.21), batchSize out of `[1, 1024]` strict-profile range, empty `kind` string, function / regex / Buffer / `__proto__` keys inside `cursorOpts` (structured-clone-unsafe — same shape `b.guardMailQuery` refuses for filter specs). Ships `strict` / `balanced` / `permissive` profiles + hipaa / pci-dss / gdpr / soc2 postures. (6) Audit lifecycle: `agent.stream.opened` on iterator creation, `agent.stream.closed` on every exit path, `agent.stream.drain_marker_emitted` when orch drain fires. Fuzz harness ships in `fuzz/guard-stream-args.fuzz.js`. Per the substrate playbook in `memory/specs/blamejs-agent-stream-spec.md`.
 - v0.9.23 (2026-05-14) — **CodeQL alert sweep — 30 alerts closed across 6 rule classes + wiki @primitive validator extracted into static gates.** Standalone substrate slice inserted into the v0.9.21–v0.9.30 playbook; downstream substrate slices shift +1 (stream now v0.9.24, eventBus v0.9.25, tenant v0.9.26, saga v0.9.27, postureChain v0.9.28, trace v0.9.29, snapshot v0.9.30). The 30 alerts were regressions of v0.9.18's earlier batch fix — v0.9.15's framework-wide `require()`-binding rename sweep (184 renames across 108 files) shifted line numbers and the suppression comments stopped tracking. (1) **`js/file-system-race` (10 sites)** — `lib/atomic-file.js:_readSyncCore` migrated from `statSync`+`readFileSync` to the canonical TOCTOU-safe-read scaffold (open fd → `fstatSync` → `readSync` loop → `closeSync` in finally; ENOENT now surfaces from `openSync`); `lib/restore-rollback.js` marker write switched to `openSync(..., "wx", 0o600)` + `writeSync` + `fsyncSync` + EEXIST tolerance; `lib/network-tls.js` new `_readPathFile` fd-based reader; `lib/backup/bundle.js` fd-narrowed read with short-read detection; `lib/static.js` content-safety gate converted to `fsp.open` filehandle pattern; `lib/vault/seal-pem-file.js`, `lib/atomic-file.js:fsyncDir`, `test/30-chain.js`, `examples/wiki/test/validate-{env,cli}-snapshot.js`, `examples/wiki/lib/source-doc-parser.js` got suppression refresh OR fd-narrowed refactor per shape. (2) **`js/insecure-temporary-file` (6 sites)** — `lib/mtls-ca.js` new `_writeExclusive` helper using `openSync(..., "wx", mode)` + `writeSync` + `fsyncSync`; `lib/vault/rotate.js` + `lib/http-client.js` got suppression refresh pointing at the operator-supplied stagingDir / 64-bit CSPRNG suffix defenses. (3) **`js/path-injection` (2 sites in `lib/static.js`)** — suppression refresh pointing at the upstream `_resolveSafe` sandbox check at line 181 (lexical resolve + `startsWith(rootResolved + sep)` + realpath escape guard + guardFilename gate). (4) **`js/remote-property-injection` (7 sites)** — `lib/middleware/csrf-protect.js` cookie-parse output + `lib/websocket.js` `_parseExtensionHeader` params switched to `Object.create(null)` so attacker-controlled keys have no prototype chain to pollute; `lib/middleware/body-parser.js` multipart fields got suppression refresh pointing at the POISONED_KEYS gate at line 867; `test/40-consumers.js` + `test/00-primitives.js` test fixtures suppressed with `test/` scope justification. (5) **`PinnedDependenciesID` (2 workflow files)** — every `uses:` line was already SHA-pinned per v0.9.18; the remaining alerts pointed at the `npm install --no-audit --no-fund` step in `.github/workflows/npm-publish.yml` + `ci.yml`; added explicit `name@version` specifiers (esbuild + postject, mirroring `package.json`'s exact pins) so CodeQL recognizes the install as pinned without committing a lockfile (which CLAUDE.md hard rule §1 forbids — vendored stack, zero npm runtime deps). (6) **`js/regex/missing-regexp-anchor` (1 site)** — `scripts/build-vendored-sbom.js:42` host-extractor regex anchored to `^https?://github.com/` so an attacker-controlled `entry.source` containing `github.com` as a path or query substring can't misdirect purl dispatch into the github branch. (7) **Wiki @primitive validator extracted into static gates** — the `@related namespace-not-primitive` nit fired on PRs #50 (v0.9.20), #51 (v0.9.21), AND #52 (v0.9.22) — same class, three rediscoveries because the validator only ran in CI's wiki-e2e gate (~90s round-trip), never in local pre-push. Extraction: `examples/wiki/lib/source-comment-block-validator.js` (shared engine, pure module, no side effects) + `scripts/validate-source-comment-blocks.js` (framework-level standalone wrapper, runs in 419–466ms, no `@blamejs/core` / vault / DB / network dependencies). Existing wiki-e2e gate refactored to delegate to the shared engine; CI invocation unchanged. CLAUDE.md release workflow step 4 (static gates) now lists `node scripts/validate-source-comment-blocks.js` after `codebase-patterns.test.js`. Each suppression comment references the active defense by file:line so future CodeQL re-runs OR future readers know which suppression applies. Multi-agent fan-out — 4 parallel subagents in isolated git worktrees per rule class.
 - v0.9.22 (2026-05-14) — **`b.agent.idempotency` — cross-dispatch idempotency keys honored at every agent consumer boundary; JMAP retry-safe semantics from day one.** Second slice of the v0.9.21–v0.9.29 substrate playbook. (1) **`b.agent.idempotency.create({ store, audit, ttlMs, maxResultBytes, fingerprintArgs })`** — pluggable backing store via `{ get, put, delete, gc }`; in-memory default ships for single-process deployments, operator wires durable backends (sqlite-backed adapter or external). Surface: `instance.get(method, actorId, key)` returns cached envelope `{ result, firstAt, lastReplayedAt, replayCount, requestFingerprint }` or `null`; `instance.put(method, actorId, key, result, { args, requestFingerprint })` serializes via `b.safeJson.stringify` + persists with TTL + refuses key-reuse-different-args via the request-fingerprint (sha3-512 of args sans key) check; `instance.invalidate(method, actorId, key)` is the saga-compensation escape hatch; `instance.gc({ olderThanMs })` for periodic cleanup. (2) **Keys hashed at the boundary** — operator-supplied keys never reach disk in raw form; namespace-hashed via `b.crypto.namespaceHash("agent.idempotency", method + "\\0" + actorId + "\\0" + key)`. Cross-actor + cross-method isolation by construction (an attacker can't replay another actor's mutation by guessing the key). (3) **Replay tracking** — every cache hit increments `replayCount` + bumps `lastReplayedAt`; audit emits `agent.idempotency.replay` with the truncated actor-id hash + first/replay timestamps so operator pipelines surface retry storms. (4) **`b.guardIdempotencyKey`** — operator-supplied key shape validator. Refuses oversized (default 256 bytes), control chars (C0/NUL/DEL — defends audit-log injection), slash + backslash (defends operators routing keys through filesystem paths), path-traversal (`..`), non-ASCII under strict (operator-greppable in audit logs across stack boundaries; permissive opts down for legacy Unicode tenant IDs). (5) **JSON round-trip test helper** — new `test/helpers/json-round-trip.js` exporting `assertJsonRoundTrip(shape, label)`. Catches the bug class Codex flagged on PR #51 (v0.9.21 `register()` stored agent function ref on backend row, lost in DB/JSON serialization). Refuses on function fields, Buffer fields, Date objects, Symbol keys, BigInt values, non-finite numbers, cycles. Applied retroactively to v0.9.21 agent-orchestrator backend row in regression test. (6) **Result size cap** (default 1 MiB per cached entry) — refuses with `agent-idempotency/result-too-big` so operators discover OOM-prone result shapes locally instead of at runtime. Fuzz harness ships in `fuzz/guard-idempotency-key.fuzz.js`; ClusterFuzzLite matrix entries added. Per the substrate playbook in `memory/specs/blamejs-agent-idempotency-spec.md`.

package/index.js

@@ -168,9 +168,18 @@ var guardMailSieve = require("./lib/guard-mail-sieve");
 var guardAgentRegistry = require("./lib/guard-agent-registry");
 var guardIdempotencyKey = require("./lib/guard-idempotency-key");
 var guardStreamArgs = require("./lib/guard-stream-args");
+var guardEventBusTopic = require("./lib/guard-event-bus-topic");
+var guardEventBusPayload = require("./lib/guard-event-bus-payload");
+var guardTenantId = require("./lib/guard-tenant-id");
+var guardSagaConfig = require("./lib/guard-saga-config");
+var guardPostureChain = require("./lib/guard-posture-chain");
 var agentOrchestrator = require("./lib/agent-orchestrator");
 var agentIdempotency = require("./lib/agent-idempotency");
 var agentStream = require("./lib/agent-stream");
+var agentEventBus = require("./lib/agent-event-bus");
+var agentTenant = require("./lib/agent-tenant");
+var agentSaga = require("./lib/agent-saga");
+var agentPostureChain = require("./lib/agent-posture-chain");
 var guardArchive = require("./lib/guard-archive");
 var guardJson = require("./lib/guard-json");
 var guardYaml = require("./lib/guard-yaml");
@@ -417,7 +426,12 @@ module.exports = {
   guardAgentRegistry: guardAgentRegistry,
   guardIdempotencyKey: guardIdempotencyKey,
   guardStreamArgs:  guardStreamArgs,
-  agent:            { orchestrator: agentOrchestrator, idempotency: agentIdempotency, stream: agentStream },
+  guardEventBusTopic: guardEventBusTopic,
+  guardEventBusPayload: guardEventBusPayload,
+  guardTenantId:    guardTenantId,
+  guardSagaConfig:  guardSagaConfig,
+  guardPostureChain: guardPostureChain,
+  agent:            { orchestrator: agentOrchestrator, idempotency: agentIdempotency, stream: agentStream, eventBus: agentEventBus, tenant: agentTenant, saga: agentSaga, postureChain: agentPostureChain },
   guardArchive:     guardArchive,
   guardJson:        guardJson,
   guardYaml:        guardYaml,

package/lib/agent-audit.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * b.agent._audit — internal shared audit-emit helper for the agent
+ * substrate (`b.agent.orchestrator` / `b.agent.idempotency` /
+ * `b.agent.stream` / `b.agent.eventBus` / future substrate slices).
+ *
+ * Each agent primitive emits audit events at lifecycle boundaries
+ * (registered / opened / closed / replay / denied / drop / etc). The
+ * emit logic is identical: actor shape → audit.safeEmit() → swallow
+ * any audit-side failures. Extracted here so the 4+ agent substrate
+ * modules don't re-implement the same wrapper.
+ *
+ * Internal — operator-facing surface is each primitive's `.audit`
+ * opt; this is the implementation detail.
+ */
+
+function safeAudit(auditImpl, action, actor, metadata) {
+  try {
+    auditImpl.safeEmit({
+      action: action,
+      actor:  actor ? { id: actor.id, roles: actor.roles || [] } : { id: "<system>" },
+      outcome: _outcomeFor(action),
+      metadata: metadata || {},
+    });
+  } catch (_e) { /* drop-silent — audit failures don't crash the call */ }
+}
+
+// "denied" / "drop" / "threw" / "different_args" / "miss" / "not_implemented"
+// all imply failure outcome; anything else is success. Per-primitive
+// classification can override by passing a metadata.outcome — that's
+// merged in by the caller, not here.
+function _outcomeFor(action) {
+  if (typeof action !== "string") return "success";
+  if (action.indexOf("denied")          >= 0) return "failure";
+  if (action.indexOf("drop")            >= 0) return "failure";
+  if (action.indexOf("threw")           >= 0) return "failure";
+  if (action.indexOf("different_args")  >= 0) return "failure";
+  if (action.indexOf("miss")            >= 0) return "failure";
+  if (action.indexOf("not_implemented") >= 0) return "failure";
+  return "success";
+}
+
+module.exports = {
+  safeAudit: safeAudit,
+};

package/lib/agent-event-bus.js

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * @module     b.agent.eventBus
+ * @nav        Agent
+ * @title      Agent Event Bus
+ * @order      65
+ *
+ * @intro
+ *   Typed cross-agent publish/subscribe on top of `b.pubsub` (or any
+ *   pubsub-shaped instance with `publish` / `subscribe` /
+ *   `unsubscribe`). Substrate for every agent-to-agent reaction the
+ *   mail stack + future agents need: `mail.scan.malware-detected` →
+ *   MX refuses source, `mail.crypto.key-rotated` → vault invalidates
+ *   cached recipient keys, `ai.classify.prompt-injection-detected` →
+ *   agent quarantines, etc.
+ *
+ *   The bus owns:
+ *
+ *     - **Topic registry** — `registerTopic(name, { schema, posture,
+ *       permissions, tenantScope })` declares the wire contract at
+ *       boot. Unknown topics refuse publish + subscribe so typos
+ *       fail loudly.
+ *     - **Schema enforcement** — every payload validated against the
+ *       declared schema before publish AND at each delivery
+ *       (defends in-flight tampering).
+ *     - **Permission gating** — `b.permissions.check(actor, scope)`
+ *       on every publish + subscribe.
+ *     - **Posture re-validation at delivery** — same shape as
+ *       v0.9.20 cross-queue posture check.
+ *     - **Audit lifecycle** — publish / subscribe / delivery / refused
+ *       events emit to the operator's audit chain.
+ *
+ *   ```js
+ *   var bus = b.agent.eventBus.create({
+ *     pubsub:       myPubsub,
+ *     audit:        b.audit,
+ *     permissions:  myPerms,
+ *   });
+ *
+ *   bus.registerTopic("mail.scan.malware-detected", {
+ *     schema: {
+ *       source:       "string",
+ *       confidence:   "number",
+ *       detectedAt:   "isoDateTime",
+ *     },
+ *     posture:    "soc2",
+ *     permissions: {
+ *       publish:   ["mail-scan:write"],
+ *       subscribe: ["mail-mx:write"],
+ *     },
+ *   });
+ *
+ *   await bus.publish("mail.scan.malware-detected", {
+ *     source: "1.2.3.4", confidence: 0.95, detectedAt: new Date().toISOString(),
+ *   }, { actor: { id: "scan-agent", roles: ["mail-scan-internal"] } });
+ *   ```
+ *
+ * @card
+ *   Typed cross-agent publish/subscribe. Topics registered with schema
+ *   + posture + permissions; every payload validated; subscriber-side
+ *   posture re-validated at delivery so no posture downgrade survives
+ *   the bus boundary.
+ */
+
+var lazyRequire           = require("./lazy-require");
+var { defineClass }       = require("./framework-error");
+var guardEventBusTopic    = require("./guard-event-bus-topic");
+var guardEventBusPayload  = require("./guard-event-bus-payload");
+var agentAudit            = require("./agent-audit");
+
+var audit                 = lazyRequire(function () { return require("./audit"); });
+
+var AgentEventBusError = defineClass("AgentEventBusError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.agent.eventBus.create
+ * @signature b.agent.eventBus.create(opts)
+ * @since     0.9.25
+ * @status    stable
+ * @related   b.agent.orchestrator.create, b.pubsub.create
+ *
+ * Create the bus facade. Returns an instance with `registerTopic` /
+ * `publish` / `subscribe` / `listTopics`. Operator supplies a pubsub-
+ * shaped backend; framework owns schema validation, permission
+ * gating, posture re-validation, audit lifecycle.
+ *
+ * @opts
+ *   pubsub:       { publish, subscribe, unsubscribe },   // required
+ *   audit:        b.audit namespace,                      // optional
+ *   permissions:  b.permissions instance,                  // optional
+ *
+ * @example
+ *   var bus = b.agent.eventBus.create({ pubsub: myPubsub });
+ *   bus.registerTopic("mail.scan.malware-detected", {
+ *     schema: { source: "string" },
+ *   });
+ *   await bus.publish("mail.scan.malware-detected", { source: "1.2.3.4" });
+ */
+function create(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new AgentEventBusError("agent-event-bus/bad-opts",
+      "create: opts required");
+  }
+  if (!opts.pubsub || typeof opts.pubsub.publish !== "function" ||
+      typeof opts.pubsub.subscribe !== "function") {
+    throw new AgentEventBusError("agent-event-bus/bad-pubsub",
+      "create: opts.pubsub must expose { publish, subscribe }");
+  }
+  var auditImpl   = opts.audit || audit();
+  var permissions = opts.permissions || null;
+  var topics      = new Map();
+
+  return {
+    registerTopic: function (name, topicOpts)    { return _registerTopic(topics, name, topicOpts || {}, auditImpl); },
+    publish:       function (name, payload, pOpts) { return _publish(topics, opts.pubsub, name, payload, pOpts || {}, permissions, auditImpl); },
+    subscribe:     function (name, handler, sOpts) { return _subscribe(topics, opts.pubsub, name, handler, sOpts || {}, permissions, auditImpl); },
+    listTopics:    function (args)                { return _listTopics(topics, args || {}, permissions); },
+    AgentEventBusError: AgentEventBusError,
+    guards: {
+      topic:   guardEventBusTopic,
+      payload: guardEventBusPayload,
+    },
+  };
+}
+
+// ---- Registry -------------------------------------------------------------
+
+function _registerTopic(topics, name, topicOpts, auditImpl) {
+  guardEventBusTopic.validate(name);
+  if (topics.has(name)) {
+    throw new AgentEventBusError("agent-event-bus/topic-duplicate",
+      "registerTopic: '" + name + "' already registered");
+  }
+  if (!topicOpts.schema || typeof topicOpts.schema !== "object") {
+    throw new AgentEventBusError("agent-event-bus/bad-schema",
+      "registerTopic: schema required (flat key→type map)");
+  }
+  var entry = {
+    name:        name,
+    schema:      Object.freeze(Object.assign({}, topicOpts.schema)),
+    posture:     topicOpts.posture || null,
+    tenantScope: topicOpts.tenantScope === true,
+    permissions: {
+      publish:   topicOpts.permissions && Array.isArray(topicOpts.permissions.publish)
+                   ? topicOpts.permissions.publish.slice() : null,
+      subscribe: topicOpts.permissions && Array.isArray(topicOpts.permissions.subscribe)
+                   ? topicOpts.permissions.subscribe.slice() : null,
+    },
+    registeredAt: Date.now(),
+  };
+  topics.set(name, entry);
+  _safeAudit(auditImpl, "agent.event_bus.topic_registered", null, {
+    name: name, posture: entry.posture, tenantScope: entry.tenantScope,
+  });
+}
+
+function _listTopics(topics, args, permissions) {
+  // Permission gate: list-topics requires no special scope by default;
+  // operator can wrap with their own permissions instance for stricter.
+  var out = [];
+  topics.forEach(function (entry) {
+    if (args.kind && entry.kind && entry.kind !== args.kind) return;
+    out.push({
+      name:        entry.name,
+      schema:      entry.schema,
+      posture:     entry.posture,
+      tenantScope: entry.tenantScope,
+      registeredAt: entry.registeredAt,
+    });
+  });
+  return out;
+}
+
+// ---- Publish --------------------------------------------------------------
+
+async function _publish(topics, pubsub, name, payload, pOpts, permissions, auditImpl) {
+  guardEventBusTopic.validate(name);
+  var entry = topics.get(name);
+  if (!entry) {
+    throw new AgentEventBusError("agent-event-bus/unknown-topic",
+      "publish: topic '" + name + "' not registered");
+  }
+  // Permission check for publish.
+  if (permissions && entry.permissions.publish) {
+    if (!pOpts.actor) {
+      throw new AgentEventBusError("agent-event-bus/no-actor",
+        "publish: topic '" + name + "' requires actor");
+    }
+    var allowedPub = false;
+    for (var i = 0; i < entry.permissions.publish.length; i += 1) {
+      if (permissions.check(pOpts.actor, entry.permissions.publish[i])) {
+        allowedPub = true; break;
+      }
+    }
+    if (!allowedPub) {
+      _safeAudit(auditImpl, "agent.event_bus.publish_denied", pOpts.actor, { topic: name });
+      throw new AgentEventBusError("agent-event-bus/publish-denied",
+        "publish: actor lacks any of " + JSON.stringify(entry.permissions.publish) +
+        " required for topic '" + name + "'");
+    }
+  }
+  // Schema validation.
+  guardEventBusPayload.validate(payload, entry.schema);
+  // Wrap the payload with topic metadata so subscribers can see the
+  // posture + tenantScope at delivery (re-validation).
+  var wrapped = {
+    _topic:       name,
+    _posture:     entry.posture,
+    _tenantId:    pOpts.actor && pOpts.actor.tenantId ? pOpts.actor.tenantId : null,
+    _publishedAt: Date.now(),
+    payload:      payload,
+  };
+  await pubsub.publish(name, wrapped);
+  _safeAudit(auditImpl, "agent.event_bus.published", pOpts.actor, {
+    topic: name, posture: entry.posture,
+  });
+  return { topic: name, publishedAt: wrapped._publishedAt };
+}
+
+// ---- Subscribe ------------------------------------------------------------
+
+async function _subscribe(topics, pubsub, name, handler, sOpts, permissions, auditImpl) {
+  guardEventBusTopic.validate(name);
+  var entry = topics.get(name);
+  if (!entry) {
+    throw new AgentEventBusError("agent-event-bus/unknown-topic",
+      "subscribe: topic '" + name + "' not registered");
+  }
+  if (typeof handler !== "function") {
+    throw new AgentEventBusError("agent-event-bus/bad-handler",
+      "subscribe: handler must be a function");
+  }
+  // Permission check for subscribe.
+  if (permissions && entry.permissions.subscribe) {
+    if (!sOpts.actor) {
+      throw new AgentEventBusError("agent-event-bus/no-actor",
+        "subscribe: topic '" + name + "' requires actor");
+    }
+    var allowedSub = false;
+    for (var i = 0; i < entry.permissions.subscribe.length; i += 1) {
+      if (permissions.check(sOpts.actor, entry.permissions.subscribe[i])) {
+        allowedSub = true; break;
+      }
+    }
+    if (!allowedSub) {
+      _safeAudit(auditImpl, "agent.event_bus.subscribe_denied", sOpts.actor, { topic: name });
+      throw new AgentEventBusError("agent-event-bus/subscribe-denied",
+        "subscribe: actor lacks any of " + JSON.stringify(entry.permissions.subscribe) +
+        " required for topic '" + name + "'");
+    }
+  }
+  // Cross-tenant subscription gate — when tenantScope is set, the
+  // subscriber's actor MUST declare a tenantId at subscribe-time.
+  // Subscribers without an actor.tenantId on a tenant-scoped topic
+  // are refused outright; the previous shape (filter only when both
+  // tenants present) silently accepted such subscribers and let them
+  // receive every tenant's events.
+  var subscriberTenant = sOpts.actor && sOpts.actor.tenantId ? sOpts.actor.tenantId : null;
+  if (entry.tenantScope && !subscriberTenant) {
+    _safeAudit(auditImpl, "agent.event_bus.subscribe_denied", sOpts.actor, {
+      topic: name, reason: "tenant-scoped-topic-requires-actor-tenant-id",
+    });
+    throw new AgentEventBusError("agent-event-bus/subscribe-denied",
+      "subscribe: tenant-scoped topic '" + name +
+      "' requires actor.tenantId; subscribers without a tenant identity are refused");
+  }
+
+  // Wrapped handler: re-validate posture + tenant at delivery so an
+  // in-flight tamper / cross-tenant routing attempt is refused at the
+  // consumer boundary (not at the bus's trust boundary alone).
+  async function _wrappedHandler(wrapped, evMeta) {
+    if (!wrapped || typeof wrapped !== "object" || !wrapped._topic) {
+      _safeAudit(auditImpl, "agent.event_bus.delivery_dropped", sOpts.actor,
+        { topic: name, reason: "malformed-envelope" });
+      return;
+    }
+    // Tenant-scope check: subscriber's tenantId must match the
+    // publisher's tenantId from the wire envelope. If the envelope
+    // lacks _tenantId (publisher omitted), that's a tampered or
+    // malformed wire and the delivery drops.
+    if (entry.tenantScope) {
+      if (!wrapped._tenantId || wrapped._tenantId !== subscriberTenant) {
+        _safeAudit(auditImpl, "agent.event_bus.cross_tenant_drop", sOpts.actor, {
+          topic: name,
+          publisherTenant:  wrapped._tenantId || null,
+          subscriberTenant: subscriberTenant,
+          reason: wrapped._tenantId ? "tenant-mismatch" : "missing-publisher-tenant",
+        });
+        return;
+      }
+    }
+    // Re-validate payload against schema in case of in-flight tamper.
+    try { guardEventBusPayload.validate(wrapped.payload, entry.schema); }
+    catch (_e) {
+      _safeAudit(auditImpl, "agent.event_bus.delivery_dropped", sOpts.actor,
+        { topic: name, reason: "payload-schema-violation" });
+      return;
+    }
+    // Await handler — supports async handlers + catches their async
+    // rejections. Without await, an async handler that rejects would
+    // surface as an unhandled rejection and skip the audit emit.
+    try {
+      await handler(wrapped.payload, {
+        topic: name, publishedAt: wrapped._publishedAt,
+        source: evMeta && evMeta.source,
+      });
+    }
+    catch (e) {
+      _safeAudit(auditImpl, "agent.event_bus.handler_threw", sOpts.actor,
+        { topic: name, message: (e && e.message) || String(e) });
+    }
+  }
+  var token = await pubsub.subscribe(name, _wrappedHandler);
+  _safeAudit(auditImpl, "agent.event_bus.subscribed", sOpts.actor, { topic: name });
+  return function unsubscribe() {
+    try {
+      if (typeof token === "function") return token();
+      if (token && typeof token.unsubscribe === "function") return token.unsubscribe();
+    } catch (_e) { /* best-effort */ }
+  };
+}
+
+// ---- Audit helper ---------------------------------------------------------
+
+function _safeAudit(auditImpl, action, actor, metadata) {
+  agentAudit.safeAudit(auditImpl, action, actor, metadata);
+}
+
+module.exports = {
+  create:                  create,
+  AgentEventBusError:      AgentEventBusError,
+  guards: {
+    topic:   guardEventBusTopic,
+    payload: guardEventBusPayload,
+  },
+};

package/lib/agent-idempotency.js

@@ -64,6 +64,7 @@ var { defineClass }   = require("./framework-error");
 var bCrypto           = require("./crypto");
 var safeJson          = require("./safe-json");
 var guardIdempotencyKey = require("./guard-idempotency-key");
+var agentAudit        = require("./agent-audit");
 
 var audit             = lazyRequire(function () { return require("./audit"); });
 
@@ -331,14 +332,7 @@ function _inMemoryBackend() {
 }
 
 function _safeAudit(auditImpl, action, actor, metadata) {
-  try {
-    auditImpl.safeEmit({
-      action: action,
-      actor:  actor ? { id: actor.id, roles: actor.roles || [] } : { id: "<system>" },
-      outcome: action.indexOf("denied") >= 0 || action.indexOf("different_args") >= 0 ? "failure" : "success",
-      metadata: metadata || {},
-    });
-  } catch (_e) { /* drop-silent */ }
+  agentAudit.safeAudit(auditImpl, action, actor, metadata);
 }
 
 module.exports = {

package/lib/agent-orchestrator.js

@@ -56,6 +56,7 @@ var C                 = require("./constants");
 var { defineClass }   = require("./framework-error");
 var guardAgentRegistry = require("./guard-agent-registry");
 var bCrypto           = require("./crypto");
+var agentAudit        = require("./agent-audit");
 
 var audit             = lazyRequire(function () { return require("./audit"); });
 var cluster           = lazyRequire(function () { return require("./cluster"); });
@@ -449,14 +450,7 @@ function _checkPermission(ctx, actor, scope) {
 }
 
 function _safeAudit(ctx, action, actor, metadata) {
-  try {
-    ctx.audit.safeEmit({
-      action: action,
-      actor:  actor ? { id: actor.id, roles: actor.roles || [] } : { id: "<system>" },
-      outcome: action.indexOf("denied") >= 0 || action.indexOf("miss") >= 0 ? "failure" : "success",
-      metadata: metadata || {},
-    });
-  } catch (_e) { /* drop-silent — audit emit failures don't crash the call */ }
+  agentAudit.safeAudit(ctx.audit, action, actor, metadata);
 }
 
 module.exports = {