@grimoirelabs/core 0.7.0 → 0.9.0

package/dist/runtime/interpreter.js

@@ -1,6 +1,6 @@
 /**
  * Spell Interpreter
- * Executes compiled SpellIR
+ * Executes compiled SpellIR via the preview/commit model.
  */
 import { createExecutor } from "../wallet/executor.js";
 import { createProvider } from "../wallet/provider.js";
@@ -8,8 +8,9 @@ import { CircuitBreakerManager } from "./circuit-breaker.js";
 import { InMemoryLedger, createContext, getPersistentStateObject, incrementAdvisoryCalls, markStepExecuted, } from "./context.js";
 import { createEvalContext, evaluateAsync } from "./expression-evaluator.js";
 import { resolveAdvisorSkill } from "./skills/registry.js";
+import { evaluatePreviewValueFlow, inferDriftClass, } from "./value-flow.js";
 // Step executors
-import { executeActionStep } from "./steps/action.js";
+import { commitActionStep, executeActionStep, previewActionStep, } from "./steps/action.js";
 import { executeAdvisoryStep } from "./steps/advisory.js";
 import { executeComputeStep } from "./steps/compute.js";
 import { executeConditionalStep } from "./steps/conditional.js";
@@ -20,29 +21,36 @@ import { executeParallelStep } from "./steps/parallel.js";
 import { executePipelineStep } from "./steps/pipeline.js";
 import { executeTryStep } from "./steps/try.js";
 import { executeWaitStep } from "./steps/wait.js";
+// Keep preview-issued receipts in-process so commit only accepts known receipts.
+const issuedReceipts = new Map();
+const committedReceipts = new Set();
 /**
- * Execute a compiled spell
+ * Preview a spell — runs the full step loop in simulation mode,
+ * collects PlannedActions and ValueDeltas, and assembles a Receipt.
  */
-export async function execute(options) {
-    const { spell, vault, chain, params = {}, persistentState = {}, simulate = false } = options;
-    const actionMode = resolveExecutionMode(options, simulate);
-    const actionExecution = createActionExecutionOptions(options, actionMode, chain);
-    // Initialize circuit breaker manager if policy has breakers
+export async function preview(options) {
+    const { spell, vault, chain, params = {}, persistentState = {} } = options;
+    // Always simulate during preview
+    const actionExecution = { mode: "simulate" };
     if (options.policy?.circuitBreakers?.length) {
         actionExecution.circuitBreakerManager = new CircuitBreakerManager(options.policy.circuitBreakers);
     }
-    // Create execution context
     const ctx = createContext({
         spell,
         vault,
         chain,
+        trigger: options.trigger,
         params,
         persistentState,
     });
     ctx.advisorTooling = buildAdvisorTooling(spell.advisors, options.advisorSkillsDirs);
-    // Create ledger
-    const ledger = new InMemoryLedger(ctx.runId, spell.id);
-    // Log run start
+    const ledger = new InMemoryLedger(ctx.runId, spell.id, options.eventCallback);
+    const guardResults = [];
+    const advisoryResults = [];
+    const plannedActions = [];
+    const valueDeltas = [];
+    const receiptId = `rcpt_${ctx.runId}`;
+    ledger.emit({ type: "preview_started", runId: ctx.runId, spellId: spell.id });
     ledger.emit({
         type: "run_started",
         runId: ctx.runId,
@@ -50,126 +58,631 @@ export async function execute(options) {
         trigger: ctx.trigger,
     });
     try {
-        // Check pre-execution guards
-        const guardResult = await checkGuards(spell.guards, ctx, ledger);
-        if (!guardResult.success) {
-            throw new Error(`Guard failed: ${guardResult.error}`);
+        // Check pre-execution guards and collect results
+        const guardCheck = await checkGuards(spell.guards, ctx, ledger);
+        collectGuardResults(guardResults, spell.guards, guardCheck);
+        if (!guardCheck.success) {
+            const structuredError = createStructuredError("preview", "GUARD_FAILED", `Guard failed: ${guardCheck.error}`);
+            const receipt = buildReceipt({
+                id: receiptId,
+                spell,
+                ctx,
+                guardResults,
+                advisoryResults,
+                plannedActions,
+                valueDeltas,
+                status: "rejected",
+                error: structuredError.message,
+            });
+            registerIssuedReceipt(receipt);
+            ledger.emit({ type: "receipt_generated", receiptId });
+            ledger.emit({ type: "preview_completed", runId: ctx.runId, receiptId, status: "rejected" });
+            return {
+                success: false,
+                receipt,
+                error: structuredError,
+                ledgerEvents: ledger.getEntries(),
+            };
         }
-        // Build step map for quick lookup
+        // Run step loop in preview mode — action steps produce PlannedActions instead of executing
         const stepMap = new Map(spell.steps.map((s) => [s.id, s]));
-        // Execute steps in order (topological sort would be ideal, but for now sequential)
-        for (const step of spell.steps) {
-            // Skip steps already executed by a parent (try/loop/conditional)
-            if (ctx.executedSteps.includes(step.id)) {
-                continue;
-            }
-            // Check dependencies
-            for (const depId of step.dependsOn) {
-                if (!ctx.executedSteps.includes(depId)) {
-                    throw new Error(`Step '${step.id}' depends on '${depId}' which has not been executed`);
-                }
-            }
-            // Execute step
-            const result = await executeStep(step, ctx, ledger, stepMap, actionExecution, options.onAdvisory);
-            // Mark all child steps of container steps (try/loop/conditional) as executed
-            // so the main loop doesn't re-execute them standalone
-            for (const childId of getChildStepIds(step)) {
-                if (!ctx.executedSteps.includes(childId)) {
-                    markStepExecuted(ctx, childId);
-                }
-            }
-            // Enrich step_failed ledger events with source location
-            if (!result.success) {
-                const loc = spell.sourceMap?.[step.id];
-                if (loc) {
-                    enrichStepFailedEvents(ledger, step.id, loc);
-                }
-            }
-            // Handle halt
-            if (result.halted) {
-                ledger.emit({
-                    type: "run_completed",
-                    runId: ctx.runId,
-                    success: true,
-                    metrics: ctx.metrics,
-                });
-                return {
-                    success: true,
-                    runId: ctx.runId,
-                    startTime: ctx.startTime,
-                    endTime: Date.now(),
-                    duration: Date.now() - ctx.startTime,
-                    metrics: ctx.metrics,
-                    finalState: getPersistentStateObject(ctx),
-                    ledgerEvents: ledger.getEntries(),
-                };
-            }
-            // Handle failure
-            if (!result.success) {
-                const onFailure = "onFailure" in step ? step.onFailure : "revert";
-                const loc = spell.sourceMap?.[step.id];
-                const locSuffix = loc ? ` at line ${loc.line}, column ${loc.column}` : "";
-                switch (onFailure) {
-                    case "halt":
-                        throw new Error(`Step '${step.id}' failed${locSuffix}: ${result.error}`);
-                    case "revert":
-                        throw new Error(`Step '${step.id}' failed${locSuffix}: ${result.error}`);
-                    case "skip":
-                        ledger.emit({
-                            type: "step_skipped",
-                            stepId: step.id,
-                            reason: result.error ?? "Unknown error",
-                        });
-                        continue;
-                    case "catch":
-                        // Would be handled by try/catch step
-                        continue;
-                }
-            }
-            markStepExecuted(ctx, step.id);
+        const stepLoopResult = await executeStepLoop(spell, ctx, ledger, stepMap, actionExecution, options.onAdvisory, { isPreview: true, plannedActions, valueDeltas, advisoryResults });
+        if (!stepLoopResult.success) {
+            const structuredError = createStructuredError("preview", "STEP_FAILED", stepLoopResult.error ?? "Step execution failed");
+            const receipt = buildReceipt({
+                id: receiptId,
+                spell,
+                ctx,
+                guardResults,
+                advisoryResults,
+                plannedActions,
+                valueDeltas,
+                status: "rejected",
+                error: structuredError.message,
+            });
+            registerIssuedReceipt(receipt);
+            ledger.emit({ type: "receipt_generated", receiptId });
+            ledger.emit({ type: "preview_completed", runId: ctx.runId, receiptId, status: "rejected" });
+            return {
+                success: false,
+                receipt,
+                error: structuredError,
+                ledgerEvents: ledger.getEntries(),
+            };
         }
-        // Check post-execution guards
-        const postGuardResult = await checkGuards(spell.guards, ctx, ledger);
-        if (!postGuardResult.success && postGuardResult.severity === "halt") {
-            throw new Error(`Post-execution guard failed: ${postGuardResult.error}`);
+        // Post-execution guards
+        const postGuardCheck = await checkGuards(spell.guards, ctx, ledger);
+        if (!postGuardCheck.success && postGuardCheck.severity === "halt") {
+            const structuredError = createStructuredError("preview", "POST_GUARD_FAILED", `Post-execution guard failed: ${postGuardCheck.error}`);
+            const receipt = buildReceipt({
+                id: receiptId,
+                spell,
+                ctx,
+                guardResults,
+                advisoryResults,
+                plannedActions,
+                valueDeltas,
+                status: "rejected",
+                error: structuredError.message,
+            });
+            registerIssuedReceipt(receipt);
+            ledger.emit({ type: "receipt_generated", receiptId });
+            ledger.emit({ type: "preview_completed", runId: ctx.runId, receiptId, status: "rejected" });
+            return {
+                success: false,
+                receipt,
+                error: structuredError,
+                ledgerEvents: ledger.getEntries(),
+            };
+        }
+        const valueFlow = evaluatePreviewValueFlow(ctx, plannedActions, valueDeltas);
+        if (valueFlow.violation) {
+            const structuredError = structuredErrorFromValueFlowViolation("preview", valueFlow.violation);
+            const receipt = buildReceipt({
+                id: receiptId,
+                spell,
+                ctx,
+                guardResults,
+                advisoryResults,
+                plannedActions,
+                valueDeltas,
+                status: "rejected",
+                error: structuredError.message,
+                constraintResults: valueFlow.constraintResults,
+                driftKeys: valueFlow.driftKeys,
+                requiresApproval: valueFlow.requiresApproval,
+                accounting: valueFlow.accounting,
+            });
+            registerIssuedReceipt(receipt);
+            ledger.emit({ type: "receipt_generated", receiptId });
+            ledger.emit({ type: "preview_completed", runId: ctx.runId, receiptId, status: "rejected" });
+            return {
+                success: false,
+                receipt,
+                error: structuredError,
+                ledgerEvents: ledger.getEntries(),
+            };
         }
-        // Log run completion
+        const requiresApproval = valueFlow.requiresApproval;
+        const receipt = buildReceipt({
+            id: receiptId,
+            spell,
+            ctx,
+            guardResults,
+            advisoryResults,
+            plannedActions,
+            valueDeltas,
+            status: "ready",
+            constraintResults: valueFlow.constraintResults,
+            driftKeys: valueFlow.driftKeys,
+            requiresApproval: valueFlow.requiresApproval,
+            accounting: valueFlow.accounting,
+        });
+        registerIssuedReceipt(receipt);
+        if (requiresApproval) {
+            ledger.emit({
+                type: "approval_required",
+                receiptId,
+                reason: "One or more actions crossed approval_required_above",
+            });
+        }
+        ledger.emit({ type: "receipt_generated", receiptId });
         ledger.emit({
             type: "run_completed",
             runId: ctx.runId,
             success: true,
             metrics: ctx.metrics,
         });
+        ledger.emit({ type: "preview_completed", runId: ctx.runId, receiptId, status: "ready" });
+        return { success: true, receipt, ledgerEvents: ledger.getEntries() };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const structuredError = createStructuredError("preview", "PREVIEW_INTERNAL_ERROR", message);
+        ledger.emit({ type: "run_failed", runId: ctx.runId, error: message });
+        ledger.emit({ type: "preview_completed", runId: ctx.runId, receiptId, status: "rejected" });
+        return { success: false, error: structuredError, ledgerEvents: ledger.getEntries() };
+    }
+}
+/**
+ * Commit a receipt — executes planned actions from the preview.
+ */
+export async function commit(options) {
+    const { receipt, wallet } = options;
+    const runId = receipt.id.replace("rcpt_", "");
+    const ledger = new InMemoryLedger(runId, receipt.spellId, options.eventCallback);
+    ledger.emit({ type: "commit_started", runId, receiptId: receipt.id });
+    // Validate receipt status
+    if (receipt.status !== "ready") {
+        const structuredError = createStructuredError("commit", "RECEIPT_INVALID_STATUS", `Receipt status is '${receipt.status}', expected 'ready'`);
+        ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
         return {
-            success: true,
-            runId: ctx.runId,
-            startTime: ctx.startTime,
-            endTime: Date.now(),
-            duration: Date.now() - ctx.startTime,
-            metrics: ctx.metrics,
-            finalState: getPersistentStateObject(ctx),
+            success: false,
+            receiptId: receipt.id,
+            transactions: [],
+            driftChecks: [],
+            finalState: receipt.finalState,
             ledgerEvents: ledger.getEntries(),
+            error: structuredError,
         };
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        ledger.emit({
-            type: "run_failed",
-            runId: ctx.runId,
-            error: message,
-        });
+    const receiptValidationError = validateCommitReceipt(receipt);
+    if (receiptValidationError) {
+        ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
         return {
             success: false,
-            runId: ctx.runId,
-            startTime: ctx.startTime,
-            endTime: Date.now(),
-            duration: Date.now() - ctx.startTime,
-            error: message,
-            metrics: ctx.metrics,
-            finalState: getPersistentStateObject(ctx),
+            receiptId: receipt.id,
+            transactions: [],
+            driftChecks: [],
+            finalState: receipt.finalState,
             ledgerEvents: ledger.getEntries(),
+            error: receiptValidationError,
         };
     }
+    // Check receipt age
+    if (options.driftPolicy?.maxAge) {
+        const ageSec = (Date.now() - receipt.timestamp) / 1000;
+        if (ageSec > options.driftPolicy.maxAge) {
+            const structuredError = createStructuredError("commit", "RECEIPT_EXPIRED", `Receipt expired: age ${Math.round(ageSec)}s exceeds maxAge ${options.driftPolicy.maxAge}s`, {
+                actual: Math.round(ageSec),
+                limit: options.driftPolicy.maxAge,
+                suggestion: "Run preview again to generate a fresh receipt.",
+            });
+            ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
+            return {
+                success: false,
+                receiptId: receipt.id,
+                transactions: [],
+                driftChecks: [],
+                finalState: receipt.finalState,
+                ledgerEvents: ledger.getEntries(),
+                error: structuredError,
+            };
+        }
+    }
+    const driftChecks = [];
+    for (const driftKey of receipt.driftKeys) {
+        if (options.driftPolicy?.maxAge) {
+            const keyAgeSec = Math.max(0, Math.floor((Date.now() - driftKey.timestamp) / 1000));
+            if (keyAgeSec > options.driftPolicy.maxAge) {
+                const structuredError = createStructuredError("commit", "DRIFT_KEY_STALE", `Drift key '${driftKey.field}' is stale (${keyAgeSec}s > ${options.driftPolicy.maxAge}s)`, {
+                    constraint: "drift_key_freshness",
+                    actual: keyAgeSec,
+                    limit: options.driftPolicy.maxAge,
+                    path: driftKey.field,
+                    suggestion: "Run preview again to refresh drift keys.",
+                });
+                ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
+                return {
+                    success: false,
+                    receiptId: receipt.id,
+                    transactions: [],
+                    driftChecks,
+                    finalState: receipt.finalState,
+                    ledgerEvents: ledger.getEntries(),
+                    error: structuredError,
+                };
+            }
+        }
+        let resolvedValue;
+        try {
+            resolvedValue = await resolveCommitDriftValue(driftKey, options);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const structuredError = createStructuredError("commit", "DRIFT_RESOLUTION_FAILED", `Failed to resolve drift value for '${driftKey.field}': ${message}`, {
+                constraint: "drift_keys",
+                path: driftKey.field,
+            });
+            ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
+            return {
+                success: false,
+                receiptId: receipt.id,
+                transactions: [],
+                driftChecks,
+                finalState: receipt.finalState,
+                ledgerEvents: ledger.getEntries(),
+                error: structuredError,
+            };
+        }
+        if (!resolvedValue.found && options.driftPolicy) {
+            const structuredError = createStructuredError("commit", "DRIFT_VALUE_MISSING", `Missing commit-time drift value for '${driftKey.field}'`, {
+                constraint: "drift_keys",
+                path: driftKey.field,
+                suggestion: "Provide driftValues for this key or configure resolveDriftValue to fetch commit-time values.",
+            });
+            ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
+            return {
+                success: false,
+                receiptId: receipt.id,
+                transactions: [],
+                driftChecks,
+                finalState: receipt.finalState,
+                ledgerEvents: ledger.getEntries(),
+                error: structuredError,
+            };
+        }
+        const commitValue = resolvedValue.found ? resolvedValue.value : driftKey.previewValue;
+        const driftResult = evaluateDriftKey(driftKey, commitValue, options.driftPolicy);
+        driftChecks.push(driftResult);
+        ledger.emit({
+            type: "drift_check",
+            field: driftKey.field,
+            passed: driftResult.passed,
+            previewValue: driftResult.previewValue,
+            commitValue: driftResult.commitValue,
+        });
+        if (!driftResult.passed) {
+            const tolerance = resolveToleranceBps(driftKey, options.driftPolicy);
+            const structuredError = createStructuredError("commit", "DRIFT_EXCEEDED", `Drift exceeded for '${driftKey.field}'`, {
+                constraint: "drift_policy",
+                actual: driftResult.driftBps,
+                limit: tolerance,
+                path: driftKey.field,
+                suggestion: "Run preview again or increase drift tolerance for this key class.",
+            });
+            ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
+            return {
+                success: false,
+                receiptId: receipt.id,
+                transactions: [],
+                driftChecks,
+                finalState: receipt.finalState,
+                ledgerEvents: ledger.getEntries(),
+                error: structuredError,
+            };
+        }
+    }
+    // Execute planned actions
+    const { chainId } = receipt.chainContext;
+    const provider = options.provider ?? createProvider(chainId, options.rpcUrl);
+    const executor = createExecutor({
+        wallet,
+        provider,
+        mode: "execute",
+        gasMultiplier: options.gasMultiplier,
+        confirmCallback: options.confirmCallback,
+        progressCallback: options.progressCallback,
+        skipTestnetConfirmation: options.skipTestnetConfirmation,
+        adapters: options.adapters,
+    });
+    const transactions = [];
+    for (const planned of receipt.plannedActions) {
+        try {
+            const txResult = await commitActionStep(planned, executor);
+            if (txResult.success) {
+                transactions.push({
+                    stepId: planned.stepId,
+                    hash: txResult.hash,
+                    gasUsed: txResult.gasUsed,
+                    success: true,
+                });
+                if (txResult.hash) {
+                    ledger.emit({
+                        type: "action_submitted",
+                        action: planned.action,
+                        txHash: txResult.hash,
+                    });
+                }
+                if (txResult.gasUsed !== undefined) {
+                    ledger.emit({
+                        type: "action_confirmed",
+                        txHash: txResult.hash ?? "",
+                        gasUsed: txResult.gasUsed.toString(),
+                    });
+                }
+            }
+            else {
+                transactions.push({
+                    stepId: planned.stepId,
+                    hash: txResult.hash,
+                    success: false,
+                    error: txResult.error,
+                });
+                if (planned.onFailure === "skip") {
+                    ledger.emit({
+                        type: "step_skipped",
+                        stepId: planned.stepId,
+                        reason: txResult.error ?? "Action execution failed",
+                    });
+                    continue;
+                }
+                const structuredError = createStructuredError("commit", "ACTION_COMMIT_FAILED", `Action step '${planned.stepId}' failed: ${txResult.error}`);
+                ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
+                return {
+                    success: false,
+                    receiptId: receipt.id,
+                    transactions,
+                    driftChecks,
+                    finalState: receipt.finalState,
+                    ledgerEvents: ledger.getEntries(),
+                    error: structuredError,
+                };
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            transactions.push({ stepId: planned.stepId, success: false, error: message });
+            const structuredError = createStructuredError("commit", "COMMIT_INTERNAL_ERROR", message);
+            ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
+            return {
+                success: false,
+                receiptId: receipt.id,
+                transactions,
+                driftChecks,
+                finalState: receipt.finalState,
+                ledgerEvents: ledger.getEntries(),
+                error: structuredError,
+            };
+        }
+    }
+    committedReceipts.add(receipt.id);
+    ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: true });
+    return {
+        success: true,
+        receiptId: receipt.id,
+        transactions,
+        driftChecks,
+        finalState: receipt.finalState,
+        ledgerEvents: ledger.getEntries(),
+    };
+}
+// =============================================================================
+// EXECUTE (backward-compatible wrapper)
+// =============================================================================
+/**
+ * Execute a compiled spell (backward-compatible wrapper).
+ * Internally uses preview() and, if needed, commit().
+ */
+export async function execute(options) {
+    const { spell, vault, chain, params = {}, persistentState = {}, simulate = false } = options;
+    const actionMode = resolveExecutionMode(options, simulate);
+    const previewResult = await preview({
+        spell,
+        vault,
+        chain,
+        params,
+        persistentState,
+        trigger: options.trigger,
+        adapters: options.adapters,
+        policy: options.policy,
+        advisorSkillsDirs: options.advisorSkillsDirs,
+        onAdvisory: options.onAdvisory,
+        progressCallback: options.progressCallback,
+        eventCallback: options.eventCallback,
+    });
+    if (!previewResult.success || !previewResult.receipt) {
+        return convertPreviewToExecutionResult(previewResult, spell);
+    }
+    const receipt = previewResult.receipt;
+    // Preview-only execution for simulate/dry-run/no-wallet and compute-only spells.
+    if (actionMode === "simulate" ||
+        actionMode === "dry-run" ||
+        !options.wallet ||
+        receipt.plannedActions.length === 0) {
+        return convertPreviewToExecutionResult(previewResult, spell);
+    }
+    const commitResult = await commit({
+        receipt,
+        wallet: options.wallet,
+        provider: options.provider,
+        rpcUrl: options.rpcUrl,
+        gasMultiplier: options.gasMultiplier,
+        adapters: options.adapters,
+        confirmCallback: options.confirmCallback,
+        progressCallback: options.progressCallback,
+        skipTestnetConfirmation: options.skipTestnetConfirmation,
+        eventCallback: options.eventCallback,
+    });
+    return convertPreviewCommitToExecutionResult(previewResult, commitResult);
+}
+/**
+ * Shared step execution loop used by both preview() and execute().
+ */
+async function executeStepLoop(spell, ctx, ledger, stepMap, actionExecution, advisoryHandler, collectors) {
+    for (const step of spell.steps) {
+        if (ctx.executedSteps.includes(step.id)) {
+            continue;
+        }
+        for (const depId of step.dependsOn) {
+            if (!ctx.executedSteps.includes(depId)) {
+                return {
+                    success: false,
+                    error: `Step '${step.id}' depends on '${depId}' which has not been executed`,
+                };
+            }
+        }
+        // In preview mode, action steps go through previewActionStep
+        let result;
+        if (collectors?.isPreview && step.kind === "action") {
+            const previewResult = await previewActionStep(step, ctx, ledger, actionExecution);
+            result = previewResult.stepResult;
+            if (previewResult.plannedAction) {
+                collectors.plannedActions?.push(previewResult.plannedAction);
+            }
+            if (previewResult.valueDeltas?.length) {
+                collectors.valueDeltas?.push(...previewResult.valueDeltas);
+                for (const delta of previewResult.valueDeltas) {
+                    ledger.emit({ type: "value_delta", delta });
+                }
+            }
+        }
+        else if (collectors?.isPreview && step.kind === "advisory") {
+            result = await executeAdvisoryStep(step, ctx, ledger, advisoryHandler);
+            if (result.success) {
+                collectors.advisoryResults?.push({
+                    stepId: step.id,
+                    advisor: step.advisor,
+                    output: result.output,
+                    fallback: result.fallback ?? false,
+                    rawOutput: result.rawOutput,
+                    effectiveOutput: result.effectiveOutput ?? result.output,
+                    onViolation: result.violationPolicy ?? step.violationPolicy ?? "reject",
+                    policyScope: step.policyScope,
+                    clampConstraints: step.clampConstraints,
+                    clamped: result.clamped ?? false,
+                    violations: result.advisoryViolations,
+                });
+            }
+        }
+        else {
+            result = await executeStep(step, ctx, ledger, stepMap, actionExecution, advisoryHandler);
+        }
+        for (const childId of getChildStepIds(step)) {
+            if (!ctx.executedSteps.includes(childId)) {
+                markStepExecuted(ctx, childId);
+            }
+        }
+        if (!result.success) {
+            const loc = spell.sourceMap?.[step.id];
+            if (loc) {
+                enrichStepFailedEvents(ledger, step.id, loc);
+            }
+        }
+        if (result.halted) {
+            return { success: true, halted: true };
+        }
+        if (!result.success) {
+            const onFailure = "onFailure" in step ? step.onFailure : "revert";
+            const loc = spell.sourceMap?.[step.id];
+            const locSuffix = loc ? ` at line ${loc.line}, column ${loc.column}` : "";
+            switch (onFailure) {
+                case "halt":
+                    return { success: false, error: `Step '${step.id}' failed${locSuffix}: ${result.error}` };
+                case "revert":
+                    return { success: false, error: `Step '${step.id}' failed${locSuffix}: ${result.error}` };
+                case "skip":
+                    ledger.emit({
+                        type: "step_skipped",
+                        stepId: step.id,
+                        reason: result.error ?? "Unknown error",
+                    });
+                    continue;
+                case "catch":
+                    continue;
+            }
+        }
+        markStepExecuted(ctx, step.id);
+    }
+    return { success: true };
+}
+// =============================================================================
+// HELPERS
+// =============================================================================
+function convertPreviewToExecutionResult(previewResult, _spell) {
+    const receipt = previewResult.receipt;
+    const now = Date.now();
+    const startTime = receipt?.timestamp ?? now;
+    return {
+        success: previewResult.success,
+        runId: receipt?.id.replace("rcpt_", "") ?? `preview_${now}`,
+        startTime,
+        endTime: now,
+        duration: now - startTime,
+        error: previewResult.error ? formatStructuredError(previewResult.error) : undefined,
+        structuredError: previewResult.error,
+        metrics: receipt?.metrics ?? {
+            stepsExecuted: 0,
+            actionsExecuted: 0,
+            gasUsed: 0n,
+            advisoryCalls: 0,
+            errors: 0,
+            retries: 0,
+        },
+        finalState: receipt?.finalState ?? {},
+        ledgerEvents: previewResult.ledgerEvents,
+        receipt,
+    };
+}
+function convertPreviewCommitToExecutionResult(previewResult, commitResult) {
+    const receipt = previewResult.receipt;
+    const endTime = Date.now();
+    const startTime = receipt?.timestamp ?? endTime;
+    const txGasUsed = commitResult.transactions.reduce((sum, tx) => sum + (tx.gasUsed ?? 0n), 0n);
+    const baseMetrics = receipt?.metrics ?? {
+        stepsExecuted: 0,
+        actionsExecuted: 0,
+        gasUsed: 0n,
+        advisoryCalls: 0,
+        errors: 0,
+        retries: 0,
+    };
+    return {
+        success: commitResult.success,
+        runId: receipt?.id.replace("rcpt_", "") ?? `commit_${endTime}`,
+        startTime,
+        endTime,
+        duration: endTime - startTime,
+        error: commitResult.error ? formatStructuredError(commitResult.error) : undefined,
+        structuredError: commitResult.error,
+        metrics: {
+            ...baseMetrics,
+            gasUsed: baseMetrics.gasUsed + txGasUsed,
+        },
+        finalState: commitResult.finalState,
+        ledgerEvents: [...previewResult.ledgerEvents, ...commitResult.ledgerEvents],
+        receipt,
+        commit: commitResult,
+    };
+}
+function buildReceipt(opts) {
+    return {
+        id: opts.id,
+        spellId: opts.spell.id,
+        phase: "preview",
+        timestamp: Date.now(),
+        chainContext: {
+            chainId: opts.ctx.chain,
+            vault: opts.ctx.vault,
+        },
+        guardResults: opts.guardResults,
+        advisoryResults: opts.advisoryResults,
+        plannedActions: opts.plannedActions,
+        valueDeltas: opts.valueDeltas,
+        accounting: opts.accounting ??
+            {
+                assets: [],
+                totalUnaccounted: 0n,
+                passed: true,
+            },
+        constraintResults: opts.constraintResults ?? [],
+        driftKeys: opts.driftKeys ?? [],
+        requiresApproval: opts.requiresApproval ?? false,
+        status: opts.status,
+        metrics: { ...opts.ctx.metrics },
+        finalState: getPersistentStateObject(opts.ctx),
+        error: opts.error,
+    };
+}
+function collectGuardResults(guardResults, guards, check) {
+    for (const guard of guards) {
+        guardResults.push({
+            guardId: guard.id,
+            passed: check.success,
+            severity: check.severity ?? ("severity" in guard ? String(guard.severity) : "warn"),
+            message: check.success ? undefined : check.error,
+        });
+    }
 }
 function resolveExecutionMode(options, simulate) {
     if (options.executionMode) {
@@ -183,25 +696,159 @@ function resolveExecutionMode(options, simulate) {
     }
     return "simulate";
 }
-function createActionExecutionOptions(options, mode, chainId) {
-    if (mode === "simulate") {
-        return { mode };
+function createStructuredError(phase, code, message, extras) {
+    return {
+        phase,
+        code,
+        message,
+        ...extras,
+    };
+}
+function structuredErrorFromValueFlowViolation(phase, violation) {
+    return createStructuredError(phase, violation.code, violation.message, {
+        constraint: violation.constraint,
+        actual: violation.actual,
+        limit: violation.limit,
+        path: violation.path,
+        suggestion: violation.suggestion,
+    });
+}
+function formatStructuredError(error) {
+    return `[${error.code}] ${error.message}`;
+}
+function registerIssuedReceipt(receipt) {
+    issuedReceipts.set(receipt.id, {
+        spellId: receipt.spellId,
+        chainId: receipt.chainContext.chainId,
+        vault: receipt.chainContext.vault,
+        timestamp: receipt.timestamp,
+    });
+}
+function validateCommitReceipt(receipt) {
+    if (receipt.phase !== "preview") {
+        return createStructuredError("commit", "RECEIPT_INVALID_PHASE", `Receipt phase is '${receipt.phase}', expected 'preview'`);
     }
-    if (!options.wallet) {
-        throw new Error("Wallet is required for non-simulated execution");
+    if (!receipt.id.startsWith("rcpt_")) {
+        return createStructuredError("commit", "RECEIPT_INVALID_ID", "Receipt ID must start with 'rcpt_'");
     }
-    const provider = options.provider ?? createProvider(chainId, options.rpcUrl);
-    const executor = createExecutor({
-        wallet: options.wallet,
-        provider,
-        mode,
-        gasMultiplier: options.gasMultiplier,
-        confirmCallback: options.confirmCallback,
-        progressCallback: options.progressCallback,
-        skipTestnetConfirmation: options.skipTestnetConfirmation,
-        adapters: options.adapters,
-    });
-    return { mode, executor };
+    if (committedReceipts.has(receipt.id)) {
+        return createStructuredError("commit", "RECEIPT_ALREADY_COMMITTED", "Receipt has already been committed.");
+    }
+    const issuedReceipt = issuedReceipts.get(receipt.id);
+    if (!issuedReceipt) {
+        return createStructuredError("commit", "PREVIEW_RECEIPT_UNKNOWN", "Commit requires a valid preview receipt generated by this runtime.");
+    }
+    if (issuedReceipt.spellId !== receipt.spellId ||
+        issuedReceipt.chainId !== receipt.chainContext.chainId ||
+        issuedReceipt.vault !== receipt.chainContext.vault ||
+        issuedReceipt.timestamp !== receipt.timestamp) {
+        return createStructuredError("commit", "PREVIEW_RECEIPT_TAMPERED", "Receipt identity does not match the preview-generated artifact.");
+    }
+    return undefined;
+}
+async function resolveCommitDriftValue(driftKey, options) {
+    if (options.driftValues &&
+        Object.prototype.hasOwnProperty.call(options.driftValues, driftKey.field)) {
+        return { found: true, value: options.driftValues[driftKey.field] };
+    }
+    if (options.resolveDriftValue) {
+        const value = await options.resolveDriftValue(driftKey);
+        if (value !== undefined) {
+            return { found: true, value };
+        }
+    }
+    return { found: false, value: undefined };
+}
+function evaluateDriftKey(driftKey, commitValue, policy) {
+    const tolerance = resolveToleranceBps(driftKey, policy);
+    const numericPreview = toNumeric(driftKey.previewValue);
+    const numericCommit = toNumeric(commitValue);
+    if (tolerance !== undefined && numericPreview !== undefined && numericCommit !== undefined) {
+        const driftBps = computeDriftBps(numericPreview, numericCommit);
+        return {
+            field: driftKey.field,
+            passed: driftBps <= tolerance,
+            previewValue: driftKey.previewValue,
+            commitValue,
+            driftBps,
+        };
+    }
+    if (tolerance !== undefined) {
+        return {
+            field: driftKey.field,
+            passed: false,
+            previewValue: driftKey.previewValue,
+            commitValue,
+        };
+    }
+    return {
+        field: driftKey.field,
+        passed: valuesEquivalent(driftKey.previewValue, commitValue),
+        previewValue: driftKey.previewValue,
+        commitValue,
+    };
+}
+function resolveToleranceBps(driftKey, policy) {
+    if (!policy)
+        return undefined;
+    const driftClass = driftKey.class ?? inferDriftClass(driftKey.field);
+    switch (driftClass) {
+        case "balance":
+            return policy.balance?.toleranceBps;
+        case "quote":
+            return policy.quote?.toleranceBps;
+        case "rate":
+            return policy.rate?.toleranceBps;
+        case "gas":
+            return policy.gas?.toleranceBps;
+        default:
+            return undefined;
+    }
+}
+function toNumeric(value) {
+    if (typeof value === "bigint") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return undefined;
+        return BigInt(Math.trunc(value));
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!/^[-+]?\d+$/.test(trimmed))
+            return undefined;
+        try {
+            return BigInt(trimmed);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function computeDriftBps(preview, commit) {
+    const delta = preview >= commit ? preview - commit : commit - preview;
+    if (preview === 0n) {
+        return delta === 0n ? 0 : 10_000;
+    }
+    return Number((delta * 10000n) / (preview >= 0n ? preview : -preview));
+}
+function valuesEquivalent(left, right) {
+    if (typeof left === "bigint" || typeof right === "bigint") {
+        const leftBigint = toNumeric(left);
+        const rightBigint = toNumeric(right);
+        if (leftBigint === undefined || rightBigint === undefined)
+            return false;
+        return leftBigint === rightBigint;
+    }
+    if (typeof left === "number" && typeof right === "number") {
+        return Number.isFinite(left) && Number.isFinite(right) && left === right;
+    }
+    if (typeof left === "string" && typeof right === "string") {
+        return left === right;
+    }
+    return Object.is(left, right);
 }
 function buildAdvisorTooling(advisors, searchDirs) {
     if (!advisors.length)
@@ -397,8 +1044,6 @@ async function checkGuards(guards, ctx, ledger) {
 }
 /**
  * Enrich step_failed ledger events with source location info.
- * Scans recent events to find step_failed events for the given stepId
- * and adds line/column from the source map.
  */
 function enrichStepFailedEvents(ledger, stepId, loc) {
     const entries = ledger.getEntries();