@velum-labs/routekit-eval-setup 1.3.2 → 1.5.0

package/dist/services/oracle-builder/service.d.ts

@@ -0,0 +1,146 @@
+import { Context, Effect, Layer } from "effect";
+import { RepositoryFoundryError } from "../../errors.js";
+import { type RepositoryHiddenOracleV1 } from "../../repository-oracle-protocol.js";
+import type { RepositoryHistoricalOracleInputV1 } from "../../repository-execution-protocol.js";
+export type { RepositoryExecutableSolutionV1, RepositoryStructuralOracleClauseV1 } from "../../repository-execution-protocol.js";
+export type OracleBuilderShape = {
+    readonly buildHistorical: (input: RepositoryHistoricalOracleInputV1) => Effect.Effect<RepositoryHiddenOracleV1, import("../../errors.js").RepositoryFoundryError>;
+};
+declare const OracleBuilder_base: Context.ServiceClass<OracleBuilder, "@velum-labs/routekit-eval-setup/OracleBuilder", OracleBuilderShape>;
+export declare class OracleBuilder extends OracleBuilder_base {
+}
+export type RepositoryHistoricalOracleExecutionInputV1 = RepositoryHistoricalOracleInputV1 & {
+    /**
+     * Host-owned execution evidence from a previously interrupted invocation.
+     * Only complete, strictly validated replay units are reused.
+     */
+    readonly resumeOracle?: RepositoryHiddenOracleV1;
+    /** Persist complete baseline repetitions, fixture repetitions, and structural inspections. */
+    readonly onReplayCompleted?: (oracle: RepositoryHiddenOracleV1) => Effect.Effect<void>;
+    /** Persist a complete per-solution boundary before another solution starts. */
+    readonly onSolutionCompleted?: (oracle: RepositoryHiddenOracleV1) => Effect.Effect<void>;
+};
+export declare const buildHistoricalHiddenOracleV1: (input: RepositoryHistoricalOracleExecutionInputV1) => Effect.Effect<{
+    readonly version: 1;
+    readonly fixtures: readonly ({
+        readonly kind: "historical-regression";
+        readonly expectationMode: "changes";
+        readonly id: string;
+        readonly description: string;
+        readonly expectedBehavior: string;
+        readonly source: "historical" | "generated" | "reviewed";
+        readonly testPath: string;
+    } | {
+        readonly kind: "boundary";
+        readonly expectationMode: "changes" | "preserved";
+        readonly id: string;
+        readonly description: string;
+        readonly expectedBehavior: string;
+        readonly source: "historical" | "generated" | "reviewed";
+        readonly testPath: string;
+    } | {
+        readonly kind: "counterfactual";
+        readonly expectationMode: "changes";
+        readonly id: string;
+        readonly description: string;
+        readonly expectedBehavior: string;
+        readonly source: "historical" | "generated" | "reviewed";
+        readonly testPath: string;
+    } | {
+        readonly kind: "metamorphic";
+        readonly expectationMode: "preserved";
+        readonly id: string;
+        readonly description: string;
+        readonly expectedBehavior: string;
+        readonly source: "historical" | "generated" | "reviewed";
+        readonly testPath: string;
+    })[];
+    readonly caseId: string;
+    readonly hardFailurePolicy: "any-critical-hard-clause-fails";
+    readonly clauses: readonly ({
+        readonly kind: "candidate-policy";
+        readonly policyId: string;
+        readonly forbiddenPaths: readonly string[];
+        readonly id: string;
+        readonly critical: boolean;
+        readonly description: string;
+    } | {
+        readonly kind: "test-command";
+        readonly recipeId: string;
+        readonly expectedExitCode: number;
+        readonly fixtureIds: readonly string[];
+        readonly id: string;
+        readonly critical: boolean;
+        readonly description: string;
+    } | {
+        readonly kind: "json-field";
+        readonly id: string;
+        readonly description: string;
+        readonly critical: boolean;
+        readonly operator: "equals" | "present" | "absent";
+        readonly pointer: string;
+        readonly expectedJson?: string | undefined;
+    } | {
+        readonly kind: "ordered-events";
+        readonly id: string;
+        readonly description: string;
+        readonly critical: boolean;
+        readonly eventTypes: readonly string[];
+        readonly terminalEvent?: string | undefined;
+    } | {
+        readonly kind: "property";
+        readonly propertyId: string;
+        readonly fixtureIds: readonly string[];
+        readonly id: string;
+        readonly critical: boolean;
+        readonly description: string;
+    } | {
+        readonly kind: "differential";
+        readonly implementationIds: readonly string[];
+        readonly fixtureIds: readonly string[];
+        readonly id: string;
+        readonly critical: boolean;
+        readonly description: string;
+    } | {
+        readonly kind: "architecture";
+        readonly ruleId: string;
+        readonly expectedPaths: readonly string[];
+        readonly id: string;
+        readonly critical: boolean;
+        readonly description: string;
+    } | {
+        readonly kind: "transformation-completeness";
+        readonly ruleId: string;
+        readonly forbiddenLegacyPaths: readonly string[];
+        readonly requiredNewPaths: readonly string[];
+        readonly id: string;
+        readonly critical: boolean;
+        readonly description: string;
+    } | {
+        readonly kind: "semantic-residual";
+        readonly criterion: string;
+        readonly id: string;
+        readonly critical: boolean;
+        readonly description: string;
+    })[];
+    readonly solutions: readonly {
+        readonly kind: "historical-reference" | "independent-valid" | "simplified-valid" | "behavior-preserving-valid" | "historical-defect" | "mutation" | "model-near-miss" | "reward-hacking";
+        readonly id: string;
+        readonly expectedClass: "valid" | "wrong";
+        readonly family: string;
+        readonly commit?: string | undefined;
+    }[];
+    readonly observations: readonly {
+        readonly outcome: "pass" | "fail" | "unknown";
+        readonly solutionId: string;
+        readonly clauseId: string;
+        readonly repetition: number;
+        readonly detail: string;
+        readonly inconclusiveReason?: "unattributed-test-failure" | undefined;
+    }[];
+    readonly knownLimitations: readonly string[];
+    readonly executionBindingDigest?: string | undefined;
+    readonly executionRepetitions?: number | undefined;
+}, RepositoryFoundryError, never>;
+export declare const makeOracleBuilder: Effect.Effect<OracleBuilderShape, never, never>;
+export declare const OracleBuilderLive: Layer.Layer<OracleBuilder, never, never>;

package/dist/services/oracle-builder/service.js

@@ -0,0 +1,513 @@
+import { randomUUID } from "node:crypto";
+import { Context, Effect, Layer, Option, Semaphore } from "effect";
+import { checkpointDigestV1 } from "../../case-pipeline-protocol.js";
+import { repositoryCommandTestEvidenceV1 } from "../../adapters/repository-command-evidence.js";
+import { inspectRepositorySolutionPathsV1, makeRepositoryPreparationCacheV1, replayRepositoryCommandsV1 } from "../../adapters/repository-command-runner.js";
+import { RepositoryFoundryError } from "../../errors.js";
+import { assertRepositoryHiddenFixtureSuiteV1 } from "../../repository-fixture-protocol.js";
+import { assertRepositoryHiddenOracleV1 } from "../../repository-oracle-protocol.js";
+import { evaluateRepositoryOracleAdequacyV1 } from "../../repository-quality-policy.js";
+import { repositoryOracleExecutionBindingV1 } from "../../repository-oracle-execution-binding.js";
+import { RepositoryFoundryEvidenceReconstruction } from "../evidence-reconstruction/service.js";
+import { reportFoundryAuthoringArtifactV1, reportFoundryHeartbeatV1 } from "../foundry-progress/service.js";
+export class OracleBuilder extends Context.Service()("@velum-labs/routekit-eval-setup/OracleBuilder") {
+}
+export const buildHistoricalHiddenOracleV1 = Effect.fn("OracleBuilder.buildHistorical")(function* (input) {
+    const reconstruction = yield* Effect.serviceOption(RepositoryFoundryEvidenceReconstruction);
+    if (Option.isSome(reconstruction))
+        return yield* reconstruction.value.oracle(input);
+    const oracleConcurrency = input.oracleConcurrency === undefined ? 2 : input.oracleConcurrency;
+    if (!Number.isInteger(oracleConcurrency) || oracleConcurrency < 1 || oracleConcurrency > 4) {
+        return yield* new RepositoryFoundryError({
+            operation: "run-command",
+            detail: "oracleConcurrency must be an integer from 1 to 4"
+        });
+    }
+    if (input.seed.status !== "qualified" || input.seed.referenceCommit === undefined) {
+        throw new Error("historical hidden oracle requires a qualified seed with a reference commit");
+    }
+    if (input.hiddenFixtureSuite !== undefined) {
+        assertRepositoryHiddenFixtureSuiteV1(input.hiddenFixtureSuite);
+        if (input.hiddenFixtureSuite.caseId !== input.caseId) {
+            throw new Error("hidden fixture suite case id does not match the oracle case");
+        }
+    }
+    const { executionBindingDigest, solutions, solutionMetadata, hiddenTestOverlays, protectedControlOverlays, structuralClauses, repetitions } = repositoryOracleExecutionBindingV1(input);
+    const ids = new Set(solutions.map((solution) => solution.id));
+    if (ids.size !== solutions.length) {
+        throw new Error("repository executable solution ids must be unique");
+    }
+    const executionId = randomUUID();
+    const evidenceKind = input.hiddenFixtureSuite === undefined ? "historical" : "generated";
+    const recordExecution = (suffix, value) => reportFoundryAuthoringArtifactV1({
+        version: 1,
+        operationId: `${input.caseId}:oracle:${executionId}:${suffix}`,
+        role: "oracle-executor",
+        model: "host",
+        reasoningEffort: "none",
+        schemaName: "routekit_repository_oracle_execution_v1",
+        validation: "validated",
+        request: {
+            instructions: "Host-recorded isolated execution evidence. This is not a model request or benchmark admission.",
+            input: {
+                executionId,
+                kind: evidenceKind,
+                caseId: input.caseId,
+                initialCommit: input.seed.initialState.commit,
+                referenceCommit: input.seed.referenceCommit
+            },
+            jsonSchema: { type: "object" },
+            maximumOutputTokens: 0
+        },
+        response: { text: JSON.stringify(value) },
+        value
+    });
+    const preparationCache = yield* makeRepositoryPreparationCacheV1({
+        repositoryRoot: input.repositoryRoot,
+        commits: [input.seed.initialState.commit, input.seed.referenceCommit],
+        trustedPreparationRecipes: input.seed.environment.trustedPreparationRecipes
+    });
+    const testClauses = input.seed.environment.gradeRecipes.map((recipe) => ({
+        id: `test-${recipe.id}`,
+        kind: "test-command",
+        critical: true,
+        description: `The repository's reviewed regression command ${recipe.id} passes.`,
+        recipeId: recipe.id,
+        expectedExitCode: 0,
+        fixtureIds: []
+    }));
+    const fixtureExecutions = input.hiddenFixtureSuite?.fixtures.map((fixture) => {
+        const recipe = [...input.seed.environment.gradeRecipes]
+            .filter((candidate) => candidate.cwd === "." ||
+            fixture.testPath === candidate.cwd ||
+            fixture.testPath.startsWith(`${candidate.cwd}/`))
+            .sort((left, right) => right.cwd.length - left.cwd.length)[0];
+        const overlay = input.hiddenFixtureSuite.overlays.find((candidate) => candidate.fixtureIds.length === 1 && candidate.fixtureIds[0] === fixture.id);
+        if (recipe === undefined || overlay === undefined) {
+            throw new Error(`hidden fixture ${JSON.stringify(fixture.id)} has no independently executable reviewed recipe and overlay`);
+        }
+        return { fixture, recipe, overlay };
+    }) ?? [];
+    const fixtureClauses = fixtureExecutions.map(({ fixture, recipe }) => ({
+        id: `fixture-${fixture.id}`,
+        kind: "test-command",
+        critical: true,
+        description: `The independently executed hidden fixture ${fixture.id} satisfies its expected behavior.`,
+        recipeId: recipe.id,
+        expectedExitCode: 0,
+        fixtureIds: [fixture.id]
+    }));
+    const validationClauses = input.seed.environment.candidateValidationRecipes.map((recipe) => ({
+        id: `validation-${recipe.id}`,
+        kind: "test-command",
+        critical: true,
+        description: "The candidate builds or passes its reviewed static validation before behavioral grading.",
+        recipeId: recipe.id,
+        expectedExitCode: 0,
+        fixtureIds: []
+    }));
+    const candidatePolicyClause = {
+        id: "candidate-policy-protected-paths",
+        kind: "candidate-policy",
+        critical: true,
+        description: "The candidate does not modify protected harness controls. Visible tests are independently restored or overlaid for hidden grading.",
+        policyId: "protected-harness-controls",
+        forbiddenPaths: [...new Set(input.seed.environment.protectedControlPaths)].sort()
+    };
+    const structuralPaths = [
+        ...new Set(structuralClauses.flatMap((clause) => clause.kind === "architecture"
+            ? [...clause.expectedPaths]
+            : [...clause.requiredNewPaths, ...clause.forbiddenLegacyPaths]))
+    ];
+    const replaySolution = Effect.fnUntraced(function* (solution, solutionIndex) {
+        const observations = [...solutionRows[solutionIndex]];
+        const observed = (clauseId, repetition) => observations.some((row) => row.clauseId === clauseId && row.repetition === repetition);
+        const overridePaths = solution.fileOverrides?.map((override) => override.path) ?? [];
+        const duplicateOverridePaths = [
+            ...new Set(overridePaths.filter((path, index) => overridePaths.indexOf(path) !== index))
+        ];
+        const forbiddenOverridePaths = overridePaths.filter((path) => candidatePolicyClause.forbiddenPaths.includes(path));
+        const policyViolations = [
+            ...forbiddenOverridePaths.map((path) => `protected path override: ${path}`),
+            ...duplicateOverridePaths.map((path) => `duplicate path override: ${path}`)
+        ];
+        observations.push(...Array.from({ length: repetitions }, (_, index) => ({
+            solutionId: solution.id,
+            clauseId: candidatePolicyClause.id,
+            repetition: index + 1,
+            outcome: policyViolations.length === 0 ? "pass" : "fail",
+            detail: policyViolations.length === 0
+                ? "candidate material passed protected-path preflight"
+                : policyViolations.join("; ")
+        })).filter((row) => !observed(row.clauseId, row.repetition)));
+        if (policyViolations.length > 0) {
+            yield* publishReplayProgress(solutionIndex, observations);
+            return observations;
+        }
+        for (let repetition = 1; repetition <= repetitions; repetition += 1) {
+            if ([...validationClauses, ...testClauses].every((clause) => observed(clause.id, repetition)))
+                continue;
+            const results = yield* replayRepositoryCommandsV1({
+                preparationCache,
+                repositoryRoot: input.repositoryRoot,
+                commit: solution.commit,
+                recipes: input.seed.environment.gradeRecipes,
+                trustedPreparationRecipes: input.seed.environment.trustedPreparationRecipes,
+                candidateValidationRecipes: input.seed.environment.candidateValidationRecipes,
+                overlays: [...protectedControlOverlays, ...hiddenTestOverlays],
+                ...(solution.fileOverrides === undefined ? {} : { fileOverrides: solution.fileOverrides }),
+                repetitions: 1,
+                repetitionStart: repetition
+            });
+            yield* recordExecution(`solution-${solutionIndex}:baseline:${repetition}`, {
+                diagnosticOnly: true,
+                admissionEvidence: false,
+                complete: false,
+                solutionId: solution.id,
+                results
+            });
+            yield* reportFoundryHeartbeatV1({
+                detail: `oracle baseline replay complete; solutionIndex=${solutionIndex + 1}; commandResults=${results.length}`
+            });
+            const preparationFailure = results.find((result) => !result.gradeExecuted && result.stage === "trusted-preparation");
+            if (preparationFailure !== undefined) {
+                return yield* new RepositoryFoundryError({
+                    operation: "run-command",
+                    detail: [
+                        `trusted environment preparation failed for ${solution.id}`,
+                        `recipe=${preparationFailure.recipeId}`,
+                        `exit=${String(preparationFailure.exitCode)}`,
+                        `timeout=${String(preparationFailure.timedOut)}`
+                    ].join("; ")
+                });
+            }
+            const validationResults = [
+                ...new Map(results.map((result) => [result.repetition, result])).values()
+            ];
+            for (const result of validationResults) {
+                for (const recipe of input.seed.environment.candidateValidationRecipes) {
+                    const validation = result.candidateValidationResults.find((candidate) => candidate.recipeId === recipe.id);
+                    observations.push({
+                        solutionId: solution.id,
+                        clauseId: `validation-${recipe.id}`,
+                        repetition: result.repetition,
+                        outcome: validation !== undefined && validation.exitCode === 0 && !validation.timedOut
+                            ? "pass"
+                            : "unknown",
+                        detail: validation === undefined
+                            ? `validation not executed because an earlier candidate validation failed; terminalStage=${result.stage}; terminalRecipe=${result.recipeId}`
+                            : [
+                                `exit=${String(validation.exitCode)}`,
+                                `timeout=${String(validation.timedOut)}`,
+                                `durationMs=${String(validation.durationMs)}`,
+                                ...(validation.outputTruncated ? ["output=truncated"] : [])
+                            ].join("; ")
+                    });
+                }
+            }
+            for (const clause of testClauses) {
+                const result = results.find((candidate) => candidate.repetition === repetition && candidate.recipeId === clause.recipeId) ?? results.find((candidate) => candidate.repetition === repetition);
+                const evidence = repositoryCommandTestEvidenceV1(result, clause.recipeId);
+                observations.push({
+                    solutionId: solution.id,
+                    clauseId: clause.id,
+                    repetition,
+                    outcome: evidence.outcome,
+                    ...(evidence.inconclusiveReason === undefined
+                        ? {}
+                        : { inconclusiveReason: evidence.inconclusiveReason }),
+                    detail: result === undefined
+                        ? `recipe=${clause.recipeId}; result=unobserved`
+                        : [
+                            `recipe=${clause.recipeId}`,
+                            `observedRecipe=${result.recipeId}`,
+                            `exit=${String(result.exitCode)}`,
+                            `stage=${result.stage}`,
+                            `gradeExecuted=${String(result.gradeExecuted)}`,
+                            `timeout=${String(result.timedOut)}`,
+                            `durationMs=${String(result.durationMs)}`,
+                            ...(result.preparation === undefined
+                                ? []
+                                : [
+                                    `preparationTemplate=${result.preparation.templateKey}`,
+                                    `cloneDurationMs=${result.preparation.cloneDurationMs}`
+                                ]),
+                            `evidence=${evidence.detail}`,
+                            ...(result.outputTruncated ? ["output=truncated"] : [])
+                        ].join("; ")
+                });
+            }
+            yield* publishReplayProgress(solutionIndex, observations);
+        }
+        for (const [fixtureIndex, { fixture, recipe, overlay }] of fixtureExecutions.entries()) {
+            for (let repetition = 1; repetition <= repetitions; repetition += 1) {
+                if (observed(`fixture-${fixture.id}`, repetition))
+                    continue;
+                const fixtureResults = yield* replayRepositoryCommandsV1({
+                    preparationCache,
+                    repositoryRoot: input.repositoryRoot,
+                    commit: solution.commit,
+                    recipes: [recipe],
+                    trustedPreparationRecipes: input.seed.environment.trustedPreparationRecipes,
+                    candidateValidationRecipes: input.seed.environment.candidateValidationRecipes,
+                    overlays: [...protectedControlOverlays, ...hiddenTestOverlays],
+                    contentOverlays: [
+                        {
+                            path: overlay.path,
+                            content: overlay.content
+                        }
+                    ],
+                    ...(solution.fileOverrides === undefined
+                        ? {}
+                        : { fileOverrides: solution.fileOverrides }),
+                    repetitions: 1,
+                    repetitionStart: repetition
+                });
+                yield* recordExecution(`solution-${solutionIndex}:fixture-${fixtureIndex}:${repetition}`, {
+                    diagnosticOnly: true,
+                    admissionEvidence: false,
+                    complete: false,
+                    solutionId: solution.id,
+                    fixtureId: fixture.id,
+                    results: fixtureResults
+                });
+                yield* reportFoundryHeartbeatV1({
+                    detail: `oracle fixture replay complete; solutionIndex=${solutionIndex + 1}; fixtureIndex=${fixtureIndex + 1}; commandResults=${fixtureResults.length}`
+                });
+                const result = fixtureResults.find((candidate) => candidate.repetition === repetition && candidate.recipeId === recipe.id) ?? fixtureResults.find((candidate) => candidate.repetition === repetition);
+                const evidence = repositoryCommandTestEvidenceV1(result, recipe.id);
+                observations.push({
+                    solutionId: solution.id,
+                    clauseId: `fixture-${fixture.id}`,
+                    repetition,
+                    outcome: evidence.outcome,
+                    ...(evidence.inconclusiveReason === undefined
+                        ? {}
+                        : { inconclusiveReason: evidence.inconclusiveReason }),
+                    detail: result === undefined
+                        ? `fixture=${fixture.id}; recipe=${recipe.id}; result=unobserved`
+                        : [
+                            `fixture=${fixture.id}`,
+                            `recipe=${recipe.id}`,
+                            `observedRecipe=${result.recipeId}`,
+                            `exit=${String(result.exitCode)}`,
+                            `stage=${result.stage}`,
+                            `gradeExecuted=${String(result.gradeExecuted)}`,
+                            `timeout=${String(result.timedOut)}`,
+                            `durationMs=${String(result.durationMs)}`,
+                            ...(result.preparation === undefined
+                                ? []
+                                : [
+                                    `preparationTemplate=${result.preparation.templateKey}`,
+                                    `cloneDurationMs=${result.preparation.cloneDurationMs}`
+                                ]),
+                            `evidence=${evidence.detail}`,
+                            ...(result.outputTruncated ? ["output=truncated"] : [])
+                        ].join("; ")
+                });
+                yield* publishReplayProgress(solutionIndex, observations);
+            }
+        }
+        if (structuralPaths.length > 0 &&
+            !structuralClauses.every((clause) => Array.from({ length: repetitions }, (_, index) => index + 1).every((repetition) => observed(clause.id, repetition)))) {
+            const pathInspections = yield* inspectRepositorySolutionPathsV1({
+                repositoryRoot: input.repositoryRoot,
+                commit: solution.commit,
+                paths: structuralPaths,
+                repetitions,
+                ...(solution.fileOverrides === undefined ? {} : { fileOverrides: solution.fileOverrides })
+            });
+            for (const clause of structuralClauses) {
+                for (let repetition = 1; repetition <= repetitions; repetition += 1) {
+                    const inspected = pathInspections.filter((entry) => entry.repetition === repetition);
+                    const outcome = clause.kind === "architecture"
+                        ? clause.expectedPaths.every((path) => inspectionKind(inspected, path) === "file")
+                        : clause.requiredNewPaths.every((path) => inspectionKind(inspected, path) === "file") &&
+                            clause.forbiddenLegacyPaths.every((path) => inspectionKind(inspected, path) === "missing");
+                    observations.push({
+                        solutionId: solution.id,
+                        clauseId: clause.id,
+                        repetition,
+                        outcome: outcome ? "pass" : "fail",
+                        detail: structuralObservationDetail(clause, inspected)
+                    });
+                }
+            }
+            yield* publishReplayProgress(solutionIndex, observations);
+        }
+        return observations;
+    });
+    const clauses = [
+        candidatePolicyClause,
+        ...validationClauses,
+        ...testClauses,
+        ...fixtureClauses,
+        ...structuralClauses
+    ];
+    const makeOracle = (observations) => {
+        const oracle = {
+            version: 1,
+            caseId: input.caseId,
+            hardFailurePolicy: "any-critical-hard-clause-fails",
+            executionBindingDigest,
+            executionRepetitions: repetitions,
+            fixtures: input.hiddenFixtureSuite?.fixtures ?? [],
+            clauses,
+            // Executable overrides belong to the execution input, not the oracle's
+            // public solution metadata. The digest above preserves their identity
+            // across the schema round trip that deliberately omits patch bodies.
+            solutions: solutionMetadata,
+            observations: [...observations].sort((left, right) => solutions.findIndex(({ id }) => id === left.solutionId) -
+                solutions.findIndex(({ id }) => id === right.solutionId) ||
+                clauses.findIndex(({ id }) => id === left.clauseId) -
+                    clauses.findIndex(({ id }) => id === right.clauseId) ||
+                left.repetition - right.repetition),
+            knownLimitations: [
+                ...(input.hiddenFixtureSuite === undefined
+                    ? ["No generated counterfactual or metamorphic fixtures were supplied."]
+                    : []),
+                ...(structuralClauses.length === 0
+                    ? [
+                        "No reviewed structural or transformation-completeness clauses were supplied for this case."
+                    ]
+                    : [])
+            ]
+        };
+        assertRepositoryHiddenOracleV1(oracle);
+        return oracle;
+    };
+    const expectedOracle = makeOracle([]);
+    const solutionRows = Array.from({ length: solutions.length }, () => []);
+    const observationKey = (clauseId, repetition) => `${clauseId}:${repetition}`;
+    const replayUnits = [
+        Array.from({ length: repetitions }, (_, index) => observationKey(candidatePolicyClause.id, index + 1)),
+        ...Array.from({ length: repetitions }, (_, index) => [...validationClauses, ...testClauses].map((clause) => observationKey(clause.id, index + 1))),
+        ...fixtureClauses.flatMap((clause) => Array.from({ length: repetitions }, (_, index) => [observationKey(clause.id, index + 1)])),
+        structuralClauses.flatMap((clause) => Array.from({ length: repetitions }, (_, index) => observationKey(clause.id, index + 1)))
+    ].filter((unit) => unit.length > 0);
+    const completeSolution = (rows) => {
+        const policyFailed = rows.some((row) => row.clauseId === candidatePolicyClause.id && row.outcome === "fail");
+        return (rows.length === (policyFailed ? repetitions : expectedOracle.clauses.length * repetitions));
+    };
+    // Legacy checkpoints did not bind patch content or the preparation plan.
+    // Preserve their surrounding tournament state, but replay execution instead
+    // of either trusting incomplete identity or permanently rejecting resume.
+    if (input.resumeOracle?.executionBindingDigest !== undefined) {
+        const resumed = input.resumeOracle;
+        if (resumed.executionBindingDigest !== executionBindingDigest ||
+            (resumed.executionRepetitions !== undefined && resumed.executionRepetitions !== repetitions) ||
+            resumed.caseId !== expectedOracle.caseId ||
+            resumed.hardFailurePolicy !== expectedOracle.hardFailurePolicy ||
+            checkpointDigestV1(resumed.fixtures) !== checkpointDigestV1(expectedOracle.fixtures) ||
+            checkpointDigestV1(resumed.clauses) !== checkpointDigestV1(expectedOracle.clauses) ||
+            checkpointDigestV1(resumed.solutions) !== checkpointDigestV1(expectedOracle.solutions)) {
+            return yield* new RepositoryFoundryError({
+                operation: "run-command",
+                detail: "resumable oracle evidence does not bind the current executable inputs, environment, case, suite, clauses, and solutions"
+            });
+        }
+        if (resumed.observations.some((row) => !ids.has(row.solutionId))) {
+            return yield* new RepositoryFoundryError({
+                operation: "run-command",
+                detail: "resumable oracle evidence refers to an unknown solution"
+            });
+        }
+        const clauseIds = new Set(expectedOracle.clauses.map(({ id }) => id));
+        for (const [solutionIndex, solution] of solutions.entries()) {
+            const rows = resumed.observations.filter((observation) => observation.solutionId === solution.id);
+            if (rows.length === 0)
+                continue;
+            const keys = new Set();
+            for (const row of rows) {
+                const key = `${row.clauseId}:${String(row.repetition)}`;
+                if (!clauseIds.has(row.clauseId) ||
+                    row.repetition < 1 ||
+                    row.repetition > repetitions ||
+                    keys.has(key)) {
+                    return yield* new RepositoryFoundryError({
+                        operation: "run-command",
+                        detail: `resumable oracle evidence is invalid for solution ${JSON.stringify(solution.id)}`
+                    });
+                }
+                keys.add(key);
+            }
+            const policyFailed = rows.some((row) => row.clauseId === candidatePolicyClause.id && row.outcome === "fail");
+            const expectedKeys = policyFailed
+                ? Array.from({ length: repetitions }, (_, index) => `${candidatePolicyClause.id}:${String(index + 1)}`)
+                : expectedOracle.clauses.flatMap((clause) => Array.from({ length: repetitions }, (_, index) => `${clause.id}:${String(index + 1)}`));
+            if (rows.some((row) => !expectedKeys.includes(observationKey(row.clauseId, row.repetition))) ||
+                !replayUnits[0].every((key) => keys.has(key)) ||
+                replayUnits.some((unit) => unit.some((key) => keys.has(key)) && !unit.every((key) => keys.has(key)))) {
+                return yield* new RepositoryFoundryError({
+                    operation: "run-command",
+                    detail: `resumable oracle evidence contains an incomplete replay unit for solution ${JSON.stringify(solution.id)}`
+                });
+            }
+            solutionRows[solutionIndex] = rows;
+        }
+    }
+    let completedSolutions = solutionRows.filter(completeSolution).length;
+    const progressSemaphore = yield* Semaphore.make(1);
+    const publishReplayProgress = (solutionIndex, observations) => progressSemaphore.withPermit(Effect.gen(function* () {
+        // Snapshot before publishing: another concurrent solution may finish while
+        // the durable callback runs, but it cannot overwrite this accepted prefix.
+        solutionRows[solutionIndex] = [...observations];
+        if (input.onReplayCompleted !== undefined) {
+            yield* input.onReplayCompleted(makeOracle(solutionRows.flat()));
+        }
+        yield* reportFoundryHeartbeatV1({
+            detail: `oracle replay checkpoint; solutionIndex=${solutionIndex + 1}; observations=${observations.length}`
+        });
+    }));
+    // Each replay owns fresh scoped checkouts, HOME/TMPDIR, and child process groups.
+    // Keep all repetitions and fixtures sequential within one solution; flatten in input order.
+    yield* Effect.forEach(solutions
+        .map((solution, index) => ({ solution, index }))
+        .filter(({ index }) => !completeSolution(solutionRows[index])), ({ solution, index }) => replaySolution(solution, index).pipe(Effect.flatMap((rows) => progressSemaphore.withPermit(Effect.gen(function* () {
+        solutionRows[index] = rows;
+        completedSolutions += 1;
+        yield* recordExecution(`solution-${index}:complete`, {
+            diagnosticOnly: true,
+            admissionEvidence: false,
+            complete: false,
+            solutionId: solution.id,
+            observations: rows
+        });
+        if (input.onSolutionCompleted !== undefined) {
+            yield* input.onSolutionCompleted(makeOracle(solutionRows.flat()));
+        }
+        yield* reportFoundryHeartbeatV1({
+            detail: `oracle solution completed=${completedSolutions}/${solutions.length}; solutionIndex=${index + 1}; observations=${rows.length}`
+        });
+    })))), { concurrency: oracleConcurrency });
+    const oracle = makeOracle(solutionRows.flat());
+    const adequacy = evaluateRepositoryOracleAdequacyV1(oracle);
+    yield* recordExecution("complete", {
+        diagnosticOnly: true,
+        admissionEvidence: false,
+        complete: true,
+        oracle,
+        adequacy
+    });
+    const unresolved = new Set([
+        ...adequacy.falseAcceptedSolutionIds,
+        ...adequacy.falseRejectedSolutionIds,
+        ...adequacy.unstableSolutionIds
+    ]).size;
+    yield* reportFoundryHeartbeatV1({
+        role: "oracle-executor",
+        detail: `oracle measurement; executionId=${executionId}; kind=${evidenceKind}; solutions=${solutions.length}; ` +
+            `falseAccepts=${adequacy.falseAcceptedSolutionIds.length}; falseRejects=${adequacy.falseRejectedSolutionIds.length}; ` +
+            `unstable=${adequacy.unstableSolutionIds.length}; unresolved=${unresolved}; adequate=${String(adequacy.admitted)}`
+    });
+    return oracle;
+}, Effect.scoped);
+const inspectionKind = (inspections, path) => inspections.find((entry) => entry.path === path)?.kind ?? "unobserved";
+const structuralObservationDetail = (clause, inspections) => {
+    const paths = clause.kind === "architecture"
+        ? clause.expectedPaths
+        : [...clause.requiredNewPaths, ...clause.forbiddenLegacyPaths];
+    return paths.map((path) => `${path}=${inspectionKind(inspections, path)}`).join("; ");
+};
+export const makeOracleBuilder = Effect.succeed(OracleBuilder.of({ buildHistorical: buildHistoricalHiddenOracleV1 }));
+export const OracleBuilderLive = Layer.effect(OracleBuilder, makeOracleBuilder);