@dailephd/my-dev-kit-lab 0.7.1 → 0.8.0

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/retrievalQuality/buildRetrievalEvidence.js

@@ -0,0 +1,292 @@
+import { compareCodeUnits } from "../indexSnapshot.js";
+import { RETRIEVAL_COMMAND_FAMILIES } from "./types.js";
+const MAX_PATH_LENGTH = 1024;
+const REASON_COMMAND_FAILED = "command-failed";
+const REASON_NOT_JSON = "output-is-not-json";
+const REASON_UNSUPPORTED = "output-is-not-the-supported-upstream-schema";
+const REASON_REJECTED = "unsafe-or-invalid-identity-rejected";
+const REASON_NO_SELECTED_FILE = "no-selected-file-for-source-attribution";
+const REASON_SELECTION_UNTRUSTED = "selection-not-backed-by-supported-search-output";
+const REASON_DUPLICATE = "repeated-command-family-ignored";
+/**
+ * Normalizes a repository-relative path to the single platform-neutral form (forward slashes, no leading
+ * "./"). Returns null for anything that is not a safe repository-relative path: absolute, drive-qualified,
+ * UNC, traversing, or containing empty segments. It never repairs an unsafe value into a plausible one.
+ *
+ * Same contract as the context-window-scaling plugin's `normalizeRepositoryRelativePath`; kept local so the
+ * evaluation layer does not import from an experiment plugin. The unit tests assert the two agree.
+ */
+export function normalizeRetrievedRepositoryPath(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_PATH_LENGTH || value.includes("\0")) {
+        return null;
+    }
+    let normalized = value.replace(/\\/g, "/");
+    while (normalized.startsWith("./")) {
+        normalized = normalized.slice(2);
+    }
+    if (normalized.length === 0 || normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized)) {
+        return null;
+    }
+    if (normalized.split("/").some((segment) => segment === ".." || segment === "")) {
+        return null;
+    }
+    return normalized;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function symbolKey(name, nodeId, file) {
+    return nodeId !== undefined ? `id\0${nodeId}` : `name\0${file ?? ""}\0${name}`;
+}
+/**
+ * Reads one upstream node-like entry. Only `file` and `symbol` kinds are evidence; edges and every other
+ * kind carry no explicit file/symbol identity of their own and are ignored. Fields are read by their
+ * documented names only; identifiers embedded inside other strings are never parsed.
+ */
+function readNode(entry, idKey) {
+    if (!isRecord(entry) || typeof entry.kind !== "string") {
+        return { type: "rejected" };
+    }
+    if (entry.kind === "file") {
+        const path = normalizeRetrievedRepositoryPath(entry.path);
+        return path === null ? { type: "rejected" } : { type: "file", path };
+    }
+    if (entry.kind === "symbol") {
+        const name = typeof entry.symbolName === "string" && entry.symbolName.length > 0 ? entry.symbolName : entry.label;
+        if (typeof name !== "string" || name.length === 0) {
+            return { type: "rejected" };
+        }
+        let file;
+        if (entry.path !== undefined) {
+            const normalized = normalizeRetrievedRepositoryPath(entry.path);
+            if (normalized === null) {
+                return { type: "rejected" };
+            }
+            file = normalized;
+        }
+        const rawId = entry[idKey];
+        if (rawId !== undefined && (typeof rawId !== "string" || rawId.length === 0)) {
+            return { type: "rejected" };
+        }
+        return { type: "symbol", name, nodeId: rawId, file };
+    }
+    return { type: "ignored" };
+}
+function interpretEntries(family, entries, idKey, files, symbols) {
+    const result = { parseState: "parsed", files: new Set(), symbolKeys: new Set(), rejected: 0 };
+    for (const entry of entries) {
+        const reading = readNode(entry, idKey);
+        if (reading.type === "ignored")
+            continue;
+        if (reading.type === "rejected") {
+            result.rejected += 1;
+            continue;
+        }
+        if (reading.type === "file") {
+            addFile(files, reading.path, family);
+            result.files.add(reading.path);
+            continue;
+        }
+        const key = symbolKey(reading.name, reading.nodeId, reading.file);
+        const existing = symbols.get(key);
+        if (existing) {
+            existing.surfacedBy.add(family);
+        }
+        else {
+            symbols.set(key, { name: reading.name, nodeId: reading.nodeId, file: reading.file, surfacedBy: new Set([family]) });
+        }
+        result.symbolKeys.add(key);
+        if (reading.file !== undefined) {
+            // A symbol node carries an explicit file identity, so that file is surfaced by the same command.
+            addFile(files, reading.file, family);
+            result.files.add(reading.file);
+        }
+    }
+    if (result.rejected > 0) {
+        result.reason = REASON_REJECTED;
+    }
+    return result;
+}
+function addFile(files, path, family) {
+    const existing = files.get(path);
+    if (existing) {
+        existing.add(family);
+    }
+    else {
+        files.set(path, new Set([family]));
+    }
+}
+function failedInterpretation(parseState, reason) {
+    return { parseState, files: new Set(), symbolKeys: new Set(), rejected: 0, reason };
+}
+function interpretStructured(command, files, symbols) {
+    const payload = parseJson(command.stdout);
+    if (!isRecord(payload)) {
+        return failedInterpretation(payload === undefined ? "malformed" : "unsupported-schema", payload === undefined ? REASON_NOT_JSON : REASON_UNSUPPORTED);
+    }
+    if (command.family === "search") {
+        const supported = payload.artifactKind === "my-dev-kit-v1-search-result" &&
+            typeof payload.version === "string" &&
+            payload.version.startsWith("1.") &&
+            Array.isArray(payload.results);
+        return supported
+            ? interpretEntries("search", payload.results, "nodeId", files, symbols)
+            : failedInterpretation("unsupported-schema", REASON_UNSUPPORTED);
+    }
+    if (command.family === "lookup") {
+        const supported = payload.status === "found" && isRecord(payload.node) && Array.isArray(payload.neighbors);
+        return supported
+            ? interpretEntries("lookup", [payload.node, ...payload.neighbors], "id", files, symbols)
+            : failedInterpretation("unsupported-schema", REASON_UNSUPPORTED);
+    }
+    const supported = payload.artifactKind === "my-dev-kit-v1-graph-slice" && typeof payload.version === "string" && payload.version.startsWith("1.") && Array.isArray(payload.nodes);
+    return supported
+        ? interpretEntries("slice", payload.nodes, "id", files, symbols)
+        : failedInterpretation("unsupported-schema", REASON_UNSUPPORTED);
+}
+/**
+ * Source output is context text. Evidence is attributed only from the trusted selection the lifecycle
+ * passed to the source command: its selected file, and the symbol already surfaced by structured output
+ * under the same node id. Nothing is read from the source body.
+ */
+function attributeSource(selection, searchInterpreted, files, symbols) {
+    if (!searchInterpreted) {
+        // The selection was derived from search output; without supported search evidence it is not trusted.
+        return failedInterpretation("unattributable", REASON_SELECTION_UNTRUSTED);
+    }
+    if (selection?.file === undefined) {
+        return failedInterpretation("unattributable", REASON_NO_SELECTED_FILE);
+    }
+    const path = normalizeRetrievedRepositoryPath(selection.file);
+    if (path === null) {
+        return { ...failedInterpretation("unattributable", REASON_REJECTED), rejected: 1 };
+    }
+    const result = { parseState: "selection-attributed", files: new Set([path]), symbolKeys: new Set(), rejected: 0 };
+    addFile(files, path, "source");
+    if (selection.nodeId !== undefined) {
+        const key = symbolKey("", selection.nodeId, undefined);
+        const known = symbols.get(key);
+        if (known) {
+            known.surfacedBy.add("source");
+            result.symbolKeys.add(key);
+        }
+    }
+    return result;
+}
+function orderedProvenance(provenance) {
+    return RETRIEVAL_COMMAND_FAMILIES.filter((family) => provenance.has(family));
+}
+function isFullyInterpreted(entry) {
+    return (entry.parseState === "parsed" || entry.parseState === "selection-attributed") && entry.rejectedIdentityCount === 0;
+}
+/**
+ * Pure policy: builds normalized retrieval evidence from the commands the lifecycle executed.
+ * Deterministic: output ordering depends only on code-unit comparison of identities and the fixed
+ * search -> lookup -> slice -> source family order, never on input order or object enumeration.
+ */
+export function buildRetrievalEvidence(input) {
+    const files = new Map();
+    const symbols = new Map();
+    const interpreted = new Map();
+    const duplicates = [];
+    const ordered = RETRIEVAL_COMMAND_FAMILIES.flatMap((family) => input.commands.filter((command) => command.family === family));
+    // Symbol attribution for source depends on structured evidence, so structured families run first (they do
+    // by family order); source is last.
+    for (const command of ordered) {
+        if (interpreted.has(command.family)) {
+            duplicates.push(command.family);
+            continue;
+        }
+        let outcome;
+        if (!command.ok) {
+            outcome = failedInterpretation("command-failed", REASON_COMMAND_FAILED);
+        }
+        else if (command.family === "source") {
+            outcome = attributeSource(input.selection, interpreted.get("search")?.parseState === "parsed", files, symbols);
+        }
+        else {
+            outcome = interpretStructured(command, files, symbols);
+        }
+        interpreted.set(command.family, {
+            family: command.family,
+            succeeded: command.ok,
+            parseState: outcome.parseState,
+            fileEvidenceCount: outcome.files.size,
+            symbolEvidenceCount: outcome.symbolKeys.size,
+            rejectedIdentityCount: outcome.rejected,
+            ...(outcome.reason !== undefined ? { reason: outcome.reason } : {})
+        });
+    }
+    const commands = RETRIEVAL_COMMAND_FAMILIES.flatMap((family) => {
+        const entry = interpreted.get(family);
+        return entry ? [entry] : [];
+    });
+    const fileEvidence = [...files.entries()]
+        .map(([path, provenance]) => ({ path, surfacedBy: orderedProvenance(provenance) }))
+        .sort((left, right) => compareCodeUnits(left.path, right.path));
+    const symbolEvidence = [...symbols.values()]
+        .map((symbol) => ({
+        name: symbol.name,
+        ...(symbol.nodeId !== undefined ? { nodeId: symbol.nodeId } : {}),
+        ...(symbol.file !== undefined ? { file: symbol.file } : {}),
+        surfacedBy: orderedProvenance(symbol.surfacedBy)
+    }))
+        .sort((left, right) => compareCodeUnits(left.file ?? "", right.file ?? "") ||
+        compareCodeUnits(left.name, right.name) ||
+        compareCodeUnits(left.nodeId ?? "", right.nodeId ?? ""));
+    const search = interpreted.get("search");
+    let availability;
+    let availabilityReason;
+    if (commands.length === 0) {
+        availability = "unavailable";
+        availabilityReason = "no-retrieval-commands-executed";
+    }
+    else if (!search) {
+        availability = "unavailable";
+        availabilityReason = "search-command-not-executed";
+    }
+    else if (search.parseState !== "parsed") {
+        availability = "unavailable";
+        availabilityReason = "search-evidence-unavailable";
+    }
+    else if (duplicates.length > 0 || !commands.every(isFullyInterpreted)) {
+        availability = "partial";
+        availabilityReason = "some-executed-commands-were-not-fully-interpreted";
+    }
+    else {
+        availability = "available";
+    }
+    return {
+        schemaVersion: "retrieval-evidence-v1",
+        availability,
+        ...(availabilityReason !== undefined ? { availabilityReason } : {}),
+        files: fileEvidence,
+        symbols: symbolEvidence,
+        commands: commands.map((entry) => duplicates.includes(entry.family) && entry.reason === undefined ? { ...entry, reason: REASON_DUPLICATE } : entry)
+    };
+}
+/**
+ * Thin adapter from the lifecycle's measured commands to the pure builder. Only the four retrieval
+ * families are considered; `index`, `version`, and any other command are ignored. Source stdout is dropped
+ * here on purpose.
+ */
+export function buildRetrievalEvidenceFromCommands(commands, selection) {
+    const inputs = [];
+    for (const command of commands) {
+        if (command.commandId === "source") {
+            inputs.push({ family: "source", ok: command.ok });
+        }
+        else if (command.commandId === "search" || command.commandId === "lookup" || command.commandId === "slice") {
+            inputs.push({ family: command.commandId, ok: command.ok, stdout: command.stdout });
+        }
+    }
+    return buildRetrievalEvidence({ commands: inputs, selection });
+}

package/dist/src/evaluation/retrievalQuality/corpusCompleteness.js

@@ -0,0 +1,122 @@
+import { normalizeRetrievedRepositoryPath } from "./buildRetrievalEvidence.js";
+import { hasFactMapping, interpretFactContextTarget } from "./factContextTargets.js";
+const asRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+function normalizedSet(values, normalize) {
+    if (!Array.isArray(values))
+        return undefined;
+    const result = new Set();
+    for (const value of values) {
+        const normalized = normalize(value);
+        if (normalized === null)
+            return undefined;
+        result.add(normalized);
+    }
+    return result;
+}
+const plainString = (value) => (typeof value === "string" && value.length > 0 ? value : null);
+/**
+ * Ground-truth completeness for one retrieval-precision-recall case. Returns bounded error strings that never
+ * echo unsafe values. This rule set applies only to corpora that opt into retrieval-precision-recall; it is not
+ * a global answer-key rule.
+ */
+export function validateRetrievalPrecisionRecallCase(evaluationCase) {
+    const label = `retrieval-precision-recall case ${typeof evaluationCase.id === "string" ? evaluationCase.id : "<unknown>"}`;
+    const answerKey = asRecord(evaluationCase.answerKey);
+    if (!answerKey)
+        return [`${label}: answerKey is required.`];
+    const errors = [];
+    const expectedFiles = normalizedSet(answerKey.expectedFiles, normalizeRetrievedRepositoryPath);
+    const expectedSymbols = normalizedSet(answerKey.expectedSymbols, plainString);
+    if (expectedFiles === undefined || expectedFiles.size === 0)
+        errors.push(`${label}: answerKey.expectedFiles must be a nonempty array of safe repository-relative paths.`);
+    if (expectedSymbols === undefined || expectedSymbols.size === 0)
+        errors.push(`${label}: answerKey.expectedSymbols must be a nonempty array of nonempty strings.`);
+    const topFiles = normalizedSet(evaluationCase.expectedFiles, normalizeRetrievedRepositoryPath);
+    const topSymbols = normalizedSet(evaluationCase.expectedSymbols, plainString);
+    const sameSet = (left, right) => left !== undefined && right !== undefined && left.size === right.size && [...left].every((value) => right.has(value));
+    if (expectedFiles !== undefined && !sameSet(topFiles, expectedFiles))
+        errors.push(`${label}: expectedFiles must agree with answerKey.expectedFiles.`);
+    if (expectedSymbols !== undefined && !sameSet(topSymbols, expectedSymbols))
+        errors.push(`${label}: expectedSymbols must agree with answerKey.expectedSymbols.`);
+    const facts = answerKey.expectedFacts;
+    const factIds = [];
+    if (!Array.isArray(facts) || facts.length === 0) {
+        errors.push(`${label}: answerKey.expectedFacts must be a nonempty array.`);
+    }
+    else {
+        for (const fact of facts) {
+            const id = asRecord(fact)?.id;
+            if (typeof id !== "string" || id.length === 0 || factIds.includes(id)) {
+                errors.push(`${label}: answerKey.expectedFacts must have unique nonempty ids.`);
+                break;
+            }
+            factIds.push(id);
+        }
+    }
+    const targets = answerKey.expectedContextTargets;
+    if (!Array.isArray(targets) || targets.length === 0) {
+        errors.push(`${label}: answerKey.expectedContextTargets is required for fact coverage.`);
+        return errors;
+    }
+    const known = new Set(factIds);
+    const requiredMappedFacts = new Set();
+    targets.forEach((target, index) => {
+        const targetLabel = `${label}: answerKey.expectedContextTargets[${index}]`;
+        const record = asRecord(target);
+        if (!record) {
+            errors.push(`${targetLabel}: target must be an object.`);
+            return;
+        }
+        if (hasFactMapping(target)) {
+            const interpretation = interpretFactContextTarget(target, known);
+            if (!interpretation.ok) {
+                errors.push(`${targetLabel}: ${interpretation.problem}.`);
+                return;
+            }
+            if (interpretation.target.required)
+                interpretation.target.factIds.forEach((id) => requiredMappedFacts.add(id));
+        }
+        // No hidden expectation outside the answer key, mapped or not.
+        const file = normalizeRetrievedRepositoryPath(record.file);
+        if (file === null) {
+            errors.push(`${targetLabel}: file must be a safe repository-relative path.`);
+        }
+        else if (expectedFiles !== undefined && !expectedFiles.has(file)) {
+            errors.push(`${targetLabel}: file must be listed in answerKey.expectedFiles.`);
+        }
+        if (Array.isArray(record.symbols) && expectedSymbols !== undefined) {
+            for (const symbol of record.symbols) {
+                if (typeof symbol !== "string" || !expectedSymbols.has(symbol)) {
+                    errors.push(`${targetLabel}: every symbol must be listed in answerKey.expectedSymbols.`);
+                    break;
+                }
+            }
+        }
+    });
+    for (const id of factIds) {
+        if (!requiredMappedFacts.has(id))
+            errors.push(`${label}: expected fact ${id} has no required fact-mapped context target.`);
+    }
+    return errors;
+}
+/** Validates every case of a production retrieval-precision-recall corpus; case ids must be unique. */
+export function validateRetrievalPrecisionRecallCorpus(cases) {
+    const errors = [];
+    const seen = new Set();
+    for (const evaluationCase of cases) {
+        if (seen.has(evaluationCase.id))
+            errors.push(`retrieval-precision-recall corpus: duplicate case id ${evaluationCase.id}.`);
+        seen.add(evaluationCase.id);
+        errors.push(...validateRetrievalPrecisionRecallCase(evaluationCase));
+    }
+    return errors;
+}
+/**
+ * Per-case issue counts without any identity text. Use this, never the detailed messages, when reporting about an
+ * external private subject: the detailed messages may name expected facts.
+ */
+export function summarizeRetrievalGroundTruthIssuesSafely(cases) {
+    return cases
+        .map((evaluationCase) => ({ caseId: evaluationCase.id, issueCount: validateRetrievalPrecisionRecallCase(evaluationCase).length }))
+        .filter((entry) => entry.issueCount > 0);
+}

package/dist/src/evaluation/retrievalQuality/factContextTargets.js

@@ -0,0 +1,44 @@
+import { normalizeRetrievedRepositoryPath } from "./buildRetrievalEvidence.js";
+/** True when the target participates in fact mapping, i.e. it carries a `factIds` field. */
+export function hasFactMapping(target) {
+    return typeof target === "object" && target !== null && !Array.isArray(target) && target.factIds !== undefined;
+}
+/**
+ * Single owner of the `ExpectedContextTarget.factIds` contract. Pure. Problems are fixed bounded strings and
+ * never echo the offending value. Unsafe file identities are rejected, never repaired.
+ */
+export function interpretFactContextTarget(target, knownFactIds) {
+    if (typeof target !== "object" || target === null || Array.isArray(target)) {
+        return { ok: false, problem: "target must be an object" };
+    }
+    const record = target;
+    const file = normalizeRetrievedRepositoryPath(record.file);
+    if (file === null) {
+        return { ok: false, problem: "file must be a safe repository-relative path" };
+    }
+    const rawFactIds = record.factIds;
+    if (!Array.isArray(rawFactIds) || rawFactIds.length === 0 || rawFactIds.some((id) => typeof id !== "string" || id.length === 0)) {
+        return { ok: false, problem: "factIds must be a nonempty array of nonempty strings" };
+    }
+    const factIds = rawFactIds;
+    if (new Set(factIds).size !== factIds.length) {
+        return { ok: false, problem: "factIds must not contain duplicates" };
+    }
+    if (factIds.some((id) => !knownFactIds.has(id))) {
+        return { ok: false, problem: "factIds must reference existing expectedFacts ids" };
+    }
+    let symbols = [];
+    if (record.symbols !== undefined) {
+        if (!Array.isArray(record.symbols) || record.symbols.some((symbol) => typeof symbol !== "string" || symbol.length === 0)) {
+            return { ok: false, problem: "symbols must be an array of nonempty strings" };
+        }
+        symbols = record.symbols;
+        if (new Set(symbols).size !== symbols.length) {
+            return { ok: false, problem: "symbols must not contain duplicates" };
+        }
+    }
+    if (record.required !== undefined && typeof record.required !== "boolean") {
+        return { ok: false, problem: "required must be a boolean when present" };
+    }
+    return { ok: true, target: { file, symbols: [...symbols], required: record.required !== false, factIds: [...factIds] } };
+}