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

package/dist/evaluation-grader-calibration.js

@@ -0,0 +1,334 @@
+import { createHash } from "node:crypto";
+import { Schema } from "effect";
+import { EVAL_GRADER_JUDGE_PROTOCOL_VERSION, EVAL_GRADER_MINIMUM_SCORE, EVAL_GRADER_SYSTEM_PROMPT, renderEvaluationCandidatePrompt } from "./evaluation-grading-policy.js";
+import { EVAL_GRADER_CALIBRATION_POLICY_VERSION, EvalGraderCalibrationObservation as CalibrationObservationSchema, EvalGraderCalibrationPlan as CalibrationPlanSchema, EvalGraderCalibrationReport as CalibrationReportSchema } from "./evaluation-grader-calibration-protocol.js";
+import { assertEvaluationStructure, candidateCaseProjection, hiddenOracleProjection } from "./evaluation-structure-policy.js";
+import { assertEvaluationProposal } from "./evaluation-proposal-policy.js";
+export { EVAL_GRADER_CALIBRATION_POLICY_VERSION, EvalGraderCalibrationControl, EvalGraderCalibrationObservation, EvalGraderCalibrationPlan, EvalGraderCalibrationReport, EvalGraderCalibrationResult } from "./evaluation-grader-calibration-protocol.js";
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const stableCompare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const controlSemantic = (control) => ({
+    suiteKind: control.suiteKind,
+    suiteId: control.suiteId,
+    caseId: control.caseId,
+    authoredControlId: control.authoredControlId,
+    kind: control.kind,
+    targetedCriterionIds: control.targetedCriterionIds,
+    expectedOutcome: control.expectedOutcome,
+    prompt: control.prompt,
+    criteria: control.criteria,
+    response: control.response
+});
+const compileControl = (control) => {
+    const controlDigest = sha256(JSON.stringify(controlSemantic(control)));
+    return {
+        ...control,
+        id: `cal_${controlDigest}`,
+        controlDigest
+    };
+};
+const controlsForCase = (testCase, suiteKind, suiteId) => {
+    const candidate = candidateCaseProjection(testCase);
+    const oracle = hiddenOracleProjection(testCase);
+    const common = {
+        suiteKind,
+        suiteId,
+        caseId: testCase.id,
+        prompt: renderEvaluationCandidatePrompt(candidate),
+        criteria: oracle.rubric
+    };
+    return [
+        ...oracle.positiveControls.map((control) => compileControl({
+            ...common,
+            authoredControlId: control.id,
+            kind: "positive",
+            targetedCriterionIds: [],
+            expectedOutcome: "accept",
+            response: control.response
+        })),
+        ...oracle.negativeControls.map((control) => compileControl({
+            ...common,
+            authoredControlId: control.id,
+            kind: control.kind,
+            targetedCriterionIds: [...control.targetedCriterionIds].sort(stableCompare),
+            expectedOutcome: "reject",
+            response: control.response
+        }))
+    ];
+};
+const planSemantic = (plan) => ({
+    version: plan.version,
+    policyVersion: plan.policyVersion,
+    evaluationDigest: plan.evaluationDigest,
+    judgeProtocolVersion: plan.judgeProtocolVersion,
+    judgeModel: plan.judgeModel,
+    judgeReasoningEffort: plan.judgeReasoningEffort,
+    judgeSystemPrompt: plan.judgeSystemPrompt,
+    minimumJudgeScore: plan.minimumJudgeScore,
+    callCount: plan.callCount,
+    controls: plan.controls
+});
+const expectedPlanDigest = (plan) => sha256(JSON.stringify(planSemantic(plan)));
+const reportSemantic = (report) => ({
+    version: report.version,
+    policyVersion: report.policyVersion,
+    planDigest: report.planDigest,
+    evaluationDigest: report.evaluationDigest,
+    judgeProtocolVersion: report.judgeProtocolVersion,
+    judgeModel: report.judgeModel,
+    judgeReasoningEffort: report.judgeReasoningEffort,
+    judgeSystemPrompt: report.judgeSystemPrompt,
+    minimumJudgeScore: report.minimumJudgeScore,
+    startedAt: report.startedAt,
+    finishedAt: report.finishedAt,
+    callCount: report.callCount,
+    acceptedCount: report.acceptedCount,
+    rejectedCount: report.rejectedCount,
+    matchedCount: report.matchedCount,
+    passed: report.passed,
+    results: report.results
+});
+export const evaluationGraderCalibrationReportDigest = (report) => sha256(JSON.stringify(reportSemantic(report)));
+const assertNonEmpty = (value, label) => {
+    if (value.trim().length === 0) {
+        throw new Error(`${label} must not be empty`);
+    }
+};
+const assertPlan = (plan) => {
+    Schema.decodeSync(CalibrationPlanSchema)(plan);
+    if (plan.policyVersion !== EVAL_GRADER_CALIBRATION_POLICY_VERSION ||
+        plan.judgeProtocolVersion !== EVAL_GRADER_JUDGE_PROTOCOL_VERSION) {
+        throw new Error("grader calibration plan uses an unsupported policy version");
+    }
+    if (plan.minimumJudgeScore !== EVAL_GRADER_MINIMUM_SCORE ||
+        plan.judgeSystemPrompt !== EVAL_GRADER_SYSTEM_PROMPT) {
+        throw new Error("grader calibration plan does not bind the current judge policy");
+    }
+    assertNonEmpty(plan.evaluationDigest, "evaluation digest");
+    assertNonEmpty(plan.judgeModel, "grader calibration judge model");
+    if (plan.callCount !== plan.controls.length || plan.callCount < 1) {
+        throw new Error("grader calibration plan call count is inconsistent");
+    }
+    if (new Set(plan.controls.map((control) => control.id)).size !==
+        plan.controls.length) {
+        throw new Error("grader calibration control ids must be unique");
+    }
+    for (const control of plan.controls) {
+        assertNonEmpty(control.suiteId, "grader calibration suite id");
+        assertNonEmpty(control.caseId, "grader calibration case id");
+        assertNonEmpty(control.authoredControlId, "authored control id");
+        assertNonEmpty(control.criteria, "grader calibration criteria");
+        assertNonEmpty(control.prompt, "grader calibration prompt");
+        assertNonEmpty(control.response, "grader calibration response");
+        const canonicalTargetIds = [...new Set(control.targetedCriterionIds)].sort(stableCompare);
+        if ((control.kind === "positive" &&
+            (control.expectedOutcome !== "accept" ||
+                control.targetedCriterionIds.length !== 0)) ||
+            (control.kind !== "positive" &&
+                (control.expectedOutcome !== "reject" ||
+                    control.targetedCriterionIds.length === 0 ||
+                    control.targetedCriterionIds.length !== canonicalTargetIds.length ||
+                    control.targetedCriterionIds.some((criterionId, index) => criterionId !== canonicalTargetIds[index])))) {
+            throw new Error(`grader calibration control ${JSON.stringify(control.id)} has inconsistent semantics`);
+        }
+        const digest = sha256(JSON.stringify(controlSemantic(control)));
+        if (control.controlDigest !== digest ||
+            control.id !== `cal_${digest}`) {
+            throw new Error(`grader calibration control ${JSON.stringify(control.id)} digest is stale`);
+        }
+    }
+    const { planDigest: _planDigest, ...withoutDigest } = plan;
+    if (plan.planDigest !== expectedPlanDigest(withoutDigest)) {
+        throw new Error("grader calibration plan digest is stale");
+    }
+};
+const isCanonicalIsoInstant = (value) => {
+    const timestamp = Date.parse(value);
+    return (Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value);
+};
+const assertReportMatchesPlan = (plan, report) => {
+    if (report.planDigest !== plan.planDigest ||
+        report.evaluationDigest !== plan.evaluationDigest ||
+        report.judgeProtocolVersion !== plan.judgeProtocolVersion ||
+        report.judgeModel !== plan.judgeModel ||
+        report.judgeReasoningEffort !== plan.judgeReasoningEffort ||
+        report.judgeSystemPrompt !== plan.judgeSystemPrompt ||
+        report.minimumJudgeScore !== plan.minimumJudgeScore) {
+        throw new Error("grader calibration report does not match its expected plan");
+    }
+};
+export function compileEvaluationGraderCalibrationPlan(input) {
+    const { proposal } = input;
+    assertEvaluationProposal(proposal);
+    assertEvaluationStructure(input);
+    const controls = [
+        ...proposal.suites.flatMap((suite) => suite.cases.flatMap((testCase) => controlsForCase(testCase, "dimension", suite.dimensionId))),
+        ...proposal.compositionSuite.cases.flatMap((testCase) => controlsForCase(testCase, "composition", "composition"))
+    ].sort((left, right) => stableCompare([
+        left.suiteKind,
+        left.suiteId,
+        left.caseId,
+        left.kind,
+        left.authoredControlId,
+        left.id
+    ].join("\u0000"), [
+        right.suiteKind,
+        right.suiteId,
+        right.caseId,
+        right.kind,
+        right.authoredControlId,
+        right.id
+    ].join("\u0000")));
+    if (controls.length === 0) {
+        throw new Error("grader calibration requires at least one authored control");
+    }
+    const withoutDigest = {
+        version: 1,
+        policyVersion: EVAL_GRADER_CALIBRATION_POLICY_VERSION,
+        evaluationDigest: proposal.evaluationDigest,
+        judgeProtocolVersion: EVAL_GRADER_JUDGE_PROTOCOL_VERSION,
+        judgeModel: proposal.judgeModel,
+        // The project protocol does not currently collect a judge effort. Null
+        // explicitly binds the absence of an override instead of pretending the
+        // provider-resolved default is known.
+        judgeReasoningEffort: null,
+        judgeSystemPrompt: EVAL_GRADER_SYSTEM_PROMPT,
+        minimumJudgeScore: EVAL_GRADER_MINIMUM_SCORE,
+        callCount: controls.length,
+        controls
+    };
+    const plan = {
+        ...withoutDigest,
+        planDigest: expectedPlanDigest(withoutDigest)
+    };
+    assertPlan(plan);
+    return plan;
+}
+export function compileEvaluationGraderCalibrationReport(input) {
+    assertPlan(input.plan);
+    if (!isCanonicalIsoInstant(input.startedAt) ||
+        !isCanonicalIsoInstant(input.finishedAt) ||
+        Date.parse(input.finishedAt) < Date.parse(input.startedAt)) {
+        throw new Error("grader calibration report timestamps are invalid");
+    }
+    if (input.observations.length !== input.plan.controls.length) {
+        throw new Error("grader calibration observations are incomplete");
+    }
+    const controls = new Map(input.plan.controls.map((control) => [control.id, control]));
+    const seenControls = new Set();
+    const seenCalls = new Set();
+    const results = input.observations.map((observation) => {
+        Schema.decodeSync(CalibrationObservationSchema)(observation);
+        const control = controls.get(observation.controlId);
+        if (control === undefined) {
+            throw new Error(`grader calibration contains unknown control ${JSON.stringify(observation.controlId)}`);
+        }
+        if (seenControls.has(observation.controlId)) {
+            throw new Error(`grader calibration contains duplicate control ${JSON.stringify(observation.controlId)}`);
+        }
+        seenControls.add(observation.controlId);
+        if (observation.judgeModel !== input.plan.judgeModel) {
+            throw new Error("grader calibration observation uses the wrong judge model");
+        }
+        assertNonEmpty(observation.callId, "grader calibration call id");
+        if (seenCalls.has(observation.callId)) {
+            throw new Error("grader calibration observations reuse a judge call id");
+        }
+        seenCalls.add(observation.callId);
+        assertNonEmpty(observation.reason, "grader calibration verdict reason");
+        const accepted = observation.pass &&
+            observation.score >= input.plan.minimumJudgeScore;
+        const observedOutcome = accepted ? "accept" : "reject";
+        return {
+            ...observation,
+            expectedOutcome: control.expectedOutcome,
+            observedOutcome,
+            matchedExpectation: observedOutcome === control.expectedOutcome
+        };
+    });
+    if (seenControls.size !== controls.size) {
+        throw new Error("grader calibration observations do not cover every control");
+    }
+    results.sort((left, right) => stableCompare(left.controlId, right.controlId));
+    const acceptedCount = results.filter((result) => result.observedOutcome === "accept").length;
+    const rejectedCount = results.length - acceptedCount;
+    const matchedCount = results.filter((result) => result.matchedExpectation).length;
+    const withoutDigest = {
+        version: 1,
+        policyVersion: EVAL_GRADER_CALIBRATION_POLICY_VERSION,
+        planDigest: input.plan.planDigest,
+        evaluationDigest: input.plan.evaluationDigest,
+        judgeProtocolVersion: input.plan.judgeProtocolVersion,
+        judgeModel: input.plan.judgeModel,
+        judgeReasoningEffort: input.plan.judgeReasoningEffort,
+        judgeSystemPrompt: input.plan.judgeSystemPrompt,
+        minimumJudgeScore: input.plan.minimumJudgeScore,
+        startedAt: input.startedAt,
+        finishedAt: input.finishedAt,
+        callCount: results.length,
+        acceptedCount,
+        rejectedCount,
+        matchedCount,
+        passed: matchedCount === results.length,
+        results
+    };
+    return {
+        ...withoutDigest,
+        reportDigest: evaluationGraderCalibrationReportDigest(withoutDigest)
+    };
+}
+export function assertEvaluationGraderCalibrationPassed(input) {
+    assertPlan(input.plan);
+    const { report } = input;
+    Schema.decodeSync(CalibrationReportSchema)(report);
+    assertReportMatchesPlan(input.plan, report);
+    if (!isCanonicalIsoInstant(report.startedAt) ||
+        !isCanonicalIsoInstant(report.finishedAt) ||
+        Date.parse(report.finishedAt) < Date.parse(report.startedAt)) {
+        throw new Error("grader calibration report timestamps are invalid");
+    }
+    const { reportDigest: _reportDigest, ...withoutDigest } = report;
+    if (report.reportDigest !==
+        evaluationGraderCalibrationReportDigest(withoutDigest)) {
+        throw new Error("grader calibration report digest is stale");
+    }
+    if (report.policyVersion !== EVAL_GRADER_CALIBRATION_POLICY_VERSION ||
+        report.callCount !== report.results.length ||
+        report.callCount !== input.plan.callCount ||
+        new Set(report.results.map((result) => result.controlId)).size !==
+            report.results.length ||
+        new Set(report.results.map((result) => result.callId)).size !==
+            report.results.length ||
+        report.matchedCount !==
+            report.results.filter((result) => result.matchedExpectation).length ||
+        report.acceptedCount !==
+            report.results.filter((result) => result.observedOutcome === "accept")
+                .length ||
+        report.rejectedCount !==
+            report.results.filter((result) => result.observedOutcome === "reject")
+                .length) {
+        throw new Error("grader calibration report summary is inconsistent");
+    }
+    const controls = new Map(input.plan.controls.map((control) => [control.id, control]));
+    if (report.results.some((result) => {
+        const control = controls.get(result.controlId);
+        return (control === undefined ||
+            result.judgeModel !== input.plan.judgeModel ||
+            result.callId.trim().length === 0 ||
+            result.reason.trim().length === 0 ||
+            result.expectedOutcome !== control.expectedOutcome ||
+            result.observedOutcome !==
+                (result.pass && result.score >= input.plan.minimumJudgeScore
+                    ? "accept"
+                    : "reject") ||
+            result.matchedExpectation !==
+                (result.observedOutcome === result.expectedOutcome));
+    })) {
+        throw new Error("grader calibration report results are inconsistent");
+    }
+    if (!report.passed ||
+        report.matchedCount !== report.callCount ||
+        report.results.some((result) => !result.matchedExpectation)) {
+        throw new Error("grader calibration did not satisfy every control");
+    }
+}

package/dist/evaluation-grading-policy.d.ts

@@ -0,0 +1,24 @@
+export declare const EVAL_GRADER_JUDGE_PROTOCOL_VERSION: 1;
+/**
+ * The current generated qualification suite's inherited judge acceptance
+ * threshold. Calibration binds this exact behavior; it does not claim that the
+ * threshold is empirically optimal.
+ */
+export declare const EVAL_GRADER_MINIMUM_SCORE = 0.8;
+/**
+ * Pin the judge instruction bytes in calibration plans rather than depending
+ * on an SDK default that can change independently of a reviewed plan.
+ */
+export declare const EVAL_GRADER_SYSTEM_PROMPT: string;
+export declare const EVAL_CANDIDATE_RESPONSE_REQUIREMENTS: readonly ["Answer every part of the request directly and completely.", "When translating protocols, emit the complete target-protocol envelope and terminal event; do not merely reframe or forward source objects.", "When asked for a body, bytes, frames, or code, include the concrete output rather than only describing it."];
+export type EvalCandidatePromptInput = {
+    readonly prompt: string;
+    readonly context: string;
+};
+export declare function renderEvaluationCandidatePrompt(candidateCase: EvalCandidatePromptInput): string;
+/**
+ * Render the generated-suite statement from the same policy constants as the
+ * pure compiler renderer. This remains source generation because materialized
+ * suites execute outside eval-setup and cannot import its private modules.
+ */
+export declare function renderEvaluationCandidatePromptSource(candidateExpression?: string): string;

package/dist/evaluation-grading-policy.js

@@ -0,0 +1,54 @@
+export const EVAL_GRADER_JUDGE_PROTOCOL_VERSION = 1;
+/**
+ * The current generated qualification suite's inherited judge acceptance
+ * threshold. Calibration binds this exact behavior; it does not claim that the
+ * threshold is empirically optimal.
+ */
+export const EVAL_GRADER_MINIMUM_SCORE = 0.8;
+/**
+ * Pin the judge instruction bytes in calibration plans rather than depending
+ * on an SDK default that can change independently of a reviewed plan.
+ */
+export const EVAL_GRADER_SYSTEM_PROMPT = [
+    "You are a strict evaluator for AI agent outputs.",
+    "Grade the candidate against the criteria. Be conservative: only pass when the criteria are clearly met.",
+    "Return your verdict as the structured JSON object you were asked for — nothing else."
+].join("\n");
+export const EVAL_CANDIDATE_RESPONSE_REQUIREMENTS = [
+    "Answer every part of the request directly and completely.",
+    "When translating protocols, emit the complete target-protocol envelope and terminal event; do not merely reframe or forward source objects.",
+    "When asked for a body, bytes, frames, or code, include the concrete output rather than only describing it."
+];
+const candidatePromptParts = (candidateCase) => [
+    candidateCase.prompt,
+    "",
+    "Response requirements:",
+    ...EVAL_CANDIDATE_RESPONSE_REQUIREMENTS.map((requirement) => `- ${requirement}`),
+    "",
+    "Reference material:",
+    "-----",
+    candidateCase.context,
+    "-----"
+];
+export function renderEvaluationCandidatePrompt(candidateCase) {
+    return candidatePromptParts(candidateCase).join("\n");
+}
+/**
+ * Render the generated-suite statement from the same policy constants as the
+ * pure compiler renderer. This remains source generation because materialized
+ * suites execute outside eval-setup and cannot import its private modules.
+ */
+export function renderEvaluationCandidatePromptSource(candidateExpression = "candidateCase") {
+    return `const responseRequirements = ${JSON.stringify(EVAL_CANDIDATE_RESPONSE_REQUIREMENTS)};
+      const prompt = [
+        ${candidateExpression}.prompt,
+        "",
+        "Response requirements:",
+        ...responseRequirements.map((requirement) => \`- \${requirement}\`),
+        "",
+        "Reference material:",
+        "-----",
+        ${candidateExpression}.context,
+        "-----"
+      ].join("\\n");`;
+}

package/dist/evaluation-proposal-policy.d.ts

@@ -0,0 +1,4 @@
+import type { EvalEvaluationProposal } from "./project-contracts.js";
+export declare const evaluationProposalPayload: (proposal: EvalEvaluationProposal) => Omit<EvalEvaluationProposal, "evaluationDigest">;
+export declare function evaluationProposalDigest(proposal: Omit<EvalEvaluationProposal, "evaluationDigest">): string;
+export declare function assertEvaluationProposal(proposal: EvalEvaluationProposal): void;

package/dist/evaluation-proposal-policy.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const evaluationProposalPayload = (proposal) => ({
+    version: proposal.version,
+    basisDigest: proposal.basisDigest,
+    candidateModels: proposal.candidateModels,
+    ...(proposal.candidateReasoningEfforts === undefined
+        ? {}
+        : { candidateReasoningEfforts: proposal.candidateReasoningEfforts }),
+    judgeModel: proposal.judgeModel,
+    ...(proposal.evidenceSources === undefined
+        ? {}
+        : { evidenceSources: proposal.evidenceSources }),
+    suites: proposal.suites,
+    decompositionBenchmark: proposal.decompositionBenchmark,
+    compositionSuite: proposal.compositionSuite
+});
+export function evaluationProposalDigest(proposal) {
+    return digest(proposal);
+}
+const assertDimensionSuite = (suite) => {
+    if (suite.maximumOutputTokens < 1) {
+        throw new Error(`dimension suite ${JSON.stringify(suite.dimensionId)} has no output allowance`);
+    }
+    if (suite.cases.length < 5) {
+        throw new Error(`dimension suite ${JSON.stringify(suite.dimensionId)} must contain at least five cases`);
+    }
+    const ids = new Set();
+    for (const testCase of suite.cases) {
+        if (testCase.id.trim().length === 0 ||
+            testCase.prompt.trim().length === 0 ||
+            testCase.rubric.trim().length === 0) {
+            throw new Error(`dimension suite ${JSON.stringify(suite.dimensionId)} contains an incomplete case`);
+        }
+        if (ids.has(testCase.id)) {
+            throw new Error(`dimension suite ${JSON.stringify(suite.dimensionId)} contains duplicate case ${JSON.stringify(testCase.id)}`);
+        }
+        ids.add(testCase.id);
+    }
+};
+export function assertEvaluationProposal(proposal) {
+    if (proposal.evaluationDigest !==
+        evaluationProposalDigest(evaluationProposalPayload(proposal))) {
+        throw new Error("evaluation proposal digest does not match its contents");
+    }
+    if (proposal.candidateModels.length < 2) {
+        throw new Error("evaluation proposal requires at least two candidate models");
+    }
+    if (new Set(proposal.candidateModels).size !== proposal.candidateModels.length) {
+        throw new Error("evaluation proposal candidate models must be unique");
+    }
+    if (Object.keys(proposal.candidateReasoningEfforts ?? {}).some((model) => !proposal.candidateModels.includes(model))) {
+        throw new Error("evaluation proposal reasoning efforts must belong to candidate models");
+    }
+    if (proposal.judgeModel.trim().length === 0) {
+        throw new Error("evaluation proposal judge must be explicit");
+    }
+    const dimensions = new Set();
+    for (const suite of proposal.suites) {
+        if (dimensions.has(suite.dimensionId)) {
+            throw new Error(`duplicate dimension suite ${JSON.stringify(suite.dimensionId)}`);
+        }
+        dimensions.add(suite.dimensionId);
+        assertDimensionSuite(suite);
+    }
+    if (proposal.decompositionBenchmark.maximumVectorL1Error < 0 ||
+        proposal.decompositionBenchmark.maximumVectorL1Error > 2 ||
+        proposal.decompositionBenchmark.cases.length < 5) {
+        throw new Error("decomposition benchmark must define a reviewed threshold and at least five cases");
+    }
+    if (proposal.compositionSuite.maximumOutputTokens < 1 ||
+        proposal.compositionSuite.minimumWinnerScoreGap < 0 ||
+        proposal.compositionSuite.minimumWinnerScoreGap > 1 ||
+        proposal.compositionSuite.minimumWinnerAgreement < 0 ||
+        proposal.compositionSuite.minimumWinnerAgreement > 1 ||
+        proposal.compositionSuite.cases.length < 5) {
+        throw new Error("composition benchmark must define reviewed thresholds and at least five cases");
+    }
+    for (const [label, cases] of [
+        ["decomposition", proposal.decompositionBenchmark.cases],
+        ["composition", proposal.compositionSuite.cases]
+    ]) {
+        const ids = new Set();
+        for (const testCase of cases) {
+            if (testCase.id.trim().length === 0 || ids.has(testCase.id)) {
+                throw new Error(`${label} benchmark contains an invalid or duplicate case id`);
+            }
+            ids.add(testCase.id);
+        }
+    }
+}

package/dist/evaluation-source-retrieval.d.ts

@@ -0,0 +1,68 @@
+import type { RoutingBasis } from "@velum-labs/routekit-eval-contracts";
+import type { EvalEvidenceBlock, EvalEvidenceSource } from "./project-contracts.js";
+export declare const EVAL_SOURCE_RETRIEVAL_INDEX_FILES = 512;
+export declare const EVAL_SOURCE_RETRIEVAL_INDEX_BYTES: number;
+export declare const EVAL_SOURCE_RETRIEVAL_FILE_BYTES: number;
+export declare const EVAL_SOURCE_RETRIEVAL_PACKET_BLOCKS = 20;
+export declare const EVAL_SOURCE_RETRIEVAL_BLOCKS_PER_SOURCE = 2;
+export type EvalSourceRetrievalCandidate = {
+    readonly path: string;
+    readonly sizeBytes: number;
+    readonly sourceClass: "implementation" | "test" | "protocol" | "documentation" | "operational";
+    readonly explicitReason?: string;
+    readonly pathScore?: number;
+};
+export type EvalSourceRetrievalDocument = EvalSourceRetrievalCandidate & {
+    readonly content: string;
+};
+export type EvalSourceRetrievalSelection = EvalSourceRetrievalDocument & {
+    readonly inclusionReason: string;
+};
+export type EvalEvidenceRetrievalDocument = EvalSourceRetrievalCandidate & {
+    readonly evidenceSource: EvalEvidenceSource;
+    readonly pathScore?: number;
+};
+export type EvalEvidenceRetrievalSelection = {
+    readonly source: EvalSourceRetrievalCandidate;
+    readonly blocks: readonly EvalEvidenceBlock[];
+    readonly sizeBytes: number;
+    readonly inclusionReason: string;
+};
+/**
+ * Tokenizes identifiers and prose without asking a model to infer source
+ * relevance. CamelCase boundaries are retained so `providerBackend` can match
+ * the reviewed positive scope `provider backend`.
+ */
+export declare const evaluationSourceTokens: (value: string) => readonly string[];
+/**
+ * Produces a bounded content-index plan. Positive path matches identify likely
+ * ownership roots, then generic filenames inside those roots may compete by
+ * content. This avoids reading an unbounded repository or relying on inventory
+ * order.
+ */
+export declare function planEvaluationSourceRetrieval(input: {
+    readonly candidates: readonly EvalSourceRetrievalCandidate[];
+    readonly workloadDescription?: string;
+    readonly targetDimensions?: RoutingBasis["dimensions"];
+    readonly maximumFiles?: number;
+    readonly maximumBytes?: number;
+}): readonly EvalSourceRetrievalCandidate[];
+export declare function selectEvaluationSourcePacket(input: {
+    readonly documents: readonly EvalSourceRetrievalDocument[];
+    readonly workloadDescription?: string;
+    readonly targetDimensions?: RoutingBasis["dimensions"];
+    readonly maximumFiles: number;
+    readonly maximumBytes: number;
+}): readonly EvalSourceRetrievalSelection[];
+/**
+ * Selects compiler-owned evidence blocks rather than whole files. Packet
+ * assembly proceeds in per-source rounds so one large source cannot consume
+ * the complete authoring budget before complementary owners can compete.
+ */
+export declare function selectEvaluationEvidencePacket(input: {
+    readonly documents: readonly EvalEvidenceRetrievalDocument[];
+    readonly targetDimensions: RoutingBasis["dimensions"];
+    readonly maximumBlocks?: number;
+    readonly maximumBytes: number;
+    readonly maximumBlocksPerSource?: number;
+}): readonly EvalEvidenceRetrievalSelection[];