@grimoirelabs/core 0.19.0 → 0.21.0

package/dist/runtime/interpreter.js

@@ -27,18 +27,104 @@ 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;
+function normalizeSelectedTrigger(selectedTrigger, triggerFilter) {
+    if (selectedTrigger && triggerFilter) {
+        throw new Error("selectedTrigger cannot be combined with triggerFilter");
+    }
+    const normalized = selectedTrigger ?? (triggerFilter ? { label: triggerFilter } : undefined);
+    if (!normalized) {
+        return undefined;
+    }
+    const definedFields = [normalized.id, normalized.index, normalized.label].filter((value) => value !== undefined);
+    if (definedFields.length > 1) {
+        throw new Error("selectedTrigger must define exactly one of id, index, or label");
+    }
+    return normalized;
+}
+function getSpellTriggerHandlers(spell) {
+    if (spell.triggerHandlers && spell.triggerHandlers.length > 0) {
+        return spell.triggerHandlers;
+    }
+    const primaryTrigger = spell.triggers[0];
+    if (primaryTrigger?.type === "any") {
+        return primaryTrigger.triggers.map((trigger, index) => {
+            const handlerTrigger = assertConcreteTrigger(trigger);
+            const stepIds = spell.triggerStepMap?.[index] ?? [];
+            return {
+                selector: {
+                    id: `trigger_${index}`,
+                    index,
+                    label: describeTriggerLabel(handlerTrigger),
+                    source: resolveTriggerSourceFromSpell(stepIds, spell),
+                },
+                trigger: handlerTrigger,
+                stepIds,
+            };
+        });
+    }
+    const trigger = (primaryTrigger ?? { type: "manual" });
+    return [
+        {
+            selector: {
+                id: "trigger_0",
+                index: 0,
+                label: describeTriggerLabel(trigger),
+                source: resolveTriggerSourceFromSpell(spell.steps.map((step) => step.id), spell),
+            },
+            trigger,
+            stepIds: spell.steps.map((step) => step.id),
+        },
+    ];
+}
+function resolveSelectedTriggerHandler(spell, selectedTrigger) {
+    if (!selectedTrigger) {
+        return undefined;
+    }
+    const handlers = getSpellTriggerHandlers(spell);
+    if (selectedTrigger.id !== undefined) {
+        const match = handlers.find((handler) => handler.selector.id === selectedTrigger.id);
+        if (!match) {
+            throw new Error(`Unknown trigger id "${selectedTrigger.id}". Available triggers: ${formatTriggerCandidates(handlers)}`);
+        }
+        return match;
+    }
+    if (selectedTrigger.index !== undefined) {
+        const match = handlers.find((handler) => handler.selector.index === selectedTrigger.index);
+        if (!match) {
+            throw new Error(`Unknown trigger index "${selectedTrigger.index}". Available triggers: ${formatTriggerCandidates(handlers)}`);
+        }
+        return match;
+    }
+    if (selectedTrigger.label !== undefined) {
+        const matches = handlers.filter((handler) => getTriggerMatchLabels(handler).has(selectedTrigger.label));
+        if (matches.length === 0) {
+            throw new Error(`Unknown trigger label "${selectedTrigger.label}". Available triggers: ${formatTriggerCandidates(handlers)}`);
+        }
+        if (matches.length > 1) {
+            throw new Error(`Ambiguous trigger label "${selectedTrigger.label}". Matching triggers: ${formatTriggerCandidates(matches)}`);
+        }
+        return matches[0];
+    }
+    return undefined;
+}
+function getTriggerMatchLabels(handler) {
+    const labels = new Set([handler.selector.label, handler.trigger.type]);
+    if (handler.trigger.type === "schedule") {
+        if (handler.trigger.cron === "0 * * * *") {
+            labels.add("hourly");
+        }
+        if (handler.trigger.cron === "0 0 * * *") {
+            labels.add("daily");
+        }
+    }
+    return labels;
+}
+function formatTriggerCandidates(handlers) {
+    return handlers
+        .map((handler) => `{id=${handler.selector.id}, index=${handler.selector.index}, label=${handler.selector.label}}`)
+        .join(", ");
 }
-/** Describe a trigger for user-facing messages */
-function describeTrigger(trigger) {
+function describeTriggerLabel(trigger) {
     if (trigger.type === "schedule") {
         if (trigger.cron === "0 * * * *")
             return "hourly";
@@ -46,8 +132,26 @@ function describeTrigger(trigger) {
             return "daily";
         return `schedule(${trigger.cron})`;
     }
+    if (trigger.type === "event") {
+        return `event(${trigger.event})`;
+    }
     return trigger.type;
 }
+function resolveTriggerSourceFromSpell(stepIds, spell) {
+    for (const stepId of stepIds) {
+        const loc = spell.sourceMap?.[stepId];
+        if (loc) {
+            return loc;
+        }
+    }
+    return { line: 1, column: 1 };
+}
+function assertConcreteTrigger(trigger) {
+    if (trigger.type === "any") {
+        throw new Error("Nested trigger.any handlers are not supported");
+    }
+    return trigger;
+}
 /**
  * Preview a spell — runs the full step loop in simulation mode,
  * collects PlannedActions and ValueDeltas, and assembles a Receipt.
@@ -57,24 +161,25 @@ export async function preview(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 };
-        }
+    let selectedTrigger;
+    const triggerSelection = normalizeSelectedTrigger(options.selectedTrigger, options.triggerFilter);
+    const matchedTriggerHandler = resolveSelectedTriggerHandler(originalSpell, triggerSelection);
+    if (matchedTriggerHandler) {
+        const allowedStepIds = new Set(matchedTriggerHandler.stepIds);
+        spell = {
+            ...originalSpell,
+            steps: originalSpell.steps.filter((step) => allowedStepIds.has(step.id)),
+            triggers: [matchedTriggerHandler.trigger],
+            triggerHandlers: [matchedTriggerHandler],
+            triggerStepMap: { 0: [...matchedTriggerHandler.stepIds] },
+        };
+        triggerOverride = {
+            ...matchedTriggerHandler.trigger,
+            id: matchedTriggerHandler.selector.id,
+            index: matchedTriggerHandler.selector.index,
+            label: matchedTriggerHandler.selector.label,
+        };
+        selectedTrigger = matchedTriggerHandler.selector;
     }
     // Always simulate during preview
     const actionExecution = { mode: "simulate" };
@@ -143,6 +248,7 @@ export async function preview(options) {
                 receipt,
                 error: structuredError,
                 ledgerEvents: ledger.getEntries(),
+                selectedTrigger,
             };
         }
         // Run step loop in preview mode — action steps produce PlannedActions instead of executing
@@ -169,6 +275,7 @@ export async function preview(options) {
                 receipt,
                 error: structuredError,
                 ledgerEvents: ledger.getEntries(),
+                selectedTrigger,
             };
         }
         // Post-execution guards
@@ -194,6 +301,7 @@ export async function preview(options) {
                 receipt,
                 error: structuredError,
                 ledgerEvents: ledger.getEntries(),
+                selectedTrigger,
             };
         }
         const valueFlow = evaluatePreviewValueFlow(ctx, plannedActions, valueDeltas);
@@ -222,6 +330,7 @@ export async function preview(options) {
                 receipt,
                 error: structuredError,
                 ledgerEvents: ledger.getEntries(),
+                selectedTrigger,
             };
         }
         const requiresApproval = valueFlow.requiresApproval;
@@ -255,16 +364,33 @@ export async function preview(options) {
             metrics: ctx.metrics,
         });
         ledger.emit({ type: "preview_completed", runId: ctx.runId, receiptId, status: "ready" });
-        return { success: true, receipt, ledgerEvents: ledger.getEntries() };
+        return { success: true, receipt, ledgerEvents: ledger.getEntries(), selectedTrigger };
     }
     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() };
+        return {
+            success: false,
+            error: structuredError,
+            ledgerEvents: ledger.getEntries(),
+            selectedTrigger,
+        };
     }
 }
+function commitFailureResult(receiptId, runId, ledger, driftChecks, finalState, error) {
+    ledger.emit({ type: "commit_completed", runId, receiptId, success: false });
+    return {
+        success: false,
+        receiptId,
+        transactions: [],
+        driftChecks,
+        finalState,
+        ledgerEvents: ledger.getEntries(),
+        error,
+    };
+}
 /**
  * Commit a receipt — executes planned actions from the preview.
  */
@@ -309,16 +435,7 @@ export async function commit(options) {
                 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,
-            };
+            return commitFailureResult(receipt.id, runId, ledger, [], receipt.finalState, structuredError);
         }
     }
     const driftResult = await performDriftChecks(receipt.driftKeys, {
@@ -327,16 +444,7 @@ export async function commit(options) {
         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,
-        };
+        return commitFailureResult(receipt.id, runId, ledger, driftResult.driftChecks, receipt.finalState, driftResult.error);
     }
     const driftChecks = driftResult.driftChecks;
     for (const check of driftChecks) {
@@ -353,29 +461,11 @@ export async function commit(options) {
     if (options.provider && options.provider.chainId !== chainId) {
         const structuredError = 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.`);
-        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,
-        };
+        return commitFailureResult(receipt.id, runId, ledger, driftChecks, receipt.finalState, structuredError);
     }
     const resolvedAssets = resolveAuthoritativeAssets(receipt.assets, options.assets);
     if (resolvedAssets.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: resolvedAssets.error,
-        };
+        return commitFailureResult(receipt.id, runId, ledger, driftChecks, receipt.finalState, resolvedAssets.error);
     }
     const provider = options.provider ?? createProvider(chainId, options.rpcUrl);
     const executor = createExecutor({
@@ -570,7 +660,15 @@ export async function buildTransactions(options) {
     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, resolvedAssets.assets);
+            const builtTxs = await buildActionTransactions({
+                action: planned.action,
+                chainId,
+                getProvider,
+                walletAddress: options.walletAddress,
+                vault: receipt.chainContext.vault,
+                registry,
+                assets: resolvedAssets.assets,
+            });
             transactions.push({
                 stepId: planned.stepId,
                 builtTransactions: builtTxs,
@@ -628,6 +726,7 @@ export async function execute(options) {
         warningCallback: options.warningCallback,
         crossChain: options.crossChain,
         queryProvider: options.queryProvider,
+        selectedTrigger: options.selectedTrigger,
         triggerFilter: options.triggerFilter,
     });
     if (!previewResult.success || !previewResult.receipt) {
@@ -771,6 +870,7 @@ function convertPreviewToExecutionResult(previewResult, _spell) {
         },
         finalState: receipt?.finalState ?? {},
         ledgerEvents: previewResult.ledgerEvents,
+        selectedTrigger: previewResult.selectedTrigger,
         receipt,
     };
 }
@@ -801,6 +901,7 @@ function convertPreviewCommitToExecutionResult(previewResult, commitResult) {
         },
         finalState: commitResult.finalState,
         ledgerEvents: [...previewResult.ledgerEvents, ...commitResult.ledgerEvents],
+        selectedTrigger: previewResult.selectedTrigger,
         receipt,
         commit: commitResult,
     };
@@ -920,25 +1021,7 @@ function registerIssuedReceipt(receipt) {
  * 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,
-        })),
-        assets: canonicalizeAssetDefs(receipt.assets),
-    };
-    return JSON.stringify(critical, (_key, value) => typeof value === "bigint" ? `__bigint__${value.toString()}` : value);
-}
-function canonicalizeReceiptFieldsLegacy(receipt) {
+function canonicalizeReceiptFields(receipt, includeAssets = true) {
     const critical = {
         id: receipt.id,
         spellId: receipt.spellId,
@@ -953,6 +1036,9 @@ function canonicalizeReceiptFieldsLegacy(receipt) {
             onFailure: pa.onFailure,
         })),
     };
+    if (includeAssets) {
+        critical.assets = canonicalizeAssetDefs(receipt.assets);
+    }
     return JSON.stringify(critical, (_key, value) => typeof value === "bigint" ? `__bigint__${value.toString()}` : value);
 }
 function canonicalizeAssetDefs(assets) {
@@ -998,7 +1084,7 @@ function verifyReceiptIntegrity(receipt, secret, integrity) {
         return false;
     }
     const legacyExpected = createHmac("sha256", secret)
-        .update(canonicalizeReceiptFieldsLegacy(receipt))
+        .update(canonicalizeReceiptFields(receipt, false))
         .digest("hex");
     return integrityMatches(legacyExpected, integrity);
 }
@@ -1153,19 +1239,8 @@ async function resolveDriftValue(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, assets) {
+async function buildActionTransactions(options) {
+    const { action, chainId, getProvider, walletAddress, vault, registry, assets } = options;
     const normalizeBuildResult = (result) => Array.isArray(result) ? result : [result];
     if (action.type === "custom") {
         const adapter = registry.get(action.venue);