attenu-guard 0.3.1 → 0.5.0

package/dist/cjs/guard.js

@@ -28,14 +28,96 @@
  * (`spawn`/`spawn_denied`/`kill`) even though the API reads
  * issue/delegate/revoke. That field is a separately-versioned published wire
  * contract that verifiers depend on.
+ *
+ * ## Execution binding (0.9.0, `Guard.issue(agentId, authority, {schemaVersion: 2})` only)
+ *
+ * `schemaVersion: 1` chains (the default — nothing below applies to them) behave EXACTLY as they
+ * did before 0.9.0: no `callId`, no pending tracking, no `NODE_FINALIZED` refusal, `check`'s new
+ * `authorizedParams`/`capture`/`adapter` options throw if supplied. A caller opts in per chain,
+ * once, at `Guard.issue` — schema versions never mix within a chain
+ * (docs/execution-binding spec section 9).
+ *
+ * On a `schemaVersion: 2` chain, `check`'s transition is, in order:
+ *
+ *   1. refuse if the node is already `complete()`d (`ReasonCode.NODE_FINALIZED`);
+ *   2. otherwise evaluate authority/ceilings and update meters (`evaluate` + auto-metering,
+ *      unchanged from schema version 1);
+ *   3. allocate `callId` — 16 bytes from `crypto.randomBytes`, lowercase hex; if that throws, the
+ *      call is denied and NOTHING is appended (`ReasonCode.CALL_ID_UNAVAILABLE`);
+ *   4. commit the entry (append to the audit log — may throw `CommittedAuditError` if persistence
+ *      fails AFTER the in-memory commit; this method attaches `.decision` to that error before it
+ *      propagates, per spec section 1: "carries the committed entry and the decision");
+ *   5. register an allowed call as pending (even across a `CommittedAuditError` — spec: "the
+ *      guard registers an allowed call as pending before raising");
+ *   6. return the `Decision`, which now carries `.callId`.
+ *
+ * `recordOutcome` is the producer API a body-owning wrapper calls once it knows how the call
+ * ended; `complete` refuses (returns a falsy-in-`==` `CompletionResult`) while calls are still
+ * pending; `revoke`/`revokeAgent` snapshot the still-pending callIds onto the `kill` entry as
+ * `pending_at_kill` without clearing them — a late `recordOutcome` after a kill is accepted.
+ *
+ * JavaScript has no analogue of Python's `__bool__`, so unlike the Python library,
+ * `if (guard.complete())` cannot be made to read `false` on refusal — see `CompletionResult`'s
+ * own doc comment in reasons.ts for exactly what IS and is not bridged.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Guard = exports.AuthorityDenied = void 0;
+exports.Guard = exports.DuplicateOutcomeError = exports.AuthorityDenied = void 0;
 const authority_js_1 = require("./authority.js");
 const audit_js_1 = require("./audit.js");
 const chain_js_1 = require("./chain.js");
 const ceilings_js_1 = require("./ceilings.js");
 const reasons_js_1 = require("./reasons.js");
+const paramsMod = __importStar(require("./params.js"));
+const params_js_1 = require("./params.js");
+const version_js_1 = require("./version.js");
+const node_crypto_1 = require("node:crypto");
+/**
+ * Capture modes that promise a terminal observation of the body — the only ones a call should
+ * ever be registered PENDING for. `Capture.PRE_HOOK_ONLY` (the Guard's own default for a bare
+ * v2 `check()`, and any adapter's explicit choice) is honest about NOT observing completion —
+ * nothing will ever call `recordOutcome` for it, so treating it as pending would wedge
+ * `complete()` forever (mirrors the Python D14 fix, guard.py `_TERMINAL_CAPTURES`). The offline
+ * verifier already treats a missing `PRE_HOOK_ONLY` outcome as merely `unobserved`
+ * (evidence.ts); runtime pending-tracking now agrees.
+ */
+const TERMINAL_CAPTURES = new Set([
+    reasons_js_1.Capture.WRAPPER_SYNC,
+    reasons_js_1.Capture.WRAPPER_ASYNC,
+    reasons_js_1.Capture.FRAMEWORK_POST_HOOK,
+]);
 /**
  * Thrown only by `enforce`. Carries the full `Decision`, so a caller can branch
  * on `err.decision.reasons[0].code` instead of parsing a message string.
@@ -49,6 +131,19 @@ class AuthorityDenied extends Error {
     }
 }
 exports.AuthorityDenied = AuthorityDenied;
+/**
+ * Thrown by `Guard.recordOutcome` when `callId` already has a recorded outcome in this chain's
+ * lifetime. A programming error in the caller (a wrapper observing the same call twice), not a
+ * policy outcome — "exactly one outcome per callId, enforced at append" (docs/execution-binding
+ * spec section 3).
+ */
+class DuplicateOutcomeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DuplicateOutcomeError";
+    }
+}
+exports.DuplicateOutcomeError = DuplicateOutcomeError;
 /**
  * A monotonic integer for audit sequencing, distinct from the wall clock used
  * for TTL expiry — it keeps the log's ordering deterministic regardless of
@@ -77,9 +172,27 @@ class Guard {
         this.strikes = strikes;
     }
     // ---- factory ----------------------------------------------------------
-    /** A fresh root Guard, starting a new delegation chain. */
+    /**
+     * A fresh root Guard, starting a new delegation chain. `schemaVersion: 2` opts the whole chain
+     * into 0.9.0 execution binding — see the module doc comment.
+     *
+     * `auditOverwrite: true` (silently replace an existing non-empty ledger at `auditPath`) is
+     * REFUSED on a `schemaVersion: 2` chain: the restart rule has no escape hatch on v2 — a v2
+     * process restart must always open a NEW audit path, never overwrite an old one, so that a
+     * pending call from before the restart stays truthfully unaccounted rather than vanishing
+     * under a fresh chain at the same path. v1 keeps the flag exactly as before.
+     */
     static issue(agentId, authority, options = {}) {
         const chainId = options.chainId ?? "chain";
+        const schemaVersion = options.schemaVersion ?? 1;
+        if (schemaVersion !== 1 && schemaVersion !== 2) {
+            throw new Error(`unsupported schemaVersion ${schemaVersion}; expected 1 or 2`);
+        }
+        if (schemaVersion === 2 && options.auditOverwrite) {
+            throw new Error("auditOverwrite: true is not permitted on a schemaVersion: 2 chain — the restart rule " +
+                "has no escape hatch on v2 (docs/execution-binding spec section 1). Open a new audit " +
+                "path for the new chain instead; v1 chains may still set auditOverwrite: true.");
+        }
         const chain = new chain_js_1.Chain(chainId, {
             maxDepth: options.maxDepth ?? 6,
             maxFanout: options.maxFanout ?? 16,
@@ -88,15 +201,22 @@ class Guard {
         const audit = new audit_js_1.AuditLog({
             path: options.auditPath ?? null,
             sinks: options.auditSinks ?? [],
+            schemaVersion,
+            overwrite: options.auditOverwrite ?? false,
         });
         const seq = new SeqClock();
         const node = chain.addRoot(agentId, authority, options.task ?? "root");
-        audit.append("root", seq.now(), {
+        const rootFields = {
             chain_id: chainId,
             node: node.nodeId,
             agent: agentId,
             authority: authority.toWire(),
-        });
+        };
+        if (schemaVersion === 2) {
+            chain.paramsSalt = (0, node_crypto_1.randomBytes)(16);
+            rootFields["params_salt"] = chain.paramsSalt.toString("hex");
+        }
+        audit.append("root", seq.now(), rootFields);
         return new Guard(node, chain, audit, seq, options.strictMetering ?? false, options.strikes ?? null);
     }
     // ---- identity ---------------------------------------------------------
@@ -125,6 +245,18 @@ class Guard {
     get isComplete() {
         return this.node.complete;
     }
+    /**
+     * 0.9.0: the schema version this Guard's chain was issued at (1 or 2 — see
+     * `Guard.issue({schemaVersion})`). Adapters use this to decide whether to pass
+     * `capture`/`adapter`/`authorizedParams` to `check` and call `recordOutcome` afterwards,
+     * rather than reaching into the audit log directly.
+     */
+    get schemaVersion() {
+        return this.audit.schemaVersion;
+    }
+    get isV2() {
+        return this.schemaVersion === 2;
+    }
     /** Is `other` an ancestor of this guard in the same chain? */
     isDescendantOf(other) {
         if (other.chain !== this.chain)
@@ -138,21 +270,34 @@ class Guard {
         return false;
     }
     /**
-     * Mark this node's work FINISHED — one `done` event, idempotent. Purely a
-     * lifecycle marker for the ledger and downstream analytics (a delegation that
-     * never reached `done` was cut short); it does NOT change authority.
-     * Revocation is the hard stop.
+     * Mark this node's work FINISHED — one `done` event.
+     *
+     * On a `schemaVersion: 2` chain, returns a `CompletionResult` (see its own doc comment in
+     * reasons.ts for the JavaScript-specific limits of its truthiness bridge) and refuses — a
+     * falsy-by-`.completed` `CompletionResult` carrying `.pendingCallIds` — while this node has
+     * `allow`ed calls that have not yet reported an outcome; completing while a call is still open
+     * would be a false claim that the node's work is finished. Idempotent:
+     * `CompletionResult(false, [])` if already marked.
+     *
+     * On a `schemaVersion: 1` chain (the default) this returns a plain `boolean`, byte-and-type
+     * IDENTICAL to every release before 0.9.0 — v1 never gained pending-call awareness, so there is
+     * nothing new to report and no reason to change its return type. Purely a lifecycle marker
+     * either way — it does NOT change authority; revocation is the hard stop.
      */
     complete() {
+        const v2 = this.isV2;
         if (this.node.complete)
-            return false;
+            return v2 ? new reasons_js_1.CompletionResult(false, []) : false;
+        const pending = v2 ? this.chain.pendingFor(this.node.nodeId) : [];
+        if (pending.length > 0)
+            return new reasons_js_1.CompletionResult(false, pending); // only reachable on v2
         this.node.complete = true;
         this.append("done", {
             chain_id: this.chainId,
             node: this.node.nodeId,
             agent: this.node.agentId,
         });
-        return true;
+        return v2 ? new reasons_js_1.CompletionResult(true, []) : true;
     }
     // ---- delegation -------------------------------------------------------
     /**
@@ -263,7 +408,7 @@ class Guard {
                 `${Array.from(reasons_js_1.DISPOSITIONS).sort().join(", ")}`);
         }
     }
-    logDecision(decision, scope, tool, context, disposition) {
+    logDecision(decision, scope, tool, context, disposition, extraFields) {
         const event = decision.allowed ? "allow" : "deny";
         const fields = {
             chain_id: this.chainId,
@@ -287,7 +432,9 @@ class Guard {
             if (d !== null)
                 fields["disposition"] = d;
         }
-        this.append(event, fields);
+        if (extraFields)
+            Object.assign(fields, extraFields);
+        return this.append(event, fields);
     }
     // ---- enforcement ------------------------------------------------------
     callLimits() {
@@ -311,6 +458,37 @@ class Guard {
         }
         return filled;
     }
+    static attachCallId(decision, callId) {
+        return callId === null ? decision : decision.withCallId(callId);
+    }
+    /**
+     * `[hashHex, reason]` against this chain's `paramsSalt` — see params.ts. `[null, null]` if the
+     * caller omitted the option entirely (opted out of this specific commitment).
+     */
+    paramsCommitment(value) {
+        if (value === undefined)
+            return [null, null];
+        const salt = this.chain.paramsSalt;
+        if (salt === null)
+            return [null, params_js_1.ParamsHashReason.UNSUPPORTED]; // cannot happen for a properly-issued v2 chain
+        return paramsMod.commit(value, salt);
+    }
+    static validateCaptureAdapter(capture, adapter) {
+        if (capture !== null && !reasons_js_1.CAPTURES.has(capture)) {
+            throw new Error(`unknown capture ${JSON.stringify(capture)}; expected one of ` +
+                `${Array.from(reasons_js_1.CAPTURES).sort().join(", ")}`);
+        }
+        if (capture !== null && adapter === null) {
+            throw new Error("adapter: {module, version, hookPath} is required alongside capture " +
+                "(docs/execution-binding spec section 2)");
+        }
+        if (adapter !== null) {
+            const missing = ["module", "version", "hookPath"].filter((k) => !(k in adapter));
+            if (missing.length > 0) {
+                throw new Error(`adapter is missing ${JSON.stringify(missing)}; expected module/version/hookPath`);
+            }
+        }
+    }
     /**
      * Authorize an action. Returns a `Decision`; it does not throw on a denial.
      * Every call — allow or deny — is appended to the audit log.
@@ -319,33 +497,138 @@ class Guard {
      * supply `calls`, the guard supplies the running count for (node, pattern)
      * itself, including this call, and increments it on allow. An explicit
      * `calls` in the context always wins.
+     *
+     * `authorizedParams`/`capture`/`adapter` (0.9.0, `schemaVersion: 2` chains only — throws
+     * otherwise): the execution-binding inputs, see the module doc comment and
+     * docs/execution-binding spec sections 1-4. On a schema-version-2 chain, the returned
+     * `Decision.callId` is what a later `recordOutcome` call binds to.
      */
     check(scope, options = {}) {
         const disposition = options.disposition ?? null;
         Guard.checkDisposition(disposition); // refuse before anything reaches the ledger
+        const isV2 = this.isV2;
+        const authorizedParams = options.authorizedParams;
+        const capture = options.capture ?? null;
+        const adapter = options.adapter ?? null;
+        if (!isV2 && (authorizedParams !== undefined || capture !== null || adapter !== null)) {
+            throw new Error("authorizedParams/capture/adapter require a schemaVersion: 2 chain " +
+                "(Guard.issue(..., {schemaVersion: 2}))");
+        }
+        Guard.validateCaptureAdapter(capture, adapter);
         const ctx = { ...(options.context ?? {}) };
-        const filled = this.autoMeter(scope, ctx);
-        const decision = this.evaluate(scope, ctx, options.metered ?? false);
-        if (decision.allowed) {
-            for (const c of filled)
-                this.chain.countCall(this.node.nodeId, c.meterKey ?? "*");
+        const nid = this.node.nodeId;
+        // 1. refuse if the node is finalized (v2 only — a v1 chain's `complete()` has always been a
+        //    pure informational marker that leaves authority, and `check`, untouched).
+        let decision;
+        let filled;
+        if (isV2 && this.node.complete) {
+            decision = reasons_js_1.Decision.deny(new reasons_js_1.Reason(reasons_js_1.ReasonCode.NODE_FINALIZED, { message: "node already finalized (complete())" }), nid);
+            filled = [];
+        }
+        else {
+            // 2. evaluate authority/ceilings; update meters on allow.
+            filled = this.autoMeter(scope, ctx);
+            decision = this.evaluate(scope, ctx, options.metered ?? false);
+            if (decision.allowed) {
+                for (const c of filled)
+                    this.chain.countCall(nid, c.meterKey ?? "*");
+            }
+        }
+        // 3. allocate callId (v2 only) — fail-closed, nothing written, if the CSPRNG throws.
+        let callId = null;
+        if (isV2) {
+            try {
+                callId = (0, node_crypto_1.randomBytes)(16).toString("hex");
+            }
+            catch (exc) {
+                // Pre-commit failure (spec section 1): meters are restored, nothing is pending, the call
+                // is denied, nothing is appended.
+                if (decision.allowed) {
+                    for (const c of filled)
+                        this.chain.uncountCall(nid, c.meterKey ?? "*");
+                }
+                return reasons_js_1.Decision.deny(new reasons_js_1.Reason(reasons_js_1.ReasonCode.CALL_ID_UNAVAILABLE, { message: String(exc) }), nid);
+            }
         }
-        this.logDecision(decision, scope, options.tool ?? null, ctx, disposition);
+        const extra = {};
+        if (isV2) {
+            extra["call_id"] = callId;
+            if (decision.allowed) {
+                if (capture !== null) {
+                    extra["capture"] = capture;
+                    extra["adapter"] = {
+                        module: adapter.module,
+                        version: adapter.version,
+                        hook_path: adapter.hookPath,
+                    };
+                }
+                else {
+                    // A bare check() with no wrapper IS itself an observation, honestly described:
+                    // authorization was observed; execution was not. The guard supplies this default
+                    // rather than leaving capture/adapter absent, so every v2 allow carries them — the
+                    // verifier requires both (merge-gate item 4); the caller-facing API stays optional,
+                    // the ledger is not.
+                    extra["capture"] = reasons_js_1.Capture.PRE_HOOK_ONLY;
+                    extra["adapter"] = { module: "attenu-guard", version: version_js_1.VERSION, hook_path: "Guard.check" };
+                }
+                const [ph, preason] = this.paramsCommitment(authorizedParams);
+                if (ph !== null)
+                    extra["authorized_params_hash"] = ph;
+                else if (preason !== null)
+                    extra["params_hash_reason"] = preason;
+            }
+        }
+        // 4. commit (append) — a post-commit persistence failure throws CommittedAuditError; attach
+        //    `.decision` (spec: "carries the committed entry and the decision") before it propagates,
+        //    and still register the pending call first (step 5). ANY OTHER exception here (e.g. a
+        //    canonicalization failure while hashing the entry, inside AuditLog.append's hashEntry
+        //    call, which runs BEFORE its commit point) is a pre-commit failure exactly like the
+        //    CSPRNG case above: meters are restored, nothing is pending, and the exception is
+        //    re-thrown as-is (not swallowed into a Decision — unlike CSPRNG exhaustion, a malformed
+        //    context/authorizedParams value is the caller's error, and this library's convention
+        //    elsewhere is to throw on malformed input, not silently deny).
+        try {
+            this.logDecision(decision, scope, options.tool ?? null, ctx, disposition, extra);
+        }
+        catch (exc) {
+            if (exc instanceof audit_js_1.CommittedAuditError) {
+                const decisionWithId = Guard.attachCallId(decision, callId);
+                if (isV2 && decision.allowed && TERMINAL_CAPTURES.has(extra["capture"])) {
+                    this.chain.registerPending(nid, callId);
+                }
+                exc.decision = decisionWithId;
+            }
+            else if (decision.allowed) {
+                for (const c of filled)
+                    this.chain.uncountCall(nid, c.meterKey ?? "*");
+            }
+            throw exc;
+        }
+        decision = Guard.attachCallId(decision, callId);
+        // 5. register pending (allows only, and only for a capture that promises a terminal
+        //    observation -- a PRE_HOOK_ONLY allow is never going to get a recordOutcome() call, by
+        //    construction, so it must never sit in complete()'s pending set).
+        if (isV2 && decision.allowed && TERMINAL_CAPTURES.has(extra["capture"])) {
+            this.chain.registerPending(nid, callId);
+        }
+        // 6. fall through to strike-policy handling, then return.
         if (!decision.allowed &&
             this.strikes !== null &&
             this.strikes.enabled &&
-            !this.chain.isRevoked(this.node.nodeId)) {
-            const count = this.chain.recordStrike(this.strikes.key(this.node.nodeId, scope));
+            !this.chain.isRevoked(nid)) {
+            const count = this.chain.recordStrike(this.strikes.key(nid, scope));
             if (count >= this.strikes.n) {
-                const revoked = this.chain.revoke(this.node.nodeId);
+                const revoked = this.chain.revoke(nid);
+                const killExtra = isV2 ? this.pendingAtKill(revoked) : {};
                 this.append("kill", {
                     chain_id: this.chainId,
-                    target: this.node.nodeId,
+                    target: nid,
                     reason: "strike_policy",
                     scope,
                     strikes: count,
                     mode: this.strikes.mode,
                     revoked,
+                    ...killExtra,
                 });
             }
         }
@@ -362,7 +645,8 @@ class Guard {
     }
     /**
      * A pure dry-run: identical policy evaluation to `check`, but it never throws
-     * and — critically — writes NOTHING to the audit log.
+     * and — critically — writes NOTHING to the audit log. Never allocates a `callId`
+     * (there is nothing to bind an outcome to).
      */
     wouldAllow(scope, options = {}) {
         const ctx = { ...(options.context ?? {}) };
@@ -378,21 +662,153 @@ class Guard {
      *
      * `scope` defaults to `tool` (or "-"), because the published schema requires
      * a string scope on allow and deny events.
+     *
+     * On a `schemaVersion: 2` chain this also allocates and attaches a `callId` (same fail-closed
+     * CSPRNG handling as `check`) — every allow/deny entry carries one; a deny never expects an
+     * outcome.
      */
     recordDenial(reason, message = "", options = {}) {
         Guard.checkDisposition(options.disposition ?? null);
         const r = reason instanceof reasons_js_1.Reason ? reason : new reasons_js_1.Reason(String(reason), { message });
         const decision = reasons_js_1.Decision.deny(r, this.node.nodeId);
+        const isV2 = this.isV2;
         const tool = options.tool ?? null;
-        this.logDecision(decision, options.scope ?? tool ?? "-", tool, { ...(options.context ?? {}) }, options.disposition ?? null);
-        return decision;
+        let callId = null;
+        if (isV2) {
+            try {
+                callId = (0, node_crypto_1.randomBytes)(16).toString("hex");
+            }
+            catch {
+                return reasons_js_1.Decision.deny(r, this.node.nodeId); // fail-closed: nothing written
+            }
+        }
+        try {
+            this.logDecision(decision, options.scope ?? tool ?? "-", tool, { ...(options.context ?? {}) }, options.disposition ?? null, isV2 ? { call_id: callId } : undefined);
+        }
+        catch (exc) {
+            if (exc instanceof audit_js_1.CommittedAuditError) {
+                exc.decision = Guard.attachCallId(decision, callId);
+            }
+            throw exc;
+        }
+        return Guard.attachCallId(decision, callId);
+    }
+    /**
+     * The body-owning wrapper's report of how an `allow`ed call (identified by `callId`, from that
+     * `check` call's `Decision.callId`) ended. `schemaVersion: 2` chains only.
+     *
+     * `bodyState` is one of the `BodyState` constants. `errorCode` is required exactly when
+     * `bodyState === BodyState.RAISED` (a normalized exception class name, never a message) and
+     * forbidden otherwise. `durationMs` (observation start to observation end) is required.
+     * `invokedParams` is the corresponding JSON object the wrapper observed immediately before the
+     * actual invocation — hashed the same way as `check`'s `authorizedParams`; omit the option to
+     * opt out. `receipt` is unverified carriage, `{type, ref, digest}`.
+     *
+     * Exactly one outcome per `callId` is enforced here (throws `DuplicateOutcomeError`); a second
+     * outcome for the same callId is a caller bug, not a policy outcome. A callId that was never
+     * pending anywhere in this chain (bound to a deny, or foreign) is still recorded — this is a
+     * best-effort runtime cleanup, not a gate; the offline verifier is what flags
+     * `outcome_without_allow`/`cross_ref` from the ledger alone.
+     */
+    recordOutcome(callId, bodyState, options) {
+        if (!this.isV2) {
+            throw new Error("recordOutcome requires a schemaVersion: 2 chain (Guard.issue(..., {schemaVersion: 2}))");
+        }
+        if (!reasons_js_1.BODY_STATES.has(bodyState)) {
+            throw new Error(`unknown bodyState ${JSON.stringify(bodyState)}; expected one of ` +
+                `${Array.from(reasons_js_1.BODY_STATES).sort().join(", ")}`);
+        }
+        const errorCode = options.errorCode ?? null;
+        if (bodyState === reasons_js_1.BodyState.RAISED) {
+            if (typeof errorCode !== "string" || !errorCode) {
+                throw new Error("errorCode is required (a non-empty string) when bodyState === BodyState.RAISED");
+            }
+        }
+        else if (errorCode !== null) {
+            throw new Error("errorCode is only permitted when bodyState === BodyState.RAISED");
+        }
+        const durationMs = options.durationMs;
+        if (!Number.isInteger(durationMs) || durationMs < 0) {
+            throw new Error(`durationMs must be a non-negative integer; got ${JSON.stringify(durationMs)}`);
+        }
+        const receipt = options.receipt ?? null;
+        if (receipt !== null) {
+            const r = receipt;
+            const missing = ["type", "ref", "digest"].filter((k) => !(k in r));
+            if (missing.length > 0) {
+                throw new Error(`receipt is missing ${JSON.stringify(missing)}; expected type/ref/digest`);
+            }
+            for (const k of ["type", "ref"]) {
+                if (typeof r[k] !== "string" || !r[k]) {
+                    throw new Error(`receipt[${JSON.stringify(k)}] must be a non-empty string`);
+                }
+            }
+            if (typeof r["digest"] !== "string" || !/^[0-9a-f]{64}$/.test(r["digest"])) {
+                throw new Error("receipt['digest'] must be a lowercase-hex SHA-256 digest (64 hex characters) — spec section 7");
+            }
+        }
+        // Exactly one outcome per callId, "enforced at append" (spec section 3): peek first, but
+        // only COMMIT the outcomed/pending state AFTER the append actually reaches its commit point
+        // — see below. A pre-commit failure here (e.g. a canonicalization failure while hashing this
+        // entry) must leave callId exactly as unresolved as before this call, so a corrected retry
+        // is still possible and `complete()` does not wrongly believe the call was accounted for.
+        if (this.chain.isOutcomed(callId)) {
+            throw new DuplicateOutcomeError(`callId ${JSON.stringify(callId)} already has a recorded outcome`);
+        }
+        const fields = {
+            chain_id: this.chainId,
+            node: this.node.nodeId,
+            call_id: callId,
+            body_state: bodyState,
+            duration_ms: durationMs,
+        };
+        if (errorCode !== null)
+            fields["error_code"] = errorCode;
+        const [ph, preason] = this.paramsCommitment(options.invokedParams);
+        if (ph !== null)
+            fields["invoked_params_hash"] = ph;
+        else if (preason !== null)
+            fields["params_hash_reason"] = preason;
+        if (receipt !== null)
+            fields["receipt"] = { ...receipt };
+        let entry;
+        try {
+            entry = this.append("outcome", fields);
+        }
+        catch (exc) {
+            if (exc instanceof audit_js_1.CommittedAuditError) {
+                // post-commit: the outcome DID reach the in-memory chain; it is now safe (and correct)
+                // to mark it done and drop it from pending before the persistence failure propagates.
+                this.chain.markOutcomed(callId);
+                this.chain.resolvePending(callId);
+            }
+            throw exc;
+        }
+        // success: commit the bookkeeping only now, never before.
+        this.chain.markOutcomed(callId);
+        this.chain.resolvePending(callId);
+        return entry;
     }
     // ---- chain controls ---------------------------------------------------
+    /**
+     * `{pending_at_kill: [...]}` — the still-open callIds across every node a kill revoked,
+     * snapshotted (NOT cleared: a late `recordOutcome` after this kill is still accepted — spec
+     * section 1). Only meaningful on v2 chains; call only when `isV2`.
+     */
+    pendingAtKill(revokedNodes) {
+        const pending = new Set();
+        for (const nid of revokedNodes) {
+            for (const c of this.chain.pendingFor(nid))
+                pending.add(c);
+        }
+        return { pending_at_kill: Array.from(pending).sort() };
+    }
     /** Cascade-revoke a node — by default this one — and its whole subtree. */
     revoke(nodeId) {
         const target = nodeId ?? this.node.nodeId;
         const revoked = this.chain.revoke(target);
-        this.append("kill", { chain_id: this.chainId, target, revoked });
+        const extra = this.isV2 ? this.pendingAtKill(revoked) : {};
+        this.append("kill", { chain_id: this.chainId, target, revoked, ...extra });
         return revoked;
     }
     /**
@@ -404,11 +820,13 @@ class Guard {
      */
     revokeAgent(agentId) {
         const revoked = this.chain.revokeAgent(agentId);
+        const extra = this.isV2 ? this.pendingAtKill(revoked) : {};
         this.append("kill", {
             chain_id: this.chainId,
             target: this.node.nodeId,
             agent: agentId,
             revoked,
+            ...extra,
         });
         return revoked;
     }