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

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

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./buildRetrievalEvidence.js";
+export * from "./factContextTargets.js";
+export * from "./metrics.js";
+export * from "./corpusCompleteness.js";

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

@@ -0,0 +1,233 @@
+import { compareCodeUnits } from "../indexSnapshot.js";
+import { normalizeRetrievedRepositoryPath } from "./buildRetrievalEvidence.js";
+import { hasFactMapping, interpretFactContextTarget } from "./factContextTargets.js";
+const sortedUnique = (values) => [...new Set(values)].sort(compareCodeUnits);
+function ratio(numerator, denominator, notApplicableReason) {
+    if (denominator === 0) {
+        return { availability: "not-applicable", numerator: null, denominator: null, value: null, reason: notApplicableReason };
+    }
+    return { availability: "available", numerator, denominator, value: numerator / denominator, reason: null };
+}
+function unavailableRatio(reason) {
+    return { availability: "unavailable", numerator: null, denominator: null, value: null, reason };
+}
+function normalizeExpectedFiles(values) {
+    if (!Array.isArray(values))
+        return { ok: false, reason: "expected-files-missing" };
+    const normalized = [];
+    for (const value of values) {
+        const path = normalizeRetrievedRepositoryPath(value);
+        if (path === null)
+            return { ok: false, reason: "unsafe-expected-file-identity" };
+        normalized.push(path);
+    }
+    return { ok: true, values: sortedUnique(normalized) };
+}
+function normalizeExpectedSymbols(values) {
+    if (!Array.isArray(values))
+        return { ok: false, reason: "expected-symbols-missing" };
+    if (values.some((value) => typeof value !== "string" || value.length === 0))
+        return { ok: false, reason: "invalid-expected-symbol" };
+    return { ok: true, values: sortedUnique(values) };
+}
+function sameSet(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+/**
+ * The answer key is the semantic source of relevance. A top-level expectation that is also present must agree
+ * with it after normalization; disagreement is never silently reconciled.
+ */
+function resolveExpectation(topLevel, answerKeyValues, hasAnswerKey, normalize, mismatchReason) {
+    if (!hasAnswerKey)
+        return normalize(topLevel);
+    const fromKey = normalize(answerKeyValues);
+    if (!fromKey.ok)
+        return fromKey;
+    if (Array.isArray(topLevel)) {
+        const fromTop = normalize(topLevel);
+        if (!fromTop.ok)
+            return fromTop;
+        if (!sameSet(fromTop.values, fromKey.values))
+            return { ok: false, reason: mismatchReason };
+    }
+    return fromKey;
+}
+const expectationStatus = (resolved) => resolved.ok ? { availability: "available", reason: null } : { availability: "unavailable", reason: resolved.reason };
+/** Symbol name -> normalized files it was retrieved from. Symbols without file identity cannot satisfy a file-specific target. */
+function symbolFilesByName(evidence) {
+    const byName = new Map();
+    for (const symbol of evidence.symbols) {
+        if (symbol.file === undefined)
+            continue;
+        const files = byName.get(symbol.name) ?? new Set();
+        files.add(symbol.file);
+        byName.set(symbol.name, files);
+    }
+    return byName;
+}
+function calculateFactCoverage(answerKey, evidence, retrievedFiles) {
+    if (!answerKey || typeof answerKey !== "object")
+        return { kind: "unavailable", reason: "answer-key-missing" };
+    const facts = answerKey.expectedFacts;
+    if (!Array.isArray(facts))
+        return { kind: "unavailable", reason: "expected-facts-invalid" };
+    const factIds = [];
+    for (const fact of facts) {
+        const id = typeof fact === "object" && fact !== null ? fact.id : undefined;
+        if (typeof id !== "string" || id.length === 0 || factIds.includes(id)) {
+            return { kind: "unavailable", reason: "expected-facts-invalid" };
+        }
+        factIds.push(id);
+    }
+    if (factIds.length === 0)
+        return { kind: "not-applicable", reason: "no-expected-facts" };
+    const targets = answerKey.expectedContextTargets;
+    if (!Array.isArray(targets))
+        return { kind: "unavailable", reason: "fact-context-mapping-unavailable" };
+    const known = new Set(factIds);
+    const targetsByFact = new Map(factIds.map((id) => [id, []]));
+    for (const target of targets) {
+        if (!hasFactMapping(target))
+            continue;
+        const required = target.required !== false;
+        const interpretation = interpretFactContextTarget(target, known);
+        if (!interpretation.ok) {
+            // An invalid optional target cannot gate coverage; an invalid required one makes the mapping untrustworthy.
+            if (required)
+                return { kind: "unavailable", reason: "fact-context-mapping-invalid" };
+            continue;
+        }
+        if (!interpretation.target.required)
+            continue;
+        for (const id of interpretation.target.factIds)
+            targetsByFact.get(id)?.push(interpretation.target);
+    }
+    if (factIds.some((id) => (targetsByFact.get(id) ?? []).length === 0)) {
+        return { kind: "unavailable", reason: "fact-context-mapping-unavailable" };
+    }
+    const symbolFiles = symbolFilesByName(evidence);
+    const isCovered = (target) => retrievedFiles.has(target.file) && target.symbols.every((symbol) => symbolFiles.get(symbol)?.has(target.file) === true);
+    const covered = factIds.filter((id) => (targetsByFact.get(id) ?? []).every(isCovered));
+    const coveredSet = new Set(covered);
+    return {
+        kind: "computed",
+        covered: sortedUnique(covered),
+        uncovered: sortedUnique(factIds.filter((id) => !coveredSet.has(id))),
+        total: factIds.length
+    };
+}
+function evidenceReason(evidence) {
+    if (evidence === undefined)
+        return "retrieval-evidence-missing";
+    if (evidence.availability === "partial")
+        return "retrieval-evidence-partial";
+    if (evidence.availability === "unavailable")
+        return "retrieval-evidence-unavailable";
+    return null;
+}
+/**
+ * Pure per-case retrieval-quality calculation. Formulas are planner-frozen:
+ * file precision = |R_file ∩ E_file| / |R_file|; file recall = |R_file ∩ E_file| / |E_file|;
+ * irrelevant context ratio = |R_file - E_file| / |R_file|; symbol precision/recall use the same set formulas
+ * over exact unique symbol names; fact coverage = covered facts / expected facts, unweighted and derived only
+ * from explicit `factIds` target mappings. No input is mutated and nothing is read from disk or text.
+ * Unavailable or not-applicable results are never converted to zero.
+ */
+export function calculateRetrievalQualityMetrics(input) {
+    const { evaluationCase, retrieval } = input;
+    const evidence = retrieval.retrievalEvidence;
+    const evidenceBlocked = evidenceReason(evidence);
+    const answerKey = evaluationCase.answerKey;
+    const hasAnswerKey = answerKey !== undefined && answerKey !== null && typeof answerKey === "object";
+    const expectedFiles = resolveExpectation(evaluationCase.expectedFiles, hasAnswerKey ? answerKey.expectedFiles : undefined, hasAnswerKey, normalizeExpectedFiles, "expected-files-answer-key-mismatch");
+    const expectedSymbols = resolveExpectation(evaluationCase.expectedSymbols, hasAnswerKey ? answerKey.expectedSymbols : undefined, hasAnswerKey, normalizeExpectedSymbols, "expected-symbols-answer-key-mismatch");
+    const usable = evidenceBlocked === null && evidence !== undefined ? evidence : undefined;
+    const retrievedFiles = usable ? sortedUnique(usable.files.map((file) => file.path)) : undefined;
+    const retrievedSymbols = usable ? sortedUnique(usable.symbols.map((symbol) => symbol.name)) : undefined;
+    // ---- files
+    let file = {
+        relevantRetrievedFiles: null,
+        irrelevantRetrievedFiles: null,
+        missedFiles: null,
+        missedFileCount: null,
+        precision: unavailableRatio(evidenceBlocked ?? (expectedFiles.ok ? "unavailable" : expectedFiles.reason)),
+        recall: unavailableRatio(evidenceBlocked ?? (expectedFiles.ok ? "unavailable" : expectedFiles.reason))
+    };
+    let irrelevantContextRatio = unavailableRatio(evidenceBlocked ?? (expectedFiles.ok ? "unavailable" : expectedFiles.reason));
+    if (retrievedFiles !== undefined && expectedFiles.ok) {
+        const expected = new Set(expectedFiles.values);
+        const retrieved = new Set(retrievedFiles);
+        const relevant = retrievedFiles.filter((path) => expected.has(path));
+        const irrelevant = retrievedFiles.filter((path) => !expected.has(path));
+        const missed = expectedFiles.values.filter((path) => !retrieved.has(path));
+        file = {
+            relevantRetrievedFiles: relevant,
+            irrelevantRetrievedFiles: irrelevant,
+            missedFiles: missed,
+            missedFileCount: missed.length,
+            precision: ratio(relevant.length, retrievedFiles.length, "no-retrieved-files"),
+            recall: ratio(relevant.length, expectedFiles.values.length, "no-expected-files")
+        };
+        irrelevantContextRatio = ratio(irrelevant.length, retrievedFiles.length, "no-retrieved-files");
+    }
+    // ---- symbols (exact unique names)
+    let symbol = {
+        relevantRetrievedSymbols: null,
+        irrelevantRetrievedSymbols: null,
+        missedSymbols: null,
+        missedSymbolCount: null,
+        precision: unavailableRatio(evidenceBlocked ?? (expectedSymbols.ok ? "unavailable" : expectedSymbols.reason)),
+        recall: unavailableRatio(evidenceBlocked ?? (expectedSymbols.ok ? "unavailable" : expectedSymbols.reason))
+    };
+    if (retrievedSymbols !== undefined && expectedSymbols.ok) {
+        const expected = new Set(expectedSymbols.values);
+        const retrieved = new Set(retrievedSymbols);
+        const relevant = retrievedSymbols.filter((name) => expected.has(name));
+        const missed = expectedSymbols.values.filter((name) => !retrieved.has(name));
+        symbol = {
+            relevantRetrievedSymbols: relevant,
+            irrelevantRetrievedSymbols: retrievedSymbols.filter((name) => !expected.has(name)),
+            missedSymbols: missed,
+            missedSymbolCount: missed.length,
+            precision: ratio(relevant.length, retrievedSymbols.length, "no-retrieved-symbols"),
+            recall: ratio(relevant.length, expectedSymbols.values.length, "no-expected-symbols")
+        };
+    }
+    // ---- facts
+    let fact = {
+        coveredFactIds: null,
+        uncoveredFactIds: null,
+        uncoveredFactCount: null,
+        coverage: unavailableRatio(evidenceBlocked ?? "unavailable")
+    };
+    if (usable !== undefined && retrievedFiles !== undefined) {
+        const outcome = calculateFactCoverage(answerKey, usable, new Set(retrievedFiles));
+        if (outcome.kind === "computed") {
+            fact = {
+                coveredFactIds: outcome.covered,
+                uncoveredFactIds: outcome.uncovered,
+                uncoveredFactCount: outcome.uncovered.length,
+                coverage: ratio(outcome.covered.length, outcome.total, "no-expected-facts")
+            };
+        }
+        else {
+            fact = { ...fact, coverage: outcome.kind === "unavailable" ? unavailableRatio(outcome.reason) : { availability: "not-applicable", numerator: null, denominator: null, value: null, reason: outcome.reason } };
+        }
+    }
+    const tokensValid = typeof retrieval.totalEstimatedTokens === "number" && Number.isFinite(retrieval.totalEstimatedTokens) && retrieval.totalEstimatedTokens >= 0;
+    return {
+        schemaVersion: "retrieval-quality-metrics-v1",
+        caseId: evaluationCase.id,
+        evidence: {
+            availability: evidence === undefined ? "missing" : evidence.availability,
+            reason: evidence === undefined ? "retrieval-evidence-missing" : (evidence.availabilityReason ?? null)
+        },
+        expectations: { files: expectationStatus(expectedFiles), symbols: expectationStatus(expectedSymbols) },
+        file,
+        symbol,
+        fact,
+        irrelevantContextRatio,
+        retrievedTokenCount: tokensValid ? retrieval.totalEstimatedTokens : null,
+        tokenCountMethod: tokensValid && typeof retrieval.tokenCountMethod === "string" ? retrieval.tokenCountMethod : null
+    };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Normalized retrieval-evidence contract (V1).
+ *
+ * Describes which files and symbols the existing my-dev-kit search -> lookup -> slice -> source
+ * lifecycle actually surfaced. It is observation only: it carries no relevance judgement and no
+ * score. It deliberately contains no source text, stdout/stderr bodies, or machine-local paths.
+ */
+/** Retrieval command families in fixed lifecycle order. */
+export const RETRIEVAL_COMMAND_FAMILIES = ["search", "lookup", "slice", "source"];

package/dist/src/evaluation/runMyDevKitRetrieval.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { countEstimatedTokens, countTextChars, tokenCountMethod } from "../core/countTokens.js";
 import { runMeasuredCommand } from "../core/runMeasuredCommand.js";
 import { interpretToolVersionOutput } from "./indexSnapshot.js";
+import { buildRetrievalEvidenceFromCommands } from "./retrievalQuality/buildRetrievalEvidence.js";
 const VERSION_PROBE_TIMEOUT_MS = 30_000;
 function parseJsonIfPossible(text) {
     try {
@@ -52,6 +53,7 @@ function skippedRetrieval(caseId, warnings, commands, durationMs) {
         contextText: "",
         filesRead: [],
         commands,
+        retrievalEvidence: buildRetrievalEvidenceFromCommands(commands),
         durationMs
     };
 }
@@ -177,6 +179,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] : []),
@@ -336,6 +339,7 @@ export async function runMyDevKitRetrievalFromIndex(options) {
         selectedNodeId,
         selectedFile,
         selectedSymbol,
+        retrievalEvidence: buildRetrievalEvidenceFromCommands(commands, { nodeId: selectedNodeId, file: selectedFile }),
         durationMs: Date.now() - started
     };
 }
@@ -352,7 +356,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/targetImmutability/captureTargetSnapshot.js

@@ -18,7 +18,7 @@ function isInsideRoot(resolvedRoot, candidate) {
     const relative = path.relative(resolvedRoot, candidate);
     return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
-async function snapshotPathEntry(resolvedPath) {
+async function snapshotPathEntry(resolvedPath, maxHashedFileBytes) {
     let stats;
     try {
         stats = await lstat(resolvedPath);
@@ -38,6 +38,15 @@ async function snapshotPathEntry(resolvedPath) {
         return { state: "directory", sha256: null, symbolicLinkTarget: null };
     }
     if (stats.isFile()) {
+        if (maxHashedFileBytes !== undefined && stats.size > maxHashedFileBytes) {
+            // Safe mode: a file above the bound is fingerprinted by metadata and its contents are never read.
+            return {
+                state: "file",
+                sha256: null,
+                symbolicLinkTarget: null,
+                contentFingerprint: { sizeBytes: stats.size, mtimeMs: stats.mtimeMs }
+            };
+        }
         const contents = await readFile(resolvedPath);
         return { state: "file", sha256: sha256Hex(contents), symbolicLinkTarget: null };
     }
@@ -69,8 +78,9 @@ async function runRequiredGit(resolvedRoot, args, targetRootPath) {
         : `git ${args.join(" ")} failed: ${result.message}`;
     return { ok: false, code, targetRootPath, message };
 }
-export async function captureTargetSnapshot(config) {
+export async function captureTargetSnapshot(config, options = {}) {
     const resolvedTargetRootPath = path.resolve(config.targetRootPath);
+    const maxHashedFileBytes = options.externalLocalSafe?.maxHashedFileBytes;
     let rootStats;
     try {
         rootStats = await lstat(resolvedTargetRootPath);
@@ -113,13 +123,14 @@ export async function captureTargetSnapshot(config) {
             };
         }
         try {
-            const entry = await snapshotPathEntry(resolvedPath);
+            const entry = await snapshotPathEntry(resolvedPath, maxHashedFileBytes);
             configuredFiles.push({
                 relativePath,
                 resolvedPath,
                 state: entry.state,
                 sha256: entry.sha256,
-                symbolicLinkTarget: entry.symbolicLinkTarget
+                symbolicLinkTarget: entry.symbolicLinkTarget,
+                ...(entry.contentFingerprint ? { contentFingerprint: entry.contentFingerprint } : {})
             });
         }
         catch (error) {
@@ -183,15 +194,25 @@ export async function captureTargetSnapshot(config) {
     const untrackedFiles = [];
     for (const untrackedRelativePath of untrackedPaths) {
         const resolvedPath = path.resolve(resolvedTargetRootPath, untrackedRelativePath);
-        const entry = await snapshotPathEntry(resolvedPath);
+        const entry = await snapshotPathEntry(resolvedPath, maxHashedFileBytes);
         const state = entry.state === "directory" ? "other" : entry.state;
         untrackedFiles.push({
             path: untrackedRelativePath,
             state,
             sha256: entry.sha256,
-            symbolicLinkTarget: entry.symbolicLinkTarget
+            symbolicLinkTarget: entry.symbolicLinkTarget,
+            ...(entry.contentFingerprint ? { contentFingerprint: entry.contentFingerprint } : {})
         });
     }
+    let ignoredPaths;
+    if (maxHashedFileBytes !== undefined) {
+        // Safe mode: Lab-created files in ignored locations (for example a stray index directory) are invisible to
+        // `git status`, so record the ignored path set by name. Contents are never read.
+        const ignoredOutcome = await runRequiredGit(resolvedTargetRootPath, ["ls-files", "--others", "--ignored", "--exclude-standard", "-z"], config.targetRootPath);
+        if (!ignoredOutcome.ok)
+            return ignoredOutcome;
+        ignoredPaths = ignoredOutcome.stdout.split("\0").filter((entry) => entry.length > 0).sort();
+    }
     const git = {
         availability: "available",
         branch,
@@ -199,7 +220,8 @@ export async function captureTargetSnapshot(config) {
         statusEntries,
         worktreeDiffSha256,
         stagedDiffSha256,
-        untrackedFiles
+        untrackedFiles,
+        ...(ignoredPaths !== undefined ? { ignoredPaths } : {})
     };
     return {
         ok: true,

package/dist/src/evaluation/targetImmutability/compareTargetSnapshots.js

@@ -38,6 +38,10 @@ export function compareTargetSnapshots(before, after) {
             mutations.push(mutation(`git.untracked:${afterEntry.path}`, "git-untracked-file", `git.untrackedFiles.${afterEntry.path}`, null, afterEntry));
         }
     }
+    if ((before.git.ignoredPaths !== undefined || after.git.ignoredPaths !== undefined) &&
+        !isDeepStrictEqual(before.git.ignoredPaths ?? null, after.git.ignoredPaths ?? null)) {
+        mutations.push(mutation("git.ignored-paths", "git-ignored-paths", "git.ignoredPaths", (before.git.ignoredPaths ?? null), (after.git.ignoredPaths ?? null)));
+    }
     const afterConfiguredByPath = new Map(after.configuredFiles.map((entry) => [entry.relativePath, entry]));
     for (const beforeEntry of before.configuredFiles) {
         const afterEntry = afterConfiguredByPath.get(beforeEntry.relativePath);

package/dist/src/experiments/defaultRegistry.js

@@ -2,6 +2,7 @@ import { ExperimentPluginRegistry } from "./registry.js";
 import { contextStrategyComparisonPlugin } from "./plugins/contextStrategyComparison/index.js";
 import { contextWindowScalingPlugin } from "./plugins/contextWindowScaling/index.js";
 import { incrementalChangeStalenessPlugin } from "./plugins/incrementalChangeStaleness/index.js";
+import { retrievalPrecisionRecallPlugin } from "./plugins/retrievalPrecisionRecall/index.js";
 import { warmIndexReusePlugin } from "./plugins/warmIndexReuse/index.js";
 export function createDefaultExperimentPluginRegistry() {
     const registry = new ExperimentPluginRegistry();
@@ -9,5 +10,6 @@ export function createDefaultExperimentPluginRegistry() {
     registry.register(warmIndexReusePlugin);
     registry.register(incrementalChangeStalenessPlugin);
     registry.register(contextWindowScalingPlugin);
+    registry.register(retrievalPrecisionRecallPlugin);
     return registry;
 }

package/dist/src/experiments/plugins/contextWindowScaling/localSubjectErrors.js

@@ -0,0 +1,35 @@
+/**
+ * Thrown when a local-subject execution did not complete cleanly. The primary code is the first issue in the
+ * ordered list (execution, mutation, snapshot, cleanup); every issue is retained so a secondary failure never
+ * masks the primary one. `caseEvidence` and `immutability` are runtime-only partial evidence for forensics and
+ * must not be persisted without the later privacy projection.
+ */
+export class LocalSubjectExecutionError extends Error {
+    code;
+    issues;
+    caseEvidence;
+    immutability;
+    constructor(issues, partial = {}) {
+        if (issues.length === 0)
+            throw new Error("LocalSubjectExecutionError requires at least one issue.");
+        super(`Local subject execution failed (${issues[0].code}): ${issues.map((issue) => issue.message).join("; ")}`);
+        this.name = "LocalSubjectExecutionError";
+        this.code = issues[0].code;
+        this.issues = [...issues];
+        this.caseEvidence = partial.caseEvidence ?? null;
+        this.immutability = partial.immutability ?? null;
+    }
+}
+/** Replaces absolute private roots in a message so errors never carry the target or scratch location. */
+export function redactPrivatePaths(message, privatePaths) {
+    let redacted = message;
+    for (const privatePath of privatePaths) {
+        if (!privatePath)
+            continue;
+        const variants = new Set([privatePath, privatePath.replace(/\\/g, "/"), privatePath.replace(/\//g, "\\")]);
+        for (const variant of variants) {
+            redacted = redacted.split(variant).join("<private-path>");
+        }
+    }
+    return redacted;
+}

package/dist/src/experiments/plugins/contextWindowScaling/localSubjectExclusions.js

@@ -0,0 +1,75 @@
+import { compareCodeUnits } from "../../../evaluation/localRepositorySubject/index.js";
+import { LocalSubjectExecutionError } from "./localSubjectErrors.js";
+/** Fail-closed ceilings so the exclusion arguments stay well inside Windows command-line limits. */
+export const GUIDED_EXCLUSION_MAX_ENTRIES = 500;
+export const GUIDED_EXCLUSION_MAX_CHARACTERS = 24_000;
+/**
+ * Pure policy: turns Batch 1 runtime exclusion evidence into the exact `--exclude` paths for the guided index.
+ *
+ * Each excluded file is covered by the shallowest ancestor directory that contains no eligible file (so a fully
+ * ignored directory becomes one entry), otherwise by the file path itself. Bare names are never produced because
+ * my-dev-kit treats a bare name as "every directory with this name", which would drop eligible material. If the
+ * result is too large the call throws instead of truncating: an incomplete exclusion list would be unsafe.
+ */
+export function deriveGuidedIndexExclusions(input) {
+    const eligibleDirectories = new Set();
+    const eligibleSegments = new Set();
+    for (const eligible of input.eligibleFiles) {
+        const segments = eligible.split("/");
+        segments.forEach((segment) => eligibleSegments.add(segment));
+        for (let depth = 1; depth < segments.length; depth += 1) {
+            eligibleDirectories.add(segments.slice(0, depth).join("/"));
+        }
+    }
+    const candidates = new Set();
+    for (const excluded of input.excludedFiles) {
+        const segments = excluded.split("/");
+        let covering = excluded;
+        for (let depth = 1; depth < segments.length; depth += 1) {
+            const directory = segments.slice(0, depth).join("/");
+            if (!eligibleDirectories.has(directory)) {
+                covering = directory;
+                break;
+            }
+        }
+        // A single-segment entry is a name match in my-dev-kit (any depth), and "./name" is silently ignored, so it is
+        // only safe when no eligible path uses that name. Otherwise descend to a multi-segment path, which is exact.
+        if (!covering.includes("/") && eligibleSegments.has(covering)) {
+            if (covering !== excluded && segments.length > 2) {
+                covering = segments.slice(0, 2).join("/");
+            }
+            else if (covering !== excluded) {
+                covering = excluded;
+            }
+            else {
+                throw new LocalSubjectExecutionError([
+                    {
+                        code: "GUIDED_EXCLUSION_UNREPRESENTABLE",
+                        message: `an excluded top-level entry shares its name with eligible files and cannot be excluded exactly (${excluded}).`,
+                    },
+                ]);
+            }
+        }
+        candidates.add(covering);
+    }
+    const exclusions = [...candidates]
+        .filter((candidate) => {
+        const segments = candidate.split("/");
+        for (let depth = 1; depth < segments.length; depth += 1) {
+            if (candidates.has(segments.slice(0, depth).join("/")))
+                return false;
+        }
+        return true;
+    })
+        .sort(compareCodeUnits);
+    const characters = exclusions.reduce((total, entry) => total + entry.length + 1, 0);
+    if (exclusions.length > GUIDED_EXCLUSION_MAX_ENTRIES || characters > GUIDED_EXCLUSION_MAX_CHARACTERS) {
+        throw new LocalSubjectExecutionError([
+            {
+                code: "GUIDED_EXCLUSION_LIMIT",
+                message: `guided index exclusions exceed the safe limit (${exclusions.length} entries, ${characters} characters).`,
+            },
+        ]);
+    }
+    return exclusions;
+}