@velum-labs/routekit-eval-setup 1.0.26 → 1.1.1

package/dist/adapters/git-basis-snapshot.d.ts

@@ -0,0 +1,27 @@
+import { Effect } from "effect";
+import { EvalBasisSnapshotError } from "../errors.js";
+import type { FrozenRepositorySnapshotV3 } from "../project-contracts.js";
+export type CapturedRepositorySnapshotV3 = {
+    readonly snapshot: FrozenRepositorySnapshotV3;
+    readonly sourceInventory: readonly string[];
+};
+export type FrozenRepositorySourceV3 = {
+    readonly path: string;
+    readonly content: string;
+};
+/**
+ * Reads a deterministic bounded source sample from the exact frozen Git tree.
+ * Mutable worktree contents are never consulted.
+ */
+export declare function readFrozenRepositorySourcesV3(input: {
+    readonly repositoryRoot: string;
+    readonly tree: string;
+    readonly sourceInventory: readonly string[];
+}): Effect.Effect<readonly FrozenRepositorySourceV3[], EvalBasisSnapshotError>;
+/** Git adapter for an exact, bounded repository snapshot. */
+export declare function captureFrozenRepositorySnapshotV3(input: {
+    readonly repositoryRoot: string;
+    readonly requestedRef: string;
+    readonly allowDirty: boolean;
+    readonly capturedAt: string;
+}): Effect.Effect<CapturedRepositorySnapshotV3, EvalBasisSnapshotError>;

package/dist/adapters/git-basis-snapshot.js

@@ -0,0 +1,178 @@
+import { execFile } from "node:child_process";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { routingContractDigest } from "@velum-labs/routekit-eval-contracts";
+import { Effect } from "effect";
+import { EvalBasisSnapshotError } from "../errors.js";
+const execFilePromise = promisify(execFile);
+const MAX_TREE_PATHS = 40_000;
+const MAX_DIRTY_BYTES = 8 * 1024 * 1024;
+const MAX_AUTHORING_FILES = 64;
+const MAX_AUTHORING_BYTES = 60_000;
+const failure = (operation, detail, cause) => new EvalBasisSnapshotError({
+    operation,
+    detail,
+    ...(cause === undefined ? {} : { cause })
+});
+function git(root, args, operation) {
+    return Effect.tryPromise({
+        try: async () => {
+            const result = (await execFilePromise("git", ["-C", root, ...args], {
+                encoding: "utf8",
+                maxBuffer: 16 * 1024 * 1024,
+                windowsHide: true
+            }));
+            return result.stdout;
+        },
+        catch: (cause) => failure(operation, `git ${args.join(" ")} failed`, cause)
+    });
+}
+function pathWithin(root, candidate) {
+    const path = relative(root, candidate);
+    return (path === "" ||
+        (path !== ".." &&
+            !path.startsWith(`..${sep}`) &&
+            !path.startsWith("/")));
+}
+function dirtyContentDigest(root, status) {
+    return Effect.gen(function* () {
+        const patch = yield* git(root, ["diff", "--binary", "--no-ext-diff", "HEAD", "--"], "read-dirty-content");
+        const untracked = (yield* git(root, ["ls-files", "--others", "--exclude-standard", "-z"], "read-dirty-content"))
+            .split("\0")
+            .filter((entry) => entry.length > 0)
+            .sort();
+        let totalBytes = Buffer.byteLength(status, "utf8") + Buffer.byteLength(patch, "utf8");
+        const untrackedDigests = [];
+        for (const path of untracked) {
+            const absolute = resolve(root, path);
+            if (!pathWithin(root, absolute)) {
+                return yield* failure("read-dirty-content", `untracked path escapes the repository: ${JSON.stringify(path)}`);
+            }
+            const info = yield* Effect.tryPromise({
+                try: () => lstat(absolute),
+                catch: (cause) => failure("read-dirty-content", `failed to inspect untracked path ${JSON.stringify(path)}`, cause)
+            });
+            if (!info.isFile() || info.isSymbolicLink()) {
+                return yield* failure("read-dirty-content", `untracked path is not a regular non-symlink file: ${JSON.stringify(path)}`);
+            }
+            totalBytes += Number(info.size);
+            if (totalBytes > MAX_DIRTY_BYTES) {
+                return yield* failure("read-dirty-content", `dirty repository evidence exceeds ${String(MAX_DIRTY_BYTES)} bytes`);
+            }
+            const content = yield* Effect.tryPromise({
+                try: () => readFile(absolute),
+                catch: (cause) => failure("read-dirty-content", `failed to read untracked path ${JSON.stringify(path)}`, cause)
+            });
+            untrackedDigests.push({
+                path,
+                contentDigest: routingContractDigest("routekit.dirty-untracked-content.v1", "content", content.toString("base64"))
+            });
+        }
+        return routingContractDigest("routekit.dirty-repository-patch.v1", "dirty", { status, patch, untracked: untrackedDigests });
+    });
+}
+/**
+ * Reads a deterministic bounded source sample from the exact frozen Git tree.
+ * Mutable worktree contents are never consulted.
+ */
+export function readFrozenRepositorySourcesV3(input) {
+    return Effect.gen(function* () {
+        const root = yield* Effect.tryPromise({
+            try: () => realpath(input.repositoryRoot),
+            catch: (cause) => failure("resolve-root", `failed to resolve ${JSON.stringify(input.repositoryRoot)}`, cause)
+        });
+        const selected = input.sourceInventory
+            .filter((path) => /(^|\/)(readme(?:\.[^/]*)?|package\.json|[^/]+\.(?:ts|tsx|js|jsx|md|json))$/iu.test(path))
+            .sort((left, right) => {
+            const rank = (path) => /(^|\/)readme(?:\.[^/]*)?$/iu.test(path)
+                ? 0
+                : /(^|\/)package\.json$/u.test(path)
+                    ? 1
+                    : path.endsWith(".md")
+                        ? 2
+                        : 3;
+            return rank(left) - rank(right) || left.localeCompare(right);
+        });
+        const sources = [];
+        let totalBytes = 0;
+        for (const path of selected) {
+            if (sources.length >= MAX_AUTHORING_FILES)
+                break;
+            if (path.trim().length === 0 ||
+                path.startsWith("/") ||
+                path.split("/").includes("..") ||
+                path.includes("\0")) {
+                return yield* failure("read-tree", `source inventory contains an unsafe path: ${JSON.stringify(path)}`);
+            }
+            const content = yield* git(root, ["show", `${input.tree}:${path}`], "read-tree");
+            const bytes = Buffer.byteLength(content, "utf8");
+            if (bytes > MAX_AUTHORING_BYTES - totalBytes)
+                continue;
+            sources.push({ path, content });
+            totalBytes += bytes;
+        }
+        if (sources.length === 0) {
+            return yield* failure("read-tree", "frozen repository tree contains no bounded authoring source");
+        }
+        return sources;
+    });
+}
+/** Git adapter for an exact, bounded repository snapshot. */
+export function captureFrozenRepositorySnapshotV3(input) {
+    return Effect.gen(function* () {
+        const root = yield* Effect.tryPromise({
+            try: () => realpath(input.repositoryRoot),
+            catch: (cause) => failure("resolve-root", `failed to resolve ${JSON.stringify(input.repositoryRoot)}`, cause)
+        });
+        const status = yield* git(root, ["status", "--porcelain=v1", "--untracked-files=normal"], "inspect-status");
+        const dirty = status.trim().length > 0;
+        if (dirty && !input.allowDirty) {
+            return yield* failure("inspect-status", "repository is dirty; commit or stash changes before Classification V3 onboarding");
+        }
+        const requestedRef = input.requestedRef.trim();
+        if (requestedRef.length === 0) {
+            return yield* failure("resolve-ref", "snapshot ref must not be empty");
+        }
+        const commit = (yield* git(root, ["rev-parse", "--verify", `${requestedRef}^{commit}`], "resolve-ref")).trim();
+        const tree = (yield* git(root, ["rev-parse", "--verify", `${requestedRef}^{tree}`], "resolve-ref")).trim();
+        const sourceInventory = (yield* git(root, ["ls-tree", "-r", "--name-only", "-z", tree], "read-tree"))
+            .split("\0")
+            .filter((entry) => entry.length > 0);
+        if (sourceInventory.length > MAX_TREE_PATHS) {
+            return yield* failure("read-tree", `repository tree exceeds ${String(MAX_TREE_PATHS)} paths`);
+        }
+        const sourceInventoryDigest = routingContractDigest("routekit.repository-source-inventory.v1", "paths", sourceInventory);
+        const repositoryRootDigest = routingContractDigest("routekit.repository-root.v1", "root", root);
+        const dirtyPatchDigest = dirty
+            ? yield* dirtyContentDigest(root, status)
+            : undefined;
+        const repositoryDigest = routingContractDigest("routekit.frozen-repository-snapshot.v1", "snapshot", {
+            repositoryRootDigest,
+            requestedRef,
+            commit,
+            tree,
+            dirty,
+            ...(dirtyPatchDigest === undefined
+                ? {}
+                : { dirtyPatchDigest }),
+            sourceInventoryDigest
+        });
+        return {
+            snapshot: {
+                repositoryRootDigest,
+                requestedRef,
+                commit,
+                tree,
+                repositoryDigest,
+                capturedAt: input.capturedAt,
+                dirty,
+                ...(dirtyPatchDigest === undefined
+                    ? {}
+                    : { dirtyPatchDigest }),
+                sourceInventoryDigest
+            },
+            sourceInventory
+        };
+    });
+}

package/dist/basis-candidates.d.ts

@@ -0,0 +1,72 @@
+import type { BasisCandidateRecipeV3, BasisTaskRecordV3, BasisTaskSplitV3 } from "./project-contracts.js";
+export declare const BASIS_AUTHOR_INPUT_TOKENS_PER_ATTEMPT = 65536;
+export declare const BASIS_AUTHOR_OUTPUT_TOKENS_PER_ATTEMPT = 16384;
+export declare const DEFAULT_BASIS_CANDIDATE_RECIPES_V3: readonly [{
+    readonly id: "incumbent-enriched-8";
+    readonly dimensionCount: 8;
+    readonly historySize: 0;
+    readonly sampling: "none";
+    readonly includeChangedPathStatistics: false;
+    readonly deterministic: true;
+}, {
+    readonly id: "structure-only-8";
+    readonly dimensionCount: 8;
+    readonly historySize: 0;
+    readonly sampling: "none";
+    readonly includeChangedPathStatistics: false;
+    readonly deterministic: false;
+}, {
+    readonly id: "hybrid-paths-20-diverse-8";
+    readonly dimensionCount: 8;
+    readonly historySize: 20;
+    readonly sampling: "diverse";
+    readonly includeChangedPathStatistics: true;
+    readonly deterministic: false;
+}, {
+    readonly id: "hybrid-paths-40-diverse-6";
+    readonly dimensionCount: 6;
+    readonly historySize: 40;
+    readonly sampling: "diverse";
+    readonly includeChangedPathStatistics: true;
+    readonly deterministic: false;
+}, {
+    readonly id: "hybrid-paths-40-diverse-8";
+    readonly dimensionCount: 8;
+    readonly historySize: 40;
+    readonly sampling: "diverse";
+    readonly includeChangedPathStatistics: true;
+    readonly deterministic: false;
+}, {
+    readonly id: "hybrid-paths-40-diverse-10";
+    readonly dimensionCount: 10;
+    readonly historySize: 40;
+    readonly sampling: "diverse";
+    readonly includeChangedPathStatistics: true;
+    readonly deterministic: false;
+}, {
+    readonly id: "hybrid-paths-40-recent-8";
+    readonly dimensionCount: 8;
+    readonly historySize: 40;
+    readonly sampling: "recent";
+    readonly includeChangedPathStatistics: true;
+    readonly deterministic: false;
+}, {
+    readonly id: "hybrid-paths-80-diverse-8";
+    readonly dimensionCount: 8;
+    readonly historySize: 80;
+    readonly sampling: "diverse";
+    readonly includeChangedPathStatistics: true;
+    readonly deterministic: false;
+}];
+/**
+ * Freezes oldest→newest construction/validation/final cohorts.
+ *
+ * The default keeps 12 validation and 28 final tasks whenever at least one
+ * older construction task remains. Sparse histories fail closed with explicit
+ * provisional/no-final warnings rather than borrowing from held-out cohorts.
+ */
+export declare function splitBasisTasksChronologicallyV3(tasks: readonly BasisTaskRecordV3[], input?: {
+    readonly validationCount?: number;
+    readonly finalCount?: number;
+}): BasisTaskSplitV3;
+export declare function selectConstructionTasksForRecipeV3(split: BasisTaskSplitV3, recipe: BasisCandidateRecipeV3): readonly BasisTaskRecordV3[];

package/dist/basis-candidates.js

@@ -0,0 +1,157 @@
+import { routingContractDigest } from "@velum-labs/routekit-eval-contracts";
+export const BASIS_AUTHOR_INPUT_TOKENS_PER_ATTEMPT = 65_536;
+export const BASIS_AUTHOR_OUTPUT_TOKENS_PER_ATTEMPT = 16_384;
+export const DEFAULT_BASIS_CANDIDATE_RECIPES_V3 = [
+    {
+        id: "incumbent-enriched-8",
+        dimensionCount: 8,
+        historySize: 0,
+        sampling: "none",
+        includeChangedPathStatistics: false,
+        deterministic: true
+    },
+    {
+        id: "structure-only-8",
+        dimensionCount: 8,
+        historySize: 0,
+        sampling: "none",
+        includeChangedPathStatistics: false,
+        deterministic: false
+    },
+    {
+        id: "hybrid-paths-20-diverse-8",
+        dimensionCount: 8,
+        historySize: 20,
+        sampling: "diverse",
+        includeChangedPathStatistics: true,
+        deterministic: false
+    },
+    {
+        id: "hybrid-paths-40-diverse-6",
+        dimensionCount: 6,
+        historySize: 40,
+        sampling: "diverse",
+        includeChangedPathStatistics: true,
+        deterministic: false
+    },
+    {
+        id: "hybrid-paths-40-diverse-8",
+        dimensionCount: 8,
+        historySize: 40,
+        sampling: "diverse",
+        includeChangedPathStatistics: true,
+        deterministic: false
+    },
+    {
+        id: "hybrid-paths-40-diverse-10",
+        dimensionCount: 10,
+        historySize: 40,
+        sampling: "diverse",
+        includeChangedPathStatistics: true,
+        deterministic: false
+    },
+    {
+        id: "hybrid-paths-40-recent-8",
+        dimensionCount: 8,
+        historySize: 40,
+        sampling: "recent",
+        includeChangedPathStatistics: true,
+        deterministic: false
+    },
+    {
+        id: "hybrid-paths-80-diverse-8",
+        dimensionCount: 8,
+        historySize: 80,
+        sampling: "diverse",
+        includeChangedPathStatistics: true,
+        deterministic: false
+    }
+];
+function orderedTasks(tasks) {
+    const seen = new Set();
+    for (const task of tasks) {
+        if (task.caseId.trim().length === 0 || seen.has(task.caseId)) {
+            throw new Error("basis tasks require non-empty unique case IDs");
+        }
+        if (!Number.isFinite(Date.parse(task.occurredAt))) {
+            throw new Error(`basis task ${JSON.stringify(task.caseId)} has an invalid occurredAt`);
+        }
+        seen.add(task.caseId);
+    }
+    return [...tasks].sort((left, right) => Date.parse(left.occurredAt) - Date.parse(right.occurredAt) ||
+        left.caseId.localeCompare(right.caseId));
+}
+/**
+ * Freezes oldest→newest construction/validation/final cohorts.
+ *
+ * The default keeps 12 validation and 28 final tasks whenever at least one
+ * older construction task remains. Sparse histories fail closed with explicit
+ * provisional/no-final warnings rather than borrowing from held-out cohorts.
+ */
+export function splitBasisTasksChronologicallyV3(tasks, input = {}) {
+    const ordered = orderedTasks(tasks);
+    const requestedValidation = input.validationCount ?? 12;
+    const requestedFinal = input.finalCount ?? 28;
+    if (!Number.isSafeInteger(requestedValidation) ||
+        requestedValidation < 1 ||
+        !Number.isSafeInteger(requestedFinal) ||
+        requestedFinal < 1) {
+        throw new Error("basis split counts must be positive integers");
+    }
+    const validationCount = Math.min(requestedValidation, Math.max(0, ordered.length - 1));
+    const finalCount = Math.min(requestedFinal, Math.max(0, ordered.length - validationCount - 1));
+    const constructionCount = ordered.length - validationCount - finalCount;
+    const construction = ordered.slice(0, constructionCount);
+    const validation = ordered.slice(constructionCount, constructionCount + validationCount);
+    const final = ordered.slice(constructionCount + validationCount);
+    const warnings = [
+        ...(validation.length < requestedValidation
+            ? [
+                `validation cohort contains ${String(validation.length)} tasks; ${String(requestedValidation)} are required for non-provisional selection`
+            ]
+            : []),
+        ...(final.length < requestedFinal
+            ? [
+                `final cohort contains ${String(final.length)} tasks; ${String(requestedFinal)} are required for the default launch qualification`
+            ]
+            : []),
+        ...(final.length === 0
+            ? ["no untouched final cohort is available; production qualification is prohibited"]
+            : [])
+    ];
+    const semantic = {
+        version: 1,
+        construction,
+        validation,
+        final,
+        provisional: validation.length < requestedValidation,
+        warnings
+    };
+    return {
+        ...semantic,
+        splitDigest: routingContractDigest("routekit.basis-task-split.v1", "split", semantic)
+    };
+}
+export function selectConstructionTasksForRecipeV3(split, recipe) {
+    if (recipe.historySize === 0)
+        return [];
+    const construction = [...split.construction];
+    if (construction.length <= recipe.historySize)
+        return construction;
+    if (recipe.sampling === "recent") {
+        return construction.slice(-recipe.historySize);
+    }
+    if (recipe.sampling !== "diverse") {
+        throw new Error(`recipe ${JSON.stringify(recipe.id)} has an invalid history sampling mode`);
+    }
+    if (recipe.historySize === 1)
+        return [construction[0]];
+    const selected = new Map();
+    for (let index = 0; index < recipe.historySize; index += 1) {
+        const position = Math.round((index * (construction.length - 1)) / (recipe.historySize - 1));
+        const task = construction[position];
+        selected.set(task.caseId, task);
+    }
+    return [...selected.values()].sort((left, right) => Date.parse(left.occurredAt) - Date.parse(right.occurredAt) ||
+        left.caseId.localeCompare(right.caseId));
+}

package/dist/basis-projection.d.ts

@@ -0,0 +1,9 @@
+import { type RoutingBasisV3, type RoutingDimensionDefinitionV3, type WorkloadDimension } from "@velum-labs/routekit-eval-contracts";
+import type { BasisEvaluationProjectionV3 } from "./project-contracts.js";
+/**
+ * Projects the approved V3 semantic basis into the existing evaluator/scorer
+ * dimension vocabulary. The projection is derived, immutable, and never an
+ * independently editable routing basis.
+ */
+export declare function projectRoutingDimensionV3(dimension: RoutingDimensionDefinitionV3): WorkloadDimension;
+export declare function projectRoutingBasisV3(basis: RoutingBasisV3): BasisEvaluationProjectionV3;

package/dist/basis-projection.js

@@ -0,0 +1,30 @@
+import { assertRoutingBasis } from "@velum-labs/routekit-eval-contracts";
+import { routingBasisDigest } from "./project-artifacts.js";
+/**
+ * Projects the approved V3 semantic basis into the existing evaluator/scorer
+ * dimension vocabulary. The projection is derived, immutable, and never an
+ * independently editable routing basis.
+ */
+export function projectRoutingDimensionV3(dimension) {
+    return {
+        id: dimension.id,
+        description: dimension.description,
+        includes: dimension.inclusions,
+        excludes: dimension.exclusions
+    };
+}
+export function projectRoutingBasisV3(basis) {
+    const dimensions = basis.dimensions.map(projectRoutingDimensionV3);
+    const projected = {
+        version: 2,
+        basisDigest: routingBasisDigest(dimensions),
+        dimensions
+    };
+    assertRoutingBasis(projected);
+    return {
+        version: 1,
+        basisDigest: basis.basisDigest,
+        projectedBasisDigest: projected.basisDigest,
+        dimensions: projected.dimensions
+    };
+}

package/dist/basis-validation.d.ts

@@ -0,0 +1,38 @@
+import { type DimensionScoreLabelV3, type DimensionScorePredictionV3, type RoutingBasisApprovalV3 } from "@velum-labs/routekit-eval-contracts";
+import type { BasisCandidateDatasetV3, BasisCandidateRecordV3, BasisLabelProtocolV3, BasisSelectionReportV3, BasisStructureReportV3, BasisTaskRecordV3, BasisValidationPlanV3, BasisValidationResultV3, FrozenRepositorySnapshotV3 } from "./project-contracts.js";
+export declare function inspectBasisCandidatesV3(candidates: readonly BasisCandidateRecordV3[], aliasSimilarityThreshold?: number): readonly BasisStructureReportV3[];
+export declare function makeBasisCandidateDatasetV3(input: {
+    readonly splitDigest: string;
+    readonly candidate: BasisCandidateRecordV3;
+    readonly tasks: readonly BasisTaskRecordV3[];
+    readonly labelProtocol: BasisLabelProtocolV3;
+    readonly labels: readonly DimensionScoreLabelV3[];
+}): BasisCandidateDatasetV3;
+export declare function evaluateBasisCandidateValidationV3(input: {
+    readonly candidate: BasisCandidateRecordV3;
+    readonly dataset: BasisCandidateDatasetV3;
+    readonly validationPlan: BasisValidationPlanV3;
+    readonly predictions: readonly DimensionScorePredictionV3[];
+    readonly provisional: boolean;
+}): BasisValidationResultV3;
+export declare function selectValidatedBasisCandidatesV3(input: {
+    readonly repositoryDigest: string;
+    readonly validationPlan: BasisValidationPlanV3;
+    readonly candidates: readonly BasisCandidateRecordV3[];
+    readonly structureReports: readonly BasisStructureReportV3[];
+    readonly validationResults: readonly BasisValidationResultV3[];
+}): BasisSelectionReportV3;
+export declare function approveSelectedBasisV3(input: {
+    readonly projectId: string;
+    readonly approvedBy: string;
+    readonly approvedAt: string;
+    readonly snapshot: FrozenRepositorySnapshotV3;
+    readonly candidate: BasisCandidateRecordV3;
+    readonly structure: BasisStructureReportV3;
+    readonly validation: BasisValidationResultV3;
+    readonly selection: BasisSelectionReportV3;
+    readonly provisionalAcknowledgement?: string;
+}): {
+    readonly approval: RoutingBasisApprovalV3;
+    readonly approvalDigest: string;
+};