@actuarial-ts/agents 0.2.0 → 0.3.0

package/src/errors.ts

@@ -0,0 +1,62 @@
+/**
+ * Error idiom for the agents package, mirroring core's ReservingError and
+ * compliance's ComplianceError: a typed Error subclass carrying a registered
+ * machine code. The registry below is the closed contract - add the code here
+ * when introducing a new throw.
+ *
+ * These errors are DEFINITION-TIME and SEAM errors (bad tool schemas, bad
+ * gate specs, missing tenant context, undocumented judgment). They are never
+ * allowed to reach the model: defineActuarialTool's wrapper converts anything
+ * thrown during tool execution into a { success: false, error } envelope.
+ */
+
+/** Every machine-readable code an AgentsError can carry. */
+export const AGENTS_ERROR_CODES = [
+  /** A tool read the request context and found no (or a non-string/empty) tenant id. */
+  "NO_TENANT_CONTEXT",
+  /** A tool's input schema declares a tenant-id key (projectId/tenantId); tenant ids travel only via RequestContext. */
+  "TENANT_IN_SCHEMA",
+  "BAD_INPUT_SCHEMA",
+  /** A judgment chain was defined with an invalid gate list or gate spec. */
+  "BAD_GATE",
+  /** A judgment gate was resumed without a non-blank rationale. */
+  "MISSING_RATIONALE",
+  /** Two tools with the same id were passed to toolRegistry. */
+  "DUPLICATE_TOOL_ID",
+  /** promoteStudy was called with malformed deps/options (programmer error). */
+  "BAD_PROMOTION_OPTIONS",
+  /** A study document carries no selections; nothing to promote. */
+  "EMPTY_STUDY",
+  /** The study's stated replayTolerance exceeds the host ceiling (spec 6 Gate 1). */
+  "TOLERANCE_CEILING_EXCEEDED",
+  /** A selection's segment labels match no host workspace target (no fuzzy matching in v1). */
+  "SEGMENT_UNRESOLVED",
+  /** Two selections resolve to the same workspace target; v1 promotes one selection per segment. */
+  "SEGMENT_AMBIGUOUS",
+  /** The divergence explainer was invoked on a report whose verdict is not "disagree" (spec 9 item 3: only-on-disagree is structural). */
+  "VERDICT_NOT_DISAGREE",
+  /** The result docs handed to the divergence explainer do not match the crosscheck report's engine stamps (wrong docs, or a/b swapped). */
+  "DIVERGENCE_INPUT_MISMATCH",
+  /** The divergence evidence tool ran without assembled evidence in the request context (drive the agent through explainDivergence). */
+  "NO_DIVERGENCE_EVIDENCE",
+  /** A remote sidecar 2xx response failed interchange parseDocument (bad JSON, bad schema, broken integrity tag, or a non-result kind). */
+  "REMOTE_RESULT_INVALID",
+  /** The boot self-test found an MCP-exposed probe tool that did NOT fail closed without tenant context; the MCP tenant seam is not wired up and the server must abort startup. */
+  "MCP_SELF_TEST_FAILED",
+] as const;
+
+export type AgentsErrorCode = (typeof AGENTS_ERROR_CODES)[number];
+
+/**
+ * Thrown for invalid agent-toolkit input: tenant-seam violations, malformed
+ * gate specs, undocumented judgment. Carries a registered machine code so
+ * envelopes and tests can match on it without parsing messages.
+ */
+export class AgentsError extends Error {
+  readonly code: AgentsErrorCode;
+  constructor(code: AgentsErrorCode, message: string) {
+    super(message);
+    this.name = "AgentsError";
+    this.code = code;
+  }
+}

package/src/evals.ts

@@ -0,0 +1,162 @@
+/**
+ * Golden-prompt tool-selection eval harness: does a realistic instruction
+ * make the agent call the right tool(s)? Generalizes the ActNG server's
+ * eval-advisor script.
+ *
+ * Asserts tool SELECTION, not prose: each case lists tools that must appear
+ * among the turn's calls. Running against a real agent costs live API tokens
+ * and is opt-in by design - the harness itself is pure bookkeeping, which is
+ * why package tests exercise it with a stubbed agent and canned streams.
+ *
+ * Chunk shapes (verified against @mastra/core 1.49 fullStream): tool calls
+ * arrive as { type: "tool-call", payload: { toolName } }, with a legacy
+ * { type: "tool-call", toolName } fallback.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+
+export interface ToolSelectionEvalCase {
+  id: string;
+  prompt: string;
+  /** Tool names that must ALL appear among the turn's calls. */
+  expectTools: readonly string[];
+}
+
+export interface ToolSelectionCaseResult {
+  id: string;
+  pass: boolean;
+  /** Tool names actually called, in first-call order. */
+  called: string[];
+  /** Expected tools that never got called. */
+  missing: string[];
+  /** Stream error or timeout, when the case failed exceptionally. */
+  error?: string;
+}
+
+export interface ToolSelectionEvalReport {
+  results: ToolSelectionCaseResult[];
+  summary: { total: number; passed: number; failed: number };
+}
+
+/**
+ * The structural slice of an agent the harness needs: stream(messages,
+ * options) resolving to something with an async-iterable fullStream.
+ *
+ * WHY structural instead of the concrete @mastra/core Agent class: the Agent
+ * type carries heavy generics and live-model plumbing the harness never
+ * touches; it only consumes the fullStream chunk feed. Typing the seam
+ * structurally lets package tests substitute a canned-stream stub (no LLM, no
+ * network) and lets hosts pass any Agent from any compatible Mastra patch
+ * level without generic gymnastics.
+ */
+export interface ToolStreamingAgent {
+  stream(
+    messages: Array<{ role: "user"; content: string }>,
+    options?: Record<string, unknown>,
+  ): Promise<{ fullStream: AsyncIterable<unknown> }>;
+}
+
+export interface RunToolSelectionEvalsOptions {
+  agent: ToolStreamingAgent;
+  cases: readonly ToolSelectionEvalCase[];
+  /** Forwarded verbatim to agent.stream options (the tenant seam for tools). */
+  requestContext?: unknown;
+  /** Max agent steps per case. Default 8. */
+  maxSteps?: number;
+  /** Per-case wall clock: a stalled stream fails the case, not the suite. Default 180000. */
+  timeoutMs?: number;
+  /**
+   * Optional per-case memory option factory (thread/resource), for agents
+   * whose Memory configuration requires one on every stream call.
+   */
+  memoryFor?: (evalCase: ToolSelectionEvalCase) => { thread: string; resource: string };
+}
+
+// ---------------------------------------------------------------------------
+// Harness
+
+/** Extracts the tool name from a fullStream chunk, or null for non-tool-call chunks. */
+function toolCallName(chunk: unknown): string | null {
+  const c = chunk as {
+    type?: unknown;
+    toolName?: unknown;
+    payload?: { toolName?: unknown };
+  };
+  if (c?.type !== "tool-call") return null;
+  const name = c.payload?.toolName ?? c.toolName;
+  return typeof name === "string" && name.length > 0 ? name : null;
+}
+
+/**
+ * Runs every case sequentially against the agent, collecting the tool calls
+ * from the fullStream and asserting each case's expectTools is a subset of
+ * the tools actually called. A per-case Promise.race timeout keeps one
+ * stalled stream from hanging the whole suite.
+ */
+export async function runToolSelectionEvals(
+  options: RunToolSelectionEvalsOptions,
+): Promise<ToolSelectionEvalReport> {
+  const { agent, cases, requestContext } = options;
+  const maxSteps = options.maxSteps ?? 8;
+  const timeoutMs = options.timeoutMs ?? 180_000;
+
+  const results: ToolSelectionCaseResult[] = [];
+  for (const evalCase of cases) {
+    const called = new Set<string>();
+    let error: string | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    // On timeout the underlying stream is CANCELLED, not abandoned: the
+    // iterator's return() is invoked so a well-behaved provider stops
+    // generating (and billing), and no chunks bleed into the next case.
+    // Hosts whose models accept an abort signal should prefer abortable
+    // models; the iterator return() is the portable floor.
+    let activeIterator: AsyncIterator<unknown> | undefined;
+    try {
+      await Promise.race([
+        (async () => {
+          const stream = await agent.stream([{ role: "user", content: evalCase.prompt }], {
+            ...(requestContext !== undefined ? { requestContext } : {}),
+            maxSteps,
+            ...(options.memoryFor ? { memory: options.memoryFor(evalCase) } : {}),
+          });
+          const iterator = stream.fullStream[Symbol.asyncIterator]();
+          activeIterator = iterator;
+          for (;;) {
+            const next = await iterator.next();
+            if (next.done) break;
+            const name = toolCallName(next.value);
+            if (name) called.add(name);
+          }
+        })(),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`case timed out after ${timeoutMs}ms`)),
+            timeoutMs,
+          );
+        }),
+      ]);
+    } catch (err) {
+      error = err instanceof Error ? err.message : String(err);
+      // Best-effort cancellation of a stream that outlived its race.
+      void activeIterator?.return?.().catch(() => undefined);
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+    const missing = evalCase.expectTools.filter((tool) => !called.has(tool));
+    const result: ToolSelectionCaseResult = {
+      id: evalCase.id,
+      pass: error === undefined && missing.length === 0,
+      called: [...called],
+      missing,
+      ...(error !== undefined ? { error } : {}),
+    };
+    results.push(result);
+  }
+
+  const passed = results.filter((r) => r.pass).length;
+  return {
+    results,
+    summary: { total: results.length, passed, failed: results.length - passed },
+  };
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./errors.js";
+export * from "./tools.js";
+export * from "./judgment.js";
+export * from "./promotion.js";
+export * from "./advisor.js";
+export * from "./evals.js";
+export * from "./divergence.js";
+export * from "./remote.js";
+export * from "./mcp.js";

package/src/judgment.ts

@@ -0,0 +1,458 @@
+/**
+ * Judgment gates that write the compliance ledger: the generalization of the
+ * ActNG server's derive-expected-losses workflow (cap -> restoration ->
+ * trends -> ELR) into a factory any host can point at its own gate list.
+ *
+ * The loop each gate enforces is propose -> justify -> approve -> record:
+ * the gate gathers evidence and SUSPENDS with a recommendation; a human
+ * decides; the resume payload carries the decision plus a VERBATIM rationale;
+ * the gate applies the decision and appends the resulting assumptions to an
+ * @actuarial-ts/compliance ledger threaded through the workflow state. A
+ * completed chain returns { trail, ledger } - a ledger ready to hand straight
+ * to generateDisclosure, so ASOP 41 documentation falls out of running the
+ * analysis instead of being reconstructed afterwards.
+ *
+ * Ground truth (verified against @mastra/core 1.49 dist types and a live
+ * suspend/resume probe):
+ * - Steps execute as ({ inputData, resumeData, suspend, requestContext });
+ *   suspend(payload) pauses the run with the payload surfaced under
+ *   result.steps[stepId].suspendPayload; run.resume({ step, resumeData,
+ *   requestContext }) re-executes the step with resumeData set.
+ * - Resume data is validated against the gate's resumeSchema by Mastra
+ *   itself; run.resume REJECTS on schema violations. The chain additionally
+ *   rejects blank rationales at runtime (AgentsError MISSING_RATIONALE), so a
+ *   host schema of plain z.string() cannot smuggle undocumented judgment.
+ * - Suspend/resume requires snapshot storage: hosts register the returned
+ *   workflow on their Mastra instance (new Mastra({ workflows: { chain } })),
+ *   which provides in-memory storage by default and durable storage when
+ *   configured - exactly how the server keeps paused derivations resumable
+ *   across restarts.
+ *
+ * Purity: the package never reads a clock. The host supplies now() and every
+ * ledger timestamp comes from it.
+ *
+ * Tenant seam: the tenant id travels in the workflow requestContext, never in
+ * step inputs - the same boundary as every actuarial tool.
+ */
+
+import { createStep, createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+import {
+  createLedger,
+  recordAssumption,
+  type AssumptionActor,
+  type AssumptionEntry,
+  type AssumptionLedger,
+  type JsonValue,
+} from "@actuarial-ts/compliance";
+import { AgentsError } from "./errors.js";
+import { zodObjectShape } from "./tools.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+
+/**
+ * The request-context key a host sets (server-side, from its authenticated
+ * session — the same trust path as the tenant id) to identify WHO is resuming
+ * gates. The resume payload cannot supply it: a payload travels through
+ * model-reachable surfaces, and an identity that can be asserted from there
+ * is a claim, not a record.
+ */
+export const ACTOR_IDENTITY_CONTEXT_KEY = "actorIdentity";
+
+/** One decision in the audit trail; skip gates record skipped: true. */
+export interface JudgmentTrailEntry {
+  stage: string;
+  decision: string;
+  rationale: string;
+  skipped: boolean;
+  /** Coarse classification from the resume payload (default | actuary | agent). */
+  actor?: AssumptionActor;
+  /**
+   * The authenticated identity from the request context, when the host set
+   * one. Absent means the host supplied none — identity is never invented,
+   * and never read from the resume payload.
+   */
+  actorIdentity?: string;
+}
+
+/**
+ * What earlier gates decided, keyed by gate id: the validated resume payload
+ * for decided gates, or { skipped: true, reason } for self-skipped ones.
+ * Available to skipWhen/gatherEvidence/applyDecision so a later gate can
+ * self-skip on an earlier decision (the server's ilf gate skips when the cap
+ * gate chose to stay unlimited).
+ */
+export type JudgmentDecisions = Record<string, unknown>;
+
+/** Marker recorded into the decisions map when a gate self-skips. */
+export interface JudgmentSkipRecord {
+  skipped: true;
+  reason: string;
+}
+
+/** The context every gate hook receives. */
+export interface JudgmentGateContext {
+  /** The workflow request context (tenant id lives here, never in inputs). */
+  requestContext: { get(key: string): unknown };
+  /** Host-injected clock; the source of every ledger timestamp. */
+  now: () => string;
+  /** Decisions from earlier gates, keyed by gate id. */
+  decisions: JudgmentDecisions;
+  /** The trail accumulated so far. */
+  trail: readonly JudgmentTrailEntry[];
+}
+
+/**
+ * A ledger entry as a gate's applyDecision returns it: timestamp, actor, and
+ * rationale may be omitted - the chain fills timestamp from ctx.now(), actor
+ * from the resume payload's optional actor field (default "actuary"), and
+ * rationale from the decision's verbatim rationale.
+ */
+export interface JudgmentLedgerEntry {
+  /** Dotted assumption path, e.g. "layer.cap". */
+  field: string;
+  value: JsonValue;
+  previousValue?: JsonValue;
+  source?: string;
+  rationale?: string;
+  timestamp?: string;
+  actor?: AssumptionActor;
+}
+
+/** What applyDecision hands back to the chain. */
+export interface JudgmentApplication {
+  /** Assumptions this decision fixed; appended to the threaded ledger. */
+  ledgerEntries?: JudgmentLedgerEntry[];
+  /** Human-readable decision text for the trail; derived from the payload when omitted. */
+  summary?: string;
+}
+
+/**
+ * One human judgment gate. TDecision is the validated resume payload shape;
+ * its schema MUST declare a rationale key (createJudgmentChain rejects the
+ * spec otherwise) and SHOULD make it a non-empty string - either way the
+ * chain rejects blank rationales at runtime.
+ */
+export interface JudgmentGateSpec<TDecision = unknown> {
+  /** Step id; also the resume target (run.resume({ step: id, ... })). */
+  id: string;
+  /** Stage label surfaced in the suspend payload and the trail. */
+  stage: string;
+  /** Validates the resume payload. Must contain a rationale key. */
+  resumeSchema: z.ZodType<TDecision>;
+  /**
+   * Returns the skip reason when the gate should pass through without a
+   * human decision (e.g. a later gate made moot by an earlier decision),
+   * null to proceed. A skipped gate records a trail note and never suspends.
+   */
+  skipWhen?: (ctx: JudgmentGateContext) => string | null;
+  /** Gathers the evidence and recommendation the gate suspends with. */
+  gatherEvidence: (
+    ctx: JudgmentGateContext,
+  ) => Promise<{ recommendation: string; evidence: unknown }> | { recommendation: string; evidence: unknown };
+  /** Applies the human decision through the host's service layer. */
+  applyDecision: (ctx: JudgmentGateContext, decision: TDecision) => Promise<JudgmentApplication>;
+}
+
+/** The completed chain's output: the audit trail and the fused compliance ledger. */
+export interface JudgmentChainOutcome {
+  trail: JudgmentTrailEntry[];
+  /** Ready for @actuarial-ts/compliance generateDisclosure. */
+  ledger: AssumptionLedger;
+}
+
+export interface CreateJudgmentChainOptions {
+  /** Workflow id. */
+  id: string;
+  /** The gates, in order. Must be non-empty with unique ids. */
+  gates: readonly JudgmentGateSpec<any>[]; // eslint-disable-line @typescript-eslint/no-explicit-any -- heterogeneous decision types; each gate stays internally typed
+  /**
+   * Host-injected clock for ledger timestamps (purity: this package never
+   * reads Date). Return an ISO-8601 string.
+   */
+  now: () => string;
+  /** Runs once after the last gate, before the chain returns its outcome. */
+  onComplete?: (
+    outcome: JudgmentChainOutcome,
+    ctx: JudgmentGateContext,
+  ) => Promise<void> | void;
+  /** Optional request-context validation (e.g. z.object({ projectId: z.string() })). */
+  requestContextSchema?: z.ZodTypeAny;
+}
+
+// ---------------------------------------------------------------------------
+// Chain state threaded through step outputs
+
+// Declares EVERY JudgmentTrailEntry field: zod strips undeclared keys on the
+// step-output parse, so an undeclared field here is silently erased between
+// gates (the ledger schema below carries the same warning for the same reason).
+const trailEntrySchema = z.object({
+  stage: z.string(),
+  decision: z.string(),
+  rationale: z.string(),
+  skipped: z.boolean(),
+  actor: z.enum(["default", "actuary", "agent"]).optional(),
+  actorIdentity: z.string().optional(),
+});
+
+// Declares EVERY AssumptionEntry field: zod strips undeclared keys on parse,
+// and losing previousValue/source between steps would corrupt the ledger.
+const ledgerEntrySchema = z.object({
+  seq: z.number().int().positive(),
+  timestamp: z.string(),
+  actor: z.enum(["default", "actuary", "agent"]),
+  field: z.string(),
+  value: z.unknown(),
+  previousValue: z.unknown().optional(),
+  source: z.string().optional(),
+  rationale: z.string().optional(),
+});
+
+const chainStateSchema = z.object({
+  trail: z.array(trailEntrySchema).default([]),
+  ledgerEntries: z.array(ledgerEntrySchema).default([]),
+  decisions: z.record(z.unknown()).default({}),
+});
+
+const suspendSchema = z.object({
+  stage: z.string(),
+  recommendation: z.string(),
+  evidence: z.unknown(),
+});
+
+const chainInputSchema = z.object({});
+const chainResultSchema = z.object({
+  trail: z.array(trailEntrySchema),
+  ledger: z.custom<AssumptionLedger>(
+    (value) =>
+      typeof value === "object" &&
+      value !== null &&
+      Array.isArray((value as { entries?: unknown }).entries),
+  ),
+});
+
+interface ChainState {
+  trail: JudgmentTrailEntry[];
+  ledgerEntries: AssumptionEntry[];
+  decisions: JudgmentDecisions;
+}
+
+/**
+ * The first gate receives the workflow input ({}), and snapshot storage may
+ * round-trip state through JSON, so normalize defensively instead of trusting
+ * zod defaults to have been applied.
+ */
+function normalizeState(input: unknown): ChainState {
+  const raw = (input ?? {}) as Partial<ChainState>;
+  return {
+    trail: Array.isArray(raw.trail) ? raw.trail : [],
+    ledgerEntries: Array.isArray(raw.ledgerEntries) ? raw.ledgerEntries : [],
+    decisions:
+      typeof raw.decisions === "object" && raw.decisions !== null ? raw.decisions : {},
+  };
+}
+
+/** Trail text for a decision when applyDecision returns no summary. */
+function describeDecision(decision: unknown): string {
+  if (typeof decision === "object" && decision !== null) {
+    const named = (decision as { decision?: unknown }).decision;
+    if (typeof named === "string" && named.length > 0) return named;
+    const { rationale: _rationale, actor: _actor, ...rest } = decision as Record<string, unknown>;
+    if (Object.keys(rest).length > 0) return JSON.stringify(rest);
+  }
+  return "decided";
+}
+
+function actorOf(decision: unknown): AssumptionActor {
+  const actor = (decision as { actor?: unknown } | null | undefined)?.actor;
+  return actor === "agent" || actor === "default" || actor === "actuary" ? actor : "actuary";
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+
+/** Reserved id of the terminal step that assembles { trail, ledger }. */
+const COMPLETE_STEP_ID = "complete";
+
+/**
+ * The committed workflow type hosts receive: register it on a Mastra instance
+ * for snapshot storage, then createRun/start/resume exactly like any Mastra
+ * workflow. (Instantiation expression pins the concrete schema generics; the
+ * step list is dynamic, so the per-step chain typing is erased - see the cast
+ * at the bottom of createJudgmentChain.)
+ */
+export type JudgmentChainWorkflow = ReturnType<
+  typeof createWorkflow<string, typeof chainInputSchema, typeof chainResultSchema>
+>;
+
+/**
+ * Builds a committed Mastra workflow from an ordered gate list. Each gate:
+ * skipWhen? -> pass through with a trail note; else gatherEvidence ->
+ * suspend({ stage, recommendation, evidence }); on resume -> validate the
+ * decision (schema + non-blank rationale), applyDecision, append the
+ * resulting assumptions to the threaded ledger. The terminal step rebuilds
+ * the frozen ledger, invokes onComplete, and returns { trail, ledger }.
+ *
+ * FOOTGUN (learned the hard way): a Mastra Workflow exposes a .then(step)
+ * builder method, which makes it an ACCIDENTAL THENABLE. Never await the
+ * returned workflow and never return it from an async function - JS will
+ * call .then(resolve, reject) with the promise resolver as a "step" and the
+ * promise never settles. Assign it synchronously and register it on your
+ * Mastra instance.
+ */
+export function createJudgmentChain(options: CreateJudgmentChainOptions): JudgmentChainWorkflow {
+  const { id, gates, now, onComplete, requestContextSchema } = options;
+
+  if (gates.length === 0) {
+    throw new AgentsError("BAD_GATE", `Judgment chain "${id}" needs at least one gate`);
+  }
+  const seen = new Set<string>();
+  for (const gate of gates) {
+    if (gate.id === COMPLETE_STEP_ID) {
+      throw new AgentsError(
+        "BAD_GATE",
+        `Gate id "${COMPLETE_STEP_ID}" is reserved for the chain's terminal step`,
+      );
+    }
+    if (seen.has(gate.id)) {
+      throw new AgentsError("BAD_GATE", `Duplicate gate id "${gate.id}" in chain "${id}"`);
+    }
+    seen.add(gate.id);
+    const shape = zodObjectShape(gate.resumeSchema);
+    if (!shape || !("rationale" in shape)) {
+      throw new AgentsError(
+        "BAD_GATE",
+        `Gate "${gate.id}" resumeSchema must be a zod object containing a "rationale" key: every human decision enters the audit trail with its verbatim rationale`,
+      );
+    }
+  }
+
+  const gateSteps = gates.map((gate) =>
+    createStep({
+      id: gate.id,
+      inputSchema: chainStateSchema,
+      outputSchema: chainStateSchema,
+      suspendSchema,
+      resumeSchema: gate.resumeSchema,
+      execute: async ({ inputData, resumeData, suspend, requestContext }) => {
+        const state = normalizeState(inputData);
+        const ctx: JudgmentGateContext = {
+          requestContext,
+          now,
+          decisions: state.decisions,
+          trail: state.trail,
+        };
+
+        const skipReason = gate.skipWhen?.(ctx) ?? null;
+        if (skipReason !== null) {
+          const skip: JudgmentSkipRecord = { skipped: true, reason: skipReason };
+          return {
+            trail: [
+              ...state.trail,
+              { stage: gate.stage, decision: "skipped", rationale: skipReason, skipped: true },
+            ],
+            ledgerEntries: state.ledgerEntries,
+            decisions: { ...state.decisions, [gate.id]: skip },
+          };
+        }
+
+        if (resumeData === undefined) {
+          const { recommendation, evidence } = await gate.gatherEvidence(ctx);
+          await suspend({ stage: gate.stage, recommendation, evidence });
+          return state; // unreachable after suspend; satisfies the output type
+        }
+
+        const decision = resumeData;
+        const rationale = (decision as { rationale?: unknown } | null)?.rationale;
+        if (typeof rationale !== "string" || rationale.trim() === "") {
+          throw new AgentsError(
+            "MISSING_RATIONALE",
+            `Gate "${gate.id}" (${gate.stage}) resumed without a rationale; undocumented judgment is exactly what the ledger exists to prevent`,
+          );
+        }
+        const actor = actorOf(decision);
+        // WHO decided comes from the server-set context, never the payload:
+        // the payload's job is the decision and its coarse classification.
+        const rawIdentity = requestContext?.get(ACTOR_IDENTITY_CONTEXT_KEY);
+        const actorIdentity =
+          typeof rawIdentity === "string" && rawIdentity.length > 0 ? rawIdentity : undefined;
+
+        const applied = await gate.applyDecision(ctx, decision);
+
+        // recordAssumption is the single validator/freezer: replay the
+        // threaded entries into a ledger, append, and thread the plain
+        // entries array (snapshot storage may JSON round-trip state).
+        let ledger: AssumptionLedger = { entries: state.ledgerEntries };
+        for (const entry of applied.ledgerEntries ?? []) {
+          ledger = recordAssumption(ledger, {
+            field: entry.field,
+            value: entry.value,
+            ...(entry.previousValue !== undefined ? { previousValue: entry.previousValue } : {}),
+            ...(entry.source !== undefined ? { source: entry.source } : {}),
+            timestamp: entry.timestamp ?? now(),
+            actor: entry.actor ?? actor,
+            rationale: entry.rationale ?? rationale,
+          });
+        }
+
+        return {
+          trail: [
+            ...state.trail,
+            {
+              actor,
+              ...(actorIdentity !== undefined ? { actorIdentity } : {}),
+              stage: gate.stage,
+              decision: applied.summary ?? describeDecision(decision),
+              rationale,
+              skipped: false,
+            },
+          ],
+          ledgerEntries: [...ledger.entries],
+          decisions: { ...state.decisions, [gate.id]: decision },
+        };
+      },
+    }),
+  );
+
+  const completeStep = createStep({
+    id: COMPLETE_STEP_ID,
+    inputSchema: chainStateSchema,
+    outputSchema: chainResultSchema,
+    execute: async ({ inputData, requestContext }) => {
+      const state = normalizeState(inputData);
+      // Rebuild through recordAssumption so the returned ledger is frozen and
+      // seq-consistent even after a JSON round-trip through snapshot storage.
+      let ledger = createLedger();
+      for (const entry of state.ledgerEntries) {
+        const { seq: _seq, ...fresh } = entry;
+        ledger = recordAssumption(ledger, fresh);
+      }
+      const outcome: JudgmentChainOutcome = { trail: state.trail, ledger };
+      await onComplete?.(outcome, {
+        requestContext,
+        now,
+        decisions: state.decisions,
+        trail: state.trail,
+      });
+      return outcome;
+    },
+  });
+
+  // The gate list is dynamic, so the step-by-step generic threading
+  // createWorkflow's .then() performs cannot be expressed statically; every
+  // gate shares the chain-state schema, so runtime shapes stay checked and
+  // the cast is confined to this builder.
+  interface ChainBuilder {
+    then(step: unknown): ChainBuilder;
+    commit(): unknown;
+  }
+  let builder = createWorkflow({
+    id,
+    inputSchema: chainInputSchema,
+    outputSchema: chainResultSchema,
+    ...(requestContextSchema ? { requestContextSchema } : {}),
+  }) as unknown as ChainBuilder;
+  for (const step of gateSteps) builder = builder.then(step);
+  return builder.then(completeStep).commit() as JudgmentChainWorkflow;
+}