human-to-code 0.1.13 → 0.1.14

package/dist/agents/guided/workflow.js

@@ -0,0 +1,1360 @@
+/** Auditable generation, isolated validation, and explicit application workflow. */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmod, lstat } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import { analyzeProject, SUPPORT_MATRIX_VERSION } from "../../analysis/analyzer.js";
+import { evaluateProviderCertification, providerProfileId } from "../../providers/certification.js";
+import { CompilerToolExecutor } from "../../context/compiler-tools.js";
+import { validateConfig } from "../../config/config.js";
+import { canonicalJson, hashCanonical, sha256Text, validateChangeContractV1, validatePatchSetV1, validateValidationPlanV1, validateValidationReportV1, } from "../../core/contracts.js";
+import { hashContextManifest, selectContext, validateContextManifestV1, } from "../../context/context.js";
+import { applyPatchAtomic, normalizePatchPath, PatchSafetyError, preparePatch } from "../../pipeline/patch.js";
+import { DocumentationError, OfficialDocumentationClient } from "../../context/documentation.js";
+import { COMPILER_CONTEXT_TOOLS, ProviderBudgetTracker, ProviderError, generateValidated, withProviderRetries, } from "../../providers/provider.js";
+import { RunStore } from "../../pipeline/run-store.js";
+import { PATCH_SET_SCHEMA_V1 } from "../../providers/schemas.js";
+import { ProjectSecretScanError, scanProjectForSecrets } from "../../security/secret-scan.js";
+import { buildGuidedPatchPrompt } from "../../prompts/guided-patch.js";
+import { buildGuidedRepairPrompt } from "../../prompts/guided-repair.js";
+import { cloneWorkspaceSnapshot, createWorkspaceSnapshot, disposeWorkspaceSnapshot } from "../../pipeline/snapshot.js";
+import { strongSandboxAvailable, validateBaselineAndCandidate } from "../../pipeline/validation.js";
+import { createValidationPlan, resolveWorkspaceConfig, targetWorkspaces, unique, } from "./workspace-policy.js";
+import { renderPatchDiff } from "./patch-diff.js";
+import { assertExternalApisGrounded } from "./api-grounding.js";
+export { createValidationPlan, resolveWorkspaceConfig } from "./workspace-policy.js";
+export { renderPatchDiff } from "./patch-diff.js";
+function now() {
+    return new Date().toISOString();
+}
+function initialContextCandidates(contract, workspaces, config) {
+    const candidates = [{
+            origin: "project",
+            path: contract.source.path,
+            reason: "Reviewed natural-language change source bound by the contract hash.",
+            required: true,
+            priority: 1000,
+        }];
+    for (const workspace of workspaces) {
+        for (const path of workspace.manifests) {
+            candidates.push({ origin: "project", path, reason: `Manifest for target workspace ${workspace.id}.`, required: true, priority: 900 });
+        }
+        for (const path of [...workspace.entryPoints, ...workspace.routes]) {
+            candidates.push({ origin: "project", path, reason: `Target entry point or route in ${workspace.id}.`, priority: 700 });
+        }
+        for (const evidence of workspace.evidence) {
+            if (evidence.kind === "source" || evidence.kind === "config" || evidence.kind === "lockfile") {
+                candidates.push({
+                    origin: evidence.kind === "lockfile" ? "dependency" : "project",
+                    path: evidence.path,
+                    reason: `${workspace.id} analysis evidence: ${evidence.detail}`,
+                    priority: evidence.kind === "source" ? 600 : 500,
+                    ...(evidence.kind === "lockfile" && workspace.lockfiles.includes(evidence.path) ? { version: workspace.framework.resolvedVersion } : {}),
+                });
+            }
+        }
+    }
+    for (const path of config.documentation.privatePaths) {
+        candidates.push({ origin: "private_documentation", path, reason: "Operator-configured private project documentation.", priority: 400 });
+    }
+    return candidates.filter((candidate) => {
+        if (candidate.origin === "official_documentation")
+            return true;
+        return !config.privacy.excludedPaths.some((excluded) => candidate.path === excluded || candidate.path.startsWith(`${excluded}/`));
+    });
+}
+function officialDocumentationHosts(config) {
+    return unique([
+        "react.dev", "nextjs.org", "vite.dev", "docs.nestjs.com", "fastapi.tiangolo.com",
+        "docs.pydantic.dev", "docs.python.org", "doc.rust-lang.org", "docs.rs",
+        ...config.documentation.officialDomains,
+    ]);
+}
+function dependencyIdentity(value) {
+    return value.toLowerCase().replaceAll("_", "-");
+}
+function officialDocumentationUrl(config, workspace, dependency, version) {
+    const configured = config.documentation.officialSources.find((source) => source.ecosystem === workspace.ecosystem
+        && dependencyIdentity(source.dependency) === dependencyIdentity(dependency)
+        && source.version === version);
+    if (configured)
+        return configured.url;
+    if (workspace.ecosystem !== "rust")
+        return undefined;
+    const crate = dependency.replaceAll("_", "-");
+    return `https://docs.rs/${encodeURIComponent(crate)}/${encodeURIComponent(version)}/${encodeURIComponent(crate.replaceAll("-", "_"))}/`;
+}
+function contextBudget(config) {
+    const maxBytes = Math.max(1024, Math.min(8 * 1024 * 1024, config.privacy.maxContextTokens * 4));
+    return {
+        maxBytes,
+        maxBytesPerItem: Math.min(config.privacy.maxFileBytes, maxBytes),
+        maxEstimatedTokens: config.privacy.maxContextTokens,
+    };
+}
+function permittedContextCandidate(candidate, config) {
+    if (candidate.origin === "official_documentation")
+        return true;
+    return !config.privacy.excludedPaths.some((excluded) => candidate.path === excluded || candidate.path.startsWith(`${excluded}/`));
+}
+function manifestCandidates(manifest) {
+    return manifest.evidence.map((item) => item.origin === "official_documentation"
+        ? {
+            origin: "official_documentation",
+            url: item.url,
+            version: item.version,
+            content: item.content,
+            contentSha256: item.sha256,
+            reason: item.reason,
+            cached: item.cached,
+            range: { startLine: item.startLine, endLine: item.endLine },
+            required: true,
+        }
+        : {
+            origin: item.origin,
+            path: item.path,
+            reason: item.reason,
+            range: { startLine: item.startLine, endLine: item.endLine },
+            required: true,
+            ...(item.version === undefined ? {} : { version: item.version }),
+        });
+}
+async function precomputeContractContext(root, profile, contract, config, offline, initial) {
+    const documentation = new OfficialDocumentationClient({
+        allowedHosts: officialDocumentationHosts(config),
+        maxBytes: Math.min(2 * 1024 * 1024, config.privacy.maxFileBytes * 4),
+    });
+    const executor = new CompilerToolExecutor(root, profile, {
+        maximumRequests: 8,
+        officialDocumentation: async ({ workspace, dependency, version, reason }) => {
+            const url = officialDocumentationUrl(config, workspace, dependency, version);
+            if (!url)
+                return undefined;
+            return documentation.retrieve({
+                url,
+                version,
+                reason: `Version-matched official API evidence for ${dependency} ${version}: ${reason}`,
+                offline,
+            });
+        },
+    });
+    const candidates = [...initial];
+    let requestNumber = 0;
+    const workspaces = targetWorkspaces(profile, contract);
+    const symbols = unique(contract.targetSymbols)
+        .filter((symbol) => symbol.length >= 2 && symbol.length <= 256 && !/[\r\n\0]/u.test(symbol))
+        .slice(0, 4);
+    for (const workspace of workspaces) {
+        for (const symbol of symbols) {
+            if (requestNumber >= 4)
+                break;
+            requestNumber += 1;
+            const found = await executor.execute({
+                schemaVersion: 1,
+                requestId: `host-symbol-${requestNumber}`,
+                kind: "symbol",
+                workspace: workspace.id,
+                query: symbol,
+                reason: "Deterministic pre-provider lookup for a reviewed target symbol.",
+                maxItems: 3,
+                path: null,
+            }).catch(() => []);
+            candidates.push(...found.map((item) => ({ ...item, priority: 800 })));
+        }
+    }
+    const firstManifest = await selectContext({
+        root,
+        projectFingerprint: profile.fingerprint,
+        candidates: candidates.filter((candidate) => permittedContextCandidate(candidate, config)),
+        offline,
+        secretPolicy: "block",
+        budget: contextBudget(config),
+        officialDocumentationHosts: officialDocumentationHosts(config),
+    });
+    const manifestPaths = new Set(workspaces.flatMap((workspace) => [...workspace.manifests, ...workspace.lockfiles]));
+    const corpus = `${canonicalJson(contract)}\n${firstManifest.evidence
+        .filter((item) => (item.origin === "project" || item.origin === "private_documentation")
+        && !("path" in item && manifestPaths.has(item.path)))
+        .map((item) => item.content)
+        .join("\n")}`.toLowerCase();
+    const coreNames = new Set(workspaces.flatMap((workspace) => {
+        if (workspace.ecosystem === "react")
+            return ["react", "react-dom", "next", "vite"];
+        if (workspace.ecosystem === "nestjs")
+            return ["@nestjs/core", "@nestjs/common", "@nestjs/platform-express", "@nestjs/platform-fastify"];
+        if (workspace.ecosystem === "fastapi")
+            return ["fastapi", "pydantic"];
+        return [];
+    }));
+    const mentioned = workspaces.flatMap((workspace) => workspace.framework.dependencies
+        .map((dependency) => {
+        const names = unique([
+            dependency.name.toLowerCase(),
+            dependency.name.toLowerCase().replaceAll("-", "_"),
+            dependency.name.toLowerCase().replace(/^@[^/]+\//u, ""),
+        ]);
+        const explicit = names.some((name) => name.length >= 2 && corpus.includes(name));
+        const core = coreNames.has(dependency.name.toLowerCase());
+        return { workspace, dependency, score: explicit ? 2 : core ? 1 : 0 };
+    })
+        .filter((item) => item.score > 0))
+        .sort((left, right) => right.score - left.score
+        || left.dependency.name.localeCompare(right.dependency.name)
+        || left.workspace.id.localeCompare(right.workspace.id));
+    for (const { workspace, dependency } of mentioned) {
+        if (requestNumber >= 8)
+            break;
+        requestNumber += 1;
+        const found = await executor.execute({
+            schemaVersion: 1,
+            requestId: `host-dependency-${requestNumber}`,
+            kind: "dependency-doc",
+            workspace: workspace.id,
+            query: dependency.name,
+            reason: "Installed API evidence referenced by the reviewed contract or selected project code.",
+            maxItems: 4,
+            path: null,
+        });
+        candidates.push(...found.map((item) => ({ ...item, priority: 650 })));
+    }
+    return candidates.filter((candidate) => permittedContextCandidate(candidate, config));
+}
+export async function buildContextPreview(rootInput, profile, contract, config, offline = config.documentation.mode === "offline") {
+    const root = resolve(rootInput);
+    await scanProjectForSecrets(root);
+    config = resolveWorkspaceConfig(config, profile, contract);
+    const workspaces = targetWorkspaces(profile, contract);
+    const candidates = await precomputeContractContext(root, profile, contract, config, offline, initialContextCandidates(contract, workspaces, config));
+    return selectContext({
+        root,
+        projectFingerprint: profile.fingerprint,
+        candidates,
+        offline,
+        secretPolicy: "block",
+        budget: contextBudget(config),
+        officialDocumentationHosts: officialDocumentationHosts(config),
+    });
+}
+function toolRequestFromOutput(output) {
+    if (typeof output !== "object" || output === null || Array.isArray(output))
+        throw new ProviderError("schema", "Provider tool output was not an object.");
+    const calls = output.toolCalls;
+    if (!Array.isArray(calls) || calls.length !== 1)
+        throw new ProviderError("schema", "Exactly one context tool call is allowed per model request.");
+    const call = calls[0];
+    if (typeof call !== "object" || call === null || Array.isArray(call))
+        throw new ProviderError("schema", "Context tool call was invalid.");
+    const record = call;
+    if (record.name !== "request_context")
+        throw new ProviderError("safety", "Provider requested an unauthorized tool.");
+    return record.arguments;
+}
+function providerBudget(config, maxElapsedMs = config.budgets.timeoutMs) {
+    return new ProviderBudgetTracker({
+        maxInputTokens: config.budgets.maxInputTokens,
+        maxOutputTokens: config.budgets.maxOutputTokens,
+        maxRequests: config.budgets.maxRequests,
+        maxRepairs: config.budgets.maxRepairs,
+        maxCostUsd: config.budgets.maxCostUsd,
+        maxElapsedMs,
+    });
+}
+function usageSummary(budget) {
+    const usage = budget.usage;
+    return {
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        totalTokens: usage.inputTokens + usage.outputTokens,
+        requests: usage.requests,
+        repairs: usage.repairs,
+        costUsd: usage.costUsd,
+    };
+}
+function certificationFor(profile, contract, profileId) {
+    // Certification is derived only from re-scored, host-owned benchmark evidence
+    // for this exact provider/model profile. The shipped registry is empty, so a
+    // normal preview run resolves to certified: false and cannot reach VERIFIED.
+    const targets = targetWorkspaces(profile, contract);
+    const certifiedKeys = new Set(evaluateProviderCertification(profileId).certifiedMatrixKeys);
+    const providerCertified = certifiedKeys.size > 0;
+    const uncertified = targets.filter((workspace) => !certifiedKeys.has(workspace.support.matrixKey));
+    const profileCertified = targets.length > 0 && uncertified.length === 0;
+    const provider = {
+        matrixKey: profileId,
+        certified: providerCertified,
+        reason: providerCertified
+            ? `Provider profile ${profileId} has passing certification benchmark evidence.`
+            : `No certified benchmark evidence exists for provider profile ${profileId}.`,
+    };
+    const reasons = [
+        ...(profileCertified ? [] : [
+            uncertified.length === targets.length
+                ? "No target ecosystem has passed the certification benchmark for this provider/model."
+                : `These target ecosystems lack certification evidence for this provider/model: ${uncertified.map((workspace) => workspace.support.matrixKey).join(", ")}.`,
+        ]),
+        ...(provider.certified ? [] : [provider.reason]),
+    ];
+    return {
+        schemaVersion: 1,
+        supportMatrixVersion: SUPPORT_MATRIX_VERSION,
+        provider,
+        profileCertified,
+        certified: profileCertified && provider.certified,
+        reasons,
+    };
+}
+function runRecord(root, runId) {
+    const timestamp = now();
+    return {
+        runId,
+        schemaVersion: 1,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        root,
+        status: "INCONCLUSIVE",
+        diagnostics: ["Run created; no success status is implied until isolated validation completes."],
+    };
+}
+async function persistOutcome(store, runId, status, diagnostics, fields = {}) {
+    return store.update(runId, (current) => ({
+        ...current,
+        ...fields,
+        runId: current.runId,
+        schemaVersion: 1,
+        updatedAt: now(),
+        status,
+        diagnostics,
+    }));
+}
+export async function generateRun(input) {
+    const options = { ...input, config: resolveWorkspaceConfig(input.config, input.profile, input.contract) };
+    const root = resolve(options.root);
+    const store = options.store ?? new RunStore();
+    const runId = randomUUID();
+    await store.create(runRecord(root, runId));
+    const diagnostics = [];
+    let baseline;
+    try {
+        const contract = validateChangeContractV1(options.contract);
+        if (options.profile.status !== "SUPPORTED")
+            throw new Error(`Project profile status is ${options.profile.status}.`);
+        if (contract.projectFingerprint !== options.profile.fingerprint)
+            throw new Error("Contract profile fingerprint is stale.");
+        const workspaces = targetWorkspaces(options.profile, contract);
+        // The strict pipeline refuses to generate what it cannot validate. The
+        // ungrounded `general` fallback is the sole, explicitly-degraded exception:
+        // it has no toolchain to validate against, produces a reviewable patch, and
+        // is pinned to INCONCLUSIVE for the life of the run (never VERIFIED/applied).
+        const generalRun = workspaces.length > 0 && workspaces.every((workspace) => workspace.ecosystem === "general");
+        const validationPlan = generalRun ? undefined : createValidationPlan(options.profile, contract);
+        if (!generalRun && (validationPlan === undefined || validationPlan.commands.length === 0)) {
+            throw new Error("No required project validation command could be selected before generation.");
+        }
+        baseline = await createWorkspaceSnapshot(root, { excludeNames: [".venv", "venv", "target", ".next", "coverage"] });
+        let manifest = await buildContextPreview(root, options.profile, contract, options.config, options.offline ?? options.config.documentation.mode === "offline");
+        // Keep every item in the reviewed preview when local-only context tools add
+        // further evidence. Re-selection must never silently drop the preview set.
+        const candidates = manifestCandidates(manifest);
+        await store.writeArtifact(runId, "profile.json", options.profile);
+        await store.writeArtifact(runId, "run-config.json", options.config);
+        await store.writeArtifact(runId, "contract.json", contract);
+        if (validationPlan)
+            await store.writeArtifact(runId, "validation-plan.json", validationPlan);
+        await store.writeArtifact(runId, "context.json", manifest);
+        if (options.provider.capabilities.remote && !options.config.privacy.remoteProviderConsent) {
+            diagnostics.push("Outbound context preview was created, but remote provider consent is false. Review context.json and explicitly enable consent.");
+            await persistOutcome(store, runId, "NEEDS_INPUT", diagnostics, {
+                contractHash: hashCanonical(contract),
+                contextManifestHash: hashContextManifest(manifest),
+            });
+            return { runId, status: "NEEDS_INPUT", diagnostics };
+        }
+        const budget = providerBudget(options.config);
+        const documentation = new OfficialDocumentationClient({
+            allowedHosts: officialDocumentationHosts(options.config),
+            maxBytes: Math.min(2 * 1024 * 1024, options.config.privacy.maxFileBytes * 4),
+        });
+        const executor = new CompilerToolExecutor(root, options.profile, {
+            maximumRequests: 8,
+            officialDocumentation: async ({ workspace, dependency, version, reason }) => {
+                const url = officialDocumentationUrl(options.config, workspace, dependency, version);
+                if (!url)
+                    return undefined;
+                return documentation.retrieve({
+                    url,
+                    version,
+                    reason: `Version-matched official API evidence for ${dependency} ${version}: ${reason}`,
+                    offline: options.offline ?? options.config.documentation.mode === "offline",
+                });
+            },
+        });
+        const requestIds = [];
+        let result;
+        let patch;
+        for (;;) {
+            const request = {
+                operation: "patch",
+                model: options.config.provider.model,
+                messages: buildGuidedPatchPrompt({
+                    profile: options.profile,
+                    contract,
+                    manifest,
+                    snapshotHash: baseline.snapshotHash,
+                    workspaces,
+                }),
+                responseSchema: PATCH_SET_SCHEMA_V1,
+                ...(options.provider.capabilities.toolCalling && !options.provider.capabilities.remote ? { tools: [...COMPILER_CONTEXT_TOOLS] } : {}),
+                timeoutMs: Math.min(options.config.budgets.timeoutMs, 60 * 60_000),
+                maxOutputTokens: Math.min(options.config.budgets.maxOutputTokens, 100_000),
+                temperature: 0,
+                signal: options.signal,
+            };
+            const generated = await withProviderRetries(() => generateValidated(options.provider, request, (value) => value, { budget }), { maxRetries: 2, maxElapsedMs: options.config.budgets.timeoutMs, signal: options.signal });
+            result = generated.result;
+            requestIds.push(result.requestId);
+            if (result.finishReason !== "tool_call") {
+                patch = validatePatchSetV1(generated.value, contract);
+                break;
+            }
+            const more = await executor.execute(toolRequestFromOutput(generated.value));
+            if (more.length === 0)
+                throw new ProviderError("schema", "Requested context could not be grounded by project evidence.");
+            candidates.push(...more);
+            manifest = await selectContext({
+                root,
+                projectFingerprint: options.profile.fingerprint,
+                candidates,
+                offline: options.offline ?? options.config.documentation.mode === "offline",
+                secretPolicy: "block",
+                budget: contextBudget(options.config),
+                officialDocumentationHosts: officialDocumentationHosts(options.config),
+            });
+            await store.writeArtifact(runId, "context.json", manifest);
+        }
+        if (!patch || !result)
+            throw new Error("Provider generation completed without a patch artifact.");
+        if (patch.snapshotHash !== baseline.snapshotHash)
+            throw new ProviderError("schema", "Patch snapshot hash does not match the immutable generation snapshot.");
+        assertExternalApisGrounded(patch, workspaces, manifest);
+        const policy = {
+            allowedPaths: contract.scope.allowedPaths,
+            protectedPaths: contract.scope.prohibitedPaths,
+            expectedSnapshotHash: baseline.snapshotHash,
+            allowDeletes: contract.scope.allowedOperations.includes("delete"),
+            allowRenames: contract.scope.allowedOperations.includes("rename"),
+        };
+        await preparePatch(baseline.root, patch, policy);
+        const diff = renderPatchDiff(patch);
+        const providerIdentity = {
+            name: options.provider.name,
+            requestedModel: options.config.provider.model,
+            resolvedModel: result.resolvedModelId,
+            requestIds,
+        };
+        // Certification is resolved exclusively from shipped, immutable evidence
+        // bound to this exact provider/model profile. Programmatic callers cannot
+        // self-attest a provider/model as certified.
+        const certification = certificationFor(options.profile, contract, providerProfileId(providerIdentity.name, providerIdentity.resolvedModel));
+        await store.writeArtifact(runId, "context.json", manifest);
+        await store.writeArtifact(runId, "patch.json", patch);
+        await store.writeArtifact(runId, "diff.json", { diff });
+        await store.writeArtifact(runId, "certification.json", certification);
+        diagnostics.push("A reviewable patch was generated and safety-checked; isolated validation is still required.");
+        if (!certification.certified)
+            diagnostics.push(...certification.reasons);
+        await persistOutcome(store, runId, "INCONCLUSIVE", diagnostics, {
+            contractHash: hashCanonical(contract),
+            contextManifestHash: hashContextManifest(manifest),
+            patchHash: hashCanonical(patch),
+            provider: providerIdentity,
+            usage: usageSummary(budget),
+        });
+        return { runId, status: "INCONCLUSIVE", diagnostics, diff, usage: usageSummary(budget) };
+    }
+    catch (error) {
+        const security = error instanceof ProjectSecretScanError && error.code === "SECRET_DETECTED"
+            || error instanceof ProviderError && error.code === "safety"
+            || error instanceof Error && /secret|credential|path escape|symlink|hardlink/iu.test(error.message);
+        const contextInsufficient = error instanceof DocumentationError
+            || error instanceof ProviderError && error.code === "schema" && /context|ground/iu.test(error.message);
+        const status = security ? "SECURITY_BLOCKED"
+            : contextInsufficient ? "INCONCLUSIVE"
+                : error instanceof ProviderError && ["configuration", "authentication"].includes(error.code) ? "NEEDS_INPUT" : "FAILED";
+        diagnostics.push(error instanceof Error ? error.message : String(error));
+        await persistOutcome(store, runId, status, diagnostics).catch(() => undefined);
+        const exitCode = security ? 4
+            : error instanceof ProjectSecretScanError && error.code === "PARTIAL_SCAN" ? 6
+                : error instanceof DocumentationError || error instanceof ProviderError ? 5
+                    : status === "INCONCLUSIVE" || status === "NEEDS_INPUT" ? 3 : 2;
+        return { runId, status, diagnostics, exitCode };
+    }
+    finally {
+        if (baseline)
+            await disposeWorkspaceSnapshot(baseline).catch(() => undefined);
+    }
+}
+function sandboxImage(profile, override) {
+    if (override)
+        return override;
+    const ecosystems = new Set(profile.workspaces.map((workspace) => workspace.ecosystem));
+    if ([...ecosystems].some((name) => name === "rust"))
+        return ecosystems.size === 1 ? "rust:1.85-bookworm" : undefined;
+    if ([...ecosystems].some((name) => name === "fastapi"))
+        return ecosystems.size === 1 ? "python:3.13-bookworm" : undefined;
+    return "node:24-bookworm";
+}
+async function sandboxBinary(config, override) {
+    if (override)
+        return override;
+    if (config.sandbox.engine === "docker")
+        return "docker";
+    if (config.sandbox.engine === "podman")
+        return "podman";
+    if (await strongSandboxAvailable("docker"))
+        return "docker";
+    if (await strongSandboxAvailable("podman"))
+        return "podman";
+    return "docker";
+}
+const REPAIR_FROZEN_PATH = /(?:^|\/)(?:package\.json|Cargo\.toml|Cargo\.lock|pyproject\.toml|setup\.(?:py|cfg)|environment\.ya?ml|requirements(?:-[^/]*)?\.(?:txt|in)|poetry\.lock|uv\.lock|Pipfile(?:\.lock)?|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|nest-cli\.json|nx\.json|turbo\.json|angular\.json|tsconfig(?:\.[^/]*)?\.json|[^/]+\.config\.[^/]+|\.github\/workflows|\.cargo\/config(?:\.toml)?|__tests__|tests?|specs?|e2e|integration|fixtures?|snapshots?|migrations?|generated)(?:\/|$)|\.(?:test|spec)\.[^/]+$|\.snap$/iu;
+const INLINE_TEST_CONTENT = /#\s*\[\s*cfg\s*\(\s*test\s*\)\s*\]|\b(?:describe|it|test)\s*\(|@pytest\b|\bunittest\.|\bTestCase\b|\bassert(?:_eq|_ne)?!\s*\(/iu;
+function patchOperationIdentity(operation) {
+    return operation.kind === "rename"
+        ? `rename:${operation.from}->${operation.path}`
+        : `${operation.kind}:${operation.path}`;
+}
+function repairFrozenOperation(operation) {
+    const content = operation.kind === "create"
+        ? operation.content
+        : operation.kind === "edit"
+            ? `${operation.oldText}\n${operation.newText}`
+            : "";
+    return REPAIR_FROZEN_PATH.test(operation.path)
+        || operation.kind === "rename" && REPAIR_FROZEN_PATH.test(operation.from)
+        || INLINE_TEST_CONTENT.test(content);
+}
+/** A repair may correct implementation text, but may not redesign the patch. */
+function assertRepairPatchConstraints(original, repaired) {
+    if (repaired.contractHash !== original.contractHash || repaired.snapshotHash !== original.snapshotHash) {
+        throw new ProviderError("safety", "Repair attempted to change immutable contract or snapshot provenance.");
+    }
+    const originalIdentities = original.operations.map(patchOperationIdentity).sort();
+    const repairedIdentities = repaired.operations.map(patchOperationIdentity).sort();
+    if (canonicalJson(originalIdentities) !== canonicalJson(repairedIdentities)) {
+        throw new ProviderError("safety", "Repair attempted to add, remove, rename, or change the kind of a patch path.");
+    }
+    if (canonicalJson([...original.requirementIds].sort()) !== canonicalJson([...repaired.requirementIds].sort())) {
+        throw new ProviderError("safety", "Repair attempted to change requirement coverage.");
+    }
+    const repairedTests = new Set(repaired.proposedTests);
+    if (original.proposedTests.some((test) => !repairedTests.has(test))) {
+        throw new ProviderError("safety", "Repair attempted to remove a proposed validation or test obligation.");
+    }
+    const originalByIdentity = new Map(original.operations.map((operation) => [patchOperationIdentity(operation), operation]));
+    for (const operation of repaired.operations) {
+        const previous = originalByIdentity.get(patchOperationIdentity(operation));
+        if (!repairFrozenOperation(operation) && (previous === undefined || !repairFrozenOperation(previous)))
+            continue;
+        if (previous === undefined || canonicalJson(previous) !== canonicalJson(operation)) {
+            throw new ProviderError("safety", "Repair attempted to modify a dependency, lockfile, test, or validation-configuration operation.");
+        }
+    }
+}
+function cleanValidationResult(result) {
+    return result.status === "passed"
+        && result.exitCode === 0
+        && !result.timedOut
+        && !result.flaky
+        && !result.outputTruncated
+        && !result.stderr.startsWith("SECURITY_BLOCKED:");
+}
+/** Repairs are allowed only for deterministic candidate regressions. */
+function repairableValidationFailure(report, plan) {
+    if (report.status !== "failed" || report.sandbox !== "strong")
+        return false;
+    if (report.diagnostics.some((diagnostic) => diagnostic.startsWith("SECURITY_BLOCKED:")))
+        return false;
+    if (report.baseline.length !== plan.commands.length || report.candidate.length !== plan.commands.length)
+        return false;
+    if (!report.baseline.every(cleanValidationResult))
+        return false;
+    const required = new Set(plan.commands.filter((command) => command.required).map((command) => command.id));
+    const requiredFailures = report.candidate.filter((result) => required.has(result.id) && result.status !== "passed");
+    if (requiredFailures.length === 0)
+        return false;
+    if (report.candidate.some((result) => result.status === "error" || result.status === "skipped"
+        || result.timedOut || result.flaky || result.outputTruncated
+        || result.signal !== null || [126, 127, 137, 139, 143].includes(result.exitCode ?? -1)
+        || /command not found|executable file not found|ENOSPC|out of memory|(?:^|\s)killed(?:\s|$)|toolchain .*not installed/iu.test(`${result.stdout}\n${result.stderr}`)
+        || result.stderr.startsWith("SECURITY_BLOCKED:")))
+        return false;
+    return requiredFailures.every((result) => result.status === "failed" && result.exitCode !== null);
+}
+function repairDiagnosticPayload(report, plan) {
+    const required = new Set(plan.commands.filter((command) => command.required).map((command) => command.id));
+    const failures = report.candidate
+        .filter((result) => required.has(result.id) && result.status === "failed")
+        .map((result) => ({
+        id: result.id,
+        exitCode: result.exitCode,
+        signal: result.signal,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    }));
+    const payload = canonicalJson({
+        status: report.status,
+        diagnostics: report.diagnostics,
+        failures,
+    });
+    if (Buffer.byteLength(payload, "utf8") > 1024 * 1024) {
+        throw new ProviderError("budget", "Validation diagnostics exceed the bounded repair context; no diagnostic was silently truncated.");
+    }
+    return payload;
+}
+function validateRepairCheckpoint(value, expected) {
+    const record = exactRecord(value, "repairCheckpoint", [
+        "schemaVersion", "contractHash", "contextManifestHash", "snapshotHash", "validationPlanHash",
+        "attempts", "provider", "usage", "updatedAt",
+    ]);
+    if (record.schemaVersion !== 1
+        || record.contractHash !== expected.contractHash
+        || record.contextManifestHash !== expected.contextManifestHash
+        || record.snapshotHash !== expected.snapshotHash
+        || record.validationPlanHash !== expected.validationPlanHash
+        || typeof record.updatedAt !== "string" || !Number.isFinite(Date.parse(record.updatedAt))) {
+        throw new ProviderError("safety", "Repair checkpoint provenance is invalid.");
+    }
+    const provider = exactRecord(record.provider, "repairCheckpoint.provider", ["name", "requestedModel", "resolvedModel", "requestIds"]);
+    if (typeof provider.name !== "string" || typeof provider.requestedModel !== "string" || typeof provider.resolvedModel !== "string"
+        || !Array.isArray(provider.requestIds) || provider.requestIds.length === 0
+        || provider.requestIds.some((id) => typeof id !== "string" || id.length === 0)
+        || new Set(provider.requestIds).size !== provider.requestIds.length
+        || !expected.record.provider
+        || provider.name !== expected.record.provider.name
+        || provider.requestedModel !== expected.record.provider.requestedModel
+        || provider.resolvedModel !== expected.record.provider.resolvedModel
+        || expected.record.provider.requestIds.some((id) => !provider.requestIds.includes(id))) {
+        throw new ProviderError("safety", "Repair checkpoint provider identity is invalid.");
+    }
+    const usage = exactRecord(record.usage, "repairCheckpoint.usage", [
+        "inputTokens", "outputTokens", "totalTokens", "requests", "repairs", "costUsd",
+    ]);
+    for (const key of ["inputTokens", "outputTokens", "totalTokens", "requests", "repairs"]) {
+        if (!Number.isSafeInteger(usage[key]) || usage[key] < 0)
+            throw new ProviderError("safety", "Repair checkpoint usage is invalid.");
+    }
+    if (usage.repairs > 2 || usage.totalTokens !== usage.inputTokens + usage.outputTokens
+        || typeof usage.costUsd !== "number" || !Number.isFinite(usage.costUsd) || usage.costUsd < 0) {
+        throw new ProviderError("safety", "Repair checkpoint usage totals are invalid.");
+    }
+    const checkedAttempts = validateValidationReportV1({
+        schemaVersion: 1,
+        status: "unvalidated",
+        sandbox: "none",
+        baseline: [],
+        candidate: [],
+        repairs: record.attempts,
+        manualChecks: [],
+        diagnostics: [],
+        startedAt: record.updatedAt,
+        finishedAt: record.updatedAt,
+    }).repairs;
+    if (checkedAttempts.length !== usage.repairs) {
+        throw new ProviderError("safety", "Repair checkpoint attempts do not match its cumulative budget usage.");
+    }
+    const prior = expected.record.usage;
+    if (prior && (usage.inputTokens < prior.inputTokens
+        || usage.outputTokens < prior.outputTokens
+        || usage.requests < prior.requests
+        || usage.repairs < (prior.repairs ?? 0)
+        || usage.costUsd < (prior.costUsd ?? 0))) {
+        throw new ProviderError("safety", "Repair checkpoint usage regresses persisted cumulative usage.");
+    }
+    return {
+        schemaVersion: 1,
+        contractHash: record.contractHash,
+        contextManifestHash: record.contextManifestHash,
+        snapshotHash: record.snapshotHash,
+        validationPlanHash: record.validationPlanHash,
+        attempts: checkedAttempts.map((attempt) => ({ ...attempt, diagnostics: [...attempt.diagnostics] })),
+        provider: {
+            name: provider.name,
+            requestedModel: provider.requestedModel,
+            resolvedModel: provider.resolvedModel,
+            requestIds: [...provider.requestIds],
+        },
+        usage: {
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            requests: usage.requests,
+            repairs: usage.repairs,
+            costUsd: usage.costUsd,
+        },
+        updatedAt: record.updatedAt,
+    };
+}
+async function writeRepairCheckpoint(store, runId, provenance, attempts, provider, budget) {
+    const usage = usageSummary(budget);
+    await store.writeArtifact(runId, "repair-checkpoint.json", {
+        schemaVersion: 1,
+        ...provenance,
+        attempts: attempts.map((attempt) => ({ ...attempt, diagnostics: [...attempt.diagnostics] })),
+        provider: { ...provider, requestIds: [...provider.requestIds] },
+        usage: { ...usage, repairs: budget.usage.repairs },
+        updatedAt: now(),
+    });
+}
+function hydratedRepairBudget(config, record, persisted = record.usage) {
+    const elapsed = Math.max(0, Date.now() - Date.parse(record.createdAt));
+    const remainingElapsed = config.budgets.timeoutMs - elapsed;
+    if (!Number.isFinite(remainingElapsed) || remainingElapsed < 1) {
+        throw new ProviderError("budget", "Run elapsed-time budget expired before repair.");
+    }
+    const budget = providerBudget(config, Math.floor(remainingElapsed));
+    if (!persisted)
+        return budget;
+    if (!Number.isSafeInteger(persisted.requests) || persisted.requests < 0
+        || persisted.requests === 0 && (persisted.inputTokens !== 0 || persisted.outputTokens !== 0)) {
+        throw new ProviderError("schema", "Persisted provider usage cannot initialize a repair budget.");
+    }
+    for (let index = 0; index < persisted.requests; index += 1) {
+        const final = index === persisted.requests - 1;
+        budget.recordUsage({
+            inputTokens: final ? persisted.inputTokens : 0,
+            outputTokens: final ? persisted.outputTokens : 0,
+            ...(final && persisted.costUsd !== undefined ? { costUsd: persisted.costUsd } : {}),
+        });
+    }
+    for (let index = 0; index < (persisted.repairs ?? 0); index += 1)
+        budget.recordRepair();
+    return budget;
+}
+function repairProviderIdentity(provider, config, record) {
+    const identity = record.provider;
+    if (!identity)
+        throw new ProviderError("configuration", "Run has no persisted provider identity for repair.");
+    if (provider.name !== identity.name || config.provider.model !== identity.requestedModel) {
+        throw new ProviderError("configuration", "Repair provider or requested model differs from the generation run.");
+    }
+    return identity;
+}
+async function assertStoredRepairInputsUnchanged(store, runId, contractHash, contextManifestHash, snapshotHash, planHash) {
+    const [contractRaw, contextRaw, patchRaw, planRaw] = await Promise.all([
+        store.readArtifact(runId, "contract.json"),
+        store.readArtifact(runId, "context.json"),
+        store.readArtifact(runId, "patch.json"),
+        store.readArtifact(runId, "validation-plan.json"),
+    ]);
+    const context = validateContextManifestV1(contextRaw);
+    if (hashCanonical(contractRaw) !== contractHash
+        || hashContextManifest(context) !== contextManifestHash
+        || patchRaw.snapshotHash !== snapshotHash
+        || hashCanonical(planRaw) !== planHash) {
+        throw new ProviderError("safety", "Persisted contract, context, snapshot, or validation plan changed during repair.");
+    }
+    return context;
+}
+async function validateStoredRunLocked(options) {
+    const store = options.store;
+    const record = await store.read(options.runId);
+    const diagnostics = [];
+    const root = resolve(record.root);
+    let baseline;
+    let validationBaseline;
+    let candidate;
+    try {
+        const [storedProfile, storedConfigRaw, contractRaw, contextRaw, patchRaw, planRaw, certificationRaw] = await Promise.all([
+            store.readArtifact(options.runId, "profile.json"),
+            store.readArtifact(options.runId, "run-config.json"),
+            store.readArtifact(options.runId, "contract.json"),
+            store.readArtifact(options.runId, "context.json"),
+            store.readArtifact(options.runId, "patch.json"),
+            store.readArtifact(options.runId, "validation-plan.json"),
+            store.readArtifact(options.runId, "certification.json"),
+        ]);
+        const storedConfig = validateConfig(storedConfigRaw);
+        const contract = validateChangeContractV1(contractRaw);
+        const context = validateContextManifestV1(contextRaw);
+        const originalPatch = validatePatchSetV1(patchRaw, contract);
+        let patch = originalPatch;
+        const plan = validateValidationPlanV1(planRaw);
+        const certification = validateCertificationArtifact(certificationRaw);
+        const contractHash = hashCanonical(contract);
+        const contextManifestHash = record.contextManifestHash;
+        const validationPlanHash = hashCanonical(plan);
+        if (record.contractHash !== contractHash || record.patchHash !== hashCanonical(originalPatch)
+            || contextManifestHash === undefined || contextManifestHash !== hashContextManifest(context)) {
+            throw new ProviderError("safety", "Stored run provenance does not match its contract, context, or patch artifacts.");
+        }
+        const currentProfile = await analyzeProject(root);
+        if (currentProfile.fingerprint !== storedProfile.fingerprint || currentProfile.fingerprint !== plan.profileFingerprint) {
+            throw new Error("Project analysis changed after generation; regenerate the patch against the current profile.");
+        }
+        baseline = await createWorkspaceSnapshot(root, { excludeNames: [".venv", "venv", "target", ".next", "coverage"] });
+        if (baseline.snapshotHash !== patch.snapshotHash)
+            throw new Error("Workspace snapshot changed after generation; validation is stale.");
+        const policy = {
+            allowedPaths: contract.scope.allowedPaths,
+            protectedPaths: contract.scope.prohibitedPaths,
+            expectedSnapshotHash: baseline.snapshotHash,
+            allowDeletes: contract.scope.allowedOperations.includes("delete"),
+            allowRenames: contract.scope.allowedOperations.includes("rename"),
+        };
+        const image = sandboxImage(currentProfile, options.sandboxImage);
+        const validationRunner = options.validationRunner ?? validateBaselineAndCandidate;
+        const executionPlan = options.manualChecksPassed ? { ...plan, manualChecks: [] } : plan;
+        const dockerBinary = image
+            ? await sandboxBinary(storedConfig, options.dockerBinary)
+            : undefined;
+        const repairAttempts = [];
+        const checkpointRaw = await store.readArtifactOptional(options.runId, "repair-checkpoint.json");
+        const checkpoint = checkpointRaw === undefined ? undefined : validateRepairCheckpoint(checkpointRaw, {
+            contractHash,
+            contextManifestHash,
+            snapshotHash: baseline.snapshotHash,
+            validationPlanHash,
+            record,
+        });
+        const persistedRepairCount = checkpoint?.usage.repairs ?? record.usage?.repairs ?? 0;
+        if (!Number.isInteger(persistedRepairCount) || persistedRepairCount < 0 || persistedRepairCount > 2) {
+            throw new ProviderError("schema", "Persisted repair usage is invalid.");
+        }
+        if (checkpoint) {
+            repairAttempts.push(...checkpoint.attempts.map((attempt) => ({
+                ...attempt,
+                diagnostics: [...attempt.diagnostics],
+            })));
+        }
+        else if (persistedRepairCount > 0) {
+            const previousReport = validateValidationReportV1(await store.readArtifact(options.runId, "validation-report.json"));
+            if (record.validationReportHash !== hashCanonical(previousReport)
+                || previousReport.repairs.length !== persistedRepairCount) {
+                throw new ProviderError("safety", "Persisted repair count does not match the prior validation provenance.");
+            }
+            repairAttempts.push(...previousReport.repairs.map((attempt) => ({
+                ...attempt,
+                diagnostics: [...attempt.diagnostics],
+            })));
+        }
+        const repairResults = [];
+        const validateFreshCandidate = async () => {
+            if (candidate) {
+                await disposeWorkspaceSnapshot(candidate);
+                candidate = undefined;
+            }
+            if (validationBaseline) {
+                await disposeWorkspaceSnapshot(validationBaseline);
+                validationBaseline = undefined;
+            }
+            await preparePatch(baseline.root, patch, policy);
+            // Validators execute arbitrary project code against disposable copies.
+            // The content-addressed master snapshot is never mounted or mutated.
+            validationBaseline = await cloneWorkspaceSnapshot(baseline);
+            candidate = await cloneWorkspaceSnapshot(baseline);
+            await applyPatchAtomic(candidate.root, patch, policy);
+            let next;
+            if (!image) {
+                const timestamp = now();
+                next = {
+                    schemaVersion: 1,
+                    status: "unvalidated",
+                    sandbox: "none",
+                    baseline: [],
+                    candidate: [],
+                    repairs: [],
+                    manualChecks: plan.manualChecks.map((description) => ({ description, status: "pending" })),
+                    diagnostics: ["Mixed-ecosystem validation requires an explicitly provisioned, trusted multi-toolchain image."],
+                    startedAt: timestamp,
+                    finishedAt: timestamp,
+                };
+            }
+            else {
+                next = await validationRunner(executionPlan, {
+                    baselineRoot: validationBaseline.root,
+                    candidateRoot: candidate.root,
+                    image,
+                    dockerBinary,
+                    retryFailedOnce: true,
+                });
+                if (options.manualChecksPassed) {
+                    next.manualChecks = plan.manualChecks.map((description) => ({
+                        description,
+                        status: "passed",
+                        evidence: "Explicit operator attestation supplied to validate.",
+                    }));
+                }
+            }
+            return validateValidationReportV1({
+                ...next,
+                repairs: repairAttempts.map((attempt) => ({ ...attempt, diagnostics: [...attempt.diagnostics] })),
+            });
+        };
+        let report = await validateFreshCandidate();
+        await store.writeArtifact(options.runId, "validation-report-attempt-0.json", report);
+        let budget;
+        let providerIdentity;
+        let repairFailureStatus;
+        if (repairableValidationFailure(report, plan)
+            && (options.provider !== undefined || options.config !== undefined)) {
+            if (options.provider === undefined || options.config === undefined) {
+                throw new ProviderError("configuration", "Guided repair requires both the original provider and immutable run configuration.");
+            }
+            if (canonicalJson(options.config) !== canonicalJson(storedConfig)) {
+                throw new ProviderError("configuration", "Repair configuration differs from the configuration persisted during generation.");
+            }
+            const generatedIdentity = repairProviderIdentity(options.provider, options.config, record);
+            providerIdentity = checkpoint
+                ? { ...checkpoint.provider, requestIds: [...checkpoint.provider.requestIds] }
+                : { ...generatedIdentity, requestIds: [...generatedIdentity.requestIds] };
+            budget = hydratedRepairBudget(storedConfig, record, checkpoint?.usage);
+        }
+        const maximumRepairs = Math.min(2, storedConfig.budgets.maxRepairs);
+        const checkpointProvenance = {
+            contractHash,
+            contextManifestHash,
+            snapshotHash: baseline.snapshotHash,
+            validationPlanHash,
+        };
+        while (options.provider && budget && providerIdentity
+            && repairAttempts.length < maximumRepairs
+            && repairableValidationFailure(report, plan)) {
+            const attempt = repairAttempts.length + 1;
+            const promptingDiagnostics = report.diagnostics.length > 0
+                ? [...report.diagnostics]
+                : ["Candidate validation failed a required command while the baseline remained healthy."];
+            let repairRequestId;
+            try {
+                const diagnosticPayload = repairDiagnosticPayload(report, plan);
+                budget.recordRepair();
+                const provenance = { attempt, diagnostics: promptingDiagnostics };
+                repairAttempts.push(provenance);
+                await writeRepairCheckpoint(store, options.runId, checkpointProvenance, repairAttempts, providerIdentity, budget);
+                const context = await assertStoredRepairInputsUnchanged(store, options.runId, contractHash, contextManifestHash, baseline.snapshotHash, validationPlanHash);
+                const generated = await withProviderRetries(() => generateValidated(options.provider, {
+                    operation: "repair",
+                    model: providerIdentity.requestedModel,
+                    messages: buildGuidedRepairPrompt({
+                        contract,
+                        patch,
+                        validationPlan: plan,
+                        diagnosticPayload,
+                        attempt,
+                    }),
+                    responseSchema: PATCH_SET_SCHEMA_V1,
+                    timeoutMs: Math.min(storedConfig.budgets.timeoutMs, 60 * 60_000),
+                    maxOutputTokens: Math.min(storedConfig.budgets.maxOutputTokens, 100_000),
+                    temperature: 0,
+                    signal: options.signal,
+                }, (value) => value, {
+                    budget,
+                    onBeforeRequest: () => writeRepairCheckpoint(store, options.runId, checkpointProvenance, repairAttempts, providerIdentity, budget),
+                }), {
+                    maxRetries: 2,
+                    maxElapsedMs: Math.max(1, budget.remainingElapsedMs),
+                    signal: options.signal,
+                    onRetry: (_retry, error) => {
+                        const requestId = error.options.requestId;
+                        if (requestId && !providerIdentity.requestIds.includes(requestId))
+                            providerIdentity.requestIds.push(requestId);
+                    },
+                });
+                repairRequestId = generated.result.requestId;
+                const reusedRequestId = providerIdentity.requestIds.includes(generated.result.requestId);
+                if (!reusedRequestId)
+                    providerIdentity.requestIds.push(generated.result.requestId);
+                // Persist cumulative request/token usage and request identity before
+                // interpreting output, so a crash cannot reset the repair allowance.
+                await writeRepairCheckpoint(store, options.runId, checkpointProvenance, repairAttempts, providerIdentity, budget);
+                if (generated.result.resolvedModelId !== providerIdentity.resolvedModel) {
+                    throw new ProviderError("schema", "Repair resolved to a different model identity than generation.", {
+                        requestId: generated.result.requestId,
+                    });
+                }
+                if (reusedRequestId) {
+                    throw new ProviderError("schema", "Repair provider reused a request id; provenance would be ambiguous.");
+                }
+                const repaired = validatePatchSetV1(generated.value, contract);
+                assertRepairPatchConstraints(originalPatch, repaired);
+                if (repaired.snapshotHash !== baseline.snapshotHash) {
+                    throw new ProviderError("safety", "Repair patch changed the immutable workspace snapshot hash.");
+                }
+                assertExternalApisGrounded(repaired, targetWorkspaces(currentProfile, contract), context);
+                await preparePatch(baseline.root, repaired, policy);
+                provenance.patchHash = hashCanonical(repaired);
+                await store.writeArtifact(options.runId, `patch-repair-${attempt}.json`, repaired);
+                await store.writeArtifact(options.runId, `diff-repair-${attempt}.json`, { diff: renderPatchDiff(repaired) });
+                const previousPatch = patch;
+                patch = repaired;
+                try {
+                    report = await validateFreshCandidate();
+                }
+                catch (error) {
+                    // Canonical patch.json is not replaced until a complete report exists.
+                    // A crash or unavailable validator therefore remains resumable from
+                    // the last provenance-bound patch rather than leaving mismatched state.
+                    patch = previousPatch;
+                    throw error;
+                }
+                await store.writeArtifact(options.runId, `validation-report-attempt-${attempt}.json`, report);
+                repairResults.push({
+                    attempt,
+                    status: report.status === "validated" ? "validated"
+                        : report.status === "failed" ? "failed" : "inconclusive",
+                    patchHash: provenance.patchHash,
+                    requestId: generated.result.requestId,
+                    diagnostic: `Fresh candidate validation completed with status ${report.status}.`,
+                });
+                await writeRepairCheckpoint(store, options.runId, checkpointProvenance, repairAttempts, providerIdentity, budget);
+            }
+            catch (error) {
+                const requestId = error instanceof ProviderError ? error.options.requestId : undefined;
+                if (requestId && !providerIdentity.requestIds.includes(requestId))
+                    providerIdentity.requestIds.push(requestId);
+                const rejection = `Repair rejected: ${error instanceof Error ? error.message : String(error)}`;
+                const existingAttempt = repairAttempts.find((item) => item.attempt === attempt);
+                if (existingAttempt)
+                    existingAttempt.diagnostics.push(rejection);
+                else
+                    repairAttempts.push({ attempt, diagnostics: [...promptingDiagnostics, rejection] });
+                repairResults.push({
+                    attempt,
+                    status: "rejected",
+                    ...(existingAttempt?.patchHash ? { patchHash: existingAttempt.patchHash } : {}),
+                    ...(repairRequestId ? { requestId: repairRequestId } : {}),
+                    diagnostic: rejection,
+                });
+                report = { ...report, repairs: repairAttempts.map((item) => ({ ...item, diagnostics: [...item.diagnostics] })) };
+                diagnostics.push(error instanceof Error ? error.message : String(error));
+                await writeRepairCheckpoint(store, options.runId, checkpointProvenance, repairAttempts, providerIdentity, budget);
+                repairFailureStatus = error instanceof PatchSafetyError
+                    || error instanceof ProviderError && error.code === "safety"
+                    || error instanceof Error && /out.of.scope|path escape|weaken|dependency|lockfile|validation.configuration/iu.test(error.message)
+                    ? "SECURITY_BLOCKED"
+                    : "FAILED";
+                break;
+            }
+        }
+        if (repairableValidationFailure(report, plan) && repairAttempts.length >= maximumRepairs) {
+            diagnostics.push(`Candidate validation still fails after the bounded ${maximumRepairs}-repair allowance.`);
+        }
+        report = validateValidationReportV1({
+            ...report,
+            repairs: repairAttempts.map((attempt) => ({ ...attempt, diagnostics: [...attempt.diagnostics] })),
+        });
+        await store.writeArtifact(options.runId, "validation-report.json", report);
+        await store.writeArtifact(options.runId, "patch.json", patch);
+        await store.writeArtifact(options.runId, "diff.json", { diff: renderPatchDiff(patch) });
+        const existingRepairProvenance = await store.readArtifactOptional(options.runId, "repair-provenance.json");
+        if (repairResults.length > 0 || existingRepairProvenance === undefined) {
+            await store.writeArtifact(options.runId, "repair-provenance.json", {
+                schemaVersion: 1,
+                contractHash,
+                snapshotHash: baseline.snapshotHash,
+                validationPlanHash,
+                attempts: repairAttempts,
+                results: repairResults,
+                provider: providerIdentity ?? record.provider ?? null,
+                usage: budget?.usage ?? record.usage ?? null,
+            });
+        }
+        const validationSecurityBlock = report.diagnostics.some((diagnostic) => diagnostic.startsWith("SECURITY_BLOCKED:"));
+        const status = repairFailureStatus === "SECURITY_BLOCKED" || validationSecurityBlock ? "SECURITY_BLOCKED"
+            : report.status === "validated" && report.sandbox === "strong" && certification.certified
+                ? "VERIFIED"
+                : repairFailureStatus === "FAILED" || report.status === "failed" ? "FAILED" : "INCONCLUSIVE";
+        diagnostics.push(...report.diagnostics);
+        if (!certification.certified)
+            diagnostics.push(...certification.reasons);
+        if (status === "VERIFIED")
+            diagnostics.push("All immutable validation checks passed in a strong sandbox for a certified profile/model combination.");
+        await persistOutcome(store, options.runId, status, diagnostics, {
+            patchHash: hashCanonical(patch),
+            validationReportHash: hashCanonical(report),
+            ...(providerIdentity ? { provider: providerIdentity } : {}),
+            ...(budget ? { usage: usageSummary(budget) } : {}),
+        });
+        return {
+            runId: options.runId,
+            status,
+            diagnostics,
+            report,
+            diff: renderPatchDiff(patch),
+            ...(budget ? { usage: usageSummary(budget) } : {}),
+        };
+    }
+    catch (error) {
+        diagnostics.push(error instanceof Error ? error.message : String(error));
+        const security = error instanceof PatchSafetyError
+            || error instanceof ProviderError && error.code === "safety";
+        const status = security ? "SECURITY_BLOCKED" : "INCONCLUSIVE";
+        await persistOutcome(store, options.runId, status, diagnostics).catch(() => undefined);
+        return { runId: options.runId, status, diagnostics };
+    }
+    finally {
+        if (candidate)
+            await disposeWorkspaceSnapshot(candidate).catch(() => undefined);
+        if (validationBaseline)
+            await disposeWorkspaceSnapshot(validationBaseline).catch(() => undefined);
+        if (baseline)
+            await disposeWorkspaceSnapshot(baseline).catch(() => undefined);
+    }
+}
+export async function validateStoredRun(options) {
+    const store = options.store ?? new RunStore();
+    return store.exclusive(options.runId, () => validateStoredRunLocked({ ...options, store }));
+}
+async function isGitProject(root) {
+    const marker = await lstat(resolve(root, ".git")).catch(() => undefined);
+    if (!marker)
+        return false;
+    return new Promise((complete) => {
+        const child = spawn("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+            env: { PATH: process.env.PATH ?? "" },
+        });
+        let output = "";
+        child.stdout.on("data", (chunk) => { if (output.length < 1024)
+            output += chunk.toString("utf8"); });
+        child.once("error", () => complete(false));
+        child.once("close", (code) => complete(code === 0 && output.trim() === "true"));
+    });
+}
+function exactRecord(value, label, required, optional = []) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    const record = value;
+    const allowed = new Set([...required, ...optional]);
+    for (const key of required) {
+        if (!Object.hasOwn(record, key))
+            throw new Error(`${label}.${key} is required.`);
+    }
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key))
+            throw new Error(`${label}.${key} is not allowed.`);
+    }
+    return record;
+}
+function boundedArtifactText(value, label) {
+    if (typeof value !== "string" || Buffer.byteLength(value, "utf8") > 10 * 1024 * 1024) {
+        throw new Error(`${label} must be a bounded string.`);
+    }
+    return value;
+}
+function artifactPath(value, label) {
+    if (typeof value !== "string" || normalizePatchPath(value) !== value) {
+        throw new Error(`${label} must be a canonical confined path.`);
+    }
+    return value;
+}
+function artifactHash(value, label, nullable = false) {
+    if (nullable && value === null)
+        return null;
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) {
+        throw new Error(`${label} must be a SHA-256 digest${nullable ? " or null" : ""}.`);
+    }
+    return value;
+}
+function validateRollbackArtifact(value, patch) {
+    const record = exactRecord(value, "rollback", ["schemaVersion", "patchHash", "createdAt", "entries"]);
+    if (record.schemaVersion !== 1 || record.patchHash !== hashCanonical(patch)) {
+        throw new Error("Rollback artifact provenance is invalid.");
+    }
+    if (typeof record.createdAt !== "string" || !Number.isFinite(Date.parse(record.createdAt))) {
+        throw new Error("Rollback artifact timestamp is invalid.");
+    }
+    if (!Array.isArray(record.entries) || record.entries.length !== patch.operations.length || record.entries.length === 0 || record.entries.length > 200) {
+        throw new Error("Rollback entries do not exactly correspond to the stored patch.");
+    }
+    const entries = [];
+    for (let index = 0; index < patch.operations.length; index++) {
+        const operation = patch.operations[index];
+        const raw = exactRecord(record.entries[index], `rollback.entries[${index}]`, ["kind", "path", "before", "afterHash", "mode"], ["from", "after"]);
+        const path = artifactPath(raw.path, `rollback.entries[${index}].path`);
+        const before = boundedArtifactText(raw.before, `rollback.entries[${index}].before`);
+        if (!Number.isInteger(raw.mode) || raw.mode < 0 || raw.mode > 0o777) {
+            throw new Error(`rollback.entries[${index}].mode is invalid.`);
+        }
+        const mode = raw.mode;
+        if (operation.kind === "create") {
+            const afterHash = artifactHash(raw.afterHash, `rollback.entries[${index}].afterHash`);
+            if (raw.kind !== "created" || path !== operation.path || before !== "" || raw.from !== undefined || raw.after !== undefined
+                || afterHash !== sha256Text(operation.content)) {
+                throw new Error(`Rollback create entry ${index} does not match the stored patch.`);
+            }
+            entries.push({ kind: "created", path, before, afterHash, mode });
+            continue;
+        }
+        if (operation.kind === "edit") {
+            const after = boundedArtifactText(raw.after, `rollback.entries[${index}].after`);
+            const afterHash = artifactHash(raw.afterHash, `rollback.entries[${index}].afterHash`);
+            const first = before.indexOf(operation.oldText);
+            const unique = first >= 0 && before.indexOf(operation.oldText, first + 1) < 0;
+            const expectedAfter = unique
+                ? before.slice(0, first) + operation.newText + before.slice(first + operation.oldText.length)
+                : undefined;
+            if (raw.kind !== "edited" || path !== operation.path || raw.from !== undefined
+                || sha256Text(before) !== operation.baseHash || after !== expectedAfter || afterHash !== sha256Text(after)) {
+                throw new Error(`Rollback edit entry ${index} does not match the stored patch.`);
+            }
+            entries.push({ kind: "edited", path, before, after, afterHash, mode });
+            continue;
+        }
+        if (operation.kind === "delete") {
+            const afterHash = artifactHash(raw.afterHash, `rollback.entries[${index}].afterHash`, true);
+            if (raw.kind !== "deleted" || path !== operation.path || raw.from !== undefined || raw.after !== undefined
+                || sha256Text(before) !== operation.baseHash || afterHash !== null) {
+                throw new Error(`Rollback delete entry ${index} does not match the stored patch.`);
+            }
+            entries.push({ kind: "deleted", path, before, afterHash: null, mode });
+            continue;
+        }
+        const from = artifactPath(raw.from, `rollback.entries[${index}].from`);
+        const afterHash = artifactHash(raw.afterHash, `rollback.entries[${index}].afterHash`);
+        if (raw.kind !== "renamed" || path !== operation.path || from !== operation.from || raw.after !== undefined
+            || sha256Text(before) !== operation.baseHash || afterHash !== operation.baseHash) {
+            throw new Error(`Rollback rename entry ${index} does not match the stored patch.`);
+        }
+        entries.push({ kind: "renamed", path, from, before, afterHash, mode });
+    }
+    return { schemaVersion: 1, patchHash: record.patchHash, createdAt: record.createdAt, entries };
+}
+function validateCertificationArtifact(value) {
+    const record = exactRecord(value, "certification", ["schemaVersion", "supportMatrixVersion", "provider", "profileCertified", "certified", "reasons"]);
+    const provider = exactRecord(record.provider, "certification.provider", ["matrixKey", "certified", "reason"]);
+    if (record.schemaVersion !== 1 || record.supportMatrixVersion !== SUPPORT_MATRIX_VERSION
+        || typeof record.profileCertified !== "boolean" || typeof record.certified !== "boolean"
+        || typeof provider.matrixKey !== "string" || typeof provider.certified !== "boolean" || typeof provider.reason !== "string"
+        || !Array.isArray(record.reasons) || record.reasons.some((reason) => typeof reason !== "string" || reason.length === 0)
+        || record.certified !== (record.profileCertified && provider.certified)) {
+        throw new Error("Certification artifact is invalid.");
+    }
+    return record;
+}
+function validateApplyArtifact(value, patchHash) {
+    const record = exactRecord(value, "apply", ["appliedAt", "paths", "patchHash"]);
+    if (record.patchHash !== patchHash || typeof record.appliedAt !== "string" || !Number.isFinite(Date.parse(record.appliedAt))
+        || !Array.isArray(record.paths) || record.paths.some((path) => typeof path !== "string" || path.length === 0)) {
+        throw new Error("Apply artifact provenance is invalid.");
+    }
+}
+export async function applyVerifiedRun(runId, store = new RunStore()) {
+    const initialRecord = await store.read(runId);
+    if (initialRecord.status !== "VERIFIED")
+        return { runId, status: initialRecord.status, diagnostics: ["Automatic apply requires a VERIFIED run."] };
+    if (!(await isGitProject(initialRecord.root)))
+        return { runId, status: "INCONCLUSIVE", diagnostics: ["Automatic apply is disabled for non-Git projects because no verified rollback backend is available."] };
+    try {
+        const result = await store.exclusive(runId, async () => {
+            const record = await store.read(runId);
+            if (record.status !== "VERIFIED")
+                throw new Error("Run status changed before apply; automatic application was blocked.");
+            const contract = validateChangeContractV1(await store.readArtifact(runId, "contract.json"));
+            const patch = validatePatchSetV1(await store.readArtifact(runId, "patch.json"), contract);
+            const context = validateContextManifestV1(await store.readArtifact(runId, "context.json"));
+            const validationReport = validateValidationReportV1(await store.readArtifact(runId, "validation-report.json"));
+            const certification = validateCertificationArtifact(await store.readArtifact(runId, "certification.json"));
+            if (record.contractHash !== hashCanonical(contract) || record.patchHash !== hashCanonical(patch))
+                throw new Error("Stored contract or patch provenance changed after validation.");
+            if (record.contextManifestHash !== hashContextManifest(context))
+                throw new Error("Stored context provenance changed after validation.");
+            if (record.validationReportHash !== hashCanonical(validationReport))
+                throw new Error("Stored validation report provenance changed after validation.");
+            if (validationReport.status !== "validated" || validationReport.sandbox !== "strong" || !certification.certified) {
+                throw new Error("Apply requires a validated strong-sandbox report and shipped certification evidence.");
+            }
+            const policy = {
+                allowedPaths: contract.scope.allowedPaths,
+                protectedPaths: contract.scope.prohibitedPaths,
+                allowDeletes: contract.scope.allowedOperations.includes("delete"),
+                allowRenames: contract.scope.allowedOperations.includes("rename"),
+            };
+            const prepared = await preparePatch(record.root, patch, policy);
+            const rollback = {
+                schemaVersion: 1,
+                patchHash: hashCanonical(patch),
+                createdAt: now(),
+                entries: prepared.operations.map((operation) => {
+                    if (operation.kind === "create")
+                        return { kind: "created", path: operation.path, before: "", afterHash: sha256Text(operation.content), mode: operation.mode };
+                    if (operation.kind === "edit")
+                        return { kind: "edited", path: operation.path, before: operation.before, after: operation.after, afterHash: sha256Text(operation.after), mode: operation.mode };
+                    if (operation.kind === "delete")
+                        return { kind: "deleted", path: operation.path, before: operation.before, afterHash: null, mode: operation.mode };
+                    return { kind: "renamed", path: operation.path, from: operation.from, before: operation.before, afterHash: sha256Text(operation.before), mode: operation.mode };
+                }),
+            };
+            await store.writeArtifact(runId, "rollback.json", rollback);
+            const applied = await applyPatchAtomic(record.root, patch, policy);
+            await store.writeArtifact(runId, "apply.json", { appliedAt: now(), paths: applied.applied, patchHash: applied.patchHash });
+            return applied;
+        });
+        const diagnostics = [`Applied ${result.applied.length} structured operation(s) atomically after exact base-hash checks.`];
+        return { runId, status: "VERIFIED", diagnostics };
+    }
+    catch (error) {
+        return { runId, status: "INCONCLUSIVE", diagnostics: [error instanceof Error ? error.message : String(error)] };
+    }
+}
+export async function rollbackAppliedRun(runId, store = new RunStore()) {
+    try {
+        const restored = await store.exclusive(runId, async () => {
+            const record = await store.read(runId);
+            const contract = validateChangeContractV1(await store.readArtifact(runId, "contract.json"));
+            const patch = validatePatchSetV1(await store.readArtifact(runId, "patch.json"), contract);
+            const patchHash = hashCanonical(patch);
+            if (record.patchHash !== patchHash)
+                throw new Error("Stored patch provenance changed before rollback.");
+            validateApplyArtifact(await store.readArtifact(runId, "apply.json"), patchHash);
+            const artifact = validateRollbackArtifact(await store.readArtifact(runId, "rollback.json"), patch);
+            const operations = [];
+            for (const entry of [...artifact.entries].reverse()) {
+                if (entry.kind === "created") {
+                    operations.push({ kind: "delete", path: entry.path, baseHash: entry.afterHash });
+                }
+                else if (entry.kind === "edited") {
+                    operations.push({ kind: "edit", path: entry.path, baseHash: entry.afterHash, oldText: entry.after, newText: entry.before });
+                }
+                else if (entry.kind === "deleted") {
+                    operations.push({ kind: "create", path: entry.path, content: entry.before });
+                }
+                else {
+                    if (!entry.from)
+                        throw new Error("Rollback rename source is missing.");
+                    operations.push({ kind: "rename", from: entry.path, path: entry.from, baseHash: entry.afterHash });
+                }
+            }
+            const inverse = {
+                schemaVersion: 1,
+                contractHash: "0".repeat(64),
+                snapshotHash: "0".repeat(64),
+                operations,
+                requirementIds: ["ROLLBACK"],
+                proposedTests: [],
+            };
+            const paths = unique(artifact.entries.flatMap((entry) => [entry.path, ...(entry.from ? [entry.from] : [])]));
+            const result = await applyPatchAtomic(record.root, inverse, { allowedPaths: paths, allowDeletes: true, allowRenames: true });
+            for (const entry of artifact.entries) {
+                if (entry.kind === "created")
+                    continue;
+                const restoredPath = entry.kind === "renamed" ? entry.from : entry.path;
+                await chmod(resolve(record.root, restoredPath), entry.mode);
+            }
+            await store.writeArtifact(runId, "rollback-result.json", { rolledBackAt: now(), paths: result.applied, patchHash: result.patchHash });
+            return result;
+        });
+        return { runId, status: "VERIFIED", diagnostics: [`Rollback restored ${restored.applied.length} operation(s) after exact post-apply hash checks.`] };
+    }
+    catch (error) {
+        return { runId, status: "INCONCLUSIVE", diagnostics: [error instanceof Error ? error.message : String(error)] };
+    }
+}
+export function rootRelative(root, path) {
+    const value = relative(resolve(root), resolve(path));
+    if (value === ".." || value.startsWith(`..${sep}`))
+        throw new Error("Path escapes root.");
+    return value.split(sep).join("/") || ".";
+}
+//# sourceMappingURL=workflow.js.map