@blamejs/core 0.9.24 → 0.9.38

package/lib/agent-snapshot.js

@@ -0,0 +1,346 @@
+"use strict";
+/**
+ * @module     b.agent.snapshot
+ * @nav        Agent
+ * @title      Agent Snapshot
+ * @order      90
+ *
+ * @intro
+ *   Drain → snapshot in-flight state; restart → restore + resume. The
+ *   last substrate slice: makes the orchestrator + idempotency +
+ *   stream + event-bus + tenant + saga + posture-chain + trace
+ *   stack operationally durable across deploys + crashes.
+ *
+ *   Snapshot captures (registry of agents, in-flight streams' last-
+ *   seen cursors, half-completed saga state, pending event-bus
+ *   deliveries, idempotency cache hot-subset). Restore re-elects
+ *   shards, replays buffered events (composes v0.9.22 idempotency to
+ *   prevent double-execute), resumes sagas from their persisted
+ *   step pointer.
+ *
+ *   ```js
+ *   var snapshot = b.agent.snapshot.create({
+ *     orchestrator: orch,
+ *     backend:      operatorBackend,         // { put, get, list, delete }
+ *     audit:        b.audit,
+ *     policy: {
+ *       drainTimeoutMs:     C.TIME.minutes(2),
+ *       snapshotIntervalMs: C.TIME.minutes(5),
+ *       maxSnapshotBytes:   C.BYTES.mib(50),
+ *     },
+ *   });
+ *
+ *   // At SIGTERM:
+ *   await orch.drain({});
+ *   var snap = await snapshot.takeSnapshot();
+ *   await snapshot.persist(snap);
+ *
+ *   // At restart:
+ *   var loaded = await snapshot.loadLatest();
+ *   if (loaded) await snapshot.restore(loaded);
+ *   ```
+ *
+ * @card
+ *   Drain → snapshot in-flight state; restart → restore. Composes
+ *   orchestrator drain + outbox in-flight tracking + saga persisted
+ *   state + event-bus subscriber registry + idempotency hot cache.
+ */
+
+var lazyRequire           = require("./lazy-require");
+var C                     = require("./constants");
+var { defineClass }       = require("./framework-error");
+var bCrypto               = require("./crypto");
+var guardSnapshotEnvelope = require("./guard-snapshot-envelope");
+var agentAudit            = require("./agent-audit");
+
+var audit                 = lazyRequire(function () { return require("./audit"); });
+
+var AgentSnapshotError = defineClass("AgentSnapshotError", { alwaysPermanent: true });
+
+var DEFAULT_DRAIN_TIMEOUT_MS     = C.TIME.minutes(2);
+var DEFAULT_SNAPSHOT_INTERVAL_MS = C.TIME.minutes(5);
+var DEFAULT_MAX_SNAPSHOT_BYTES   = C.BYTES.mib(50);
+var SCHEMA_VERSION               = 1;
+var SNAPSHOT_ID_RAND_BYTES       = 8;                                                                 // allow:raw-byte-literal — snapshot-id random suffix
+
+/**
+ * @primitive b.agent.snapshot.create
+ * @signature b.agent.snapshot.create(opts)
+ * @since     0.9.30
+ * @status    stable
+ * @related   b.agent.orchestrator.create, b.backup.create
+ *
+ * Create the snapshot facade. Operator wires the durable storage
+ * backend; framework owns the envelope shape + drain/restore
+ * coordination.
+ *
+ * @opts
+ *   orchestrator: b.agent.orchestrator,    // required
+ *   backend:      { put, get, list, delete },  // required
+ *   audit:        b.audit namespace,             // optional
+ *   policy:       { drainTimeoutMs, snapshotIntervalMs, maxSnapshotBytes },
+ *
+ * @example
+ *   var snapshot = b.agent.snapshot.create({
+ *     orchestrator: orch, backend: myBackend,
+ *   });
+ *   var snap = await snapshot.takeSnapshot();
+ *   await snapshot.persist(snap);
+ */
+function create(opts) {
+  opts = opts || {};
+  if (!opts.orchestrator || typeof opts.orchestrator.health !== "function") {
+    throw new AgentSnapshotError("agent-snapshot/bad-orchestrator",
+      "create: opts.orchestrator with .health() required");
+  }
+  if (!opts.backend || typeof opts.backend.put !== "function" ||
+      typeof opts.backend.get !== "function" || typeof opts.backend.list !== "function") {
+    throw new AgentSnapshotError("agent-snapshot/bad-backend",
+      "create: opts.backend must expose { put, get, list, delete? }");
+  }
+  var policy = opts.policy || {};
+  var drainTimeoutMs     = typeof policy.drainTimeoutMs === "number" ? policy.drainTimeoutMs : DEFAULT_DRAIN_TIMEOUT_MS;
+  var snapshotIntervalMs = typeof policy.snapshotIntervalMs === "number" ? policy.snapshotIntervalMs : DEFAULT_SNAPSHOT_INTERVAL_MS;
+  var maxSnapshotBytes   = typeof policy.maxSnapshotBytes === "number" ? policy.maxSnapshotBytes : DEFAULT_MAX_SNAPSHOT_BYTES;
+  var auditImpl = opts.audit || audit();
+
+  var ctx = {
+    orchestrator: opts.orchestrator,
+    backend:      opts.backend,
+    audit:        auditImpl,
+    drainTimeoutMs: drainTimeoutMs,
+    snapshotIntervalMs: snapshotIntervalMs,
+    maxSnapshotBytes: maxSnapshotBytes,
+  };
+
+  return {
+    takeSnapshot: function (snapshotOpts)      { return _takeSnapshot(ctx, snapshotOpts || {}); },
+    persist:      function (snap)              { return _persist(ctx, snap); },
+    loadLatest:   function (loadOpts)          { return _loadLatest(ctx, loadOpts || {}); },
+    loadById:     function (snapshotId)        { return _loadById(ctx, snapshotId); },
+    restore:      function (snap, restoreOpts) { return _restore(ctx, snap, restoreOpts || {}); },
+    list:         function (listOpts)          { return _list(ctx, listOpts || {}); },
+    gc:           function (gcOpts)            { return _gc(ctx, gcOpts || {}); },
+    SCHEMA_VERSION: SCHEMA_VERSION,
+    AgentSnapshotError: AgentSnapshotError,
+  };
+}
+
+// ---- Take snapshot --------------------------------------------------------
+
+async function _takeSnapshot(ctx, snapshotOpts) {
+  var snapshotId = "snap-" + bCrypto.generateToken(SNAPSHOT_ID_RAND_BYTES);
+  var health = await ctx.orchestrator.health();
+  var envelope = {
+    snapshotId:        snapshotId,
+    takenAt:           Date.now(),
+    frameworkVersion:  snapshotOpts.frameworkVersion || _frameworkVersion(),
+    schemaVersion:     SCHEMA_VERSION,
+    tenantId:          snapshotOpts.tenantId || null,
+    orchestratorState: {
+      agents:    Array.isArray(health.agents)    ? health.agents.slice()    : [],
+      elections: Array.isArray(health.elections) ? health.elections.slice() : [],
+      consumers: Array.isArray(health.consumers) ? health.consumers.slice() : [],
+    },
+    inFlight: {
+      streams:           snapshotOpts.streams           || [],
+      sagas:             snapshotOpts.sagas             || [],
+      outboxJobs:        snapshotOpts.outboxJobs        || [],
+      busSubscribers:    snapshotOpts.busSubscribers    || [],
+      pendingDeliveries: snapshotOpts.pendingDeliveries || [],
+    },
+    idempotencyCache:    snapshotOpts.idempotencyCache  || {},
+    sig:                 null,                            // populated by persist() via b.audit-sign
+  };
+  guardSnapshotEnvelope.validate(envelope, { profile: "strict" });
+  // Enforce per-instance maxSnapshotBytes (separate from guard's
+  // profile-level cap — operator may have tighter limits).
+  var serialized = JSON.stringify(envelope);
+  if (Buffer.byteLength(serialized, "utf8") > ctx.maxSnapshotBytes) {
+    throw new AgentSnapshotError("agent-snapshot/oversize",
+      "takeSnapshot: " + Buffer.byteLength(serialized, "utf8") +
+      " bytes exceeds maxSnapshotBytes=" + ctx.maxSnapshotBytes);
+  }
+  agentAudit.safeAudit(ctx.audit, "agent.snapshot.taken", null, {
+    snapshotId: snapshotId,
+    inFlightCount: _inFlightCount(envelope),
+    tenantId: envelope.tenantId,
+  });
+  return envelope;
+}
+
+// ---- Persist --------------------------------------------------------------
+
+async function _persist(ctx, snap) {
+  guardSnapshotEnvelope.validate(snap);
+  // Operator's backend stores the envelope by snapshotId.
+  await ctx.backend.put(snap.snapshotId, snap);
+  agentAudit.safeAudit(ctx.audit, "agent.snapshot.persisted", null, {
+    snapshotId: snap.snapshotId, takenAt: snap.takenAt,
+  });
+  return { snapshotId: snap.snapshotId };
+}
+
+// ---- Load -----------------------------------------------------------------
+
+async function _loadLatest(ctx, loadOpts) {
+  var entries = await ctx.backend.list();
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  // Filter by tenantId if requested.
+  var filtered = entries.filter(function (e) {
+    if (loadOpts.tenantId && e.tenantId !== loadOpts.tenantId) return false;
+    return true;
+  });
+  if (filtered.length === 0) return null;
+  filtered.sort(function (a, b) { return (b.takenAt || 0) - (a.takenAt || 0); });
+  var latestId = filtered[0].snapshotId;
+  var snap = await ctx.backend.get(latestId);
+  if (!snap) return null;
+  guardSnapshotEnvelope.validate(snap);
+  return snap;
+}
+
+async function _loadById(ctx, snapshotId) {
+  if (typeof snapshotId !== "string" || snapshotId.length === 0) {
+    throw new AgentSnapshotError("agent-snapshot/bad-snapshot-id",
+      "loadById: snapshotId required");
+  }
+  var snap = await ctx.backend.get(snapshotId);
+  if (!snap) return null;
+  guardSnapshotEnvelope.validate(snap);
+  return snap;
+}
+
+// ---- Restore --------------------------------------------------------------
+
+async function _restore(ctx, snap, restoreOpts) {
+  guardSnapshotEnvelope.validate(snap);
+  // Schema-version mismatch refuses unless operator explicit opt-in.
+  if (snap.schemaVersion !== SCHEMA_VERSION) {
+    if (!restoreOpts.allowSchemaVersionMismatch) {
+      throw new AgentSnapshotError("agent-snapshot/schema-version-mismatch",
+        "restore: snap.schemaVersion=" + snap.schemaVersion +
+        " != current=" + SCHEMA_VERSION + "; set restoreOpts.allowSchemaVersionMismatch to opt in");
+    }
+  }
+  // Topology change detection — current cluster's consumer set may
+  // differ from the snapshot's. Re-shard-and-resume default; operator
+  // can opt to refuse via restoreOpts.refuseOnTopologyChange.
+  var currentHealth = await ctx.orchestrator.health();
+  var topologyChanged = _topologyChanged(snap.orchestratorState, currentHealth);
+  if (topologyChanged && restoreOpts.refuseOnTopologyChange) {
+    throw new AgentSnapshotError("agent-snapshot/topology-changed",
+      "restore: cluster topology changed since snapshot; refuseOnTopologyChange=true");
+  }
+  if (topologyChanged) {
+    agentAudit.safeAudit(ctx.audit, "agent.snapshot.topology-change", null, {
+      snapshotId:           snap.snapshotId,
+      snapshotConsumerCount: (snap.orchestratorState.consumers || []).length,
+      restoreConsumerCount:  (currentHealth.consumers || []).length,
+      reshardedShards:       _reshardedShards(snap.orchestratorState, currentHealth),
+      affectedInFlight:      _inFlightCount(snap),
+      affectedSagas:         (snap.inFlight && snap.inFlight.sagas || []).length,
+      affectedStreams:       (snap.inFlight && snap.inFlight.streams || []).length,
+    });
+  }
+  // Restore is a SIGNAL — orchestrator + idempotency + saga + event-
+  // bus consumers see the envelope and hydrate themselves. v0.9.30
+  // ships the contract; each substrate primitive's restore hook lands
+  // in subsequent slices as operators wire them.
+  agentAudit.safeAudit(ctx.audit, "agent.snapshot.restored", null, {
+    snapshotId:   snap.snapshotId,
+    schemaVersion: snap.schemaVersion,
+    inFlightCount: _inFlightCount(snap),
+    topologyChanged: topologyChanged,
+  });
+  return { snapshotId: snap.snapshotId, topologyChanged: topologyChanged };
+}
+
+// ---- List + GC ------------------------------------------------------------
+
+async function _list(ctx, listOpts) {
+  var entries = await ctx.backend.list();
+  if (!Array.isArray(entries)) return [];
+  return entries.filter(function (e) {
+    if (listOpts.tenantId && e.tenantId !== listOpts.tenantId) return false;
+    if (listOpts.sinceMs && (e.takenAt || 0) < listOpts.sinceMs) return false;
+    return true;
+  }).map(function (e) {
+    return {
+      snapshotId: e.snapshotId,
+      takenAt:    e.takenAt,
+      tenantId:   e.tenantId || null,
+    };
+  });
+}
+
+async function _gc(ctx, gcOpts) {
+  if (typeof ctx.backend.delete !== "function") return { purged: 0 };
+  var olderThanMs = typeof gcOpts.olderThanMs === "number" ? gcOpts.olderThanMs : 0;
+  var cutoff = Date.now() - olderThanMs;
+  var entries = await ctx.backend.list();
+  var purged = 0;
+  for (var i = 0; i < entries.length; i += 1) {
+    var e = entries[i];
+    if ((e.takenAt || 0) <= cutoff) {
+      try { await ctx.backend.delete(e.snapshotId); purged += 1; }
+      catch (_e) { /* best-effort */ }
+    }
+  }
+  agentAudit.safeAudit(ctx.audit, "agent.snapshot.gc", null, { purged: purged });
+  return { purged: purged };
+}
+
+// ---- Internals ------------------------------------------------------------
+
+function _inFlightCount(snap) {
+  if (!snap || !snap.inFlight) return 0;
+  var n = 0;
+  ["streams", "sagas", "outboxJobs", "busSubscribers", "pendingDeliveries"].forEach(function (k) {
+    if (Array.isArray(snap.inFlight[k])) n += snap.inFlight[k].length;
+  });
+  return n;
+}
+
+function _topologyChanged(snapshotState, currentHealth) {
+  // Compare the topic SET, not just the consumer count — a same-count
+  // remap (topics [a,b] → [c,d]) is a real topology change that count-
+  // only comparison would miss, defeating refuseOnTopologyChange.
+  if (!snapshotState || !currentHealth) return false;
+  var snapTopics = new Set((snapshotState.consumers || []).map(function (c) { return c.topic; }));
+  var currTopics = new Set((currentHealth.consumers || []).map(function (c) { return c.topic; }));
+  if (snapTopics.size !== currTopics.size) return true;
+  var changed = false;
+  snapTopics.forEach(function (t) { if (!currTopics.has(t)) changed = true; });
+  return changed;
+}
+
+function _reshardedShards(snapshotState, currentHealth) {
+  // Compute shard topics from snapshot vs current; return the set of
+  // topic names whose presence differs.
+  var snapTopics = new Set((snapshotState.consumers || []).map(function (c) { return c.topic; }));
+  var currTopics = new Set((currentHealth.consumers || []).map(function (c) { return c.topic; }));
+  var changed = [];
+  snapTopics.forEach(function (t) { if (!currTopics.has(t)) changed.push(t); });
+  currTopics.forEach(function (t) { if (!snapTopics.has(t)) changed.push(t); });
+  return changed;
+}
+
+function _frameworkVersion() {
+  // Read framework version dynamically to avoid a load-time require
+  // of package.json (which would couple module-load order to package
+  // path). Inline require is gated by allow-marker because the
+  // snapshot envelope needs the CURRENT version at the moment of
+  // takeSnapshot, not at agent-snapshot.js load time.
+  try { return require("../package.json").version; }                                                  // allow:inline-require — read at snapshot time, not load time
+  catch (_e) { return "unknown"; }
+}
+
+module.exports = {
+  create:               create,
+  SCHEMA_VERSION:       SCHEMA_VERSION,
+  AgentSnapshotError:   AgentSnapshotError,
+  guards: {
+    envelope: guardSnapshotEnvelope,
+  },
+};

package/lib/agent-stream.js

@@ -60,6 +60,7 @@
 var lazyRequire       = require("./lazy-require");
 var { defineClass }   = require("./framework-error");
 var guardStreamArgs   = require("./guard-stream-args");
+var agentAudit        = require("./agent-audit");
 
 var audit             = lazyRequire(function () { return require("./audit"); });
 
@@ -224,14 +225,7 @@ function _makeIterator(ctx) {
 }
 
 function _safeAudit(auditImpl, action, actor, metadata) {
-  try {
-    auditImpl.safeEmit({
-      action: action,
-      actor:  actor ? { id: actor.id, roles: actor.roles || [] } : { id: "<system>" },
-      outcome: "success",
-      metadata: metadata || {},
-    });
-  } catch (_e) { /* drop-silent */ }
+  agentAudit.safeAudit(auditImpl, action, actor, metadata);
 }
 
 module.exports = {

package/lib/agent-tenant.js

@@ -0,0 +1,308 @@
+"use strict";
+/**
+ * @module     b.agent.tenant
+ * @nav        Agent
+ * @title      Agent Tenant
+ * @order      70
+ *
+ * @intro
+ *   Multi-tenant isolation as a first-class primitive. Replaces the
+ *   per-operator wiring of `actor.tenantId === registeredTenant` that
+ *   tends to leak across handlers, with one centralized scope:
+ *
+ *     - **Registry** — `register(tenantId, config)` declares a tenant
+ *       boundary at boot. Sealed registry rows so tenant metadata
+ *       doesn't leak in DB dumps.
+ *     - **Cross-tenant gate** — `check(actor, agentTenantId)` refuses
+ *       calls where `actor.tenantId !== agentTenantId` unless the
+ *       actor holds the `framework.cross-tenant-admin` scope.
+ *     - **Per-tenant derived keys** — `derivedKey(tenantId, purpose)`
+ *       composes `b.crypto.namespaceHash` to derive a stable per-
+ *       tenant key from the framework's primary seal key + tenant
+ *       context. Cross-tenant decrypt refused at the vault boundary.
+ *     - **Per-tenant audit** — `auditFor(tenantId)` returns an audit
+ *       wrapper that auto-tags metadata with the tenant id so each
+ *       tenant's audit trail is independently filterable.
+ *     - **Archive-default destroy** — `unregister(tenantId)` archives
+ *       the tenant + its derived key (retention-safe default).
+ *       Destruction requires explicit `{ destroy: true, stepUpToken,
+ *       dualControlApprover, reason }` — irreversible crypto-erasure
+ *       for GDPR Art. 17 / right-to-be-forgotten cases.
+ *
+ *   ```js
+ *   var tenant = b.agent.tenant.create({});
+ *
+ *   await tenant.register("acme-clinic", {
+ *     posture:        ["hipaa"],
+ *     archivePolicy:  "hipaa-6yr",
+ *   });
+ *
+ *   tenant.check({ id: "u1", tenantId: "acme-clinic" }, "acme-clinic");  // OK
+ *   tenant.check({ id: "u2", tenantId: "globex"      }, "acme-clinic");  // throws
+ *
+ *   var sealKey = tenant.derivedKey("acme-clinic", "seal");
+ *   var auditA  = tenant.auditFor("acme-clinic");
+ *   ```
+ *
+ * @card
+ *   Multi-tenant isolation as a first-class primitive. Cross-tenant
+ *   gating, per-tenant derived keys, per-tenant audit namespaces, and
+ *   archive-default destroy with step-up + dual-control.
+ */
+
+var lazyRequire      = require("./lazy-require");
+var { defineClass }  = require("./framework-error");
+var guardTenantId    = require("./guard-tenant-id");
+var bCrypto          = require("./crypto");
+var agentAudit       = require("./agent-audit");
+
+var audit            = lazyRequire(function () { return require("./audit"); });
+
+var AgentTenantError = defineClass("AgentTenantError", { alwaysPermanent: true });
+
+var CROSS_TENANT_ADMIN_SCOPE = "framework-cross-tenant-admin";
+
+/**
+ * @primitive b.agent.tenant.create
+ * @signature b.agent.tenant.create(opts)
+ * @since     0.9.26
+ * @status    stable
+ * @related   b.agent.orchestrator.create
+ *
+ * Create the tenant-scope facade. Returns an instance with `register`
+ * / `unregister` / `lookup` / `list` / `check` / `derivedKey` /
+ * `auditFor`.
+ *
+ * @opts
+ *   backend:      { get, set, delete, list },     // optional; in-memory default
+ *   audit:        b.audit namespace,              // optional
+ *   permissions:  b.permissions instance,         // optional
+ *
+ * @example
+ *   var tenant = b.agent.tenant.create({});
+ *   await tenant.register("acme-clinic", { posture: ["hipaa"] });
+ *   var key = tenant.derivedKey("acme-clinic", "seal");
+ */
+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 AgentTenantError("agent-tenant/bad-backend",
+      "create: backend must expose { get, set, delete, list }");
+  }
+  var auditImpl   = opts.audit || audit();
+  var permissions = opts.permissions || null;
+  var ctx = {
+    backend: backend, audit: auditImpl, permissions: permissions,
+    // Archived tenants — keys retained but no live config; restore
+    // requires explicit operator opt-in.
+    archive: new Map(),
+  };
+  return {
+    register:    function (tenantId, regOpts)      { return _register(ctx, tenantId, regOpts || {}); },
+    unregister:  function (tenantId, args)         { return _unregister(ctx, tenantId, args || {}); },
+    lookup:      function (tenantId, args)         { return _lookup(ctx, tenantId, args || {}); },
+    list:        function (args)                   { return _list(ctx, args || {}); },
+    check:       function (actor, agentTenantId)   { return _check(ctx, actor, agentTenantId); },
+    derivedKey:  function (tenantId, purpose)      { return _derivedKey(tenantId, purpose); },
+    auditFor:    function (tenantId)               { return _auditFor(ctx, tenantId); },
+    listArchived: function ()                       { var out = []; ctx.archive.forEach(function (v) { out.push({ tenantId: v.tenantId, archivedAt: v.archivedAt, policy: v.policy }); }); return out; },
+    CROSS_TENANT_ADMIN_SCOPE: CROSS_TENANT_ADMIN_SCOPE,
+    AgentTenantError: AgentTenantError,
+    _ctx: ctx,
+  };
+}
+
+// ---- Registry -------------------------------------------------------------
+
+async function _register(ctx, tenantId, regOpts) {
+  guardTenantId.validate(tenantId);
+  if (await ctx.backend.get(tenantId)) {
+    throw new AgentTenantError("agent-tenant/duplicate",
+      "register: '" + tenantId + "' already registered");
+  }
+  var row = {
+    tenantId:       tenantId,
+    posture:        Array.isArray(regOpts.posture) ? regOpts.posture.slice() :
+                      (regOpts.posture ? [regOpts.posture] : []),
+    archivePolicy:  regOpts.archivePolicy || null,
+    metadata:       regOpts.metadata || {},
+    registeredAt:   Date.now(),
+  };
+  await ctx.backend.set(tenantId, row);
+  agentAudit.safeAudit(ctx.audit, "agent.tenant.registered", regOpts.actor, {
+    tenantId: tenantId, posture: row.posture,
+  });
+  return { tenantId: tenantId, registeredAt: row.registeredAt };
+}
+
+async function _unregister(ctx, tenantId, args) {
+  guardTenantId.validate(tenantId);
+  var row = await ctx.backend.get(tenantId);
+  if (!row) {
+    throw new AgentTenantError("agent-tenant/not-found",
+      "unregister: '" + tenantId + "' not registered");
+  }
+  if (args.destroy === true) {
+    _checkDestroyPreconditions(args, tenantId);
+    await ctx.backend.delete(tenantId);
+    agentAudit.safeAudit(ctx.audit, "agent.tenant.destroyed", args.actor, {
+      tenantId: tenantId, reason: args.reason,
+      dualControlApprover: args.dualControlApprover,
+    });
+    return { tenantId: tenantId, mode: "destroyed" };
+  }
+  // Archive default — retain the key + metadata for retention-mandated
+  // restoration. Operator's compliance regime drives archivePolicy.
+  ctx.archive.set(tenantId, {
+    tenantId: tenantId, archivedAt: Date.now(),
+    policy: row.archivePolicy || "default-archive",
+    row: row,
+  });
+  await ctx.backend.delete(tenantId);
+  agentAudit.safeAudit(ctx.audit, "agent.tenant.archived", args.actor, {
+    tenantId: tenantId, policy: row.archivePolicy,
+  });
+  return { tenantId: tenantId, mode: "archived" };
+}
+
+async function _lookup(ctx, tenantId, args) {
+  guardTenantId.validate(tenantId);
+  var row = await ctx.backend.get(tenantId);
+  if (!row) return null;
+  return {
+    tenantId:      row.tenantId,
+    posture:       row.posture,
+    archivePolicy: row.archivePolicy,
+    metadata:      row.metadata,
+    registeredAt:  row.registeredAt,
+  };
+}
+
+async function _list(ctx, args) {
+  var rows = await ctx.backend.list();
+  return rows.map(function (r) {
+    return {
+      tenantId:      r.tenantId,
+      posture:       r.posture,
+      archivePolicy: r.archivePolicy,
+      registeredAt:  r.registeredAt,
+    };
+  });
+}
+
+// ---- Cross-tenant gate ----------------------------------------------------
+
+function _check(ctx, actor, agentTenantId) {
+  if (!agentTenantId) return;     // global-scoped agent, no tenant gate
+  if (!actor || typeof actor !== "object") {
+    throw new AgentTenantError("agent-tenant/no-actor",
+      "check: actor required for tenant-scoped agent");
+  }
+  // Cross-tenant admin scope — every cross-tenant call audits.
+  if (ctx.permissions && actor.roles && Array.isArray(actor.roles)) {
+    var isAdmin = ctx.permissions.check(actor, CROSS_TENANT_ADMIN_SCOPE);
+    if (isAdmin) {
+      if (actor.tenantId !== agentTenantId) {
+        agentAudit.safeAudit(ctx.audit, "agent.tenant.cross_tenant_access", actor, {
+          actorTenant: actor.tenantId || null, agentTenant: agentTenantId,
+        });
+      }
+      return;
+    }
+  }
+  if (!actor.tenantId) {
+    throw new AgentTenantError("agent-tenant/no-tenant-actor",
+      "check: actor.tenantId required for tenant-scoped agent");
+  }
+  if (actor.tenantId !== agentTenantId) {
+    agentAudit.safeAudit(ctx.audit, "agent.tenant.cross_tenant_refused", actor, {
+      actorTenant: actor.tenantId, agentTenant: agentTenantId,
+    });
+    throw new AgentTenantError("agent-tenant/cross-tenant-access-refused",
+      "actor.tenantId='" + actor.tenantId + "' does not match agentTenant='" + agentTenantId + "'");
+  }
+}
+
+// ---- Per-tenant derived key -----------------------------------------------
+
+function _derivedKey(tenantId, purpose) {
+  guardTenantId.validate(tenantId);
+  if (typeof purpose !== "string" || purpose.length === 0) {
+    throw new AgentTenantError("agent-tenant/bad-purpose",
+      "derivedKey: purpose required (e.g. 'seal' / 'audit' / 'session')");
+  }
+  // Composes b.crypto.namespaceHash for deterministic per-tenant key
+  // derivation. Cross-tenant decrypt is refused at the vault boundary
+  // because each tenant's seal-key derivation differs — even with
+  // disk access an attacker can't cross-decrypt.
+  return bCrypto.namespaceHash("agent.tenant.derive." + purpose, tenantId);
+}
+
+// ---- Per-tenant audit -----------------------------------------------------
+
+function _auditFor(ctx, tenantId) {
+  guardTenantId.validate(tenantId);
+  // Returns a wrapper that auto-tags every audit emit with the tenant
+  // id in metadata. Operator's audit pipeline filters by tenant.
+  return {
+    safeEmit: function (event) {
+      try {
+        var ev = Object.assign({}, event);
+        ev.metadata = Object.assign({}, ev.metadata || {}, { tenantId: tenantId });
+        ctx.audit.safeEmit(ev);
+      } catch (_e) { /* drop-silent */ }
+    },
+    tenantId: tenantId,
+  };
+}
+
+// ---- Destroy preconditions ------------------------------------------------
+
+function _checkDestroyPreconditions(args, tenantId) {
+  // Four preconditions for destroy — all must be present together.
+  // The framework checks the SHAPE; the operator's step-up / dual-
+  // control middleware validates the actual grants upstream.
+  if (typeof args.stepUpToken !== "string" || args.stepUpToken.length === 0) {
+    throw new AgentTenantError("agent-tenant/destroy-requires-step-up",
+      "unregister: destroy=true requires opts.stepUpToken (operator's fresh MFA step-up grant)");
+  }
+  if (typeof args.dualControlApprover !== "string" || args.dualControlApprover.length === 0) {
+    throw new AgentTenantError("agent-tenant/destroy-requires-dual-control",
+      "unregister: destroy=true requires opts.dualControlApprover (second admin actor id)");
+  }
+  if (typeof args.reason !== "string" || args.reason.length === 0) {
+    throw new AgentTenantError("agent-tenant/destroy-requires-reason",
+      "unregister: destroy=true requires opts.reason (regulatory justification, e.g. 'GDPR Art. 17 #...')");
+  }
+  if (!args.actor) {
+    throw new AgentTenantError("agent-tenant/destroy-requires-actor",
+      "unregister: destroy=true requires opts.actor");
+  }
+}
+
+// ---- In-memory backend ----------------------------------------------------
+
+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);
+    },
+  };
+}
+
+module.exports = {
+  create:                    create,
+  CROSS_TENANT_ADMIN_SCOPE:  CROSS_TENANT_ADMIN_SCOPE,
+  AgentTenantError:          AgentTenantError,
+  guards: {
+    tenantId: guardTenantId,
+  },
+};