@blamejs/core 0.9.23 → 0.9.28

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,
+  },
+};

package/lib/agent-stream.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * @module     b.agent.stream
+ * @nav        Agent
+ * @title      Agent Stream
+ * @order      60
+ *
+ * @intro
+ *   Async-iterable variants for agent methods that yield N rows.
+ *   Operator wraps a cursor-shaped fetcher with `b.agent.stream.create`;
+ *   the resulting object is `AsyncIterable<row>` — built-in
+ *   backpressure (each `yield` blocks until the consumer pulls),
+ *   automatic cursor close via `try`/`finally` on any exit path
+ *   (consumer break, throw, network drop), and drain-marker emit on
+ *   orchestrator drain so clients can resume from `lastSeenCursor`
+ *   against the new agent post-drain.
+ *
+ *   ```js
+ *   var stream = b.agent.stream.create({
+ *     orchestrator: orch,                  // optional — for drain reg
+ *     actor:        { id: "u1" },
+ *     kind:         "search",
+ *     batchSize:    256,
+ *     openCursor:   function (cursorOpts) {
+ *       return store.openSearchCursor(cursorOpts);     // operator
+ *     },
+ *     cursorOpts:   { folder: "INBOX", sinceModseq: 0 },
+ *   });
+ *
+ *   for await (var row of stream) {
+ *     // row delivered as soon as the cursor yields it.
+ *     // Pulling slowly applies backpressure to the store.
+ *     if (someCondition) break;            // cursor.close() fires automatically
+ *   }
+ *   ```
+ *
+ *   ## Drain-marker semantic
+ *
+ *   When orchestrator drain fires, in-flight streams emit ONE final
+ *   `{ _drainMarker: true, lastSeenCursor: <opaque>, reason: "drain" }`
+ *   row and exit cleanly. Clients reconnecting via JMAP-WebSocket /
+ *   IMAP NOTIFY pass `lastSeenCursor` back to resume.
+ *
+ *   ## Cursor contract
+ *
+ *   Operator-supplied cursor:
+ *     `cursor.fetchBatch(batchSize) → { rows, nextCursor, done }`
+ *     `cursor.close() → void | Promise<void>`
+ *
+ *   The framework's `b.mailStore` will gain `openSearchCursor` /
+ *   `openFolderCursor` / `openExportCursor` etc. at later mail-stack
+ *   slices that compose this primitive.
+ *
+ * @card
+ *   Async-iterable variants for agent methods that yield N rows.
+ *   Cursor-backed backpressure; auto-close on exit; drain-marker
+ *   emit so clients resume cleanly post-deploy.
+ */
+
+var lazyRequire       = require("./lazy-require");
+var { defineClass }   = require("./framework-error");
+var guardStreamArgs   = require("./guard-stream-args");
+var agentAudit        = require("./agent-audit");
+
+var audit             = lazyRequire(function () { return require("./audit"); });
+
+var AgentStreamError = defineClass("AgentStreamError", { alwaysPermanent: true });
+
+var DEFAULT_BATCH_SIZE = 256;                                                                          // allow:raw-byte-literal — cursor batch row count, not bytes
+
+/**
+ * @primitive b.agent.stream.create
+ * @signature b.agent.stream.create(opts)
+ * @since     0.9.24
+ * @status    stable
+ * @related   b.agent.orchestrator.create
+ *
+ * Create an async-iterable backed by an operator-supplied cursor.
+ * Returns an object that implements `[Symbol.asyncIterator]` — usable
+ * with `for await (var row of stream)`. Cursor close + audit emit +
+ * orchestrator stream-registry hook are owned by the framework;
+ * operator only supplies the `openCursor` factory + `cursorOpts`.
+ *
+ * @opts
+ *   openCursor:    function(cursorOpts) → cursor,   // required
+ *   cursorOpts:    object,                           // operator-passed
+ *   batchSize:     integer,                           // default 256
+ *   orchestrator:  b.agent.orchestrator,              // optional — for drain reg
+ *   actor:         { id, ... },                       // optional — audit attribution
+ *   kind:          string,                            // "search" / "export" / ...
+ *   audit:         b.audit,                           // optional
+ *
+ * @example
+ *   var stream = b.agent.stream.create({
+ *     openCursor: function (o) { return store.openSearchCursor(o); },
+ *     cursorOpts: { folder: "INBOX" },
+ *   });
+ *   for await (var row of stream) { process(row); }
+ */
+function create(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new AgentStreamError("agent-stream/bad-opts", "create: opts required");
+  }
+  if (typeof opts.openCursor !== "function") {
+    throw new AgentStreamError("agent-stream/bad-open-cursor",
+      "create: opts.openCursor must be a function");
+  }
+  guardStreamArgs.validate({
+    batchSize:  opts.batchSize,
+    kind:       opts.kind,
+    cursorOpts: opts.cursorOpts,
+  });
+  var batchSize = typeof opts.batchSize === "number" ? opts.batchSize : DEFAULT_BATCH_SIZE;
+  var orch      = opts.orchestrator || null;
+  var auditImpl = opts.audit || audit();
+  var actor     = opts.actor || null;
+  var kind      = opts.kind  || "stream";
+
+  return {
+    [Symbol.asyncIterator]: function () {
+      return _makeIterator({
+        openCursor: opts.openCursor,
+        cursorOpts: opts.cursorOpts,
+        batchSize:  batchSize,
+        orchestrator: orch,
+        audit:      auditImpl,
+        actor:      actor,
+        kind:       kind,
+      });
+    },
+  };
+}
+
+function _makeIterator(ctx) {
+  var streamId   = ctx.orchestrator ? ctx.orchestrator.registerStream({ kind: ctx.kind, actor: ctx.actor }) : null;
+  var cursor     = null;
+  var buffer     = [];
+  var done       = false;
+  var closed     = false;
+  var drained    = false;
+  _safeAudit(ctx.audit, "agent.stream.opened", ctx.actor, { kind: ctx.kind, streamId: streamId });
+
+  async function _closeOnce(reason) {
+    if (closed) return;
+    closed = true;
+    if (cursor && typeof cursor.close === "function") {
+      try { await cursor.close(); } catch (_e) { /* best-effort */ }
+    }
+    if (streamId && ctx.orchestrator) {
+      try { ctx.orchestrator.unregisterStream(streamId); } catch (_e) { /* best-effort */ }
+    }
+    _safeAudit(ctx.audit, "agent.stream.closed", ctx.actor, {
+      kind: ctx.kind, streamId: streamId, reason: reason || "exhausted",
+    });
+  }
+
+  return {
+    next: async function () {
+      try {
+        if (buffer.length > 0) {
+          var row = buffer.shift();
+          return { value: row, done: false };
+        }
+        if (done) {
+          if (!closed) await _closeOnce("exhausted");
+          return { value: undefined, done: true };
+        }
+        // Check orchestrator drain BEFORE fetching the next batch.
+        if (ctx.orchestrator && ctx.orchestrator.isDraining && ctx.orchestrator.isDraining()) {
+          if (!drained) {
+            drained = true;
+            var marker = {
+              _drainMarker:   true,
+              lastSeenCursor: cursor && typeof cursor.lastSeenCursor === "function"
+                                ? cursor.lastSeenCursor() : null,
+              reason:         "drain",
+            };
+            _safeAudit(ctx.audit, "agent.stream.drain_marker_emitted", ctx.actor, {
+              kind: ctx.kind, streamId: streamId,
+            });
+            done = true;
+            return { value: marker, done: false };
+          }
+          await _closeOnce("drain");
+          return { value: undefined, done: true };
+        }
+        if (!cursor) {
+          cursor = await ctx.openCursor(ctx.cursorOpts);
+          if (!cursor || typeof cursor.fetchBatch !== "function") {
+            throw new AgentStreamError("agent-stream/bad-cursor",
+              "openCursor returned non-cursor (missing fetchBatch)");
+          }
+        }
+        var batch = await cursor.fetchBatch(ctx.batchSize);
+        if (!batch || typeof batch !== "object") {
+          throw new AgentStreamError("agent-stream/bad-batch",
+            "cursor.fetchBatch returned non-object");
+        }
+        var rows = batch.rows || [];
+        if (batch.done) done = true;
+        if (rows.length === 0) {
+          if (!closed) await _closeOnce("exhausted");
+          return { value: undefined, done: true };
+        }
+        // Push all but the first into the buffer; return the first.
+        for (var i = 1; i < rows.length; i += 1) buffer.push(rows[i]);
+        return { value: rows[0], done: false };
+      } catch (e) {
+        // Any error closes the cursor + emits an audit. Re-throw to
+        // surface upward.
+        await _closeOnce("error");
+        throw e;
+      }
+    },
+    return: async function () {
+      // Consumer's `break` calls this — close the cursor cleanly.
+      await _closeOnce("consumer-break");
+      return { value: undefined, done: true };
+    },
+    throw: async function (err) {
+      await _closeOnce("consumer-throw");
+      throw err;
+    },
+  };
+}
+
+function _safeAudit(auditImpl, action, actor, metadata) {
+  agentAudit.safeAudit(auditImpl, action, actor, metadata);
+}
+
+module.exports = {
+  create:            create,
+  AgentStreamError:  AgentStreamError,
+  guards: {
+    args: guardStreamArgs,
+  },
+};