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

package/dist/repository-execution-protocol.d.ts

@@ -0,0 +1,150 @@
+import { Schema } from "effect";
+import type { RepositoryHiddenFixtureSuiteV1 } from "./repository-fixture-protocol.js";
+import type { RepositoryOracleClauseV1, RepositoryReferenceSolutionV1 } from "./repository-oracle-protocol.js";
+import type { RepositoryTaskSeedV1 } from "./repository-task-seed-protocol.js";
+export declare const RepositoryCommandExecutionStageV1: Schema.Literals<readonly ["trusted-preparation", "candidate-validation", "grade"]>;
+export type RepositoryCommandExecutionStageV1 = typeof RepositoryCommandExecutionStageV1.Type;
+export type RepositoryCommandObservationV1 = {
+    readonly version: 1;
+    readonly kind: "started";
+    readonly at: string;
+    readonly commandId: string;
+    readonly recipeId: string;
+    readonly repetition: number;
+    readonly stage: RepositoryCommandExecutionStageV1;
+} | {
+    readonly version: 1;
+    readonly kind: "output";
+    readonly at: string;
+    readonly commandId: string;
+    readonly recipeId: string;
+    readonly repetition: number;
+    readonly stage: RepositoryCommandExecutionStageV1;
+    readonly stream: "stdout" | "stderr";
+    readonly sequence: number;
+    readonly chunk: string;
+    readonly chunkBytes: number;
+    readonly commandBytes: number;
+    readonly truncated: boolean;
+} | {
+    readonly version: 1;
+    readonly kind: "completed";
+    readonly at: string;
+    readonly commandId: string;
+    readonly recipeId: string;
+    readonly repetition: number;
+    readonly stage: RepositoryCommandExecutionStageV1;
+    readonly exitCode: number | null;
+    readonly timedOut: boolean;
+    readonly durationMs: number;
+    readonly commandBytes: number;
+    readonly truncated: boolean;
+};
+export declare const RepositoryCommandInvocationResultV1: Schema.Struct<{
+    readonly recipeId: Schema.String;
+    readonly commit: Schema.String;
+    readonly repetition: Schema.Finite;
+    readonly stage: Schema.Literals<readonly ["trusted-preparation", "candidate-validation", "grade"]>;
+    readonly exitCode: Schema.NullOr<Schema.Finite>;
+    readonly timedOut: Schema.Boolean;
+    readonly outputTruncated: Schema.Boolean;
+    readonly stdout: Schema.String;
+    readonly stderr: Schema.String;
+    readonly durationMs: Schema.Finite;
+    /** Host-selected evidence protocol; candidate stdout cannot select a grader. */
+    readonly testReporter: Schema.optionalKey<Schema.Literal<"vitest-v1">>;
+}>;
+export type RepositoryCommandInvocationResultV1 = typeof RepositoryCommandInvocationResultV1.Type;
+export declare const RepositoryCommandResultV1: Schema.Struct<{
+    readonly gradeExecuted: Schema.Boolean;
+    readonly trustedPreparationResults: Schema.$Array<Schema.Struct<{
+        readonly recipeId: Schema.String;
+        readonly commit: Schema.String;
+        readonly repetition: Schema.Finite;
+        readonly stage: Schema.Literals<readonly ["trusted-preparation", "candidate-validation", "grade"]>;
+        readonly exitCode: Schema.NullOr<Schema.Finite>;
+        readonly timedOut: Schema.Boolean;
+        readonly outputTruncated: Schema.Boolean;
+        readonly stdout: Schema.String;
+        readonly stderr: Schema.String;
+        readonly durationMs: Schema.Finite;
+        /** Host-selected evidence protocol; candidate stdout cannot select a grader. */
+        readonly testReporter: Schema.optionalKey<Schema.Literal<"vitest-v1">>;
+    }>>;
+    readonly candidateValidationResults: Schema.$Array<Schema.Struct<{
+        readonly recipeId: Schema.String;
+        readonly commit: Schema.String;
+        readonly repetition: Schema.Finite;
+        readonly stage: Schema.Literals<readonly ["trusted-preparation", "candidate-validation", "grade"]>;
+        readonly exitCode: Schema.NullOr<Schema.Finite>;
+        readonly timedOut: Schema.Boolean;
+        readonly outputTruncated: Schema.Boolean;
+        readonly stdout: Schema.String;
+        readonly stderr: Schema.String;
+        readonly durationMs: Schema.Finite;
+        /** Host-selected evidence protocol; candidate stdout cannot select a grader. */
+        readonly testReporter: Schema.optionalKey<Schema.Literal<"vitest-v1">>;
+    }>>;
+    readonly isolationTimings: Schema.optionalKey<Schema.Struct<{
+        readonly checkoutDurationMs: Schema.Finite;
+        readonly overlayDurationMs: Schema.Finite;
+        readonly cleanupDurationMs: Schema.Finite;
+    }>>;
+    readonly preparation: Schema.optionalKey<Schema.Struct<{
+        readonly kind: Schema.Literal<"pristine-install-template">;
+        readonly templateKey: Schema.String;
+        readonly sourceCommit: Schema.String;
+        readonly cloneDurationMs: Schema.Finite;
+        readonly sharedResults: Schema.$Array<Schema.Struct<{
+            readonly recipeId: Schema.String;
+            readonly commit: Schema.String;
+            readonly repetition: Schema.Finite;
+            readonly stage: Schema.Literals<readonly ["trusted-preparation", "candidate-validation", "grade"]>;
+            readonly exitCode: Schema.NullOr<Schema.Finite>;
+            readonly timedOut: Schema.Boolean;
+            readonly outputTruncated: Schema.Boolean;
+            readonly stdout: Schema.String;
+            readonly stderr: Schema.String;
+            readonly durationMs: Schema.Finite;
+            /** Host-selected evidence protocol; candidate stdout cannot select a grader. */
+            readonly testReporter: Schema.optionalKey<Schema.Literal<"vitest-v1">>;
+        }>>;
+    }>>;
+    readonly recipeId: Schema.String;
+    readonly commit: Schema.String;
+    readonly repetition: Schema.Finite;
+    readonly stage: Schema.Literals<readonly ["trusted-preparation", "candidate-validation", "grade"]>;
+    readonly exitCode: Schema.NullOr<Schema.Finite>;
+    readonly timedOut: Schema.Boolean;
+    readonly outputTruncated: Schema.Boolean;
+    readonly stdout: Schema.String;
+    readonly stderr: Schema.String;
+    readonly durationMs: Schema.Finite;
+    /** Host-selected evidence protocol; candidate stdout cannot select a grader. */
+    readonly testReporter: Schema.optionalKey<Schema.Literal<"vitest-v1">>;
+}>;
+export type RepositoryCommandResultV1 = typeof RepositoryCommandResultV1.Type;
+export type RepositoryCommandFileOverrideV1 = {
+    readonly path: string;
+    readonly content: string;
+} | {
+    readonly path: string;
+    readonly delete: true;
+};
+export type RepositoryStructuralOracleClauseV1 = Extract<RepositoryOracleClauseV1, {
+    readonly kind: "architecture" | "transformation-completeness";
+}>;
+export type RepositoryExecutableSolutionV1 = RepositoryReferenceSolutionV1 & {
+    readonly commit: string;
+    readonly fileOverrides?: readonly RepositoryCommandFileOverrideV1[];
+};
+export type RepositoryHistoricalOracleInputV1 = {
+    readonly repositoryRoot: string;
+    readonly caseId: string;
+    readonly seed: RepositoryTaskSeedV1;
+    readonly additionalSolutions: readonly RepositoryExecutableSolutionV1[];
+    readonly hiddenFixtureSuite?: RepositoryHiddenFixtureSuiteV1;
+    readonly structuralClauses?: readonly RepositoryStructuralOracleClauseV1[];
+    readonly repetitions?: number;
+    readonly oracleConcurrency?: number;
+};

package/dist/repository-execution-protocol.js

@@ -0,0 +1,38 @@
+import { Schema } from "effect";
+export const RepositoryCommandExecutionStageV1 = Schema.Literals([
+    "trusted-preparation",
+    "candidate-validation",
+    "grade"
+]);
+export const RepositoryCommandInvocationResultV1 = Schema.Struct({
+    recipeId: Schema.String,
+    commit: Schema.String,
+    repetition: Schema.Finite,
+    stage: RepositoryCommandExecutionStageV1,
+    exitCode: Schema.NullOr(Schema.Finite),
+    timedOut: Schema.Boolean,
+    outputTruncated: Schema.Boolean,
+    stdout: Schema.String,
+    stderr: Schema.String,
+    durationMs: Schema.Finite,
+    /** Host-selected evidence protocol; candidate stdout cannot select a grader. */
+    testReporter: Schema.optionalKey(Schema.Literal("vitest-v1"))
+});
+export const RepositoryCommandResultV1 = Schema.Struct({
+    ...RepositoryCommandInvocationResultV1.fields,
+    gradeExecuted: Schema.Boolean,
+    trustedPreparationResults: Schema.Array(RepositoryCommandInvocationResultV1),
+    candidateValidationResults: Schema.Array(RepositoryCommandInvocationResultV1),
+    isolationTimings: Schema.optionalKey(Schema.Struct({
+        checkoutDurationMs: Schema.Finite,
+        overlayDurationMs: Schema.Finite,
+        cleanupDurationMs: Schema.Finite
+    })),
+    preparation: Schema.optionalKey(Schema.Struct({
+        kind: Schema.Literal("pristine-install-template"),
+        templateKey: Schema.String,
+        sourceCommit: Schema.String,
+        cloneDurationMs: Schema.Finite,
+        sharedResults: Schema.Array(RepositoryCommandInvocationResultV1)
+    }))
+});

package/dist/repository-fixture-instructions.d.ts

@@ -0,0 +1,3 @@
+/** Shared authoring contract for new fixtures and bounded fixture repairs. */
+export declare const REPOSITORY_FIXTURE_EVIDENCE_INSTRUCTIONS = "The original historical tests run separately for every solution.\nPreserve that baseline and use generated overlays for additional discriminating behavior; do not reproduce unrelated\nhistorical tests as extra fixture modules. Each fixture starts a separate clean checkout and build for every control\nand repetition. Group related requirements into a small number of coherent fixture modules, usually three to five\nfor a bounded task, with many independently named tests and table-driven examples inside each module. One fixture\nmay cover several related scope clauses; map each clause to the module that actually asserts it. Group only behavior\nthat its description, expectedBehavior, kind, and expectationMode can accurately describe. Keep distinct expectation\nmodes separate when combining them would misrepresent the fixture. Do not create one module per scope clause or\ninput value by default. Fixture count is a packaging choice, never a quality target: preserve every required\nassertion, boundary, counterfactual, and invariant even when more modules are necessary. Use separate named tests\nso a failing example does not prevent unrelated examples in the module from executing.\n\nExercise the boundaries and preservation rules in the visible contract, using the pinned reference to resolve\nexpected behavior. When two fields or representations can describe the same fact, include conflicting values\nthat establish which one is authoritative; examples where they agree cannot test precedence. Vary advisory\nmetadata independently from the actual payload or state, including empty, zero, missing, and stale values\nwhere the contract permits them. Check that metadata which is not an eligibility condition cannot introduce\na shortcut around required behavior. Do not invent requirements outside the visible contract. Prefer compact\ntable-driven combinations within a fixture to separate fixture modules for every value.\n\nDerive variations from the relevant public signatures and preserved behavior, not only the historical example.\nExercise omitted, default, and explicit optional settings alongside the primary operation modes, including\ncombinations where an advisory setting could incorrectly override an explicit mode. Where the contract says\nlogical inputs are equivalent, test different representations or delivery patterns of that same input.\nFor incremental or batched processing, compare whole-input delivery with deterministic partitions at, before,\nand after meaningful boundaries, including apparent terminators followed by additional permitted input.\nFor indexed collections, include empty and sparse positions as well as dense examples when supported.\nOnly assert invariance where the pinned reference and visible contract establish it; do not assume ordering,\nbatching, or representation is irrelevant when it has specified meaning. Use independently named cases and\ndeterministic data so these variations remain reproducible across controls and repetitions.\n\nrepositoryEnvironment.localImports contains complete helper and dependency files from the initial snapshot.\nWhen supplied, referenceLocalImports contains the corresponding reference-snapshot context for oracle work.\nReuse demonstrated fixture factories and public constructors rather than guessing how imported objects are\ninitialized. Treat omitted and unresolved entries as explicit context limits, not evidence that an API exists.\nSupporting context does not expand the allowed edit paths. Keep setup faithful to the repository's existing\nhelpers, especially resource lifecycle, authentication, clocks, and dependency injection.\n\nFor Node test recipes, only completed test-body AssertionErrors are behavioral failure evidence. Plain Error or\nTypeError exceptions, hook failures, process crashes, missing tests, and test-runner timeouts are inconclusive.\nExpress required behavior with node:assert/strict. Required success is itself a behavior to assert: capture the\nresult of an application operation inside an awaited assert.doesNotReject callback, or a helper that does so\nand returns that result. A bare await of an operation expected to succeed lets an incorrect implementation's\nexception become inconclusive instead of an assertion failure. Apply this to required-success calls, response\nbody reads, and asynchronous races. Use assert.doesNotThrow for required synchronous success. Keep fixture\nconstruction, environment setup, and imports outside these behavioral assertions; do not wrap an entire test.\nFor a specified asynchronous deadline or streaming-return\nrequirement, race against a resolved tagged sentinel and assert that the sentinel did not win; do not reject a\ntimer with a plain Error or use the test-runner timeout as the behavioral assertion. Await assert.rejects for\nrequired rejections and assert structural preconditions before reading nested result fields.\nKeep assertions tied to the visible contract. Never catch all setup, import, or harness errors and relabel them\nas assertion failures, suppress failures, or replace behavioral checks with constants.";
+export declare const repositoryFixtureAuthoringInstructionsV1: (instructions: string, witnessVersion?: 1 | 2, oracleRepairFeedbackVersion?: 1) => string;

package/dist/repository-fixture-instructions.js

@@ -0,0 +1,91 @@
+/** Shared authoring contract for new fixtures and bounded fixture repairs. */
+export const REPOSITORY_FIXTURE_EVIDENCE_INSTRUCTIONS = `The original historical tests run separately for every solution.
+Preserve that baseline and use generated overlays for additional discriminating behavior; do not reproduce unrelated
+historical tests as extra fixture modules. Each fixture starts a separate clean checkout and build for every control
+and repetition. Group related requirements into a small number of coherent fixture modules, usually three to five
+for a bounded task, with many independently named tests and table-driven examples inside each module. One fixture
+may cover several related scope clauses; map each clause to the module that actually asserts it. Group only behavior
+that its description, expectedBehavior, kind, and expectationMode can accurately describe. Keep distinct expectation
+modes separate when combining them would misrepresent the fixture. Do not create one module per scope clause or
+input value by default. Fixture count is a packaging choice, never a quality target: preserve every required
+assertion, boundary, counterfactual, and invariant even when more modules are necessary. Use separate named tests
+so a failing example does not prevent unrelated examples in the module from executing.
+
+Exercise the boundaries and preservation rules in the visible contract, using the pinned reference to resolve
+expected behavior. When two fields or representations can describe the same fact, include conflicting values
+that establish which one is authoritative; examples where they agree cannot test precedence. Vary advisory
+metadata independently from the actual payload or state, including empty, zero, missing, and stale values
+where the contract permits them. Check that metadata which is not an eligibility condition cannot introduce
+a shortcut around required behavior. Do not invent requirements outside the visible contract. Prefer compact
+table-driven combinations within a fixture to separate fixture modules for every value.
+
+Derive variations from the relevant public signatures and preserved behavior, not only the historical example.
+Exercise omitted, default, and explicit optional settings alongside the primary operation modes, including
+combinations where an advisory setting could incorrectly override an explicit mode. Where the contract says
+logical inputs are equivalent, test different representations or delivery patterns of that same input.
+For incremental or batched processing, compare whole-input delivery with deterministic partitions at, before,
+and after meaningful boundaries, including apparent terminators followed by additional permitted input.
+For indexed collections, include empty and sparse positions as well as dense examples when supported.
+Only assert invariance where the pinned reference and visible contract establish it; do not assume ordering,
+batching, or representation is irrelevant when it has specified meaning. Use independently named cases and
+deterministic data so these variations remain reproducible across controls and repetitions.
+
+repositoryEnvironment.localImports contains complete helper and dependency files from the initial snapshot.
+When supplied, referenceLocalImports contains the corresponding reference-snapshot context for oracle work.
+Reuse demonstrated fixture factories and public constructors rather than guessing how imported objects are
+initialized. Treat omitted and unresolved entries as explicit context limits, not evidence that an API exists.
+Supporting context does not expand the allowed edit paths. Keep setup faithful to the repository's existing
+helpers, especially resource lifecycle, authentication, clocks, and dependency injection.
+
+For Node test recipes, only completed test-body AssertionErrors are behavioral failure evidence. Plain Error or
+TypeError exceptions, hook failures, process crashes, missing tests, and test-runner timeouts are inconclusive.
+Express required behavior with node:assert/strict. Required success is itself a behavior to assert: capture the
+result of an application operation inside an awaited assert.doesNotReject callback, or a helper that does so
+and returns that result. A bare await of an operation expected to succeed lets an incorrect implementation's
+exception become inconclusive instead of an assertion failure. Apply this to required-success calls, response
+body reads, and asynchronous races. Use assert.doesNotThrow for required synchronous success. Keep fixture
+construction, environment setup, and imports outside these behavioral assertions; do not wrap an entire test.
+For a specified asynchronous deadline or streaming-return
+requirement, race against a resolved tagged sentinel and assert that the sentinel did not win; do not reject a
+timer with a plain Error or use the test-runner timeout as the behavioral assertion. Await assert.rejects for
+required rejections and assert structural preconditions before reading nested result fields.
+Keep assertions tied to the visible contract. Never catch all setup, import, or harness errors and relabel them
+as assertion failures, suppress failures, or replace behavioral checks with constants.`;
+// Existing plans reconstruct the exact original prompt. Only a V2 plan opts in
+// to the corrected observation guidance.
+const REPOSITORY_FIXTURE_EVIDENCE_INSTRUCTIONS_V2 = REPOSITORY_FIXTURE_EVIDENCE_INSTRUCTIONS.replace(`For a specified asynchronous deadline or streaming-return
+requirement, race against a resolved tagged sentinel and assert that the sentinel did not win; do not reject a
+timer with a plain Error or use the test-runner timeout as the behavioral assertion.`, `For a specified asynchronous deadline or streaming-return requirement, withhold the input or state
+transition whose premature dependency would violate the contract, and observe the required output while it
+remains withheld. Use a generous explicit observation watchdog within the reviewed command budget and assert
+on its tagged result. A resolved-promise race or fixed count of microtasks measures implementation scheduling,
+not the contract. Do not require a particular number of turns or immediate promise settlement. Release readers,
+gates and timers in finally blocks so a negative control cannot hang the runner. Do not use a plain Error or
+the test-runner timeout as the behavioral assertion.
+Transport chunks are not logical event boundaries. Accumulate reads to the required byte or event boundary
+before comparing output, allowing a correct implementation to split or coalesce chunks and to schedule delivery
+asynchronously. Assert complete bytes, framing and semantic ordering only where the contract requires them.
+Snapshot expected mutable input metadata before invoking the operation, so in-place corruption cannot change
+both the result and its expected value.`);
+const BOUNDED_FAILURE_EVIDENCE_INSTRUCTIONS = `A fixture must finish with usable assertion evidence on plausible wrong implementations as well as on the reference.
+Keep assertion diagnostics bounded independently of input size. For large binary or textual payloads, compare
+the complete length and complete content, then assert the boolean or small comparison result with a concise
+message. For example, Buffer.equals compares all bytes; assert.ok(actual.equals(expected), "complete bytes
+must match") avoids formatting multi-megabyte actual/expected buffers. Do not deepEqual large buffers or put
+large payloads in assertion messages. Do not replace complete equality with prefix, length-only, or sampled
+checks. A process crash while constructing or reporting an assertion is inconclusive, never a semantic kill.
+Bound generated input production and release streams/resources even when assertions fail.
+
+When priorRejectedAttempts includes candidateFixtureProposal and candidateObservations, these describe the
+actual post-preflight rejected revision and its measured per-clause outcomes. Use that concrete evidence to
+repair the failed revision while preserving its demonstrated behavioral checks and every incumbent obligation.
+The rejected revision has not become the incumbent or admission evidence. Never treat missing, unstable, or
+inconclusive observations as passes or kills; the replacement must complete the full unchanged tournament.`;
+export const repositoryFixtureAuthoringInstructionsV1 = (instructions, witnessVersion, oracleRepairFeedbackVersion) => {
+    const versioned = witnessVersion === 2
+        ? instructions.replace(REPOSITORY_FIXTURE_EVIDENCE_INSTRUCTIONS, REPOSITORY_FIXTURE_EVIDENCE_INSTRUCTIONS_V2)
+        : instructions;
+    return oracleRepairFeedbackVersion === 1
+        ? `${versioned}\n\n${BOUNDED_FAILURE_EVIDENCE_INSTRUCTIONS}`
+        : versioned;
+};

package/dist/repository-fixture-protocol.d.ts

@@ -0,0 +1,79 @@
+import { Schema } from "effect";
+export declare const RepositoryOracleFixtureV1: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"historical-regression">;
+    readonly expectationMode: Schema.Literal<"changes">;
+    readonly id: Schema.String;
+    readonly description: Schema.String;
+    readonly expectedBehavior: Schema.String;
+    readonly source: Schema.Literals<readonly ["historical", "generated", "reviewed"]>;
+    readonly testPath: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"boundary">;
+    readonly expectationMode: Schema.Literals<readonly ["changes", "preserved"]>;
+    readonly id: Schema.String;
+    readonly description: Schema.String;
+    readonly expectedBehavior: Schema.String;
+    readonly source: Schema.Literals<readonly ["historical", "generated", "reviewed"]>;
+    readonly testPath: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"counterfactual">;
+    readonly expectationMode: Schema.Literal<"changes">;
+    readonly id: Schema.String;
+    readonly description: Schema.String;
+    readonly expectedBehavior: Schema.String;
+    readonly source: Schema.Literals<readonly ["historical", "generated", "reviewed"]>;
+    readonly testPath: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"metamorphic">;
+    readonly expectationMode: Schema.Literal<"preserved">;
+    readonly id: Schema.String;
+    readonly description: Schema.String;
+    readonly expectedBehavior: Schema.String;
+    readonly source: Schema.Literals<readonly ["historical", "generated", "reviewed"]>;
+    readonly testPath: Schema.String;
+}>]>;
+export type RepositoryOracleFixtureV1 = typeof RepositoryOracleFixtureV1.Type;
+export declare const RepositoryHiddenFixtureSuiteV1: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly caseId: Schema.String;
+    readonly fixtures: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"historical-regression">;
+        readonly expectationMode: Schema.Literal<"changes">;
+        readonly id: Schema.String;
+        readonly description: Schema.String;
+        readonly expectedBehavior: Schema.String;
+        readonly source: Schema.Literals<readonly ["historical", "generated", "reviewed"]>;
+        readonly testPath: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"boundary">;
+        readonly expectationMode: Schema.Literals<readonly ["changes", "preserved"]>;
+        readonly id: Schema.String;
+        readonly description: Schema.String;
+        readonly expectedBehavior: Schema.String;
+        readonly source: Schema.Literals<readonly ["historical", "generated", "reviewed"]>;
+        readonly testPath: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"counterfactual">;
+        readonly expectationMode: Schema.Literal<"changes">;
+        readonly id: Schema.String;
+        readonly description: Schema.String;
+        readonly expectedBehavior: Schema.String;
+        readonly source: Schema.Literals<readonly ["historical", "generated", "reviewed"]>;
+        readonly testPath: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"metamorphic">;
+        readonly expectationMode: Schema.Literal<"preserved">;
+        readonly id: Schema.String;
+        readonly description: Schema.String;
+        readonly expectedBehavior: Schema.String;
+        readonly source: Schema.Literals<readonly ["historical", "generated", "reviewed"]>;
+        readonly testPath: Schema.String;
+    }>]>>;
+    readonly overlays: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.String;
+        readonly content: Schema.String;
+        readonly fixtureIds: Schema.$Array<Schema.String>;
+    }>>;
+}>;
+export type RepositoryHiddenFixtureSuiteV1 = typeof RepositoryHiddenFixtureSuiteV1.Type;
+export declare function assertRepositoryHiddenFixtureSuiteV1(value: unknown): asserts value is RepositoryHiddenFixtureSuiteV1;

package/dist/repository-fixture-protocol.js

@@ -0,0 +1,79 @@
+import { Schema } from "effect";
+const RepositoryOracleFixtureBaseV1 = {
+    id: Schema.String,
+    description: Schema.String,
+    expectedBehavior: Schema.String,
+    source: Schema.Literals(["historical", "generated", "reviewed"]),
+    testPath: Schema.String
+};
+export const RepositoryOracleFixtureV1 = Schema.Union([
+    Schema.Struct({
+        ...RepositoryOracleFixtureBaseV1,
+        kind: Schema.Literal("historical-regression"),
+        expectationMode: Schema.Literal("changes")
+    }),
+    Schema.Struct({
+        ...RepositoryOracleFixtureBaseV1,
+        kind: Schema.Literal("boundary"),
+        expectationMode: Schema.Literals(["changes", "preserved"])
+    }),
+    Schema.Struct({
+        ...RepositoryOracleFixtureBaseV1,
+        kind: Schema.Literal("counterfactual"),
+        expectationMode: Schema.Literal("changes")
+    }),
+    Schema.Struct({
+        ...RepositoryOracleFixtureBaseV1,
+        kind: Schema.Literal("metamorphic"),
+        expectationMode: Schema.Literal("preserved")
+    })
+]);
+export const RepositoryHiddenFixtureSuiteV1 = Schema.Struct({
+    version: Schema.Literal(1),
+    caseId: Schema.String,
+    fixtures: Schema.Array(RepositoryOracleFixtureV1),
+    overlays: Schema.Array(Schema.Struct({
+        path: Schema.String,
+        content: Schema.String,
+        fixtureIds: Schema.Array(Schema.String)
+    }))
+});
+export function assertRepositoryHiddenFixtureSuiteV1(value) {
+    const suite = Schema.decodeUnknownSync(RepositoryHiddenFixtureSuiteV1)(value);
+    const fixtureIds = new Set(suite.fixtures.map((fixture) => fixture.id));
+    if (suite.caseId.trim().length === 0 ||
+        suite.fixtures.length === 0 ||
+        fixtureIds.size !== suite.fixtures.length) {
+        throw new Error("repository hidden fixture suite requires a case id and unique fixtures");
+    }
+    if (!suite.fixtures.some((fixture) => fixture.kind === "counterfactual" ||
+        fixture.kind === "metamorphic")) {
+        throw new Error("repository hidden fixture suite requires a counterfactual or metamorphic fixture");
+    }
+    const coveredFixtureIds = new Set(suite.overlays.flatMap((overlay) => overlay.fixtureIds));
+    const overlayCountByFixtureId = new Map();
+    for (const overlay of suite.overlays) {
+        for (const fixtureId of overlay.fixtureIds) {
+            overlayCountByFixtureId.set(fixtureId, (overlayCountByFixtureId.get(fixtureId) ?? 0) + 1);
+        }
+    }
+    if (suite.overlays.length === 0 ||
+        suite.overlays.some((overlay) => overlay.path.trim().length === 0 ||
+            overlay.content.trim().length === 0 ||
+            overlay.fixtureIds.length !== 1 ||
+            new Set(overlay.fixtureIds).size !== overlay.fixtureIds.length ||
+            overlay.fixtureIds.some((id) => !fixtureIds.has(id))) ||
+        [...fixtureIds].some((id) => !coveredFixtureIds.has(id) ||
+            overlayCountByFixtureId.get(id) !== 1)) {
+        throw new Error("every repository hidden fixture must be implemented by exactly one independently executable overlay");
+    }
+    for (const fixture of suite.fixtures) {
+        if (fixture.id.trim().length === 0 ||
+            fixture.description.trim().length === 0 ||
+            fixture.expectedBehavior.trim().length === 0 ||
+            !suite.overlays.some((overlay) => overlay.path === fixture.testPath &&
+                overlay.fixtureIds.includes(fixture.id))) {
+            throw new Error("repository hidden fixture metadata must match its test overlay");
+        }
+    }
+}

package/dist/repository-foundry-plan-protocol.d.ts

@@ -0,0 +1,118 @@
+import { Schema } from "effect";
+import { type RepositoryFoundryModelRoleV1 } from "./repository-language-model-protocol.js";
+export declare const REPOSITORY_FOUNDRY_BASE_MODEL_CALLS: number;
+export declare const REPOSITORY_FOUNDRY_TRAJECTORY_REPAIR_ATTEMPTS = 2;
+export declare const REPOSITORY_FOUNDRY_TRAJECTORY_REPAIR_CALLS: number;
+export declare const REPOSITORY_FOUNDRY_VALID_SOLUTION_REPAIR_ATTEMPTS = 2;
+export declare const REPOSITORY_FOUNDRY_VALID_SOLUTION_REPAIR_CALLS: number;
+export declare const REPOSITORY_FOUNDRY_HELD_OUT_REPAIR_CALLS = 2;
+export declare const REPOSITORY_FOUNDRY_MAXIMUM_HILL_CLIMB_ATTEMPTS = 3;
+export declare const REPOSITORY_FOUNDRY_MAXIMUM_SPECIFICATION_REVISIONS = 2;
+export declare const REPOSITORY_FOUNDRY_MAXIMUM_ORACLE_COVERAGE_REVISIONS = 2;
+export declare const REPOSITORY_FOUNDRY_MAXIMUM_VALID_CONTROL_REGENERATIONS = 3;
+export declare const REPOSITORY_FOUNDRY_TRANSIENT_RETRY_RESERVE = 3;
+export declare const REPOSITORY_FOUNDRY_REQUEST_INPUT_CEILING = 512000;
+export declare const REPOSITORY_FOUNDRY_STANDARD_OUTPUT_CEILING = 32768;
+export declare const REPOSITORY_FOUNDRY_EXPANSIVE_OUTPUT_CEILING = 65536;
+export declare const REPOSITORY_FOUNDRY_PER_CALL_OUTPUT_CEILING = 65536;
+export declare const repositoryFoundryRoleOutputCeilingV1: (role: RepositoryFoundryModelRoleV1) => number;
+export declare const REPOSITORY_FOUNDRY_BASE_OUTPUT_CEILING: number;
+export declare const REPOSITORY_FOUNDRY_HILL_CLIMB_OUTPUT_CEILING: number;
+export declare const REPOSITORY_FOUNDRY_DEFAULT_WALL_TIME_MS: number;
+export declare const REPOSITORY_FOUNDRY_MINIMUM_WALL_TIME_MS: number;
+export declare const REPOSITORY_FOUNDRY_MAXIMUM_WALL_TIME_MS: number;
+export declare const RepositoryFoundryGenerationBudgetV1: Schema.Struct<{
+    readonly plannedModelCalls: Schema.Finite;
+    readonly maximumTransientRetries: Schema.Finite;
+    readonly maximumHillClimbAttempts: Schema.Finite;
+    readonly maximumSpecificationRevisions: Schema.optionalKey<Schema.Finite>;
+    readonly maximumOracleCoverageRevisions: Schema.optionalKey<Schema.Finite>;
+    readonly maximumFixtureRepairAttempts: Schema.optionalKey<Schema.Finite>;
+    readonly requiredTotalInputTokens: Schema.Finite;
+    readonly requiredTotalOutputTokens: Schema.Finite;
+    readonly perCallOutputTokens: Schema.Finite;
+    readonly wallTimeMs: Schema.Finite;
+}>;
+export type RepositoryFoundryGenerationBudgetV1 = typeof RepositoryFoundryGenerationBudgetV1.Type;
+export declare const RepositoryIntegratedHistoryProvenanceV1: Schema.Struct<{
+    readonly method: Schema.Literal<"integrated-retained-history-v1">;
+    readonly requestedRef: Schema.String;
+    readonly requestedTipCommit: Schema.String;
+    readonly requestedTipTree: Schema.String;
+    readonly integrationCommit: Schema.String;
+    readonly pathBlobs: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.String;
+        readonly blob: Schema.String;
+    }>>;
+}>;
+export type RepositoryIntegratedHistoryProvenanceV1 = typeof RepositoryIntegratedHistoryProvenanceV1.Type;
+export declare const REPOSITORY_INTEGRATED_HISTORY_MAXIMUM_PATHS = 32;
+export declare const validIntegratedHistoryProvenanceV1: (proof: RepositoryIntegratedHistoryProvenanceV1) => boolean;
+export declare const RepositoryFoundryGenerationPlanV1: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly planDigest: Schema.String;
+    readonly repository: Schema.Struct<{
+        readonly root: Schema.String;
+        readonly requestedRef: Schema.String;
+        readonly commit: Schema.String;
+        readonly tree: Schema.String;
+    }>;
+    readonly caseId: Schema.String;
+    readonly requestedDimension: Schema.optionalKey<Schema.String>;
+    readonly excludedReferenceCommits: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly historyProvenance: Schema.optionalKey<Schema.Struct<{
+        readonly method: Schema.Literal<"integrated-retained-history-v1">;
+        readonly requestedRef: Schema.String;
+        readonly requestedTipCommit: Schema.String;
+        readonly requestedTipTree: Schema.String;
+        readonly integrationCommit: Schema.String;
+        readonly pathBlobs: Schema.$Array<Schema.Struct<{
+            readonly path: Schema.String;
+            readonly blob: Schema.String;
+        }>>;
+    }>>;
+    readonly validControlRegenerationSequence: Schema.optionalKey<Schema.Finite>;
+    readonly validControlReviewVersion: Schema.optionalKey<Schema.Literals<readonly [1, 2]>>;
+    readonly dependencyContextVersion: Schema.optionalKey<Schema.Literals<readonly [1, 2]>>;
+    readonly oracleCoverageWitnessVersion: Schema.optionalKey<Schema.Literals<readonly [1, 2]>>;
+    readonly oracleCoverageWitnessRepairVersion: Schema.optionalKey<Schema.Literal<1>>;
+    readonly oracleRepairFeedbackVersion: Schema.optionalKey<Schema.Literal<1>>;
+    readonly reviewInputVersion: Schema.optionalKey<Schema.Literal<2>>;
+    readonly specificationContractFactsVersion: Schema.optionalKey<Schema.Literal<1>>;
+    readonly seedId: Schema.String;
+    readonly initialCommit: Schema.String;
+    readonly referenceCommit: Schema.String;
+    readonly modelPlan: Schema.Struct<{
+        readonly version: Schema.Literal<1>;
+        readonly assignments: Schema.$Array<Schema.Struct<{
+            readonly role: Schema.Literals<readonly ["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", "oracle-critic"]>;
+            readonly model: Schema.String;
+            readonly reasoningEffort: Schema.Literals<readonly ["low", "medium", "high", "xhigh", "max", "ultra"]>;
+        }>>;
+    }>;
+    readonly qualification: Schema.Struct<{
+        readonly batches: Schema.Finite;
+        readonly repetitionsPerBatch: Schema.Finite;
+        readonly oracleRepetitions: Schema.Finite;
+        readonly oracleConcurrency: Schema.optionalKey<Schema.Finite>;
+    }>;
+    readonly budget: Schema.Struct<{
+        readonly plannedModelCalls: Schema.Finite;
+        readonly maximumTransientRetries: Schema.Finite;
+        readonly maximumHillClimbAttempts: Schema.Finite;
+        readonly maximumSpecificationRevisions: Schema.optionalKey<Schema.Finite>;
+        readonly maximumOracleCoverageRevisions: Schema.optionalKey<Schema.Finite>;
+        readonly maximumFixtureRepairAttempts: Schema.optionalKey<Schema.Finite>;
+        readonly requiredTotalInputTokens: Schema.Finite;
+        readonly requiredTotalOutputTokens: Schema.Finite;
+        readonly perCallOutputTokens: Schema.Finite;
+        readonly wallTimeMs: Schema.Finite;
+    }>;
+}>;
+export type RepositoryFoundryGenerationPlanV1 = typeof RepositoryFoundryGenerationPlanV1.Type;
+type PlanWithoutDigest = Omit<RepositoryFoundryGenerationPlanV1, "planDigest">;
+export declare function assertRepositoryFoundryReferenceExclusionsV1(references: readonly string[] | undefined): void;
+export declare const repositoryFoundryGenerationBudgetV1: (maximumHillClimbAttempts: number, wallTimeMs?: number, maximumSpecificationRevisions?: number, maximumOracleCoverageRevisions?: number, maximumFixtureRepairAttempts?: number, reviewInputVersion?: 2, specificationContractFactsVersion?: 1) => RepositoryFoundryGenerationBudgetV1;
+export declare const repositoryFoundryGenerationPlanDigestV1: (plan: PlanWithoutDigest) => string;
+export declare function assertRepositoryFoundryGenerationPlanV1(value: unknown): asserts value is RepositoryFoundryGenerationPlanV1;
+export {};