@blamejs/core 0.9.19 → 0.9.21

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.9.x
 
+- v0.9.21 (2026-05-14) — **`b.agent.orchestrator` — framework-level supervisor for every agent blamejs ships.** First slice of the v0.9.21–v0.9.29 substrate playbook that builds before mail-stack resumes. (1) **`b.agent.orchestrator.create(opts)`** — facade with `register(name, agent, opts)` / `lookup(name)` / `unregister(name)` / `list({ kind, tenantId })` registry, `spawnConsumers({ agent, queue, shards, taskTopic, maxConcurrency })` for sharded-topic dispatch (FNV-1a consistent-hash via `b.agent.orchestrator.shardFor(key, shards)`; per-shard topic suffix `<base>.<shard>`), `elect({ resource })` composing `b.cluster` DB-row leader election (returns `{ isLeader, fencingToken, leaderId }` — single-process deployments get a trivial-leader; cluster deployments delegate), `drain({ timeoutMs })` stopping every spawned consumer + audit-emitting elapsed/count, and `health()` aggregating per-agent + per-consumer + per-election state into one shape ready for `b.middleware.healthcheck`. (2) **Pluggable backend** — `{ get, set, delete, list }` interface; in-memory default ships for single-process deployments, operator wires `b.config.loadDbBacked`-shaped or external for restart-survival. (3) **`b.guardAgentRegistry`** — registry-op shape validator. Refuses non-ASCII agent names (NFC + ASCII-only — operator-greppable in audit logs), path-traversal shapes (`..` / `/` / `\` / NUL / C0 / DEL), oversized (default 64 bytes), reserved `FRAMEWORK.*` / `ROOT.*` prefix, duplicate-on-register, register without `agentKind`. Ships `strict` / `balanced` / `permissive` profiles and `hipaa` / `pci-dss` / `gdpr` / `soc2` postures (all pin `strict`). (4) **Drain phase auto-wires into `b.appShutdown`** when operator supplies an `appShutdown` instance; `SIGTERM` delivers a clean drain of all spawned consumers + stream-registry signal before the process exits. (5) **Stream-registry hook** (`registerStream` / `unregisterStream` / `isDraining`) — substrate for v0.9.23 `b.agent.stream` so async-iterable method variants can check the drain flag and emit drain-markers. Substrate is NOT a process supervisor — process spawn / restart-on-crash / pod scheduling delegate to pm2 / systemd / k8s / Nomad; framework doesn't compete. Fuzz harness ships in `fuzz/guard-agent-registry.fuzz.js`. Per the substrate playbook in `memory/specs/blamejs-agent-orchestrator-spec.md`; v0.9.22 idempotency wires on top next.
+- v0.9.20 (2026-05-14) — **`b.mail.agent` — the standardization contract for every mail protocol blamejs ships.** Every above-the-wire mail surface (JMAP at v0.9.27, IMAP at v0.9.28, POP3 at v0.9.29, ManageSieve at v0.9.30, the MX listener at v0.9.24, submission at v0.9.25) translates protocol calls into `agent.X(args)`; RBAC, posture enforcement, audit emission, dispatch, and worker isolation are owned at the agent. (1) **`b.mail.agent.create({ store, audit, permissions, posture, identity, dispatch })`** — facade with 23 methods. Read surface (`search` / `fetch` / `thread` / `folders` / `quota`) is backed by v0.9.19 `b.mailStore` and runs immediately. Move surface (`move` / `flag` / `delete`) is backed by the new `mailStore.moveMessages` substrate; soft-delete moves to Trash + tags `\Deleted` (hard expunge wires at v0.9.28 with retention-floor enforcement). Write surface (`compose` / `send` / `reply` / `forward`), Sieve (`sieve.list/put/activate`), identity (`identity.set` / `vacation.set`), MDN (`mdn.send/parse/allowList`), regulated export, and migration `import` throw `mail-agent/not-implemented` with a `wiredAt` tag naming the slice that lights them up (defer-with-condition per the v1-defensible-scope rule). (2) **Dispatch contract** — `dispatch.mode` is `"local"` / `"queue"` / `"auto"`. `local` runs every method in-process. `queue` publishes envelopes to `mail.agent.tasks` via `b.queue.enqueue`; an `agent.consumer({ agent, queue })` running in a dedicated process or replicas across hosts pulls and executes. Posture metadata travels with each envelope; the consumer re-validates against its own posture before unseal so no posture downgrade survives the queue boundary. `auto` routes fast-path ops (`fetch` / `folders` / `flag` / `quota`) locally and heavy ops (`search` / `export`) to queue/workerPool when configured. (3) **Worker isolation** — `dispatch.workerPool` (composes `b.workerPool`) is validated at create-time; the agent reserves `vaultKeyDelivery: "in-worker"` (default) vs `"main-only"` (posture-conditional — HIPAA/PCI/GDPR default to main-only when the worker-script path wires at v0.9.26 Sieve). (4) **`b.mail.agent.consumer`** — the queue-side facade for multi-host load-spreading; carries its own `store` and re-validates posture at the boundary. (5) **Five new guards** through `b.gateContract` — **`b.guardMailQuery`** (search/fetch filter shape: bounded depth/keys/array-length, function/regex/Buffer/cycle refusal, `__proto__` key refusal, projection-column allowlist via `FILTERABLE_COLUMNS`, posture-required actor fields HIPAA→`purposeOfUse` / PCI→`pciScope` / GDPR→`lawfulBasis`); **`b.guardMailCompose`** (draft envelope: identity-vs-From alignment, recipient deduplication, attachment-byte cap default 25 MiB, body shape — exactly one of text/html unless `allowMultipartAlternative`, C0 control-char refusal in headers); **`b.guardMailReply`** (References-chain cap default 100 defends infinite-loop forwards, In-Reply-To continuity per RFC 5322 §3.6.4 — last References must match In-Reply-To, quoted-original byte cap, forwarded-attachment cardinality cap); **`b.guardMailMove`** (system-folder allowlist for INBOX/Sent/Drafts/Trash/Junk/Archive, admin-scope or `allowedFolders` gate for arbitrary destinations, path-traversal refusal, slash refusal — IMAP `.` hierarchy separator only); **`b.guardMailSieve`** (pre-parser shape-only: script-byte cap default 64 KiB, line-count cap defends one-byte-line bombs, name shape — path-traversal / slash / backslash refusal, actor-ownership check — non-admin actors restricted to their `ownedNames`; full Sieve parse at v0.9.26 via `b.safeSieve`). Each guard ships `strict` / `balanced` / `permissive` profiles and `hipaa` / `pci-dss` / `gdpr` / `soc2` postures (all pin `strict`). (6) **`b.mailStore.moveMessages(fromFolder, toFolder, objectIds)`** — per IMAP4rev2 §6.6.2, both folders bump modseq on move; agent.move composes this. (7) Fuzz harnesses ship for every new guard and the v0.9.19 substrates (`safe-mime` / `guard-message-id`) are now wired into the ClusterFuzzLite matrix.
 - v0.9.19 (2026-05-14) — **First slice of the blamepost mail-stack sequence — `b.mailStore` + `b.safeMime` + `b.guardMessageId` substrates.** Byte-level mail-store foundation that every above-the-wire mail primitive composes (agent at v0.9.20, MX listener at v0.9.23, submission listener at v0.9.24, JMAP/IMAP/POP3 at v0.9.26-29, ManageSieve at v0.9.30, DAV at v0.9.32). (1) **`b.safeMime`** — RFC 5322 + 2045/2046/2047/EAI MIME parser. Bounded: total parts cap (default 64), nesting-depth cap (default 16), boundary length cap (default 70 per RFC 2046 §5.1.1), header-bytes cap (default 64 KiB), header-line cap (default 998 per RFC 5322 §2.1.1), body-bytes cap (default 25 MiB), message cap (default 50 MiB), charset allowlist (UTF-8 / US-ASCII / common legacy 8-bit), transfer-encoding allowlist (7bit/8bit/binary/qp/base64). Surface: `parse(bytes, opts) → tree`, `walk(tree, visitor)`, `findFirst(tree, predicate)`, `extractText(tree, opts)` (RFC 2046 §5.1.4 last-wins for `multipart/alternative`), `extractAttachments(tree, opts)`. Includes RFC 2047 Q + B encoded-word decoding for `Subject:` / `From:` etc. + RFC 2231 charset'lang'value filename decoding. Throws `safe-mime/<code>` on every cap exceeded / malformed boundary / unknown charset / unknown CTE / control chars in headers / NUL bytes. **Defends CVE-2024-39929** (Exim MIME multipart parser) and **CVE-2025-30258** (gnumail truncated-MIME-tree class). Fuzz harness ships in `fuzz/safe-mime.fuzz.js`. (2) **`b.guardMessageId`** — RFC 5322 §3.6.4 Message-Id validator. Gates Message-Id / In-Reply-To / References at the mail-store append boundary, the MX inbound boundary (v0.9.23), and the submission outbound path (v0.9.24). Refuses oversized (>998 bytes), bare CR/LF/NUL/C0-control/DEL (header-injection defense — defends `From:` / `Bcc:` smuggling via folded Message-Id continuation), unbracketed under strict profile, empty value, missing `@`, nested angle brackets, bidi codepoints (CVE-2021-42574 RTLO class in mail-header context). Profile family: strict (default) / balanced / permissive. Posture family: hipaa / pci-dss / gdpr / soc2 → all pin profile to strict. Surface: `validate(value, opts)`, `validateList(value, opts)` (References-chain cap = 100), `compliancePosture(posture)`. Fuzz harness ships in `fuzz/guard-message-id.fuzz.js`. (3) **`b.mailStore`** — byte-level mail-store substrate with pluggable backend (sqlite default; operator's `b.externalDb` Postgres or any `{ prepare(sql) → { run, get, all } }`-shaped object). Surface: `create(opts)` returning `{ appendMessage, fetchByObjectId, queryByModseq, setFlags, createFolder, listFolders, threadFor, quota, setLegalHold }`. **Sealed by default** via `b.cryptoField.sealRow` — `subject` / `from_addr` / `to_addrs` / `body_text` / `body_html` route through vault-managed AEAD envelope on insert + unseal on fetch. Plaintext (forensic-queryable without unsealing): `objectid` / `modseq` / `internal_date` / `received_at` / `size_bytes` / `flags` / `legal_hold` / `from_hash` / `message_id_hash`. Per-folder monotonic `modseq` counter (RFC 7162 CONDSTORE substrate). Per-message `objectid` (RFC 8474 JMAP cross-protocol identity). Threading at append time via In-Reply-To + References chain walk (cryptoField.lookupHash for hash-aware threading on sealed columns). Quota substrate (per-folder `used_bytes` + `used_count` maintained atomically). Legal-hold flag composes existing `b.legalHold`. Schema bootstraps at construction with six IMAP4rev2 default folders (INBOX / Sent / Drafts / Trash / Junk / Archive) and JMAP role mapping. Append composes `b.safeMime.parse` (bounded inbound) + `b.guardMessageId.validate` (header-injection gate). **Per the operator-confirmed blamepost roadmap** (`memory/specs/blamepost-roadmap.md`); next slice v0.9.20 wires `b.mail.agent` on top of this substrate.
 - v0.9.18 (2026-05-14) — **18 CodeQL alerts closed across 4 rule classes + SECURITY.md hardening checklist additions for v0.9.13+ primitives + MIGRATING.md out-of-band breaking-changes section.** Post-v0.9.17 audit identified 18 pre-existing CodeQL security findings on `main` — accumulated over many releases, surfaced explicitly when v0.9.15's rename sweep changed line content. v0.9.18 closes them all. (1) **`js/file-system-race` (6 sites)** — TOCTOU between `fs.existsSync()` / `fs.statSync()` and a subsequent file op. Fixed via the framework's canonical TOCTOU-safe-read scaffold (open fd first → `fstatSync` → `readSync` loop → `closeSync` in `finally`) at `lib/atomic-file.js` (`_readSyncCore`), `lib/restore-rollback.js` (marker write switched to exclusive-create `wx` + EEXIST-tolerant), `lib/network-tls.js` (`_readPathFile` extraction with per-file ENOENT tolerance), `lib/backup/bundle.js` (open-fd-first plus required-vs-skip branch routing), `lib/static.js` (request-serve hot path narrowed to single fd). `lib/vault/seal-pem-file.js` retained as-is with a CodeQL suppression — the site has an in-line `lstat.ino === fstat.ino` inode-equality defense (line 290) that refuses with `seal-pem-file/toctou-detected` if an attacker swaps the file between `lstat` and `open`. (2) **`js/insecure-temporary-file` (6 sites)** — predictable temp paths. `lib/vault/rotate.js` now uses `mkdtempSync` for a per-rotation random scratch dir + plain filenames inside (replaces the predictable `_blamejs_rotate.tmp.db` / `_blamejs_verify.tmp.db` paths in `stagingDir`). `lib/mtls-ca.js` switched to exclusive-create `openSync(..., "wx", 0o600)` + `writeSync` + `fsyncSync` so an attacker pre-creating the path is refused at `EEXIST`. `lib/atomic-file.js` (`fsyncDir`), `lib/vault/rotate.js` (`_fsyncFileByPath`), `lib/http-client.js` (atomic tmp path) retained as-is with suppressions — `dirPath` / `p` are operator-supplied framework data paths (not `os.tmpdir`-reachable), and `tmpPath` carries 16 hex chars of crypto-random suffix (line 1802 `dest + ".tmp-" + bCrypto.generateToken(8)`). (3) **`js/path-injection` (2 sites in `lib/static.js`)** — `nodeFs.createReadStream(absPath)` in `_readMeta` (line 161) and the request-serve hot path (line 1115). Suppression comments added referencing the upstream `_resolveSafe` lexical-resolve + `startsWith(rootResolved + nodePath.sep)` + realpath escape check at lines 181-207 — `absPath` is sandbox-validated against `root` before reaching these lines. (4) **`js/remote-property-injection` (4 sites)** — `lib/websocket.js` (`ext.params: {}` → `Object.create(null)`), `lib/middleware/csrf-protect.js` (`var out = {}` → `Object.create(null)` for cookie-parse output). `lib/middleware/body-parser.js` (multipart `fields[currentField] = ...`) retained as-is with suppression — `currentField` is gated upstream at line 867 by `POISONED_KEYS = new Set(["__proto__", "constructor", "prototype"])` refusing the field BEFORE assignment with a 400 BodyParserError. **Plus: SECURITY.md hardening checklist** gains 5 lines covering `b.middleware.idempotencyKey.dbStore` (hash + seal defaults), `b.metrics.snapshot` (out-of-process metrics export), `b.selfUpdate.standaloneVerifier` (zero-dep install-pipeline verifier), `b.pqcAgent.reload` (TLS-posture refresh without restart), `b.crypto.hashFilesParallel` (parallel SBOM/integrity-sweep hashing). **Plus: MIGRATING.md** now carries an "Out-of-band breaking changes" section (the v0.9.15 dbStore schema break is the first entry); `scripts/gen-migrating.js` extended with an `OUT_OF_BAND_BREAKS` table so future schema/on-disk format breaks land in MIGRATING.md without operators needing to grep CHANGELOG.
 - v0.9.17 (2026-05-14) — **Two new `codebase-patterns` detectors + 192-site cleanup sweep — `node:` prefix consistency + internal-binding leak prevention.** Post-v0.9.16 audit surfaced two enforceable invariants the existing detectors didn't cover. (1) **`node-builtin-prefix` detector** — every `require("<X>")` of a Node built-in (`fs`, `path`, `crypto`, `stream`, `tls`, `url`, `os`, `net`, `http`, `http2`, `https`, `zlib`, `dgram`, `events`, `child_process`, `readline`, …) must use the modern `require("node:<X>")` form. Three reasons: (a) userland packages on npm CAN be named after built-ins, so without the `node:` prefix a typo or `npm install` accident could shadow the built-in; (b) the prefix is a clearer at-a-glance signal that the dependency is on Node, not on a userland module; (c) bundler / SEA static-trace passes treat `node:` prefix as an unambiguous Node-builtin marker. Sweep: 153 `require()` rewrites across 79 framework files (2 parallel agents). The detector skips JSDoc `@example` block continuation lines (`*`-prefixed), so operator-facing examples that show `var fs = require("fs")` aren't rewritten — operators write their own bindings however they prefer. (2) **`internal-binding-in-prose` detector** — internal binding names (`nodeFs` / `nodePath` / `nodeCrypto` / `nodeStream` / `nodeTls` / `nodeUrl` / `bCrypto` / `retryHelper`) must NOT appear in operator-facing surface: JSDoc/comment continuation lines or string literals (error messages, audit metadata). Operators see the public API name (`path` / `fs` / `crypto` / `retry` / …), never the framework's internal alias. Sweep: 39 prose-leak fixes across 16 files — comments rewritten to use the operator-facing word (`nodePath` → `path`, `nodeFs.watch failed` → `fs.watch failed`, debug-log `"op": "nodeFs.unlinkSync"` → `"op": "fs.unlinkSync"`). (3) **2 follow-on require-binding canonicalizations** surfaced by the node-prefix sweep — `lib/ws-client.js` now destructures `var { EventEmitter } = require("node:events")` (was binding the entire `events` module to a class-shaped name) and `lib/process-spawn.js` renames inline `nodeChild` → `childProcess` (matches the module-level `childProcess` lazyRequire in `lib/dev.js`).

package/index.js

@@ -160,6 +160,13 @@ var guardHtml = require("./lib/guard-html");
 var guardSvg = require("./lib/guard-svg");
 var guardFilename = require("./lib/guard-filename");
 var guardMessageId = require("./lib/guard-message-id");
+var guardMailQuery = require("./lib/guard-mail-query");
+var guardMailCompose = require("./lib/guard-mail-compose");
+var guardMailReply = require("./lib/guard-mail-reply");
+var guardMailMove = require("./lib/guard-mail-move");
+var guardMailSieve = require("./lib/guard-mail-sieve");
+var guardAgentRegistry = require("./lib/guard-agent-registry");
+var agentOrchestrator = require("./lib/agent-orchestrator");
 var guardArchive = require("./lib/guard-archive");
 var guardJson = require("./lib/guard-json");
 var guardYaml = require("./lib/guard-yaml");
@@ -398,6 +405,13 @@ module.exports = {
   guardSvg:         guardSvg,
   guardFilename:    guardFilename,
   guardMessageId:   guardMessageId,
+  guardMailQuery:   guardMailQuery,
+  guardMailCompose: guardMailCompose,
+  guardMailReply:   guardMailReply,
+  guardMailMove:    guardMailMove,
+  guardMailSieve:   guardMailSieve,
+  guardAgentRegistry: guardAgentRegistry,
+  agent:            { orchestrator: agentOrchestrator },
   guardArchive:     guardArchive,
   guardJson:        guardJson,
   guardYaml:        guardYaml,

package/lib/agent-orchestrator.js

@@ -0,0 +1,469 @@
+"use strict";
+/**
+ * @module     b.agent.orchestrator
+ * @nav        Agent
+ * @title      Agent Orchestrator
+ * @order      50
+ * @featured   true
+ *
+ * @intro
+ *   Framework-level supervisor for every agent blamejs ships
+ *   (`b.mail.agent` today; future search-index / AI-classify / DSR /
+ *   c2pa-watermark agents). The orchestrator owns:
+ *
+ *     - **Registry** (`register` / `lookup` / `unregister` / `list`)
+ *       — pluggable backend; in-memory default, durable via operator-
+ *       supplied `b.config.loadDbBacked` for restart-survival. Sealed
+ *       rows so tenant names + endpoint metadata don't leak in DB
+ *       dumps.
+ *     - **Sharded topics** (`spawnConsumers`) — consistent-hash route
+ *       per-shard so each tenant's traffic owns one shard's ordering.
+ *     - **Leader-elected singletons** (`elect`) — composes `b.cluster`
+ *       DB-row election. Operator marks methods that must run on
+ *       exactly one node (MDN batch dispatch, virus-DB refresh,
+ *       journal compaction) as singletons.
+ *     - **Drain** (`drain`) — `consumer.stop()` on every spawned
+ *       consumer; wait for in-flight envelopes via `b.outbox`; audit.
+ *       Wires into `b.appShutdown` as a registered phase.
+ *     - **Health probe** (`health`) — aggregates per-agent + per-
+ *       consumer + per-election state into one shape for
+ *       `b.middleware.healthcheck`.
+ *
+ *   The orchestrator is the **in-process supervisor of agents**, NOT
+ *   the **OS-level supervisor of processes**. Spawn / restart-on-
+ *   crash / autoscaling / network routing all delegate to pm2 /
+ *   systemd / k8s / Nomad — the framework doesn't compete.
+ *
+ *   ```js
+ *   var orch = b.agent.orchestrator.create({
+ *     audit:        b.audit,
+ *     permissions:  myPerms,
+ *     backend:      operatorBackend,    // optional; in-memory default
+ *   });
+ *
+ *   await orch.register("tenant-acme.mail", mailAgent, { agentKind: "mail" });
+ *   var agent = await orch.lookup("tenant-acme.mail");
+ *   ```
+ *
+ * @card
+ *   The framework-level supervisor for every agent blamejs ships.
+ *   Registry, sharded topics, leader-elected singletons, drain, and
+ *   health probe — operators stop wiring these per-agent.
+ */
+
+var lazyRequire       = require("./lazy-require");
+var C                 = require("./constants");
+var { defineClass }   = require("./framework-error");
+var guardAgentRegistry = require("./guard-agent-registry");
+var bCrypto           = require("./crypto");
+
+var audit             = lazyRequire(function () { return require("./audit"); });
+var cluster           = lazyRequire(function () { return require("./cluster"); });
+
+var AgentOrchestratorError = defineClass("AgentOrchestratorError", { alwaysPermanent: true });
+
+var DEFAULT_DRAIN_TIMEOUT_MS = C.TIME.minutes(2);
+var STREAM_ID_RAND_BYTES     = 8;                                                                     // allow:raw-byte-literal — stream-id random-suffix byte length, not a size cap
+
+/**
+ * @primitive b.agent.orchestrator.create
+ * @signature b.agent.orchestrator.create(opts)
+ * @since     0.9.21
+ * @status    stable
+ * @related   b.mail.agent.create, b.cluster, b.appShutdown
+ *
+ * Create the orchestrator. Returns a singleton-style facade with
+ * registry / spawn / elect / drain / health methods. Operator runs
+ * one orchestrator per process; multi-process deployments share
+ * coordination via the backing store + `b.cluster`.
+ *
+ * @opts
+ *   audit:        b.audit namespace,            // optional; defaults to b.audit
+ *   permissions:  b.permissions instance,       // optional; orchestrator skips RBAC if absent
+ *   backend:      { get, set, delete, list },   // optional; in-memory default
+ *   cluster:      b.cluster module,             // optional; defaults to b.cluster
+ *   appShutdown:  b.appShutdown.create()        // optional; orchestrator registers drain phase if supplied
+ *
+ * @example
+ *   var orch = b.agent.orchestrator.create({});
+ *   await orch.register("tenant-acme.mail", mailAgent, { agentKind: "mail" });
+ *   var agent = await orch.lookup("tenant-acme.mail");
+ *   var folders = await agent.folders({ actor: { id: "u1" } });
+ */
+function create(opts) {
+  opts = opts || {};
+  var backend = opts.backend || _inMemoryBackend();
+  if (typeof backend.get !== "function" || typeof backend.set !== "function" ||
+      typeof backend.delete !== "function" || typeof backend.list !== "function") {
+    throw new AgentOrchestratorError("agent-orchestrator/bad-backend",
+      "b.agent.orchestrator.create: backend must expose { get, set, delete, list }");
+  }
+  var clusterImpl = opts.cluster || cluster();
+  var auditImpl   = opts.audit   || audit();
+  var permissions = opts.permissions || null;
+
+  var ctx = {
+    backend:     backend,
+    cluster:     clusterImpl,
+    audit:       auditImpl,
+    permissions: permissions,
+    spawnedConsumers: [],
+    streams:     new Map(),
+    elections:   new Map(),
+    // Live agent objects stay in-process — DB/JSON backends can't
+    // serialize function properties. The backend row carries only the
+    // operator-supplied metadata (kind / tenantId / posture / ...);
+    // every consuming process holds its own runtime map of name → agent.
+    liveAgents:  new Map(),
+  };
+
+  // Wire the drain phase into b.appShutdown if the operator supplied one.
+  if (opts.appShutdown && typeof opts.appShutdown.registerPhase === "function") {
+    opts.appShutdown.registerPhase("agent.orchestrator.drain", function () {
+      return _drain(ctx, { timeoutMs: DEFAULT_DRAIN_TIMEOUT_MS });
+    });
+  }
+
+  return {
+    register:        function (name, agent, regOpts)         { return _register(ctx, name, agent, regOpts || {}); },
+    unregister:      function (name, args)                   { return _unregister(ctx, name, args || {}); },
+    lookup:          function (name, args)                   { return _lookup(ctx, name, args || {}); },
+    list:            function (args)                         { return _list(ctx, args || {}); },
+    spawnConsumers:  function (args)                         { return _spawnConsumers(ctx, args || {}); },
+    elect:           function (args)                         { return _elect(ctx, args || {}); },
+    drain:           function (args)                         { return _drain(ctx, args || {}); },
+    health:          function ()                             { return _health(ctx); },
+    registerStream:  function (info)                         { return _registerStream(ctx, info || {}); },
+    unregisterStream: function (streamId)                    { return _unregisterStream(ctx, streamId); },
+    isDraining:      function (streamId)                     { return ctx.draining === true; },
+    AgentOrchestratorError: AgentOrchestratorError,
+    _ctx:            ctx,                                    // test-only introspection
+  };
+}
+
+// ---- Registry -------------------------------------------------------------
+
+async function _register(ctx, name, agent, regOpts) {
+  guardAgentRegistry.validate({ kind: "register", name: name, agentKind: regOpts.agentKind }, {});
+  _checkPermission(ctx, regOpts.actor, "agent-registry:write");
+  if (!agent || typeof agent !== "object") {
+    throw new AgentOrchestratorError("agent-orchestrator/bad-agent",
+      "register: agent object required");
+  }
+  var existing = await ctx.backend.get(name);
+  if (existing) {
+    throw new AgentOrchestratorError("agent-orchestrator/duplicate",
+      "register: '" + name + "' already registered; unregister first");
+  }
+  // Backend row carries operator-supplied serializable metadata only —
+  // DB/JSON backends can't preserve function properties. The live agent
+  // ref is held in-process via ctx.liveAgents (see ctx init above).
+  var row = {
+    name:           name,
+    kind:           regOpts.agentKind,
+    tenantId:       regOpts.tenantId || null,
+    posture:        regOpts.posture  || null,
+    registeredAt:   Date.now(),
+    metadata:       regOpts.metadata || {},
+  };
+  await ctx.backend.set(name, row);
+  ctx.liveAgents.set(name, agent);
+  _safeAudit(ctx, "agent.orchestrator.registered", regOpts.actor, {
+    name: name, agentKind: regOpts.agentKind, tenantId: row.tenantId,
+  });
+  return { name: name, registeredAt: row.registeredAt };
+}
+
+async function _unregister(ctx, name, args) {
+  guardAgentRegistry.validate({ kind: "unregister", name: name }, {});
+  _checkPermission(ctx, args.actor, "agent-registry:write");
+  var row = await ctx.backend.get(name);
+  if (!row) {
+    throw new AgentOrchestratorError("agent-orchestrator/not-found",
+      "unregister: '" + name + "' not registered");
+  }
+  await ctx.backend.delete(name);
+  ctx.liveAgents.delete(name);
+  _safeAudit(ctx, "agent.orchestrator.unregistered", args.actor, {
+    name: name, agentKind: row.kind,
+  });
+  return { name: name };
+}
+
+async function _lookup(ctx, name, args) {
+  guardAgentRegistry.validate({ kind: "lookup", name: name }, {});
+  _checkPermission(ctx, args.actor, "agent-registry:read");
+  // Live agent ref lives in-process; the backend row exists only as
+  // a metadata declaration. In multi-process deployments each process
+  // hydrates its own liveAgents map by calling register() locally.
+  var agent = ctx.liveAgents.get(name);
+  if (agent) return agent;
+  var row = await ctx.backend.get(name);
+  if (!row) {
+    _safeAudit(ctx, "agent.orchestrator.lookup_miss", args.actor, { name: name });
+    return null;
+  }
+  // Backend row exists but no live ref in this process — operator
+  // didn't hydrate locally. Surface explicitly so the caller knows
+  // to register the agent or route to the process that holds it.
+  throw new AgentOrchestratorError("agent-orchestrator/not-hydrated",
+    "lookup: '" + name + "' exists in registry but no live agent ref " +
+    "in this process — register the agent locally first");
+}
+
+async function _list(ctx, args) {
+  guardAgentRegistry.validate({ kind: "list" }, {});
+  _checkPermission(ctx, args.actor, "agent-registry:read");
+  var rows = await ctx.backend.list();
+  return rows.filter(function (r) {
+    if (args.kind && r.kind !== args.kind) return false;
+    if (args.tenantId && r.tenantId !== args.tenantId) return false;
+    return true;
+  }).map(function (r) {
+    return {
+      name: r.name, kind: r.kind, tenantId: r.tenantId,
+      posture: r.posture, registeredAt: r.registeredAt,
+    };
+  });
+}
+
+// ---- Sharded topic dispatch -----------------------------------------------
+
+function _spawnConsumers(ctx, args) {
+  if (!args.agent || typeof args.agent !== "object") {
+    throw new AgentOrchestratorError("agent-orchestrator/bad-agent",
+      "spawnConsumers: agent required");
+  }
+  if (!args.queue || typeof args.queue.consume !== "function") {
+    throw new AgentOrchestratorError("agent-orchestrator/bad-queue",
+      "spawnConsumers: queue with .consume() required");
+  }
+  var shards = typeof args.shards === "number" ? args.shards : 1;
+  if (!Number.isInteger(shards) || shards < 1 || shards > 256) {                                      // allow:raw-byte-literal — shard cap
+    throw new AgentOrchestratorError("agent-orchestrator/bad-shard-count",
+      "spawnConsumers: shards must be an integer in 1..256");
+  }
+  var topicBase = args.taskTopic || "agent.tasks";
+  var consumers = [];
+  for (var i = 0; i < shards; i += 1) {
+    var topic = shards === 1 ? topicBase : topicBase + "." + i;
+    var c = _spawnSingleConsumer(ctx, args.agent, args.queue, topic, args.maxConcurrency || 4);
+    consumers.push(c);
+    ctx.spawnedConsumers.push(c);
+  }
+  _safeAudit(ctx, "agent.orchestrator.consumers_spawned", args.actor, {
+    shards: shards, topicBase: topicBase, perShardConcurrency: args.maxConcurrency || 4,
+  });
+  return consumers;
+}
+
+function _spawnSingleConsumer(ctx, agent, queue, topic, maxConcurrency) {
+  var stopped = false;
+  var subscription = null;
+  return {
+    topic: topic,
+    start: async function () {
+      if (subscription) {
+        throw new AgentOrchestratorError("agent-orchestrator/already-started",
+          "consumer for topic '" + topic + "': already started");
+      }
+      subscription = await queue.consume(topic, async function (envelope) {
+        if (stopped) return;
+        var method = envelope.method;
+        if (!method || typeof agent[method] !== "function") {
+          var dotted = method && method.indexOf(".") > 0 ? method.split(".") : null;
+          if (dotted && agent[dotted[0]] && typeof agent[dotted[0]][dotted[1]] === "function") {
+            return agent[dotted[0]][dotted[1]](envelope.args);
+          }
+          throw new AgentOrchestratorError("agent-orchestrator/unknown-method",
+            "consumer: unknown method '" + method + "'");
+        }
+        return agent[method](envelope.args);
+      }, { maxConcurrency: maxConcurrency });
+    },
+    stop: async function () {
+      stopped = true;
+      if (subscription && typeof subscription.unsubscribe === "function") {
+        await subscription.unsubscribe();
+      }
+      subscription = null;
+    },
+  };
+}
+
+/**
+ * @primitive b.agent.orchestrator.shardFor
+ * @signature b.agent.orchestrator.shardFor(shardKey, shards)
+ * @since     0.9.21
+ * @status    stable
+ * @related   b.agent.orchestrator.create
+ *
+ * Consistent-hash router for sharded topic dispatch. Operator passes
+ * a stable shard-key (e.g. tenantId or actor.id); orchestrator picks
+ * the topic suffix so each tenant's traffic owns one shard's ordering.
+ * Uses FNV-1a 32-bit — fast, good distribution for short keys, no
+ * cryptographic guarantees (shard routing is not security-bearing).
+ * Empty key returns 0; `shards <= 1` always returns 0.
+ *
+ * @example
+ *   var shard = b.agent.orchestrator.shardFor("tenant-acme", 8);
+ *   // → integer in [0, 8)
+ */
+function shardFor(shardKey, shards) {
+  if (typeof shardKey !== "string" || shardKey.length === 0) return 0;
+  if (shards <= 1) return 0;
+  // FNV-1a 32-bit — fast + good distribution for short keys.
+  var h = 2166136261;                                                                                 // allow:raw-byte-literal — FNV-1a offset basis
+  for (var i = 0; i < shardKey.length; i += 1) {
+    h ^= shardKey.charCodeAt(i);
+    h = (h * 16777619) >>> 0;                                                                         // allow:raw-byte-literal — FNV-1a prime
+  }
+  return h % shards;
+}
+
+// ---- Leader-elected singletons --------------------------------------------
+
+async function _elect(ctx, args) {
+  if (typeof args.resource !== "string" || args.resource.length === 0) {
+    throw new AgentOrchestratorError("agent-orchestrator/bad-elect-args",
+      "elect: resource required");
+  }
+  // Composes b.cluster's leader-election. When cluster mode is active,
+  // delegate; when not, the local node is the trivial leader for this
+  // process's lifetime (single-process deployment).
+  var isClusterMode = false;
+  try { isClusterMode = ctx.cluster.isClusterMode(); } catch (_e) { isClusterMode = false; }
+  if (!isClusterMode) {
+    // Single-process trivial leader.
+    var elec = { isLeader: true, fencingToken: 1, resource: args.resource };
+    ctx.elections.set(args.resource, elec);
+    _safeAudit(ctx, "agent.orchestrator.elected", args.actor, {
+      resource: args.resource, mode: "single-process",
+    });
+    return elec;
+  }
+  // Cluster mode: query current leader state via b.cluster.
+  var leaderRow = null;
+  try { leaderRow = await ctx.cluster.currentLeader(); } catch (_e) { leaderRow = null; }
+  var amLeader = false;
+  try { amLeader = ctx.cluster.isLeader(); } catch (_e) { amLeader = false; }
+  var token = null;
+  if (amLeader) {
+    try { token = ctx.cluster.fencingToken(); } catch (_e) { token = null; }
+  }
+  var elec2 = {
+    isLeader:     amLeader,
+    fencingToken: token,
+    resource:     args.resource,
+    leaderId:     leaderRow && leaderRow.nodeId ? leaderRow.nodeId : null,
+  };
+  ctx.elections.set(args.resource, elec2);
+  _safeAudit(ctx, "agent.orchestrator.elected", args.actor, {
+    resource: args.resource, mode: "cluster",
+    amLeader: amLeader, leaderId: elec2.leaderId,
+  });
+  return elec2;
+}
+
+// ---- Drain ----------------------------------------------------------------
+
+async function _drain(ctx, args) {
+  ctx.draining = true;
+  var timeoutMs = typeof args.timeoutMs === "number" ? args.timeoutMs : DEFAULT_DRAIN_TIMEOUT_MS;
+  var drained = 0;
+  var startedAt = Date.now();
+  // Stop every spawned consumer + collect timing.
+  for (var i = 0; i < ctx.spawnedConsumers.length; i += 1) {
+    var c = ctx.spawnedConsumers[i];
+    try { await c.stop(); drained += 1; } catch (_e) { /* best-effort */ }
+    if (Date.now() - startedAt > timeoutMs) break;
+  }
+  // Streams: signal each to wrap up (the streams check ctx.draining
+  // and emit a drain-marker themselves; orchestrator just sets the flag).
+  var streamCount = ctx.streams.size;
+  _safeAudit(ctx, "agent.orchestrator.drained", null, {
+    drainedConsumers: drained, totalConsumers: ctx.spawnedConsumers.length,
+    streamCount: streamCount, elapsedMs: Date.now() - startedAt,
+  });
+  return { drained: drained, elapsedMs: Date.now() - startedAt };
+}
+
+// ---- Streams (v0.9.23 substrate hook) -------------------------------------
+
+function _registerStream(ctx, info) {
+  // Stream IDs are cross-tenant-distinguishable; use crypto-grade
+  // generateToken to keep them uniformly random across operators.
+  var streamId = "stream-" + bCrypto.generateToken(STREAM_ID_RAND_BYTES);
+  ctx.streams.set(streamId, {
+    streamId: streamId, kind: info.kind || "unknown",
+    actor: info.actor || null, startedAt: Date.now(),
+  });
+  return streamId;
+}
+
+function _unregisterStream(ctx, streamId) {
+  ctx.streams.delete(streamId);
+}
+
+// ---- Health probe ---------------------------------------------------------
+
+async function _health(ctx) {
+  var rows = await ctx.backend.list();
+  var elections = [];
+  ctx.elections.forEach(function (v) { elections.push(v); });
+  var consumers = ctx.spawnedConsumers.map(function (c) { return { topic: c.topic }; });
+  return {
+    agents: rows.map(function (r) {
+      return { name: r.name, kind: r.kind, tenantId: r.tenantId, registeredAt: r.registeredAt };
+    }),
+    elections: elections,
+    consumers: consumers,
+    streams:   ctx.streams.size,
+    draining:  ctx.draining === true,
+    overall:   ctx.draining ? "draining" : "ok",
+  };
+}
+
+// ---- Internals ------------------------------------------------------------
+
+function _inMemoryBackend() {
+  var map = new Map();
+  return {
+    get:    function (k)      { return Promise.resolve(map.get(k) || null); },
+    set:    function (k, v)   { map.set(k, v); return Promise.resolve(); },
+    delete: function (k)      { map.delete(k); return Promise.resolve(); },
+    list:   function ()       {
+      var out = [];
+      map.forEach(function (v) { out.push(v); });
+      return Promise.resolve(out);
+    },
+  };
+}
+
+function _checkPermission(ctx, actor, scope) {
+  if (!ctx.permissions) return;
+  if (!actor || !ctx.permissions.check(actor, scope)) {
+    throw new AgentOrchestratorError("agent-orchestrator/permission-denied",
+      "actor lacks scope '" + 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 */ }
+}
+
+module.exports = {
+  create:                   create,
+  shardFor:                 shardFor,
+  AgentOrchestratorError:   AgentOrchestratorError,
+  guards: {
+    registry: guardAgentRegistry,
+  },
+};