@petepetrash/circuit 0.1.0

package/dist/runtime/run/iteration-ledger.js

@@ -0,0 +1,91 @@
+// The per-iteration experiment ledger — a pure projection over a finished
+// until-loop trace.
+//
+// A judge-gated until loop re-enters its body once per pass; at each tail seam
+// the engine disposes the stop-judge's goal-met claim against the evidence floor
+// and stamps a `run.until-judgment` entry (src/schemas/trace-entry.ts). That
+// entry is the durable record of ONE pass: what the judge proposed, whether the
+// floor confirmed it, the settled disposition, the stall count, the open-latch
+// count, and the carried lesson. This projection joins each judgment to the
+// per-relay usage recorded SINCE the previous judgment, producing one row per
+// iteration the operator can read in the final summary. It is the Circuit analog
+// of autoresearch's results.tsv: one line per experiment, with its cost.
+//
+// Usage parsing mirrors the until-loop budget accumulator
+// (src/runtime/run/until-budget.ts): the same RelayUsageEvidence parse, the same
+// input+output token sum, and a cost that stays undefined until a relay reports
+// one. A run with no judgment entries (any non-until run, or a count-driven
+// until loop) yields an empty ledger.
+import { RelayUsageEvidence } from '../../schemas/trace-entry.js';
+function emptyUsage() {
+    return { tokens: 0, costUsd: undefined };
+}
+// Project the run's trace into one ledger row per iteration. Entries arrive in
+// sequence order from TraceStore.load, but we sort defensively by sequence so a
+// caller passing an unordered slice still projects in iteration order. The walk
+// accumulates relay.completed usage and, at each run.until-judgment, emits a row
+// joining the accumulated usage to that judgment, then resets the accumulator.
+export function iterationLedgerFromTrace(entries) {
+    const ordered = [...entries].sort((a, b) => a.sequence - b.sequence);
+    const rows = [];
+    let usage = emptyUsage();
+    for (const entry of ordered) {
+        if (entry.kind === 'relay.completed') {
+            const parsed = RelayUsageEvidence.safeParse(entry.usage);
+            if (!parsed.success)
+                continue;
+            usage.tokens += parsed.data.input_tokens + parsed.data.output_tokens;
+            if (parsed.data.total_cost_usd_reported !== undefined) {
+                usage.costUsd = (usage.costUsd ?? 0) + parsed.data.total_cost_usd_reported;
+            }
+            continue;
+        }
+        if (entry.kind !== 'run.until-judgment')
+            continue;
+        rows.push({
+            iteration: entry.iteration,
+            disposition: entry.disposition,
+            goalProposed: entry.goal_proposed,
+            evidenceConfirmed: entry.evidence_confirmed,
+            openLatchCount: entry.open_latch_count,
+            noProgressCount: entry.no_progress_count,
+            ...(entry.lesson === undefined ? {} : { lesson: entry.lesson }),
+            inputPlusOutputTokens: usage.tokens,
+            ...(usage.costUsd === undefined ? {} : { costUsd: usage.costUsd }),
+        });
+        usage = emptyUsage();
+    }
+    return rows;
+}
+// Keep a carried lesson short enough that the table stays scannable. The cut
+// uses a single-character ellipsis so the truncation reads as deliberate.
+const LESSON_MAX = 80;
+function truncateLesson(lesson) {
+    const oneLine = lesson.replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= LESSON_MAX)
+        return oneLine;
+    return `${oneLine.slice(0, LESSON_MAX - 1)}…`;
+}
+// Escape the pipe so a lesson containing one never breaks the table grid.
+function cell(value) {
+    return value.replace(/\|/g, '\\|');
+}
+function yesNo(value) {
+    return value ? 'yes' : 'no';
+}
+// Render the ledger as a compact Markdown table, one row per iteration. Plain
+// English headers only — no engine field names. Returns the empty string for an
+// empty ledger so a caller can append it unconditionally and a non-until run (or
+// a count-driven loop) adds nothing.
+export function renderIterationLedgerMarkdown(rows) {
+    if (rows.length === 0)
+        return '';
+    const header = '| Iteration | Disposition | Goal proposed | Evidence confirmed | Open latches | No-progress | Tokens | Lesson |';
+    const separator = '| --- | --- | --- | --- | --- | --- | --- | --- |';
+    const lines = rows.map((row) => {
+        const lesson = row.lesson === undefined ? '' : cell(truncateLesson(row.lesson));
+        return `| ${row.iteration} | ${row.disposition} | ${yesNo(row.goalProposed)} | ${yesNo(row.evidenceConfirmed)} | ${row.openLatchCount} | ${row.noProgressCount} | ${row.inputPlusOutputTokens} | ${lesson} |`;
+    });
+    return [header, separator, ...lines].join('\n');
+}
+//# sourceMappingURL=iteration-ledger.js.map

package/dist/runtime/run/iteration-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iteration-ledger.js","sourceRoot":"","sources":["../../../src/runtime/run/iteration-ledger.ts"],"names":[],"mappings":"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"}

package/dist/runtime/run/manifest-snapshot.d.ts

@@ -0,0 +1,27 @@
+import { type CompiledFlow } from '../../schemas/compiled-flow.js';
+import { ManifestSnapshot } from '../../schemas/manifest.js';
+import type { FlowId } from '../domain/flow.js';
+import type { RunId as RuntimeRunId } from '../domain/run.js';
+export declare const MANIFEST_SNAPSHOT_RUN_FILE = "manifest.snapshot.json";
+export declare function runtimeManifestSnapshotPath(runDir: string): string;
+export interface RuntimeManifestSnapshotInput {
+    readonly runDir: string;
+    readonly runId: RuntimeRunId;
+    readonly flowId: FlowId;
+    readonly capturedAt: string;
+    readonly bytes: Uint8Array;
+}
+export declare function writeRuntimeManifestSnapshot(input: RuntimeManifestSnapshotInput): Promise<ManifestSnapshot>;
+export declare function readRuntimeManifestSnapshot(runDir: string): Promise<ManifestSnapshot>;
+export interface RuntimeCompiledFlowManifestSnapshot {
+    readonly snapshot: ManifestSnapshot;
+    readonly flowBytes: Buffer;
+    readonly flow: CompiledFlow;
+}
+export declare function readRuntimeCompiledFlowManifestSnapshot(input: {
+    readonly runDir: string;
+    readonly expectedRunId?: string;
+    readonly expectedFlowId?: string;
+    readonly expectedHash?: string;
+}): Promise<RuntimeCompiledFlowManifestSnapshot>;
+//# sourceMappingURL=manifest-snapshot.d.ts.map

package/dist/runtime/run/manifest-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-snapshot.d.ts","sourceRoot":"","sources":["../../../src/runtime/run/manifest-snapshot.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,YAAY,EAElB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,gBAAgB,EAAuB,MAAM,2BAA2B,CAAC;AAClF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,KAAK,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE9D,eAAO,MAAM,0BAA0B,2BAA2B,CAAC;AAEnE,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAe3B;AAED,wBAAsB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAG3F;AAED,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;CAC7B;AAED,wBAAsB,uCAAuC,CAAC,KAAK,EAAE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC,GAAG,OAAO,CAAC,mCAAmC,CAAC,CAkC/C"}

package/dist/runtime/run/manifest-snapshot.js

@@ -0,0 +1,58 @@
+// Runtime manifest snapshot persistence. A run stores the exact compiled-flow
+// bytes it started with so resume and status projection use the same flow even
+// if generated files change later. Graph execution only passes the bytes
+// through.
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { CompiledFlow as CompiledFlowSchema, } from '../../schemas/compiled-flow.js';
+import { CompiledFlowId, RunId } from '../../schemas/ids.js';
+import { ManifestSnapshot, computeManifestHash } from '../../schemas/manifest.js';
+export const MANIFEST_SNAPSHOT_RUN_FILE = 'manifest.snapshot.json';
+export function runtimeManifestSnapshotPath(runDir) {
+    return join(runDir, MANIFEST_SNAPSHOT_RUN_FILE);
+}
+export async function writeRuntimeManifestSnapshot(input) {
+    const bytes = Buffer.from(input.bytes);
+    const snapshot = ManifestSnapshot.parse({
+        schema_version: 1,
+        run_id: RunId.parse(input.runId),
+        flow_id: CompiledFlowId.parse(input.flowId),
+        captured_at: input.capturedAt,
+        algorithm: 'sha256-raw',
+        hash: computeManifestHash(bytes),
+        bytes_base64: bytes.toString('base64'),
+    });
+    const path = runtimeManifestSnapshotPath(input.runDir);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(snapshot, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+    return snapshot;
+}
+export async function readRuntimeManifestSnapshot(runDir) {
+    const raw = JSON.parse(await readFile(runtimeManifestSnapshotPath(runDir), 'utf8'));
+    return ManifestSnapshot.parse(raw);
+}
+export async function readRuntimeCompiledFlowManifestSnapshot(input) {
+    const snapshot = await readRuntimeManifestSnapshot(input.runDir);
+    if (input.expectedRunId !== undefined && snapshot.run_id !== input.expectedRunId) {
+        throw new Error(`manifest snapshot run_id mismatch: expected '${input.expectedRunId}' but found '${snapshot.run_id}'`);
+    }
+    if (input.expectedFlowId !== undefined && snapshot.flow_id !== input.expectedFlowId) {
+        throw new Error(`manifest snapshot flow_id mismatch: expected '${input.expectedFlowId}' but found '${snapshot.flow_id}'`);
+    }
+    if (input.expectedHash !== undefined && snapshot.hash !== input.expectedHash) {
+        throw new Error(`manifest snapshot hash mismatch: expected '${input.expectedHash}' but found '${snapshot.hash}'`);
+    }
+    const flowBytes = Buffer.from(snapshot.bytes_base64, 'base64');
+    let flow;
+    try {
+        flow = CompiledFlowSchema.parse(JSON.parse(flowBytes.toString('utf8')));
+    }
+    catch (error) {
+        throw new Error(`manifest snapshot bytes do not parse as CompiledFlow: ${error.message}`);
+    }
+    if (flow.id !== snapshot.flow_id) {
+        throw new Error(`manifest snapshot flow_id '${snapshot.flow_id}' does not match compiled flow id '${flow.id}'`);
+    }
+    return { snapshot, flowBytes, flow };
+}
+//# sourceMappingURL=manifest-snapshot.js.map

package/dist/runtime/run/manifest-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-snapshot.js","sourceRoot":"","sources":["../../../src/runtime/run/manifest-snapshot.ts"],"names":[],"mappings":"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"}

package/dist/runtime/run/oracle-command-pin.d.ts

@@ -0,0 +1,20 @@
+import { type ProofPlanCommand } from '../../shared/proof-plan.js';
+interface PinnedOracle {
+    readonly commands: readonly ProofPlanCommand[];
+    readonly scriptFingerprints: ReadonlyMap<string, string>;
+}
+export interface OracleCommandPinChannel {
+    readonly pins: Map<string, PinnedOracle>;
+}
+export declare function createOracleCommandPinChannel(): OracleCommandPinChannel;
+export declare class OracleCommandDriftError extends Error {
+    constructor(message: string);
+}
+export declare function resolveOracleCommands(input: {
+    readonly channel: OracleCommandPinChannel;
+    readonly stepId: string;
+    readonly projectRoot: string;
+    readonly load: () => readonly ProofPlanCommand[];
+}): readonly ProofPlanCommand[];
+export {};
+//# sourceMappingURL=oracle-command-pin.d.ts.map

package/dist/runtime/run/oracle-command-pin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oracle-command-pin.d.ts","sourceRoot":"","sources":["../../../src/runtime/run/oracle-command-pin.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,4BAA4B,CAAC;AA0BpC,UAAU,YAAY;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAK/C,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC1C;AAED,wBAAgB,6BAA6B,IAAI,uBAAuB,CAEvE;AAKD,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAkED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,SAAS,gBAAgB,EAAE,CAAC;CAClD,GAAG,SAAS,gBAAgB,EAAE,CA6B9B"}

package/dist/runtime/run/oracle-command-pin.js

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sha256OfString } from '../../schemas/hashing.js';
+import { packageScriptInvocation, resolveProjectRelativeProofCwd, } from '../../shared/proof-plan.js';
+export function createOracleCommandPinChannel() {
+    return { pins: new Map() };
+}
+// Thrown when a pinned package-script body changed between waves. Caught by the
+// verification executor's try/catch, which turns it into a step failure so the
+// run aborts rather than trusting a rewritten oracle.
+export class OracleCommandDriftError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OracleCommandDriftError';
+    }
+}
+// Resolve the body string of the package script a command invokes, or undefined
+// if the command is not a package-script invocation. Throws if the script is
+// referenced but its package.json cannot be read or the script is missing —
+// the same conditions the proof-plan preflight already rejects, surfaced here
+// so a pinned script that disappears is a drift, not a silent passthrough.
+function readReferencedScriptBody(command, projectRoot) {
+    const script = packageScriptInvocation(command);
+    if (script === undefined)
+        return undefined;
+    const cwdAbs = resolveProjectRelativeProofCwd(projectRoot, command.cwd);
+    const packageJsonPath = join(cwdAbs, 'package.json');
+    if (!existsSync(packageJsonPath)) {
+        throw new OracleCommandDriftError(`oracle script "${script}" for command '${command.id}' vanished: package.json missing at its cwd`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new OracleCommandDriftError(`oracle script "${script}" for command '${command.id}' unreadable: ${message}`);
+    }
+    const scripts = parsed && typeof parsed === 'object' ? parsed.scripts : undefined;
+    const body = scripts && typeof scripts === 'object' && !Array.isArray(scripts)
+        ? scripts[script]
+        : undefined;
+    if (typeof body !== 'string') {
+        throw new OracleCommandDriftError(`oracle script "${script}" for command '${command.id}' vanished from package.json since the loop entered`);
+    }
+    return { script, body };
+}
+function fingerprintCommands(commands, projectRoot) {
+    const fingerprints = new Map();
+    for (const command of commands) {
+        const referenced = readReferencedScriptBody(command, projectRoot);
+        if (referenced === undefined)
+            continue;
+        fingerprints.set(command.id, sha256OfString(referenced.body));
+    }
+    return fingerprints;
+}
+// Serve the same resolved oracle command list for a step across every wave of a
+// loop, and reject a drifted package-script body.
+//
+// First call for `stepId`: run `load()`, fingerprint referenced script bodies,
+// cache both, and return the freshly loaded commands. Every later call: ignore
+// what `load()` would now return (that is the narrowing vector — never read it),
+// re-fingerprint the pinned commands' scripts against the current package.json,
+// throw OracleCommandDriftError on any mismatch, and otherwise return the
+// pinned commands.
+export function resolveOracleCommands(input) {
+    const { channel, stepId, projectRoot, load } = input;
+    const existing = channel.pins.get(stepId);
+    if (existing === undefined) {
+        const commands = load();
+        const scriptFingerprints = fingerprintCommands(commands, projectRoot);
+        channel.pins.set(stepId, { commands, scriptFingerprints });
+        return commands;
+    }
+    // Re-check every pinned script body against what is on disk now. The pinned
+    // commands are the source of truth for what runs; `load()` is deliberately
+    // not called, so a narrowed plan cannot take effect.
+    for (const command of existing.commands) {
+        const pinnedFingerprint = existing.scriptFingerprints.get(command.id);
+        if (pinnedFingerprint === undefined)
+            continue;
+        const referenced = readReferencedScriptBody(command, projectRoot);
+        // readReferencedScriptBody throws if the script vanished; a defined result
+        // with a changed body is the swap vector.
+        const currentFingerprint = referenced === undefined ? undefined : sha256OfString(referenced.body);
+        if (currentFingerprint !== pinnedFingerprint) {
+            const scriptName = packageScriptInvocation(command) ?? command.id;
+            throw new OracleCommandDriftError(`oracle script "${scriptName}" changed since the loop entered; refusing to trust a rewritten verification command`);
+        }
+    }
+    return existing.commands;
+}
+//# sourceMappingURL=oracle-command-pin.js.map

package/dist/runtime/run/oracle-command-pin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oracle-command-pin.js","sourceRoot":"","sources":["../../../src/runtime/run/oracle-command-pin.ts"],"names":[],"mappings":"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"}

package/dist/runtime/run/recovery-binding-verdict.d.ts

@@ -0,0 +1,40 @@
+import type { RecoveryFailureCause, RecoveryRouteBindingV0 } from '../../schemas/recovery-route-kind.js';
+import type { Ref } from '../../schemas/ref.js';
+export interface RecoveryFailureEvidence {
+    readonly ref: Ref;
+    readonly cause: RecoveryFailureCause;
+}
+export interface RecoveryBindingVerdictInput {
+    /** Present only when the run is bound by a WorkContract; binding rules are inert otherwise. */
+    readonly workContractRef: Ref | undefined;
+    readonly stepId: string;
+    readonly stepKind: string;
+    readonly route: string;
+    /** Whether the selected route carries recovery mechanics (a matching binding shape). */
+    readonly routeHasRecoveryMechanics: boolean;
+    /** Failure evidence derived for the completed route, if any. */
+    readonly recoveryFailure: RecoveryFailureEvidence | undefined;
+    /** The WorkContract binding for the completed route, if one is declared. */
+    readonly recoveryBinding: RecoveryRouteBindingV0 | undefined;
+}
+export type RecoveryBindingVerdict = {
+    readonly kind: 'ok';
+} | {
+    readonly kind: 'abort';
+    readonly reason: string;
+};
+export declare function recoveryCauseAllowed(binding: RecoveryRouteBindingV0, cause: RecoveryFailureCause): boolean;
+/**
+ * Decide whether a completed recovery route violates its WorkContract binding.
+ *
+ * Mirrors the three recovery-binding aborts the graph-runner loop previously
+ * inlined, in order:
+ *  1. recovery mechanics with no failure evidence  -> "without failure evidence"
+ *  2. failure evidence with no matching binding     -> missingRecoveryBindingReason
+ *  3. failure evidence whose cause the binding bans  -> recoveryCauseNotAllowedReason
+ *
+ * Returns `{ kind: 'ok' }` when the route is permitted (including every case
+ * where no WorkContract binds the run).
+ */
+export declare function recoveryBindingVerdict(input: RecoveryBindingVerdictInput): RecoveryBindingVerdict;
+//# sourceMappingURL=recovery-binding-verdict.d.ts.map

package/dist/runtime/run/recovery-binding-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-binding-verdict.d.ts","sourceRoot":"","sources":["../../../src/runtime/run/recovery-binding-verdict.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAED,MAAM,WAAW,2BAA2B;IAC1C,+FAA+F;IAC/F,QAAQ,CAAC,eAAe,EAAE,GAAG,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,eAAe,EAAE,uBAAuB,GAAG,SAAS,CAAC;IAC9D,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,EAAE,sBAAsB,GAAG,SAAS,CAAC;CAC9D;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAIxD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAET;AA0BD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,sBAAsB,CAuCjG"}

package/dist/runtime/run/recovery-binding-verdict.js

@@ -0,0 +1,70 @@
+// Pure WorkContract recovery-binding enforcement.
+//
+// Given the recovery evidence and binding resolved for a completed route, this
+// returns whether the run must abort because the route violates its WorkContract
+// recovery binding. It performs no IO: the graph-runner loop acts on the verdict
+// (appending step.aborted and closing the run) so the binding rules stay
+// unit-testable in isolation. The abort-reason strings are part of the runtime
+// contract and are pinned by tests; do not change them.
+const OK = { kind: 'ok' };
+export function recoveryCauseAllowed(binding, cause) {
+    return binding.allowed_failure_causes.includes(cause);
+}
+function missingRecoveryBindingReason(input) {
+    return `step '${input.stepId}' selected recovery route '${input.route}' after ${input.cause} but the WorkContract does not declare a matching recovery binding`;
+}
+function recoveryCauseNotAllowedReason(input) {
+    return `step '${input.stepId}' selected recovery route '${input.route}' for ${input.cause}, but its WorkContract binding only allows: ${input.binding.allowed_failure_causes.join(', ')}`;
+}
+function missingFailureEvidenceReason(input) {
+    return `step '${input.stepId}' selected recovery route '${input.route}' without failure evidence`;
+}
+/**
+ * Decide whether a completed recovery route violates its WorkContract binding.
+ *
+ * Mirrors the three recovery-binding aborts the graph-runner loop previously
+ * inlined, in order:
+ *  1. recovery mechanics with no failure evidence  -> "without failure evidence"
+ *  2. failure evidence with no matching binding     -> missingRecoveryBindingReason
+ *  3. failure evidence whose cause the binding bans  -> recoveryCauseNotAllowedReason
+ *
+ * Returns `{ kind: 'ok' }` when the route is permitted (including every case
+ * where no WorkContract binds the run).
+ */
+export function recoveryBindingVerdict(input) {
+    if (input.workContractRef === undefined)
+        return OK;
+    if (input.stepKind !== 'checkpoint' &&
+        input.routeHasRecoveryMechanics &&
+        input.recoveryFailure === undefined) {
+        return {
+            kind: 'abort',
+            reason: missingFailureEvidenceReason({ stepId: input.stepId, route: input.route }),
+        };
+    }
+    if (input.recoveryFailure !== undefined) {
+        if (input.recoveryBinding === undefined) {
+            return {
+                kind: 'abort',
+                reason: missingRecoveryBindingReason({
+                    stepId: input.stepId,
+                    route: input.route,
+                    cause: input.recoveryFailure.cause,
+                }),
+            };
+        }
+        if (!recoveryCauseAllowed(input.recoveryBinding, input.recoveryFailure.cause)) {
+            return {
+                kind: 'abort',
+                reason: recoveryCauseNotAllowedReason({
+                    stepId: input.stepId,
+                    route: input.route,
+                    cause: input.recoveryFailure.cause,
+                    binding: input.recoveryBinding,
+                }),
+            };
+        }
+    }
+    return OK;
+}
+//# sourceMappingURL=recovery-binding-verdict.js.map

package/dist/runtime/run/recovery-binding-verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-binding-verdict.js","sourceRoot":"","sources":["../../../src/runtime/run/recovery-binding-verdict.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,+EAA+E;AAC/E,iFAAiF;AACjF,iFAAiF;AACjF,yEAAyE;AACzE,+EAA+E;AAC/E,wDAAwD;AA+BxD,MAAM,EAAE,GAA2B,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAElD,MAAM,UAAU,oBAAoB,CAClC,OAA+B,EAC/B,KAA2B;IAE3B,OAAO,OAAO,CAAC,sBAAsB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,4BAA4B,CAAC,KAIrC;IACC,OAAO,SAAS,KAAK,CAAC,MAAM,8BAA8B,KAAK,CAAC,KAAK,WAAW,KAAK,CAAC,KAAK,oEAAoE,CAAC;AAClK,CAAC;AAED,SAAS,6BAA6B,CAAC,KAKtC;IACC,OAAO,SAAS,KAAK,CAAC,MAAM,8BAA8B,KAAK,CAAC,KAAK,SAAS,KAAK,CAAC,KAAK,+CAA+C,KAAK,CAAC,OAAO,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC5L,CAAC;AAED,SAAS,4BAA4B,CAAC,KAGrC;IACC,OAAO,SAAS,KAAK,CAAC,MAAM,8BAA8B,KAAK,CAAC,KAAK,4BAA4B,CAAC;AACpG,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAkC;IACvE,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAEnD,IACE,KAAK,CAAC,QAAQ,KAAK,YAAY;QAC/B,KAAK,CAAC,yBAAyB;QAC/B,KAAK,CAAC,eAAe,KAAK,SAAS,EACnC,CAAC;QACD,OAAO;YACL,IAAI,EAAE,OAAO;YACb,MAAM,EAAE,4BAA4B,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;SACnF,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACxC,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YACxC,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,MAAM,EAAE,4BAA4B,CAAC;oBACnC,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,KAAK;iBACnC,CAAC;aACH,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9E,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,MAAM,EAAE,6BAA6B,CAAC;oBACpC,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,KAAK;oBAClC,OAAO,EAAE,KAAK,CAAC,eAAe;iBAC/B,CAAC;aACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/runtime/run/recovery-corridor.d.ts

@@ -0,0 +1,103 @@
+import type { RecoveryRouteBindingV0 } from '../../schemas/recovery-route-kind.js';
+import type { Ref } from '../../schemas/ref.js';
+import type { AcceptanceRetryFeedback } from '../acceptance-criteria.js';
+import type { TraceEntry } from '../domain/trace.js';
+import type { ExecutableStep } from '../manifest/executable-flow.js';
+import type { RecoveryFailureEvidence } from './recovery-binding-verdict.js';
+/** Decides whether a route on a step carries WorkContract recovery mechanics. */
+export type RouteHasRecoveryMechanics = (input: {
+    readonly step: ExecutableStep;
+    readonly route: string | undefined;
+}) => boolean;
+/** Resolves the latest step.report_written / relay.result ref for an attempt. */
+export type LatestStepReportOrRelayRef = (input: {
+    readonly stepId: string;
+    readonly attempt: number;
+}) => Ref | undefined;
+export interface RecoveryCorridorDeps {
+    readonly steps: ReadonlyMap<string, ExecutableStep>;
+    readonly bindings: readonly RecoveryRouteBindingV0[] | undefined;
+    readonly routeHasRecoveryMechanics: RouteHasRecoveryMechanics;
+    readonly latestStepReportOrRelayRef: LatestStepReportOrRelayRef;
+}
+export interface CorridorEnterInput {
+    readonly originStepId: string;
+    readonly route: string;
+    readonly recoveryReason: unknown;
+    readonly recoveryFailure: RecoveryFailureEvidence | undefined;
+    readonly acceptanceFeedback: AcceptanceRetryFeedback | undefined;
+}
+export declare class RecoveryCorridor {
+    private readonly deps;
+    private active;
+    constructor(deps: RecoveryCorridorDeps);
+    /** True when `route` is the recovery route this corridor is currently traversing. */
+    isActiveRoute(route: string | undefined): boolean;
+    /**
+     * True when stepping into `stepId` via `route` is a return toward the corridor
+     * origin through non-recovery routes (so re-entering a completed step is legal).
+     */
+    isReturnToOrigin(input: {
+        readonly stepId: string;
+        readonly route: string | undefined;
+    }): boolean;
+    /** The "; last recovery reason: ..." suffix for cycle/budget abort messages. */
+    lastReasonSuffix(): string;
+    /**
+     * Acceptance-retry feedback to surface when `stepId` re-enters as the corridor
+     * origin via the active recovery route.
+     */
+    acceptanceFeedbackForReentry(input: {
+        readonly stepId: string;
+        readonly incomingRoute: string | undefined;
+    }): AcceptanceRetryFeedback | undefined;
+    /**
+     * Failure evidence derived from the active corridor (when the completed route
+     * has recovery mechanics but no direct failure evidence of its own).
+     */
+    evidenceFor(input: {
+        readonly stepId: string;
+        readonly attempt: number;
+        readonly binding: RecoveryRouteBindingV0 | undefined;
+    }): RecoveryFailureEvidence | undefined;
+    /** Enter / advance the corridor when a step takes a recovery route. */
+    enter(input: CorridorEnterInput): void;
+    /**
+     * Clear the corridor when its origin step completes without taking a recovery
+     * route (the corridor has returned and exited).
+     */
+    clearIfExitingOrigin(input: {
+        readonly stepId: string;
+        readonly routeHasRecoveryMechanics: boolean;
+    }): void;
+    /**
+     * Checkpoint-resume reseed: replay the durable `step.completed` entries so a
+     * resumed run lands on the same STRUCTURAL corridor identity (which recovery
+     * route is active, with what origin step) the prior process held. Mirrors
+     * seedSkillHookInjectionsFromTrace / seedPowerInferenceFromTrace: a fold over
+     * existing trace entries into the in-memory channel, applying the exact
+     * enter / clearIfExitingOrigin transitions the live loop applies after each
+     * step completes (graph-runner: enter on a recovery-mechanics route, then
+     * clearIfExitingOrigin when the origin re-completes without mechanics).
+     *
+     * Faithfulness boundary — read before relying on this. The durable
+     * `step.completed` entry carries only `route_taken` (+ ids/attempt/slice).
+     * The live `enter()` also took executor-outcome fields — `recoveryReason`
+     * (details.reason), `recoveryFailure`, and `acceptanceFeedback`
+     * (details.acceptance_feedback) — that are NOT persisted to the trace. This
+     * reseed therefore restores ONLY the structural fields (originStepId, route)
+     * and deliberately leaves the payload fields undefined. The consequence is
+     * exact: after reseed `lastReasonSuffix()` returns '' and
+     * `acceptanceFeedbackForReentry()` returns undefined even where the live run
+     * carried a reason / feedback. `evidenceFor()` likewise has no seeded failure
+     * to surface. That payload gap is the spec line for the full cursor
+     * (docs/ideas/durability-tier2-cursor-spec.md); restoring it requires
+     * persisting those fields, which is out of scope for this foundation slice.
+     *
+     * This is plumbing ahead of its consumer: no current code path resumes at an
+     * arbitrary step.completed, so this is inert until a Tier-2 cursor calls it.
+     */
+    seedFromTrace(entries: readonly TraceEntry[]): void;
+    private canReachStepViaNonRecoveryRoutes;
+}
+//# sourceMappingURL=recovery-corridor.d.ts.map

package/dist/runtime/run/recovery-corridor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-corridor.d.ts","sourceRoot":"","sources":["../../../src/runtime/run/recovery-corridor.ts"],"names":[],"mappings":"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"}