@dailephd/my-dev-kit-lab 0.7.0 → 0.7.2

package/dist/src/evaluation/localRepositorySubject/loadLocalRepositorySubject.js

@@ -0,0 +1,48 @@
+import { parseLocalRepositorySubjectConfig } from "./config.js";
+import { buildLocalRepositorySubjectEvaluationCases } from "./evaluationCase.js";
+import { validateExpectedFiles } from "./expectedFiles.js";
+import { readRepositoryIdentity } from "./gitRepository.js";
+import { buildLocalRepositorySubjectInventory, defaultLocalRepositorySubjectFsIo, validateSourceRootOnDisk, } from "./inventory.js";
+import { buildLocalRepositorySubjectManifest } from "./manifest.js";
+import { DEFAULT_LOCAL_REPOSITORY_SUBJECT_MAX_FILE_BYTES, LocalRepositorySubjectConfigError, compareCodeUnits, logicalTargetRootForSubject, } from "./types.js";
+/**
+ * Loads a local repository subject in the frozen safety order: validate config, identify the Git repository,
+ * validate source roots on disk, inventory (without reading contents), validate required files, then build the
+ * privacy-safe manifest and in-memory EvaluationCase objects. Never mutates the subject repository.
+ */
+export async function loadLocalRepositorySubject(options) {
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_LOCAL_REPOSITORY_SUBJECT_MAX_FILE_BYTES;
+    if (!Number.isSafeInteger(maxFileBytes) || maxFileBytes < 1) {
+        throw new LocalRepositorySubjectConfigError([`policy.maxFileBytes: must be a positive safe integer (received ${String(maxFileBytes)}).`]);
+    }
+    const io = options.io ?? defaultLocalRepositorySubjectFsIo;
+    const config = parseLocalRepositorySubjectConfig(options.config);
+    const { repositoryRoot, identity } = await readRepositoryIdentity(options.repositoryPath);
+    const rootErrors = [];
+    for (let caseIndex = 0; caseIndex < config.cases.length; caseIndex += 1) {
+        const roots = config.cases[caseIndex].sourceRoots;
+        for (let rootIndex = 0; rootIndex < roots.length; rootIndex += 1) {
+            rootErrors.push(...(await validateSourceRootOnDisk(repositoryRoot, roots[rootIndex], `config.cases[${caseIndex}].sourceRoots[${rootIndex}]`, io)));
+        }
+    }
+    if (rootErrors.length > 0)
+        throw new LocalRepositorySubjectConfigError(rootErrors);
+    const unionRoots = [...new Set(config.cases.flatMap((subjectCase) => subjectCase.sourceRoots))];
+    const inventory = await buildLocalRepositorySubjectInventory(repositoryRoot, unionRoots, maxFileBytes, io);
+    const expectedFileErrors = await validateExpectedFiles(repositoryRoot, config.cases, inventory, io);
+    if (expectedFileErrors.length > 0)
+        throw new LocalRepositorySubjectConfigError(expectedFileErrors);
+    const manifest = buildLocalRepositorySubjectManifest(config, identity, maxFileBytes, inventory);
+    return {
+        subjectId: config.subjectId,
+        logicalTargetRoot: logicalTargetRootForSubject(config.subjectId),
+        repositoryRoot,
+        manifest,
+        evaluationCases: buildLocalRepositorySubjectEvaluationCases(config, repositoryRoot),
+        eligibleFiles: inventory.eligibleFiles.map((file) => file.path),
+        runtimeSafetyExclusions: {
+            gitIgnoredFiles: [...inventory.ignoredFiles].sort(compareCodeUnits),
+            oversizedFiles: [...inventory.oversizedFiles].sort(compareCodeUnits),
+        },
+    };
+}

package/dist/src/evaluation/localRepositorySubject/manifest.js

@@ -0,0 +1,52 @@
+import { LOCAL_REPOSITORY_SUBJECT_MANIFEST_SCHEMA_ID, LOCAL_REPOSITORY_SUBJECT_MANIFEST_SCHEMA_VERSION, LOCAL_REPOSITORY_SUBJECT_SAFETY_POLICY_VERSION, compareCodeUnits, logicalTargetRootForSubject, } from "./types.js";
+/** Lowercase text after the last "." of the basename; "(none)" when absent or only a leading dot. */
+export function extensionOf(filePath) {
+    const base = filePath.slice(filePath.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 || dot === base.length - 1)
+        return "(none)";
+    return base.slice(dot + 1).toLowerCase();
+}
+function summarizeExtensions(filePaths) {
+    const counts = new Map();
+    for (const filePath of filePaths) {
+        const extension = extensionOf(filePath);
+        counts.set(extension, (counts.get(extension) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort(([left], [right]) => compareCodeUnits(left, right))
+        .map(([extension, fileCount]) => ({ extension, fileCount }));
+}
+/** Builds the privacy-safe manifest model. Inputs that are runtime-only (paths, file lists) are reduced to aggregates. */
+export function buildLocalRepositorySubjectManifest(config, identity, maxFileBytes, inventory) {
+    const sourceRoots = [...new Set(config.cases.flatMap((subjectCase) => subjectCase.sourceRoots))].sort(compareCodeUnits);
+    return {
+        schemaId: LOCAL_REPOSITORY_SUBJECT_MANIFEST_SCHEMA_ID,
+        schemaVersion: LOCAL_REPOSITORY_SUBJECT_MANIFEST_SCHEMA_VERSION,
+        subjectId: config.subjectId,
+        logicalTargetRoot: logicalTargetRootForSubject(config.subjectId),
+        repository: { commit: identity.commit, branch: identity.branch, workingTreeDirty: identity.workingTreeDirty },
+        safetyPolicy: {
+            version: LOCAL_REPOSITORY_SUBJECT_SAFETY_POLICY_VERSION,
+            maxFileBytes,
+            gitIgnoreAuthority: "git",
+            symlinkPolicy: "excluded-not-followed",
+        },
+        sourceRoots,
+        caseCount: config.cases.length,
+        caseIds: config.cases.map((subjectCase) => subjectCase.id),
+        inventory: {
+            eligibleFileCount: inventory.counts.eligibleFileCount,
+            eligibleByteCount: inventory.counts.eligibleByteCount,
+            gitIgnoredCount: inventory.counts.gitIgnoredCount,
+            oversizedCount: inventory.counts.oversizedCount,
+            symlinkCount: inventory.counts.symlinkCount,
+            otherExcludedCount: inventory.counts.otherExcludedCount,
+            extensionSummary: summarizeExtensions(inventory.eligibleFiles.map((file) => file.path)),
+        },
+    };
+}
+/** Deterministic serialization (fixed key order from the builder, LF terminated). */
+export function serializeLocalRepositorySubjectManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/dist/src/evaluation/localRepositorySubject/types.js

@@ -0,0 +1,55 @@
+export const LOCAL_REPOSITORY_SUBJECT_CONFIG_SCHEMA_ID = "my-dev-kit-lab-local-repository-subject-config-v1";
+export const LOCAL_REPOSITORY_SUBJECT_CONFIG_SCHEMA_VERSION = "1.0.0";
+export const LOCAL_REPOSITORY_SUBJECT_MANIFEST_SCHEMA_ID = "my-dev-kit-lab-local-repository-subject-manifest-v1";
+export const LOCAL_REPOSITORY_SUBJECT_MANIFEST_SCHEMA_VERSION = "1.0.0";
+/** Operational safety policy (not a quality metric): files larger than this are never eligible subject material. */
+export const DEFAULT_LOCAL_REPOSITORY_SUBJECT_MAX_FILE_BYTES = 1_048_576;
+export const LOCAL_REPOSITORY_SUBJECT_SAFETY_POLICY_VERSION = "1.0.0";
+export const LOCAL_REPOSITORY_SUBJECT_LIMITS = {
+    subjectIdMaxLength: 128,
+};
+export const LOCAL_REPOSITORY_SUBJECT_CONFIG_FIELDS = ["schemaVersion", "subjectId", "cases"];
+export const LOCAL_REPOSITORY_SUBJECT_CASE_FIELDS = [
+    "id",
+    "title",
+    "sourceRoots",
+    "query",
+    "expectedFiles",
+    "expectedSymbols",
+    "rawIncludeGlobs",
+    "answerKey",
+    "expectedFacts",
+    "taskLocality",
+    "promptComplexityHint",
+    "projectComplexityRelevance",
+    "notes",
+];
+/** Thrown when the config, or required paths it names, fail validation. Messages carry logical labels only. */
+export class LocalRepositorySubjectConfigError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Invalid local repository subject configuration: ${errors.join("; ")}`);
+        this.name = "LocalRepositorySubjectConfigError";
+        this.errors = [...errors];
+    }
+}
+/** Thrown when the selected repository cannot be identified or classified safely. Never carries raw Git output. */
+export class LocalRepositorySubjectRepositoryError extends Error {
+    code;
+    constructor(code, message) {
+        super(`Local repository subject repository error (${code}): ${message}`);
+        this.name = "LocalRepositorySubjectRepositoryError";
+        this.code = code;
+    }
+}
+export function logicalTargetRootForSubject(subjectId) {
+    return `local-repository:${subjectId}`;
+}
+/** Locale-independent ordering by code unit. */
+export function compareCodeUnits(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}

package/dist/src/evaluation/projectFileTree.js

@@ -45,8 +45,52 @@ export function countFileLines(filePath) {
     }
     return content.split(/\r?\n/).length;
 }
-export function buildProjectFileTree(projectRoot) {
+function buildAllowedFileTree(root, allowedRelativeFiles) {
+    const top = { children: new Map(), isFile: false };
+    for (const allowed of allowedRelativeFiles) {
+        const relativePath = allowed.replace(/\\/g, "/");
+        if (isExcludedProjectPath(relativePath))
+            continue;
+        let node = top;
+        const segments = relativePath.split("/");
+        segments.forEach((segment, index) => {
+            let child = node.children.get(segment);
+            if (!child) {
+                child = { children: new Map(), isFile: index === segments.length - 1 };
+                node.children.set(segment, child);
+            }
+            node = child;
+        });
+    }
+    const entries = [];
+    const walk = (node, prefix) => {
+        const names = [...node.children.keys()].sort((a, b) => a.localeCompare(b));
+        for (const name of names) {
+            const child = node.children.get(name);
+            const relativePath = prefix === "" ? name : `${prefix}/${name}`;
+            if (child.isFile) {
+                entries.push({
+                    path: relativePath,
+                    kind: "file",
+                    role: inferFileRole(relativePath, "file"),
+                    language: inferFileLanguage(relativePath),
+                    lines: countFileLines(path.join(root, ...relativePath.split("/")))
+                });
+            }
+            else {
+                entries.push({ path: relativePath, kind: "directory", role: inferFileRole(relativePath, "directory") });
+                walk(child, relativePath);
+            }
+        }
+    };
+    walk(top, "");
+    return { entries };
+}
+export function buildProjectFileTree(projectRoot, options = {}) {
     const root = path.resolve(projectRoot);
+    if (options.allowedRelativeFiles !== undefined) {
+        return buildAllowedFileTree(root, options.allowedRelativeFiles);
+    }
     const entries = [];
     function walk(currentDir) {
         const dirEntries = readdirSync(currentDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));

package/dist/src/evaluation/runMyDevKitRetrieval.js

@@ -177,6 +177,7 @@ export async function buildMyDevKitIndex(options) {
             "--root",
             options.target.absoluteTargetRoot,
             ...options.target.sourceRoots.flatMap((sourceRoot) => ["--src", sourceRoot]),
+            ...(options.excludePaths ?? []).flatMap((excludePath) => ["--exclude", excludePath]),
             "--out",
             options.indexDir,
             ...(mode.kind === "incremental" ? ["--incremental", "--refresh-scope", mode.refreshScope] : []),
@@ -352,7 +353,8 @@ export async function runMyDevKitRetrieval(options) {
         kitCommand: options.kitCommand,
         indexDir,
         commandsDir,
-        requireKit: options.requireKit
+        requireKit: options.requireKit,
+        excludePaths: options.excludePaths
     });
     if (!index.ok) {
         return skippedRetrieval(options.evaluationCase.id, [...index.warnings], [index.command], Date.now() - started);

package/dist/src/evaluation/runRawFullFileBaseline.js

@@ -1,7 +1,8 @@
-import { readFileSync, statSync } from "node:fs";
-import { collectFilesForGlobs } from "../core/fileGlobs.js";
+import { lstatSync, readFileSync, statSync } from "node:fs";
+import { collectFilesForGlobs, selectRelativePathsForGlobs } from "../core/fileGlobs.js";
+import { resolveWithinRoot } from "../core/pathSafety.js";
 import { countEstimatedTokens, countTextChars, tokenCountMethod } from "../core/countTokens.js";
-export async function runRawFullFileBaseline(evaluationCase) {
+export async function runRawFullFileBaseline(evaluationCase, options = {}) {
     const started = Date.now();
     let stats;
     try {
@@ -13,7 +14,9 @@ export async function runRawFullFileBaseline(evaluationCase) {
     if (!stats.isDirectory()) {
         throw new Error(`Target root is not a directory: ${evaluationCase.targetRoot}`);
     }
-    const files = collectFilesForGlobs(evaluationCase.absoluteTargetRoot, evaluationCase.rawIncludeGlobs);
+    const files = options.eligibleFiles === undefined
+        ? collectFilesForGlobs(evaluationCase.absoluteTargetRoot, evaluationCase.rawIncludeGlobs)
+        : selectEligibleFiles(evaluationCase, options.eligibleFiles);
     const contextText = files
         .map(({ absolutePath, relativePath }) => `=== FILE: ${relativePath} ===\n${readFileSync(absolutePath, "utf8")}\n`)
         .join("\n");
@@ -29,3 +32,14 @@ export async function runRawFullFileBaseline(evaluationCase) {
         durationMs: Date.now() - started
     };
 }
+function selectEligibleFiles(evaluationCase, eligibleFiles) {
+    return selectRelativePathsForGlobs(eligibleFiles, evaluationCase.rawIncludeGlobs).map((relativePath) => {
+        const absolutePath = resolveWithinRoot(evaluationCase.absoluteTargetRoot, relativePath);
+        // The eligible list was built earlier; refuse a file that has since been swapped for a link or removed.
+        const stats = lstatSync(absolutePath, { throwIfNoEntry: false });
+        if (!stats || stats.isSymbolicLink() || !stats.isFile()) {
+            throw new Error(`Eligible file is no longer a regular file: ${relativePath}`);
+        }
+        return { absolutePath, relativePath };
+    });
+}

package/dist/src/evaluation/syntheticRepository/config.js

@@ -0,0 +1,304 @@
+import { TASK_LOCALITIES } from "../types.js";
+import { SYNTHETIC_REPOSITORY_CONFIG_SCHEMA_VERSION, SYNTHETIC_REPOSITORY_LANGUAGES, SyntheticRepositoryConfigError, } from "./types.js";
+export const SYNTHETIC_REPOSITORY_LIMITS = {
+    maxCases: 64,
+    caseIdMaxLength: 64,
+    seedMaxLength: 256,
+    sourceFileCount: { min: 1, max: 10000 },
+    moduleDepth: { min: 1, max: 64 },
+    internalImportCount: { min: 0, max: 100000 },
+    symbolCount: { min: 1, max: 100000 },
+    testFileCount: { min: 0, max: 10000 },
+    repeatedPatternCount: { min: 0, max: 100000 },
+    broadChangeMinSourceFiles: 4,
+    crossModuleMinSourceFiles: 2,
+};
+/** Fixed field order of one case; also the canonical serialization order. */
+export const SYNTHETIC_REPOSITORY_CASE_FIELDS = [
+    "id",
+    "language",
+    "seed",
+    "sourceFileCount",
+    "moduleDepth",
+    "internalImportCount",
+    "symbolCount",
+    "testFileCount",
+    "taskLocality",
+    "repeatedPatternCount",
+];
+const COUNT_FIELDS = [
+    "sourceFileCount",
+    "moduleDepth",
+    "internalImportCount",
+    "symbolCount",
+    "testFileCount",
+    "repeatedPatternCount",
+];
+const CASE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const WINDOWS_DEVICE_NAME_PATTERN = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+/** Locale-independent ordering by UTF-16 code unit. */
+export function compareCodeUnits(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+/**
+ * Maximum number of unique directed acyclic import edges among `sourceFileCount` modules whose longest
+ * dependency chain has exactly `moduleDepth` modules: the edge count of the balanced complete
+ * multipartite arrangement, (N^2 - sum of squared layer sizes) / 2.
+ */
+export function maxImportEdges(sourceFileCount, moduleDepth) {
+    const base = Math.floor(sourceFileCount / moduleDepth);
+    const larger = sourceFileCount % moduleDepth;
+    const sumOfSquares = larger * (base + 1) * (base + 1) + (moduleDepth - larger) * base * base;
+    return (sourceFileCount * sourceFileCount - sumOfSquares) / 2;
+}
+/** Returns the case in canonical field order. Assumes the spec is valid. */
+export function orderCaseSpec(spec) {
+    return {
+        id: spec.id,
+        language: spec.language,
+        seed: spec.seed,
+        sourceFileCount: spec.sourceFileCount,
+        moduleDepth: spec.moduleDepth,
+        internalImportCount: spec.internalImportCount,
+        symbolCount: spec.symbolCount,
+        testFileCount: spec.testFileCount,
+        taskLocality: spec.taskLocality,
+        repeatedPatternCount: spec.repeatedPatternCount,
+    };
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function describeValue(value) {
+    if (typeof value === "string") {
+        return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}...` : value);
+    }
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function hasLoneSurrogate(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                index += 1;
+                continue;
+            }
+            return true;
+        }
+        if (unit >= 0xdc00 && unit <= 0xdfff)
+            return true;
+    }
+    return false;
+}
+function validateCaseId(value, label, errors) {
+    if (typeof value !== "string") {
+        errors.push(`${label}.id: must be a string (received ${describeValue(value)}).`);
+        return false;
+    }
+    const before = errors.length;
+    if (value.length < 1 || value.length > SYNTHETIC_REPOSITORY_LIMITS.caseIdMaxLength) {
+        errors.push(`${label}.id: length must be between 1 and ${SYNTHETIC_REPOSITORY_LIMITS.caseIdMaxLength}.`);
+    }
+    else if (!CASE_ID_PATTERN.test(value)) {
+        errors.push(`${label}.id: must begin with an ASCII letter or digit and contain only ASCII letters, digits, ".", "_" and "-" (received ${describeValue(value)}).`);
+    }
+    else {
+        if (value.endsWith(".")) {
+            errors.push(`${label}.id: must not end with ".".`);
+        }
+        if (WINDOWS_DEVICE_NAME_PATTERN.test(value.split(".")[0])) {
+            errors.push(`${label}.id: must not use a reserved device name (received ${describeValue(value)}).`);
+        }
+    }
+    return errors.length === before;
+}
+function validateSeed(value, label, errors) {
+    if (typeof value !== "string") {
+        errors.push(`${label}.seed: must be a string (received ${describeValue(value)}).`);
+        return false;
+    }
+    const before = errors.length;
+    if (!/\S/.test(value)) {
+        errors.push(`${label}.seed: must contain at least one non-whitespace character.`);
+    }
+    if (value.length > SYNTHETIC_REPOSITORY_LIMITS.seedMaxLength) {
+        errors.push(`${label}.seed: must be at most ${SYNTHETIC_REPOSITORY_LIMITS.seedMaxLength} UTF-16 code units.`);
+    }
+    if (hasLoneSurrogate(value)) {
+        errors.push(`${label}.seed: must be well-formed Unicode (lone surrogate found).`);
+    }
+    return errors.length === before;
+}
+function validateCount(value, field, label, errors) {
+    const { min, max } = SYNTHETIC_REPOSITORY_LIMITS[field];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+        errors.push(`${label}.${field}: must be an integer between ${min} and ${max} (received ${describeValue(value)}).`);
+        return false;
+    }
+    return true;
+}
+function validateCase(value, label, errors) {
+    if (!isPlainObject(value)) {
+        errors.push(`${label}: must be an object (received ${describeValue(value)}).`);
+        return undefined;
+    }
+    const before = errors.length;
+    const allowed = new Set(SYNTHETIC_REPOSITORY_CASE_FIELDS);
+    for (const key of Object.keys(value).sort(compareCodeUnits)) {
+        if (!allowed.has(key))
+            errors.push(`${label}: unknown field ${JSON.stringify(key)}.`);
+    }
+    for (const field of SYNTHETIC_REPOSITORY_CASE_FIELDS) {
+        if (!hasOwn(value, field))
+            errors.push(`${label}: missing required field ${field}.`);
+    }
+    const idOk = hasOwn(value, "id") && validateCaseId(value.id, label, errors);
+    const languageOk = hasOwn(value, "language") &&
+        SYNTHETIC_REPOSITORY_LANGUAGES.includes(value.language);
+    if (hasOwn(value, "language") && !languageOk) {
+        errors.push(`${label}.language: must be one of ${SYNTHETIC_REPOSITORY_LANGUAGES.join(", ")} (received ${describeValue(value.language)}).`);
+    }
+    const seedOk = hasOwn(value, "seed") && validateSeed(value.seed, label, errors);
+    const countOk = new Map();
+    for (const field of COUNT_FIELDS) {
+        countOk.set(field, hasOwn(value, field) && validateCount(value[field], field, label, errors));
+    }
+    const localityOk = hasOwn(value, "taskLocality") && TASK_LOCALITIES.includes(value.taskLocality);
+    if (hasOwn(value, "taskLocality") && !localityOk) {
+        errors.push(`${label}.taskLocality: must be one of ${TASK_LOCALITIES.join(", ")} (received ${describeValue(value.taskLocality)}).`);
+    }
+    const sourceFileCount = value.sourceFileCount;
+    const moduleDepth = value.moduleDepth;
+    const internalImportCount = value.internalImportCount;
+    const symbolCount = value.symbolCount;
+    const taskLocality = value.taskLocality;
+    const sourceOk = countOk.get("sourceFileCount") === true;
+    const depthOk = countOk.get("moduleDepth") === true;
+    const importsOk = countOk.get("internalImportCount") === true;
+    const symbolsOk = countOk.get("symbolCount") === true;
+    if (sourceOk && depthOk) {
+        if (moduleDepth > sourceFileCount) {
+            errors.push(`${label}.moduleDepth: must not exceed sourceFileCount (${moduleDepth} > ${sourceFileCount}).`);
+        }
+        else if (importsOk) {
+            if (moduleDepth > 1 && internalImportCount < moduleDepth - 1) {
+                errors.push(`${label}.internalImportCount: must be at least moduleDepth - 1 (${moduleDepth - 1}) to realize moduleDepth ${moduleDepth}.`);
+            }
+            const capacity = maxImportEdges(sourceFileCount, moduleDepth);
+            if (internalImportCount > capacity) {
+                errors.push(`${label}.internalImportCount: exceeds the ${capacity} unique acyclic edges possible for sourceFileCount ${sourceFileCount} with exact moduleDepth ${moduleDepth}.`);
+            }
+        }
+    }
+    if (sourceOk && symbolsOk && symbolCount < sourceFileCount) {
+        errors.push(`${label}.symbolCount: must be at least sourceFileCount (${symbolCount} < ${sourceFileCount}).`);
+    }
+    if (sourceOk && localityOk) {
+        if (taskLocality === "cross-module") {
+            if (sourceFileCount < SYNTHETIC_REPOSITORY_LIMITS.crossModuleMinSourceFiles) {
+                errors.push(`${label}.taskLocality: cross-module requires sourceFileCount >= 2.`);
+            }
+            if (importsOk && internalImportCount < 1) {
+                errors.push(`${label}.taskLocality: cross-module requires internalImportCount >= 1.`);
+            }
+        }
+        else if (taskLocality === "broad-change" && sourceFileCount < SYNTHETIC_REPOSITORY_LIMITS.broadChangeMinSourceFiles) {
+            errors.push(`${label}.taskLocality: broad-change requires sourceFileCount >= 4.`);
+        }
+    }
+    if (errors.length !== before || !idOk || !languageOk || !seedOk || !localityOk)
+        return undefined;
+    return orderCaseSpec(value);
+}
+/** Validates one case spec and returns it in canonical field order. Never throws, never repairs. */
+export function validateSyntheticRepositoryCaseSpec(input) {
+    const errors = [];
+    const spec = validateCase(input, "case", errors);
+    if (errors.length > 0 || spec === undefined)
+        return { ok: false, errors };
+    return { ok: true, errors: [], spec };
+}
+/**
+ * Strictly validates an unknown value as SyntheticRepositoryConfigV1. On success the returned config is
+ * canonical: cases sorted ascending by id (code-unit order), fixed field order, values untouched.
+ */
+export function validateSyntheticRepositoryConfig(input) {
+    const errors = [];
+    if (!isPlainObject(input)) {
+        return { ok: false, errors: [`config: must be an object (received ${describeValue(input)}).`] };
+    }
+    for (const key of Object.keys(input).sort(compareCodeUnits)) {
+        if (key !== "schemaVersion" && key !== "cases")
+            errors.push(`config: unknown field ${JSON.stringify(key)}.`);
+    }
+    if (!hasOwn(input, "schemaVersion")) {
+        errors.push("config: missing required field schemaVersion.");
+    }
+    else if (input.schemaVersion !== SYNTHETIC_REPOSITORY_CONFIG_SCHEMA_VERSION) {
+        errors.push(`config.schemaVersion: must be ${JSON.stringify(SYNTHETIC_REPOSITORY_CONFIG_SCHEMA_VERSION)} (received ${describeValue(input.schemaVersion)}).`);
+    }
+    if (!hasOwn(input, "cases")) {
+        errors.push("config: missing required field cases.");
+        return { ok: false, errors };
+    }
+    const cases = input.cases;
+    if (!Array.isArray(cases)) {
+        errors.push(`config.cases: must be an array (received ${describeValue(cases)}).`);
+        return { ok: false, errors };
+    }
+    if (cases.length < 1 || cases.length > SYNTHETIC_REPOSITORY_LIMITS.maxCases) {
+        errors.push(`config.cases: must contain between 1 and ${SYNTHETIC_REPOSITORY_LIMITS.maxCases} cases (received ${cases.length}).`);
+        return { ok: false, errors };
+    }
+    const valid = [];
+    const firstIndexById = new Map();
+    cases.forEach((candidate, index) => {
+        const label = `cases[${index}]`;
+        const spec = validateCase(candidate, label, errors);
+        if (spec)
+            valid.push(spec);
+        const id = isPlainObject(candidate) ? candidate.id : undefined;
+        if (typeof id === "string") {
+            const key = id.toLowerCase();
+            const first = firstIndexById.get(key);
+            if (first === undefined) {
+                firstIndexById.set(key, index);
+            }
+            else {
+                errors.push(`${label}.id: duplicates cases[${first}].id (ids are compared without regard to letter case).`);
+            }
+        }
+    });
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const sorted = [...valid].sort((left, right) => compareCodeUnits(left.id, right.id));
+    return {
+        ok: true,
+        errors: [],
+        config: { schemaVersion: SYNTHETIC_REPOSITORY_CONFIG_SCHEMA_VERSION, cases: sorted },
+    };
+}
+/** Validates then returns the canonical configuration; throws SyntheticRepositoryConfigError when invalid. */
+export function normalizeSyntheticRepositoryConfig(input) {
+    const result = validateSyntheticRepositoryConfig(input);
+    if (!result.ok)
+        throw new SyntheticRepositoryConfigError(result.errors);
+    return result.config;
+}

package/dist/src/evaluation/syntheticRepository/evaluationCase.js

@@ -0,0 +1,43 @@
+import { describeSyntheticTask } from "./layout.js";
+/** The plan's answer key expressed in the existing benchmark answer-key vocabulary (no second correctness contract). */
+export function buildSyntheticAnswerKey(plan) {
+    const { factTextById } = describeSyntheticTask(plan);
+    return {
+        expectedFiles: [...plan.answerKey.expectedFiles],
+        expectedSymbols: [...plan.answerKey.expectedSymbols],
+        expectedFacts: plan.answerKey.facts.map((fact) => ({
+            id: fact.factId,
+            text: factTextById.get(fact.factId),
+            weight: fact.weight,
+            required: fact.required,
+        })),
+        expectedContextTargets: plan.answerKey.expectedContextTargets.map((target) => ({
+            file: target.file,
+            symbols: [...target.symbols],
+            required: target.required,
+        })),
+        minimumCorrectFacts: plan.answerKey.minimumCorrectFacts,
+    };
+}
+/**
+ * Builds the existing EvaluationCase directly in memory (never through readEvaluationCases, which owns
+ * repository-contained JSON cases). `targetRoot` is the stable logical root from the manifest; only
+ * `absoluteTargetRoot` carries the physical generated repository directory.
+ */
+export function buildSyntheticEvaluationCase(plan, manifest, repositoryRoot) {
+    const text = describeSyntheticTask(plan);
+    return {
+        id: plan.task.taskId,
+        title: text.title,
+        benchmarkProject: plan.logicalProjectId,
+        targetRoot: manifest.logicalTargetRoot,
+        sourceRoots: [...manifest.sourceRoots],
+        query: text.query,
+        expectedFiles: [...plan.answerKey.expectedFiles],
+        expectedSymbols: [...plan.answerKey.expectedSymbols],
+        rawIncludeGlobs: [...manifest.rawIncludeGlobs],
+        answerKey: buildSyntheticAnswerKey(plan),
+        taskLocality: plan.task.locality,
+        absoluteTargetRoot: repositoryRoot,
+    };
+}

package/dist/src/evaluation/syntheticRepository/identity.js

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { normalizeSyntheticRepositoryConfig, orderCaseSpec, validateSyntheticRepositoryCaseSpec } from "./config.js";
+import { SYNTHETIC_REPOSITORY_CONFIG_SCHEMA_ID, SYNTHETIC_REPOSITORY_CONFIG_SCHEMA_VERSION, SYNTHETIC_REPOSITORY_IDENTITY_ALGORITHM_VERSION, SyntheticRepositoryConfigError, } from "./types.js";
+/** Canonical JSON text of one valid case: fixed key order, exact values. */
+export function canonicalSyntheticRepositoryCaseText(spec) {
+    return JSON.stringify(orderCaseSpec(spec));
+}
+/** Canonical JSON text of a normalized configuration (cases already sorted by id). */
+export function canonicalSyntheticRepositoryConfigText(config) {
+    return JSON.stringify({
+        schemaVersion: config.schemaVersion,
+        cases: config.cases.map(orderCaseSpec),
+    });
+}
+/**
+ * SHA-256 over the UTF-8 bytes of five newline-joined lines: schema id, schema version, identity
+ * algorithm version, a domain tag ("case" or "config") and the canonical JSON payload. JSON escapes every
+ * newline, so the payload cannot forge an earlier line.
+ */
+function hashDomain(domain, payload) {
+    const text = [
+        SYNTHETIC_REPOSITORY_CONFIG_SCHEMA_ID,
+        SYNTHETIC_REPOSITORY_CONFIG_SCHEMA_VERSION,
+        SYNTHETIC_REPOSITORY_IDENTITY_ALGORITHM_VERSION,
+        domain,
+        payload,
+    ].join("\n");
+    return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}
+/** Per-case generation identity (lowercase 64-character SHA-256 hex). Throws on an invalid case. */
+export function computeSyntheticRepositoryCaseIdentity(input) {
+    const result = validateSyntheticRepositoryCaseSpec(input);
+    if (!result.ok)
+        throw new SyntheticRepositoryConfigError(result.errors);
+    return hashDomain("case", canonicalSyntheticRepositoryCaseText(result.spec));
+}
+/** Whole-configuration identity over the normalized form; input case order never matters. */
+export function computeSyntheticRepositoryConfigIdentity(input) {
+    const config = normalizeSyntheticRepositoryConfig(input);
+    return hashDomain("config", canonicalSyntheticRepositoryConfigText(config));
+}