knodin 0.8.7 → 0.9.0

package/dist/src/update-executor.js

@@ -0,0 +1,336 @@
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createUpdateJournal, managerInstallArgv, readManagerUpdateState, readUpdateJournal, resolveManagerOwnership, setAutomaticRollbackPin, setManualPin, transitionUpdateJournal, writeManagerUpdateState, writeUpdateJournal, } from "./manager-update.js";
+import { acquireExclusiveUpdateCoordination } from "./update-coordination.js";
+import { verifyUpdateCandidate } from "./update-verifier.js";
+export async function certifyAutomaticUpdates(options) {
+    const verify = options.verifyCandidate ??
+        (async (input) => verifyUpdateCandidate({ ...input, timeoutMs: 60_000, env: options.env }));
+    const durations = [];
+    let fixtureVersion = "unknown";
+    let passed = true;
+    for (let run = 0; run < 5; run++) {
+        const started = Date.now();
+        const result = await verify({
+            command: options.runtimeCommand,
+            expectedVersion: options.currentVersion,
+            verificationToken: `platform-certification-${randomUUID()}`,
+        });
+        durations.push(Date.now() - started);
+        fixtureVersion = result.record.fixtureVersion;
+        if (result.status !== "passed")
+            passed = false;
+    }
+    durations.sort((left, right) => left - right);
+    const p95Ms = durations[Math.ceil(durations.length * 0.95) - 1] ?? Number.POSITIVE_INFINITY;
+    const state = readManagerUpdateState(options.stateHome);
+    const next = {
+        ...state,
+        autoEnabled: passed && p95Ms <= 20_000,
+        platformAutoEligible: passed && p95Ms <= 20_000,
+        platformCertification: {
+            platform: `${process.platform}-${process.arch}`,
+            fixtureVersion,
+            measuredAt: new Date().toISOString(),
+            p95Ms,
+            runs: durations.length,
+        },
+    };
+    writeManagerUpdateState(next, options.stateHome);
+    return next;
+}
+function sameOwner(left, right) {
+    return (left.status === "owned" &&
+        right.status === "owned" &&
+        left.method === right.method &&
+        left.executable.realpath === right.executable.realpath &&
+        left.packageRoot === right.packageRoot);
+}
+async function defaultRunManager(argv) {
+    const [executable, ...args] = argv;
+    if (!executable)
+        return { status: 1, stderr: "manager command is empty" };
+    const result = spawnSync(executable, args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 120_000,
+        maxBuffer: 4 * 1024 * 1024,
+    });
+    return {
+        status: result.status,
+        stderr: (result.stderr || result.error?.message || "").slice(0, 4096),
+    };
+}
+export async function executeManagerUpdate(options) {
+    const owner = resolveManagerOwnership({
+        runtimeCommand: options.runtimeCommand,
+        executablePath: options.runtimeCommand.at(-1),
+        env: options.env,
+    });
+    const managerArgv = managerInstallArgv(owner.method, options.targetVersion);
+    if (owner.status !== "owned" || !managerArgv) {
+        return {
+            status: "refused",
+            owner,
+            previousVersion: options.currentVersion,
+            targetVersion: options.targetVersion,
+            reason: owner.status === "ambiguous"
+                ? "competing, stale, or shadowing installations require manual cleanup"
+                : "the active package-manager owner could not be proven",
+        };
+    }
+    if (!options.apply) {
+        return {
+            status: "planned",
+            owner,
+            previousVersion: options.currentVersion,
+            targetVersion: options.targetVersion,
+            managerArgv,
+        };
+    }
+    const verificationToken = randomUUID();
+    const lock = acquireExclusiveUpdateCoordination({
+        stateHome: options.stateHome,
+        verificationToken,
+    });
+    const runManager = options.runManager ?? defaultRunManager;
+    const verify = options.verifyCandidate ??
+        (async (input) => verifyUpdateCandidate({
+            ...input,
+            timeoutMs: 60_000,
+            env: options.env,
+            expectedOwner: owner,
+        }));
+    let journal = createUpdateJournal({
+        previousVersion: options.currentVersion,
+        targetVersion: options.targetVersion,
+        manager: owner,
+        fixtureVersion: "2026-08-14.1",
+    });
+    writeUpdateJournal(journal, options.stateHome);
+    try {
+        const revalidated = resolveManagerOwnership({
+            runtimeCommand: options.runtimeCommand,
+            executablePath: options.runtimeCommand.at(-1),
+            env: options.env,
+        });
+        if (!sameOwner(owner, revalidated)) {
+            journal = transitionUpdateJournal(journal, "terminal-unhealthy", { error: "package-manager ownership changed after update lock acquisition" }, options.stateHome);
+            return {
+                status: "refused",
+                owner: revalidated,
+                previousVersion: options.currentVersion,
+                targetVersion: options.targetVersion,
+                journal,
+                reason: journal.error,
+            };
+        }
+        journal = transitionUpdateJournal(journal, "manager-applying", {}, options.stateHome);
+        const installed = await runManager(managerArgv);
+        journal = transitionUpdateJournal(journal, installed.status === 0 ? "candidate-installed-unverified" : "rollback-required", installed.status === 0 ? {} : { error: installed.stderr || "manager application failed" }, options.stateHome);
+        if (installed.status === 0) {
+            journal = transitionUpdateJournal(journal, "candidate-verifying", {}, options.stateHome);
+            const verification = await verify({
+                command: options.runtimeCommand,
+                expectedVersion: options.targetVersion,
+                verificationToken,
+            });
+            journal = { ...journal, verification: verification.record };
+            if (verification.status === "passed") {
+                journal = transitionUpdateJournal(journal, "candidate-verified", {}, options.stateHome);
+                if (options.pinKind === "manual")
+                    setManualPin(options.targetVersion, options.stateHome);
+                return {
+                    status: "verified",
+                    owner,
+                    previousVersion: options.currentVersion,
+                    targetVersion: options.targetVersion,
+                    managerArgv,
+                    journal,
+                    verification: verification.record,
+                };
+            }
+            journal = transitionUpdateJournal(journal, "rollback-required", { error: verification.error ?? "candidate verification failed" }, options.stateHome);
+        }
+        const rollbackArgv = managerInstallArgv(owner.method, options.currentVersion);
+        if (!rollbackArgv)
+            throw new Error("exact rollback manager command is unavailable");
+        journal = transitionUpdateJournal(journal, "rollback-applying", {}, options.stateHome);
+        const restored = await runManager(rollbackArgv);
+        if (restored.status !== 0) {
+            journal = transitionUpdateJournal(journal, "terminal-unhealthy", { error: restored.stderr || "rollback manager application failed" }, options.stateHome);
+            return {
+                status: "terminal-unhealthy",
+                owner,
+                previousVersion: options.currentVersion,
+                targetVersion: options.targetVersion,
+                journal,
+                reason: journal.error,
+            };
+        }
+        journal = transitionUpdateJournal(journal, "rollback-installed-unverified", {}, options.stateHome);
+        journal = transitionUpdateJournal(journal, "rollback-verifying", {}, options.stateHome);
+        const rollbackVerification = await verify({
+            command: options.runtimeCommand,
+            expectedVersion: options.currentVersion,
+            verificationToken,
+        });
+        journal = { ...journal, verification: rollbackVerification.record };
+        if (rollbackVerification.status !== "passed") {
+            journal = transitionUpdateJournal(journal, "terminal-unhealthy", { error: rollbackVerification.error ?? "rollback verification failed" }, options.stateHome);
+            return {
+                status: "terminal-unhealthy",
+                owner,
+                previousVersion: options.currentVersion,
+                targetVersion: options.targetVersion,
+                journal,
+                verification: rollbackVerification.record,
+                reason: journal.error,
+            };
+        }
+        journal = transitionUpdateJournal(journal, "rollback-verified", {}, options.stateHome);
+        setAutomaticRollbackPin(options.currentVersion, options.targetVersion, options.stateHome);
+        return {
+            status: "rolled-back",
+            owner,
+            previousVersion: options.currentVersion,
+            targetVersion: options.targetVersion,
+            journal,
+            verification: rollbackVerification.record,
+        };
+    }
+    finally {
+        lock.release();
+    }
+}
+function installedRuntimeVersion(command, env) {
+    const [executable, ...prefix] = command;
+    if (!executable)
+        return null;
+    const result = spawnSync(executable, [...prefix, "--version"], {
+        encoding: "utf8",
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 10_000,
+    });
+    return result.status === 0 && /^\d+\.\d+\.\d+/.test(result.stdout.trim())
+        ? result.stdout.trim()
+        : null;
+}
+/** Resume an interrupted installation from its fsynced journal before ordinary dispatch. */
+export async function recoverInterruptedUpdate(options) {
+    let journal = readUpdateJournal(options.stateHome);
+    if (!journal || ["planned", "candidate-verified", "rollback-verified"].includes(journal.state))
+        return null;
+    if (journal.state === "terminal-unhealthy")
+        return {
+            status: "terminal-unhealthy",
+            owner: journal.manager,
+            previousVersion: journal.previousVersion,
+            targetVersion: journal.targetVersion,
+            journal,
+            reason: journal.error,
+        };
+    const verificationToken = randomUUID();
+    const lock = acquireExclusiveUpdateCoordination({
+        stateHome: options.stateHome,
+        verificationToken,
+        recovery: true,
+    });
+    const runManager = options.runManager ?? defaultRunManager;
+    const expectedRecoveryOwner = journal.manager;
+    const verify = options.verifyCandidate ??
+        (async (input) => verifyUpdateCandidate({
+            ...input,
+            timeoutMs: 60_000,
+            env: options.env,
+            expectedOwner: expectedRecoveryOwner,
+        }));
+    try {
+        if (journal.state === "manager-applying") {
+            const active = installedRuntimeVersion(options.runtimeCommand, options.env);
+            journal = transitionUpdateJournal(journal, active === journal.targetVersion
+                ? "candidate-installed-unverified"
+                : active === journal.previousVersion
+                    ? "rollback-installed-unverified"
+                    : "rollback-required", active && [journal.targetVersion, journal.previousVersion].includes(active)
+                ? {}
+                : {
+                    error: `manager application was interrupted with active version ${active ?? "unknown"}`,
+                }, options.stateHome);
+        }
+        if (["candidate-installed-unverified", "candidate-verifying"].includes(journal.state)) {
+            journal = transitionUpdateJournal(journal, "candidate-verifying", {}, options.stateHome);
+            const candidate = await verify({
+                command: options.runtimeCommand,
+                expectedVersion: journal.targetVersion,
+                verificationToken,
+            });
+            journal = { ...journal, verification: candidate.record };
+            if (candidate.status === "passed") {
+                journal = transitionUpdateJournal(journal, "candidate-verified", {}, options.stateHome);
+                return {
+                    status: "verified",
+                    owner: journal.manager,
+                    previousVersion: journal.previousVersion,
+                    targetVersion: journal.targetVersion,
+                    journal,
+                    verification: candidate.record,
+                };
+            }
+            journal = transitionUpdateJournal(journal, "rollback-required", { error: candidate.error ?? "interrupted candidate verification failed" }, options.stateHome);
+        }
+        if (["rollback-required", "rollback-applying"].includes(journal.state)) {
+            const rollbackArgv = managerInstallArgv(journal.manager.method, journal.previousVersion);
+            if (!rollbackArgv)
+                throw new Error("exact recovery rollback is unavailable");
+            journal = transitionUpdateJournal(journal, "rollback-applying", {}, options.stateHome);
+            const restored = await runManager(rollbackArgv);
+            if (restored.status !== 0) {
+                journal = transitionUpdateJournal(journal, "terminal-unhealthy", { error: restored.stderr || "recovery rollback manager failed" }, options.stateHome);
+                return {
+                    status: "terminal-unhealthy",
+                    owner: journal.manager,
+                    previousVersion: journal.previousVersion,
+                    targetVersion: journal.targetVersion,
+                    journal,
+                    reason: journal.error,
+                };
+            }
+            journal = transitionUpdateJournal(journal, "rollback-installed-unverified", {}, options.stateHome);
+        }
+        if (["rollback-installed-unverified", "rollback-verifying"].includes(journal.state)) {
+            journal = transitionUpdateJournal(journal, "rollback-verifying", {}, options.stateHome);
+            const restored = await verify({
+                command: options.runtimeCommand,
+                expectedVersion: journal.previousVersion,
+                verificationToken,
+            });
+            journal = { ...journal, verification: restored.record };
+            if (restored.status === "passed") {
+                journal = transitionUpdateJournal(journal, "rollback-verified", {}, options.stateHome);
+                setAutomaticRollbackPin(journal.previousVersion, journal.targetVersion, options.stateHome);
+                return {
+                    status: "rolled-back",
+                    owner: journal.manager,
+                    previousVersion: journal.previousVersion,
+                    targetVersion: journal.targetVersion,
+                    journal,
+                    verification: restored.record,
+                };
+            }
+            journal = transitionUpdateJournal(journal, "terminal-unhealthy", { error: restored.error ?? "interrupted rollback verification failed" }, options.stateHome);
+        }
+        return {
+            status: "terminal-unhealthy",
+            owner: journal.manager,
+            previousVersion: journal.previousVersion,
+            targetVersion: journal.targetVersion,
+            journal,
+            reason: journal.error ?? `recovery stopped in ${journal.state}`,
+        };
+    }
+    finally {
+        lock.release();
+    }
+}

package/dist/src/update-verifier.js

@@ -0,0 +1,358 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getModelCacheDirectory } from "./engine/embeddings.js";
+function packagedFixture() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../fixtures/update-verification");
+}
+function parseJson(output, label) {
+    try {
+        return JSON.parse(output);
+    }
+    catch {
+        throw new Error(`${label} did not return one complete JSON document`);
+    }
+}
+function run(command, args, options) {
+    const [executable, ...prefix] = command;
+    if (!executable)
+        throw new Error("candidate command is empty");
+    const timeout = options.remainingMs();
+    if (timeout <= 0)
+        throw new Error("verification deadline exceeded");
+    const result = spawnSync(executable, [...prefix, ...args], {
+        cwd: options.cwd,
+        env: options.env,
+        encoding: "utf8",
+        timeout,
+        maxBuffer: 4 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error && result.error.code === "ETIMEDOUT")
+        throw new Error("verification deadline exceeded");
+    if (result.status !== 0) {
+        const rawDetail = (result.stderr || result.stdout || `exit ${result.status}`).trim();
+        const detail = rawDetail.slice(Math.max(0, rawDetail.length - 4096));
+        throw new Error(`candidate command failed: ${detail}`);
+    }
+    return result.stdout;
+}
+const MAX_MCP_STREAM_BYTES = 64 * 1_024;
+async function startMcpSession(command, cwd, env, remainingMs) {
+    const [executable, ...prefix] = command;
+    if (!executable)
+        throw new Error("candidate command is empty");
+    const child = spawn(executable, [...prefix, "serve"], {
+        cwd,
+        env,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdoutBuffer = "";
+    let stderr = "";
+    let nextId = 1;
+    let closed = false;
+    const pending = new Map();
+    const rejectPending = (message) => {
+        closed = true;
+        for (const request of pending.values()) {
+            clearTimeout(request.timeout);
+            request.reject(new Error(`${message}: ${stderr.slice(-2048)}`));
+        }
+        pending.clear();
+    };
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        stdoutBuffer += chunk;
+        if (Buffer.byteLength(stdoutBuffer) > MAX_MCP_STREAM_BYTES) {
+            rejectPending("MCP server emitted an oversized unterminated response");
+            child.kill("SIGKILL");
+            return;
+        }
+        for (;;) {
+            const newline = stdoutBuffer.indexOf("\n");
+            if (newline < 0)
+                break;
+            const line = stdoutBuffer.slice(0, newline).trim();
+            stdoutBuffer = stdoutBuffer.slice(newline + 1);
+            if (!line)
+                continue;
+            let response;
+            try {
+                response = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (typeof response.id !== "number")
+                continue;
+            const request = pending.get(response.id);
+            if (!request)
+                continue;
+            pending.delete(response.id);
+            clearTimeout(request.timeout);
+            request.resolve(response);
+        }
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr = `${stderr}${chunk}`.slice(-MAX_MCP_STREAM_BYTES);
+    });
+    child.once("error", (error) => rejectPending(`MCP server failed: ${error.message}`));
+    child.once("exit", (code) => {
+        if (pending.size > 0)
+            rejectPending(`MCP server exited ${code}`);
+        else
+            closed = true;
+    });
+    const request = async (method, params) => {
+        if (closed)
+            throw new Error("MCP server is not running");
+        const timeoutMs = remainingMs();
+        if (timeoutMs <= 0)
+            throw new Error("MCP verification deadline exceeded");
+        const id = nextId++;
+        const response = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                pending.delete(id);
+                child.kill("SIGKILL");
+                reject(new Error("MCP verification deadline exceeded"));
+            }, Math.max(1, timeoutMs));
+            pending.set(id, { resolve, reject, timeout });
+        });
+        child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+        const value = await response;
+        if (value.error)
+            throw new Error(value.error.message ?? "MCP request failed");
+        return value;
+    };
+    const closeChild = async () => {
+        if (closed)
+            return;
+        child.stdin.end();
+        await new Promise((resolve) => {
+            const killTimeout = setTimeout(() => child.kill("SIGKILL"), 1_000);
+            const hardTimeout = setTimeout(resolve, 3_000);
+            child.once("close", () => {
+                clearTimeout(killTimeout);
+                clearTimeout(hardTimeout);
+                resolve();
+            });
+        });
+    };
+    try {
+        const initialized = await request("initialize", {
+            protocolVersion: "2025-06-18",
+            capabilities: {},
+            clientInfo: { name: "knodin-update-verifier", version: "1" },
+        });
+        child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} })}\n`);
+        const listed = await request("tools/list", {});
+        if (initialized.result?.serverInfo?.name !== "knodin" ||
+            !listed.result?.tools?.some((tool) => tool.name === "knodin"))
+            throw new Error("candidate MCP initialize/tools-list contract is incomplete");
+    }
+    catch (error) {
+        await closeChild();
+        throw error;
+    }
+    return {
+        async call(arguments_) {
+            const response = await request("tools/call", {
+                name: "knodin",
+                arguments: arguments_,
+            });
+            const toolResult = response.result;
+            const text = toolResult?.content?.find((item) => item.type === "text")?.text;
+            if (toolResult?.isError || !text)
+                throw new Error(`candidate MCP query failed${text ? `: ${text.slice(-2048)}` : ""}`);
+            return parseJson(text, "candidate MCP query");
+        },
+        close: closeChild,
+    };
+}
+function elapsedPhase(record, phase, action) {
+    const started = Date.now();
+    try {
+        return action();
+    }
+    finally {
+        record.phaseTimingsMs[phase] = Date.now() - started;
+    }
+}
+async function elapsedAsyncPhase(record, phase, action) {
+    const started = Date.now();
+    try {
+        return await action();
+    }
+    finally {
+        record.phaseTimingsMs[phase] = Date.now() - started;
+    }
+}
+export async function verifyUpdateCandidate(options) {
+    const source = options.fixtureSource ?? packagedFixture();
+    const manifest = JSON.parse(fs.readFileSync(path.join(source, "fixture.json"), "utf8"));
+    const record = {
+        fixtureVersion: manifest.fixtureVersion,
+        platform: process.platform,
+        startedAt: new Date().toISOString(),
+        phaseTimingsMs: {},
+        coverage: Object.fromEntries(manifest.languages.map((language) => [language, "unavailable"])),
+    };
+    const timeoutMs = Math.min(Math.max(options.timeoutMs ?? 60_000, 1), 60_000);
+    const deadline = Date.now() + timeoutMs;
+    const remainingMs = () => deadline - Date.now();
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "knodin-update-verification-"));
+    const repository = path.join(root, "fixture");
+    const env = {
+        ...options.env,
+        PATH: options.env?.PATH ?? process.env.PATH,
+        HOME: path.join(root, "home"),
+        XDG_CONFIG_HOME: path.join(root, "config"),
+        XDG_STATE_HOME: path.join(root, "state"),
+        KNODIN_UPDATE_CHECK: "0",
+        KNODIN_UPDATE_VERIFICATION_TOKEN: options.verificationToken ?? "",
+        // Repository/config state is isolated under the temporary HOME, while the
+        // immutable local model cache remains machine-scoped just as it is for an
+        // ordinary installation. Hiding it forces a redundant network fetch and can
+        // turn an otherwise healthy offline candidate into semanticReadiness=absent.
+        KNODIN_MODEL_CACHE: options.env?.KNODIN_MODEL_CACHE ?? getModelCacheDirectory({ env: process.env }),
+        // The immutable fixture is deliberately small. Four-way inference is
+        // measurably faster here while preserving every symbol and assertion; keep
+        // the override scoped to the verification child so production indexing
+        // retains its separately benchmarked default.
+        KNODIN_EMBEDDING_BATCH_SIZE: options.env?.KNODIN_EMBEDDING_BATCH_SIZE ?? "4",
+    };
+    let mcp;
+    try {
+        elapsedPhase(record, "copy-fixture", () => fs.cpSync(source, repository, { recursive: true, dereference: false }));
+        elapsedPhase(record, "git-fixture", () => {
+            run(["git"], ["init", "--quiet"], { cwd: repository, env, remainingMs });
+            run(["git"], ["config", "user.email", "verifier@knodin.local"], {
+                cwd: repository,
+                env,
+                remainingMs,
+            });
+            run(["git"], ["config", "user.name", "Knodin Verifier"], {
+                cwd: repository,
+                env,
+                remainingMs,
+            });
+            run(["git"], ["add", "."], { cwd: repository, env, remainingMs });
+            run(["git"], ["commit", "--quiet", "-m", "verification fixture"], {
+                cwd: repository,
+                env,
+                remainingMs,
+            });
+        });
+        elapsedPhase(record, "version-owner", () => {
+            const version = run(options.command, ["--version"], {
+                cwd: repository,
+                env,
+                remainingMs,
+            }).trim();
+            if (version !== options.expectedVersion)
+                throw new Error(`candidate version ${version || "empty"} does not equal ${options.expectedVersion}`);
+            if (options.expectedOwner) {
+                const status = parseJson(run(options.command, ["update", "status", "--json"], {
+                    cwd: repository,
+                    env,
+                    remainingMs,
+                }), "candidate owner status");
+                const owner = status.owner;
+                if (owner?.status !== "owned" ||
+                    owner.method !== options.expectedOwner.method ||
+                    owner.executable.realpath !== options.expectedOwner.executable.realpath)
+                    throw new Error("candidate executable owner changed or is ambiguous after installation");
+            }
+        });
+        const mcpStarted = Date.now();
+        const mcpSession = await startMcpSession(options.command, repository, env, remainingMs);
+        mcp = mcpSession;
+        record.phaseTimingsMs.mcp = Date.now() - mcpStarted;
+        elapsedPhase(record, "init", () => {
+            run(options.command, ["init", "--scope", "cli-only", "--json"], {
+                cwd: repository,
+                env,
+                remainingMs,
+            });
+        });
+        elapsedPhase(record, "deep-status", () => {
+            const status = parseJson(run(options.command, ["status", "--deep", "--json"], {
+                cwd: repository,
+                env,
+                remainingMs,
+            }), "deep status");
+            if (status.status !== "healthy")
+                throw new Error(`deep status is ${String(status.status)}`);
+            if (status.semanticReadiness !== "ready")
+                throw new Error(`semantic readiness is ${String(status.semanticReadiness ?? "missing")}`);
+            const coverage = status.coverage;
+            if (coverage?.percent !== 100)
+                throw new Error("graph coverage is partial");
+        });
+        await elapsedAsyncPhase(record, "assertions", async () => {
+            const batch = await mcpSession.call({
+                operation: "query_batch",
+                queries: manifest.assertions.map(({ pattern, symbol }) => ({
+                    pattern,
+                    symbol,
+                })),
+                repoPath: repository,
+            });
+            const batchResults = batch.results;
+            if (!Array.isArray(batchResults) || batchResults.length !== manifest.assertions.length)
+                throw new Error("candidate query batch returned incomplete results");
+            for (const assertion of manifest.assertions) {
+                const output = batchResults.find((row) => row.pattern === assertion.pattern && row.symbol === assertion.symbol)?.output;
+                if (!output)
+                    throw new Error(`${assertion.pattern} ${assertion.symbol} was omitted from query batch`);
+                const results = output.results;
+                if (!Array.isArray(results) || results.length === 0)
+                    throw new Error(`${assertion.pattern} ${assertion.symbol} returned empty results`);
+                const match = results.find((row) => Object.entries(assertion.expected).every(([key, value]) => row[key] === value));
+                if (!match || ("symbol" in assertion.expected && typeof match.identity !== "string"))
+                    throw new Error(`${assertion.symbol} returned incorrect identity, source location, edge kind, or evidence`);
+                for (const language of assertion.coverage)
+                    record.coverage[language] = "passed";
+            }
+            for (const language of manifest.languages)
+                if (record.coverage[language] !== "passed")
+                    throw new Error(`${language} fixture coverage was not explicitly verified`);
+        });
+        record.finishedAt = new Date().toISOString();
+        return { status: "passed", record };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        record.finishedAt = new Date().toISOString();
+        if (message.includes("deadline exceeded"))
+            record.timeoutCause = message;
+        for (const language of manifest.languages) {
+            if (record.coverage[language] !== "passed")
+                record.coverage[language] = "failed";
+        }
+        return {
+            status: message.includes("deadline exceeded") ? "timed-out" : "failed",
+            record,
+            error: message,
+        };
+    }
+    finally {
+        try {
+            await mcp?.close();
+        }
+        catch {
+            // Cleanup cannot turn a structured verification failure into an
+            // unjournaled thrown exception. The updater owns recovery decisions.
+        }
+        try {
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+        catch {
+            // A still-closing candidate may temporarily hold fixture handles on
+            // Windows. Verification truth takes precedence over temp cleanup.
+        }
+    }
+}