@blamejs/core 0.9.24 → 0.9.38

package/lib/agent-posture-chain.js

@@ -0,0 +1,208 @@
+"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 { defineClass }         = require("./framework-error");
+var guardPostureChain       = require("./guard-posture-chain");
+var agentAudit              = require("./agent-audit");
+
+var audit                   = lazyRequire(function () { return require("./audit"); });
+
+var AgentPostureChainError = defineClass("AgentPostureChainError", { alwaysPermanent: true });
+
+var BUILTIN_REGIMES = Object.freeze(["hipaa", "pci-dss", "gdpr", "soc2"]);
+
+/**
+ * @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;
+  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(envelope, hopName); },
+    validate:      function (envelope, agentPostureSet)     { return _validate(envelope, agentPostureSet, auditImpl); },
+    REGIMES:       Object.freeze(Object.keys(declaredRegimes)),
+    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(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() : [];
+  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);
+  return newEnvelope;
+}
+
+function _validate(envelope, agentPostureSet, auditImpl) {
+  guardPostureChain.validate(envelope);
+  // 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(auditImpl, "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,
+  AgentPostureChainError:    AgentPostureChainError,
+  guards: {
+    chain: guardPostureChain,
+  },
+};

package/lib/agent-saga.js

@@ -0,0 +1,191 @@
+"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();
+  return {
+    run:                    function (ctx, initialState, opts) { return _run(config, auditImpl, ctx, initialState, opts || {}); },
+    name:                   config.name,
+    stepCount:              config.steps.length,
+    AgentSagaError:         AgentSagaError,
+  };
+}
+
+async function _run(config, auditImpl, ctx, initialState, opts) {
+  var sagaId = opts.sagaId || "saga-" + bCrypto.generateToken(SAGA_ID_RAND_BYTES);
+  var state  = Object.assign({}, initialState || {});
+  var completedSteps = [];
+
+  agentAudit.safeAudit(auditImpl, "agent.saga.started", opts.actor, {
+    sagaId: sagaId, name: config.name, stepCount: config.steps.length,
+  });
+
+  for (var i = 0; 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);
+      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;
+      for (var c = completedSteps.length - 1; c >= 0; c -= 1) {
+        var compStep = completedSteps[c];
+        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;
+          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,
+      });
+      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))
+                            : ""));
+    }
+  }
+  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,
+  },
+};