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

package/dist/services/case-finalization/service.d.ts

@@ -0,0 +1,283 @@
+import { Effect } from "effect";
+import { RepositoryFoundryError } from "../../errors.js";
+import { RepositoryBenchmarkCaseV1 } from "../../repository-benchmark-protocol.js";
+import { type RepositoryFoundryGenerationPlanV1 } from "../../repository-foundry-plan-protocol.js";
+import { type RepositoryHiddenOracleV1 } from "../../repository-oracle-protocol.js";
+import { RepositorySeedCrossBatchQualificationV1 } from "../../repository-task-seed-protocol.js";
+import { type RepositoryGeneratedCaseCheckpointV1 } from "../case-generation/service.js";
+export type RepositoryFoundryFinalizationInputV1 = {
+    readonly plan: RepositoryFoundryGenerationPlanV1;
+    readonly qualification: typeof RepositorySeedCrossBatchQualificationV1.Type;
+    readonly checkpoint: RepositoryGeneratedCaseCheckpointV1;
+};
+/** Structural and cross-payload checks precede any repository execution or model call. */
+export declare const assertRepositoryFoundryFinalizationInputV1: (input: RepositoryFoundryFinalizationInputV1) => void;
+/**
+ * Re-execute the frozen final populations and then request the original quality
+ * review. No task, solution or fixture authoring is permitted in this operation.
+ */
+export declare const finalizeRepositoryGeneratedCaseV1: (input: RepositoryFoundryFinalizationInputV1 & {
+    readonly reviewOperationId: string;
+    readonly reviewInputVersion?: 2;
+}) => Effect.Effect<{
+    version: 1;
+    plan: {
+        readonly version: 1;
+        readonly caseId: string;
+        readonly repository: {
+            readonly root: string;
+            readonly requestedRef: string;
+            readonly commit: string;
+            readonly tree: string;
+        };
+        readonly referenceCommit: string;
+        readonly seedId: string;
+        readonly modelPlan: {
+            readonly version: 1;
+            readonly assignments: readonly {
+                readonly role: "oracle-critic" | "repository-analyst" | "specification-writer" | "specification-critic-a" | "specification-critic-b" | "trajectory-designer" | "trajectory-critic" | "oracle-designer" | "valid-solution-generator-a" | "valid-solution-generator-b" | "adversary" | "solution-critic-a" | "solution-critic-b" | "held-out-adversary" | "held-out-solution-critic-a" | "held-out-solution-critic-b" | "quality-reviewer" | "hill-climb-planner";
+                readonly model: string;
+                readonly reasoningEffort: "high" | "medium" | "low" | "xhigh" | "max" | "ultra";
+            }[];
+        };
+        readonly budget: {
+            readonly wallTimeMs: number;
+            readonly requiredTotalInputTokens: number;
+            readonly requiredTotalOutputTokens: number;
+            readonly plannedModelCalls: number;
+            readonly maximumTransientRetries: number;
+            readonly maximumHillClimbAttempts: number;
+            readonly perCallOutputTokens: number;
+            readonly maximumSpecificationRevisions?: number | undefined;
+            readonly maximumOracleCoverageRevisions?: number | undefined;
+            readonly maximumFixtureRepairAttempts?: number | undefined;
+        };
+        readonly qualification: {
+            readonly batches: number;
+            readonly repetitionsPerBatch: number;
+            readonly oracleRepetitions: number;
+            readonly oracleConcurrency?: number | undefined;
+        };
+        readonly planDigest: string;
+        readonly initialCommit: string;
+        readonly reviewInputVersion?: 2 | undefined;
+        readonly requestedDimension?: string | undefined;
+        readonly excludedReferenceCommits?: readonly string[] | undefined;
+        readonly historyProvenance?: {
+            readonly method: "integrated-retained-history-v1";
+            readonly requestedRef: string;
+            readonly requestedTipCommit: string;
+            readonly requestedTipTree: string;
+            readonly integrationCommit: string;
+            readonly pathBlobs: readonly {
+                readonly path: string;
+                readonly blob: string;
+            }[];
+        } | undefined;
+        readonly validControlRegenerationSequence?: number | undefined;
+        readonly validControlReviewVersion?: 1 | 2 | undefined;
+        readonly dependencyContextVersion?: 1 | 2 | undefined;
+        readonly oracleCoverageWitnessVersion?: 1 | 2 | undefined;
+        readonly oracleCoverageWitnessRepairVersion?: 1 | undefined;
+        readonly oracleRepairFeedbackVersion?: 1 | undefined;
+        readonly specificationContractFactsVersion?: 1 | undefined;
+    };
+    qualification: {
+        readonly seed: {
+            readonly id: string;
+            readonly source: {
+                readonly kind: "historical-fix";
+                readonly changeEpisodeId: string;
+            } | {
+                readonly kind: "historical-feature";
+                readonly changeEpisodeId: string;
+            } | {
+                readonly kind: "historical-refactor";
+                readonly changeEpisodeId: string;
+            } | {
+                readonly kind: "existing-test";
+                readonly testIds: readonly string[];
+            } | {
+                readonly kind: "public-api";
+                readonly surfaceIds: readonly string[];
+            } | {
+                readonly kind: "schema-contract";
+                readonly protocolIds: readonly string[];
+            } | {
+                readonly kind: "production-request";
+                readonly requestId: string;
+            } | {
+                readonly kind: "reviewed-synthetic-gap";
+                readonly reviewId: string;
+            };
+            readonly version: 1;
+            readonly rejectionReasons: readonly string[];
+            readonly confidence: "high" | "medium" | "review-required";
+            readonly status: "candidate" | "qualified" | "rejected";
+            readonly capabilityEvidence: readonly {
+                readonly kind: "symbol" | "package" | "public-surface" | "protocol" | "schema" | "test" | "command" | "history-episode" | "workload-signal" | "documentation";
+                readonly id: string;
+                readonly path?: string | undefined;
+            }[];
+            readonly initialState: {
+                readonly commit: string;
+                readonly parentCommit?: string | undefined;
+            };
+            readonly targetBehavior: readonly {
+                readonly id: string;
+                readonly description: string;
+                readonly critical: boolean;
+                readonly evidence: readonly {
+                    readonly kind: "symbol" | "package" | "public-surface" | "protocol" | "schema" | "test" | "command" | "history-episode" | "workload-signal" | "documentation";
+                    readonly id: string;
+                    readonly path?: string | undefined;
+                }[];
+            }[];
+            readonly baselineObservations: readonly {
+                readonly id: string;
+                readonly kind: "test-command" | "property" | "schema" | "event-trace" | "structural";
+                readonly subjectId: string;
+                readonly outcome: "pass" | "fail" | "unknown";
+                readonly detail: string;
+            }[];
+            readonly preChangeObservations: readonly {
+                readonly id: string;
+                readonly kind: "test-command" | "property" | "schema" | "event-trace" | "structural";
+                readonly subjectId: string;
+                readonly outcome: "pass" | "fail" | "unknown";
+                readonly detail: string;
+            }[];
+            readonly postChangeObservations: readonly {
+                readonly id: string;
+                readonly kind: "test-command" | "property" | "schema" | "event-trace" | "structural";
+                readonly subjectId: string;
+                readonly outcome: "pass" | "fail" | "unknown";
+                readonly detail: string;
+            }[];
+            readonly candidateTestIds: readonly string[];
+            readonly risks: readonly ("review-required" | "external-service" | "ambiguous-intent" | "bundled-change" | "flaky-baseline" | "reference-only-oracle" | "weak-test-delta" | "unrealistic-mutation" | "private-context" | "cross-batch-instability")[];
+            readonly summary: string;
+            readonly environment: {
+                readonly protectedControlPaths: readonly string[];
+                readonly trustedPreparationRecipes: readonly {
+                    readonly id: string;
+                    readonly kind: "schema" | "test" | "build" | "check" | "custom";
+                    readonly cwd: string;
+                    readonly executable: string;
+                    readonly args: readonly string[];
+                    readonly timeoutMs: number;
+                }[];
+                readonly candidateValidationRecipes: readonly {
+                    readonly id: string;
+                    readonly kind: "schema" | "test" | "build" | "check" | "custom";
+                    readonly cwd: string;
+                    readonly executable: string;
+                    readonly args: readonly string[];
+                    readonly timeoutMs: number;
+                }[];
+                readonly baselineGradeRecipes: readonly {
+                    readonly id: string;
+                    readonly kind: "schema" | "test" | "build" | "check" | "custom";
+                    readonly cwd: string;
+                    readonly executable: string;
+                    readonly args: readonly string[];
+                    readonly timeoutMs: number;
+                }[];
+                readonly gradeRecipes: readonly {
+                    readonly id: string;
+                    readonly kind: "schema" | "test" | "build" | "check" | "custom";
+                    readonly cwd: string;
+                    readonly executable: string;
+                    readonly args: readonly string[];
+                    readonly timeoutMs: number;
+                }[];
+                readonly packageManager?: {
+                    readonly name: "pnpm";
+                    readonly version: string;
+                } | undefined;
+                readonly lockfilePath?: string | undefined;
+            };
+            readonly referenceCommit?: string | undefined;
+        };
+        readonly stability: {
+            readonly version: 1;
+            readonly seedId: string;
+            readonly batchesRequired: number;
+            readonly repetitionsPerBatch: number;
+            readonly stable: boolean;
+            readonly batches: readonly {
+                readonly batch: number;
+                readonly status: "qualified" | "rejected";
+                readonly phaseSignatures: readonly {
+                    readonly phase: "baseline" | "pre-change" | "post-change";
+                    readonly signatures: readonly string[];
+                }[];
+                readonly rejectionReasons: readonly string[];
+            }[];
+            readonly divergentPhases: readonly ("baseline" | "pre-change" | "post-change")[];
+            readonly failureSignatures: readonly {
+                readonly signature: string;
+                readonly count: number;
+            }[];
+            readonly rejectionReasons: readonly string[];
+        };
+    };
+    generation: {
+        qualityReview: {
+            readonly verdict: "approve" | "reject";
+            readonly detail: string;
+            readonly findings: readonly {
+                readonly axis: "oracle" | "specification" | "valid-solution-independence" | "development-adversaries" | "held-out-adversaries" | "trajectory";
+                readonly outcome: "pass" | "fail";
+                readonly detail: string;
+                readonly evidenceIds: readonly string[];
+            }[];
+            readonly coverageGaps: readonly string[];
+            readonly correlatedAssumptions: readonly string[];
+        };
+        modelCalls: {
+            readonly reasoningEffort: "high" | "medium" | "low" | "xhigh" | "max" | "ultra";
+            readonly role: "oracle-critic" | "repository-analyst" | "specification-writer" | "specification-critic-a" | "specification-critic-b" | "trajectory-designer" | "trajectory-critic" | "oracle-designer" | "valid-solution-generator-a" | "valid-solution-generator-b" | "adversary" | "solution-critic-a" | "solution-critic-b" | "held-out-adversary" | "held-out-solution-critic-a" | "held-out-solution-critic-b" | "quality-reviewer" | "hill-climb-planner";
+            readonly model: string;
+            readonly operationId: string;
+            readonly callId?: string | undefined;
+        }[];
+        version: 1;
+        trajectoryPolicy: import("../../repository-trajectory-protocol.js").RepositoryTrajectoryPolicyV1;
+        authored: import("../case-authoring/service.js").RepositoryModelAuthoredCaseSpecificationV1;
+        benchmarkCase: RepositoryBenchmarkCaseV1;
+        weakAdequacy: import("../../repository-oracle-protocol.js").RepositoryOracleAdequacyReportV1;
+        fixtureProposal: import("../case-generation/service.js").RepositoryFixtureProposalV1;
+        sourceContext?: {
+            readonly initialCommit: string;
+            readonly referenceCommit: string;
+            readonly initialSupportingPaths: readonly string[];
+            readonly referenceSupportingPaths: readonly string[];
+        };
+        initialFixtureProposal: import("../case-generation/service.js").RepositoryFixtureProposalV1;
+        oracleCoverageReviews?: readonly {
+            readonly phase: "initial" | "before-freeze";
+            readonly revision: number;
+            readonly review: import("../../repository-oracle-coverage-protocol.js").RepositoryOracleCoverageReviewV1;
+            readonly executionAssessment?: {
+                readonly kind: "resolved-by-execution";
+                readonly witnesses: readonly import("../oracle-coverage-witness/service.js").RepositoryOracleCoverageWitnessV1[];
+            };
+        }[];
+        oracleCoverageWitnessRevisions?: readonly {
+            readonly sequence: number;
+            readonly decision: "accepted" | "rejected";
+            readonly revisions: readonly import("../oracle-coverage-witness/service.js").RepositoryOracleCoverageWitnessRevisionV1[];
+        }[];
+        trajectoryPolicyReview: import("../trajectory-policy/service.js").RepositoryTrajectoryPolicyReviewV1;
+        trajectoryRevisionAttempts: readonly import("../trajectory-policy/service.js").RepositoryTrajectoryRevisionAttemptV1[];
+        validSolutionProposal: import("../case-generation/service.js").RepositorySolutionProposalV1;
+        adversaryProposal: import("../case-generation/service.js").RepositorySolutionProposalV1;
+        solutionReviews: readonly [import("../case-generation/service.js").RepositorySolutionReviewProposalV1, import("../case-generation/service.js").RepositorySolutionReviewProposalV1];
+        heldOutAdversaryProposal: import("../case-generation/service.js").RepositorySolutionProposalV1;
+        heldOutSolutionReviews: readonly [import("../case-generation/service.js").RepositorySolutionReviewProposalV1, import("../case-generation/service.js").RepositorySolutionReviewProposalV1];
+        heldOutAdequacy: import("../../repository-oracle-protocol.js").RepositoryOracleAdequacyReportV1;
+        hillClimbAttempts: readonly import("../case-generation/service.js").RepositoryHillClimbAttemptV1[];
+        heldOutOracle: RepositoryHiddenOracleV1;
+    };
+}, RepositoryFoundryError, import("../language-model/service.js").RepositoryFoundryLanguageModel>;

package/dist/services/case-finalization/service.js

@@ -0,0 +1,370 @@
+import { Effect, Option, Schema } from "effect";
+import { RepositoryExecutableSolutionSchemaV1 } from "../../case-pipeline-protocol.js";
+import { RepositoryFoundryError } from "../../errors.js";
+import { RepositoryBenchmarkCaseV1 } from "../../repository-benchmark-protocol.js";
+import { assertRepositoryHiddenFixtureSuiteV1 } from "../../repository-fixture-protocol.js";
+import { assertRepositoryFoundryGenerationPlanV1 } from "../../repository-foundry-plan-protocol.js";
+import { assertRepositoryHiddenOracleV1 } from "../../repository-oracle-protocol.js";
+import { repositoryOracleExecutionBindingV1 } from "../../repository-oracle-execution-binding.js";
+import { evaluateRepositoryOracleAdequacyV1 } from "../../repository-quality-policy.js";
+import { assertRepositoryTaskSeedV1, RepositorySeedCrossBatchQualificationV1 } from "../../repository-task-seed-protocol.js";
+import { assertRepositorySpecificationContractFactsEvidenceV1, reviewRepositoryGeneratedCaseCheckpointV1 } from "../case-generation/service.js";
+import { RepositoryFoundryEvidenceReconstruction } from "../evidence-reconstruction/service.js";
+import { reportFoundryStageV1 } from "../foundry-progress/service.js";
+import { compileReviewedHistoricalCaseV1 } from "../historical-case/service.js";
+import { buildHistoricalHiddenOracleV1 } from "../oracle-builder/service.js";
+import { validateRepositoryOracleCoverageWitnessRevisionsV1 } from "../oracle-coverage-witness/service.js";
+import { buildRepositoryBehaviorMapV1 } from "../repository-model/service.js";
+import { qualifyHistoricalTaskSeedAcrossBatchesV1 } from "../task-seed/service.js";
+const fail = (detail, cause) => new RepositoryFoundryError({
+    operation: "compile-reviewed-case",
+    detail: `frozen case finalization: ${detail}`,
+    ...(cause === undefined ? {} : { cause })
+});
+const normalize = (value) => Array.isArray(value)
+    ? value.map(normalize)
+    : value !== null && typeof value === "object"
+        ? Object.fromEntries(Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, normalize(entry)]))
+        : value;
+const same = (left, right) => JSON.stringify(normalize(left)) === JSON.stringify(normalize(right));
+const structuralClauses = (oracle) => oracle.clauses.filter((clause) => clause.kind === "architecture" || clause.kind === "transformation-completeness");
+/** Public oracle solutions are labels, not executable controls. */
+const savedPopulations = (checkpoint) => {
+    const packet = checkpoint.qualityReviewInput;
+    const decode = Schema.decodeUnknownSync(Schema.Array(RepositoryExecutableSolutionSchemaV1));
+    try {
+        const valid = decode(packet.validSolutions);
+        const development = decode(packet.developmentAdversaries);
+        const heldOut = decode(packet.heldOutAdversaries);
+        if (valid.some((solution) => solution.expectedClass !== "valid") ||
+            [...development, ...heldOut].some((solution) => solution.expectedClass !== "wrong"))
+            throw fail("saved control classes differ from their populations");
+        return { development: [...valid, ...development], heldOut: [...valid, ...heldOut] };
+    }
+    catch (cause) {
+        throw fail("complete saved control populations must be executable", cause);
+    }
+};
+const assertSavedPopulation = (input, oracle, solutions) => {
+    const binding = repositoryOracleExecutionBindingV1({
+        repositoryRoot: input.plan.repository.root,
+        caseId: input.plan.caseId,
+        seed: input.checkpoint.seed,
+        additionalSolutions: solutions,
+        hiddenFixtureSuite: {
+            version: 1,
+            caseId: input.plan.caseId,
+            fixtures: oracle.fixtures,
+            overlays: input.checkpoint.generation.fixtureProposal.overlays
+        },
+        structuralClauses: structuralClauses(oracle),
+        repetitions: input.plan.qualification.oracleRepetitions
+    });
+    if (oracle.executionBindingDigest === undefined
+        // Legacy evidence retained complete controls. Never authorize patches from
+        // metadata alone when the artifact has no executable binding.
+        ? !same(binding.solutions, oracle.solutions)
+        : oracle.executionBindingDigest !== binding.executionBindingDigest ||
+            !same(binding.solutionMetadata, oracle.solutions) ||
+            (oracle.executionRepetitions !== undefined &&
+                oracle.executionRepetitions !== binding.repetitions))
+        throw fail("complete saved control populations and executable bindings must agree");
+};
+/** Structural and cross-payload checks precede any repository execution or model call. */
+export const assertRepositoryFoundryFinalizationInputV1 = (input) => {
+    assertRepositoryFoundryGenerationPlanV1(input.plan);
+    Schema.decodeUnknownSync(RepositorySeedCrossBatchQualificationV1)(input.qualification);
+    const { checkpoint, plan, qualification } = input;
+    const generation = checkpoint.generation;
+    Schema.decodeUnknownSync(RepositoryBenchmarkCaseV1)(generation.benchmarkCase);
+    // Decoding the published schema strips executable control overlays and
+    // host observation metadata. Validate against it, then bind the complete
+    // saved evidence that the generation reviewer actually received.
+    const benchmark = generation.benchmarkCase;
+    assertRepositoryTaskSeedV1(checkpoint.seed);
+    assertRepositoryHiddenOracleV1(generation.heldOutOracle);
+    if (checkpoint.version !== 1 ||
+        checkpoint.kind !== "pending-quality-review" ||
+        checkpoint.validControlReviewVersion !==
+            (plan.validControlReviewVersion === 2 ? 2 : undefined) ||
+        checkpoint.reviewInputVersion !== plan.reviewInputVersion ||
+        checkpoint.specificationContractFactsVersion !== plan.specificationContractFactsVersion ||
+        checkpoint.repositoryRoot !== plan.repository.root ||
+        checkpoint.operationId !== `repository-foundry-${plan.planDigest.slice(0, 20)}` ||
+        !same(checkpoint.modelPlan, plan.modelPlan) ||
+        benchmark.id !== plan.caseId ||
+        benchmark.status !== "valid-library" ||
+        !benchmark.adequacy.admitted ||
+        benchmark.seedId !== plan.seedId ||
+        benchmark.visible.lane !== "repository-agent" ||
+        benchmark.visible.checkoutCommit !== plan.initialCommit ||
+        checkpoint.seed.id !== plan.seedId ||
+        checkpoint.seed.initialState.commit !== plan.initialCommit ||
+        checkpoint.seed.referenceCommit !== plan.referenceCommit ||
+        qualification.seed.id !== plan.seedId ||
+        !qualification.stability.stable ||
+        qualification.seed.status !== "qualified" ||
+        qualification.seed.initialState.commit !== plan.initialCommit ||
+        qualification.seed.referenceCommit !== plan.referenceCommit ||
+        !same(qualification.seed.environment, checkpoint.seed.environment) ||
+        generation.heldOutOracle.caseId !== plan.caseId ||
+        !evaluateRepositoryOracleAdequacyV1(benchmark.hidden).admitted ||
+        !evaluateRepositoryOracleAdequacyV1(generation.heldOutOracle).admitted ||
+        generation.modelCalls.some((call) => call.role === "quality-reviewer") ||
+        generation.modelCalls.length + 1 > plan.budget.plannedModelCalls)
+        throw fail("checkpoint, completed populations, budget and parent plan must agree");
+    if (plan.specificationContractFactsVersion === 1) {
+        assertRepositorySpecificationContractFactsEvidenceV1(generation.authored);
+        if (generation.authored.referenceGrounding?.beforeCommit !== plan.initialCommit ||
+            generation.authored.referenceGrounding.referenceCommit !== plan.referenceCommit ||
+            !same(generation.authored.groundedTargetBehavior, checkpoint.seed.targetBehavior))
+            throw fail("contract-fact checkpoint must retain its pinned reference and final grounded behavior");
+    }
+    const packet = checkpoint.qualityReviewInput;
+    const boundFields = {
+        ...(plan.validControlReviewVersion === 2 ? { validControlReviewVersion: 2 } : {}),
+        ...(plan.specificationContractFactsVersion === undefined
+            ? {}
+            : {
+                specificationContractFactsVersion: plan.specificationContractFactsVersion,
+                contractFacts: generation.authored.contractFacts
+            }),
+        visible: generation.authored.visible,
+        targetBehavior: checkpoint.seed.targetBehavior,
+        specificationReviews: generation.authored.reviews,
+        fixtureProposal: generation.fixtureProposal,
+        ...(plan.oracleCoverageWitnessVersion !== undefined
+            ? { oracleCoverageReviews: generation.oracleCoverageReviews }
+            : {}),
+        ...(plan.oracleCoverageWitnessVersion === 2
+            ? { oracleCoverageWitnessRevisions: generation.oracleCoverageWitnessRevisions }
+            : {}),
+        solutionReviews: generation.solutionReviews,
+        heldOutSolutionReviews: generation.heldOutSolutionReviews,
+        heldOutAdequacy: generation.heldOutAdequacy,
+        executableAdequacy: benchmark.adequacy,
+        oracleFrozenBeforeHeldOutTournament: true,
+        trajectoryPolicy: generation.trajectoryPolicy,
+        trajectoryPolicyReview: generation.trajectoryPolicyReview,
+        trajectoryRevisionAttempts: generation.trajectoryRevisionAttempts,
+        developmentOracle: {
+            clauses: benchmark.hidden.clauses,
+            observations: benchmark.hidden.observations
+        },
+        heldOutOracle: {
+            clauses: generation.heldOutOracle.clauses,
+            observations: generation.heldOutOracle.observations
+        }
+    };
+    for (const [key, value] of Object.entries(boundFields))
+        if (!same(packet[key], value))
+            throw fail(`the saved ${key} review evidence differs`);
+    const populations = savedPopulations(checkpoint);
+    assertSavedPopulation(input, benchmark.hidden, populations.development);
+    assertSavedPopulation(input, generation.heldOutOracle, populations.heldOut);
+    if (!Array.isArray(packet.evidenceInventory) ||
+        checkpoint.sourceBases.some((source) => typeof source !== "string"))
+        throw fail("complete saved control populations and source bases must agree");
+    const suite = {
+        version: 1,
+        caseId: plan.caseId,
+        fixtures: benchmark.hidden.fixtures,
+        overlays: generation.fixtureProposal.overlays
+    };
+    assertRepositoryHiddenFixtureSuiteV1(suite);
+    if (!same(suite.fixtures, generation.heldOutOracle.fixtures))
+        throw fail("development and held-out evidence must use the same frozen suite");
+    if (plan.oracleCoverageWitnessVersion === 2) {
+        const recordedRevisions = generation.hillClimbAttempts.flatMap((attempt) => attempt.coverageWitnessRevalidation === undefined
+            ? []
+            : [
+                {
+                    sequence: attempt.sequence,
+                    decision: attempt.decision,
+                    revisions: attempt.coverageWitnessRevalidation.revisions
+                }
+            ]);
+        if (!same(generation.oracleCoverageWitnessRevisions, recordedRevisions))
+            throw fail("witness revision history must match the complete hill-climb decisions");
+        const witnesses = generation.oracleCoverageReviews?.flatMap((review) => review.executionAssessment?.witnesses ?? []) ?? [];
+        const retained = new Map(witnesses.map((witness) => [witness.fixture.id, witness.overlay]));
+        for (const attempt of generation.oracleCoverageWitnessRevisions ?? []) {
+            for (const revision of attempt.revisions) {
+                const original = witnesses.find((witness) => witness.fixture.id === revision.fixtureId);
+                if (original === undefined ||
+                    revision.originalExecutionOperationId !== original.executionOperationId ||
+                    revision.referenceCommit !== original.referenceCommit ||
+                    !same(revision.beforeOverlay, retained.get(revision.fixtureId)))
+                    throw fail("witness revision lineage must preserve the original obligation and incumbent");
+                if (attempt.decision === "accepted") {
+                    if (revision.status !== "validated" ||
+                        revision.referenceEvidence.outcome !== "pass" ||
+                        revision.mutantEvidence?.outcome !== "fail")
+                        throw fail("an accepted witness revision requires repeated semantic validation");
+                    retained.set(revision.fixtureId, revision.overlay);
+                }
+            }
+        }
+        for (const [id, overlay] of retained)
+            if (!same(overlay, suite.overlays.find((candidate) => candidate.fixtureIds[0] === id)))
+                throw fail("the final suite must contain each adopted witness revision");
+    }
+};
+const assertSameFrozenOracle = (original, replay) => {
+    // Legacy executable populations were checked in full before any execution;
+    // a fresh oracle deliberately publishes metadata rather than patch bodies.
+    const originalMetadata = original.solutions.map(({ id, kind, family, expectedClass, commit }) => ({
+        id, kind, family, expectedClass, commit
+    }));
+    if (!same(original.fixtures, replay.fixtures) ||
+        !same(original.clauses, replay.clauses) ||
+        !same(originalMetadata, replay.solutions) ||
+        (original.executionBindingDigest !== undefined &&
+            original.executionBindingDigest !== replay.executionBindingDigest) ||
+        original.observations.length !== replay.observations.length)
+        throw fail("revalidation changed a frozen fixture, clause, control, or observation population");
+};
+/**
+ * Re-execute the frozen final populations and then request the original quality
+ * review. No task, solution or fixture authoring is permitted in this operation.
+ */
+export const finalizeRepositoryGeneratedCaseV1 = Effect.fn("CaseFinalization.finalize")(function* (input) {
+    const reconstruction = yield* Effect.serviceOption(RepositoryFoundryEvidenceReconstruction);
+    if (Option.isSome(reconstruction))
+        return yield* fail("real finalization cannot run inside diagnostic reconstruction");
+    yield* Effect.try({
+        try: () => assertRepositoryFoundryFinalizationInputV1(input),
+        catch: (cause) => fail("invalid or incomplete frozen checkpoint", cause)
+    });
+    const { plan, checkpoint } = input;
+    const original = checkpoint.generation;
+    const populations = savedPopulations(checkpoint);
+    yield* reportFoundryStageV1("replay-qualify", "revalidating the frozen parent checkpoint");
+    const qualification = yield* qualifyHistoricalTaskSeedAcrossBatchesV1({
+        repositoryRoot: plan.repository.root,
+        seed: input.qualification.seed,
+        batches: plan.qualification.batches,
+        repetitionsPerBatch: plan.qualification.repetitionsPerBatch
+    });
+    if (!qualification.stability.stable || qualification.seed.status !== "qualified")
+        return yield* fail("fresh repeated historical qualification failed");
+    const seed = { ...qualification.seed, targetBehavior: checkpoint.seed.targetBehavior };
+    if (plan.oracleCoverageWitnessVersion === 2) {
+        const revisions = yield* validateRepositoryOracleCoverageWitnessRevisionsV1({
+            operationId: `${input.reviewOperationId}:witness-revalidation`,
+            repositoryRoot: plan.repository.root,
+            seed,
+            suite: {
+                version: 1,
+                caseId: plan.caseId,
+                fixtures: original.benchmarkCase.hidden.fixtures,
+                overlays: original.fixtureProposal.overlays
+            },
+            retained: (original.oracleCoverageReviews ?? []).flatMap((review) => (review.executionAssessment?.witnesses ?? []).map((witness) => ({
+                witness,
+                overlay: witness.overlay
+            })))
+        });
+        if (revisions.some((revision) => revision.status !== "validated"))
+            return yield* fail("fresh witness revalidation did not preserve an original defect-detection obligation");
+    }
+    const map = yield* buildRepositoryBehaviorMapV1({
+        repositoryRoot: plan.repository.root,
+        requestedRef: plan.repository.commit
+    });
+    if (map.repository.commit !== plan.repository.commit ||
+        map.repository.tree !== plan.repository.tree)
+        return yield* fail("the pinned repository history differs from the parent plan");
+    yield* reportFoundryStageV1("tournament", "replaying the complete frozen development population");
+    const compiled = yield* compileReviewedHistoricalCaseV1({
+        repositoryRoot: plan.repository.root,
+        map,
+        seed,
+        blueprint: {
+            caseId: plan.caseId,
+            ...(plan.requestedDimension === undefined
+                ? {}
+                : { requestedDimension: plan.requestedDimension }),
+            visible: original.authored.visible,
+            specificationReviews: original.authored.reviews,
+            finalFixtureSuite: {
+                version: 1,
+                caseId: plan.caseId,
+                fixtures: original.benchmarkCase.hidden.fixtures,
+                overlays: original.fixtureProposal.overlays
+            },
+            solutions: populations.development,
+            structuralClauses: structuralClauses(original.benchmarkCase.hidden),
+            trajectoryPolicy: original.trajectoryPolicy,
+            oracleRepetitions: plan.qualification.oracleRepetitions,
+            ...(plan.qualification.oracleConcurrency === undefined
+                ? {}
+                : { oracleConcurrency: plan.qualification.oracleConcurrency })
+        }
+    });
+    if (compiled.benchmarkCase.status !== "valid-library" ||
+        !compiled.benchmarkCase.adequacy.admitted ||
+        compiled.benchmarkCase.behavioralFingerprint !== original.benchmarkCase.behavioralFingerprint)
+        return yield* fail("fresh development validation failed or changed the task fingerprint");
+    yield* Effect.try({
+        try: () => assertSameFrozenOracle(original.benchmarkCase.hidden, compiled.hidden),
+        catch: (cause) => fail("development replay did not preserve the frozen population", cause)
+    });
+    yield* reportFoundryStageV1("held-out-tournament", "replaying the frozen held-out population");
+    const heldOutOracle = yield* buildHistoricalHiddenOracleV1({
+        repositoryRoot: plan.repository.root,
+        caseId: plan.caseId,
+        seed,
+        additionalSolutions: populations.heldOut,
+        structuralClauses: structuralClauses(original.heldOutOracle),
+        hiddenFixtureSuite: {
+            version: 1,
+            caseId: plan.caseId,
+            fixtures: original.heldOutOracle.fixtures,
+            overlays: original.fixtureProposal.overlays
+        },
+        repetitions: plan.qualification.oracleRepetitions,
+        ...(plan.qualification.oracleConcurrency === undefined
+            ? {}
+            : { oracleConcurrency: plan.qualification.oracleConcurrency })
+    });
+    const heldOutAdequacy = evaluateRepositoryOracleAdequacyV1(heldOutOracle);
+    if (!heldOutAdequacy.admitted)
+        return yield* fail("fresh frozen held-out validation failed");
+    yield* Effect.try({
+        try: () => assertSameFrozenOracle(original.heldOutOracle, heldOutOracle),
+        catch: (cause) => fail("held-out replay did not preserve the frozen population", cause)
+    });
+    const refreshed = {
+        ...checkpoint,
+        seed,
+        requiresReplayValidation: false,
+        generation: {
+            ...original,
+            benchmarkCase: compiled.benchmarkCase,
+            heldOutOracle,
+            heldOutAdequacy
+        },
+        qualityReviewInput: {
+            ...checkpoint.qualityReviewInput,
+            executableAdequacy: compiled.benchmarkCase.adequacy,
+            heldOutAdequacy,
+            developmentOracle: {
+                clauses: compiled.benchmarkCase.hidden.clauses,
+                observations: compiled.benchmarkCase.hidden.observations
+            },
+            heldOutOracle: { clauses: heldOutOracle.clauses, observations: heldOutOracle.observations }
+        }
+    };
+    const generation = yield* reviewRepositoryGeneratedCaseCheckpointV1({
+        checkpoint: refreshed,
+        operationId: input.reviewOperationId,
+        ...(input.reviewInputVersion === undefined
+            ? {}
+            : { reviewInputVersion: input.reviewInputVersion })
+    });
+    return { version: 1, plan, qualification, generation };
+});