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

package/dist/repository-foundry-plan-protocol.js

@@ -0,0 +1,296 @@
+import { createHash } from "node:crypto";
+import { Schema } from "effect";
+import { EVAL_AUTHORING_REVIEW_REQUEST_BYTES } from "./project-authoring.js";
+import { assertRepositoryFoundryModelPlanV1, REPOSITORY_FOUNDRY_MODEL_ROLES, RepositoryFoundryModelPlanV1 } from "./repository-language-model-protocol.js";
+const REPOSITORY_FOUNDRY_EXPANSIVE_OUTPUT_ROLES = new Set([
+    "oracle-designer",
+    "valid-solution-generator-a",
+    "valid-solution-generator-b",
+    "adversary",
+    "held-out-adversary",
+    "hill-climb-planner"
+]);
+const REPOSITORY_FOUNDRY_BASE_ROLES = REPOSITORY_FOUNDRY_MODEL_ROLES.filter((role) => role !== "hill-climb-planner");
+export const REPOSITORY_FOUNDRY_BASE_MODEL_CALLS = REPOSITORY_FOUNDRY_BASE_ROLES.length;
+export const REPOSITORY_FOUNDRY_TRAJECTORY_REPAIR_ATTEMPTS = 2;
+export const REPOSITORY_FOUNDRY_TRAJECTORY_REPAIR_CALLS = REPOSITORY_FOUNDRY_TRAJECTORY_REPAIR_ATTEMPTS * 2;
+export const REPOSITORY_FOUNDRY_VALID_SOLUTION_REPAIR_ATTEMPTS = 2;
+export const REPOSITORY_FOUNDRY_VALID_SOLUTION_REPAIR_CALLS = REPOSITORY_FOUNDRY_VALID_SOLUTION_REPAIR_ATTEMPTS * 4;
+export const REPOSITORY_FOUNDRY_HELD_OUT_REPAIR_CALLS = 2;
+export const REPOSITORY_FOUNDRY_MAXIMUM_HILL_CLIMB_ATTEMPTS = 3;
+export const REPOSITORY_FOUNDRY_MAXIMUM_SPECIFICATION_REVISIONS = 2;
+export const REPOSITORY_FOUNDRY_MAXIMUM_ORACLE_COVERAGE_REVISIONS = 2;
+export const REPOSITORY_FOUNDRY_MAXIMUM_VALID_CONTROL_REGENERATIONS = 3;
+export const REPOSITORY_FOUNDRY_TRANSIENT_RETRY_RESERVE = 3;
+export const REPOSITORY_FOUNDRY_REQUEST_INPUT_CEILING = 512_000;
+export const REPOSITORY_FOUNDRY_STANDARD_OUTPUT_CEILING = 32_768;
+export const REPOSITORY_FOUNDRY_EXPANSIVE_OUTPUT_CEILING = 65_536;
+export const REPOSITORY_FOUNDRY_PER_CALL_OUTPUT_CEILING = REPOSITORY_FOUNDRY_EXPANSIVE_OUTPUT_CEILING;
+export const repositoryFoundryRoleOutputCeilingV1 = (role) => REPOSITORY_FOUNDRY_EXPANSIVE_OUTPUT_ROLES.has(role)
+    ? REPOSITORY_FOUNDRY_EXPANSIVE_OUTPUT_CEILING
+    : REPOSITORY_FOUNDRY_STANDARD_OUTPUT_CEILING;
+export const REPOSITORY_FOUNDRY_BASE_OUTPUT_CEILING = REPOSITORY_FOUNDRY_BASE_ROLES.reduce((total, role) => total + repositoryFoundryRoleOutputCeilingV1(role), 0);
+export const REPOSITORY_FOUNDRY_HILL_CLIMB_OUTPUT_CEILING = repositoryFoundryRoleOutputCeilingV1("hill-climb-planner");
+export const REPOSITORY_FOUNDRY_DEFAULT_WALL_TIME_MS = 2 * 60 * 60_000;
+export const REPOSITORY_FOUNDRY_MINIMUM_WALL_TIME_MS = 15 * 60_000;
+export const REPOSITORY_FOUNDRY_MAXIMUM_WALL_TIME_MS = 4 * 60 * 60_000;
+export const RepositoryFoundryGenerationBudgetV1 = Schema.Struct({
+    plannedModelCalls: Schema.Finite,
+    maximumTransientRetries: Schema.Finite,
+    maximumHillClimbAttempts: Schema.Finite,
+    maximumSpecificationRevisions: Schema.optionalKey(Schema.Finite),
+    maximumOracleCoverageRevisions: Schema.optionalKey(Schema.Finite),
+    maximumFixtureRepairAttempts: Schema.optionalKey(Schema.Finite),
+    requiredTotalInputTokens: Schema.Finite,
+    requiredTotalOutputTokens: Schema.Finite,
+    perCallOutputTokens: Schema.Finite,
+    wallTimeMs: Schema.Finite
+});
+export const RepositoryIntegratedHistoryProvenanceV1 = Schema.Struct({
+    method: Schema.Literal("integrated-retained-history-v1"),
+    requestedRef: Schema.String,
+    requestedTipCommit: Schema.String,
+    requestedTipTree: Schema.String,
+    integrationCommit: Schema.String,
+    pathBlobs: Schema.Array(Schema.Struct({ path: Schema.String, blob: Schema.String }))
+});
+export const REPOSITORY_INTEGRATED_HISTORY_MAXIMUM_PATHS = 32;
+export const validIntegratedHistoryProvenanceV1 = (proof) => {
+    const objectId = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+    return (proof.method === "integrated-retained-history-v1" &&
+        proof.requestedRef.trim().length > 0 &&
+        [proof.requestedTipCommit, proof.requestedTipTree, proof.integrationCommit].every((value) => objectId.test(value)) &&
+        proof.pathBlobs.length > 0 &&
+        proof.pathBlobs.length <= REPOSITORY_INTEGRATED_HISTORY_MAXIMUM_PATHS &&
+        proof.pathBlobs.every((entry, index) => objectId.test(entry.blob) &&
+            entry.path.length > 0 &&
+            !entry.path.includes("\0") &&
+            !entry.path.includes("\\") &&
+            !entry.path.split("/").some((part) => part === "" || part === "." || part === "..") &&
+            (index === 0 || proof.pathBlobs[index - 1].path < entry.path)));
+};
+export const RepositoryFoundryGenerationPlanV1 = Schema.Struct({
+    version: Schema.Literal(1),
+    planDigest: Schema.String,
+    repository: Schema.Struct({
+        root: Schema.String,
+        requestedRef: Schema.String,
+        commit: Schema.String,
+        tree: Schema.String
+    }),
+    caseId: Schema.String,
+    requestedDimension: Schema.optionalKey(Schema.String),
+    excludedReferenceCommits: Schema.optionalKey(Schema.Array(Schema.String)),
+    historyProvenance: Schema.optionalKey(RepositoryIntegratedHistoryProvenanceV1),
+    validControlRegenerationSequence: Schema.optionalKey(Schema.Finite),
+    validControlReviewVersion: Schema.optionalKey(Schema.Literals([1, 2])),
+    dependencyContextVersion: Schema.optionalKey(Schema.Literals([1, 2])),
+    oracleCoverageWitnessVersion: Schema.optionalKey(Schema.Literals([1, 2])),
+    oracleCoverageWitnessRepairVersion: Schema.optionalKey(Schema.Literal(1)),
+    oracleRepairFeedbackVersion: Schema.optionalKey(Schema.Literal(1)),
+    reviewInputVersion: Schema.optionalKey(Schema.Literal(2)),
+    specificationContractFactsVersion: Schema.optionalKey(Schema.Literal(1)),
+    seedId: Schema.String,
+    initialCommit: Schema.String,
+    referenceCommit: Schema.String,
+    modelPlan: RepositoryFoundryModelPlanV1,
+    qualification: Schema.Struct({
+        batches: Schema.Finite,
+        repetitionsPerBatch: Schema.Finite,
+        oracleRepetitions: Schema.Finite,
+        oracleConcurrency: Schema.optionalKey(Schema.Finite)
+    }),
+    budget: RepositoryFoundryGenerationBudgetV1
+});
+export function assertRepositoryFoundryReferenceExclusionsV1(references) {
+    if (references === undefined)
+        return;
+    if (!Array.isArray(references) ||
+        references.length < 1 ||
+        references.length > 256 ||
+        references.some((reference, index) => typeof reference !== "string" ||
+            !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(reference) ||
+            (index > 0 && references[index - 1] >= reference))) {
+        throw new Error("reference exclusions must contain 1 to 256 sorted unique lowercase full commit SHAs");
+    }
+}
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const repositoryFoundryGenerationBudgetV1 = (maximumHillClimbAttempts, wallTimeMs = REPOSITORY_FOUNDRY_DEFAULT_WALL_TIME_MS, maximumSpecificationRevisions, maximumOracleCoverageRevisions, maximumFixtureRepairAttempts, reviewInputVersion, specificationContractFactsVersion) => {
+    if (specificationContractFactsVersion !== undefined &&
+        (specificationContractFactsVersion !== 1 || maximumSpecificationRevisions === undefined))
+        throw new Error("specification contract facts require version 1 and an explicit specification revision allowance");
+    if (reviewInputVersion !== undefined && reviewInputVersion !== 2)
+        throw new Error("repository foundry complete review input version must be 2");
+    if (maximumFixtureRepairAttempts !== undefined &&
+        (!Number.isSafeInteger(maximumFixtureRepairAttempts) ||
+            maximumFixtureRepairAttempts < 0 ||
+            maximumFixtureRepairAttempts > 3)) {
+        throw new Error("repository foundry fixture repairs must be an integer from 0 to 3");
+    }
+    if (maximumSpecificationRevisions !== undefined &&
+        (!Number.isSafeInteger(maximumSpecificationRevisions) ||
+            maximumSpecificationRevisions < 0 ||
+            maximumSpecificationRevisions > REPOSITORY_FOUNDRY_MAXIMUM_SPECIFICATION_REVISIONS)) {
+        throw new Error("repository foundry specification revisions must be an integer from 0 to 2");
+    }
+    const specificationRevisions = maximumSpecificationRevisions ?? 0;
+    // The base analyst is already reserved. Each marked revision adds exactly
+    // one private analyst clarification before the existing writer and critics.
+    const specificationContractFactCalls = specificationContractFactsVersion === 1 ? specificationRevisions : 0;
+    if (maximumOracleCoverageRevisions !== undefined &&
+        (!Number.isSafeInteger(maximumOracleCoverageRevisions) ||
+            maximumOracleCoverageRevisions < 0 ||
+            maximumOracleCoverageRevisions > REPOSITORY_FOUNDRY_MAXIMUM_ORACLE_COVERAGE_REVISIONS)) {
+        throw new Error("repository foundry oracle coverage revisions must be an integer from 0 to 2");
+    }
+    const oracleCoverageCalls = maximumOracleCoverageRevisions === undefined ? 0 : 2 + maximumOracleCoverageRevisions * 2;
+    const oracleCoverageOutput = maximumOracleCoverageRevisions === undefined
+        ? 0
+        : 2 * repositoryFoundryRoleOutputCeilingV1("oracle-critic") +
+            maximumOracleCoverageRevisions *
+                (repositoryFoundryRoleOutputCeilingV1("oracle-critic") +
+                    repositoryFoundryRoleOutputCeilingV1("oracle-designer"));
+    const boundedAttempts = Math.max(0, Math.min(Math.trunc(maximumHillClimbAttempts), REPOSITORY_FOUNDRY_MAXIMUM_HILL_CLIMB_ATTEMPTS));
+    const semanticModelCalls = REPOSITORY_FOUNDRY_BASE_MODEL_CALLS +
+        REPOSITORY_FOUNDRY_TRAJECTORY_REPAIR_CALLS +
+        REPOSITORY_FOUNDRY_VALID_SOLUTION_REPAIR_CALLS +
+        REPOSITORY_FOUNDRY_HELD_OUT_REPAIR_CALLS +
+        specificationRevisions * 3 +
+        specificationContractFactCalls +
+        oracleCoverageCalls +
+        (maximumFixtureRepairAttempts ?? 0) +
+        boundedAttempts;
+    const plannedModelCalls = semanticModelCalls + REPOSITORY_FOUNDRY_TRANSIENT_RETRY_RESERVE;
+    return {
+        plannedModelCalls,
+        maximumTransientRetries: REPOSITORY_FOUNDRY_TRANSIENT_RETRY_RESERVE,
+        maximumHillClimbAttempts: boundedAttempts,
+        ...(maximumSpecificationRevisions === undefined ? {} : { maximumSpecificationRevisions }),
+        ...(maximumOracleCoverageRevisions === undefined ? {} : { maximumOracleCoverageRevisions }),
+        ...(maximumFixtureRepairAttempts === undefined ? {} : { maximumFixtureRepairAttempts }),
+        requiredTotalInputTokens: plannedModelCalls * REPOSITORY_FOUNDRY_REQUEST_INPUT_CEILING +
+            (reviewInputVersion === 2
+                ? (1 + REPOSITORY_FOUNDRY_TRANSIENT_RETRY_RESERVE) *
+                    (EVAL_AUTHORING_REVIEW_REQUEST_BYTES - REPOSITORY_FOUNDRY_REQUEST_INPUT_CEILING)
+                : 0),
+        requiredTotalOutputTokens: REPOSITORY_FOUNDRY_BASE_OUTPUT_CEILING +
+            oracleCoverageOutput +
+            specificationContractFactCalls * repositoryFoundryRoleOutputCeilingV1("repository-analyst") +
+            specificationRevisions *
+                (repositoryFoundryRoleOutputCeilingV1("specification-writer") +
+                    repositoryFoundryRoleOutputCeilingV1("specification-critic-a") +
+                    repositoryFoundryRoleOutputCeilingV1("specification-critic-b")) +
+            REPOSITORY_FOUNDRY_TRAJECTORY_REPAIR_CALLS * REPOSITORY_FOUNDRY_STANDARD_OUTPUT_CEILING +
+            REPOSITORY_FOUNDRY_VALID_SOLUTION_REPAIR_ATTEMPTS *
+                (repositoryFoundryRoleOutputCeilingV1("valid-solution-generator-a") +
+                    repositoryFoundryRoleOutputCeilingV1("valid-solution-generator-b") +
+                    repositoryFoundryRoleOutputCeilingV1("solution-critic-a") +
+                    repositoryFoundryRoleOutputCeilingV1("solution-critic-b")) +
+            REPOSITORY_FOUNDRY_HELD_OUT_REPAIR_CALLS *
+                repositoryFoundryRoleOutputCeilingV1("held-out-adversary") +
+            (boundedAttempts +
+                (maximumFixtureRepairAttempts ?? 0) +
+                REPOSITORY_FOUNDRY_TRANSIENT_RETRY_RESERVE) *
+                REPOSITORY_FOUNDRY_HILL_CLIMB_OUTPUT_CEILING,
+        perCallOutputTokens: REPOSITORY_FOUNDRY_PER_CALL_OUTPUT_CEILING,
+        wallTimeMs
+    };
+};
+export const repositoryFoundryGenerationPlanDigestV1 = (plan) => digest(plan);
+export function assertRepositoryFoundryGenerationPlanV1(value) {
+    const plan = Schema.decodeUnknownSync(RepositoryFoundryGenerationPlanV1)(value);
+    assertRepositoryFoundryModelPlanV1(plan.modelPlan);
+    if (plan.specificationContractFactsVersion !== undefined &&
+        plan.budget.maximumSpecificationRevisions === undefined)
+        throw new Error("specification contract facts require an explicit specification revision allowance");
+    if (plan.oracleCoverageWitnessRepairVersion !== undefined &&
+        (plan.oracleCoverageWitnessVersion === undefined ||
+            plan.budget.maximumFixtureRepairAttempts === undefined)) {
+        throw new Error("coverage witness repair budgeting requires versioned witnesses and an explicit fixture repair allowance");
+    }
+    if (plan.oracleCoverageWitnessVersion !== undefined &&
+        (plan.budget.maximumOracleCoverageRevisions === undefined ||
+            plan.budget.maximumOracleCoverageRevisions < 1)) {
+        throw new Error("executable coverage witnesses require a nonzero coverage allowance");
+    }
+    if (plan.budget.maximumOracleCoverageRevisions !== undefined &&
+        (plan.budget.maximumSpecificationRevisions === undefined ||
+            !plan.modelPlan.assignments.some((assignment) => assignment.role === "oracle-critic"))) {
+        throw new Error("oracle coverage review requires pinned reference grounding and an assigned oracle critic");
+    }
+    assertRepositoryFoundryReferenceExclusionsV1(plan.excludedReferenceCommits);
+    if (plan.excludedReferenceCommits?.includes(plan.referenceCommit)) {
+        throw new Error("repository foundry generation plan selected an excluded reference commit");
+    }
+    if (plan.historyProvenance !== undefined &&
+        !validIntegratedHistoryProvenanceV1(plan.historyProvenance)) {
+        throw new Error("repository foundry integrated history provenance is invalid");
+    }
+    const integers = [
+        plan.qualification.batches,
+        plan.qualification.repetitionsPerBatch,
+        plan.qualification.oracleRepetitions,
+        ...(plan.qualification.oracleConcurrency === undefined
+            ? []
+            : [plan.qualification.oracleConcurrency]),
+        ...(plan.validControlRegenerationSequence === undefined
+            ? []
+            : [plan.validControlRegenerationSequence]),
+        plan.budget.plannedModelCalls,
+        plan.budget.maximumTransientRetries,
+        plan.budget.maximumHillClimbAttempts,
+        ...(plan.budget.maximumSpecificationRevisions === undefined
+            ? []
+            : [plan.budget.maximumSpecificationRevisions]),
+        ...(plan.budget.maximumOracleCoverageRevisions === undefined
+            ? []
+            : [plan.budget.maximumOracleCoverageRevisions]),
+        ...(plan.budget.maximumFixtureRepairAttempts === undefined
+            ? []
+            : [plan.budget.maximumFixtureRepairAttempts]),
+        plan.budget.requiredTotalInputTokens,
+        plan.budget.requiredTotalOutputTokens,
+        plan.budget.perCallOutputTokens,
+        plan.budget.wallTimeMs
+    ];
+    if (plan.caseId.trim().length === 0 ||
+        (plan.requestedDimension !== undefined &&
+            (plan.requestedDimension.length === 0 ||
+                plan.requestedDimension.length > 2000 ||
+                plan.requestedDimension !== plan.requestedDimension.trim())) ||
+        plan.seedId.trim().length === 0 ||
+        plan.repository.root.trim().length === 0 ||
+        plan.repository.commit.trim().length === 0 ||
+        plan.repository.tree.trim().length === 0 ||
+        plan.initialCommit.trim().length === 0 ||
+        plan.referenceCommit.trim().length === 0 ||
+        integers.some((entry) => !Number.isSafeInteger(entry) || entry < 0) ||
+        plan.qualification.batches < 2 ||
+        plan.qualification.repetitionsPerBatch < 2 ||
+        plan.qualification.oracleRepetitions < 2 ||
+        (plan.qualification.oracleConcurrency !== undefined &&
+            (plan.qualification.oracleConcurrency < 1 || plan.qualification.oracleConcurrency > 4)) ||
+        (plan.validControlRegenerationSequence !== undefined &&
+            (plan.validControlRegenerationSequence < 1 ||
+                plan.validControlRegenerationSequence >
+                    REPOSITORY_FOUNDRY_MAXIMUM_VALID_CONTROL_REGENERATIONS)) ||
+        plan.budget.maximumHillClimbAttempts > REPOSITORY_FOUNDRY_MAXIMUM_HILL_CLIMB_ATTEMPTS ||
+        (plan.budget.maximumSpecificationRevisions !== undefined &&
+            plan.budget.maximumSpecificationRevisions >
+                REPOSITORY_FOUNDRY_MAXIMUM_SPECIFICATION_REVISIONS) ||
+        (plan.budget.maximumOracleCoverageRevisions !== undefined &&
+            plan.budget.maximumOracleCoverageRevisions >
+                REPOSITORY_FOUNDRY_MAXIMUM_ORACLE_COVERAGE_REVISIONS) ||
+        (plan.budget.maximumFixtureRepairAttempts !== undefined &&
+            plan.budget.maximumFixtureRepairAttempts > 3) ||
+        plan.budget.wallTimeMs < REPOSITORY_FOUNDRY_MINIMUM_WALL_TIME_MS ||
+        plan.budget.wallTimeMs > REPOSITORY_FOUNDRY_MAXIMUM_WALL_TIME_MS) {
+        throw new Error("repository foundry generation plan contains invalid identifiers, qualification bounds, or execution bounds");
+    }
+    const expectedBudget = repositoryFoundryGenerationBudgetV1(plan.budget.maximumHillClimbAttempts, plan.budget.wallTimeMs, plan.budget.maximumSpecificationRevisions, plan.budget.maximumOracleCoverageRevisions, plan.budget.maximumFixtureRepairAttempts, plan.reviewInputVersion, plan.specificationContractFactsVersion);
+    if (JSON.stringify(plan.budget) !== JSON.stringify(expectedBudget) ||
+        plan.planDigest !==
+            repositoryFoundryGenerationPlanDigestV1((({ planDigest: _planDigest, ...withoutDigest }) => withoutDigest)(plan))) {
+        throw new Error("repository foundry generation plan digest or immutable budget is invalid");
+    }
+}

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

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+/**
+ * Runtime execute progress for repository foundry. Not part of the immutable
+ * generation plan / digest — idle stall is a fail-closed execute watchdog.
+ */
+export declare const REPOSITORY_FOUNDRY_DEFAULT_IDLE_STALL_MS: number;
+export declare const REPOSITORY_FOUNDRY_MINIMUM_IDLE_STALL_MS = 60000;
+export declare const REPOSITORY_FOUNDRY_MAXIMUM_IDLE_STALL_MS: number;
+export declare const REPOSITORY_FOUNDRY_PROGRESS_STAGES: readonly ["execute-start", "replay-qualify", "author-specification", "trajectory-policy", "oracle-design", "valid-solutions", "adversaries", "tournament", "hill-climb", "held-out-tournament", "quality-review", "compile-reviewed-case", "admit", "execute-complete"];
+export declare const RepositoryFoundryProgressStageV1: Schema.Literals<readonly ["execute-start", "replay-qualify", "author-specification", "trajectory-policy", "oracle-design", "valid-solutions", "adversaries", "tournament", "hill-climb", "held-out-tournament", "quality-review", "compile-reviewed-case", "admit", "execute-complete"]>;
+export type RepositoryFoundryProgressStageV1 = typeof RepositoryFoundryProgressStageV1.Type;
+export type RepositoryFoundryProgressSnapshotV1 = {
+    readonly stage: RepositoryFoundryProgressStageV1;
+    readonly modelCalls: number;
+    readonly lastProgressAtMs: number;
+    readonly lastEventKind: "stage" | "model-call" | "heartbeat";
+};
+export type RepositoryFoundryProgressEventV1 = {
+    readonly version: 1;
+    readonly at: string;
+    readonly kind: "stage" | "model-call" | "heartbeat";
+    readonly stage: RepositoryFoundryProgressStageV1;
+    readonly modelCalls: number;
+    readonly role?: string;
+    readonly phase?: "start" | "complete" | "failed" | "activity";
+    readonly operationId?: string;
+    readonly callId?: string;
+    readonly detail?: string;
+};
+/** Private authoring evidence. Never include this payload in terminal progress events. */
+export type RepositoryFoundryAuthoringArtifactV1 = {
+    readonly version: 1;
+    readonly operationId: string;
+    readonly role: string;
+    readonly model: string;
+    readonly reasoningEffort: string;
+    readonly schemaName: string;
+    readonly validation: "received" | "validated";
+    readonly request: {
+        readonly instructions: string;
+        readonly input: unknown;
+        readonly jsonSchema: Readonly<Record<string, unknown>>;
+        readonly maximumOutputTokens: number;
+    };
+    readonly response: {
+        readonly text: string;
+        readonly callId?: string;
+    };
+    readonly value?: unknown;
+};
+export declare const formatRepositoryFoundryProgressLineV1: (event: RepositoryFoundryProgressEventV1) => string;
+export declare const boundRepositoryFoundryIdleStallMsV1: (idleStallMs: number | undefined, wallTimeMs: number) => number;

package/dist/repository-foundry-progress-protocol.js

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+/**
+ * Runtime execute progress for repository foundry. Not part of the immutable
+ * generation plan / digest — idle stall is a fail-closed execute watchdog.
+ */
+export const REPOSITORY_FOUNDRY_DEFAULT_IDLE_STALL_MS = 20 * 60_000;
+export const REPOSITORY_FOUNDRY_MINIMUM_IDLE_STALL_MS = 60_000;
+export const REPOSITORY_FOUNDRY_MAXIMUM_IDLE_STALL_MS = 4 * 60 * 60_000;
+export const REPOSITORY_FOUNDRY_PROGRESS_STAGES = [
+    "execute-start",
+    "replay-qualify",
+    "author-specification",
+    "trajectory-policy",
+    "oracle-design",
+    "valid-solutions",
+    "adversaries",
+    "tournament",
+    "hill-climb",
+    "held-out-tournament",
+    "quality-review",
+    "compile-reviewed-case",
+    "admit",
+    "execute-complete"
+];
+export const RepositoryFoundryProgressStageV1 = Schema.Literals(REPOSITORY_FOUNDRY_PROGRESS_STAGES);
+export const formatRepositoryFoundryProgressLineV1 = (event) => {
+    const parts = [
+        "foundry progress",
+        `kind=${event.kind}`,
+        `stage=${event.stage}`,
+        `modelCalls=${String(event.modelCalls)}`
+    ];
+    if (event.role !== undefined)
+        parts.push(`role=${event.role}`);
+    if (event.phase !== undefined)
+        parts.push(`phase=${event.phase}`);
+    if (event.operationId !== undefined)
+        parts.push(`operationId=${event.operationId}`);
+    if (event.callId !== undefined)
+        parts.push(`callId=${event.callId}`);
+    if (event.detail !== undefined)
+        parts.push(`detail=${event.detail}`);
+    return parts.join(" ");
+};
+export const boundRepositoryFoundryIdleStallMsV1 = (idleStallMs, wallTimeMs) => {
+    const requested = idleStallMs === undefined ? REPOSITORY_FOUNDRY_DEFAULT_IDLE_STALL_MS : Math.trunc(idleStallMs);
+    if (!Number.isSafeInteger(requested) || requested < 1) {
+        throw new Error("idleStallMs must be a positive safe integer");
+    }
+    const wall = Number.isSafeInteger(wallTimeMs) && wallTimeMs > 0 ? wallTimeMs : requested;
+    return Math.min(requested, wall);
+};

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

@@ -0,0 +1,100 @@
+import { Schema } from "effect";
+export declare const RepositoryFoundryImprovementTriggerV1: Schema.Literals<readonly ["new-authentic-work", "oracle-escape", "false-rejection", "coverage-gap", "instability", "environment-drift", "contract-drift", "realism-drift", "semantic-duplicate", "superseded"]>;
+export type RepositoryFoundryImprovementTriggerV1 = typeof RepositoryFoundryImprovementTriggerV1.Type;
+export declare const RepositoryFoundryImprovementActionV1: Schema.Literals<readonly ["add-seed", "add-fixture", "strengthen-oracle", "add-valid-alternative", "regenerate-specification", "quarantine-case", "retire-case"]>;
+export type RepositoryFoundryImprovementActionV1 = typeof RepositoryFoundryImprovementActionV1.Type;
+export declare const RepositoryFoundryImprovementReviewV1: Schema.Struct<{
+    readonly reviewerId: Schema.String;
+    readonly independentlyProduced: Schema.Boolean;
+    readonly verdict: Schema.Literals<readonly ["approve", "reject"]>;
+    readonly detail: Schema.String;
+}>;
+export type RepositoryFoundryImprovementReviewV1 = typeof RepositoryFoundryImprovementReviewV1.Type;
+export declare const RepositoryFoundryImprovementDraftV1: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly trigger: Schema.Literals<readonly ["new-authentic-work", "oracle-escape", "false-rejection", "coverage-gap", "instability", "environment-drift", "contract-drift", "realism-drift", "semantic-duplicate", "superseded"]>;
+    readonly action: Schema.Literals<readonly ["add-seed", "add-fixture", "strengthen-oracle", "add-valid-alternative", "regenerate-specification", "quarantine-case", "retire-case"]>;
+    readonly summary: Schema.String;
+    readonly affectedCaseIds: Schema.$Array<Schema.String>;
+    readonly evidence: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["package", "public-surface", "symbol", "protocol", "schema", "test", "command", "history-episode", "workload-signal", "documentation"]>;
+        readonly id: Schema.String;
+        readonly path: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly reviews: Schema.$Array<Schema.Struct<{
+        readonly reviewerId: Schema.String;
+        readonly independentlyProduced: Schema.Boolean;
+        readonly verdict: Schema.Literals<readonly ["approve", "reject"]>;
+        readonly detail: Schema.String;
+    }>>;
+}>;
+export type RepositoryFoundryImprovementDraftV1 = typeof RepositoryFoundryImprovementDraftV1.Type;
+export declare const RepositoryFoundryImprovementRecordV1: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly id: Schema.String;
+    readonly trigger: Schema.Literals<readonly ["new-authentic-work", "oracle-escape", "false-rejection", "coverage-gap", "instability", "environment-drift", "contract-drift", "realism-drift", "semantic-duplicate", "superseded"]>;
+    readonly action: Schema.Literals<readonly ["add-seed", "add-fixture", "strengthen-oracle", "add-valid-alternative", "regenerate-specification", "quarantine-case", "retire-case"]>;
+    readonly summary: Schema.String;
+    readonly affectedCaseIds: Schema.$Array<Schema.String>;
+    readonly evidence: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["package", "public-surface", "symbol", "protocol", "schema", "test", "command", "history-episode", "workload-signal", "documentation"]>;
+        readonly id: Schema.String;
+        readonly path: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly reviews: Schema.$Array<Schema.Struct<{
+        readonly reviewerId: Schema.String;
+        readonly independentlyProduced: Schema.Boolean;
+        readonly verdict: Schema.Literals<readonly ["approve", "reject"]>;
+        readonly detail: Schema.String;
+    }>>;
+    readonly decision: Schema.Literals<readonly ["applied", "rejected"]>;
+    readonly rejectionReasons: Schema.$Array<Schema.String>;
+}>;
+export type RepositoryFoundryImprovementRecordV1 = typeof RepositoryFoundryImprovementRecordV1.Type;
+export declare const RepositoryBenchmarkLifecycleStateV1: Schema.Literals<readonly ["active", "audited-core", "quarantined", "retired"]>;
+export type RepositoryBenchmarkLifecycleStateV1 = typeof RepositoryBenchmarkLifecycleStateV1.Type;
+export declare const RepositoryBenchmarkLifecycleEntryV1: Schema.Struct<{
+    readonly caseId: Schema.String;
+    readonly state: Schema.Literals<readonly ["active", "audited-core", "quarantined", "retired"]>;
+    readonly improvementRecordId: Schema.optionalKey<Schema.String>;
+    readonly reason: Schema.String;
+}>;
+export type RepositoryBenchmarkLifecycleEntryV1 = typeof RepositoryBenchmarkLifecycleEntryV1.Type;
+export declare const RepositoryFoundryImprovementCycleV1: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly cycleId: Schema.String;
+    readonly inputCaseIds: Schema.$Array<Schema.String>;
+    readonly records: Schema.$Array<Schema.Struct<{
+        readonly version: Schema.Literal<1>;
+        readonly id: Schema.String;
+        readonly trigger: Schema.Literals<readonly ["new-authentic-work", "oracle-escape", "false-rejection", "coverage-gap", "instability", "environment-drift", "contract-drift", "realism-drift", "semantic-duplicate", "superseded"]>;
+        readonly action: Schema.Literals<readonly ["add-seed", "add-fixture", "strengthen-oracle", "add-valid-alternative", "regenerate-specification", "quarantine-case", "retire-case"]>;
+        readonly summary: Schema.String;
+        readonly affectedCaseIds: Schema.$Array<Schema.String>;
+        readonly evidence: Schema.$Array<Schema.Struct<{
+            readonly kind: Schema.Literals<readonly ["package", "public-surface", "symbol", "protocol", "schema", "test", "command", "history-episode", "workload-signal", "documentation"]>;
+            readonly id: Schema.String;
+            readonly path: Schema.optionalKey<Schema.String>;
+        }>>;
+        readonly reviews: Schema.$Array<Schema.Struct<{
+            readonly reviewerId: Schema.String;
+            readonly independentlyProduced: Schema.Boolean;
+            readonly verdict: Schema.Literals<readonly ["approve", "reject"]>;
+            readonly detail: Schema.String;
+        }>>;
+        readonly decision: Schema.Literals<readonly ["applied", "rejected"]>;
+        readonly rejectionReasons: Schema.$Array<Schema.String>;
+    }>>;
+    readonly lifecycle: Schema.$Array<Schema.Struct<{
+        readonly caseId: Schema.String;
+        readonly state: Schema.Literals<readonly ["active", "audited-core", "quarantined", "retired"]>;
+        readonly improvementRecordId: Schema.optionalKey<Schema.String>;
+        readonly reason: Schema.String;
+    }>>;
+    readonly activeCaseIds: Schema.$Array<Schema.String>;
+    readonly auditedCoreCaseIds: Schema.$Array<Schema.String>;
+    readonly quarantinedCaseIds: Schema.$Array<Schema.String>;
+    readonly retiredCaseIds: Schema.$Array<Schema.String>;
+}>;
+export type RepositoryFoundryImprovementCycleV1 = typeof RepositoryFoundryImprovementCycleV1.Type;
+export declare function assertRepositoryFoundryImprovementCycleV1(value: unknown): asserts value is RepositoryFoundryImprovementCycleV1;

package/dist/repository-improvement-protocol.js

@@ -0,0 +1,106 @@
+import { Schema } from "effect";
+import { RepositoryEvidenceRefV1 } from "./repository-behavior-protocol.js";
+export const RepositoryFoundryImprovementTriggerV1 = Schema.Literals([
+    "new-authentic-work",
+    "oracle-escape",
+    "false-rejection",
+    "coverage-gap",
+    "instability",
+    "environment-drift",
+    "contract-drift",
+    "realism-drift",
+    "semantic-duplicate",
+    "superseded"
+]);
+export const RepositoryFoundryImprovementActionV1 = Schema.Literals([
+    "add-seed",
+    "add-fixture",
+    "strengthen-oracle",
+    "add-valid-alternative",
+    "regenerate-specification",
+    "quarantine-case",
+    "retire-case"
+]);
+export const RepositoryFoundryImprovementReviewV1 = Schema.Struct({
+    reviewerId: Schema.String,
+    independentlyProduced: Schema.Boolean,
+    verdict: Schema.Literals(["approve", "reject"]),
+    detail: Schema.String
+});
+export const RepositoryFoundryImprovementDraftV1 = Schema.Struct({
+    id: Schema.String,
+    trigger: RepositoryFoundryImprovementTriggerV1,
+    action: RepositoryFoundryImprovementActionV1,
+    summary: Schema.String,
+    affectedCaseIds: Schema.Array(Schema.String),
+    evidence: Schema.Array(RepositoryEvidenceRefV1),
+    reviews: Schema.Array(RepositoryFoundryImprovementReviewV1)
+});
+export const RepositoryFoundryImprovementRecordV1 = Schema.Struct({
+    version: Schema.Literal(1),
+    id: Schema.String,
+    trigger: RepositoryFoundryImprovementTriggerV1,
+    action: RepositoryFoundryImprovementActionV1,
+    summary: Schema.String,
+    affectedCaseIds: Schema.Array(Schema.String),
+    evidence: Schema.Array(RepositoryEvidenceRefV1),
+    reviews: Schema.Array(RepositoryFoundryImprovementReviewV1),
+    decision: Schema.Literals(["applied", "rejected"]),
+    rejectionReasons: Schema.Array(Schema.String)
+});
+export const RepositoryBenchmarkLifecycleStateV1 = Schema.Literals([
+    "active",
+    "audited-core",
+    "quarantined",
+    "retired"
+]);
+export const RepositoryBenchmarkLifecycleEntryV1 = Schema.Struct({
+    caseId: Schema.String,
+    state: RepositoryBenchmarkLifecycleStateV1,
+    improvementRecordId: Schema.optionalKey(Schema.String),
+    reason: Schema.String
+});
+export const RepositoryFoundryImprovementCycleV1 = Schema.Struct({
+    version: Schema.Literal(1),
+    cycleId: Schema.String,
+    inputCaseIds: Schema.Array(Schema.String),
+    records: Schema.Array(RepositoryFoundryImprovementRecordV1),
+    lifecycle: Schema.Array(RepositoryBenchmarkLifecycleEntryV1),
+    activeCaseIds: Schema.Array(Schema.String),
+    auditedCoreCaseIds: Schema.Array(Schema.String),
+    quarantinedCaseIds: Schema.Array(Schema.String),
+    retiredCaseIds: Schema.Array(Schema.String)
+});
+export function assertRepositoryFoundryImprovementCycleV1(value) {
+    const cycle = Schema.decodeUnknownSync(RepositoryFoundryImprovementCycleV1)(value);
+    const inputCaseIds = new Set(cycle.inputCaseIds);
+    const recordIds = new Set(cycle.records.map((record) => record.id));
+    const lifecycleCaseIds = new Set(cycle.lifecycle.map((entry) => entry.caseId));
+    if (inputCaseIds.size !== cycle.inputCaseIds.length ||
+        recordIds.size !== cycle.records.length ||
+        lifecycleCaseIds.size !== cycle.lifecycle.length ||
+        lifecycleCaseIds.size !== inputCaseIds.size ||
+        [...lifecycleCaseIds].some((caseId) => !inputCaseIds.has(caseId))) {
+        throw new Error("repository foundry improvement cycle requires unique, complete case and record identities");
+    }
+    const byState = (state) => cycle.lifecycle
+        .filter((entry) => entry.state === state)
+        .map((entry) => entry.caseId)
+        .sort();
+    if (JSON.stringify([...cycle.activeCaseIds].sort()) !==
+        JSON.stringify(byState("active")) ||
+        JSON.stringify([...cycle.auditedCoreCaseIds].sort()) !==
+            JSON.stringify(byState("audited-core")) ||
+        JSON.stringify([...cycle.quarantinedCaseIds].sort()) !==
+            JSON.stringify(byState("quarantined")) ||
+        JSON.stringify([...cycle.retiredCaseIds].sort()) !==
+            JSON.stringify(byState("retired"))) {
+        throw new Error("repository foundry improvement lifecycle projections must match entry states");
+    }
+    for (const entry of cycle.lifecycle) {
+        if (entry.improvementRecordId !== undefined &&
+            !recordIds.has(entry.improvementRecordId)) {
+            throw new Error("repository foundry lifecycle refers to an unknown improvement record");
+        }
+    }
+}