@blamejs/core 0.9.49 → 0.10.2

package/lib/agent-saga.js

@@ -105,31 +105,119 @@ var SAGA_ID_RAND_BYTES = 8;
 function create(config) {
   guardSagaConfig.validate(config);
   var auditImpl = config.audit || audit();
+  // SUBSTRATE-7 — operator wires a stateStore for crash-safe resume.
+  // Interface: { saveStep, loadResumePoint, markCompleted, markFailed }.
+  // saveStep({sagaId, stepIndex, stepName, state, status}) commits
+  // after each step.run; loadResumePoint(sagaId) returns the resume
+  // shape `{ stepIndex, state }` on restart. Without a stateStore, the
+  // saga still runs end-to-end in-memory but a mid-saga crash loses
+  // progress (operator-acknowledged dev mode; the audit emit
+  // `agent.saga.no_state_store` surfaces the posture per call).
+  var stateStore = config.stateStore || null;
+  if (stateStore !== null) {
+    if (typeof stateStore.saveStep !== "function" ||
+        typeof stateStore.loadResumePoint !== "function") {
+      throw new AgentSagaError("agent-saga/bad-state-store",
+        "create: stateStore must expose { saveStep, loadResumePoint, markCompleted?, markFailed? }");
+    }
+  }
   return {
-    run:                    function (ctx, initialState, opts) { return _run(config, auditImpl, ctx, initialState, opts || {}); },
+    run:                    function (ctx, initialState, opts) { return _run(config, auditImpl, stateStore, ctx, initialState, opts || {}); },
+    resume:                 function (sagaId, ctx, opts) { return _resume(config, auditImpl, stateStore, sagaId, ctx, opts || {}); },
     name:                   config.name,
     stepCount:              config.steps.length,
     AgentSagaError:         AgentSagaError,
   };
 }
 
-async function _run(config, auditImpl, ctx, initialState, opts) {
+async function _resume(config, auditImpl, stateStore, sagaId, ctx, opts) {
+  if (!stateStore) {
+    throw new AgentSagaError("agent-saga/no-state-store",
+      "resume: stateStore not wired at create(); cannot resume without persisted state");
+  }
+  if (typeof sagaId !== "string" || sagaId.length === 0) {
+    throw new AgentSagaError("agent-saga/bad-saga-id",
+      "resume: sagaId required");
+  }
+  var resumePoint = await stateStore.loadResumePoint(sagaId);
+  if (!resumePoint || typeof resumePoint.stepIndex !== "number") {
+    throw new AgentSagaError("agent-saga/not-found",
+      "resume: no resume point for saga '" + sagaId + "'");
+  }
+  return _runFrom(config, auditImpl, stateStore, ctx,
+    resumePoint.state || {}, opts, sagaId, resumePoint.stepIndex);
+}
+
+async function _run(config, auditImpl, stateStore, ctx, initialState, opts) {
   var sagaId = opts.sagaId || "saga-" + bCrypto.generateToken(SAGA_ID_RAND_BYTES);
-  var state  = Object.assign({}, initialState || {});
+  return _runFrom(config, auditImpl, stateStore, ctx,
+    Object.assign({}, initialState || {}), opts, sagaId, 0);
+}
+
+async function _runFrom(config, auditImpl, stateStore, ctx, state, opts, sagaId, startIndex) {
+  // completedSteps captures index + step reference. On resume we
+  // start mid-saga; prior steps are already committed and don't need
+  // compensation on a failure in this run (compensation cascades
+  // walked persistent state to find the prior completed set).
   var completedSteps = [];
 
-  agentAudit.safeAudit(auditImpl, "agent.saga.started", opts.actor, {
-    sagaId: sagaId, name: config.name, stepCount: config.steps.length,
-  });
+  if (startIndex === 0) {
+    agentAudit.safeAudit(auditImpl, "agent.saga.started", opts.actor, {
+      sagaId: sagaId, name: config.name, stepCount: config.steps.length,
+    });
+    if (!stateStore) {
+      agentAudit.safeAudit(auditImpl, "agent.saga.no_state_store", opts.actor, {
+        sagaId: sagaId, name: config.name,
+        warning: "no stateStore wired; mid-saga crash will lose progress",
+      });
+    }
+  } else {
+    agentAudit.safeAudit(auditImpl, "agent.saga.resumed", opts.actor, {
+      sagaId: sagaId, name: config.name, fromIndex: startIndex,
+    });
+  }
 
-  for (var i = 0; i < config.steps.length; i += 1) {
+  for (var i = startIndex; i < config.steps.length; i += 1) {
     var step = config.steps[i];
     try {
       agentAudit.safeAudit(auditImpl, "agent.saga.step_started", opts.actor, {
         sagaId: sagaId, name: config.name, stepName: step.name, stepIndex: i,
       });
       await step.run(ctx, state);
-      completedSteps.push(step);
+      completedSteps.push({ step: step, index: i });
+      // SUBSTRATE-7 — checkpoint after the step.run returns. saveStep
+      // commits the post-step state so a crash before the NEXT step
+      // resumes from i+1. The audit chain records the checkpoint
+      // independently of the operator's stateStore — operator can
+      // cross-correlate.
+      if (stateStore) {
+        try {
+          await stateStore.saveStep({
+            sagaId:    sagaId,
+            sagaName:  config.name,
+            stepIndex: i,
+            stepName:  step.name,
+            state:     state,
+            status:    "completed",
+            nextIndex: i + 1,
+            checkpointedAt: Date.now(),
+          });
+        } catch (storeErr) {
+          agentAudit.safeAudit(auditImpl, "agent.saga.checkpoint_failed", opts.actor, {
+            sagaId: sagaId, name: config.name, stepName: step.name,
+            stepIndex: i, reason: (storeErr && storeErr.message) || String(storeErr),
+          });
+          // saveStep failure is fatal — without the checkpoint the
+          // saga cannot resume. Treat as step failure (compensate +
+          // throw); the operator's stateStore quota / disk / network
+          // outage surfaces here, not silently.
+          var ckptErr = new AgentSagaError("agent-saga/checkpoint-failed",
+            "saga '" + config.name + "' checkpoint after step '" + step.name +
+            "' failed: " + ((storeErr && storeErr.message) || String(storeErr)));
+          ckptErr.cause = storeErr;
+          throw ckptErr;
+        }
+      }
       agentAudit.safeAudit(auditImpl, "agent.saga.step_completed", opts.actor, {
         sagaId: sagaId, name: config.name, stepName: step.name, stepIndex: i,
       });
@@ -140,8 +228,15 @@ async function _run(config, auditImpl, ctx, initialState, opts) {
         message: (stepErr && stepErr.message) || String(stepErr),
       });
       var compensationError = null;
+      // BUG-5 — capture the compensation step that ACTUALLY failed,
+      // not "completedSteps[completedSteps.length-1].name" which
+      // names the last-COMPLETED step regardless of which compensation
+      // threw. CWE-209-adjacent (information disclosure via wrong
+      // error attribution).
+      var failedCompStepName = null;
       for (var c = completedSteps.length - 1; c >= 0; c -= 1) {
-        var compStep = completedSteps[c];
+        var compEntry = completedSteps[c];
+        var compStep = compEntry.step;
         if (typeof compStep.compensate !== "function") continue;
         try {
           agentAudit.safeAudit(auditImpl, "agent.saga.compensation_started", opts.actor, {
@@ -156,6 +251,7 @@ async function _run(config, auditImpl, ctx, initialState, opts) {
           // Halt further compensations; record what failed so audit
           // pipeline can alert.
           compensationError = compErr;
+          failedCompStepName = compStep.name;
           agentAudit.safeAudit(auditImpl, "agent.saga.compensation_failed", opts.actor, {
             sagaId: sagaId, name: config.name, stepName: compStep.name,
             message: (compErr && compErr.message) || String(compErr),
@@ -166,16 +262,50 @@ async function _run(config, auditImpl, ctx, initialState, opts) {
       agentAudit.safeAudit(auditImpl, "agent.saga.failed", opts.actor, {
         sagaId: sagaId, name: config.name, failedStep: step.name,
         compensationFailed: compensationError !== null,
+        compensationFailedAt: failedCompStepName,
       });
-      throw new AgentSagaError("agent-saga/failed",
-        "saga '" + config.name + "' failed at step '" + step.name + "': " +
-        ((stepErr && stepErr.message) || String(stepErr)) +
-        (compensationError ? " — and compensation '" + completedSteps[completedSteps.length - 1].name +
-                              "' subsequently failed: " +
-                              (compensationError.message || String(compensationError))
-                            : ""));
+      if (stateStore && typeof stateStore.markFailed === "function") {
+        try {
+          await stateStore.markFailed({
+            sagaId: sagaId, sagaName: config.name,
+            failedStep: step.name, stepIndex: i,
+            compensationFailedAt: failedCompStepName,
+            state: state,
+          });
+        } catch (_e) { /* drop-silent — audit already records */ }
+      }
+      // SUBSTRATE-15 — attach cause:stepErr so the original step
+      // error stack survives. ES2022 Error.cause is the standard
+      // mechanism; the framework's defineClass-built AgentSagaError
+      // accepts cause via the third arg.
+      var detailMsg = "saga '" + config.name + "' failed at step '" + step.name + "': " +
+        ((stepErr && stepErr.message) || String(stepErr));
+      if (compensationError && failedCompStepName) {
+        detailMsg += " — and compensation of step '" + failedCompStepName +
+                     "' subsequently failed: " +
+                     ((compensationError.message) || String(compensationError));
+      }
+      var sagaErr = new AgentSagaError("agent-saga/failed", detailMsg);
+      // SUBSTRATE-15 — ES2022 Error.cause attaches the originating
+      // stepErr so operator stack-trace tooling can walk the chain.
+      // defineClass({alwaysPermanent:true}) doesn't accept cause in
+      // its constructor signature; the property assignment after
+      // construction is the standard post-instantiation pattern.
+      sagaErr.cause                = stepErr;
+      sagaErr.compensationCause    = compensationError || null;
+      sagaErr.failedStep           = step.name;
+      sagaErr.failedCompStepName   = failedCompStepName;
+      throw sagaErr;
     }
   }
+  if (stateStore && typeof stateStore.markCompleted === "function") {
+    try {
+      await stateStore.markCompleted({
+        sagaId: sagaId, sagaName: config.name,
+        stepCount: config.steps.length, state: state,
+      });
+    } catch (_e) { /* drop-silent — audit records */ }
+  }
   agentAudit.safeAudit(auditImpl, "agent.saga.completed", opts.actor, {
     sagaId: sagaId, name: config.name, stepCount: config.steps.length,
   });

package/lib/agent-snapshot.js

@@ -52,11 +52,21 @@ var { defineClass }       = require("./framework-error");
 var bCrypto               = require("./crypto");
 var guardSnapshotEnvelope = require("./guard-snapshot-envelope");
 var agentAudit            = require("./agent-audit");
+var safeJson              = require("./safe-json");
 
 var audit                 = lazyRequire(function () { return require("./audit"); });
+var auditSign             = lazyRequire(function () { return require("./audit-sign"); });
+var vault                 = lazyRequire(function () { return require("./vault"); });
 
 var AgentSnapshotError = defineClass("AgentSnapshotError", { alwaysPermanent: true });
 
+// SUBSTRATE-2 — sealed envelopes start with this prefix on disk; the
+// loader sniffs it and routes through unseal before guardSnapshotEnvelope
+// validation. Compatible with operator backends that store the value
+// as a string (JSON DBs, k/v stores) or wrap it in `{ value: "..." }`.
+var SEALED_PREFIX = "snap-sealed-v1:";
+var SNAPSHOT_TABLE = "agent.snapshot";
+
 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);
@@ -103,6 +113,28 @@ function create(opts) {
   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();
+  // SUBSTRATE-1 — operator may inject `signer` (interface
+  // `{ sign(bytes) → Buffer, verify(bytes, sig, pubKey?) → boolean }`)
+  // for testing / alternate key custody. Default = b.auditSign when
+  // initialized at boot; refuses persist() with a clear error if
+  // neither is wired so secure-by-default holds.
+  var signer = opts.signer || null;
+  // SUBSTRATE-2 — operator may inject `sealer` (interface
+  // `{ seal(plaintext, aadParts) → string, unseal(value, aadParts) → string }`)
+  // for alternate KMS integration. Default = b.vault.aad. Refused if
+  // neither is wired AND opts.allowPlaintext is not explicitly true
+  // (operator-justified dev / single-tenant deployments only).
+  var sealer = opts.sealer || null;
+  // SUBSTRATE-18 — operator-supplied restoreHandlers walk the
+  // snapshot inFlight + idempotencyCache + orchestratorState segments
+  // and hydrate the corresponding consumer module. Map shape:
+  //   { streams, sagas, outboxJobs, busSubscribers, pendingDeliveries,
+  //     idempotencyCache, orchestratorState }
+  // Each is an async function(payload, ctx). Missing keys are no-ops.
+  var restoreHandlers = opts.restoreHandlers && typeof opts.restoreHandlers === "object"
+    ? opts.restoreHandlers : null;
+
+  var allowPlaintext = opts.allowPlaintext === true;
 
   var ctx = {
     orchestrator: opts.orchestrator,
@@ -111,6 +143,10 @@ function create(opts) {
     drainTimeoutMs: drainTimeoutMs,
     snapshotIntervalMs: snapshotIntervalMs,
     maxSnapshotBytes: maxSnapshotBytes,
+    signer:           signer,
+    sealer:           sealer,
+    restoreHandlers:  restoreHandlers,
+    allowPlaintext:   allowPlaintext,
   };
 
   return {
@@ -121,11 +157,97 @@ function create(opts) {
     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,
+    SCHEMA_VERSION:       SCHEMA_VERSION,
+    SEALED_PREFIX:        SEALED_PREFIX,
+    AgentSnapshotError:   AgentSnapshotError,
+  };
+}
+
+// ---- Signer + sealer resolution -------------------------------------------
+
+function _resolveSigner(ctx) {
+  if (ctx.signer) return ctx.signer;
+  var as;
+  try { as = auditSign(); } catch (_e) { as = null; }
+  if (as && typeof as.sign === "function" && typeof as.verify === "function") {
+    // b.auditSign.sign throws "auditSign/not-initialized" when called
+    // pre-init — surface that here as the snapshot's signer-not-wired
+    // error so the caller's message is consistent regardless of which
+    // dependency landed unwired.
+    return {
+      sign: function (bytes) {
+        try { return as.sign(bytes); }
+        catch (e) {
+          throw new AgentSnapshotError("agent-snapshot/signer-not-wired",
+            "persist: b.auditSign.sign threw (" + (e && e.message ? e.message : String(e)) +
+            ") — operator must run b.auditSign.init() at boot OR pass opts.signer to b.agent.snapshot.create");
+        }
+      },
+      verify: function (bytes, sig, pubKey) {
+        try { return as.verify(bytes, sig, pubKey); }
+        catch (_e) { return false; }
+      },
+      getPublicKey: function () {
+        try { return as.getPublicKey(); } catch (_e) { return null; }
+      },
+    };
+  }
+  throw new AgentSnapshotError("agent-snapshot/signer-not-wired",
+    "persist: no signer wired — operator must run b.auditSign.init() at boot " +
+    "OR pass opts.signer to b.agent.snapshot.create({ signer: { sign, verify } })");
+}
+
+function _resolveSealer(ctx) {
+  if (ctx.sealer) return ctx.sealer;
+  var v;
+  try { v = vault(); } catch (_e) { v = null; }
+  if (v && v.aad && typeof v.aad.seal === "function" && typeof v.aad.unseal === "function") {
+    return v.aad;
+  }
+  if (ctx.allowPlaintext) return null;
+  throw new AgentSnapshotError("agent-snapshot/sealer-not-wired",
+    "persist: no sealer wired — operator must run b.vault.init() at boot " +
+    "OR pass opts.sealer to b.agent.snapshot.create({ sealer: { seal, unseal } }) " +
+    "OR opt out explicitly with { allowPlaintext: true } (refused under hipaa/pci-dss/gdpr/soc2 postures)");
+}
+
+function _snapshotAad(snap) {
+  return {
+    table:         SNAPSHOT_TABLE,
+    rowId:         snap.snapshotId,
+    column:        "envelope",
+    schemaVersion: String(snap.schemaVersion || SCHEMA_VERSION),
   };
 }
 
+// Signable content — every field that operators verify off the wire.
+// Excludes `sig` itself (signatures don't sign themselves) and
+// excludes the schemaless `idempotencyCache` body (size + structure
+// already covered by the seal's AEAD tag).
+function _canonicalSigBytes(snap) {
+  var payload = {
+    snapshotId:        snap.snapshotId,
+    takenAt:           snap.takenAt,
+    frameworkVersion:  snap.frameworkVersion,
+    schemaVersion:     snap.schemaVersion,
+    tenantId:          snap.tenantId || null,
+    contentHash:       _contentHash(snap),
+  };
+  return Buffer.from(safeJson.canonical(payload), "utf8");
+}
+
+function _contentHash(snap) {
+  // Bind the signature to the in-flight payload via SHA3-512 so the
+  // signed bytes stay bounded (the 5 KB SLH-DSA / 3.3 KB ML-DSA-65
+  // signature shouldn't have to cover a 50 MiB envelope's payload).
+  var body = {
+    orchestratorState: snap.orchestratorState || {},
+    inFlight:          snap.inFlight || {},
+    idempotencyCache:  snap.idempotencyCache || {},
+  };
+  return bCrypto.sha3Hash(safeJson.canonical(body));
+}
+
 // ---- Take snapshot --------------------------------------------------------
 
 async function _takeSnapshot(ctx, snapshotOpts) {
@@ -150,7 +272,12 @@ async function _takeSnapshot(ctx, snapshotOpts) {
       pendingDeliveries: snapshotOpts.pendingDeliveries || [],
     },
     idempotencyCache:    snapshotOpts.idempotencyCache  || {},
-    sig:                 null,                            // populated by persist() via b.audit-sign
+    // sig + sigPubKey populated by persist() via b.audit-sign. The
+    // wire envelope MAY ship with sig:null pre-persist (operator
+    // wants to inspect the bytes before commit); guardSnapshotEnvelope
+    // doesn't enforce sig presence (loader does).
+    sig:                 null,
+    sigPubKey:           null,
   };
   guardSnapshotEnvelope.validate(envelope, { profile: "strict" });
   // Enforce per-instance maxSnapshotBytes (separate from guard's
@@ -173,20 +300,150 @@ async function _takeSnapshot(ctx, snapshotOpts) {
 
 async function _persist(ctx, snap) {
   guardSnapshotEnvelope.validate(snap);
-  // Operator's backend stores the envelope by snapshotId.
-  await ctx.backend.put(snap.snapshotId, snap);
+  // SUBSTRATE-1 — sign first so a backend that mutates on put() (very
+  // common for k/v stores adding metadata) doesn't poison the signed
+  // bytes downstream readers verify.
+  var signer = _resolveSigner(ctx);
+  var sigBytes = signer.sign(_canonicalSigBytes(snap));
+  snap.sig = sigBytes.toString("base64");
+  // Persist a fingerprint alongside the signature so loadLatest can
+  // reject stale-key signatures (operator rotated audit-sign keys
+  // after the snapshot was taken). _resolveSigner exposes
+  // getPublicKey when wired off b.auditSign; operator-supplied signers
+  // may set null which we accept (verify falls back to the bound
+  // pubkey at verify time).
+  snap.sigPubKey = (typeof signer.getPublicKey === "function" && signer.getPublicKey()) || null;
+
+  // SUBSTRATE-2 — seal the entire envelope under AAD that pins
+  // snapshotId + schemaVersion + tenantId. AAD mismatch on unseal (a
+  // copy-paste attack from one snapshotId's row into another) fails
+  // the Poly1305 tag check; tampered bytes also fail. The sealed
+  // string is what reaches durable storage.
+  var sealer = _resolveSealer(ctx);
+  var serialized = safeJson.stringify(snap);
+  if (Buffer.byteLength(serialized, "utf8") > ctx.maxSnapshotBytes) {
+    throw new AgentSnapshotError("agent-snapshot/oversize",
+      "persist: " + Buffer.byteLength(serialized, "utf8") +
+      " bytes exceeds maxSnapshotBytes=" + ctx.maxSnapshotBytes);
+  }
+  var stored;
+  if (sealer) {
+    var sealedBlob = sealer.seal(serialized, _snapshotAad(snap));
+    // Wrapper keeps the unsealed metadata fields the backend's list()
+    // implementation needs to filter by tenantId / takenAt without
+    // having to unseal every row. Sealed-blob carries the full
+    // envelope; the metadata is decorative + may be tamper-fuzzed by
+    // a hostile backend (the AEAD tag still binds via AAD on unseal).
+    stored = {
+      snapshotId: snap.snapshotId,
+      takenAt:    snap.takenAt,
+      tenantId:   snap.tenantId || null,
+      sealed:     SEALED_PREFIX + sealedBlob,
+    };
+  } else {
+    // ctx.allowPlaintext === true path — operator-acknowledged dev
+    // mode. Still emit an audit so the operational posture is visible
+    // in the audit chain (operator can grep for plaintext snapshots
+    // in production audit feeds and confirm none exist).
+    agentAudit.safeAudit(ctx.audit, "agent.snapshot.plaintext_persist", null, {
+      snapshotId: snap.snapshotId,
+    });
+    stored = snap;
+  }
+  await ctx.backend.put(snap.snapshotId, stored);
   agentAudit.safeAudit(ctx.audit, "agent.snapshot.persisted", null, {
     snapshotId: snap.snapshotId, takenAt: snap.takenAt,
+    signed: true, sealed: !!sealer,
   });
   return { snapshotId: snap.snapshotId };
 }
 
 // ---- Load -----------------------------------------------------------------
 
+async function _unwrapAndVerify(ctx, raw, expectedId) {
+  if (!raw) return null;
+  var snap;
+  if (raw.sealed && typeof raw.sealed === "string" && raw.sealed.indexOf(SEALED_PREFIX) === 0) {
+    var sealer = _resolveSealer(ctx);
+    if (!sealer) {
+      throw new AgentSnapshotError("agent-snapshot/sealer-not-wired",
+        "load: snapshot " + raw.snapshotId + " is sealed but no sealer wired");
+    }
+    var sealedBlob = raw.sealed.slice(SEALED_PREFIX.length);
+    var aad = {
+      table:         SNAPSHOT_TABLE,
+      rowId:         raw.snapshotId,
+      column:        "envelope",
+      // schemaVersion is rebuilt at the same point load reads it; the
+      // wrapper carries it explicitly so a sealed envelope written
+      // under SCHEMA_VERSION=1 still unseals when the framework
+      // bumps to 2 later (the restore path then fires the
+      // allowSchemaVersionMismatch gate).
+      schemaVersion: String(raw.schemaVersion || SCHEMA_VERSION),
+    };
+    var plaintext;
+    try { plaintext = sealer.unseal(sealedBlob, aad); }
+    catch (e) {
+      agentAudit.safeAudit(ctx.audit, "agent.snapshot.unseal_failed", null, {
+        snapshotId: raw.snapshotId, reason: (e && e.message) || String(e),
+      });
+      throw new AgentSnapshotError("agent-snapshot/unseal-failed",
+        "load: snapshot " + raw.snapshotId + " unseal failed — value may be tampered, " +
+        "copied from a different snapshotId, or sealed under a different vault keypair");
+    }
+    snap = safeJson.parse(plaintext, { maxBytes: ctx.maxSnapshotBytes });
+  } else {
+    snap = raw;
+  }
+  guardSnapshotEnvelope.validate(snap);
+  if (expectedId && snap.snapshotId !== expectedId) {
+    // Wrapper carried snapshotId 'A' but the sealed body unsealed to
+    // snapshotId 'B' — defends a hostile backend that swaps wrapper
+    // metadata while AAD still matches the inner id (the AAD is built
+    // from `raw.snapshotId`, so the unseal would fail anyway, but
+    // surface explicitly).
+    throw new AgentSnapshotError("agent-snapshot/snapshot-id-mismatch",
+      "load: wrapper snapshotId='" + expectedId + "' does not match envelope='" + snap.snapshotId + "'");
+  }
+  // SUBSTRATE-1 — verify the signature before returning the envelope
+  // to the caller. Restore-side trust derives from this gate. The
+  // allowPlaintext escape hatch (operator-acknowledged dev mode)
+  // also waives signature verification because there's no key custody
+  // wired to verify against. Audit-emits so the operational posture
+  // remains visible to compliance audit.
+  if (typeof snap.sig !== "string" || snap.sig.length === 0) {
+    if (ctx.allowPlaintext) {
+      agentAudit.safeAudit(ctx.audit, "agent.snapshot.unsigned_load", null, {
+        snapshotId: snap.snapshotId,
+      });
+      return snap;
+    }
+    throw new AgentSnapshotError("agent-snapshot/unsigned",
+      "load: snapshot " + snap.snapshotId + " is unsigned — refusing to restore");
+  }
+  var signer = _resolveSigner(ctx);
+  var sigBuf = Buffer.from(snap.sig, "base64");
+  var ok = false;
+  try {
+    ok = signer.verify(_canonicalSigBytes(snap), sigBuf, snap.sigPubKey || undefined);
+  } catch (_e) { ok = false; }
+  if (!ok) {
+    agentAudit.safeAudit(ctx.audit, "agent.snapshot.signature_invalid", null, {
+      snapshotId: snap.snapshotId,
+    });
+    throw new AgentSnapshotError("agent-snapshot/bad-signature",
+      "load: snapshot " + snap.snapshotId + " signature verify failed — " +
+      "may be tampered or signed under a key the current verifier doesn't trust");
+  }
+  return snap;
+}
+
 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.
+  // Filter by tenantId if requested. Sealed entries carry tenantId in
+  // the wrapper for cheap-index filtering; the inner sealed body
+  // confirms via AAD on unseal.
   var filtered = entries.filter(function (e) {
     if (loadOpts.tenantId && e.tenantId !== loadOpts.tenantId) return false;
     return true;
@@ -194,10 +451,8 @@ async function _loadLatest(ctx, loadOpts) {
   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;
+  var raw = await ctx.backend.get(latestId);
+  return await _unwrapAndVerify(ctx, raw, latestId);
 }
 
 async function _loadById(ctx, snapshotId) {
@@ -205,10 +460,8 @@ async function _loadById(ctx, snapshotId) {
     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;
+  var raw = await ctx.backend.get(snapshotId);
+  return await _unwrapAndVerify(ctx, raw, snapshotId);
 }
 
 // ---- Restore --------------------------------------------------------------
@@ -243,17 +496,94 @@ async function _restore(ctx, snap, restoreOpts) {
       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.
+  // SUBSTRATE-18 — invoke operator-supplied restoreHandlers across
+  // every segment the snapshot envelope carries. Handlers are
+  // declared at create() time; the snapshot primitive owns ordering
+  // (orchestratorState first so live agents register before consumers
+  // start, idempotencyCache before saga/stream so duplicate-detect
+  // works, in-flight saga/stream/outbox/bus last) and the audit
+  // emits. Each handler returns a count of restored items.
+  //
+  // Spec order — 8 documented steps:
+  //   1. orchestratorState (re-elect singletons + topology re-register)
+  //   2. idempotencyCache (hot subset of the keys)
+  //   3. inFlight.sagas (resume from persisted step pointer)
+  //   4. inFlight.streams (re-open with lastSeenCursor)
+  //   5. inFlight.outboxJobs (re-enqueue any in-flight)
+  //   6. inFlight.busSubscribers (re-subscribe + replay pending)
+  //   7. inFlight.pendingDeliveries (drain the buffered events)
+  //   8. final audit emit + result summary
+  var counts = {
+    orchestratorState: 0,
+    idempotencyCache:  0,
+    sagas:             0,
+    streams:           0,
+    outboxJobs:        0,
+    busSubscribers:    0,
+    pendingDeliveries: 0,
+  };
+  var handlers = ctx.restoreHandlers;
+  var handlerCtx = { snapshotId: snap.snapshotId, takenAt: snap.takenAt, audit: ctx.audit };
+  if (handlers) {
+    counts.orchestratorState = await _runHandler(handlers.orchestratorState, snap.orchestratorState, handlerCtx);
+    counts.idempotencyCache  = await _runHandler(handlers.idempotencyCache,  snap.idempotencyCache,  handlerCtx);
+    if (snap.inFlight) {
+      counts.sagas             = await _runHandler(handlers.sagas,             snap.inFlight.sagas,             handlerCtx);
+      counts.streams           = await _runHandler(handlers.streams,           snap.inFlight.streams,           handlerCtx);
+      counts.outboxJobs        = await _runHandler(handlers.outboxJobs,        snap.inFlight.outboxJobs,        handlerCtx);
+      counts.busSubscribers    = await _runHandler(handlers.busSubscribers,    snap.inFlight.busSubscribers,    handlerCtx);
+      counts.pendingDeliveries = await _runHandler(handlers.pendingDeliveries, snap.inFlight.pendingDeliveries, handlerCtx);
+    }
+  } else if (_inFlightCount(snap) > 0) {
+    // Per no-MVP rule: if the operator passed restoreOpts.requireHandlers
+    // OR the snapshot has in-flight items, refuse the silent no-op so
+    // an operator restarting with non-empty inFlight doesn't think
+    // restore worked when actually nothing happened.
+    if (restoreOpts.requireHandlers || _inFlightCount(snap) > 0) {
+      agentAudit.safeAudit(ctx.audit, "agent.snapshot.restore_skipped_no_handlers", null, {
+        snapshotId: snap.snapshotId, inFlightCount: _inFlightCount(snap),
+      });
+      if (restoreOpts.requireHandlers) {
+        throw new AgentSnapshotError("agent-snapshot/no-restore-handlers",
+          "restore: snapshot " + snap.snapshotId + " carries " + _inFlightCount(snap) +
+          " in-flight items but no restoreHandlers wired; pass " +
+          "create({ restoreHandlers: { ... } }) or restoreOpts.requireHandlers=false " +
+          "to acknowledge data drop");
+      }
+    }
+  }
   agentAudit.safeAudit(ctx.audit, "agent.snapshot.restored", null, {
     snapshotId:   snap.snapshotId,
     schemaVersion: snap.schemaVersion,
     inFlightCount: _inFlightCount(snap),
     topologyChanged: topologyChanged,
+    counts:       counts,
   });
-  return { snapshotId: snap.snapshotId, topologyChanged: topologyChanged };
+  return {
+    snapshotId:      snap.snapshotId,
+    topologyChanged: topologyChanged,
+    restored:        counts,
+  };
+}
+
+async function _runHandler(handler, payload, handlerCtx) {
+  if (typeof handler !== "function") return 0;
+  if (payload === undefined || payload === null) return 0;
+  var r;
+  try { r = await handler(payload, handlerCtx); }
+  catch (e) {
+    agentAudit.safeAudit(handlerCtx.audit, "agent.snapshot.restore_handler_failed", null, {
+      snapshotId: handlerCtx.snapshotId,
+      reason:     (e && e.message) || String(e),
+    });
+    throw new AgentSnapshotError("agent-snapshot/restore-handler-failed",
+      "restore: handler threw — " + ((e && e.message) || String(e)));
+  }
+  if (typeof r === "number" && r >= 0) return r;
+  // Handler that returns void is treated as 1-item processed (the
+  // payload itself); array payloads return their length.
+  if (Array.isArray(payload)) return payload.length;
+  return 1;
 }
 
 // ---- List + GC ------------------------------------------------------------