@grimoirelabs/core 0.14.0 → 0.16.0

package/dist/runtime/interpreter.d.ts

@@ -7,7 +7,7 @@ import type { SpellIR } from "../types/ir.js";
 import type { PolicySet } from "../types/policy.js";
 import type { Address, ChainId } from "../types/primitives.js";
 import type { QueryProvider } from "../types/query-provider.js";
-import type { CommitResult, DriftKey, DriftPolicy, PreviewResult, Receipt } from "../types/receipt.js";
+import type { BuildTransactionsResult, CommitResult, DriftKey, DriftPolicy, PreviewResult, Receipt } from "../types/receipt.js";
 import type { VenueAdapter } from "../venues/types.js";
 import { type ExecutionMode } from "../wallet/executor.js";
 import { type Provider } from "../wallet/provider.js";
@@ -66,6 +66,8 @@ export interface ExecuteOptions {
     crossChain?: ActionExecutionOptions["crossChain"];
     /** Pluggable query provider for balance/price/apy/etc. */
     queryProvider?: QueryProvider;
+    /** Filter execution to a specific trigger handler by type name (e.g., "manual", "hourly") */
+    triggerFilter?: string;
 }
 /**
  * Options for previewing a spell (simulation / receipt generation)
@@ -90,6 +92,8 @@ export interface PreviewOptions {
     crossChain?: ActionExecutionOptions["crossChain"];
     /** Pluggable query provider for balance/price/apy/etc. */
     queryProvider?: QueryProvider;
+    /** Filter execution to a specific trigger handler by type name (e.g., "manual", "hourly") */
+    triggerFilter?: string;
 }
 /**
  * Preview a spell — runs the full step loop in simulation mode,
@@ -118,9 +122,44 @@ export interface CommitOptions {
  * Commit a receipt — executes planned actions from the preview.
  */
 export declare function commit(options: CommitOptions): Promise<CommitResult>;
+/**
+ * Options for building unsigned transactions from a preview receipt
+ */
+export interface BuildTransactionsOptions {
+    receipt: Receipt;
+    walletAddress: Address;
+    provider?: Provider;
+    rpcUrl?: string;
+    adapters?: VenueAdapter[];
+    driftPolicy?: DriftPolicy;
+    driftValues?: Record<string, unknown>;
+    resolveDriftValue?: (key: DriftKey) => Promise<unknown>;
+    progressCallback?: (message: string) => void;
+    /**
+     * Secret used to verify receipt integrity for cross-process receipts.
+     * Required when the receipt was not issued by this process (i.e. not in
+     * the in-memory issuedReceipts map). Use signReceipt() at preview time
+     * to generate the matching integrity hash.
+     */
+    receiptSecret?: string;
+    /** HMAC integrity hash produced by signReceipt(receipt, secret) */
+    receiptIntegrity?: string;
+}
+/**
+ * Build unsigned transactions from a preview receipt.
+ * Returns calldata for client-side signing (e.g. Privy SDK).
+ * Does NOT commit the receipt — commit() can still be called afterwards.
+ */
+export declare function buildTransactions(options: BuildTransactionsOptions): Promise<BuildTransactionsResult>;
 /**
  * Execute a compiled spell (backward-compatible wrapper).
  * Internally uses preview() and, if needed, commit().
  */
 export declare function execute(options: ExecuteOptions): Promise<ExecutionResult>;
+/**
+ * Sign a receipt for cross-process integrity verification.
+ * Call this at preview time, persist the returned hex string alongside
+ * the receipt, and pass it as `receiptIntegrity` to buildTransactions().
+ */
+export declare function signReceipt(receipt: Receipt, secret: string): string;
 //# sourceMappingURL=interpreter.d.ts.map

package/dist/runtime/interpreter.d.ts.map

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

package/dist/runtime/interpreter.js

@@ -2,9 +2,11 @@
  * Spell Interpreter
  * Executes compiled SpellIR via the preview/commit model.
  */
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { createVenueRegistry } from "../venues/index.js";
 import { createExecutor } from "../wallet/executor.js";
 import { createProvider } from "../wallet/provider.js";
+import { TransactionBuilder } from "../wallet/tx-builder.js";
 import { CircuitBreakerManager } from "./circuit-breaker.js";
 import { createContext, getPersistentStateObject, InMemoryLedger, incrementAdvisoryCalls, markStepExecuted, } from "./context.js";
 import { createEvalContext, evaluateAsync } from "./expression-evaluator.js";
@@ -25,12 +27,55 @@ import { evaluatePreviewValueFlow, inferDriftClass, } from "./value-flow.js";
 // Keep preview-issued receipts in-process so commit only accepts known receipts.
 const issuedReceipts = new Map();
 const committedReceipts = new Set();
+/** Check if a trigger matches a filter string (e.g., "manual", "hourly", "daily") */
+function matchesTriggerFilter(trigger, filter) {
+    if (trigger.type === filter)
+        return true;
+    if (filter === "hourly" && trigger.type === "schedule" && trigger.cron === "0 * * * *")
+        return true;
+    if (filter === "daily" && trigger.type === "schedule" && trigger.cron === "0 0 * * *")
+        return true;
+    return false;
+}
+/** Describe a trigger for user-facing messages */
+function describeTrigger(trigger) {
+    if (trigger.type === "schedule") {
+        if (trigger.cron === "0 * * * *")
+            return "hourly";
+        if (trigger.cron === "0 0 * * *")
+            return "daily";
+        return `schedule(${trigger.cron})`;
+    }
+    return trigger.type;
+}
 /**
  * Preview a spell — runs the full step loop in simulation mode,
  * collects PlannedActions and ValueDeltas, and assembles a Receipt.
  */
 export async function preview(options) {
-    const { spell, vault, chain, params = {}, persistentState = {} } = options;
+    const { spell: originalSpell, vault, chain, params = {}, persistentState = {} } = options;
+    // Apply trigger filter: narrow steps to only those from the matched trigger handler
+    let spell = originalSpell;
+    let triggerOverride = options.trigger;
+    if (options.triggerFilter && originalSpell.triggerStepMap) {
+        const anyTrigger = originalSpell.triggers.find((t) => t.type === "any");
+        if (anyTrigger && anyTrigger.type === "any") {
+            const filter = options.triggerFilter;
+            const matchedIndex = anyTrigger.triggers.findIndex((t) => matchesTriggerFilter(t, filter));
+            if (matchedIndex === -1) {
+                const available = anyTrigger.triggers.map(describeTrigger).join(", ");
+                throw new Error(`Unknown trigger "${options.triggerFilter}". Available triggers: ${available}`);
+            }
+            const allowedStepIds = new Set(originalSpell.triggerStepMap[matchedIndex] ?? []);
+            spell = {
+                ...originalSpell,
+                steps: originalSpell.steps.filter((s) => allowedStepIds.has(s.id)),
+            };
+            // Set trigger context to the matched sub-trigger instead of "any"
+            const matchedTrigger = anyTrigger.triggers[matchedIndex];
+            triggerOverride = { type: matchedTrigger.type, source: matchedTrigger.type };
+        }
+    }
     // Always simulate during preview
     const actionExecution = { mode: "simulate" };
     if (options.adapters && options.adapters.length > 0) {
@@ -53,7 +98,7 @@ export async function preview(options) {
         vault,
         chain,
         runId: options.runId,
-        trigger: options.trigger,
+        trigger: triggerOverride,
         params,
         persistentState,
         queryProvider: options.queryProvider,
@@ -275,98 +320,32 @@ export async function commit(options) {
             };
         }
     }
-    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);
+    const driftResult = await performDriftChecks(receipt.driftKeys, {
+        driftPolicy: options.driftPolicy,
+        driftValues: options.driftValues,
+        resolveDriftValue: options.resolveDriftValue,
+    });
+    if (driftResult.error) {
+        ledger.emit({ type: "commit_completed", runId, receiptId: receipt.id, success: false });
+        return {
+            success: false,
+            receiptId: receipt.id,
+            transactions: [],
+            driftChecks: driftResult.driftChecks,
+            finalState: receipt.finalState,
+            ledgerEvents: ledger.getEntries(),
+            error: driftResult.error,
+        };
+    }
+    const driftChecks = driftResult.driftChecks;
+    for (const check of driftChecks) {
         ledger.emit({
             type: "drift_check",
-            field: driftKey.field,
-            passed: driftResult.passed,
-            previewValue: driftResult.previewValue,
-            commitValue: driftResult.commitValue,
+            field: check.field,
+            passed: check.passed,
+            previewValue: check.previewValue,
+            commitValue: check.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;
@@ -462,6 +441,124 @@ export async function commit(options) {
         ledgerEvents: ledger.getEntries(),
     };
 }
+/**
+ * Build unsigned transactions from a preview receipt.
+ * Returns calldata for client-side signing (e.g. Privy SDK).
+ * Does NOT commit the receipt — commit() can still be called afterwards.
+ */
+export async function buildTransactions(options) {
+    const { receipt } = options;
+    // Validate receipt status
+    if (receipt.status !== "ready") {
+        return {
+            success: false,
+            receiptId: receipt.id,
+            transactions: [],
+            driftChecks: [],
+            error: createStructuredError("commit", "RECEIPT_INVALID_STATUS", `Receipt status is '${receipt.status}', expected 'ready'`),
+        };
+    }
+    // Validate receipt shape, integrity, and committed status
+    const validationError = validateBuildReceipt(receipt, {
+        receiptSecret: options.receiptSecret,
+        receiptIntegrity: options.receiptIntegrity,
+    });
+    if (validationError) {
+        return {
+            success: false,
+            receiptId: receipt.id,
+            transactions: [],
+            driftChecks: [],
+            error: validationError,
+        };
+    }
+    // Check receipt age
+    if (options.driftPolicy?.maxAge) {
+        const ageSec = (Date.now() - receipt.timestamp) / 1000;
+        if (ageSec > options.driftPolicy.maxAge) {
+            return {
+                success: false,
+                receiptId: receipt.id,
+                transactions: [],
+                driftChecks: [],
+                error: 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.",
+                }),
+            };
+        }
+    }
+    // Drift checks
+    const driftResult = await performDriftChecks(receipt.driftKeys, {
+        driftPolicy: options.driftPolicy,
+        driftValues: options.driftValues,
+        resolveDriftValue: options.resolveDriftValue,
+    });
+    if (driftResult.error) {
+        return {
+            success: false,
+            receiptId: receipt.id,
+            transactions: [],
+            driftChecks: driftResult.driftChecks,
+            error: driftResult.error,
+        };
+    }
+    // Build transactions for each planned action.
+    // Defer provider creation until we actually need it for EVM gas estimation.
+    const { chainId } = receipt.chainContext;
+    // Reject mismatched provider early — adapter context must use the receipt's
+    // chain so calldata (router addresses, token addresses) matches the preview.
+    if (options.provider && options.provider.chainId !== chainId) {
+        return {
+            success: false,
+            receiptId: receipt.id,
+            transactions: [],
+            driftChecks: driftResult.driftChecks,
+            error: createStructuredError("commit", "CHAIN_MISMATCH", `Provider chain ${options.provider.chainId} does not match receipt chain ${chainId}. ` +
+                `Provide a provider for chain ${chainId} or omit it to auto-create one.`),
+        };
+    }
+    const registry = createVenueRegistry(options.adapters ?? []);
+    let lazyProvider = options.provider;
+    const getProvider = () => {
+        if (!lazyProvider) {
+            lazyProvider = createProvider(chainId, options.rpcUrl);
+        }
+        return lazyProvider;
+    };
+    const transactions = [];
+    for (const planned of receipt.plannedActions) {
+        try {
+            options.progressCallback?.(`Building transactions for step '${planned.stepId}'...`);
+            const builtTxs = await buildActionTransactions(planned.action, chainId, getProvider, options.walletAddress, receipt.chainContext.vault, registry);
+            transactions.push({
+                stepId: planned.stepId,
+                builtTransactions: builtTxs,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (planned.onFailure === "skip") {
+                options.progressCallback?.(`Skipping step '${planned.stepId}' during transaction build: ${message}`);
+                continue;
+            }
+            return {
+                success: false,
+                receiptId: receipt.id,
+                transactions,
+                driftChecks: driftResult.driftChecks,
+                error: createStructuredError("commit", "BUILD_TRANSACTIONS_FAILED", `Failed to build transactions for step '${planned.stepId}': ${message}`),
+            };
+        }
+    }
+    return {
+        success: true,
+        receiptId: receipt.id,
+        transactions,
+        driftChecks: driftResult.driftChecks,
+    };
+}
 // =============================================================================
 // EXECUTE (backward-compatible wrapper)
 // =============================================================================
@@ -492,6 +589,7 @@ export async function execute(options) {
         warningCallback: options.warningCallback,
         crossChain: options.crossChain,
         queryProvider: options.queryProvider,
+        triggerFilter: options.triggerFilter,
     });
     if (!previewResult.success || !previewResult.receipt) {
         return convertPreviewToExecutionResult(previewResult, spell);
@@ -746,6 +844,54 @@ function registerIssuedReceipt(receipt) {
         timestamp: receipt.timestamp,
     });
 }
+// =============================================================================
+// RECEIPT INTEGRITY (cross-process verification)
+// =============================================================================
+/**
+ * Deterministic serialization of the receipt fields that must not change
+ * between preview and buildTransactions.  Used as the HMAC payload.
+ */
+function canonicalizeReceiptFields(receipt) {
+    const critical = {
+        id: receipt.id,
+        spellId: receipt.spellId,
+        chainId: receipt.chainContext.chainId,
+        vault: receipt.chainContext.vault,
+        timestamp: receipt.timestamp,
+        status: receipt.status,
+        plannedActions: receipt.plannedActions.map((pa) => ({
+            stepId: pa.stepId,
+            venue: pa.venue,
+            action: pa.action,
+            onFailure: pa.onFailure,
+        })),
+    };
+    return JSON.stringify(critical, (_key, value) => typeof value === "bigint" ? `__bigint__${value.toString()}` : value);
+}
+/**
+ * Sign a receipt for cross-process integrity verification.
+ * Call this at preview time, persist the returned hex string alongside
+ * the receipt, and pass it as `receiptIntegrity` to buildTransactions().
+ */
+export function signReceipt(receipt, secret) {
+    const payload = canonicalizeReceiptFields(receipt);
+    return createHmac("sha256", secret).update(payload).digest("hex");
+}
+/**
+ * Verify a receipt's HMAC integrity against the expected hash.
+ * Uses constant-time comparison to prevent timing attacks.
+ */
+function verifyReceiptIntegrity(receipt, secret, integrity) {
+    const expected = signReceipt(receipt, secret);
+    if (expected.length !== integrity.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(integrity, "hex"));
+    }
+    catch {
+        return false;
+    }
+}
 function validateCommitReceipt(receipt) {
     if (receipt.phase !== "preview") {
         return createStructuredError("commit", "RECEIPT_INVALID_PHASE", `Receipt phase is '${receipt.phase}', expected 'preview'`);
@@ -768,7 +914,114 @@ function validateCommitReceipt(receipt) {
     }
     return undefined;
 }
-async function resolveCommitDriftValue(driftKey, options) {
+/**
+ * Receipt validation for buildTransactions().
+ *
+ * Same-process receipts (in issuedReceipts) are verified via the in-memory
+ * tamper check, exactly like commit().
+ *
+ * Cross-process receipts (not in issuedReceipts) require an HMAC integrity
+ * proof produced by signReceipt().  Without this, a caller could fabricate
+ * or modify plannedActions and obtain signable calldata for actions that
+ * were never previewed.
+ *
+ * We also check committedReceipts to prevent building calldata for a
+ * receipt that has already been committed.
+ */
+function validateBuildReceipt(receipt, integrity) {
+    if (receipt.phase !== "preview") {
+        return createStructuredError("commit", "RECEIPT_INVALID_PHASE", `Receipt phase is '${receipt.phase}', expected 'preview'`);
+    }
+    if (!receipt.id.startsWith("rcpt_")) {
+        return createStructuredError("commit", "RECEIPT_INVALID_ID", "Receipt ID must start with 'rcpt_'");
+    }
+    if (committedReceipts.has(receipt.id)) {
+        return createStructuredError("commit", "RECEIPT_ALREADY_COMMITTED", "Receipt has already been committed.");
+    }
+    // Same-process: verify against in-memory provenance
+    const issuedReceipt = issuedReceipts.get(receipt.id);
+    if (issuedReceipt) {
+        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;
+    }
+    // Cross-process: require HMAC integrity proof
+    if (!integrity.receiptSecret || !integrity.receiptIntegrity) {
+        return createStructuredError("commit", "RECEIPT_INTEGRITY_MISSING", "Cross-process receipts require receiptSecret and receiptIntegrity for verification. " +
+            "Use signReceipt() at preview time to generate the integrity hash.");
+    }
+    if (!verifyReceiptIntegrity(receipt, integrity.receiptSecret, integrity.receiptIntegrity)) {
+        return createStructuredError("commit", "RECEIPT_INTEGRITY_FAILED", "Receipt integrity verification failed. The receipt may have been modified.");
+    }
+    return undefined;
+}
+/** Run drift checks for a set of drift keys. Returns accumulated checks and optional error. */
+async function performDriftChecks(driftKeys, options) {
+    const driftChecks = [];
+    for (const driftKey of driftKeys) {
+        if (options.driftPolicy?.maxAge) {
+            const keyAgeSec = Math.max(0, Math.floor((Date.now() - driftKey.timestamp) / 1000));
+            if (keyAgeSec > options.driftPolicy.maxAge) {
+                return {
+                    driftChecks,
+                    error: 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.",
+                    }),
+                };
+            }
+        }
+        let resolvedValue;
+        try {
+            resolvedValue = await resolveDriftValue(driftKey, options);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                driftChecks,
+                error: createStructuredError("commit", "DRIFT_RESOLUTION_FAILED", `Failed to resolve drift value for '${driftKey.field}': ${message}`, {
+                    constraint: "drift_keys",
+                    path: driftKey.field,
+                }),
+            };
+        }
+        if (!resolvedValue.found && options.driftPolicy) {
+            return {
+                driftChecks,
+                error: 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.",
+                }),
+            };
+        }
+        const commitValue = resolvedValue.found ? resolvedValue.value : driftKey.previewValue;
+        const driftResult = evaluateDriftKey(driftKey, commitValue, options.driftPolicy);
+        driftChecks.push(driftResult);
+        if (!driftResult.passed) {
+            const tolerance = resolveToleranceBps(driftKey, options.driftPolicy);
+            return {
+                driftChecks,
+                error: 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.",
+                }),
+            };
+        }
+    }
+    return { driftChecks };
+}
+async function resolveDriftValue(driftKey, options) {
     if (options.driftValues && Object.hasOwn(options.driftValues, driftKey.field)) {
         return { found: true, value: options.driftValues[driftKey.field] };
     }
@@ -780,6 +1033,73 @@ async function resolveCommitDriftValue(driftKey, options) {
     }
     return { found: false, value: undefined };
 }
+/**
+ * Build unsigned transactions for a single action.
+ * Mirrors Executor.buildAction() for EVM actions without a wallet, and
+ * rejects offchain adapters because they do not produce signable calldata.
+ *
+ * The provider is lazy so we never instantiate it for receipts that
+ * contain only offchain or zero planned actions.
+ *
+ * Always uses the receipt's chainId for adapter context (not provider.chainId)
+ * so calldata matches the previewed chain even if a mismatched provider
+ * sneaks through.
+ */
+async function buildActionTransactions(action, chainId, getProvider, walletAddress, vault, registry) {
+    const normalizeBuildResult = (result) => Array.isArray(result) ? result : [result];
+    if (action.type === "custom") {
+        const adapter = registry.get(action.venue);
+        if (!adapter) {
+            throw new Error(`Adapter '${action.venue}' is not registered for custom action '${action.op}'.`);
+        }
+        if (!adapter.meta.supportedChains.includes(chainId)) {
+            throw new Error(`Adapter '${adapter.meta.name}' does not support chain ${chainId} for custom action '${action.op}'.`);
+        }
+        if (adapter.meta.executionType === "offchain") {
+            throw new Error(`Adapter '${adapter.meta.name}' is offchain and does not produce signable transactions for custom action '${action.op}'. ` +
+                `Use commit() instead for offchain execution.`);
+        }
+        const provider = getProvider();
+        if (!adapter.buildAction) {
+            throw new Error(`Adapter '${adapter.meta.name}' does not build custom EVM actions.`);
+        }
+        return normalizeBuildResult(await adapter.buildAction(action, {
+            provider,
+            walletAddress,
+            vault,
+            chainId,
+            mode: "execute",
+        }));
+    }
+    if ("venue" in action && action.venue) {
+        const adapter = registry.get(action.venue);
+        if (!adapter) {
+            throw new Error(`Adapter '${action.venue}' is not registered`);
+        }
+        if (!adapter.meta.supportedChains.includes(chainId)) {
+            throw new Error(`Adapter '${adapter.meta.name}' does not support chain ${chainId}.`);
+        }
+        if (adapter.meta.executionType === "offchain") {
+            throw new Error(`Adapter '${adapter.meta.name}' is offchain and does not produce signable transactions. ` +
+                `Use commit() instead for offchain execution.`);
+        }
+        const provider = getProvider();
+        if (!adapter.buildAction) {
+            throw new Error(`Adapter '${adapter.meta.name}' does not support EVM actions`);
+        }
+        return normalizeBuildResult(await adapter.buildAction(action, {
+            provider,
+            walletAddress,
+            vault,
+            chainId,
+            mode: "execute",
+        }));
+    }
+    // Built-in action types (transfer, approve, etc.)
+    const provider = getProvider();
+    const txBuilder = new TransactionBuilder(provider, walletAddress);
+    return [await txBuilder.buildAction(action)];
+}
 function evaluateDriftKey(driftKey, commitValue, policy) {
     const tolerance = resolveToleranceBps(driftKey, policy);
     const numericPreview = toNumeric(driftKey.previewValue);