@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.41da3780c451

package/dist/session/pre-publication-validation.js

@@ -0,0 +1,661 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { attemptDatabaseCapabilityEnvironment, attemptDatabaseCapabilitySecrets, } from "../runtime/attempt-database-broker.js";
+import { assertHostDatabaseCapabilityBoundary } from "../runtime/host-database-capability-boundary.js";
+import { nativeTestPostgresFallbackEnvironment, parseNativeTestPostgresFallback, } from "../runtime/native-test-postgres-fallback.js";
+import { hostRuntimeLegacyTestPostgresEnvironment, hostRuntimeTestPostgresAdminEnvironment, } from "../runtime/host-runtime-contract.js";
+import { redactText } from "../shared/redaction/redaction.js";
+import { findUnreferencedNewExports } from "./unreferenced-exports.js";
+import { ForgeFailureError, sanitizeFailureError, } from "./session.types.js";
+const execFileAsync = promisify(execFile);
+const contractRelativePath = ".forge/validation/ci-parity.v1.json";
+const requiredCheckIds = new Set([
+    "file-size-inventory",
+    "owned-suite-registration",
+    "dotnet-build-and-unit",
+    "openapi-and-generated-types",
+    "client",
+    "bridge",
+    "playwright-e2e",
+    "github-provider-policy",
+]);
+const currentApprovedContractDigest = "378c767c7977c850140ffb19d69db41da62d0187c37a33828d6cda8803a61c83";
+// Comment repair ran the whole ApiComponent and Orchestration tiers under this contract.
+// Story branches cut before the affected-tests contract still carry it.
+const wholeTierCommentRepairContractDigest = "024de3648c907db9c0eab13def9a4f91e81148433e0a2ba7f44776446421054a";
+// Contracts that declare the comment-repair-dotnet-regression check.
+const commentRepairRegressionContractDigests = new Set([
+    currentApprovedContractDigest,
+    wholeTierCommentRepairContractDigest,
+]);
+const compatibleApprovedContractDigests = new Set([
+    wholeTierCommentRepairContractDigest,
+    // Preserve dispatches pinned before comment repair gained all .NET regression tiers.
+    "c0014ce6abc0e0b2e66dd2bcf6cb14c47d28506444c73f87d1b76b3d1c06027b",
+    // The contract immediately before Contract and Infrastructure tiers joined pre-publication parity.
+    "06d1ca5ed48614298ae53d044d725109fe3a316a88381d361ef704681e208bbd",
+    // The Docker-prerequisite contract immediately before native PostgreSQL QA isolation.
+    "02bc1eb622fce173b00d14e15930c841f99678500858da588ec37fe21a7bec5c",
+    // The contract used by Stories prepared before prerequisite readiness was made explicit.
+    "0e8cfb2b1c1ab52bea1475dabed95aa5a2977bdd3c8500a6895632316dba0de5",
+]);
+const approvedContractDigests = new Set([
+    currentApprovedContractDigest,
+    ...compatibleApprovedContractDigests,
+]);
+const ansiColorSequence = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "gu");
+export class PrePublicationValidationError extends ForgeFailureError {
+    checkId;
+    exitCode;
+    command;
+    args;
+    detail;
+    code = "prepublication_validation_failed";
+    constructor(checkId, exitCode, command, args, detail) {
+        super("prepublication_validation_failed", `prepublication_validation_failed: ${checkId} exited ${exitCode}${detail ? `: ${detail}` : ""}`, "bridge");
+        this.checkId = checkId;
+        this.exitCode = exitCode;
+        this.command = command;
+        this.args = args;
+        this.detail = detail;
+        this.name = "PrePublicationValidationError";
+    }
+}
+export class PrePublicationInfrastructureError extends ForgeFailureError {
+    checkId;
+    exitCode;
+    command;
+    args;
+    detail;
+    code = "prepublication_infrastructure_failed";
+    constructor(checkId, exitCode, command, args, detail) {
+        super("prepublication_infrastructure_failed", `prepublication_infrastructure_failed: ${checkId} exited ${exitCode}${detail ? `: ${detail}` : ""}`, "bridge");
+        this.checkId = checkId;
+        this.exitCode = exitCode;
+        this.command = command;
+        this.args = args;
+        this.detail = detail;
+        this.name = "PrePublicationInfrastructureError";
+    }
+}
+class ProcessPrePublicationCommandRunner {
+    async run(command, args, cwd, signal, environment) {
+        try {
+            const windowsBatch = process.platform === "win32" && (command === "npm" || command === "pnpm");
+            const executable = windowsBatch ? (process.env.ComSpec ?? "cmd.exe") : command;
+            const commandArgs = windowsBatch
+                ? ["/d", "/s", "/c", [`${command}.cmd`, ...args].map(quoteWindowsCommandArgument).join(" ")]
+                : [...args];
+            const result = await execFileAsync(executable, commandArgs, {
+                cwd,
+                encoding: "utf8",
+                maxBuffer: 4 * 1024 * 1024,
+                signal,
+                env: prePublicationChildEnvironment(environment),
+            });
+            return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+        }
+        catch (error) {
+            const failure = error;
+            if (failure.name === "AbortError")
+                throw error;
+            if (failure.code === "ENOENT") {
+                return { exitCode: 127, stderr: `executable_not_found: ${command}` };
+            }
+            return {
+                exitCode: typeof failure.code === "number" ? failure.code : 1,
+                stdout: failure.stdout,
+                stderr: failure.stderr ?? failure.message,
+            };
+        }
+    }
+}
+function quoteWindowsCommandArgument(value) {
+    return /^[A-Za-z0-9_./:@=-]+$/u.test(value) ? value : `"${value.replaceAll('"', '""')}"`;
+}
+function prePublicationChildEnvironment(environment) {
+    const child = {};
+    const privilegedNames = new Set([
+        hostRuntimeTestPostgresAdminEnvironment.toLowerCase(),
+        hostRuntimeLegacyTestPostgresEnvironment.toLowerCase(),
+    ]);
+    for (const [name, value] of Object.entries(process.env)) {
+        if (typeof value === "string" && !privilegedNames.has(name.toLowerCase())) {
+            child[name] = value;
+        }
+    }
+    return { ...child, ...environment };
+}
+export class PrePublicationValidator {
+    commands;
+    dockerEngineProbe;
+    nativeTestPostgresFallback;
+    constructor(commands = new ProcessPrePublicationCommandRunner(), dockerEngineProbe, nativeTestPostgresFallback = () => null) {
+        this.commands = commands;
+        this.dockerEngineProbe = dockerEngineProbe;
+        this.nativeTestPostgresFallback = nativeTestPostgresFallback;
+    }
+    async validate(worktreePath, profile, capabilities, emit, signal, execution) {
+        const checksExports = profile === "implementation" || profile === "comment_repair";
+        const contract = await loadValidationContract(worktreePath);
+        if (contract === null) {
+            await emit?.(validationEvent("prepublication_validation_legacy_contract", "legacy-provider-validation", `This checkout predates ${contractRelativePath}; Bridge preserved legacy provider validation without source mutation.`));
+            if (checksExports) {
+                const legacy = await prepareValidationExecution(execution);
+                try {
+                    await this.assertNoTestOnlyExports(worktreePath, emit, signal, legacy.execution);
+                }
+                finally {
+                    await legacy.cleanup();
+                }
+            }
+            return [];
+        }
+        const scoped = await prepareValidationExecution(execution);
+        try {
+            if (checksExports)
+                await this.assertNoTestOnlyExports(worktreePath, emit, signal, scoped.execution);
+            const contractDigest = validationContractDigest(contract);
+            await this.assertContractMatchesDispatchBaseline(worktreePath, contractDigest, signal, scoped.execution);
+            if (contractDigest !== currentApprovedContractDigest) {
+                await emit?.(validationEvent("prepublication_validation_compatible_contract", "validation-contract", `This checkout is pinned to approved compatible CI parity contract ${contractDigest}; the host's current contract is ${currentApprovedContractDigest}.`));
+            }
+            const changedPaths = await this.changedPaths(worktreePath, signal, scoped.execution);
+            const selected = applicableChecks(contract, profile, changedPaths);
+            const completed = [];
+            for (const check of selected) {
+                if (check.providerOnly) {
+                    await emit?.(validationEvent("prepublication_validation_provider_only", check.id, `Preserved provider-only validation '${check.id}' for the provider check run.`));
+                    continue;
+                }
+                if (check.requiredCapability && !capabilities.has(check.requiredCapability)) {
+                    throw new ForgeFailureError("prepublication_capability_unavailable", `prepublication_capability_unavailable: ${check.id} requires ${check.requiredCapability}; publication is holding until a capable runner is available.`, "bridge");
+                }
+                const postgresAdminConnection = await this.ensurePrerequisite(check, scoped.execution?.environment, scoped.postgresAdminConnection, emit) ?? scoped.postgresAdminConnection;
+                await emit?.(validationEvent("prepublication_validation_started", check.id, `Running pre-publication CI parity check '${check.id}'.`));
+                for (const step of check.steps) {
+                    let result = await this.runStep(check.id, step, worktreePath, signal, scoped.execution, postgresAdminConnection);
+                    await this.throwIfPrerequisiteWasLost(check, result, scoped.execution?.environment, postgresAdminConnection, emit);
+                    if (isTimeoutOnlyClientTestFailure(check.id, step, result)) {
+                        await emit?.(validationEvent("prepublication_validation_timeout_confirmation_started", check.id, "The full client test step reported only Vitest timeouts; confirming once with the same command and attempt environment."));
+                        result = await this.runStep(check.id, step, worktreePath, signal, scoped.execution, postgresAdminConnection);
+                        await this.throwIfPrerequisiteWasLost(check, result, scoped.execution?.environment, postgresAdminConnection, emit);
+                        await emit?.(validationEvent(result.exitCode === 0
+                            ? "prepublication_validation_timeout_confirmation_passed"
+                            : "prepublication_validation_timeout_confirmation_failed", check.id, result.exitCode === 0
+                            ? "The complete client test step passed on its single timeout confirmation run."
+                            : `The complete client test step failed on its single timeout confirmation run (exit ${result.exitCode}).`));
+                    }
+                    if (isTransientBridgeCleanupFailure(check.id, step, result)) {
+                        await emit?.(validationEvent("prepublication_validation_cleanup_confirmation_started", check.id, "The Bridge suite hit the known Windows temporary-worktree cleanup race; confirming once with the same command and attempt environment."));
+                        result = await this.runStep(check.id, step, worktreePath, signal, scoped.execution, postgresAdminConnection);
+                        await this.throwIfPrerequisiteWasLost(check, result, scoped.execution?.environment, postgresAdminConnection, emit);
+                        await emit?.(validationEvent(result.exitCode === 0
+                            ? "prepublication_validation_cleanup_confirmation_passed"
+                            : "prepublication_validation_cleanup_confirmation_failed", check.id, result.exitCode === 0
+                            ? "The complete Bridge test step passed on its single cleanup confirmation run."
+                            : `The complete Bridge test step failed on its single cleanup confirmation run (exit ${result.exitCode}).`));
+                    }
+                    if (isTransientShellInfrastructureFailure(result)) {
+                        await emit?.(validationEvent("prepublication_infrastructure_confirmation_started", check.id, "The validation shell reported a known host-runtime failure; confirming once with the same command and attempt environment."));
+                        result = await this.runStep(check.id, step, worktreePath, signal, scoped.execution, postgresAdminConnection);
+                        await this.throwIfPrerequisiteWasLost(check, result, scoped.execution?.environment, postgresAdminConnection, emit);
+                        const infrastructureFailed = isTransientShellInfrastructureFailure(result);
+                        await emit?.(validationEvent(infrastructureFailed
+                            ? "prepublication_infrastructure_confirmation_failed"
+                            : "prepublication_infrastructure_confirmation_passed", check.id, infrastructureFailed
+                            ? `The validation shell failed again on its single infrastructure confirmation run (exit ${result.exitCode}).`
+                            : result.exitCode === 0
+                                ? "The validation step recovered on its single infrastructure confirmation run."
+                                : "The host-runtime failure did not recur; continuing with normal validation failure handling."));
+                        if (infrastructureFailed) {
+                            const detail = diagnosticDetail(result);
+                            await emit?.(validationEvent("prepublication_infrastructure_failed", check.id, `Pre-publication infrastructure for '${check.id}' remained unavailable${detail ? `: ${detail}` : "."}`));
+                            throw new PrePublicationInfrastructureError(check.id, result.exitCode, result.command, result.args, detail);
+                        }
+                    }
+                    if (result.exitCode !== 0) {
+                        const detail = diagnosticDetail(result);
+                        await emit?.(validationEvent("prepublication_validation_failed", check.id, `Pre-publication CI parity check '${check.id}' exited ${result.exitCode}${detail ? `: ${detail}` : "."}`));
+                        throw new PrePublicationValidationError(check.id, result.exitCode, result.command, result.args, detail);
+                    }
+                }
+                completed.push(check.id);
+                await emit?.(validationEvent("prepublication_validation_passed", check.id, `Pre-publication CI parity check '${check.id}' passed.`));
+            }
+            return completed;
+        }
+        finally {
+            await scoped.cleanup();
+        }
+    }
+    /** Returns the native fallback connection when this check must use it instead of Docker. */
+    async ensurePrerequisite(check, environment, postgresAdminConnection, emit) {
+        if (check.requiredPrerequisite === "isolated_postgres"
+            && isolatedPostgresProvided(check.id, environment, postgresAdminConnection)) {
+            await emit?.(validationEvent("prepublication_prerequisite_ready", check.id, check.id === "playwright-e2e"
+                ? `Pre-publication check '${check.id}' is using its attempt-owned PostgreSQL database. No Docker daemon is required.`
+                : `Pre-publication check '${check.id}' is using the configured loopback PostgreSQL test server with per-run owned databases. No Docker daemon is required.`));
+            return undefined;
+        }
+        if (check.requiredPrerequisite === undefined || !this.dockerEngineProbe)
+            return undefined;
+        const current = this.dockerEngineProbe.current();
+        await emit?.(validationEvent(current?.available === false
+            ? "prepublication_prerequisite_recovery_waiting"
+            : "prepublication_prerequisite_verification_started", check.id, current?.available === false
+            ? `Waiting for Docker recovery before pre-publication check '${check.id}'.`
+            : `Verifying Docker immediately before pre-publication check '${check.id}'.`));
+        const snapshot = await this.dockerEngineProbe.ensureAvailableForRequiredWork();
+        if (!snapshot.available) {
+            const detail = `Docker prerequisite unavailable (${snapshot.unavailableCode ?? "docker_engine_unavailable"}): ${snapshot.unavailableReason ?? "the daemon did not pass a fresh readiness probe"}`;
+            const fallback = check.requiredPrerequisite === "isolated_postgres" && supportsNativeTestPostgresFallback(check)
+                ? this.nativeTestPostgresFallback()
+                : null;
+            if (fallback) {
+                await emit?.(validationEvent("prepublication_prerequisite_native_fallback", check.id, `${detail}. Pre-publication check '${check.id}' is using the dedicated native PostgreSQL test cluster at ${fallback.endpoint} with per-run owned databases.`));
+                return fallback.connectionString;
+            }
+            await emit?.(validationEvent("prepublication_prerequisite_unavailable", check.id, `Pre-publication check '${check.id}' is waiting for Docker infrastructure recovery: ${detail}`));
+            throw new PrePublicationInfrastructureError(check.id, 75, "docker", ["info"], detail);
+        }
+        await emit?.(validationEvent("prepublication_prerequisite_ready", check.id, `Docker passed a fresh daemon probe for pre-publication check '${check.id}'.`));
+        return undefined;
+    }
+    async throwIfPrerequisiteWasLost(check, result, environment, postgresAdminConnection, emit) {
+        if (result.exitCode === 0
+            || check.requiredPrerequisite === undefined
+            || (check.requiredPrerequisite === "isolated_postgres"
+                && isolatedPostgresProvided(check.id, environment, postgresAdminConnection))
+            || !this.dockerEngineProbe)
+            return;
+        const snapshot = await this.dockerEngineProbe.refresh(true);
+        if (snapshot.available)
+            return;
+        const detail = `Docker became unavailable while '${check.id}' was running (${snapshot.unavailableCode ?? "docker_engine_unavailable"}): ${snapshot.unavailableReason ?? "the daemon did not pass the failure-time probe"}`;
+        await emit?.(validationEvent("prepublication_prerequisite_lost", check.id, `${detail}. The failed command is classified as retryable infrastructure and will not consume an agent repair turn.`));
+        throw new PrePublicationInfrastructureError(check.id, result.exitCode, result.command, result.args, detail);
+    }
+    // Runs for every target repository, with or without a CI parity contract: it only reads the worktree.
+    async assertNoTestOnlyExports(worktreePath, emit, signal, execution) {
+        const found = await findUnreferencedNewExports(args => this.runCommand("git", args, worktreePath, signal, execution), worktreePath, execution?.baselineRevision);
+        const unused = found.filter(row => !row.testOnly);
+        if (unused.length > 0) {
+            await emit?.(validationEvent("prepublication_unreferenced_exports", "unreferenced-exports", `New exports with no caller yet: ${unused.map(row => `${row.name} (${row.path})`).join(", ")}. Wire them to a real caller or keep them unexported.`));
+        }
+        const testOnly = found.filter(row => row.testOnly);
+        if (testOnly.length === 0)
+            return;
+        const detail = `only tests use ${testOnly.map(row => `${row.name} (${row.path})`).join(", ")}. Wire each to a real caller in this Story, or move the export and its test to the Story that first uses it. Do not delete assertions to pass.`;
+        await emit?.(validationEvent("prepublication_validation_failed", "unreferenced-exports", `New code is tested but never called: ${detail}`));
+        throw new PrePublicationValidationError("unreferenced-exports", 1, "git", ["grep"], detail);
+    }
+    async changedPaths(worktreePath, signal, execution) {
+        const baselineRevision = execution?.baselineRevision?.trim();
+        const requests = [
+            ["diff", "--name-only", "HEAD", "--"],
+            ...(baselineRevision ? [["diff", "--name-only", `${baselineRevision}..HEAD`, "--"]] : []),
+            ["status", "--porcelain=v1", "--untracked-files=all"],
+        ];
+        const paths = new Set();
+        for (const args of requests) {
+            const result = await this.runCommand("git", args, worktreePath, signal, execution);
+            if (result.exitCode !== 0) {
+                throw new ForgeFailureError("prepublication_validation_failed", `prepublication_validation_failed: unable to inventory changed paths: ${result.stderr ?? result.stdout ?? "git failed"}`, "bridge");
+            }
+            for (const line of `${result.stdout ?? ""}`.split(/\r?\n/u).filter(Boolean)) {
+                const raw = args[0] === "status" ? line.slice(3).split(" -> ").at(-1) ?? "" : line;
+                const normalized = raw.trim().replaceAll("\\", "/");
+                if (normalized)
+                    paths.add(normalized);
+            }
+        }
+        return [...paths];
+    }
+    async assertContractMatchesDispatchBaseline(worktreePath, contractDigest, signal, execution) {
+        const baselineRevision = execution?.baselineRevision?.trim();
+        if (!baselineRevision)
+            return;
+        const result = await this.runCommand("git", ["show", `${baselineRevision}:${contractRelativePath}`], worktreePath, signal, execution);
+        if (result.exitCode !== 0) {
+            throw new ForgeFailureError("prepublication_contract_invalid", `prepublication_contract_invalid: the dispatch baseline contract could not be read from ${baselineRevision}: ${result.stderr ?? result.stdout ?? "git show failed"}`, "bridge");
+        }
+        let baselineContract;
+        try {
+            baselineContract = JSON.parse(result.stdout ?? "");
+        }
+        catch (error) {
+            throw new ForgeFailureError("prepublication_contract_invalid", `prepublication_contract_invalid: the dispatch baseline contract at ${baselineRevision} is not valid JSON.`, "bridge", { cause: error });
+        }
+        const baselineDigest = validationContractDigest(baselineContract);
+        if (!approvedContractDigests.has(baselineDigest)) {
+            throw new ForgeFailureError("prepublication_contract_invalid", `prepublication_contract_invalid: the dispatch baseline uses unapproved CI parity contract ${baselineDigest}.`, "bridge");
+        }
+        if (baselineDigest !== contractDigest) {
+            throw new ForgeFailureError("prepublication_contract_invalid", `prepublication_contract_invalid: the CI parity contract changed after dispatch (baseline ${baselineDigest}, worktree ${contractDigest}).`, "bridge");
+        }
+    }
+    async runStep(checkId, step, cwd, signal, execution, postgresAdminConnection) {
+        const invocation = managedAttemptInvocation(checkId, step, execution?.environment);
+        const stepExecution = validationExecutionForStep(checkId, step, execution, postgresAdminConnection);
+        const before = await readValidationFiles(cwd, step.assertUnchangedPaths ?? []);
+        const result = await this.runCommand(invocation.command, invocation.args, cwd, signal, stepExecution);
+        if (result.exitCode === 127 && step.fallbackCommand) {
+            const fallback = await this.runCommand(step.fallbackCommand, step.fallbackArgs ?? step.args, cwd, signal, stepExecution);
+            return {
+                ...await assertValidationFilesUnchanged(cwd, before, fallback),
+                command: step.fallbackCommand,
+                args: step.fallbackArgs ?? step.args,
+            };
+        }
+        return {
+            ...await assertValidationFilesUnchanged(cwd, before, result),
+            command: invocation.command,
+            args: invocation.args,
+        };
+    }
+    async runCommand(command, args, cwd, signal, execution) {
+        const exactSecrets = validationExactSecrets(execution?.environment);
+        try {
+            if (execution?.processRunner) {
+                const result = await execution.processRunner.run({
+                    command,
+                    args,
+                    cwd,
+                    env: execution.environment,
+                    captureOutput: true,
+                    failureRedactionValues: exactSecrets,
+                }, undefined, signal);
+                return {
+                    exitCode: result.exitCode,
+                    stdout: result.stdout === undefined ? undefined : redactText(result.stdout, exactSecrets),
+                    stderr: result.stderr === undefined ? undefined : redactText(result.stderr, exactSecrets),
+                };
+            }
+            const result = await this.commands.run(command, args, cwd, signal, execution?.environment);
+            return {
+                ...result,
+                stdout: result.stdout === undefined ? undefined : redactText(result.stdout, exactSecrets),
+                stderr: result.stderr === undefined ? undefined : redactText(result.stderr, exactSecrets),
+            };
+        }
+        catch (error) {
+            throw sanitizeFailureError(error, exactSecrets);
+        }
+    }
+}
+function managedAttemptInvocation(checkId, step, environment) {
+    const playwrightConfig = environment?.FORGE_PLAYWRIGHT_CONFIG?.trim();
+    const attemptOwned = environment?.FORGE_E2E_OWNERSHIP_MODE === "attempt"
+        || Boolean(environment?.FORGE_DISPATCH_ATTEMPT_ID?.trim());
+    if (checkId !== "playwright-e2e" || !attemptOwned) {
+        return step;
+    }
+    if (!playwrightConfig) {
+        throw new ForgeFailureError("prepublication_capability_unavailable", "prepublication_capability_unavailable: playwright-e2e requires the Bridge-generated FORGE_PLAYWRIGHT_CONFIG for a managed attempt.", "bridge");
+    }
+    return {
+        command: "pnpm",
+        args: ["--dir", "tests/e2e", "exec", "playwright", "test", "--config", playwrightConfig],
+    };
+}
+const nativeFallbackCheckIds = new Set([
+    "owned-suite-registration",
+    "dotnet-build-and-unit",
+    "comment-repair-dotnet-regression",
+]);
+const nativeFallbackDotnetTierScripts = [
+    "scripts/run-dotnet-test-tier.ps1",
+    "scripts/run-dotnet-test-tier-set.ps1",
+    "scripts/run-affected-dotnet-tests.mjs",
+];
+function supportsNativeTestPostgresFallback(check) {
+    return nativeFallbackCheckIds.has(check.id);
+}
+function validationExecutionForStep(checkId, step, execution, postgresAdminConnection) {
+    // The connection only exists when Docker is unavailable and the operator
+    // provisioned a dedicated native test cluster. Only the runner-authored
+    // .NET test tiers and the suite-identity check receive it; build, client,
+    // Bridge, and E2E steps never do.
+    if (!postgresAdminConnection || !nativeFallbackCheckIds.has(checkId))
+        return execution;
+    const runsDotnetTier = step.args.some(argument => nativeFallbackDotnetTierScripts
+        .some(script => argument.replaceAll("\\", "/").endsWith(script)));
+    if (checkId !== "owned-suite-registration" && !runsDotnetTier)
+        return execution;
+    return {
+        ...execution,
+        environment: {
+            ...execution?.environment,
+            ...nativeTestPostgresFallbackEnvironment(parseNativeTestPostgresFallback(postgresAdminConnection)),
+        },
+    };
+}
+function environmentValue(environment, name) {
+    return Object.prototype.hasOwnProperty.call(environment ?? {}, name)
+        ? environment?.[name]?.trim() ?? ""
+        : process.env[name]?.trim() ?? "";
+}
+function isolatedPostgresProvided(checkId, environment, postgresAdminConnection) {
+    if (checkId === "playwright-e2e") {
+        const attemptId = environmentValue(environment, "FORGE_DISPATCH_ATTEMPT_ID");
+        return (environmentValue(environment, "FORGE_E2E_OWNERSHIP_MODE") === "attempt"
+            || /^[0-9a-f-]{36}$/iu.test(attemptId))
+            && /^forge_attempt_[0-9a-f]{32}$/u.test(environmentValue(environment, "FORGE_ATTEMPT_DATABASE_SCHEMA"))
+            && path.isAbsolute(environmentValue(environment, "FORGE_ATTEMPT_DATABASE_READINESS_PATH"))
+            // The attempt owns a database only once the Bridge's broker has issued it one.
+            && environmentValue(environment, attemptDatabaseCapabilityEnvironment).length > 0;
+    }
+    return Boolean(postgresAdminConnection);
+}
+function validationExactSecrets(environment) {
+    return [
+        environment?.[hostRuntimeTestPostgresAdminEnvironment]?.trim() ?? "",
+        environment?.[hostRuntimeLegacyTestPostgresEnvironment]?.trim() ?? "",
+        ...attemptDatabaseCapabilitySecrets(environment?.[attemptDatabaseCapabilityEnvironment]),
+    ].filter((value, index, values) => value.length > 0 && values.indexOf(value) === index);
+}
+function diagnosticDetail(result) {
+    const diagnostic = [result.stderr, result.stdout]
+        .map(value => value?.trim() ?? "")
+        .filter(Boolean)
+        .join("\n");
+    if (diagnostic.length <= 6000)
+        return diagnostic;
+    const lines = diagnostic.split(/\r?\n/u);
+    const signal = /(?:^|\s)(?:fail(?:ed|ure)?|error|assertionerror|expected|received|×|❯|not ok)(?:\s|:|$)/iu;
+    const signalIndexes = new Set();
+    for (const [index, line] of lines.entries()) {
+        if (!signal.test(line))
+            continue;
+        for (let contextIndex = index; contextIndex <= Math.min(lines.length - 1, index + 1); contextIndex += 1) {
+            signalIndexes.add(contextIndex);
+        }
+    }
+    const head = diagnostic.slice(0, 1200);
+    const focused = [...signalIndexes]
+        .sort((left, right) => left - right)
+        .map(index => lines[index].slice(0, 1200))
+        .join("\n")
+        .slice(0, 3000);
+    const tail = diagnostic.slice(-1600);
+    return [
+        head,
+        focused ? `--- failure-focused excerpt ---\n${focused}` : "",
+        `--- diagnostic tail ---\n${tail}`,
+    ].filter(Boolean).join("\n").slice(0, 6000);
+}
+function isTimeoutOnlyClientTestFailure(checkId, step, result) {
+    if (checkId !== "client"
+        || step.command !== "pnpm"
+        || step.args.join("\0") !== ["--dir", "client", "test"].join("\0")
+        || result.exitCode !== 1) {
+        return false;
+    }
+    // Only the owned Vitest suite is eligible. A compiler, build, assertion,
+    // missing-test, or ambiguous output failure remains terminal.
+    const output = [result.stdout, result.stderr].filter(Boolean).join("\n")
+        .replace(ansiColorSequence, "");
+    if (!output.includes("client_suite_test_failed: Vitest exited 1"))
+        return false;
+    const lines = output.split(/\r?\n/u);
+    const failedTasks = lines.map(line => line.trim())
+        .filter(line => /^Failed:\s+@forge\/\S+#test$/u.test(line));
+    if (failedTasks.length !== 1 || !/^Failed:\s+@forge\/web#test$/u.test(failedTasks[0])) {
+        return false;
+    }
+    const webLines = lines.filter(line => /^@forge\/web:test:/u.test(line))
+        .map(line => line.replace(/^@forge\/web:test:\s*/u, "").trim());
+    const failedTests = webLines.map(line => line.match(/\bFailed Tests\s+(\d+)\b/u)).find(Boolean);
+    const summary = webLines.find(line => /^Tests\s+\d+ failed\s*\|\s*\d+ passed/u.test(line));
+    const expectedCount = failedTests ? Number(failedTests[1]) : 0;
+    const summaryCount = summary ? Number(summary.match(/^Tests\s+(\d+) failed/u)?.[1]) : 0;
+    const failures = webLines.flatMap((line, index) => /^FAIL\s+\S/u.test(line) ? [index] : []);
+    if (expectedCount === 0 || expectedCount !== summaryCount || failures.length !== expectedCount) {
+        return false;
+    }
+    return failures.every((start, index) => {
+        const end = index + 1 < failures.length ? failures[index + 1] : webLines.length;
+        const firstError = webLines.slice(start + 1, end)
+            .find(line => /^(?:Error|AssertionError):/u.test(line));
+        return /^Error: Test timed out in \d+ms\.$/u.test(firstError ?? "");
+    });
+}
+function isTransientBridgeCleanupFailure(checkId, step, result) {
+    if (checkId !== "bridge"
+        || step.command !== "npm"
+        || step.args.join("\0") !== ["--prefix", "tools/forge-bridge", "test"].join("\0")
+        || result.exitCode !== 1) {
+        return false;
+    }
+    // Retry only the exact Windows cleanup race observed after the cancellation
+    // readiness test. Assertions, compile failures, and unrelated EBUSY errors
+    // remain terminal and cannot consume this confirmation run.
+    const output = [result.stdout, result.stderr].filter(Boolean).join("\n")
+        .replace(ansiColorSequence, "");
+    return /\bEBUSY:\s+resource busy or locked,\s+rmdir\s+['"][^'"\r\n]*forge-prepared-probe-cancel-[^'"\r\n]*\\worktree['"]/iu.test(output)
+        && output.includes("waits for probe cleanup on cancellation and never publishes its evidence");
+}
+function isTransientShellInfrastructureFailure(result) {
+    if (result.exitCode === 0)
+        return false;
+    const output = [result.stdout, result.stderr].filter(Boolean).join("\n")
+        .replace(ansiColorSequence, "");
+    return /(?:Bash\/Service\/E_UNEXPECTED|Wsl\/Service\/E_UNEXPECTED|child_copy: cygheap read copy failed|couldn't create signal pipe)/iu.test(output);
+}
+async function prepareValidationExecution(execution) {
+    assertHostDatabaseCapabilityBoundary();
+    // Validation executes mutable worktree scripts, SDK targets, and tests. It
+    // never inherits a host PostgreSQL administrative capability; the only
+    // non-container database is the dedicated native test cluster, selected per
+    // check in ensurePrerequisite when Docker is unavailable.
+    const postgresAdminConnection = undefined;
+    const scopedExecution = execution === undefined
+        ? undefined
+        : { ...execution, environment: withoutPrivilegedPostgresEnvironment(execution.environment) };
+    if (process.platform !== "win32" || !execution) {
+        return { execution: scopedExecution, postgresAdminConnection, cleanup: async () => undefined };
+    }
+    const systemDrive = process.env.SystemDrive?.trim() || "C:";
+    const configuredRoot = scopedExecution?.environment?.FORGE_VALIDATION_TEMP_ROOT?.trim()
+        || process.env.FORGE_VALIDATION_TEMP_ROOT?.trim();
+    const root = configuredRoot || path.win32.join(systemDrive, "ForgeValidationTmp");
+    const temporaryRoot = path.win32.join(root, `${process.pid}-${randomUUID().slice(0, 8)}`);
+    await fs.mkdir(temporaryRoot, { recursive: true });
+    return {
+        execution: {
+            ...scopedExecution,
+            environment: {
+                ...scopedExecution?.environment,
+                TEMP: temporaryRoot,
+                TMP: temporaryRoot,
+                TMPDIR: temporaryRoot,
+            },
+        },
+        postgresAdminConnection,
+        cleanup: async () => {
+            await fs.rm(temporaryRoot, { recursive: true, force: true, maxRetries: 15, retryDelay: 100 });
+        },
+    };
+}
+function withoutPrivilegedPostgresEnvironment(environment) {
+    if (!environment)
+        return undefined;
+    const privilegedNames = new Set([
+        hostRuntimeTestPostgresAdminEnvironment.toLowerCase(),
+        hostRuntimeLegacyTestPostgresEnvironment.toLowerCase(),
+    ]);
+    return Object.fromEntries(Object.entries(environment)
+        .filter(([name]) => !privilegedNames.has(name.toLowerCase())));
+}
+async function readValidationFiles(cwd, relativePaths) {
+    const values = new Map();
+    for (const relativePath of relativePaths) {
+        values.set(relativePath, await fs.readFile(path.join(cwd, relativePath), "utf8"));
+    }
+    return values;
+}
+async function assertValidationFilesUnchanged(cwd, before, result) {
+    if (result.exitCode !== 0)
+        return result;
+    for (const [relativePath, original] of before) {
+        const current = await fs.readFile(path.join(cwd, relativePath), "utf8");
+        if (current !== original) {
+            return {
+                exitCode: 1,
+                stderr: `generated_drift: ${relativePath} changed during validation; regenerate and review it before publication.`,
+            };
+        }
+    }
+    return result;
+}
+export function applicableChecks(contract, profile, changedPaths) {
+    return contract.checks.filter(check => check.profiles.includes(profile)
+        && changedPaths.some(changedPath => check.changedPathPatterns.some(pattern => new RegExp(pattern, "u").test(changedPath))));
+}
+export async function loadValidationContract(worktreePath) {
+    let source;
+    try {
+        source = await fs.readFile(path.join(worktreePath, contractRelativePath), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const contract = JSON.parse(source);
+    const ids = new Set(contract.checks?.map(check => check.id));
+    const contractDigest = validationContractDigest(contract);
+    const expectedCheckIds = commentRepairRegressionContractDigests.has(contractDigest)
+        ? new Set([...requiredCheckIds, "comment-repair-dotnet-regression"])
+        : requiredCheckIds;
+    if (contract.schemaVersion !== 1
+        || contract.contractId !== "forge-ci-parity-v1"
+        || !approvedContractDigests.has(contractDigest)
+        || expectedCheckIds.size !== ids.size
+        || [...expectedCheckIds].some(id => !ids.has(id))
+        || contract.checks.some(check => !check.id || !Array.isArray(check.steps) || !Array.isArray(check.changedPathPatterns))) {
+        throw new ForgeFailureError("prepublication_contract_invalid", `prepublication_contract_invalid: the Forge CI parity contract does not match an approved definition (digest ${contractDigest}, current ${currentApprovedContractDigest}).`, "bridge");
+    }
+    return contract;
+}
+function validationContractDigest(contract) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalizeJson(contract)))
+        .digest("hex");
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJson);
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return Object.fromEntries(Object.keys(record).sort().map(key => [key, canonicalizeJson(record[key])]));
+    }
+    return value;
+}
+function validationEvent(eventType, checkId, content) {
+    return { role: "runner", kind: "checkpoint", content, eventType, data: JSON.stringify({ checkId, contractId: "forge-ci-parity-v1" }) };
+}