@smartmemory/stratum 0.3.4 → 0.4.1

package/dist/engine/engine.js

@@ -8,8 +8,13 @@ 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);
 /**
@@ -61,12 +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();
@@ -87,6 +97,16 @@ export class StratumEngine {
         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);
@@ -120,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);
@@ -288,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 } : {}) });
@@ -364,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 () => {
@@ -392,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 };
@@ -446,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,
@@ -458,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);
@@ -494,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;
@@ -567,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);
@@ -595,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" });
@@ -603,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
@@ -772,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");
@@ -1465,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 };
@@ -1587,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
@@ -1626,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), {
@@ -1644,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")
@@ -1663,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}` };
         }
@@ -1727,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
@@ -1739,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) {
@@ -1760,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];
@@ -1962,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)
@@ -1974,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 },
         };
@@ -2004,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) => {
@@ -2148,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}'`);
         }
     }
@@ -2258,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) {
@@ -2265,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")
@@ -2289,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)
@@ -2403,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 } : {}) };
@@ -2444,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) {