@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/test/layer-0-primitives/agent-saga.test.js

@@ -0,0 +1,279 @@
+"use strict";
+
+var helpers = require("../helpers");
+var b       = helpers.b;
+var check   = helpers.check;
+
+function expectRejection(label, p, codeMatch) {
+  return p.then(
+    function () { check(label + " (did not reject)", false); },
+    function (e) { check(label, (e && e.code || "").indexOf(codeMatch) !== -1); }
+  );
+}
+
+function testSurface() {
+  check("create is fn",         typeof b.agent.saga.create === "function");
+  check("AgentSagaError",       typeof b.agent.saga.AgentSagaError === "function");
+  check("guards.config",        b.agent.saga.guards.config === b.guardSagaConfig);
+  var e = new b.agent.saga.AgentSagaError("agent-saga/test", "t");
+  check("error carries code",   e.code === "agent-saga/test");
+}
+
+async function testHappyPath() {
+  var saga = b.agent.saga.create({
+    name: "test.happy",
+    steps: [
+      { name: "step1", run: async function (_ctx, s) { s.a = 1; } },
+      { name: "step2", run: async function (_ctx, s) { s.b = 2; } },
+      { name: "step3", run: async function (_ctx, s) { s.c = 3; } },
+    ],
+  });
+  var r = await saga.run({}, {});
+  check("happy: completed",       r.status === "completed");
+  check("happy: state.a",          r.state.a === 1);
+  check("happy: state.c",          r.state.c === 3);
+}
+
+async function testCompensationCascade() {
+  var compensated = [];
+  var saga = b.agent.saga.create({
+    name: "test.compensation",
+    steps: [
+      {
+        name: "step1",
+        run:        async function (_ctx, s) { s.step1 = true; },
+        compensate: async function (_ctx, _s) { compensated.push("step1"); },
+      },
+      {
+        name: "step2",
+        run:        async function (_ctx, s) { s.step2 = true; },
+        compensate: async function (_ctx, _s) { compensated.push("step2"); },
+      },
+      {
+        name: "step3-fails",
+        run:        async function (_ctx, _s) { throw new Error("step3 boom"); },
+        compensate: async function (_ctx, _s) { compensated.push("step3"); },
+      },
+    ],
+  });
+  await expectRejection("saga fails when step throws",
+    saga.run({}, {}), "agent-saga/failed");
+  // Compensations run in REVERSE order over completed steps (step1+step2),
+  // skipping the failing step (step3 hadn't completed when it threw).
+  check("compensation: step2 first (reverse order)", compensated[0] === "step2");
+  check("compensation: step1 second",                compensated[1] === "step1");
+  check("compensation: failing step not compensated", compensated.indexOf("step3") === -1);
+}
+
+async function testNoCompensationForUncompletedSteps() {
+  var compensated = [];
+  var saga = b.agent.saga.create({
+    name: "test.no-comp-uncompleted",
+    steps: [
+      {
+        name: "step1-fails",
+        run:        async function (_ctx, _s) { throw new Error("immediately"); },
+        compensate: async function (_ctx, _s) { compensated.push("step1"); },
+      },
+      {
+        name: "step2",
+        run:        async function (_ctx, _s) { /* never reached */ },
+        compensate: async function (_ctx, _s) { compensated.push("step2"); },
+      },
+    ],
+  });
+  await expectRejection("first step fail aborts",
+    saga.run({}, {}), "agent-saga/failed");
+  check("no comp run for any step (first failed before completion)",
+    compensated.length === 0);
+}
+
+async function testNoCompensateOptional() {
+  var saga = b.agent.saga.create({
+    name: "test.no-compensate",
+    steps: [
+      // No compensate function — that's allowed.
+      { name: "pure-step", run: async function (_ctx, s) { s.x = 1; } },
+      // This step has compensate.
+      {
+        name: "step-with-comp",
+        run:        async function (_ctx, _s) { throw new Error("fail"); },
+        compensate: async function (_ctx, _s) { /* won't fire — pure-step had no compensate */ },
+      },
+    ],
+  });
+  await expectRejection("fails as expected",
+    saga.run({}, {}), "agent-saga/failed");
+  // The pure-step had no compensate so nothing fires; the failing step
+  // never completed. No compensation cascade.
+  check("no compensate is OK on completed steps", true);
+}
+
+async function testStateCarriesThroughSteps() {
+  var saga = b.agent.saga.create({
+    name: "test.state-flow",
+    steps: [
+      { name: "init",   run: async function (_ctx, s) { s.counter = 0; } },
+      { name: "inc",    run: async function (_ctx, s) { s.counter += 1; } },
+      { name: "double", run: async function (_ctx, s) { s.counter *= 2; } },
+    ],
+  });
+  var r = await saga.run({}, {});
+  check("state flows through steps", r.state.counter === 2);
+}
+
+async function testCtxPassedToSteps() {
+  var saga = b.agent.saga.create({
+    name: "test.ctx",
+    steps: [
+      { name: "use-ctx", run: async function (ctx, s) { s.fromCtx = ctx.value; } },
+    ],
+  });
+  var r = await saga.run({ value: "hello" }, {});
+  check("ctx passed through", r.state.fromCtx === "hello");
+}
+
+async function testCompensationFailureAudit() {
+  // Compensation that throws halts further compensations + emits
+  // critical audit + error message references it.
+  var saga = b.agent.saga.create({
+    name: "test.comp-fails",
+    steps: [
+      {
+        name: "step1",
+        run:        async function (_ctx, _s) { /* ok */ },
+        compensate: async function (_ctx, _s) { /* would be called second */ },
+      },
+      {
+        name: "step2",
+        run:        async function (_ctx, _s) { /* ok */ },
+        compensate: async function (_ctx, _s) { throw new Error("comp-boom"); },
+      },
+      {
+        name: "step3",
+        run:        async function (_ctx, _s) { throw new Error("step3 fails"); },
+      },
+    ],
+  });
+  var threw = null;
+  try { await saga.run({}, {}); } catch (e) { threw = e; }
+  check("saga fails with comp-failure indicator",
+    threw && threw.code === "agent-saga/failed" &&
+    threw.message.indexOf("compensation") >= 0);
+}
+
+async function testRefusesBadConfig() {
+  var threw = null;
+  try { b.agent.saga.create({ name: "x", steps: [] }); } catch (e) { threw = e; }
+  check("create refuses empty steps",
+    threw && (threw.code || "").indexOf("saga-config/no-steps") !== -1);
+}
+
+async function testErrorCauseAttached() {
+  // SUBSTRATE-15 — failed-step error attaches cause:stepErr so
+  // operator stack-trace tooling walks the chain.
+  var stepErr = new Error("downstream-failed");
+  stepErr.code = "downstream/timeout";
+  var saga = b.agent.saga.create({
+    name: "test.cause",
+    steps: [
+      { name: "ok",   run: async function (_c, s) { s.x = 1; } },
+      { name: "fail", run: async function () { throw stepErr; } },
+    ],
+  });
+  var threw = null;
+  try { await saga.run({}, {}); } catch (e) { threw = e; }
+  check("SUBSTRATE-15: cause attached", threw && threw.cause === stepErr);
+  check("SUBSTRATE-15: failedStep set",
+    threw && threw.failedStep === "fail");
+}
+
+async function testFailedCompStepNameCorrect() {
+  // BUG-5 — compensation error names the COMPENSATION that threw,
+  // not the last-completed step.
+  var saga = b.agent.saga.create({
+    name: "test.bug5",
+    steps: [
+      { name: "s1", run: async function () {},
+        compensate: async function () { /* fires after s3 + s2 comp */ } },
+      { name: "s2", run: async function () {},
+        compensate: async function () { throw new Error("s2-comp-failed"); } },
+      { name: "s3", run: async function () {},
+        compensate: async function () { /* fires first in reverse */ } },
+      { name: "step-fails", run: async function () { throw new Error("step-fails"); } },
+    ],
+  });
+  var threw = null;
+  try { await saga.run({}, {}); } catch (e) { threw = e; }
+  check("BUG-5: failedCompStepName matches the failing comp",
+    threw && threw.failedCompStepName === "s2");
+  // The prior shape would have named "s3" (last-completed step before
+  // the failed-comp); detector confirms we name "s2".
+}
+
+async function testSagaStatePersistedAcrossRun() {
+  // SUBSTRATE-7 — stateStore.saveStep fires after every completed
+  // step; on a mid-saga crash, resume picks up where it left off.
+  var saved = [];
+  var stateStore = {
+    saveStep: async function (chk) { saved.push(chk); },
+    loadResumePoint: async function (sagaId) {
+      // Pretend the saga crashed after step 1; resume from index 1.
+      var last = saved.filter(function (s) { return s.sagaId === sagaId; }).pop();
+      return last ? { stepIndex: last.nextIndex, state: last.state } : null;
+    },
+  };
+  var executed = [];
+  var saga = b.agent.saga.create({
+    name: "test.persist",
+    stateStore: stateStore,
+    steps: [
+      { name: "s1", run: async function (_c, s) { executed.push("s1"); s.s1 = 1; } },
+      { name: "s2", run: async function (_c, s) { executed.push("s2"); s.s2 = 2; } },
+      { name: "s3", run: async function (_c, s) { executed.push("s3"); s.s3 = 3; } },
+    ],
+  });
+  // Initial run completes fully.
+  var r = await saga.run({}, {}, { sagaId: "saga-A" });
+  check("SUBSTRATE-7: saga completed", r.status === "completed");
+  check("SUBSTRATE-7: 3 saveStep calls", saved.length === 3);
+  // Now simulate a crash partway through a DIFFERENT saga + resume.
+  var saga2 = b.agent.saga.create({
+    name: "test.persist",
+    stateStore: stateStore,
+    steps: [
+      { name: "s1", run: async function (_c, s) { s.s1 = "first-attempt"; } },
+      { name: "s2", run: async function (_c, s) { s.s2 = "first-attempt"; } },
+      { name: "s3", run: async function (_c, s) { s.s3 = "first-attempt"; } },
+    ],
+  });
+  // Pre-populate saved checkpoints for "saga-B" after s1.
+  saved.push({ sagaId: "saga-B", nextIndex: 1, stepName: "s1", state: { s1: "from-crash" } });
+  executed.length = 0;
+  var r2 = await saga2.resume("saga-B", {}, {});
+  check("SUBSTRATE-7: resume completed", r2.status === "completed");
+  check("SUBSTRATE-7: resume state preserved", r2.state.s1 === "from-crash");
+  check("SUBSTRATE-7: resume skipped s1 (already checkpointed)",
+    r2.state.s1 === "from-crash");
+}
+
+async function run() {
+  testSurface();
+  await testHappyPath();
+  await testCompensationCascade();
+  await testNoCompensationForUncompletedSteps();
+  await testNoCompensateOptional();
+  await testStateCarriesThroughSteps();
+  await testCtxPassedToSteps();
+  await testCompensationFailureAudit();
+  await testErrorCauseAttached();
+  await testFailedCompStepNameCorrect();
+  await testSagaStatePersistedAcrossRun();
+  await testRefusesBadConfig();
+}
+
+module.exports = { run: run };
+if (require.main === module) {
+  run().then(function () { console.log("OK"); })
+       .catch(function (e) { console.error(e); process.exit(1); });
+}

package/lib/vendor/blamejs/test/layer-0-primitives/agent-snapshot.test.js

@@ -0,0 +1,322 @@
+"use strict";
+
+var helpers = require("../helpers");
+var b       = helpers.b;
+var check   = helpers.check;
+
+function _fakeOrch(health) {
+  return {
+    health: function () { return Promise.resolve(health || { agents: [], elections: [], consumers: [], streams: 0, draining: false, overall: "ok" }); },
+  };
+}
+
+function _fakeBackend() {
+  var map = new Map();
+  return {
+    put:    function (k, v) { map.set(k, v); return Promise.resolve(); },
+    get:    function (k)    { return Promise.resolve(map.get(k) || null); },
+    delete: function (k)    { map.delete(k); return Promise.resolve(); },
+    list:   function ()     {
+      var out = [];
+      map.forEach(function (v) { out.push(v); });
+      return Promise.resolve(out);
+    },
+    _size: function () { return map.size; },
+  };
+}
+
+// Deterministic fake signer + sealer for the per-test snapshot path.
+// Production wires b.audit-sign + b.vault.aad; tests use the fakes so
+// they don't need the full audit-sign passphrase boot.
+function _fakeSigner() {
+  var nodeCrypto = require("node:crypto");
+  var key = Buffer.alloc(32, 0x42);                                                                     // allow:raw-byte-literal — test fake key fill byte
+  return {
+    sign: function (bytes) { return nodeCrypto.createHmac("sha3-512", key).update(bytes).digest(); },
+    verify: function (bytes, sig) {
+      var expected = nodeCrypto.createHmac("sha3-512", key).update(bytes).digest();
+      if (expected.length !== sig.length) return false;
+      try { return nodeCrypto.timingSafeEqual(expected, sig); } catch (_e) { return false; }
+    },
+    getPublicKey: function () { return null; },
+  };
+}
+
+function _fakeSealer() {
+  var nodeCrypto = require("node:crypto");
+  var key = Buffer.alloc(32, 0x55);                                                                     // allow:raw-byte-literal — test fake key fill byte
+  function _aadStr(aad) {
+    var keys = Object.keys(aad).sort();
+    return keys.map(function (k) { return k + "=" + aad[k]; }).join("|");
+  }
+  return {
+    seal: function (plaintext, aad) {
+      var aadBuf = Buffer.from(_aadStr(aad), "utf8");
+      var iv = Buffer.alloc(16, 0);                                                                     // allow:raw-byte-literal — deterministic test IV
+      var c = nodeCrypto.createCipheriv("aes-256-gcm", key, iv, { authTagLength: 16 });                 // allow:raw-byte-literal — test-only AES-GCM (production uses ML-KEM + XChaCha20)
+      c.setAAD(aadBuf);
+      var ct = Buffer.concat([c.update(Buffer.from(plaintext, "utf8")), c.final()]);
+      var tag = c.getAuthTag();
+      return Buffer.concat([tag, ct]).toString("base64");
+    },
+    unseal: function (value, aad) {
+      var aadBuf = Buffer.from(_aadStr(aad), "utf8");
+      var raw = Buffer.from(value, "base64");
+      var tag = raw.subarray(0, 16);                                                                    // allow:raw-byte-literal — AES-GCM tag length
+      var ct  = raw.subarray(16);                                                                       // allow:raw-byte-literal — AES-GCM tag length offset
+      var iv = Buffer.alloc(16, 0);                                                                     // allow:raw-byte-literal — deterministic test IV
+      var d = nodeCrypto.createDecipheriv("aes-256-gcm", key, iv, { authTagLength: 16 });               // allow:raw-byte-literal — test-only AES-GCM
+      d.setAAD(aadBuf);
+      d.setAuthTag(tag);
+      return Buffer.concat([d.update(ct), d.final()]).toString("utf8");
+    },
+  };
+}
+
+function _signedSnapshot(opts) {
+  opts = opts || {};
+  return b.agent.snapshot.create({
+    orchestrator:    opts.orchestrator || _fakeOrch(),
+    backend:         opts.backend || _fakeBackend(),
+    signer:          opts.signer || _fakeSigner(),
+    sealer:          opts.sealer || _fakeSealer(),
+    allowPlaintext:  opts.allowPlaintext === true,
+    restoreHandlers: opts.restoreHandlers || null,
+  });
+}
+
+function expectRejection(label, p, codeMatch) {
+  return p.then(
+    function () { check(label + " (did not reject)", false); },
+    function (e) { check(label, (e && e.code || "").indexOf(codeMatch) !== -1); }
+  );
+}
+
+function testSurface() {
+  check("create is fn",         typeof b.agent.snapshot.create === "function");
+  check("SCHEMA_VERSION = 1",   b.agent.snapshot.SCHEMA_VERSION === 1);
+  check("AgentSnapshotError",   typeof b.agent.snapshot.AgentSnapshotError === "function");
+  var e = new b.agent.snapshot.AgentSnapshotError("agent-snapshot/test", "t");
+  check("error carries code",   e.code === "agent-snapshot/test");
+}
+
+async function testCreateRequiresOrchestrator() {
+  var threw = null;
+  try { b.agent.snapshot.create({ backend: _fakeBackend() }); } catch (e) { threw = e; }
+  check("create refuses missing orchestrator",
+    threw && (threw.code || "").indexOf("agent-snapshot/bad-orchestrator") !== -1);
+}
+
+async function testCreateRequiresBackend() {
+  var threw = null;
+  try { b.agent.snapshot.create({ orchestrator: _fakeOrch() }); } catch (e) { threw = e; }
+  check("create refuses missing backend",
+    threw && (threw.code || "").indexOf("agent-snapshot/bad-backend") !== -1);
+}
+
+async function testTakeAndPersist() {
+  var snapshot = _signedSnapshot();
+  var snap = await snapshot.takeSnapshot({});
+  check("takeSnapshot: snapshotId present",
+    typeof snap.snapshotId === "string" && snap.snapshotId.indexOf("snap-") === 0);
+  check("takeSnapshot: schemaVersion = 1", snap.schemaVersion === 1);
+  check("takeSnapshot: takenAt is number", typeof snap.takenAt === "number");
+  var r = await snapshot.persist(snap);
+  check("persist: returns snapshotId", r.snapshotId === snap.snapshotId);
+  check("persist: sig populated", typeof snap.sig === "string" && snap.sig.length > 0);
+}
+
+async function testLoadLatest() {
+  var snapshot = _signedSnapshot();
+  var miss = await snapshot.loadLatest();
+  check("loadLatest: empty backend returns null", miss === null);
+  var s1 = await snapshot.takeSnapshot({});
+  await snapshot.persist(s1);
+  // s2.takenAt must differ from s1.takenAt for loadLatest's most-recent
+  // ordering; wait until the wall clock has advanced past s1.takenAt.
+  await helpers.waitUntil(function () {
+    return Date.now() > s1.takenAt;
+  }, { label: "agent-snapshot: clock advanced past s1.takenAt before s2" });
+  var s2 = await snapshot.takeSnapshot({});
+  await snapshot.persist(s2);
+  var loaded = await snapshot.loadLatest();
+  check("loadLatest: returns most recent",
+    loaded && loaded.snapshotId === s2.snapshotId && loaded.takenAt >= s1.takenAt);
+}
+
+async function testLoadById() {
+  var snapshot = _signedSnapshot();
+  var s = await snapshot.takeSnapshot({});
+  await snapshot.persist(s);
+  var hit = await snapshot.loadById(s.snapshotId);
+  check("loadById: returns snapshot", hit.snapshotId === s.snapshotId);
+  var miss = await snapshot.loadById("nope");
+  check("loadById: miss returns null", miss === null);
+}
+
+async function testRestoreTopologyChange() {
+  // Snapshot from a 3-consumer cluster; restore into a 5-consumer cluster.
+  var snapHealth = { agents: [], elections: [], consumers: [{ topic: "t.0" }, { topic: "t.1" }, { topic: "t.2" }], streams: 0, draining: false, overall: "ok" };
+  var restoreHealth = { agents: [], elections: [], consumers: [{ topic: "t.0" }, { topic: "t.1" }, { topic: "t.2" }, { topic: "t.3" }, { topic: "t.4" }], streams: 0, draining: false, overall: "ok" };
+
+  // Take snapshot using the 3-consumer orchestrator.
+  var snap1 = _signedSnapshot({ orchestrator: _fakeOrch(snapHealth) });
+  var snap = await snap1.takeSnapshot({});
+
+  // Restore using the 5-consumer orchestrator.
+  var snap2 = _signedSnapshot({ orchestrator: _fakeOrch(restoreHealth) });
+  var r = await snap2.restore(snap, {});
+  check("restore: topologyChanged detected",  r.topologyChanged === true);
+  check("restore: snapshotId echoed",          r.snapshotId === snap.snapshotId);
+}
+
+async function testRefuseOnTopologyChange() {
+  var snapHealth = { agents: [], elections: [], consumers: [{ topic: "t.0" }, { topic: "t.1" }], streams: 0, draining: false, overall: "ok" };
+  var restoreHealth = { agents: [], elections: [], consumers: [{ topic: "t.0" }], streams: 0, draining: false, overall: "ok" };
+  var s1 = _signedSnapshot({ orchestrator: _fakeOrch(snapHealth) });
+  var snap = await s1.takeSnapshot({});
+  var s2 = _signedSnapshot({ orchestrator: _fakeOrch(restoreHealth) });
+  await expectRejection("refuseOnTopologyChange refuses",
+    s2.restore(snap, { refuseOnTopologyChange: true }),
+    "agent-snapshot/topology-changed");
+}
+
+async function testSchemaVersionMismatch() {
+  var snapshot = _signedSnapshot();
+  var snap = await snapshot.takeSnapshot({});
+  snap.schemaVersion = 999;
+  await expectRejection("refuses schema-version mismatch",
+    snapshot.restore(snap, {}),
+    "agent-snapshot/schema-version-mismatch");
+  // Operator opt-in works
+  var r = await snapshot.restore(snap, { allowSchemaVersionMismatch: true });
+  check("schema-version opt-in OK", r.snapshotId === snap.snapshotId);
+}
+
+async function testList() {
+  var snapshot = _signedSnapshot();
+  await snapshot.persist(await snapshot.takeSnapshot({}));
+  await snapshot.persist(await snapshot.takeSnapshot({}));
+  var list = await snapshot.list({});
+  check("list: 2 entries", list.length === 2);
+}
+
+async function testGc() {
+  var backend = _fakeBackend();
+  var snapshot = _signedSnapshot({ backend: backend });
+  var snap = await snapshot.takeSnapshot({});
+  await snapshot.persist(snap);
+  // gc({olderThanMs: 0}) considers anything strictly older than `now`
+  // as fair game; wait until the clock has surpassed the snapshot's
+  // takenAt before invoking gc.
+  await helpers.waitUntil(function () {
+    return Date.now() > snap.takenAt;
+  }, { label: "agent-snapshot.gc: clock past snap.takenAt for olderThan filter" });
+  var r = await snapshot.gc({ olderThanMs: 0 });
+  check("gc: 1 purged", r.purged === 1);
+  check("gc: backend empty", backend._size() === 0);
+}
+
+async function testSignerNotWiredRefused() {
+  // SUBSTRATE-1 — persist without signer/sealer wired refuses by default.
+  // (vault is not initialized here; auditSign also not initialized.)
+  var snapshot = b.agent.snapshot.create({
+    orchestrator: _fakeOrch(),
+    backend:      _fakeBackend(),
+  });
+  var snap = await snapshot.takeSnapshot({});
+  await expectRejection("persist without signer refuses",
+    snapshot.persist(snap),
+    "agent-snapshot/signer-not-wired");
+}
+
+async function testTamperedEnvelopeRefused() {
+  // SUBSTRATE-1 — sealed+signed envelope rejects on signature tamper.
+  var backend = _fakeBackend();
+  var snap1 = _signedSnapshot({ backend: backend });
+  var s = await snap1.takeSnapshot({});
+  await snap1.persist(s);
+  // Tamper: re-write the wrapper's sealed value to a different
+  // envelope's bytes. We swap two snapshotIds' sealed payloads.
+  var s2 = await snap1.takeSnapshot({});
+  await snap1.persist(s2);
+  var raw1 = await backend.get(s.snapshotId);
+  var raw2 = await backend.get(s2.snapshotId);
+  // Cross-paste s2's sealed body into s1's wrapper. AAD pins
+  // snapshotId so unseal MUST fail.
+  var tampered = Object.assign({}, raw1, { sealed: raw2.sealed });
+  await backend.put(s.snapshotId, tampered);
+  await expectRejection("loadById refuses tampered envelope",
+    snap1.loadById(s.snapshotId),
+    "agent-snapshot/unseal-failed");
+}
+
+async function testUnsignedEnvelopeRefused() {
+  // SUBSTRATE-1 — envelope with sig stripped is refused.
+  var backend = _fakeBackend();
+  var snap1 = _signedSnapshot({ backend: backend });
+  var s = await snap1.takeSnapshot({});
+  await snap1.persist(s);
+  // Replace stored row with a plaintext envelope missing sig — simulates
+  // an attacker who wrote bytes directly to the backend.
+  await backend.put(s.snapshotId, Object.assign({}, s, { sig: null }));
+  await expectRejection("loadById refuses unsigned envelope",
+    snap1.loadById(s.snapshotId),
+    "agent-snapshot/unsigned");
+}
+
+async function testRestoreHandlersInvoked() {
+  // SUBSTRATE-18 — restoreHandlers run end-to-end with audited counts.
+  var invocations = [];
+  var handlers = {
+    orchestratorState: function (payload) { invocations.push("orchestratorState"); return 1; },
+    idempotencyCache:  function (payload) { invocations.push("idempotencyCache");  return 2; },
+    sagas:             function (payload) { invocations.push("sagas");             return payload.length; },
+    streams:           function (payload) { invocations.push("streams");           return payload.length; },
+  };
+  var snapshot = _signedSnapshot({ restoreHandlers: handlers });
+  var snap = await snapshot.takeSnapshot({
+    sagas:   [{ id: "s1" }, { id: "s2" }],
+    streams: [{ id: "st1" }],
+    idempotencyCache: { hot: 1 },
+  });
+  var r = await snapshot.restore(snap, {});
+  check("restore invoked orchestratorState handler", invocations.indexOf("orchestratorState") !== -1);
+  check("restore invoked sagas handler", invocations.indexOf("sagas") !== -1);
+  check("restore returned sagas count", r.restored.sagas === 2);
+  check("restore returned streams count", r.restored.streams === 1);
+}
+
+async function testRestoreRequireHandlersRefuses() {
+  // SUBSTRATE-18 — requireHandlers refuses silent no-op.
+  var snapshot = _signedSnapshot();
+  var snap = await snapshot.takeSnapshot({ sagas: [{ id: "s1" }] });
+  await expectRejection("restore requires handlers when in-flight",
+    snapshot.restore(snap, { requireHandlers: true }),
+    "agent-snapshot/no-restore-handlers");
+}
+
+async function run() {
+  testSurface();
+  await testCreateRequiresOrchestrator();
+  await testCreateRequiresBackend();
+  await testSignerNotWiredRefused();
+  await testTakeAndPersist();
+  await testLoadLatest();
+  await testLoadById();
+  await testTamperedEnvelopeRefused();
+  await testUnsignedEnvelopeRefused();
+  await testRestoreTopologyChange();
+  await testRefuseOnTopologyChange();
+  await testSchemaVersionMismatch();
+  await testList();
+  await testGc();
+  await testRestoreHandlersInvoked();
+  await testRestoreRequireHandlersRefuses();
+}
+
+module.exports = { run: run };
+if (require.main === module) {
+  run().then(function () { console.log("OK"); })
+       .catch(function (e) { console.error(e); process.exit(1); });
+}