@smartmemory/stratum 0.3.3 → 0.4.0

package/dist/engine/engine.js

@@ -4,13 +4,50 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
+import { z } from "zod";
 import { runAgent } from "../connectors/runner.js";
 import { extractReferences } from "../ir/refs.js";
 import { validateSpec } from "../ir/validate.js";
-import { BudgetLedger, validUsage } from "./ledger.js";
+import { LearnEgress } from "../learn/smartmemory_egress.js";
+import { mergeBundleIntoSpec, policyRuleKey, predicateType, validateBundle } from "../policy/bundle.js";
+import { buildFlowTerminalEvent, buildGateResolutionEvent } from "../policy/events.js";
+import { emitPolicyEvent as postPolicyEvent } from "../policy/smartmemory_client.js";
+import { BUDGET_KEYS, BudgetLedger, validConnectorTelemetry, validUsage } from "./ledger.js";
 import { commitCheckpoint, revertCheckpoint } from "./checkpoint.js";
+import { buildReceipt, findReceipt, ReceiptValidationError, spineSpent } from "./receipts.js";
 import { StateStore } from "./state.js";
 const execFileAsync = promisify(execFile);
+/**
+ * The fixed shape every S1 `evaluate:` step must return. Engine-owned and
+ * strict — an author's `out` contract governs what is *referenceable*, this
+ * schema governs what the data must *be*. It is the trust anchor: a transport
+ * failure can never be laundered into a `closed` verdict, and the cross-field
+ * invariants (`closed` ⇒ no children, `open` ⇒ ≥1 child) are enforced here.
+ */
+export const evaluatorResultSchema = z.object({
+    status: z.enum(["closed", "open", "failed"]),
+    children: z.array(z.unknown()),
+    reason: z.string(),
+    score: z.number().optional(),
+    route: z.enum(["claude", "codex"]).optional(),
+}).strict().superRefine((result, ctx) => {
+    if (result.status === "closed" && result.children.length > 0) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["children"], message: "a closed verdict must carry no children" });
+    }
+    if (result.status === "open" && result.children.length === 0) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["children"], message: "an open verdict must carry at least one child" });
+    }
+});
+/**
+ * The engine validates the runner's ENVELOPE at runtime, not just the verdict
+ * inside it — the `ok` discriminant is the runner's word for whether it even
+ * succeeded, and a malformed envelope must never let a `{status:"closed"}`
+ * payload reach the success path. Same trust posture as the judge verdict.
+ */
+const evaluateRunResultSchema = z.discriminatedUnion("ok", [
+    z.object({ ok: z.literal(true), result: z.unknown() }),
+    z.object({ ok: z.literal(false), kind: z.enum(["exit", "timeout", "parse"]), reason: z.string() }),
+]);
 export class CheckpointOperationError extends Error {
     errorType;
     available;
@@ -29,11 +66,17 @@ export class SpecValidationError extends Error {
         this.errors = errors;
     }
 }
+export class InputValidationError extends SpecValidationError {
+    constructor(errors) { super(errors); this.message = "entry input validation failed"; }
+}
 export class StratumEngine {
     store;
     evaluator;
     judge;
+    evaluateRunner;
     connector;
+    learnEgress;
+    learnEgressStartup;
     // Serializes load-modify-save per run: plan may hand out several ready steps, so
     // stepDone/resume can race in-process. The state root is owned by one engine process in v1.
     runLocks = new Map();
@@ -51,7 +94,19 @@ export class StratumEngine {
         this.evaluator = options.evaluator;
         if (options.judge)
             this.judge = options.judge;
+        if (options.evaluateRunner)
+            this.evaluateRunner = options.evaluateRunner;
         this.connector = options.connector ?? defaultConnector;
+        this.learnEgress = options.learnEgress ?? new LearnEgress({
+            ...options.learnEgressOptions,
+            store: this.store,
+            withReceiptUpdate: (runId, update) => this.withReceiptUpdate(runId, update),
+        });
+        this.learnEgressStartup = this.learnEgress.enabled()
+            ? this.learnEgress.drainAll().catch((error) => {
+                console.warn(`SmartMemory egress startup reconciliation failed: ${message(error)}`);
+            })
+            : Promise.resolve();
     }
     async loadRun(runId) {
         const active = this.activeRuns.get(runId);
@@ -85,27 +140,70 @@ export class StratumEngine {
         });
         return result;
     }
+    async withReceiptUpdate(runId, update) {
+        return this.withRunLock(runId, async () => {
+            const run = await this.loadRun(runId);
+            const result = await update(run);
+            await this.persist(run);
+            return result;
+        });
+    }
+    async closeLearnEgress() {
+        await this.learnEgressStartup;
+        await this.learnEgress.close();
+    }
     async plan(specInput, input, options = {}) {
         const validation = validateSpec(specInput);
         if (!validation.ok)
             throw new SpecValidationError(validation.errors);
-        const flowName = validation.value.flows.entry;
-        const flow = validation.value.flows[flowName];
+        let effectiveSpec = validation.value;
+        let policyFields = {};
+        if (options.policyBundle !== undefined) {
+            const bundle = validateBundle(options.policyBundle);
+            const merged = mergeBundleIntoSpec(effectiveSpec, bundle, options.policyStepSelector);
+            effectiveSpec = merged.spec;
+            policyFields = { bundle_id: merged.bundle_id, policy_rules: merged.policy_rules, policy_rules_version: 2, policy_verdicts: [] };
+            const policyBindings = Object.values(merged.policy_rules).flat();
+            const ruleCount = new Set(policyBindings.map((binding) => binding.rule_id)).size;
+            console.warn(`policy bundle ${merged.bundle_id}: ${ruleCount} rules bound to ${policyBindings.length} step-predicate pairs`);
+            if (bundle.rules.some((rule) => rule.bind.kind === "ensure" && rule.on_fail === "gate")) {
+                console.warn("ensure policy rule on_fail=gate is enforced as refuse in P1; gate routing is deferred to P3");
+            }
+        }
+        // Validate the policy-merged specification and entry input before allocating
+        // or persisting a run. A rejected request must never dispatch work.
+        const effectiveValidation = validateSpec(effectiveSpec);
+        if (!effectiveValidation.ok)
+            throw new SpecValidationError(effectiveValidation.errors);
+        effectiveSpec = effectiveValidation.value;
+        const flowName = effectiveSpec.flows.entry;
+        const parsedInput = effectiveValidation.inputs[flowName]?.safeParse(input);
+        if (!parsedInput)
+            throw new Error("entry flow input contract missing after validation");
+        if (!parsedInput.success) {
+            throw new InputValidationError(parsedInput.error.issues.map((issue) => ({
+                code: "INPUT_CONTRACT_INVALID",
+                path: ["input", ...issue.path].map((part, index) => typeof part === "number" ? `[${part}]` : index === 0 ? part : `.${part}`).join(""),
+                message: issue.message,
+            })));
+        }
+        const flow = effectiveSpec.flows[flowName];
         if (!flow)
             throw new Error("entry flow missing after validation");
         const steps = Object.create(null);
         for (const step of flow.steps)
             steps[step.id] = { status: "pending", attempts: [], spent: {} };
         const run = {
-            id: randomUUID(), spec: validation.value, revisionDigest: digest(validation.value), generationCounter: 0,
-            input, flowName, status: "running", flowSpent: {}, steps,
+            id: randomUUID(), spec: effectiveSpec, revisionDigest: digest(effectiveSpec), generationCounter: 0,
+            input: parsedInput.data, flowName, status: "running", flowSpent: {}, steps,
             events: [{ at: now(), type: "planned" }],
+            ...policyFields,
             // Canonicalize at plan time: a relative root must never re-resolve against a
             // different process cwd after restart.
             ...(options.workspaceRoot !== undefined ? { workspaceRoot: resolve(options.workspaceRoot) } : {}),
         };
         await this.persist(run);
-        return this.withRevisionDigest(await this.advance(run, validation.value, validation.contracts), run);
+        return this.withRevisionDigest(await this.advance(run, effectiveValidation.value, effectiveValidation.contracts), run);
     }
     async flowRunBg(specInput, input, options = {}) {
         const validation = validateSpec(specInput);
@@ -253,7 +351,9 @@ export class StratumEngine {
         const usage = { ...reported };
         delete usage.dispatches;
         // "settle": the agent already ran, so over-limit usage is still recorded in both ledgers.
-        const budgetFailure = this.debit(run, step, state, usage, "settle", scope);
+        const budgetFailure = hasBudget(usage)
+            ? this.settleLegacyReceipt(run, usage, "step_done", telemetry, { scope, step, state }, result.usdSource, result.split)
+            : undefined;
         if (budgetFailure === "flow") {
             const failure = { attempt, reason: "flow budget exhausted" };
             state.attempts.push({ attempt, at: now(), failure, ...telemetryFields(telemetry), ...(hasBudget(usage) ? { usage } : {}) });
@@ -329,6 +429,70 @@ export class StratumEngine {
         await this.persist(run);
         return this.advance(run, validated.value, validated.contracts, scope);
     }
+    async usageReport(runId, input) {
+        return this.withRunLock(runId, async () => {
+            if (typeof input === "object" && input !== null && input.usdSource === "legacy") {
+                throw new ReceiptValidationError('usdSource "legacy" is reserved for engine-synthesized receipts');
+            }
+            const run = await this.loadRun(runId);
+            const candidate = input;
+            if (typeof input !== "object" || input === null || Array.isArray(input)
+                || typeof candidate?.dispatchId !== "string" || candidate.dispatchId.length === 0) {
+                throw new ReceiptValidationError("dispatchId must be a non-empty string");
+            }
+            if (candidate.dispatchId.startsWith("legacy:")) {
+                throw new ReceiptValidationError('dispatchId prefix "legacy:" is reserved for engine-synthesized receipts');
+            }
+            if (candidate.dispatchId.startsWith("engine:")) {
+                throw new ReceiptValidationError('dispatchId prefix "engine:" is reserved for engine-synthesized receipts');
+            }
+            const duplicate = findReceipt(run, candidate.dispatchId);
+            if (duplicate !== undefined) {
+                return { status: "duplicate", runId: run.id, seq: duplicate.seq, ledger: this.ledgerInfo(run) };
+            }
+            // Validate and allocate against a staging copy so a rejected receipt cannot
+            // advance the live counter (important while an active fanout pins the run object).
+            const staged = { ...run };
+            const receipt = buildReceipt(staged, input);
+            const located = receipt.stepId === undefined
+                ? undefined
+                : this.locateReceiptStep(run, this.validationFor(run).value, receipt.stepId);
+            if (receipt.stepId !== undefined && located === undefined) {
+                throw new ReceiptValidationError(`receipt step ${JSON.stringify(receipt.stepId)} does not exist`, "invalid_step");
+            }
+            run.receiptCounter = receipt.seq;
+            const wasRunning = run.status === "running";
+            const settled = this.settleReceipt(run, receipt, located);
+            if (settled.status === "duplicate") {
+                return { status: "duplicate", runId: run.id, seq: settled.receipt.seq, ledger: this.ledgerInfo(run) };
+            }
+            let budget;
+            if (settled.budget === "flow") {
+                budget = wasRunning ? "flow_exhausted" : "flow_exhausted_after_terminal";
+                if (wasRunning) {
+                    const attempt = located?.item?.attempts.length ?? located?.state.attempts.length ?? 0;
+                    await this.terminalBudget(run, { attempt: attempt + 1, reason: "flow budget exhausted" });
+                }
+                else {
+                    await this.persist(run);
+                }
+            }
+            else {
+                if (settled.budget === "subflow")
+                    budget = "subflow_exhausted";
+                if (settled.budget === "task")
+                    budget = "task_exhausted";
+                await this.persist(run);
+            }
+            return {
+                status: "ok",
+                runId: run.id,
+                seq: receipt.seq,
+                ...(budget !== undefined ? { budget } : {}),
+                ledger: this.ledgerInfo(run),
+            };
+        });
+    }
     async commit(runId, label) {
         this.assertExternalMutationAllowed(runId, "commit");
         return await this.withRunLock(runId, async () => {
@@ -357,12 +521,39 @@ export class StratumEngine {
             const run = await this.loadCheckpointRun(runId);
             this.assertNoForegroundFanout(run, "revert");
             const normalized = label.trim();
+            // Money spent is spent: a revert restores state, never spend. Capture the live
+            // cumulative total before the snapshot overwrites it.
+            const liveSpentBeforeRevert = { ...run.flowSpent };
             if (!revertCheckpoint(run, normalized)) {
                 // Insertion order, matching Python (list(state.checkpoints.keys())) and the commit
                 // envelope's `checkpoints` — not sorted, and robust to numeric labels (array, not object).
                 const available = (run.checkpoints ?? []).map((entry) => entry.label);
                 throw new CheckpointOperationError("checkpoint_not_found", `No checkpoint '${normalized}' on flow '${runId}'`, available);
             }
+            const receiptsAtRevert = run.receiptCounter ?? 0;
+            const stepsRestored = Object.keys(run.steps);
+            // flowSpent is monotonic across reverts: the live pre-revert total already
+            // includes every receipt (spine) plus any pre-receipt legacy spend, so it is
+            // the correct value in both the receipt-era and the upgraded-mid-run case.
+            // The spine is kept as a floor (defense against a corrupted live total); the
+            // restored snapshot is never consulted for spend.
+            const spine = spineSpent(run);
+            const reconciled = {};
+            for (const key of BUDGET_KEYS) {
+                const value = Math.max(liveSpentBeforeRevert[key] ?? 0, spine[key] ?? 0);
+                if (value !== 0)
+                    reconciled[key] = value;
+            }
+            run.flowSpent = reconciled;
+            const detail = { label: normalized, receiptsAtRevert, stepsRestored };
+            this.event(run, "checkpoint_reverted", undefined, detail);
+            const checkpointReceiptSeq = receiptsAtRevert + 1;
+            (run.receipts ??= []).push(buildReceipt(run, {
+                dispatchId: `engine:checkpoint_reverted:${checkpointReceiptSeq}`,
+                source: "engine",
+                usage: {},
+                detail,
+            }));
             this.rotateRestoredIssuances(run);
             await this.persist(run);
             return { ...await this.reAdvanceLocked(runId), reverted_to: normalized };
@@ -411,7 +602,10 @@ export class StratumEngine {
     async flowPoll(runId, cursor = 0) {
         if (!Number.isInteger(cursor) || cursor < 0)
             throw new Error("invalid event cursor");
-        const run = await this.loadRun(runId);
+        // Active fanouts pin a mutable run and set terminal status before save()
+        // finishes. Observers must see only committed state; otherwise "completed"
+        // can race the final write/rename and disagree with a restarted engine.
+        const run = await this.store.load(runId);
         return {
             runId,
             status: run.status,
@@ -423,18 +617,19 @@ export class StratumEngine {
         };
     }
     async flowBgPoll(runId, cursor = 0) {
-        const flow = await this.flowPoll(runId, cursor);
         const bg = this.bgFlows.get(runId);
         if (!bg)
             throw new Error(`background flow ${runId} not found`);
-        return {
-            ...flow,
-            bg: {
-                status: bg.status,
-                cancelRequested: bg.cancelRequested,
-                pendingGates: [...bg.pendingGates],
-            },
+        // Capture driver state before reading disk. A terminal driver status is set
+        // only after persistence, so this ordering cannot pair bg.completed with an
+        // older running snapshot when the driver finishes during the asynchronous read.
+        const driver = {
+            status: bg.status,
+            cancelRequested: bg.cancelRequested,
+            pendingGates: [...bg.pendingGates],
         };
+        const flow = await this.flowPoll(runId, cursor);
+        return { ...flow, bg: driver };
     }
     async flowCancelBg(runId) {
         const bg = this.bgFlows.get(runId);
@@ -459,8 +654,20 @@ export class StratumEngine {
         }
         return { status: bg.status };
     }
-    async gateResolve(runId, stepId, decision, gateToken) {
+    async gateResolve(runId, stepId, decision, gateToken, userId) {
         const response = await this.withRunLock(runId, () => this.gateResolveLocked(runId, stepId, decision, gateToken));
+        const resolvedRun = await this.loadRun(runId);
+        if (resolvedRun.bundle_id !== undefined) {
+            const round = resolvedRun.events.filter((event) => event.type === "gate_resolved" && event.stepId === stepId).length;
+            this.firePolicyEvent(buildGateResolutionEvent({
+                runId,
+                bundleId: resolvedRun.bundle_id,
+                stepId,
+                round,
+                outcome: decision,
+                ...(userId !== undefined ? { resolvedByUserId: userId } : {}),
+            }));
+        }
         const bg = this.bgFlows.get(runId);
         if (bg?.status === "paused_gate" && response.status !== "ready" && response.status !== "running") {
             bg.status = response.status;
@@ -532,7 +739,7 @@ export class StratumEngine {
                 scope.parent.state.sub.rounds = total;
             else
                 run.rounds = total;
-            this.resetFrom(scope.flow, scope.steps, target);
+            this.resetFrom(run, scope, target);
             // The target's descendants include this gate; retain its local revision counter.
             scope.steps[step.id].iterations = gateRounds + 1;
             await this.persist(run);
@@ -560,7 +767,7 @@ export class StratumEngine {
         return this.advance(run, validated.value, validated.contracts, scope);
     }
     async completeTerminalGate(run, flow, contracts) {
-        const output = this.resolveFlowOutput({ input: run.input, steps: run.steps, flow });
+        const output = this.resolveFlowOutput({ input: run.input, steps: run.steps, flow, flowName: run.flowName });
         const parsed = contracts[flow.output.contract]?.safeParse(output);
         if (!parsed?.success)
             return this.terminalFailure(run, { attempt: 0, reason: parsed?.error.message ?? "flow output contract missing" });
@@ -568,6 +775,7 @@ export class StratumEngine {
         run.status = "completed";
         this.event(run, "completed", undefined, { output });
         await this.persist(run);
+        this.emitFlowTerminal(run);
         return this.response(run);
     }
     /** Re-derive a run's response after async fanout/subflow progress without
@@ -737,6 +945,7 @@ export class StratumEngine {
             run.status = "completed";
             this.event(run, "completed", undefined, { output });
             await this.persist(run);
+            this.emitFlowTerminal(run);
             return this.response(run);
         }
         return this.failScope(run, spec, contracts, scope, "no runnable steps remain");
@@ -895,6 +1104,74 @@ export class StratumEngine {
                         break;
                     }
                 }
+                if (step.evaluate !== undefined) {
+                    const attempt = state.attempts.length + 1;
+                    const evaluate = step.evaluate;
+                    // Deterministic, single-shot, and atomic: no intermediate `running`
+                    // is persisted, so a crash mid-evaluate leaves the step `pending` and
+                    // it re-runs on resume. `forceExhausted` terminalizes every failure —
+                    // retrying a deterministic evaluator is pointless (backtrack is S3).
+                    const evalFail = (reason) => this.failAttempt(run, spec, contracts, scope, step, state, attempt, reason, {}, undefined, undefined, true);
+                    if (!this.evaluateRunner) {
+                        await evalFail("evaluate: no evaluate runner configured");
+                        changed = true;
+                        break;
+                    }
+                    let input;
+                    try {
+                        input = evaluate.in === undefined ? undefined : this.renderValue(evaluate.in, scope);
+                    }
+                    catch (error) {
+                        await evalFail(`evaluate: input render failed: ${message(error)}`);
+                        changed = true;
+                        break;
+                    }
+                    // Sandboxing (workspaceRoot jail) is deferred — see design open question 3.
+                    let rawOutcome;
+                    try {
+                        rawOutcome = await this.evaluateRunner({ command: evaluate.command, input, timeoutMs: evaluate.timeout_ms }, {});
+                    }
+                    catch (error) {
+                        await evalFail(`evaluate: runner threw: ${message(error)}`);
+                        changed = true;
+                        break;
+                    }
+                    const envelope = evaluateRunResultSchema.safeParse(rawOutcome);
+                    if (!envelope.success) {
+                        await evalFail(`evaluate: runner returned a malformed result envelope: ${envelope.error.message}`);
+                        changed = true;
+                        break;
+                    }
+                    const outcome = envelope.data;
+                    if (!outcome.ok) {
+                        const detail = outcome.reason;
+                        const reason = outcome.kind === "exit" ? `evaluate: command exited with a non-zero status (${detail})`
+                            : outcome.kind === "timeout" ? `evaluate: command timed out (${detail})`
+                                : `evaluate: output was not valid JSON (${detail})`;
+                        await evalFail(reason);
+                        changed = true;
+                        break;
+                    }
+                    const parsed = evaluatorResultSchema.safeParse(outcome.result);
+                    if (!parsed.success) {
+                        await evalFail(`evaluate: output failed the evaluator-result contract: ${parsed.error.message}`);
+                        changed = true;
+                        break;
+                    }
+                    const outError = this.contractError(step, parsed.data, contracts);
+                    if (outError) {
+                        await evalFail(`evaluate: output failed the ${step.out} contract: ${outError}`);
+                        changed = true;
+                        break;
+                    }
+                    state.status = "succeeded";
+                    state.output = parsed.data;
+                    state.attempts.push({ attempt, at: now(), result: parsed.data });
+                    this.event(run, "result", this.scopedId(scope, step.id), { attempt, result: parsed.data });
+                    await this.persist(run);
+                    changed = true;
+                    continue;
+                }
                 if (step.do === undefined) {
                     await this.failScope(run, spec, contracts, scope, "construct is outside P1 engine scope");
                     break;
@@ -1362,7 +1639,11 @@ export class StratumEngine {
         const usage = { ...(result.usage ?? {}) };
         const reportedDispatches = usage.dispatches !== undefined;
         delete usage.dispatches;
-        const settled = this.debit(run, step, state, usage, "settle");
+        const settled = hasBudget(usage)
+            ? this.settleLegacyReceipt(run, usage, "fanout", result.telemetry, {
+                scope: this.rootScope(run, spec), step, state, item,
+            }, result.usdSource, result.split)
+            : undefined;
         if (hasBudget(usage))
             this.event(run, "fanout_ledger_debit", step.id, { itemIndex: item.index, amount: usage });
         const stageStep = { ...step, do: stage.do, out: stage.out, ensure: stage.ensure, budget: step.budget };
@@ -1484,7 +1765,7 @@ export class StratumEngine {
     }
     /** Evaluates a step's ensure list in order; the first failing predicate wins. */
     async runEnsures(run, step, state, output, scope = this.rootScope(run, this.validationFor(run).value), fanoutItem) {
-        for (const predicate of step.ensure ?? []) {
+        for (const [ensureIndex, predicate] of (step.ensure ?? []).entries()) {
             if ("judged" in predicate) {
                 const { statement, stakes } = predicate.judged;
                 // The runner is an injected seam — validate its outcome; a malformed shape
@@ -1523,12 +1804,24 @@ export class StratumEngine {
                         failureReason = `judged predicate failed: ${message(error)}`;
                     }
                 }
-                const usage = outcome?.usage ?? {};
-                const budgetFailure = hasBudget(usage) ? this.debit(run, step, state, usage, "settle", scope) : undefined;
+                const usage = { ...(outcome?.usage ?? {}) };
+                const judgedUsageAsReported = { ...usage };
+                // A judge may report `dispatches`; that key is ledger-only (never a receipt)
+                // and keeps its pre-receipt settle semantics.
+                const judgedDispatches = usage.dispatches !== undefined ? { dispatches: usage.dispatches } : undefined;
+                delete usage.dispatches;
+                const receiptItem = fanoutItem === undefined ? undefined : state.fanout?.items[fanoutItem.itemIndex];
+                const dispatchFailure = judgedDispatches !== undefined ? this.debit(run, step, state, judgedDispatches, "settle", scope) : undefined;
+                const costFailure = hasBudget(usage)
+                    ? this.settleLegacyReceipt(run, usage, "judged", outcome?.model === undefined ? undefined : {
+                        model: outcome.model.length > 0 ? outcome.model : "unknown", durationMs: 0,
+                    }, { scope, step, state, ...(receiptItem !== undefined ? { item: receiptItem } : {}) })
+                    : undefined;
+                const budgetFailure = worstBudget(dispatchFailure, costFailure);
                 // A judged debit inside a fanout item must stay visible per item — the
                 // observability contract forbids anonymous ledger movement.
-                if (fanoutItem && hasBudget(usage)) {
-                    this.event(run, "fanout_ledger_debit", step.id, { itemIndex: fanoutItem.itemIndex, amount: usage, source: "judged" });
+                if (fanoutItem && hasBudget(judgedUsageAsReported)) {
+                    this.event(run, "fanout_ledger_debit", step.id, { itemIndex: fanoutItem.itemIndex, amount: judgedUsageAsReported, source: "judged" });
                 }
                 // Fixed audit payload — every judged evaluation events, failures included.
                 this.event(run, "judged", this.scopedId(scope, step.id), {
@@ -1541,6 +1834,7 @@ export class StratumEngine {
                     usage: { tokens: usage.tokens ?? 0, usd: usage.usd ?? 0 },
                     ...(fanoutItem ? { itemIndex: fanoutItem.itemIndex, stage: fanoutItem.stage } : {}),
                 });
+                this.recordPolicyVerdict(run, scope.flowName, step.id, ensureIndex, failureReason === undefined && outcome?.holds === true, "judged");
                 if (budgetFailure === "flow")
                     return { kind: "flow_budget" };
                 if (budgetFailure === "subflow")
@@ -1560,6 +1854,7 @@ export class StratumEngine {
                     ? `file_exists(${JSON.stringify(predicate.file_exists)})`
                     : `file_contains(${JSON.stringify(predicate.file_contains.path)}, ${JSON.stringify(predicate.file_contains.text)})`;
             const verdict = this.ensurePredicate(expression, run, output, scope, fanoutItem);
+            this.recordPolicyVerdict(run, scope.flowName, step.id, ensureIndex, verdict.holds, predicateType(predicate));
             if (!verdict.holds)
                 return { kind: "fail", reason: `ensure ${JSON.stringify(expression)} failed: ${verdict.reason}` };
         }
@@ -1624,6 +1919,90 @@ export class StratumEngine {
             return "task";
         return undefined;
     }
+    settleReceipt(run, receipt, located, explicitAttempt) {
+        const duplicate = findReceipt(run, receipt.dispatchId);
+        if (duplicate !== undefined)
+            return { status: "duplicate", receipt: duplicate };
+        const canonicalStepId = located === undefined ? undefined : this.scopedId(located.scope, located.step.id);
+        if (canonicalStepId !== undefined)
+            receipt.stepId = canonicalStepId;
+        let budget;
+        const executable = located !== undefined && (located.step.do !== undefined || located.step.fanout !== undefined);
+        if (executable) {
+            budget = this.debit(run, located.step, located.state, receipt.amount, "settle", located.scope);
+        }
+        else {
+            const flowLedger = new BudgetLedger(this.flowFor(run, this.validationFor(run).value).budget, run.flowSpent);
+            const subflowLedger = located?.scope.parent
+                ? new BudgetLedger(located.scope.parent.step.budget, located.scope.parent.state.spent)
+                : undefined;
+            const flowOk = flowLedger.canDebit(receipt.amount);
+            const subflowOk = subflowLedger?.canDebit(receipt.amount) ?? true;
+            flowLedger.debit(receipt.amount);
+            subflowLedger?.debit(receipt.amount);
+            Object.assign(run.flowSpent, flowLedger.spent);
+            if (subflowLedger && located?.scope.parent)
+                Object.assign(located.scope.parent.state.spent, subflowLedger.spent);
+            if (!flowOk)
+                budget = "flow";
+            else if (!subflowOk)
+                budget = "subflow";
+        }
+        (run.receipts ??= []).push(receipt);
+        // `attempt` names the attempt the call belongs to. Legacy settles pass it (the
+        // attempt record is pushed after settlement, so length+1 is that attempt);
+        // external receipts get it only while the step is awaiting a result. Gates
+        // and finished steps have no attempt to name.
+        const attempt = explicitAttempt
+            ?? (executable && (located?.item !== undefined
+                ? (located.item.status === "ready" || located.item.status === "running")
+                : located?.state.status === "ready")
+                ? (located?.item !== undefined ? located.item.attempts.length + 1 : located.state.attempts.length + 1)
+                : undefined);
+        const item = located?.item;
+        const detail = {
+            ...(located?.state.epoch !== undefined ? { epoch: located.state.epoch } : {}),
+            ...(attempt !== undefined ? { attempt } : {}),
+            ...(item?.stage !== undefined ? { item: { itemIndex: item.index, stage: item.stage, generation: item.generation } } : {}),
+        };
+        // One detail object serves both the audit event and the receipt row, so the
+        // SmartMemory mirror carries exactly what the event stream carries.
+        const eventDetail = {
+            seq: receipt.seq,
+            dispatchId: receipt.dispatchId,
+            source: receipt.source,
+            amount: { ...receipt.amount },
+            model: receipt.telemetry.model,
+            ...(receipt.telemetry.effort !== undefined ? { effort: receipt.telemetry.effort } : {}),
+            durationMs: receipt.telemetry.durationMs,
+            ...detail,
+            ...(receipt.split !== undefined ? { split: { ...receipt.split } } : {}),
+            ...(receipt.usdSource !== undefined ? { usdSource: receipt.usdSource } : {}),
+            ...(receipt.reportedAt !== undefined ? { reportedAt: receipt.reportedAt } : {}),
+        };
+        receipt.detail = { ...(receipt.detail ?? {}), ...eventDetail };
+        this.event(run, "usage_debit", canonicalStepId, structuredClone(eventDetail));
+        return { status: "ok", ...(budget !== undefined ? { budget } : {}) };
+    }
+    settleLegacyReceipt(run, usage, source, telemetry, located, usdSource, split) {
+        const seq = (run.receiptCounter ?? 0) + 1;
+        const receipt = buildReceipt(run, {
+            dispatchId: `legacy:${seq}`,
+            stepId: this.scopedId(located.scope, located.step.id),
+            source,
+            usage,
+            ...(telemetry !== undefined ? { telemetry } : {}),
+            ...(split !== undefined ? { split } : {}),
+            // A connector that priced the call itself keeps "reported"; only an
+            // unlabelled usd is engine-synthesized "legacy".
+            ...(usage.usd !== undefined ? { usdSource: usdSource ?? "legacy" } : {}),
+        });
+        const attempt = (located.item?.attempts.length ?? located.state.attempts.length) + 1;
+        const settled = this.settleReceipt(run, receipt, located, attempt);
+        if (settled.status === "duplicate")
+            throw new Error(`legacy receipt sequence ${seq} collided`);
+        return settled.budget;
+    }
     unreachableOnFailTarget(step, scope) {
         const routers = scope.flow.steps.filter((candidate) => candidate.on_fail === step.id);
         return routers.length > 0
@@ -1636,7 +2015,8 @@ export class StratumEngine {
         return !routesHere || scope.steps[step.id].routed !== undefined;
     }
     /** Reset a revise target and its ordinary descendants; static validation proved target ancestry. */
-    resetFrom(flow, steps, target) {
+    resetFrom(run, scope, target) {
+        const { flow, steps } = scope;
         const descendants = new Set([target]);
         let changed = true;
         while (changed) {
@@ -1657,6 +2037,20 @@ export class StratumEngine {
                 }
             }
         }
+        const reset = [...descendants].map((id) => {
+            const fromEpoch = steps[id].epoch ?? 0;
+            return { stepId: this.scopedId(scope, id), fromEpoch, toEpoch: fromEpoch + 1 };
+        });
+        const subflowsDropped = [...descendants].flatMap((id) => steps[id].sub === undefined ? [] : [this.scopedId(scope, id)]);
+        const detail = { reason: "revise", reset, subflowsDropped };
+        this.event(run, "step_reset", this.scopedId(scope, target), detail);
+        const resetReceiptSeq = (run.receiptCounter ?? 0) + 1;
+        (run.receipts ??= []).push(buildReceipt(run, {
+            dispatchId: `engine:step_reset:${resetReceiptSeq}`,
+            source: "engine",
+            usage: {},
+            detail,
+        }));
         const gateIds = new Set(flow.steps.flatMap((step) => step.gate !== undefined ? [step.id] : []));
         for (const id of descendants) {
             const state = steps[id];
@@ -1859,7 +2253,7 @@ export class StratumEngine {
         return parse && !parse.success ? parse.error.message : parse ? undefined : "output contract missing";
     }
     rootScope(run, spec) {
-        return { input: run.input, steps: run.steps, flow: this.flowFor(run, spec) };
+        return { input: run.input, steps: run.steps, flow: this.flowFor(run, spec), flowName: run.flowName };
     }
     childScope(spec, parentStep, parentState) {
         if (parentStep.run === undefined || parentState.sub === undefined)
@@ -1871,6 +2265,7 @@ export class StratumEngine {
             input: parentState.sub.input,
             steps: parentState.sub.steps,
             flow,
+            flowName: parentStep.run,
             prefix: parentStep.id,
             parent: { step: parentStep, state: parentState },
         };
@@ -1901,6 +2296,32 @@ export class StratumEngine {
         const state = scope.steps[childId];
         return step && state ? { scope, step, state } : undefined;
     }
+    /** Receipt attribution may arrive after a step or run terminalizes, when the
+     * execution lookup intentionally hides inactive subflow/fanout state. */
+    locateReceiptStep(run, spec, id) {
+        const active = this.locateStep(run, spec, id);
+        if (active !== undefined || !id.includes("/"))
+            return active;
+        const parts = id.split("/");
+        if (parts.length !== 2 || !parts[0] || !parts[1])
+            return undefined;
+        const [parentId, childId] = parts;
+        const root = this.rootScope(run, spec);
+        const parentStep = root.flow.steps.find((candidate) => candidate.id === parentId);
+        const parentState = root.steps[parentId];
+        if (!parentStep || !parentState)
+            return undefined;
+        if (parentStep.fanout?.dispatch === "consumer" && parentState.fanout && /^(0|[1-9][0-9]*)$/.test(childId)) {
+            const item = parentState.fanout.items[Number(childId)];
+            return item && item.index === Number(childId) ? { scope: root, step: parentStep, state: parentState, item } : undefined;
+        }
+        if (parentStep.run === undefined || parentState.sub === undefined)
+            return undefined;
+        const scope = this.childScope(spec, parentStep, parentState);
+        const step = scope.flow.steps.find((candidate) => candidate.id === childId);
+        const state = scope.steps[childId];
+        return step && state ? { scope, step, state } : undefined;
+    }
     collectReady(run, spec) {
         const root = this.rootScope(run, spec);
         const ready = root.flow.steps.flatMap((step) => {
@@ -2045,7 +2466,9 @@ export class StratumEngine {
         try {
             return await this.loadRun(runId);
         }
-        catch {
+        catch (error) {
+            if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT"))
+                throw error;
             throw new CheckpointOperationError("flow_not_found", `No active flow with id '${runId}'`);
         }
     }
@@ -2155,6 +2578,7 @@ export class StratumEngine {
         run.failure = failure;
         this.event(run, "budget_exhausted", undefined, failure);
         await this.persist(run);
+        this.emitFlowTerminal(run);
         return this.response(run);
     }
     async terminalFailure(run, failure) {
@@ -2162,8 +2586,42 @@ export class StratumEngine {
         run.failure = failure;
         this.event(run, "failed", undefined, failure);
         await this.persist(run);
+        this.emitFlowTerminal(run);
         return this.response(run);
     }
+    recordPolicyVerdict(run, flowName, stepId, ensureIndex, met, predicateTypeValue) {
+        const binding = run.policy_rules?.[policyRuleKey(flowName, stepId)]?.find((candidate) => candidate.ensure_index === ensureIndex);
+        if (binding === undefined)
+            return;
+        (run.policy_verdicts ??= []).push({
+            rule_id: binding.rule_id,
+            source: structuredClone(binding.source),
+            met,
+            predicate_type: predicateTypeValue,
+        });
+    }
+    emitFlowTerminal(run) {
+        if (run.bundle_id === undefined)
+            return;
+        this.firePolicyEvent(buildFlowTerminalEvent({
+            runId: run.id,
+            bundleId: run.bundle_id,
+            outcome: run.status,
+            rulesEvaluated: run.policy_verdicts ?? [],
+        }));
+    }
+    firePolicyEvent(event) {
+        void postPolicyEvent(event).catch((error) => {
+            console.warn(`policy event ${event.event_id} delivery failed: ${message(error)}`);
+        });
+    }
+    triggerLearnEgress(runId) {
+        if (!this.learnEgress.enabled())
+            return;
+        void this.learnEgress.drainRun(runId).catch((error) => {
+            console.warn(`SmartMemory egress drain failed for run ${runId}: ${message(error)}`);
+        });
+    }
     response(run) {
         const ledger = this.ledgerInfo(run);
         if (run.status === "completed")
@@ -2186,7 +2644,13 @@ export class StratumEngine {
     }
     persist(run) {
         const previous = this.persistLocks.get(run.id) ?? Promise.resolve();
-        const result = previous.then(() => this.store.save(run));
+        const result = previous
+            .then(() => this.store.save(run))
+            .then(() => {
+            if (this.learnEgress.enabled() && run.receipts?.some((receipt) => receipt.egress === "pending") === true) {
+                this.triggerLearnEgress(run.id);
+            }
+        });
         const tail = result.catch(() => undefined);
         this.persistLocks.set(run.id, tail);
         void tail.then(() => { if (this.persistLocks.get(run.id) === tail)
@@ -2231,6 +2695,8 @@ function stringLeaves(step) {
     // over "${prep.output.items}" must wait for prep, not fail at resolve time.
     if (step.with !== undefined)
         collect(step.with);
+    if (step.evaluate?.in !== undefined)
+        collect(step.evaluate.in);
     if (step.fanout !== undefined) {
         collect(step.fanout.over);
         for (const stage of step.fanout.steps) {
@@ -2298,16 +2764,12 @@ function message(error) {
     }
 }
 function hasBudget(usage) { return Object.keys(usage).length > 0; }
-function validConnectorTelemetry(value) {
-    if (value === undefined)
-        return true;
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return false;
-    if (Object.keys(value).some((key) => !["durationMs", "model", "effort"].includes(key)))
-        return false;
-    return typeof value.durationMs === "number" && Number.isFinite(value.durationMs) && value.durationMs >= 0
-        && typeof value.model === "string" && value.model.length > 0
-        && (value.effort === undefined || (typeof value.effort === "string" && value.effort.length > 0));
+/** Two settle results from one attempt collapse to the most severe ledger breach. */
+function worstBudget(...results) {
+    for (const level of ["flow", "subflow", "task"])
+        if (results.includes(level))
+            return level;
+    return undefined;
 }
 function telemetryFields(value) {
     return value === undefined ? {} : { durationMs: value.durationMs, model: value.model, ...(value.effort !== undefined ? { effort: value.effort } : {}) };
@@ -2339,13 +2801,17 @@ export const defaultConnector = async ({ agent, prompt, cwd, previousFailure, ou
     });
     if ("status" in result)
         return { failure: "background connector response is not valid for synchronous fanout" };
+    const provenance = {
+        ...(result.usdSource !== undefined ? { usdSource: result.usdSource } : {}),
+        ...(result.split !== undefined ? { split: result.split } : {}),
+    };
     if (outSchema === undefined)
-        return { output: result.text, usage: result.usage, telemetry: result.telemetry };
+        return { output: result.text, usage: result.usage, telemetry: result.telemetry, ...provenance };
     try {
-        return { output: JSON.parse(stripJsonFences(result.text)), usage: result.usage, telemetry: result.telemetry };
+        return { output: JSON.parse(stripJsonFences(result.text)), usage: result.usage, telemetry: result.telemetry, ...provenance };
     }
     catch {
-        return { failure: "connector result must be JSON for a contract-enforced fanout stage", usage: result.usage, telemetry: result.telemetry };
+        return { failure: "connector result must be JSON for a contract-enforced fanout stage", usage: result.usage, telemetry: result.telemetry, ...provenance };
     }
 };
 function stripJsonFences(text) {