@superblocksteam/vite-plugin-file-sync 2.0.119 → 2.0.120-next.1

package/dist/migration/migration-verification.js

@@ -0,0 +1,1006 @@
+import crypto from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import yaml from "yaml";
+import z from "zod";
+import { AiEntityType, AiPermissionType, } from "@superblocksteam/library-shared/types";
+import { LanguagePluginID } from "@superblocksteam/shared";
+import { extractIntegrationIdsFromSource, extractMutations, } from "../ai-service/agent/tools/apis/analysis.js";
+import { compareApiResults, } from "../ai-service/agent/tools/apis/api-comparator.js";
+import { ApiExecutor, } from "../ai-service/agent/tools/apis/api-executor.js";
+import { createToolFactory, PermissionLevel, ToolCategory, } from "../ai-service/agent/tools2/types.js";
+import { updateChecklistItem } from "../ai-service/checklist/persisted-checklist-store.js";
+import { sanitizeLogMessage } from "../util/log-sanitizer.js";
+import { getLogger } from "../util/logger.js";
+import { OperationQueue } from "../util/operation-queue.js";
+import { classifyYamlStepMutation } from "./migration-classifier.js";
+import { forEachYamlStep } from "./yaml-walk.js";
+const SCRATCH_DIR = "scratch";
+const VERIFICATION_DIR = "migration-verification";
+const V2_BACKUP_DIR = "v2-backup";
+const DIFF_SIZE_CAP = 1024 * 1024; // 1 MB
+const PIPELINE_TIMEOUT_MS = 30_000;
+/**
+ * Hard cap on verification attempts per API per migration. The agent does NOT
+ * decide when to stop iterating — this counter is computed from on-disk
+ * history and enforced inside `runMigrationVerification`. An LLM agent asked
+ * to self-assess "am I converging?" reliably picks the socially acceptable
+ * answer ("yes"); the cap removes that judgment from the loop.
+ */
+export const MAX_VERIFICATION_ATTEMPTS = 10;
+const LANGUAGE_PLUGIN_IDS = new Set(Object.values(LanguagePluginID));
+/**
+ * Verify a single API by running both the v2 YAML and v3 TS versions with the
+ * supplied inputs and comparing their outputs.
+ *
+ * Wraps `computeVerificationOutcome` with on-disk history bookkeeping:
+ * - Reads `scratch/migration-verification/<apiName>.history.json` and refuses
+ *   to run beyond `MAX_VERIFICATION_ATTEMPTS`, returning `kind: "exhausted"`.
+ * - For `diverged` outcomes, computes `progress` (`first_attempt` |
+ *   `converging` | `stalled`) by hashing (path, kind) tuples and comparing to
+ *   the prior diverged attempt's hash.
+ * - Appends a history entry on every run so the next call has accurate state.
+ *
+ * History persistence is best-effort: bookkeeping I/O failures are logged but
+ * do not surface as verification errors.
+ */
+export async function runMigrationVerification(params) {
+    // Serialize the entire read-cap-check + pipeline + append for a given API
+    // through the per-API queue. Two concurrent calls for the same API used to
+    // both observe `attempts.length = MAX-1`, both pass the cap check, and
+    // both run the pipeline + append — silently exceeding the documented hard
+    // cap by N. Wrapping end-to-end (rather than serializing only the append)
+    // costs us same-API parallelism — but parallel verifications for the same
+    // API are wasteful work anyway (the second result clobbers the first or
+    // hits the cap), so the cost is purely on a degenerate path. Different
+    // APIs use different queues and remain fully parallel.
+    return getVerificationHistoryQueue(params.appRootDir, params.apiName).enqueue(async () => {
+        const history = await readHistory(params.appRootDir, params.apiName);
+        if (history.attempts.length >= MAX_VERIFICATION_ATTEMPTS) {
+            return {
+                kind: "exhausted",
+                attempts: history.attempts.length,
+                lastDivergence: await readLastDivergedDiff(params.appRootDir, params.apiName),
+            };
+        }
+        const raw = await computeVerificationOutcome(params);
+        let outcome;
+        let divergenceHashForHistory;
+        if (raw.kind === "diverged") {
+            const currentHash = divergenceShapeHash(raw.diff.summaryForAgent);
+            divergenceHashForHistory = currentHash;
+            const lastDivergedHash = findLastDivergedShapeHash(history);
+            const progress = lastDivergedHash === undefined
+                ? "first_attempt"
+                : lastDivergedHash === currentHash
+                    ? "stalled"
+                    : "converging";
+            outcome = {
+                kind: "diverged",
+                diff: raw.diff,
+                attempt: history.attempts.length + 1,
+                progress,
+            };
+        }
+        else {
+            outcome = raw;
+        }
+        // Single decision-point log so an operator chasing "Clark says diverged
+        // but I see passed" has a stdout breadcrumb to correlate. Logged here at
+        // the single return path of `runMigrationVerification` rather than in
+        // each tool-side branch — wraps every outcome (passed, diverged,
+        // both_failed, exhausted, skipped_mutation, v2_unrunnable, error) with a
+        // consistent shape. Apply name only; raw failure strings stay scrubbed.
+        getLogger().info(`[migration-verify] outcome`, {
+            apiName: params.apiName,
+            attempt: history.attempts.length + 1,
+            maxAttempts: MAX_VERIFICATION_ATTEMPTS,
+            kind: outcome.kind,
+            progress: outcome.kind === "diverged" ? outcome.progress : undefined,
+            divergenceCount: outcome.kind === "diverged"
+                ? outcome.diff.summaryForAgent.length
+                : undefined,
+        });
+        // Direct (non-enqueued) write — we already hold this API's queue, so
+        // re-entering it would deadlock.
+        await writeHistoryEntry(params.appRootDir, params.apiName, {
+            ts: new Date().toISOString(),
+            kind: outcome.kind,
+            divergenceShapeHash: divergenceHashForHistory,
+            divergenceCount: outcome.kind === "diverged"
+                ? outcome.diff.summaryForAgent.length
+                : undefined,
+        });
+        return outcome;
+    });
+}
+async function computeVerificationOutcome({ apiName, appRootDir, inputs, runV2Pipeline, runV3Sdk, allowAskPolicy, }) {
+    const verificationInputs = inputs ?? {};
+    // 1. Detect mutations in the v3 TS source before running anything.
+    const apiTsPath = join(appRootDir, "server", "apis", apiName, "api.ts");
+    let source;
+    try {
+        source = await readFile(apiTsPath, "utf-8");
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            reason: `Cannot read v3 source at ${apiTsPath}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // Extract integration IDs up-front so they can be passed to runV3Sdk for
+    // the auth preflight (matching test-api.ts). Falls back to undefined on AST
+    // parse failure — runV3Sdk will then rely on the Redux store as before.
+    let integrationIds;
+    try {
+        const ids = extractIntegrationIdsFromSource(source);
+        if (ids.length > 0)
+            integrationIds = ids;
+    }
+    catch {
+        // AST parse failure: leave undefined.
+    }
+    let mutations;
+    try {
+        mutations = extractMutations(source);
+    }
+    catch (error) {
+        // AST parse failure: we cannot prove the source is mutation-free, so fall
+        // back to the same policy gate as if mutations were detected. The user
+        // can still get the API verified by allow-and-retry or manually verified.
+        return {
+            kind: "skipped_mutation",
+            mutationDetails: [
+                `unable to analyze source for mutations: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+            skipPolicy: "ask",
+        };
+    }
+    const v2BackupPath = join(appRootDir, SCRATCH_DIR, V2_BACKUP_DIR, "apis", apiName, "api.yaml");
+    // Also check the v2 backup for writes — a half-migrated API where v3 looks
+    // read-only but the original v2 still mutates would otherwise bypass the
+    // policy gate and run the v2 pipeline against real integrations.
+    const v2Analysis = await analyzeV2BackupMutations(v2BackupPath);
+    const mutationDetails = [
+        ...mutations.map((m) => `v3 ${m.type} "${m.name}": ${m.details}`),
+        ...v2Analysis.mutationDetails,
+    ];
+    if (mutationDetails.length > 0) {
+        const { effective } = await getEffectiveMigrationWritePolicy({
+            appRootDir,
+            apiName,
+            integrationIds,
+        });
+        if (effective === "deny" || (effective === "ask" && !allowAskPolicy)) {
+            return {
+                kind: "skipped_mutation",
+                mutationDetails,
+                skipPolicy: effective,
+            };
+        }
+        // effective === "allow": fall through to run both pipelines
+    }
+    // 2. Run v2 YAML pipeline.
+    let v2Result;
+    try {
+        const pipelineResult = await withTimeout(runV2Pipeline(v2BackupPath, verificationInputs), PIPELINE_TIMEOUT_MS, "v2 pipeline");
+        if (!pipelineResult.executionResult) {
+            return {
+                kind: "v2_unrunnable",
+                reason: "v2 pipeline returned no execution result",
+            };
+        }
+        v2Result = pipelineResult.executionResult;
+    }
+    catch (error) {
+        return {
+            kind: "v2_unrunnable",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // 3. Run v3 SDK.
+    let v3Result;
+    try {
+        v3Result = await withTimeout(runV3Sdk(integrationIds, verificationInputs), PIPELINE_TIMEOUT_MS, "v3 SDK");
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // 3.5. If both executions returned failure, surface that explicitly rather
+    //      than letting compareApiResults produce a vacuous "diff.empty" pass.
+    if (!v2Result.success && !v3Result.success) {
+        return {
+            kind: "both_failed",
+            v2Error: extractFailureMessage(v2Result, "v2"),
+            v3Error: extractFailureMessage(v3Result, "v3"),
+        };
+    }
+    // 3.6. One-sided failure: if one side succeeded and the other failed, that is
+    //      a divergence regardless of what the output diff says.  Without this
+    //      guard, a v3 that returns `success: false` with empty `outputs` would
+    //      compare equal to a v2 with empty `outputs`, producing a false "passed".
+    if (v2Result.success !== v3Result.success) {
+        const failedSide = v2Result.success ? "v3" : "v2";
+        const failureMessage = extractFailureMessage(v2Result.success ? v3Result : v2Result, failedSide);
+        // Server-side log so divergence shows up in the dev-server log stream
+        // (and DataDog when the EE forwards stdout). The actual failure text is
+        // intentionally NOT logged here — extractFailureMessage may include
+        // upstream response bodies, query strings, or credentials echoed back by
+        // the integration. The agent already gets failureMessage via
+        // summaryForAgent, and the user sees full detail in the verification UI.
+        // What we want from the server log is a "this happened" marker:
+        // apiName, which side failed, and the error type/source classification.
+        // Logger.warn accepts free-form key/value pairs; .error has a stricter
+        // ErrorMeta shape that doesn't fit this diagnostic record.
+        getLogger().warn(`Migration verification diverged for ${apiName}`, {
+            apiName,
+            failedSide,
+            v2: {
+                success: v2Result.success,
+                hasSystemError: Boolean(v2Result.systemError),
+                firstErrorType: v2Result.errors?.[0]?.type,
+            },
+            v3: { success: v3Result.success },
+        });
+        // The agent-facing `failureMessage` is scrubbed via `redactForAgent`
+        // because it ends up in LLM context (and from there into chat
+        // transcripts persisted by the client). The UI-facing `valuesForUi.reason`
+        // intentionally keeps the raw text — that channel renders to the
+        // user's own browser, not into the model context.
+        return {
+            kind: "diverged",
+            diff: {
+                empty: false,
+                summaryForAgent: [
+                    {
+                        path: "success",
+                        kind: "value_mismatch",
+                        expectedHash: String(v2Result.success),
+                        actualHash: String(v3Result.success),
+                        failureMessage: redactForAgent(failureMessage),
+                    },
+                ],
+                valuesForUi: [
+                    {
+                        path: "success",
+                        expected: v2Result.success,
+                        actual: v3Result.success,
+                        reason: `${failedSide} execution failed while the other succeeded: ${failureMessage}`,
+                    },
+                ],
+            },
+        };
+    }
+    // 4. Compare.
+    const diff = compareApiResults(v2Result, v3Result);
+    if (diff.empty) {
+        return { kind: "passed" };
+    }
+    // 5. Persist the diff to disk for the UI to render (valuesForUi only).
+    const verificationDir = join(appRootDir, SCRATCH_DIR, VERIFICATION_DIR);
+    await mkdir(verificationDir, { recursive: true });
+    const diffPath = join(verificationDir, `${apiName}.diff.json`);
+    const diffJson = JSON.stringify({ valuesForUi: diff.valuesForUi }, null, 2);
+    const payload = diffJson.length > DIFF_SIZE_CAP
+        ? JSON.stringify({ valuesForUi: diff.valuesForUi.slice(0, 50), truncated: true }, null, 2)
+        : diffJson;
+    await writeFile(diffPath, payload, "utf-8");
+    return { kind: "diverged", diff };
+}
+/** Relative path (from appRootDir) for a diff JSON file. */
+export function diffRelativePath(apiName) {
+    return `${SCRATCH_DIR}/${VERIFICATION_DIR}/${apiName}.diff.json`;
+}
+export const migrationVerificationToolFactory = createToolFactory("runMigrationVerification", ({ clark, services, }) => ({
+    category: ToolCategory.DEBUG,
+    getRequiredPermissions: async (input) => {
+        const apiName = input?.apiName;
+        if (!apiName)
+            return [];
+        let source;
+        try {
+            source = await services.appShell.readFile(`server/apis/${apiName}/api.ts`);
+        }
+        catch {
+            return [];
+        }
+        let mutations;
+        try {
+            mutations = extractMutations(source);
+        }
+        catch {
+            return [];
+        }
+        if (mutations.length === 0)
+            return [];
+        let integrationIds;
+        try {
+            const ids = extractIntegrationIdsFromSource(source);
+            if (ids.length > 0)
+                integrationIds = ids;
+        }
+        catch {
+            integrationIds = undefined;
+        }
+        const { effective, sourceIds } = await getEffectiveMigrationWritePolicy({
+            appRootDir: services.appRootDirPath,
+            apiName,
+            integrationIds,
+        });
+        if (effective === "allow" || sourceIds.length === 0) {
+            return [];
+        }
+        return sourceIds.map((entityId) => ({
+            entityType: AiEntityType.INTEGRATION,
+            entityId,
+            permissionType: AiPermissionType.WRITE,
+        }));
+    },
+    getActionName: (input) => {
+        const name = input?.apiName ?? "API";
+        return {
+            future: `verify ${name}`,
+            present: `verifying ${name}`,
+            past: `verified ${name}`,
+        };
+    },
+    description: "Verify a migrated API by running both the v2 YAML and v3 TS versions " +
+        "and comparing their outputs. Pass `inputs` to inject test parameters " +
+        "for any bindings the API references (the same way `testApi` does — " +
+        "`Input1.value`, `Table1.selectedRow`, etc.); both v2 and v3 receive " +
+        "the same inputs so the comparison is apples-to-apples. Omit `inputs` " +
+        "(or pass `{}`) only when the API takes no inputs. Each pipeline has a " +
+        `${PIPELINE_TIMEOUT_MS / 1000}s reporting timeout (reject-only — the ` +
+        "underlying execution can't be cancelled, so allow-policy mutations " +
+        "may continue server-side after this returns). Returns a structured outcome: " +
+        "'passed', 'diverged' (with summaryForAgent), 'both_failed' (both " +
+        "executions errored — cannot determine correctness), " +
+        "'skipped_mutation', 'v2_unrunnable', or 'error'. On 'diverged' use " +
+        "`summaryForAgent` to revise `server/apis/<apiName>/api.ts` and re-run " +
+        "the tool — the attempt counter is tracked server-side from on-disk " +
+        "history; the response always includes the current `attempt` and " +
+        "`maxAttempts` so the agent doesn't have to thread it.",
+    inputSchema: z.object({
+        apiName: z
+            .string()
+            .describe("The API name to verify (must match the directory under " +
+            "server/apis/, may contain only letters, digits, hyphens, or " +
+            "underscores). Bare .string() — `.regex()` emits a JSON Schema " +
+            "`pattern` keyword that Snowflake Cortex rejects; the format is " +
+            "validated below at runtime.")
+            .refine((v) => /^[a-zA-Z0-9_-]+$/.test(v), {
+            message: "apiName must contain only letters, digits, hyphens, or underscores",
+        }),
+        inputs: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Test input values for the API's bindings, applied to BOTH the " +
+            "v2 YAML and v3 TS executions so the diff is meaningful. Use the " +
+            "same approach as `testApi`: a key per binding the API references " +
+            "(component values like `Input1.value`, table selections like " +
+            "`Table1.selectedRow`, state variables, workflow params, etc.) " +
+            "with realistic mock values that match the binding's expected " +
+            "type. Omit (defaults to `{}`) only when the API takes no inputs " +
+            "— passing `{}` for an API that needs inputs typically produces " +
+            "a vacuous 'both_failed' result."),
+        // `attemptCount` was previously declared here for the agent to thread
+        // through retries, but `execute` never read it — the real attempt
+        // count is computed from on-disk history inside
+        // `runMigrationVerification` so an agent that lies about its attempt
+        // index can't bypass `MAX_VERIFICATION_ATTEMPTS`. The field is dropped
+        // to match what the tool actually uses; Zod's default object policy
+        // strips unknown keys so any agent still passing it in-flight is a
+        // no-op rather than an error.
+    }),
+    async execute({ apiName, inputs }) {
+        const appRootDir = services.appRootDirPath;
+        const outcome = await runMigrationVerification({
+            apiName,
+            appRootDir,
+            inputs,
+            allowAskPolicy: true,
+            runV2Pipeline: async (sourcePath, pipelineInputs) => {
+                // runApiValidationPipeline's sourcePath only controls metadata
+                // loading (validateMetadata: false here), not execution — it always
+                // calls aiExecuteV2Api({ type: "fetch", apiName }) which resolves the
+                // API by name in the editor. After migration that name points to the
+                // v3 TS version, so the v2 backup YAML was never actually run.
+                // Load the backup YAML directly and execute inline instead.
+                const yamlContent = await readFile(sourcePath, "utf-8");
+                const apiDefinition = yaml.parse(yamlContent);
+                const editorClient = clark.context.peer;
+                if (!editorClient)
+                    throw new Error("No editor client available");
+                const executor = new ApiExecutor(editorClient, services.integrationStore);
+                const executionResult = await executor.execute({ type: "inline", definition: apiDefinition }, pipelineInputs, { includeStepOutputs: false });
+                return { success: executionResult.success, executionResult };
+            },
+            runV3Sdk: async (integrationIds, sdkInputs) => {
+                const editorClient = clark.context.peer;
+                if (!editorClient)
+                    throw new Error("No editor client available");
+                const sdkResult = await editorClient.call.aiExecuteSdkApi({
+                    apiName,
+                    input: sdkInputs,
+                    entryPoint: `server/apis/${apiName}/api.ts`,
+                    integrationIds,
+                });
+                // SdkApiExecutionResult uses `output` (singular) while
+                // ApiExecutionResult uses `outputs` (plural) — normalize here.
+                // Also forward the SDK error so divergence diagnostics can show the
+                // real reason instead of a bare success: false.
+                const errors = sdkResult.error
+                    ? [
+                        {
+                            type: "execution",
+                            message: sdkResult.error.message,
+                        },
+                    ]
+                    : undefined;
+                return {
+                    success: sdkResult.success,
+                    outputs: sdkResult.output,
+                    errors,
+                };
+            },
+        });
+        // Update checklist with verification metadata. Each branch explicitly
+        // clears fields from the previous run that no longer apply (null = clear).
+        if (outcome.kind === "passed") {
+            await updateChecklistItem({
+                appRootDirPath: appRootDir,
+                itemId: `api_${apiName}`,
+                verificationOutcome: "auto_passed",
+                verificationSkippedReason: null,
+                lastVerificationAt: new Date().toISOString(),
+            });
+        }
+        else if (outcome.kind === "skipped_mutation") {
+            await updateChecklistItem({
+                appRootDirPath: appRootDir,
+                itemId: `api_${apiName}`,
+                verificationSkippedReason: outcome.skipPolicy === "ask" ? "mutation_ask" : "mutation",
+                verificationOutcome: null,
+                lastVerificationAt: new Date().toISOString(),
+            });
+        }
+        else if (outcome.kind === "v2_unrunnable") {
+            await updateChecklistItem({
+                appRootDirPath: appRootDir,
+                itemId: `api_${apiName}`,
+                verificationSkippedReason: "v2_unrunnable",
+                verificationOutcome: null,
+                lastVerificationAt: new Date().toISOString(),
+            });
+        }
+        else if (outcome.kind === "both_failed") {
+            // Both v2 and v3 errored — most often because the API reads bindings
+            // we didn't supply. Per the migration skill, the agent should
+            // synthesize realistic inputs and retry rather than treat this as a
+            // terminal outcome, so we deliberately do NOT mark `status: completed`
+            // here (a previous version did, which contradicted the skill and left
+            // the item stuck `completed` even after the agent kept iterating).
+            // We still record `verificationSkippedReason: "both_failed"` so the
+            // UI can surface the transient state; subsequent diverged/passed
+            // attempts clear it via `verificationSkippedReason: null`.
+            await updateChecklistItem({
+                appRootDirPath: appRootDir,
+                itemId: `api_${apiName}`,
+                verificationSkippedReason: "both_failed",
+                verificationOutcome: null,
+                lastVerificationAt: new Date().toISOString(),
+            });
+        }
+        else if (outcome.kind === "diverged") {
+            await updateChecklistItem({
+                appRootDirPath: appRootDir,
+                itemId: `api_${apiName}`,
+                verificationOutcome: null,
+                verificationSkippedReason: null,
+                lastVerificationAt: new Date().toISOString(),
+                lastVerificationDiffPath: diffRelativePath(apiName),
+            });
+        }
+        else if (outcome.kind === "exhausted") {
+            // Hard cap reached. Mark the item failed so classifyItem routes it to
+            // the manual-verification lane and the user knows automatic
+            // reconciliation gave up. The agent must NOT keep calling
+            // runMigrationVerification for this API in this migration run; the
+            // tool will return `exhausted` again until the migration is reset.
+            await updateChecklistItem({
+                appRootDirPath: appRootDir,
+                itemId: `api_${apiName}`,
+                status: "failed",
+                failureReason: `verification_exhausted: hit MAX_VERIFICATION_ATTEMPTS (${MAX_VERIFICATION_ATTEMPTS}) without converging. See scratch/migration-verification/${apiName}.history.json for the per-attempt log.`,
+                verificationOutcome: null,
+                verificationSkippedReason: null,
+                lastVerificationAt: new Date().toISOString(),
+                ...(outcome.lastDivergence
+                    ? { lastVerificationDiffPath: diffRelativePath(apiName) }
+                    : {}),
+            });
+        }
+        else {
+            // outcome.kind === "error": clear stale fields so classifyItem doesn't
+            // misclassify this item as verified or skipped.
+            await updateChecklistItem({
+                appRootDirPath: appRootDir,
+                itemId: `api_${apiName}`,
+                verificationOutcome: null,
+                verificationSkippedReason: null,
+                lastVerificationAt: new Date().toISOString(),
+            });
+        }
+        if (outcome.kind === "diverged") {
+            return {
+                kind: "diverged",
+                summaryForAgent: outcome.diff.summaryForAgent,
+                diffPath: diffRelativePath(apiName),
+                attempt: outcome.attempt,
+                maxAttempts: MAX_VERIFICATION_ATTEMPTS,
+                progress: outcome.progress,
+                guidance: progressGuidance(outcome.progress, outcome.attempt),
+            };
+        }
+        if (outcome.kind === "exhausted") {
+            // Deliberately do NOT include the persisted diff payload (which holds
+            // raw response values) in the agent-facing tool result — those values
+            // belong to the user's data plane and stay scoped to local scratch
+            // and the UI render path. The checklist item already carries
+            // `lastVerificationDiffPath` for the UI to read directly from disk.
+            return {
+                kind: "exhausted",
+                attempts: outcome.attempts,
+                summary: `\`${apiName}\` hit the hard cap of ${MAX_VERIFICATION_ATTEMPTS} verification attempts without converging. ` +
+                    `The checklist item has been marked failed; do NOT call runMigrationVerification again for this API in this migration run. ` +
+                    `Continue to the next API.`,
+            };
+        }
+        if (outcome.kind === "skipped_mutation") {
+            return {
+                kind: "skipped_mutation",
+                mutationDetails: outcome.mutationDetails,
+                summary: `\`${apiName}\` makes writes — skipped automatic verification (policy: ${outcome.skipPolicy}). Mark as manually verified once you have confirmed the API behaves correctly.`,
+            };
+        }
+        if (outcome.kind === "passed") {
+            return {
+                kind: "passed",
+                summary: `\`${apiName}\` verified — v2 and v3 outputs matched exactly.`,
+            };
+        }
+        if (outcome.kind === "v2_unrunnable") {
+            return {
+                kind: "v2_unrunnable",
+                summary: `The original pre-migration version of \`${apiName}\` couldn't be run for comparison (${outcome.reason}), ` +
+                    `so automatic verification was skipped. The API has been marked complete — ` +
+                    `test it in the app to confirm it works as expected.`,
+            };
+        }
+        if (outcome.kind === "both_failed") {
+            // Scrub raw upstream error strings before surfacing them to the
+            // model — same threat model as the diverged branch's
+            // `redactForAgent(failureMessage)`. The persisted server log already
+            // omits the raw message; the agent-facing channel must too.
+            return {
+                kind: "both_failed",
+                summary: `Both the original and migrated versions of \`${apiName}\` returned errors ` +
+                    `(typically because the API reads bindings — Input1.value, Table1.selectedRow, ` +
+                    `workflow params, etc. — that the verification call did not supply). The item ` +
+                    `is NOT marked complete; per the migration skill, synthesize realistic mock ` +
+                    `inputs that satisfy the bindings the API references and call ` +
+                    `runMigrationVerification again. Only treat this as terminal if the failure is ` +
+                    `clearly environmental (auth/credentials/integration unavailable). ` +
+                    `Original error: ${redactForAgent(outcome.v2Error)}. ` +
+                    `Migrated error: ${redactForAgent(outcome.v3Error)}.`,
+            };
+        }
+        // outcome.kind === "error" — the only remaining case
+        return {
+            kind: "error",
+            reason: outcome.reason,
+        };
+    },
+}));
+/**
+ * Soft UX timeout for the verification pipeline.
+ *
+ * IMPORTANT: this is a *reporting* timeout, not an execution boundary. The
+ * underlying work — `aiExecuteV2Api` and `aiExecuteSdkApi` editor-client RPCs —
+ * has no cancellation channel (the socket `MethodSchema` is a plain
+ * `(params) => Promise<Response>`; there is no AbortSignal plumbed through
+ * the RPC, the browser-side handler, or the SDK runtime). When this rejects,
+ * the in-flight execution keeps running until the server completes or the
+ * socket disconnects.
+ *
+ * What this does protect: the verification UI doesn't stall indefinitely on a
+ * slow API; the agent gets a deterministic outcome to act on.
+ *
+ * What this does NOT protect: write-capable side effects already in flight.
+ * Mutation safety is provided by the `integrationWritePolicy` check that runs
+ * BEFORE this timeout race ever fires — `runMigrationVerification` inspects
+ * BOTH the v3 source (via `extractMutations`) and the v2 backup YAML (via
+ * `analyzeV2BackupMutations`); if either side has any write or unclassified
+ * step, the pipelines are skipped entirely unless the user has explicitly
+ * marked every involved integration as "allow". By the time this `withTimeout`
+ * runs, any side effects in flight have already been opted into. Verification
+ * is not a sandbox; it relies on the policy gate, not on cancellation.
+ *
+ * Adding real cancellation would require extending `MethodSchema` with abort
+ * signaling and propagating it through the editorClient RPC layer. Tracked
+ * separately; out of scope for this verification helper.
+ */
+function withTimeout(promise, ms, label) {
+    let timer;
+    return Promise.race([
+        promise.finally(() => clearTimeout(timer)),
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms / 1000}s`)), ms);
+        }),
+    ]);
+}
+/**
+ * Inspect a v2 backup YAML for mutating steps and the integrations they touch.
+ *
+ * Returns empty results when the backup is missing or unparseable — the
+ * verification flow handles that downstream as `v2_unrunnable`. The goal here
+ * is only to feed the policy gate so v2-only writes don't bypass it.
+ *
+ * Walks the whole tree via `forEachYamlStep` so writes nested inside
+ * control-flow blocks (`tryCatch`, `conditional`, `foreach`, `parallel`) are
+ * caught — a flat scan over `parsed.blocks` would let nested v2 writes bypass
+ * the policy gate, especially now that the language-plugin filter has removed
+ * the accidental safety net where javascript's missing policy used to block
+ * all verification.
+ *
+ * Treats `unknown` step classifications (dynamic SQL bodies, plugins we don't
+ * recognize) as mutations: better to ask the user than silently run a write.
+ */
+export async function analyzeV2BackupMutations(v2BackupPath) {
+    let raw;
+    try {
+        raw = await readFile(v2BackupPath, "utf-8");
+    }
+    catch {
+        return { mutationDetails: [], integrationIds: [] };
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        return { mutationDetails: [], integrationIds: [] };
+    }
+    const integrationIds = new Set();
+    const mutationDetails = [];
+    forEachYamlStep(parsed, (step) => {
+        const integrationId = step["integration"];
+        if (typeof integrationId === "string" && integrationId.length > 0) {
+            integrationIds.add(integrationId);
+        }
+        const classification = classifyYamlStepMutation(step);
+        if (classification === "write" || classification === "unknown") {
+            const stepName = typeof step["name"] === "string" ? step["name"] : "<unnamed>";
+            mutationDetails.push(`v2 step "${stepName}" classified as ${classification}`);
+        }
+    });
+    return {
+        mutationDetails,
+        integrationIds: Array.from(integrationIds),
+    };
+}
+async function readIntegrationWritePolicy(appRootDir) {
+    try {
+        const raw = await readFile(join(appRootDir, SCRATCH_DIR, "migration-state.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        const pol = parsed.integrationWritePolicy;
+        if (pol !== null && typeof pol === "object" && !Array.isArray(pol)) {
+            return pol;
+        }
+    }
+    catch {
+        // missing or unreadable — default to ask
+    }
+    return {};
+}
+function mostRestrictivePolicy(policies) {
+    if (policies.includes("deny"))
+        return "deny";
+    if (policies.includes("ask"))
+        return "ask";
+    return "allow";
+}
+async function getEffectiveMigrationWritePolicy({ appRootDir, apiName, integrationIds, }) {
+    const policy = await readIntegrationWritePolicy(appRootDir);
+    const v2BackupPath = join(appRootDir, SCRATCH_DIR, V2_BACKUP_DIR, "apis", apiName, "api.yaml");
+    // Use IDs from source — not Object.keys(policy) — so a UUID present in
+    // source but absent from the policy map gets a real "ask" vote rather
+    // than being ignored. Otherwise an "allow" on one integration would be
+    // taken as blanket allow for everything the API touches. Union v2 and v3
+    // integrations so the gate sees every integration the verification will
+    // touch, not just the ones still referenced by v3.
+    //
+    // Language-runtime "integrations" (`javascript`, `python`) are inline
+    // user code, not data integrations; the modal hides them and they have
+    // no real write-policy decision attached. Excluding them here keeps a
+    // mixed API (e.g. postgres + javascript) from being blocked just because
+    // javascript has no policy entry.
+    const v2Analysis = await analyzeV2BackupMutations(v2BackupPath);
+    const sourceIds = Array.from(new Set([...(integrationIds ?? []), ...v2Analysis.integrationIds])).filter((id) => !LANGUAGE_PLUGIN_IDS.has(id));
+    const effective = sourceIds.length > 0
+        ? mostRestrictivePolicy(sourceIds.map((id) => policy[id] ?? "ask"))
+        : "ask";
+    return { effective, sourceIds };
+}
+export const checkRunMigrationVerificationPermissions = async (services, input) => {
+    if (!input || !input.apiName)
+        return PermissionLevel.PROMPT;
+    const apiName = input.apiName;
+    let source;
+    try {
+        source = await services.appShell.readFile(`server/apis/${apiName}/api.ts`);
+    }
+    catch {
+        return PermissionLevel.PROMPT;
+    }
+    let mutations;
+    try {
+        mutations = extractMutations(source);
+    }
+    catch {
+        return PermissionLevel.PROMPT;
+    }
+    if (mutations.length === 0)
+        return PermissionLevel.ALLOW;
+    let integrationIds;
+    try {
+        const ids = extractIntegrationIdsFromSource(source);
+        if (ids.length > 0)
+            integrationIds = ids;
+    }
+    catch {
+        integrationIds = undefined;
+    }
+    const { effective } = await getEffectiveMigrationWritePolicy({
+        appRootDir: services.appRootDirPath,
+        apiName,
+        integrationIds,
+    });
+    if (effective === "allow")
+        return PermissionLevel.ALLOW;
+    if (effective === "deny")
+        return PermissionLevel.BLOCK;
+    return PermissionLevel.PROMPT;
+};
+/**
+ * Extract the most specific failure message from a Pick<ApiExecutionResult>.
+ * Tries errors[0].message first, then systemError, then a placeholder.
+ */
+function extractFailureMessage(result, side) {
+    return (result.errors?.[0]?.message ??
+        result.systemError ??
+        `${side} execution returned success: false with no error details`);
+}
+const REDACTED_AGENT_FAILURE_MAX_LEN = 512;
+/**
+ * Scrub raw upstream-error strings before they enter LLM context. Upstream
+ * integrations can echo back bearer tokens, JWTs, or `api_key=...` query
+ * strings in error messages — the existing `sanitizeLogMessage` helper in
+ * `util/log-sanitizer.ts` is the canonical scrubber for those patterns and
+ * is what the rest of the vite plugin already uses for log lines. We
+ * additionally cap the length so a single misbehaving upstream can't crowd
+ * out the rest of the LLM context window.
+ *
+ * Used on the agent-facing channels (`summaryForAgent.failureMessage` for
+ * diverged outcomes, the `summary` string for `both_failed`) — the
+ * comment at the `getLogger().warn` call site for "Migration verification
+ * diverged" already keeps the server log clean of these strings; this
+ * applies the same treatment to the durable LLM channel.
+ */
+function redactForAgent(msg, maxLen = REDACTED_AGENT_FAILURE_MAX_LEN) {
+    if (msg === undefined || msg === null)
+        return "";
+    const sanitized = sanitizeLogMessage(String(msg));
+    if (sanitized.length <= maxLen)
+        return sanitized;
+    return sanitized.slice(0, maxLen) + "… [truncated]";
+}
+/**
+ * Reject any `apiName` that could escape `scratch/migration-verification/`.
+ * Checklist items are persisted to disk and parsed back in without a strict
+ * shape guard, so a poisoned `apiName` containing path separators or `..`
+ * segments would let `historyPath`/`diffPath` (and therefore the `rm` calls
+ * in `clearVerificationHistory`) target arbitrary files.
+ *
+ * v2 → v3 migration API names are derived from server YAML/SDK identifiers
+ * which are restricted to `[A-Za-z0-9_-]`, so this check is conservative
+ * for legitimate inputs.
+ */
+function assertSafeApiName(apiName) {
+    if (!/^[A-Za-z0-9_-]+$/.test(apiName)) {
+        throw new Error(`Refusing to operate on verification artifacts for unsafe apiName: ${JSON.stringify(apiName)}`);
+    }
+}
+function historyPath(appRootDir, apiName) {
+    assertSafeApiName(apiName);
+    return join(appRootDir, SCRATCH_DIR, VERIFICATION_DIR, `${apiName}.history.json`);
+}
+function diffPath(appRootDir, apiName) {
+    assertSafeApiName(apiName);
+    return join(appRootDir, SCRATCH_DIR, VERIFICATION_DIR, `${apiName}.diff.json`);
+}
+/**
+ * Delete the per-API verification history (and stale diff snapshot) so the
+ * next `runMigrationVerification` call starts from a clean slate. Called by
+ * the "Fix with Clark" retry endpoints — without this, an item that hit the
+ * `MAX_VERIFICATION_ATTEMPTS` cap on the first run would immediately return
+ * `kind: "exhausted"` on retry, making the retry a no-op.
+ *
+ * Routed through the same per-API `verificationHistoryQueues` queue used by
+ * `runMigrationVerification`. Without this, a clear could race with an
+ * in-flight verification: the verification reads history, runs the pipeline,
+ * the clear `rm()`s the file, then the verification's append re-creates the
+ * file with a stale attempt count — defeating the clear and immediately
+ * returning `exhausted` on the user's next retry.
+ *
+ * Best-effort: missing files are not an error. The safety check on
+ * `apiName` (via `historyPath`/`diffPath`) runs *before* enqueueing so a
+ * poisoned name throws synchronously, never holding the queue.
+ */
+export async function clearVerificationHistory(appRootDir, apiName) {
+    const histPath = historyPath(appRootDir, apiName);
+    const dPath = diffPath(appRootDir, apiName);
+    await getVerificationHistoryQueue(appRootDir, apiName).enqueue(async () => {
+        await Promise.all([
+            rm(histPath, { force: true }),
+            rm(dPath, { force: true }),
+        ]);
+    });
+}
+/**
+ * Static guidance string keyed off the deterministic `progress` signal — the
+ * agent doesn't have to decide whether to keep iterating, the tool tells it.
+ */
+function progressGuidance(progress, attempt) {
+    if (progress === "first_attempt") {
+        return `First diverged attempt for this API. Use the summaryForAgent entries to revise server/apis/<apiName>/api.ts and call runMigrationVerification again.`;
+    }
+    if (progress === "converging") {
+        return `Converging — the set of diverging (path, kind) pairs changed since the last attempt (#${attempt - 1}). Your previous edit had structural effect. Keep iterating: pick the next summaryForAgent entry, fix it, re-run.`;
+    }
+    // stalled
+    return `STALLED — the set of diverging (path, kind) pairs is identical to attempt #${attempt - 1}. Your last edit had no structural effect on the divergence. Either you edited the wrong block, the edit was a no-op, or this divergence is structurally irreconcilable (v2 uses a YAML construct with no v3 equivalent; v2 reads runtime state v3 can't observe). On your next attempt: try a different fix, or — if you are confident the divergence cannot be reconciled — mark the item failed with failureReason starting with "verification_diverged_irreconcilable:" and continue. Do NOT submit the identical edit again.`;
+}
+function divergenceShapeHash(entries) {
+    // Sort tuples so the hash is order-independent — the comparator's emit
+    // order is structural-walk based, but small refactors to compareApiResults
+    // shouldn't accidentally invalidate the convergence signal.
+    const tuples = entries
+        .map((e) => `${e.path}::${e.kind}`)
+        .sort()
+        .join("\n");
+    return crypto.createHash("sha256").update(tuples).digest("hex").slice(0, 16);
+}
+function findLastDivergedShapeHash(history) {
+    for (let i = history.attempts.length - 1; i >= 0; i--) {
+        const entry = history.attempts[i];
+        if (entry && entry.kind === "diverged" && entry.divergenceShapeHash) {
+            return entry.divergenceShapeHash;
+        }
+    }
+    return undefined;
+}
+async function readHistory(appRootDir, apiName) {
+    let raw;
+    try {
+        raw = await readFile(historyPath(appRootDir, apiName), "utf-8");
+    }
+    catch {
+        // Missing — fresh API, no history yet. Distinct from "present but
+        // unparseable", which we want to surface as a warning so an operator
+        // chasing a stuck migration can tell amnesia apart from no-prior-run.
+        return { attempts: [] };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === "object" &&
+            "attempts" in parsed &&
+            Array.isArray(parsed.attempts)) {
+            return parsed;
+        }
+        getLogger().warn(`Verification history for ${apiName} parsed but had unexpected shape; treating as empty`, { apiName });
+    }
+    catch (error) {
+        getLogger().warn(`Verification history for ${apiName} was unreadable JSON (likely a partial-write crash); treating as empty`, {
+            apiName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return { attempts: [] };
+}
+/**
+ * Per-(appRootDir, apiName) serialization of the read-modify-write on the
+ * `<apiName>.history.json` file. Without this, two parallel
+ * `runMigrationVerification` calls for the same API can both observe
+ * `attempts.length = MAX-1`, both pass the cap check, and both write — the
+ * later clobbers the earlier and the cap is silently bypassed. We re-use the
+ * same `OperationQueue` primitive `migration-checklist.ts` uses for the
+ * shared checklist mutations.
+ */
+const verificationHistoryQueues = new Map();
+function getVerificationHistoryQueue(appRootDir, apiName) {
+    const key = `${appRootDir}\0${apiName}`;
+    let queue = verificationHistoryQueues.get(key);
+    if (!queue) {
+        queue = new OperationQueue();
+        verificationHistoryQueues.set(key, queue);
+    }
+    return queue;
+}
+/**
+ * Append a history entry without enqueueing — caller MUST already hold the
+ * per-API verification queue. Used from `runMigrationVerification`'s queued
+ * body, where re-entering the same queue would deadlock.
+ */
+async function writeHistoryEntry(appRootDir, apiName, entry) {
+    try {
+        const history = await readHistory(appRootDir, apiName);
+        history.attempts.push(entry);
+        const dir = join(appRootDir, SCRATCH_DIR, VERIFICATION_DIR);
+        await mkdir(dir, { recursive: true });
+        // Atomic write via tmp + rename: a crash mid-write would otherwise
+        // leave the file truncated, and `readHistory`'s catch would silently
+        // amnesia-reset the cap to zero. POSIX `rename` is atomic on the same
+        // filesystem, so a reader either sees the full prior file or the full
+        // new file — never a partial write.
+        const finalPath = historyPath(appRootDir, apiName);
+        const tmpPath = `${finalPath}.tmp`;
+        await writeFile(tmpPath, JSON.stringify(history, null, 2), "utf-8");
+        await rename(tmpPath, finalPath);
+    }
+    catch (error) {
+        // History persistence is best-effort: a write failure here should not
+        // surface as a verification error to the agent (the verification
+        // result itself is still valid). Worst case: the next attempt sees
+        // stale history and computes `progress: "first_attempt"`, which is a
+        // softer failure mode than throwing here.
+        getLogger().warn(`Failed to persist verification history for ${apiName}`, {
+            apiName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Read the on-disk diff JSON written by the most recent diverged run, if any.
+ * Used by the `exhausted` outcome to surface "what did we get stuck on" to
+ * the agent without re-running the pipeline.
+ */
+async function readLastDivergedDiff(appRootDir, apiName) {
+    try {
+        const raw = await readFile(diffPath(appRootDir, apiName), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === "object" &&
+            "valuesForUi" in parsed &&
+            Array.isArray(parsed.valuesForUi)) {
+            // We only persist `valuesForUi` (see writeFile call in
+            // computeVerificationOutcome), not summaryForAgent — synthesize a
+            // minimal ApiComparisonDiff so the exhausted outcome carries
+            // something the UI/agent can render.
+            return {
+                empty: false,
+                valuesForUi: parsed.valuesForUi,
+                summaryForAgent: [],
+            };
+        }
+    }
+    catch {
+        // No prior diff or unreadable — fine, return undefined.
+    }
+    return undefined;
+}
+//# sourceMappingURL=migration-verification.js.map