@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/agent-posture-chain.js

@@ -0,0 +1,366 @@
+"use strict";
+/**
+ * @module     b.agent.postureChain
+ * @nav        Agent
+ * @title      Agent Posture Chain
+ * @order      80
+ *
+ * @intro
+ *   Set-based compliance posture propagated across every agent
+ *   boundary (sub-agent delegation, queue envelopes, event-bus
+ *   payloads, saga steps). The hard rule: **target's posture set MUST
+ *   be a SUPERSET of source's posture set.** A "downgrade" (target
+ *   missing a regime the source requires) is refused at the boundary.
+ *
+ *   Compliance regimes (HIPAA / PCI-DSS / GDPR / SOC2) protect
+ *   DIFFERENT regulated-data classes — they're orthogonal, not a
+ *   linear lattice. A clinic that processes payment cards operates
+ *   under BOTH HIPAA + PCI; an EU clinic adds GDPR; an aggregator
+ *   may add SOC2. Set semantics match how real-world regulations
+ *   actually overlap.
+ *
+ *   ```js
+ *   var chain = b.agent.postureChain.create({});
+ *
+ *   var sourceSet = ["hipaa", "pci-dss"];
+ *   var targetSet = ["pci-dss"];           // missing hipaa
+ *
+ *   chain.isSubset(targetSet, sourceSet);  // false — target lacks hipaa
+ *   chain.canDelegate(sourceSet, targetSet, "mail.fetch");
+ *   // → false; agent.posture-chain.canDelegate-denied audit emit
+ *   ```
+ *
+ *   ## Per-module declaration
+ *
+ *   Each module declares its applicable regimes via a static
+ *   `POSTURES` export OR an `@compliance` JSDoc tag. The agent
+ *   primitive's posture SET = union of all composed modules' declared
+ *   regimes (operator can narrow at composition time).
+ *
+ *   ## Hop trail
+ *
+ *   Every cross-boundary envelope carries `{ postureSet, chainTrail,
+ *   enteredAt, hopCount }`. Hop count caps at default 16 — defends
+ *   infinite recursion across agent delegation. `appendHop` extends
+ *   the trail when an envelope crosses a new boundary.
+ *
+ * @card
+ *   Set-based compliance posture propagated across every boundary.
+ *   target.set ⊇ source.set required; downgrade refused. Hop-trail
+ *   tracking for audit + debugging.
+ */
+
+var lazyRequire             = require("./lazy-require");
+var nodeCrypto              = require("node:crypto");
+var { defineClass }         = require("./framework-error");
+var guardPostureChain       = require("./guard-posture-chain");
+var agentAudit              = require("./agent-audit");
+var safeJson                = require("./safe-json");
+var bCrypto                 = require("./crypto");
+
+var audit                   = lazyRequire(function () { return require("./audit"); });
+var vault                   = lazyRequire(function () { return require("./vault"); });
+
+var AgentPostureChainError = defineClass("AgentPostureChainError", { alwaysPermanent: true });
+
+var BUILTIN_REGIMES = Object.freeze(["hipaa", "pci-dss", "gdpr", "soc2"]);
+
+// SUBSTRATE-10 — envelope MAC vocabulary. Cross-process envelope
+// integrity: an attacker with queue / event-bus write access who
+// strips postureSet to [] and re-sends a saga / sub-agent envelope
+// can bypass the downgrade refusal in _validate (which only checks
+// SHAPE, not authenticity). Defense is a keyed MAC over the canonical
+// envelope bytes, computed at appendHop and verified at validate.
+var ENVELOPE_MAC_LABEL = "blamejs.agent.postureChain/v1";
+var ENVELOPE_MAC_KEY_BYTES = 32;                                                                        // allow:raw-byte-literal — HMAC-SHA3-512 keyed bytes
+// SUBSTRATE-21 — hop count cap defends infinite recursion across
+// agent delegation. 16 is the spec default; operators can lower via
+// opts.maxHopCount but never raise (audit fan-out without a cap is a
+// DoS class).
+var DEFAULT_MAX_HOP_COUNT = 16;                                                                         // allow:raw-byte-literal — hop count cap
+var _macKeyCache = null;                                                                                // memoized per-vault-master key
+
+function _resolveMacKey() {
+  // Lazy derivation keyed off the vault master. Operator rotating
+  // vault keys invalidates every in-flight MAC — desired property.
+  // Memoization is process-local; if vault rotates within the same
+  // process the operator restarts (vault rotation already implies it).
+  if (_macKeyCache) return _macKeyCache;
+  var v;
+  try { v = vault(); } catch (_e) { v = null; }
+  if (!v || typeof v.getKeysJson !== "function") {
+    throw new AgentPostureChainError("agent-posture-chain/vault-not-initialized",
+      "envelope MAC: vault must be initialized before posture-chain envelopes can be authenticated " +
+      "(operator wires b.vault.init() at boot)");
+  }
+  var keysJson;
+  try { keysJson = v.getKeysJson(); }
+  catch (e) {
+    throw new AgentPostureChainError("agent-posture-chain/vault-not-initialized",
+      "envelope MAC: vault.getKeysJson threw — " + (e && e.message ? e.message : String(e)));
+  }
+  var rootBytes = Buffer.from(bCrypto.sha3Hash(keysJson), "hex");
+  var input = Buffer.concat([
+    Buffer.from(ENVELOPE_MAC_LABEL, "utf8"),
+    Buffer.from([0x00]),
+    rootBytes,
+  ]);
+  _macKeyCache = bCrypto.kdf(input, ENVELOPE_MAC_KEY_BYTES);
+  return _macKeyCache;
+}
+
+function _envelopeMacBytes(envelope) {
+  // Sign every field that downstream consumers verify off the wire,
+  // except the `_mac` field itself. SUBSTRATE-21 — also includes
+  // hopCount + chainTrail so a hostile rewriter can't roll back the
+  // trail to evade the cap.
+  var payload = {
+    postureSet: Array.isArray(envelope.postureSet) ? envelope.postureSet.slice().sort() : [],
+    chainTrail: Array.isArray(envelope.chainTrail) ? envelope.chainTrail.slice() : [],
+    enteredAt:  Array.isArray(envelope.enteredAt)  ? envelope.enteredAt.slice()  : [],
+    hopCount:   typeof envelope.hopCount === "number" ? envelope.hopCount : 0,
+  };
+  return Buffer.from(safeJson.canonical(payload), "utf8");
+}
+
+function _signEnvelope(envelope) {
+  var key = _resolveMacKey();
+  var mac = nodeCrypto.createHmac("sha3-512", key).update(_envelopeMacBytes(envelope)).digest();
+  return mac.toString("base64");
+}
+
+function _verifyEnvelopeMac(envelope) {
+  if (typeof envelope._mac !== "string" || envelope._mac.length === 0) return false;
+  var expected = _signEnvelope(envelope);
+  return bCrypto.timingSafeEqual(envelope._mac, expected);
+}
+
+/**
+ * @primitive b.agent.postureChain.create
+ * @signature b.agent.postureChain.create(opts)
+ * @since     0.9.28
+ * @status    stable
+ * @related   b.agent.tenant.create, b.agent.eventBus.create
+ *
+ * Create the posture-chain facade. Returns an instance with
+ * `isSubset` / `union` / `canDelegate` / `declareRegime` / `validate`
+ * / `appendHop`.
+ *
+ * @opts
+ *   audit:  b.audit namespace,   // optional
+ *
+ * @example
+ *   var chain = b.agent.postureChain.create({});
+ *   chain.isSubset(["pci-dss"], ["hipaa", "pci-dss"]); // → false
+ */
+function create(opts) {
+  opts = opts || {};
+  var auditImpl = opts.audit || audit();
+  var declaredRegimes = Object.create(null);
+  for (var i = 0; i < BUILTIN_REGIMES.length; i += 1) declaredRegimes[BUILTIN_REGIMES[i]] = true;
+  // allow:numeric-opt-Infinity — operator opt clamped to [1, DEFAULT_MAX_HOP_COUNT]; bad input falls back to default
+  var maxHopCount = typeof opts.maxHopCount === "number" && opts.maxHopCount > 0 &&
+                    opts.maxHopCount <= DEFAULT_MAX_HOP_COUNT
+                      ? Math.floor(opts.maxHopCount)
+                      : DEFAULT_MAX_HOP_COUNT;
+  // SUBSTRATE-10 escape hatch — only operator-confirmed single-process
+  // unit tests should opt out of envelope MAC. Production / multi-
+  // process / queue-spanning deployments leave the default on; the
+  // gate audit-emits when bypassed so the posture is visible.
+  var requireMac = opts.requireMac !== false;
+  var ctx = {
+    audit:        auditImpl,
+    maxHopCount:  maxHopCount,
+    requireMac:   requireMac,
+  };
+  return {
+    declareRegime: function (name)                          { return _declareRegime(declaredRegimes, name); },
+    isSubset:      function (targetSet, sourceSet)          { return _isSubset(targetSet, sourceSet); },
+    union:         function ()                              { return _union.apply(null, arguments); },
+    canDelegate:   function (sourceSet, targetSet, method)  { return _canDelegate(sourceSet, targetSet, method, auditImpl); },
+    appendHop:     function (envelope, hopName)             { return _appendHop(ctx, envelope, hopName); },
+    validate:      function (envelope, agentPostureSet)     { return _validate(ctx, envelope, agentPostureSet); },
+    sign:          function (envelope)                      { return _signEnvelope(envelope); },
+    verify:        function (envelope)                      { return _verifyEnvelopeMac(envelope); },
+    REGIMES:       Object.freeze(Object.keys(declaredRegimes)),
+    MAX_HOP_COUNT: maxHopCount,
+    AgentPostureChainError: AgentPostureChainError,
+    _declaredRegimes: declaredRegimes,
+  };
+}
+
+function _declareRegime(declaredRegimes, name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new AgentPostureChainError("agent-posture-chain/bad-regime",
+      "declareRegime: name must be a non-empty string");
+  }
+  if (declaredRegimes[name]) {
+    throw new AgentPostureChainError("agent-posture-chain/duplicate-regime",
+      "declareRegime: '" + name + "' already declared");
+  }
+  declaredRegimes[name] = true;
+}
+
+function _isSubset(targetSet, sourceSet) {
+  if (!Array.isArray(targetSet) || !Array.isArray(sourceSet)) return false;
+  if (sourceSet.length === 0) return true;     // empty source ⊆ any target
+  var targetIdx = Object.create(null);
+  for (var i = 0; i < targetSet.length; i += 1) targetIdx[targetSet[i]] = true;
+  for (var j = 0; j < sourceSet.length; j += 1) {
+    if (!targetIdx[sourceSet[j]]) return false;
+  }
+  return true;
+}
+
+function _union() {
+  var seen = Object.create(null);
+  var out = [];
+  for (var a = 0; a < arguments.length; a += 1) {
+    var set = arguments[a];
+    if (!Array.isArray(set)) continue;
+    for (var i = 0; i < set.length; i += 1) {
+      if (!seen[set[i]]) {
+        seen[set[i]] = true;
+        out.push(set[i]);
+      }
+    }
+  }
+  return out;
+}
+
+function _canDelegate(sourceSet, targetSet, method, auditImpl) {
+  if (_isSubset(targetSet, sourceSet)) return true;
+  agentAudit.safeAudit(auditImpl, "agent.posture_chain.delegate_denied", null, {
+    method: method, sourceSet: sourceSet, targetSet: targetSet,
+    missing: _missing(targetSet, sourceSet),
+  });
+  return false;
+}
+
+function _missing(targetSet, sourceSet) {
+  var idx = Object.create(null);
+  if (Array.isArray(targetSet)) for (var i = 0; i < targetSet.length; i += 1) idx[targetSet[i]] = true;
+  var out = [];
+  if (Array.isArray(sourceSet)) for (var j = 0; j < sourceSet.length; j += 1) {
+    if (!idx[sourceSet[j]]) out.push(sourceSet[j]);
+  }
+  return out;
+}
+
+function _appendHop(ctx, envelope, hopName) {
+  if (!envelope || typeof envelope !== "object") {
+    throw new AgentPostureChainError("agent-posture-chain/bad-envelope",
+      "appendHop: envelope required");
+  }
+  if (typeof hopName !== "string" || hopName.length === 0) {
+    throw new AgentPostureChainError("agent-posture-chain/bad-hop-name",
+      "appendHop: hopName must be a non-empty string");
+  }
+  var trail = Array.isArray(envelope.chainTrail) ? envelope.chainTrail.slice() : [];
+  // SUBSTRATE-21 — cap enforced BEFORE the push so the hop-cap throw
+  // fires consistently regardless of whether the operator inspects
+  // trail.length first. Cap is a hard refusal (no truncation) because
+  // a silently-dropped hop loses audit provenance for the call.
+  if (trail.length >= ctx.maxHopCount) {
+    agentAudit.safeAudit(ctx.audit, "agent.posture_chain.hop_cap_refused", null, {
+      hopName: hopName, hopCount: trail.length, maxHopCount: ctx.maxHopCount,
+      chainTrail: trail,
+    });
+    throw new AgentPostureChainError("agent-posture-chain/hop-cap-exceeded",
+      "appendHop: chain trail has " + trail.length + " hops; cap is " + ctx.maxHopCount +
+      " — refusing to extend (operator delegation cycle?)");
+  }
+  trail.push(hopName);
+  var enteredAt = Array.isArray(envelope.enteredAt) ? envelope.enteredAt.slice() : [];
+  enteredAt.push(Date.now());
+  var newEnvelope = Object.assign({}, envelope, {
+    chainTrail: trail,
+    enteredAt:  enteredAt,
+    hopCount:   trail.length,
+  });
+  guardPostureChain.validate(newEnvelope);
+  // SUBSTRATE-10 — sign at every hop. Verify-side enforces requireMac.
+  // ctx.requireMac=false (operator-confirmed test escape hatch) skips
+  // the sign so a vault-less test path still works.
+  if (ctx.requireMac) {
+    try {
+      newEnvelope._mac = _signEnvelope(newEnvelope);
+    } catch (e) {
+      // Vault not initialized at boot — surface the error to the
+      // operator. Without the MAC the envelope is unauthenticated and
+      // every downstream _validate would refuse it; better to refuse
+      // here with a clear message.
+      throw new AgentPostureChainError("agent-posture-chain/mac-sign-failed",
+        "appendHop: envelope MAC sign failed — " + (e && e.message ? e.message : String(e)) +
+        " — operator wires b.vault.init() before agent-posture-chain.appendHop OR " +
+        "passes create({ requireMac: false }) for vault-less unit tests");
+    }
+  }
+  return newEnvelope;
+}
+
+function _validate(ctx, envelope, agentPostureSet) {
+  guardPostureChain.validate(envelope);
+  // SUBSTRATE-10 — MAC verification BEFORE any field-based decision so
+  // the wire-rewrite attack (postureSet:[] downgrade with valid SHAPE
+  // but no integrity binding) is refused. ctx.requireMac=false skips
+  // verification and emits an audit so the bypass is visible.
+  if (ctx.requireMac) {
+    if (typeof envelope._mac !== "string" || envelope._mac.length === 0) {
+      agentAudit.safeAudit(ctx.audit, "agent.posture_chain.unauthenticated_envelope", null, {
+        chainTrail: envelope.chainTrail, postureSet: envelope.postureSet,
+      });
+      throw new AgentPostureChainError("agent-posture-chain/missing-mac",
+        "validate: envelope is unauthenticated (no _mac field) — refusing under requireMac=true");
+    }
+    if (!_verifyEnvelopeMac(envelope)) {
+      agentAudit.safeAudit(ctx.audit, "agent.posture_chain.mac_verify_failed", null, {
+        chainTrail: envelope.chainTrail, postureSet: envelope.postureSet,
+      });
+      throw new AgentPostureChainError("agent-posture-chain/mac-verify-failed",
+        "validate: envelope MAC verification failed — bytes tampered, " +
+        "chain trail rewritten, or signed under a different vault keypair");
+    }
+  } else {
+    agentAudit.safeAudit(ctx.audit, "agent.posture_chain.mac_skipped", null, {
+      chainTrail: envelope.chainTrail,
+    });
+  }
+  // SUBSTRATE-21 — hop cap also enforced at validate-time. A hostile
+  // envelope might arrive with hopCount > cap if a prior hop's
+  // requireMac was off; refuse here regardless.
+  if (Array.isArray(envelope.chainTrail) && envelope.chainTrail.length > ctx.maxHopCount) {
+    throw new AgentPostureChainError("agent-posture-chain/hop-cap-exceeded",
+      "validate: chain trail length " + envelope.chainTrail.length +
+      " exceeds cap " + ctx.maxHopCount);
+  }
+  // The source (envelope) carries a postureSet; the target (the agent
+  // we're entering) declares its own posture set. Target must be a
+  // superset of source — i.e., the agent covers every regime the
+  // calling context requires.
+  if (Array.isArray(agentPostureSet)) {
+    if (!_isSubset(agentPostureSet, envelope.postureSet)) {
+      var missing = _missing(agentPostureSet, envelope.postureSet);
+      agentAudit.safeAudit(ctx.audit, "agent.posture_chain.downgrade_refused", null, {
+        sourceSet: envelope.postureSet, targetSet: agentPostureSet, missing: missing,
+        chainTrail: envelope.chainTrail,
+      });
+      throw new AgentPostureChainError("agent-posture-chain/downgrade-refused",
+        "validate: agent posture-set " + JSON.stringify(agentPostureSet) +
+        " missing regimes required by envelope: " + JSON.stringify(missing));
+    }
+  }
+  return envelope;
+}
+
+module.exports = {
+  create:                    create,
+  BUILTIN_REGIMES:           BUILTIN_REGIMES,
+  MAX_HOP_COUNT:             DEFAULT_MAX_HOP_COUNT,
+  AgentPostureChainError:    AgentPostureChainError,
+  guards: {
+    chain: guardPostureChain,
+  },
+  // Test-only — flush the memoized MAC key after a vault reset.
+  _resetForTest: function () { _macKeyCache = null; },
+};

package/lib/vendor/blamejs/lib/agent-saga.js

@@ -0,0 +1,321 @@
+"use strict";
+/**
+ * @module     b.agent.saga
+ * @nav        Agent
+ * @title      Agent Saga
+ * @order      75
+ *
+ * @intro
+ *   Multi-step coordination with compensation cascade. When a saga's
+ *   step fails mid-way, the framework fires every previously-completed
+ *   step's `compensate` in reverse order so the operator-side state
+ *   doesn't end up half-written.
+ *
+ *   Substrate for v0.9.34 submission (DKIM-sign → ARC-sign → outbox-
+ *   enqueue → SMTP-deliver → store-move-to-Sent), regulated export,
+ *   journal compaction, every future multi-step write.
+ *
+ *   ```js
+ *   var sendSaga = b.agent.saga.create({
+ *     name:  "mail.send",
+ *     audit: b.audit,
+ *     steps: [
+ *       {
+ *         name: "dkim-sign",
+ *         run:        async function (ctx, state) { state.signed = sign(state.message); },
+ *         compensate: async function (ctx, state) { /* sign is pure, nothing to undo *\/ },
+ *       },
+ *       {
+ *         name: "store-draft",
+ *         run:        async function (ctx, state) { state.draftId = store.append("Drafts", state.signed); },
+ *         compensate: async function (ctx, state) { if (state.draftId) store.delete(state.draftId); },
+ *       },
+ *       {
+ *         name: "smtp-deliver",
+ *         run:        async function (ctx, state) { await smtp.deliver(state.signed); },
+ *         compensate: async function (ctx, state) { /* idempotent: SMTP delivery doesn't have a recall *\/ },
+ *       },
+ *     ],
+ *   });
+ *
+ *   var result = await sendSaga.run({ store, smtp }, { message: bytes });
+ *   ```
+ *
+ *   ## Compensation order
+ *
+ *   If step `i` throws, the framework calls `step[i-1].compensate`,
+ *   `step[i-2].compensate`, ..., `step[0].compensate` in reverse
+ *   order. Each compensate receives the SAME `state` object that
+ *   the corresponding `run` mutated — operator inspects what got
+ *   written and undoes it.
+ *
+ *   Compensations that throw emit `agent.saga.compensation_failed`
+ *   audit at CRITICAL severity and halt further compensations
+ *   (operator alert; manual intervention needed). The saga returns
+ *   `{ status: "failed", failedStep, lastCompensationError }`.
+ *
+ *   ## No saga-level retry
+ *
+ *   Per the substrate playbook decision (operator-confirmed
+ *   2026-05-14): saga's value-add is compensation, not retry. If a
+ *   step needs retry-with-backoff, the operator wraps `step.run`
+ *   with `b.retry` inside the step body. With v0.9.22 idempotency
+ *   available, internal retry inside step.run is side-effect-safe.
+ *
+ * @card
+ *   Multi-step coordination with compensation cascade. Reverse-order
+ *   compensations on step failure. No saga-level retry — step.run
+ *   owns its own retry semantics via b.retry + v0.9.22 idempotency.
+ */
+
+var lazyRequire        = require("./lazy-require");
+var { defineClass }    = require("./framework-error");
+var guardSagaConfig    = require("./guard-saga-config");
+var bCrypto            = require("./crypto");
+var agentAudit         = require("./agent-audit");
+
+var audit              = lazyRequire(function () { return require("./audit"); });
+
+var AgentSagaError = defineClass("AgentSagaError", { alwaysPermanent: true });
+
+var SAGA_ID_RAND_BYTES = 8;                                                                           // allow:raw-byte-literal — saga-id random-suffix byte length
+
+/**
+ * @primitive b.agent.saga.create
+ * @signature b.agent.saga.create(config)
+ * @since     0.9.27
+ * @status    stable
+ * @related   b.agent.idempotency.create, b.outbox.enqueue
+ *
+ * Create a saga definition. Returns an instance with `run(ctx,
+ * initialState, opts) → Promise<finalState>`.
+ *
+ * @opts
+ *   name:    string,                       // required (audit label)
+ *   steps:   Array<{ name, run, compensate? }>,   // required, non-empty
+ *   audit:   b.audit namespace,            // optional
+ *
+ * @example
+ *   var saga = b.agent.saga.create({
+ *     name: "my.workflow",
+ *     steps: [{ name: "step1", run: async (ctx, s) => { s.x = 1; } }],
+ *   });
+ *   var final = await saga.run({}, {});
+ */
+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, 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 _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);
+  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 = [];
+
+  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 = 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: 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,
+      });
+    } catch (stepErr) {
+      // Step failed — compensate in reverse over already-completed steps.
+      agentAudit.safeAudit(auditImpl, "agent.saga.step_failed", opts.actor, {
+        sagaId: sagaId, name: config.name, stepName: step.name, stepIndex: i,
+        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 compEntry = completedSteps[c];
+        var compStep = compEntry.step;
+        if (typeof compStep.compensate !== "function") continue;
+        try {
+          agentAudit.safeAudit(auditImpl, "agent.saga.compensation_started", opts.actor, {
+            sagaId: sagaId, name: config.name, stepName: compStep.name,
+          });
+          await compStep.compensate(ctx, state);
+          agentAudit.safeAudit(auditImpl, "agent.saga.compensation_completed", opts.actor, {
+            sagaId: sagaId, name: config.name, stepName: compStep.name,
+          });
+        } catch (compErr) {
+          // CRITICAL: compensation failed — operator intervention needed.
+          // 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),
+          });
+          break;
+        }
+      }
+      agentAudit.safeAudit(auditImpl, "agent.saga.failed", opts.actor, {
+        sagaId: sagaId, name: config.name, failedStep: step.name,
+        compensationFailed: compensationError !== null,
+        compensationFailedAt: failedCompStepName,
+      });
+      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,
+  });
+  return { status: "completed", sagaId: sagaId, state: state };
+}
+
+module.exports = {
+  create:            create,
+  AgentSagaError:    AgentSagaError,
+  guards: {
+    config: guardSagaConfig,
+  },
+};