@n8n/instance-ai 1.12.4 → 1.13.1

package/dist/tools/orchestration/verify-built-workflow.tool.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.verifyBuiltWorkflowInputSchema = void 0;
 exports.createVerifyBuiltWorkflowTool = createVerifyBuiltWorkflowTool;
 const agents_1 = require("@n8n/agents");
+const utils_1 = require("@n8n/utils");
 const zod_1 = require("zod");
 const remediation_1 = require("../../workflow-loop/remediation");
 const DEFAULT_NODE_PREVIEW_CHARS = 600;
@@ -16,9 +17,6 @@ function stringifyForToolOutput(value) {
         return String(value);
     }
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function unwrapUntrustedData(value) {
     const match = /^<untrusted_data\b[^>]*>\n([\s\S]*)\n<\/untrusted_data>$/i.exec(value);
     if (!match)
@@ -37,67 +35,8 @@ function unwrapUntrustedData(value) {
 function outputForInspection(nodeOutput) {
     return typeof nodeOutput === 'string' ? unwrapUntrustedData(nodeOutput) : nodeOutput;
 }
-async function extractDataTableWriteNodes(workflowService, workflowId) {
-    try {
-        const json = await workflowService.getAsWorkflowJSON(workflowId);
-        const out = [];
-        for (const node of json.nodes ?? []) {
-            if (node.type !== 'n8n-nodes-base.dataTable')
-                continue;
-            const params = node.parameters;
-            const operation = params?.operation;
-            if (operation !== 'insert' && operation !== 'upsert' && operation !== 'update')
-                continue;
-            const ref = params?.dataTableId;
-            let dataTableId;
-            if (typeof ref === 'string' && ref.length > 0) {
-                dataTableId = ref;
-            }
-            else if (ref &&
-                typeof ref === 'object' &&
-                'value' in ref &&
-                typeof ref.value === 'string') {
-                const value = ref.value;
-                if (value.length > 0)
-                    dataTableId = value;
-            }
-            if (!dataTableId || !node.name)
-                continue;
-            out.push({ nodeName: node.name, dataTableId, operation });
-        }
-        return out;
-    }
-    catch {
-        return [];
-    }
-}
-function extractRowIdsFromNodeOutput(nodeOutput) {
-    const ids = [];
-    const visit = (value) => {
-        const inspected = outputForInspection(value);
-        if (!inspected)
-            return;
-        if (Array.isArray(inspected)) {
-            for (const item of inspected)
-                visit(item);
-            return;
-        }
-        if (!isRecord(inspected))
-            return;
-        const row = inspected;
-        if (row.json !== undefined) {
-            visit(row.json);
-            return;
-        }
-        const id = row.id;
-        if (typeof id === 'number' && Number.isFinite(id))
-            ids.push(id);
-    };
-    visit(nodeOutput);
-    return ids;
-}
 function getCountFromMetadata(value) {
-    if (!isRecord(value))
+    if (!(0, utils_1.isRecord)(value))
         return undefined;
     for (const key of ['totalItems', '_itemCount']) {
         const count = value[key];
@@ -128,7 +67,7 @@ function previewValue(value, maxChars) {
     }
     return { preview: `${serialized.slice(0, maxChars)}...`, truncated: true };
 }
-function buildNodePreviews(resultData, maxChars) {
+function buildNodePreviews(resultData, maxChars, simulatedNodeNames) {
     if (!resultData)
         return [];
     return Object.entries(resultData).map(([nodeName, nodeOutput]) => {
@@ -140,9 +79,26 @@ function buildNodePreviews(resultData, maxChars) {
             preview: preview.preview,
             truncated: preview.truncated,
             chars: serialized.length,
+            ...(simulatedNodeNames?.has(nodeName) ? { simulated: true } : {}),
         };
     });
 }
+function buildVerificationPinData(buildOutcome) {
+    const merged = { ...(buildOutcome.verificationPinData ?? {}) };
+    const fixtures = buildOutcome.simulationFixtures ?? {};
+    const simulatedNodes = [];
+    for (const verdict of buildOutcome.nodeSimulationPlan ?? []) {
+        if (verdict.verdict !== 'simulate')
+            continue;
+        simulatedNodes.push({ nodeName: verdict.nodeName, reason: verdict.reason });
+        const items = fixtures[verdict.nodeName];
+        merged[verdict.nodeName] = items?.length ? items : [{}];
+    }
+    return {
+        pinData: Object.keys(merged).length > 0 ? merged : undefined,
+        simulatedNodes,
+    };
+}
 function countProducedOutputRows(resultData) {
     if (!resultData)
         return undefined;
@@ -154,98 +110,6 @@ function countProducedOutputRows(resultData) {
     }
     return count;
 }
-const SNAPSHOT_PAGE_SIZE = 1000;
-const SNAPSHOT_MAX_ROWS = 100_000;
-async function cleanupInsertedRowsByNodeOutput(dataTableService, writeNodes, resultData, preIdsByTable, logger) {
-    if (!resultData)
-        return 0;
-    const createdIdsByTable = new Map();
-    for (const { nodeName, dataTableId, operation } of writeNodes) {
-        if (operation !== 'insert')
-            continue;
-        const output = resultData[nodeName];
-        if (!output)
-            continue;
-        const ids = extractRowIdsFromNodeOutput(output);
-        if (ids.length === 0)
-            continue;
-        let bucket = createdIdsByTable.get(dataTableId);
-        if (!bucket) {
-            bucket = new Set();
-            createdIdsByTable.set(dataTableId, bucket);
-        }
-        for (const id of ids)
-            bucket.add(id);
-    }
-    let total = 0;
-    for (const [dataTableId, ids] of createdIdsByTable) {
-        const preIds = preIdsByTable.get(dataTableId);
-        if (preIds === undefined || preIds === null) {
-            logger.warn('Skipping data-table cleanup: pre-verify snapshot unavailable. Rows left in place to avoid deleting existing data.', { dataTableId, candidateIds: ids.size });
-            continue;
-        }
-        const toDelete = [...ids].filter((id) => !preIds.has(id));
-        if (toDelete.length === 0)
-            continue;
-        try {
-            await dataTableService.deleteRows(dataTableId, {
-                type: 'or',
-                filters: toDelete.map((id) => ({
-                    columnName: 'id',
-                    condition: 'eq',
-                    value: id,
-                })),
-            });
-            total += toDelete.length;
-        }
-        catch {
-        }
-    }
-    return total;
-}
-async function snapshotRowIdsPerTable(dataTableService, dataTableIds, logger) {
-    const out = new Map();
-    for (const id of dataTableIds) {
-        try {
-            const bucket = new Set();
-            let offset = 0;
-            let truncated = false;
-            for (;;) {
-                const { data } = await dataTableService.queryRows(id, {
-                    limit: SNAPSHOT_PAGE_SIZE,
-                    offset,
-                });
-                for (const row of data) {
-                    const rid = row.id;
-                    if (typeof rid === 'number')
-                        bucket.add(rid);
-                }
-                if (data.length < SNAPSHOT_PAGE_SIZE)
-                    break;
-                offset += SNAPSHOT_PAGE_SIZE;
-                if (offset >= SNAPSHOT_MAX_ROWS) {
-                    truncated = true;
-                    break;
-                }
-            }
-            if (truncated) {
-                logger.warn('Data-table pre-verify snapshot exceeded row cap — cleanup disabled for this table', { dataTableId: id, cap: SNAPSHOT_MAX_ROWS });
-                out.set(id, null);
-            }
-            else {
-                out.set(id, bucket);
-            }
-        }
-        catch (error) {
-            logger.warn('Data-table pre-verify snapshot failed — cleanup disabled for this table', {
-                dataTableId: id,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            out.set(id, null);
-        }
-    }
-    return out;
-}
 exports.verifyBuiltWorkflowInputSchema = zod_1.z.object({
     workItemId: zod_1.z.string().describe('The work item ID from the build (wi_XXXXXXXX)'),
     workflowId: zod_1.z.string().describe('The workflow ID to verify'),
@@ -288,34 +152,47 @@ const remediationOutputSchema = zod_1.z
     attemptCount: zod_1.z.number().int().min(0).optional(),
 })
     .optional();
+const CREDENTIAL_FAILURE_KEYWORDS = [
+    'credential',
+    'unauthorized',
+    'forbidden',
+    '401',
+    '403',
+    'free tier',
+    'quota',
+];
+const TRANSIENT_FAILURE_KEYWORDS = ['429', 'rate limit', '502', 'bad gateway', 'timed out'];
+function messageMatchesAny(normalized, keywords) {
+    return keywords.some((keyword) => normalized.includes(keyword));
+}
 function classifyVerificationFailure(error, status, buildOutcome) {
-    if (buildOutcome.hasUnresolvedPlaceholders) {
-        return (0, remediation_1.createRemediation)({
-            category: 'needs_setup',
-            shouldEdit: false,
-            reason: 'mocked_credentials_or_placeholders',
-            guidance: 'Workflow submitted successfully, but verification is blocked by unresolved setup values. Stop code edits and route to workflows(action="setup").',
-        });
-    }
     if (status === 'waiting') {
+        const hasSimulationPlan = (buildOutcome.nodeSimulationPlan?.length ?? 0) > 0;
         return (0, remediation_1.createRemediation)({
             category: 'needs_setup',
             shouldEdit: false,
-            reason: 'execution_waiting',
-            guidance: 'Workflow verification is waiting for user action or setup. Stop code edits and ask the user to complete setup.',
+            reason: hasSimulationPlan ? 'unsimulated_user_action_node' : 'execution_waiting',
+            guidance: hasSimulationPlan
+                ? 'Verification paused on a node that waits for user action and was not simulated — ' +
+                    'nodes downstream of it were not verified. This is not a workflow bug: do not edit ' +
+                    'the code. Report to the user which node paused and that the rest of the workflow ' +
+                    'needs a manual test.'
+                : 'Workflow verification is waiting for user action or setup. Stop code edits and ask the user to complete setup.',
         });
     }
     const normalized = (error ?? '').toLowerCase();
     const mockedCredentialTypeCount = buildOutcome.mockedCredentialTypes?.length ?? 0;
     const mockedNodeCount = buildOutcome.mockedNodeNames?.length ?? 0;
     const hasMockedCredentialContext = Boolean(mockedCredentialTypeCount > 0 || mockedNodeCount > 0);
-    if (normalized.includes('credential') ||
-        normalized.includes('unauthorized') ||
-        normalized.includes('forbidden') ||
-        normalized.includes('401') ||
-        normalized.includes('403') ||
-        normalized.includes('free tier') ||
-        normalized.includes('quota')) {
+    if ((0, utils_1.isPlaceholderValue)(error)) {
+        return (0, remediation_1.createRemediation)({
+            category: 'needs_setup',
+            shouldEdit: false,
+            reason: 'mocked_credentials_or_placeholders',
+            guidance: 'Workflow verification reached an unresolved setup value. Stop code edits and route to workflows(action="setup").',
+        });
+    }
+    if (messageMatchesAny(normalized, CREDENTIAL_FAILURE_KEYWORDS)) {
         return (0, remediation_1.createRemediation)({
             category: 'needs_setup',
             shouldEdit: false,
@@ -327,11 +204,7 @@ function classifyVerificationFailure(error, status, buildOutcome) {
                 : 'Workflow submitted successfully, but verification requires credential or account setup. Stop code edits and route to workflows(action="setup").',
         });
     }
-    if (normalized.includes('429') ||
-        normalized.includes('rate limit') ||
-        normalized.includes('502') ||
-        normalized.includes('bad gateway') ||
-        normalized.includes('timed out')) {
+    if (messageMatchesAny(normalized, TRANSIENT_FAILURE_KEYWORDS)) {
         return (0, remediation_1.createRemediation)({
             category: 'blocked',
             shouldEdit: false,
@@ -346,94 +219,281 @@ function classifyVerificationFailure(error, status, buildOutcome) {
         guidance: 'Verification found a workflow runtime failure. Diagnose it and apply one batched workflow-code repair if the guard allows it.',
     });
 }
-function createVerifyBuiltWorkflowTool(context) {
-    return new agents_1.Tool('verify-built-workflow')
-        .description('Run a built workflow using sidecar verification context from the build outcome. ' +
-        'Use this as the standard verifier for workflows produced by the workflow-builder. ' +
-        'It supports manual, schedule, form, webhook, chat, and other event triggers with build-outcome pin data, mocked credential context, or trigger-shaped inputData. ' +
-        'Use `executions(action="run")` only for ad hoc runs outside build verification. ' +
-        'CRITICAL: `inputData` shape depends on the trigger type — see the per-trigger guidance on the inputData field. ' +
-        'Passing the wrong shape (e.g. wrapping form fields under `formFields`) produces null downstream values that ' +
-        'look like an expression bug but are not — do not patch the workflow, re-run verify with the correct shape.')
-        .input(exports.verifyBuiltWorkflowInputSchema)
-        .output(zod_1.z.object({
-        executionId: zod_1.z.string().optional(),
-        success: zod_1.z.boolean(),
-        status: zod_1.z.enum(['running', 'success', 'error', 'waiting', 'unknown']).optional(),
-        nodesExecuted: zod_1.z.array(zod_1.z.string()).optional(),
-        nodePreviews: zod_1.z
-            .array(zod_1.z.object({
-            nodeName: zod_1.z.string(),
-            itemCount: zod_1.z.number().optional(),
-            preview: zod_1.z.string(),
-            truncated: zod_1.z.boolean(),
-            chars: zod_1.z.number(),
-        }))
-            .optional(),
-        data: zod_1.z.record(zod_1.z.unknown()).optional(),
-        error: zod_1.z.string().optional(),
-        remediation: remediationOutputSchema,
-        guidance: zod_1.z.string().optional(),
+const verifyBuiltWorkflowOutputSchema = zod_1.z.object({
+    executionId: zod_1.z.string().optional(),
+    success: zod_1.z.boolean(),
+    status: zod_1.z.enum(['running', 'success', 'error', 'waiting', 'unknown']).optional(),
+    nodesExecuted: zod_1.z.array(zod_1.z.string()).optional(),
+    nodePreviews: zod_1.z
+        .array(zod_1.z.object({
+        nodeName: zod_1.z.string(),
+        itemCount: zod_1.z.number().optional(),
+        preview: zod_1.z.string(),
+        truncated: zod_1.z.boolean(),
+        chars: zod_1.z.number(),
+        simulated: zod_1.z.boolean().optional(),
     }))
-        .handler(async (input) => {
-        if (!context.workflowTaskService || !context.domainContext) {
-            const remediation = (0, remediation_1.createRemediation)({
-                category: 'blocked',
-                shouldEdit: false,
-                reason: 'verification_support_unavailable',
-                guidance: 'Verification support is not available. Stop code edits and explain the blocker.',
-            });
-            return { success: false, error: 'Verification support not available.', remediation };
-        }
-        const stateBefore = await context.workflowTaskService.getWorkflowLoopState(input.workItemId);
-        const terminalRemediation = stateBefore?.lastRemediation && !stateBefore.lastRemediation.shouldEdit
-            ? (0, remediation_1.terminalRemediationFromState)(stateBefore, context.runId)
-            : undefined;
-        if (terminalRemediation) {
-            return {
+        .optional(),
+    simulatedNodes: zod_1.z.array(zod_1.z.object({ nodeName: zod_1.z.string(), reason: zod_1.z.string() })).optional(),
+    simulationNote: zod_1.z.string().optional(),
+    lastNodeExecuted: zod_1.z.string().optional(),
+    nodesNotReached: zod_1.z.array(zod_1.z.string()).optional(),
+    coverageNote: zod_1.z.string().optional(),
+    data: zod_1.z.record(zod_1.z.unknown()).optional(),
+    error: zod_1.z.string().optional(),
+    remediation: remediationOutputSchema,
+    guidance: zod_1.z.string().optional(),
+});
+function namesOrDataKeys(reachedNames, data) {
+    if (reachedNames.size > 0)
+        return [...reachedNames];
+    return data ? Object.keys(data) : undefined;
+}
+async function resolveVerifyPreconditions(input, context) {
+    if (!context.workflowTaskService || !context.domainContext) {
+        const remediation = (0, remediation_1.createRemediation)({
+            category: 'blocked',
+            shouldEdit: false,
+            reason: 'verification_support_unavailable',
+            guidance: 'Verification support is not available. Stop code edits and explain the blocker.',
+        });
+        return {
+            result: { success: false, error: 'Verification support not available.', remediation },
+        };
+    }
+    const stateBefore = await context.workflowTaskService.getWorkflowLoopState(input.workItemId);
+    const terminalRemediation = stateBefore?.lastRemediation && !stateBefore.lastRemediation.shouldEdit
+        ? (0, remediation_1.terminalRemediationFromState)(stateBefore, context.runId)
+        : undefined;
+    if (terminalRemediation) {
+        return {
+            result: {
                 success: false,
                 error: terminalRemediation.guidance,
                 remediation: terminalRemediation,
                 guidance: terminalRemediation.guidance,
-            };
-        }
-        const buildOutcome = await context.workflowTaskService.getBuildOutcome(input.workItemId);
-        if (!buildOutcome) {
-            const remediation = (0, remediation_1.createRemediation)({
-                category: 'blocked',
-                shouldEdit: false,
-                reason: 'missing_build_outcome',
-                guidance: `No build outcome found for work item ${input.workItemId}. Stop code edits and explain the blocker.`,
-            });
-            return {
+            },
+        };
+    }
+    const buildOutcome = await context.workflowTaskService.getBuildOutcome(input.workItemId);
+    if (!buildOutcome) {
+        const remediation = (0, remediation_1.createRemediation)({
+            category: 'blocked',
+            shouldEdit: false,
+            reason: 'missing_build_outcome',
+            guidance: `No build outcome found for work item ${input.workItemId}. Stop code edits and explain the blocker.`,
+        });
+        return {
+            result: {
                 success: false,
                 error: `No build outcome found for work item ${input.workItemId}.`,
                 remediation,
                 guidance: remediation.guidance,
-            };
-        }
-        if (!buildOutcome.workflowId) {
-            return {
+            },
+        };
+    }
+    if (!buildOutcome.workflowId) {
+        return {
+            result: {
                 success: false,
                 error: `Build outcome ${input.workItemId} does not include a workflow ID.`,
-            };
-        }
-        if (buildOutcome.workflowId !== input.workflowId) {
-            return {
+            },
+        };
+    }
+    if (buildOutcome.workflowId !== input.workflowId) {
+        return {
+            result: {
                 success: false,
                 error: `Build outcome ${input.workItemId} belongs to workflow ${buildOutcome.workflowId}, ` +
                     `but verification was requested for workflow ${input.workflowId}.`,
-            };
+            },
+        };
+    }
+    return {
+        buildOutcome,
+        workflowId: buildOutcome.workflowId,
+        stateBefore,
+        workflowTaskService: context.workflowTaskService,
+        domainContext: context.domainContext,
+    };
+}
+async function handleMissingSimulationPlan(input, context, workflowTaskService, workflowId) {
+    const guidance = 'Verification was not run because the build outcome has no simulation plan. ' +
+        'Rebuild or resubmit the workflow so destructive nodes can be classified before verification.';
+    const remediation = (0, remediation_1.createRemediation)({
+        category: 'blocked',
+        shouldEdit: false,
+        reason: 'missing_simulation_plan',
+        guidance,
+    });
+    context.logger.warn('verify-built-workflow: build outcome has no simulation plan — refusing to run without simulation safeguards', { workItemId: input.workItemId, workflowId });
+    try {
+        await workflowTaskService.updateBuildOutcome(input.workItemId, {
+            remediation,
+            verification: {
+                attempted: true,
+                success: false,
+                status: 'unknown',
+                failureSignature: 'missing_simulation_plan',
+                evidence: { errorMessage: guidance },
+                verifiedAt: new Date().toISOString(),
+            },
+        });
+    }
+    catch {
+    }
+    try {
+        await workflowTaskService.reportVerificationVerdict({
+            workItemId: input.workItemId,
+            runId: context.runId,
+            workflowId,
+            verdict: 'failed_terminal',
+            failureSignature: 'missing_simulation_plan',
+            diagnosis: guidance,
+            remediation,
+            summary: guidance,
+        });
+    }
+    catch (error) {
+        context.logger.warn('verify-built-workflow: failed to persist terminal verdict', {
+            workItemId: input.workItemId,
+            workflowId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return { success: false, status: 'unknown', error: guidance, remediation, guidance };
+}
+async function persistVerificationRecord(input, workflowTaskService, args) {
+    const { success, result, reachedNames, nodesNotReached } = args;
+    try {
+        const executedForEvidence = namesOrDataKeys(reachedNames, result.data);
+        await workflowTaskService.updateBuildOutcome(input.workItemId, {
+            verification: {
+                attempted: true,
+                success,
+                executionId: result.executionId || undefined,
+                status: result.status,
+                failureSignature: success ? undefined : result.error,
+                evidence: {
+                    nodesExecuted: executedForEvidence && executedForEvidence.length > 0 ? executedForEvidence : undefined,
+                    nodesNotReached: nodesNotReached.length > 0 ? nodesNotReached : undefined,
+                    producedOutputRows: countProducedOutputRows(result.data),
+                    errorMessage: success ? undefined : result.error,
+                },
+                verifiedAt: new Date().toISOString(),
+            },
+        });
+    }
+    catch {
+    }
+}
+async function reportTerminalRemediation(input, context, workflowTaskService, args) {
+    const { remediation, workflowId, executionId } = args;
+    try {
+        await workflowTaskService.reportVerificationVerdict({
+            workItemId: input.workItemId,
+            runId: context.runId,
+            workflowId,
+            executionId,
+            verdict: remediation.category === 'needs_setup' ? 'needs_user_input' : 'failed_terminal',
+            failureSignature: remediation.reason,
+            diagnosis: remediation.guidance,
+            remediation,
+            summary: remediation.guidance,
+        });
+    }
+    catch (error) {
+        context.logger.warn('verify-built-workflow: failed to persist terminal verdict', {
+            workItemId: input.workItemId,
+            workflowId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    try {
+        context.trackTelemetry?.('Builder remediation guard fired', {
+            thread_id: context.threadId,
+            run_id: context.runId,
+            work_item_id: input.workItemId,
+            workflow_id: workflowId,
+            category: remediation.category,
+            attempt_count: remediation.attemptCount,
+            reason: remediation.reason,
+        });
+    }
+    catch (error) {
+        context.logger.warn('verify-built-workflow: failed to emit remediation telemetry', {
+            workItemId: input.workItemId,
+            workflowId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function buildSimulationNote(reachedSimulatedNodes, planMissing) {
+    if (reachedSimulatedNodes.length > 0) {
+        return (`Simulated ${reachedSimulatedNodes.length} node(s) during verification — no real external writes happened: ` +
+            reachedSimulatedNodes.map((n) => `${n.nodeName} (${n.reason})`).join('; ') +
+            '. Relay this to the user when presenting the result.');
+    }
+    if (planMissing) {
+        return ('No simulation plan was available for this verification run — nodes were NOT ' +
+            'simulated and may have performed real external writes (sent messages, created or ' +
+            'modified records). Relay this to the user when presenting the result.');
+    }
+    return undefined;
+}
+function buildCoverageNote(nodesNotReached, result, success) {
+    if (nodesNotReached.length === 0)
+        return undefined;
+    const ending = result.lastNodeExecuted
+        ? `. Execution ended at "${result.lastNodeExecuted}"${success ? ' because it produced no output items (empty item lists stop downstream nodes)' : ''}.`
+        : '.';
+    const guidance = success
+        ? ' This usually means a lookup or query returned nothing. Seed matching test data and re-run verification, or tell the user the unreached part needs a manual test. Do NOT report the workflow as fully verified.'
+        : '';
+    return (`Partial coverage: ${nodesNotReached.length} node(s) were never reached and remain UNVERIFIED: ` +
+        nodesNotReached.join(', ') +
+        ending +
+        guidance);
+}
+function createVerifyBuiltWorkflowTool(context) {
+    return new agents_1.Tool('verify-built-workflow')
+        .description('Run a built workflow using sidecar verification context from the build outcome. ' +
+        'Call when the current turn is responsible for post-build verification. ' +
+        'Use this as the standard verifier for workflows produced by the workflow-builder. ' +
+        'It supports manual, schedule, form, webhook, chat, and other event triggers with build-outcome pin data, mocked credential context, or trigger-shaped inputData. ' +
+        'Use `executions(action="run")` only for ad hoc runs outside build verification. ' +
+        'CRITICAL: `inputData` shape depends on the trigger type — see the per-trigger guidance on the inputData field. ' +
+        'Passing the wrong shape (e.g. wrapping form fields under `formFields`) produces null downstream values that ' +
+        'look like an expression bug but are not — do not patch the workflow, re-run verify with the correct shape.')
+        .input(exports.verifyBuiltWorkflowInputSchema)
+        .output(verifyBuiltWorkflowOutputSchema)
+        .handler(async (input) => {
+        const preconditions = await resolveVerifyPreconditions(input, context);
+        if ('result' in preconditions)
+            return preconditions.result;
+        const { buildOutcome, workflowId, stateBefore, workflowTaskService, domainContext } = preconditions;
+        const planMissing = buildOutcome.nodeSimulationPlan === undefined;
+        if (planMissing) {
+            return await handleMissingSimulationPlan(input, context, workflowTaskService, workflowId);
         }
-        const workflowId = buildOutcome.workflowId;
-        const writeNodes = await extractDataTableWriteNodes(context.domainContext.workflowService, workflowId);
-        const preSnapshots = await snapshotRowIdsPerTable(context.domainContext.dataTableService, new Set(writeNodes.map((n) => n.dataTableId)), context.logger);
-        const result = await context.domainContext.executionService.run(workflowId, input.inputData, {
+        const { pinData: verificationPinData, simulatedNodes } = buildVerificationPinData(buildOutcome);
+        const simulationMap = simulatedNodes.length > 0
+            ? Object.fromEntries(simulatedNodes.map((n) => [n.nodeName, { reason: n.reason }]))
+            : undefined;
+        const result = await domainContext.executionService.run(workflowId, input.inputData, {
             timeout: input.timeout,
-            pinData: buildOutcome.verificationPinData,
+            pinData: verificationPinData,
+            simulation: simulationMap,
         });
+        const reachedNames = new Set(result.executedNodeNames ?? (result.data ? Object.keys(result.data) : []));
+        const reachedSimulatedNodes = simulatedNodes.filter((n) => reachedNames.has(n.nodeName));
+        const nodesNotReached = (buildOutcome.nodeSimulationPlan ?? [])
+            .map((verdict) => verdict.nodeName)
+            .filter((name) => !reachedNames.has(name));
+        const hasSimulationPlan = (buildOutcome.nodeSimulationPlan?.length ?? 0) > 0;
         const hasOutput = result.data ? Object.keys(result.data).length > 0 : false;
-        const success = result.status === 'success' || (result.status === 'waiting' && !result.error && hasOutput);
+        const success = result.status === 'success' ||
+            (!hasSimulationPlan && result.status === 'waiting' && !result.error && hasOutput);
         const failureRemediation = success
             ? undefined
             : classifyVerificationFailure(result.error, result.status, buildOutcome);
@@ -441,82 +501,35 @@ function createVerifyBuiltWorkflowTool(context) {
             ? (0, remediation_1.terminalRemediationFromState)(stateBefore, context.runId)
             : undefined;
         const remediation = budgetRemediation ?? failureRemediation;
-        const cleanedRows = await cleanupInsertedRowsByNodeOutput(context.domainContext.dataTableService, writeNodes, result.data, preSnapshots, context.logger);
-        try {
-            const nodesExecuted = result.data ? Object.keys(result.data) : undefined;
-            await context.workflowTaskService.updateBuildOutcome(input.workItemId, {
-                verification: {
-                    attempted: true,
-                    success,
-                    executionId: result.executionId || undefined,
-                    status: result.status,
-                    failureSignature: success ? undefined : result.error,
-                    evidence: {
-                        nodesExecuted: nodesExecuted && nodesExecuted.length > 0 ? nodesExecuted : undefined,
-                        producedOutputRows: countProducedOutputRows(result.data),
-                        errorMessage: success ? undefined : result.error,
-                    },
-                    verifiedAt: new Date().toISOString(),
-                },
-            });
-        }
-        catch {
-        }
-        if (cleanedRows > 0) {
-            context.logger.debug?.('verify-built-workflow: cleaned up inserted rows', {
-                workItemId: input.workItemId,
+        await persistVerificationRecord(input, workflowTaskService, {
+            success,
+            result,
+            reachedNames,
+            nodesNotReached,
+        });
+        if (remediation && !remediation.shouldEdit) {
+            await reportTerminalRemediation(input, context, workflowTaskService, {
+                remediation,
                 workflowId,
-                cleanedRows,
+                executionId: result.executionId || undefined,
             });
         }
-        if (remediation && !remediation.shouldEdit) {
-            try {
-                await context.workflowTaskService.reportVerificationVerdict({
-                    workItemId: input.workItemId,
-                    runId: context.runId,
-                    workflowId,
-                    executionId: result.executionId || undefined,
-                    verdict: remediation.category === 'needs_setup' ? 'needs_user_input' : 'failed_terminal',
-                    failureSignature: remediation.reason,
-                    diagnosis: remediation.guidance,
-                    remediation,
-                    summary: remediation.guidance,
-                });
-            }
-            catch (error) {
-                context.logger.warn('verify-built-workflow: failed to persist terminal verdict', {
-                    workItemId: input.workItemId,
-                    workflowId,
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-            try {
-                context.trackTelemetry?.('Builder remediation guard fired', {
-                    thread_id: context.threadId,
-                    run_id: context.runId,
-                    work_item_id: input.workItemId,
-                    workflow_id: workflowId,
-                    category: remediation.category,
-                    attempt_count: remediation.attemptCount,
-                    reason: remediation.reason,
-                });
-            }
-            catch (error) {
-                context.logger.warn('verify-built-workflow: failed to emit remediation telemetry', {
-                    workItemId: input.workItemId,
-                    workflowId,
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        }
         const maxDataChars = input.maxDataChars ?? DEFAULT_NODE_PREVIEW_CHARS;
-        const nodesExecuted = result.data ? Object.keys(result.data) : undefined;
+        const nodesExecuted = namesOrDataKeys(reachedNames, result.data);
+        const simulatedNames = new Set(reachedSimulatedNodes.map((n) => n.nodeName));
+        const simulationNote = buildSimulationNote(reachedSimulatedNodes, planMissing);
+        const coverageNote = buildCoverageNote(nodesNotReached, result, success);
         return {
             executionId: result.executionId || undefined,
             success,
             status: result.status,
             nodesExecuted,
-            nodePreviews: buildNodePreviews(result.data, maxDataChars),
+            lastNodeExecuted: result.lastNodeExecuted,
+            nodePreviews: buildNodePreviews(result.data, maxDataChars, simulatedNames),
+            simulatedNodes: reachedSimulatedNodes.length > 0 ? reachedSimulatedNodes : undefined,
+            simulationNote,
+            nodesNotReached: nodesNotReached.length > 0 ? nodesNotReached : undefined,
+            coverageNote,
             ...(input.includeData ? { data: result.data } : {}),
             error: result.error,
             remediation,