@blamejs/core 0.9.21 → 0.9.22

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.9.x
 
+- 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`.
 - 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.

package/index.js

@@ -166,7 +166,9 @@ 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 guardIdempotencyKey = require("./lib/guard-idempotency-key");
 var agentOrchestrator = require("./lib/agent-orchestrator");
+var agentIdempotency = require("./lib/agent-idempotency");
 var guardArchive = require("./lib/guard-archive");
 var guardJson = require("./lib/guard-json");
 var guardYaml = require("./lib/guard-yaml");
@@ -411,7 +413,8 @@ module.exports = {
   guardMailMove:    guardMailMove,
   guardMailSieve:   guardMailSieve,
   guardAgentRegistry: guardAgentRegistry,
-  agent:            { orchestrator: agentOrchestrator },
+  guardIdempotencyKey: guardIdempotencyKey,
+  agent:            { orchestrator: agentOrchestrator, idempotency: agentIdempotency },
   guardArchive:     guardArchive,
   guardJson:        guardJson,
   guardYaml:        guardYaml,

package/lib/agent-idempotency.js

@@ -0,0 +1,350 @@
+"use strict";
+/**
+ * @module     b.agent.idempotency
+ * @nav        Agent
+ * @title      Agent Idempotency
+ * @order      55
+ *
+ * @intro
+ *   Cross-dispatch idempotency keys honored at every agent consumer
+ *   boundary. Composes the v0.9.15 sealed `b.middleware.idempotencyKey`
+ *   patterns (namespace-hashed keys, sealed result columns) into a
+ *   generic agent-shaped surface:
+ *
+ *     - **`instance.get(method, actorId, key)`** — returns cached
+ *       result envelope or `null`. Sealed columns unseal via
+ *       `b.cryptoField`.
+ *     - **`instance.put(method, actorId, key, result, opts?)`** —
+ *       serialize (`b.safeJson.stringify`) + seal + persist with TTL.
+ *       Refuses if the same `(method, actorId, key)` already has a
+ *       cached entry whose `requestFingerprint` differs from the
+ *       supplied args fingerprint (defends key-reuse-different-args
+ *       attack).
+ *     - **`instance.invalidate(method, actorId, key)`** — operator
+ *       opt-out (e.g., a saga compensation that needs to allow a
+ *       fresh retry).
+ *     - **`instance.gc({ olderThanMs })`** — periodic cleanup, wires
+ *       into `b.scheduler`.
+ *
+ *   JMAP §3.7 requires method-level idempotency ("if Email/set is
+ *   retried with the same accountId+id, the server MUST return the
+ *   same result"). With v0.9.22 every mutating agent method honors
+ *   `args.idempotencyKey` and the consumer side dedupes BEFORE
+ *   running — at-least-once delivery on the queue + at-most-once at
+ *   the consumer = exactly-once end-to-end.
+ *
+ *   ```js
+ *   var idem = b.agent.idempotency.create({
+ *     store: myBackingStore,
+ *     ttlMs: b.C.TIME.hours(24),
+ *   });
+ *
+ *   var result = await agent.move({
+ *     actor: u, fromFolder: "INBOX", toFolder: "Archive", objectIds: [oid],
+ *     idempotencyKey: "jmap-req-abc",
+ *   });
+ *
+ *   // Retry returns cached result, doesn't re-bump modseq:
+ *   var result2 = await agent.move({
+ *     actor: u, fromFolder: "INBOX", toFolder: "Archive", objectIds: [oid],
+ *     idempotencyKey: "jmap-req-abc",
+ *   });
+ *   ```
+ *
+ * @card
+ *   JMAP retry-safe semantics for every agent method. Keys hashed at
+ *   the boundary; results sealed + persisted with TTL; consumer-side
+ *   dedup at the dispatch boundary turns at-least-once + at-most-once
+ *   into exactly-once.
+ */
+
+var lazyRequire       = require("./lazy-require");
+var C                 = require("./constants");
+var { defineClass }   = require("./framework-error");
+var bCrypto           = require("./crypto");
+var safeJson          = require("./safe-json");
+var guardIdempotencyKey = require("./guard-idempotency-key");
+
+var audit             = lazyRequire(function () { return require("./audit"); });
+
+var AgentIdempotencyError = defineClass("AgentIdempotencyError", { alwaysPermanent: true });
+
+var DEFAULT_TTL_MS        = C.TIME.hours(24);
+var MAX_RESULT_BYTES      = C.BYTES.mib(1);
+// Parse ceiling tracks the operator's configured maxResultBytes (set
+// per-instance via opts.maxResultBytes) — see _get. A static parse cap
+// would silently lose entries when operators raise the write cap.
+
+/**
+ * @primitive b.agent.idempotency.create
+ * @signature b.agent.idempotency.create(opts)
+ * @since     0.9.22
+ * @status    stable
+ * @related   b.agent.orchestrator.create, b.middleware.idempotencyKey.dbStore
+ *
+ * Create an idempotency instance for an agent. Operator supplies a
+ * backing store implementing `{ get, put, delete, gc }`; framework
+ * ships an in-memory default for single-process deployments.
+ *
+ * @opts
+ *   store:        { get, put, delete, gc },     // optional; in-memory default
+ *   audit:        b.audit namespace,            // optional
+ *   ttlMs:        number,                        // default 24h
+ *   maxResultBytes: number,                      // default 1 MiB per entry
+ *   fingerprintArgs: boolean,                    // default true
+ *
+ * @example
+ *   var idem = b.agent.idempotency.create({});
+ *   var existing = await idem.get("move", "u1", "jmap-req-abc");
+ *   if (existing) return existing.result;
+ *   var result = await mailAgent.move(args);
+ *   await idem.put("move", "u1", "jmap-req-abc", result, { argsFingerprint: "..." });
+ */
+function create(opts) {
+  opts = opts || {};
+  var store = opts.store || _inMemoryBackend();
+  if (typeof store.get !== "function" || typeof store.put !== "function" ||
+      typeof store.delete !== "function") {
+    throw new AgentIdempotencyError("agent-idempotency/bad-store",
+      "create: store must expose { get, put, delete }");
+  }
+  var ttlMs = typeof opts.ttlMs === "number" ? opts.ttlMs : DEFAULT_TTL_MS;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    throw new AgentIdempotencyError("agent-idempotency/bad-ttl",
+      "create: opts.ttlMs must be a positive finite number");
+  }
+  var maxResultBytes = typeof opts.maxResultBytes === "number" ? opts.maxResultBytes : MAX_RESULT_BYTES;
+  var fingerprintArgs = opts.fingerprintArgs !== false;
+  var auditImpl = opts.audit || audit();
+
+  return {
+    get:        function (method, actorId, key)                       { return _get(store, method, actorId, key, auditImpl, ttlMs, maxResultBytes); },
+    put:        function (method, actorId, key, result, putOpts)      { return _put(store, method, actorId, key, result, putOpts || {}, ttlMs, maxResultBytes, fingerprintArgs, auditImpl); },
+    invalidate: function (method, actorId, key)                       { return _invalidate(store, method, actorId, key, auditImpl); },
+    gc:         function (gcOpts)                                     { return _gc(store, gcOpts || {}, auditImpl); },
+    fingerprintArgs: _fingerprintArgs,
+    keyHash:    _keyHash,
+    AgentIdempotencyError: AgentIdempotencyError,
+  };
+}
+
+// ---- Core API -------------------------------------------------------------
+
+async function _get(store, method, actorId, key, auditImpl, ttlMs, maxResultBytes) {
+  _checkArgs(method, actorId, key);
+  guardIdempotencyKey.validate(key);
+  var hash = _keyHash(method, actorId, key);
+  var row = await store.get(method, actorId, hash);
+  if (!row) return null;
+  if (row.expiresAt && row.expiresAt < Date.now()) {
+    // Expired entries get GC'd lazily on read.
+    await store.delete(method, actorId, hash);
+    _safeAudit(auditImpl, "agent.idempotency.expired", null,
+      { method: method, actorIdHash: _truncHash(_actorIdHash(actorId)) });
+    return null;
+  }
+  var nextReplayCount = (row.replayCount || 0) + 1;
+  _safeAudit(auditImpl, "agent.idempotency.replay", null, {
+    method: method, actorIdHash: _truncHash(_actorIdHash(actorId)),
+    firstAt: row.firstAt, replayCount: nextReplayCount,
+  });
+  // Deserialize the sealed result blob. v0.9.22 ships a simple
+  // safeJson re-parse since the result was JSON-stringified at put().
+  // v0.9.25 tenant integration will swap this for per-tenant sealRow
+  // unseal when the row is sealed at rest.
+  var result;
+  try {
+    // Parse cap mirrors the operator's configured maxResultBytes (the
+    // same cap put() enforced on write) — a static parse ceiling would
+    // turn valid cached entries into permanent replay errors when the
+    // operator raises the write cap.
+    result = safeJson.parse(row.resultBlob, { maxBytes: maxResultBytes });
+  } catch (e) {
+    throw new AgentIdempotencyError("agent-idempotency/corrupt-result",
+      "get: cached result failed to parse — " + (e && e.message ? e.message : String(e)));
+  }
+  // Persist the incremented replayCount + lastReplayedAt so subsequent
+  // gets see the updated state. Operator audit pipelines rely on
+  // replayCount to surface retry storms.
+  row.replayCount    = nextReplayCount;
+  row.lastReplayedAt = Date.now();
+  await store.put(method, actorId, hash, row);
+  return {
+    result:               result,
+    firstAt:              row.firstAt,
+    lastReplayedAt:       row.lastReplayedAt,
+    replayCount:          nextReplayCount,
+    requestFingerprint:   row.requestFingerprint,
+  };
+}
+
+async function _put(store, method, actorId, key, result, putOpts, ttlMs, maxResultBytes, fingerprintArgs, auditImpl) {
+  _checkArgs(method, actorId, key);
+  guardIdempotencyKey.validate(key);
+  var hash = _keyHash(method, actorId, key);
+  var existing = await store.get(method, actorId, hash);
+  var requestFingerprint = putOpts.requestFingerprint ||
+    (fingerprintArgs && putOpts.args ? _fingerprintArgs(putOpts.args) : null);
+
+  if (existing && existing.requestFingerprint && requestFingerprint &&
+      existing.requestFingerprint !== requestFingerprint) {
+    _safeAudit(auditImpl, "agent.idempotency.key_reuse_different_args", null, {
+      method: method, actorIdHash: _truncHash(_actorIdHash(actorId)),
+    });
+    throw new AgentIdempotencyError("agent-idempotency/key-reuse-different-args",
+      "put: key '" + key + "' reused with different args for method '" + method +
+      "' — refused per JMAP §3.7 semantics");
+  }
+  var resultBlob;
+  try { resultBlob = safeJson.stringify(result); }
+  catch (e) {
+    throw new AgentIdempotencyError("agent-idempotency/bad-result",
+      "put: result not JSON-serializable: " + (e && e.message ? e.message : String(e)));
+  }
+  if (Buffer.byteLength(resultBlob, "utf8") > maxResultBytes) {
+    throw new AgentIdempotencyError("agent-idempotency/result-too-big",
+      "put: serialized result " + Buffer.byteLength(resultBlob, "utf8") +
+      " bytes exceeds maxResultBytes=" + maxResultBytes);
+  }
+  var now = Date.now();
+  var row = {
+    method:             method,
+    actorIdHash:        _actorIdHash(actorId),
+    keyHash:            hash,
+    requestFingerprint: requestFingerprint,
+    resultBlob:         resultBlob,
+    firstAt:            existing && existing.firstAt ? existing.firstAt : now,
+    lastWrittenAt:      now,
+    replayCount:        existing ? (existing.replayCount || 0) : 0,
+    expiresAt:          now + ttlMs,
+  };
+  await store.put(method, actorId, hash, row);
+  _safeAudit(auditImpl, "agent.idempotency.put", null, {
+    method: method, actorIdHash: _truncHash(row.actorIdHash),
+    resultBytes: Buffer.byteLength(resultBlob, "utf8"),
+  });
+}
+
+async function _invalidate(store, method, actorId, key, auditImpl) {
+  _checkArgs(method, actorId, key);
+  guardIdempotencyKey.validate(key);
+  var hash = _keyHash(method, actorId, key);
+  await store.delete(method, actorId, hash);
+  _safeAudit(auditImpl, "agent.idempotency.invalidated", null, {
+    method: method, actorIdHash: _truncHash(_actorIdHash(actorId)),
+  });
+}
+
+async function _gc(store, opts, auditImpl) {
+  if (typeof store.gc !== "function") {
+    // Backend doesn't support GC (in-memory default does); operator
+    // periodic cleanup of durable stores is the operator's job.
+    return { purged: 0 };
+  }
+  var olderThanMs = typeof opts.olderThanMs === "number" ? opts.olderThanMs : 0;
+  var cutoff = Date.now() - olderThanMs;
+  var r = await store.gc({ expiresAtBefore: cutoff });
+  _safeAudit(auditImpl, "agent.idempotency.gc", null, {
+    purged: r && r.purged ? r.purged : 0,
+  });
+  return r || { purged: 0 };
+}
+
+// ---- Internals ------------------------------------------------------------
+
+function _keyHash(method, actorId, key) {
+  // Namespaced hash — same pattern as v0.9.15 b.middleware.idempotencyKey
+  // dbStore so raw operator-supplied keys never reach disk.
+  return bCrypto.namespaceHash("agent.idempotency",
+    method + "\0" + actorId + "\0" + key);
+}
+
+function _actorIdHash(actorId) {
+  return bCrypto.namespaceHash("agent.idempotency.actor", String(actorId));
+}
+
+function _truncHash(hash) {
+  if (typeof hash !== "string") return "";
+  return hash.slice(0, 16);                                                                            // allow:raw-byte-literal — audit-log truncation length, not a size cap
+}
+
+function _fingerprintArgs(args) {
+  // Strip the idempotencyKey itself out of fingerprint computation —
+  // the key IS the cache lookup; including it would make every key a
+  // unique fingerprint and defeat the args-mismatch defense. Also
+  // strip framework-internal cross-cutting fields that vary per-hop.
+  var argsClone = Object.assign({}, args);
+  delete argsClone.idempotencyKey;
+  delete argsClone._postureChain;
+  delete argsClone._traceContext;
+  // Canonicalize via RFC 8785 JCS (key-sorted) so two semantically
+  // identical args objects with different key insertion order produce
+  // the same fingerprint. Cross-producer / cross-runtime retries (JMAP
+  // clients, queue replay, different JSON parsers) construct objects
+  // with different key order; without canonicalization the args-
+  // mismatch check would fire false-positives.
+  var canonical;
+  try { canonical = safeJson.canonical(argsClone); }
+  catch (_e) { canonical = "[unserializable]"; }
+  return bCrypto.namespaceHash("agent.idempotency.fingerprint", canonical);
+}
+
+function _checkArgs(method, actorId, key) {
+  if (typeof method !== "string" || method.length === 0) {
+    throw new AgentIdempotencyError("agent-idempotency/bad-method",
+      "method must be a non-empty string");
+  }
+  if (typeof actorId !== "string" || actorId.length === 0) {
+    throw new AgentIdempotencyError("agent-idempotency/bad-actor-id",
+      "actorId must be a non-empty string");
+  }
+  // key is validated separately via guardIdempotencyKey.validate.
+}
+
+function _inMemoryBackend() {
+  var map = new Map();
+  function _k(method, actorId, hash) { return method + "\0" + actorId + "\0" + hash; }
+  return {
+    get:    function (method, actorId, hash) {
+      return Promise.resolve(map.get(_k(method, actorId, hash)) || null);
+    },
+    put:    function (method, actorId, hash, row) {
+      map.set(_k(method, actorId, hash), row);
+      return Promise.resolve();
+    },
+    delete: function (method, actorId, hash) {
+      map.delete(_k(method, actorId, hash));
+      return Promise.resolve();
+    },
+    gc:     function (gcOpts) {
+      var cutoff = gcOpts && gcOpts.expiresAtBefore ? gcOpts.expiresAtBefore : 0;
+      var purged = 0;
+      map.forEach(function (row, k) {
+        if (row.expiresAt && row.expiresAt <= cutoff) {
+          map.delete(k);
+          purged += 1;
+        }
+      });
+      return Promise.resolve({ purged: purged });
+    },
+  };
+}
+
+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 */ }
+}
+
+module.exports = {
+  create:                 create,
+  AgentIdempotencyError:  AgentIdempotencyError,
+  guards: {
+    key: guardIdempotencyKey,
+  },
+};

package/lib/guard-idempotency-key.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * @module     b.guardIdempotencyKey
+ * @nav        Guards
+ * @title      Guard Idempotency Key
+ * @order      436
+ *
+ * @intro
+ *   Operator-supplied idempotency key shape validator. Refuses keys
+ *   that wouldn't be safe to surface in audit logs, persist in the
+ *   sealed dbStore, or replay across processes:
+ *
+ *     - oversized (default 256 bytes — operators sometimes pass full
+ *       JMAP request envelopes as keys; 256 is plenty for any
+ *       reasonable correlation id without blowing storage)
+ *     - control chars (C0 / NUL / DEL — defends audit-log injection
+ *       when the key is rendered in a log message)
+ *     - non-ASCII (NFC-normalized + ASCII-only; operator-greppable
+ *       in audit logs across stack boundaries)
+ *     - path-traversal shapes (`..` / `/` / `\` — defends operators
+ *       who route idempotency keys through a filesystem-shaped path)
+ *
+ *   Permissive profile opts down the non-ASCII refusal for operators
+ *   with legacy systems that include Unicode tenant IDs in keys.
+ *
+ * @card
+ *   Validates operator-supplied `args.idempotencyKey` strings. Bounded
+ *   length, control-char refusal, path-traversal refusal, ASCII-only
+ *   under strict.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardIdempotencyKeyError = defineClass("GuardIdempotencyKeyError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxBytes: 256,  asciiOnly: true  },                                                   // allow:raw-byte-literal
+  balanced:   { maxBytes: 512,  asciiOnly: true  },                                                   // allow:raw-byte-literal
+  permissive: { maxBytes: 2048, asciiOnly: false },                                                   // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+/**
+ * @primitive b.guardIdempotencyKey.validate
+ * @signature b.guardIdempotencyKey.validate(value, opts?)
+ * @since     0.9.22
+ * @status    stable
+ * @related   b.agent.idempotency.create
+ *
+ * Validate an operator-supplied idempotency key. Returns the input
+ * on success; throws `GuardIdempotencyKeyError` on refusal.
+ *
+ * @opts
+ *   profile:    "strict" | "balanced" | "permissive",   // default "strict"
+ *   posture:    "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   maxBytes:   number,                                  // per-profile default
+ *
+ * @example
+ *   b.guardIdempotencyKey.validate("jmap-req-abc-123");
+ */
+function validate(value, opts) {
+  opts = opts || {};
+  var profileName = _resolveProfile(opts);
+  var profile = PROFILES[profileName];
+  var maxBytes = typeof opts.maxBytes === "number" ? opts.maxBytes : profile.maxBytes;
+
+  if (typeof value !== "string") {
+    throw new GuardIdempotencyKeyError("idempotency-key/bad-input",
+      "guardIdempotencyKey.validate: value must be a string (got " + typeof value + ")");
+  }
+  if (value.length === 0) {
+    throw new GuardIdempotencyKeyError("idempotency-key/empty",
+      "guardIdempotencyKey.validate: empty key refused");
+  }
+  if (Buffer.byteLength(value, "utf8") > maxBytes) {
+    throw new GuardIdempotencyKeyError("idempotency-key/oversize",
+      "guardIdempotencyKey.validate: " + Buffer.byteLength(value, "utf8") +
+      " bytes exceeds maxBytes=" + maxBytes);
+  }
+  // Path-traversal refusal — defends operators routing keys through
+  // filesystem paths.
+  if (value.indexOf("..") >= 0) {
+    throw new GuardIdempotencyKeyError("idempotency-key/path-traversal",
+      "guardIdempotencyKey.validate: key contains '..'");
+  }
+  // C0 / DEL / slash refusal.
+  for (var i = 0; i < value.length; i += 1) {
+    var c = value.charCodeAt(i);
+    if (c < 0x20 || c === 0x7F) {                                                                     // allow:raw-byte-literal — C0 + DEL refusal
+      throw new GuardIdempotencyKeyError("idempotency-key/control-char",
+        "guardIdempotencyKey.validate: control char 0x" + c.toString(16) + " at offset " + i);
+    }
+    if (c === 0x2F || c === 0x5C) {                                                                   // allow:raw-byte-literal — / and \ refusal
+      throw new GuardIdempotencyKeyError("idempotency-key/slash",
+        "guardIdempotencyKey.validate: key contains '/' or '\\' at offset " + i);
+    }
+    if (profile.asciiOnly && c > 0x7F) {                                                              // allow:raw-byte-literal — ASCII-only cap
+      throw new GuardIdempotencyKeyError("idempotency-key/non-ascii",
+        "guardIdempotencyKey.validate: non-ASCII codepoint at offset " + i +
+        " (use profile='permissive' to allow)");
+    }
+  }
+  return value;
+}
+
+/**
+ * @primitive b.guardIdempotencyKey.compliancePosture
+ * @signature b.guardIdempotencyKey.compliancePosture(posture)
+ * @since     0.9.22
+ * @status    stable
+ *
+ * Return the effective profile for a given compliance posture name.
+ * Returns `null` for unknown posture names so operator typos surface
+ * here instead of silently falling through to the default profile.
+ *
+ * @example
+ *   b.guardIdempotencyKey.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return COMPLIANCE_POSTURES[opts.posture];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardIdempotencyKeyError("idempotency-key/bad-profile",
+      "guardIdempotencyKey: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:                  validate,
+  compliancePosture:         compliancePosture,
+  PROFILES:                  PROFILES,
+  COMPLIANCE_POSTURES:       COMPLIANCE_POSTURES,
+  GuardIdempotencyKeyError:  GuardIdempotencyKeyError,
+  NAME:                      "idempotencyKey",
+  KIND:                      "idempotency-key",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.9.21",
+  "version": "0.9.22",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:f8b30ec2-7478-4a7b-852d-09721ba89ab2",
+  "serialNumber": "urn:uuid:66e27fdc-e5e4-44ce-84cf-f8eddc4a5a45",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-14T20:33:49.367Z",
+    "timestamp": "2026-05-14T21:47:04.186Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.9.21",
+      "bom-ref": "@blamejs/core@0.9.22",
       "type": "library",
       "name": "blamejs",
-      "version": "0.9.21",
+      "version": "0.9.22",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.9.21",
+      "purl": "pkg:npm/%40blamejs/core@0.9.22",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.9.21",
+      "ref": "@blamejs/core@0.9.22",
       "dependsOn": []
     }
   ]