@dailephd/my-dev-kit-lab 0.7.1 → 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/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/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;
+}

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

@@ -0,0 +1,136 @@
+import path from "node:path";
+import { relativeWithinRoot } from "../../../core/pathSafety.js";
+import { runMyDevKitRetrieval } from "../../../evaluation/runMyDevKitRetrieval.js";
+import { runRawFullFileBaseline } from "../../../evaluation/runRawFullFileBaseline.js";
+import { captureTargetSnapshot, compareTargetSnapshots } from "../../../evaluation/targetImmutability/index.js";
+import { executeContextWindowScalingCases, } from "./execution.js";
+import { LocalSubjectExecutionError, redactPrivatePaths, } from "./localSubjectErrors.js";
+import { deriveGuidedIndexExclusions } from "./localSubjectExclusions.js";
+import { assertWorkRootOutsideTarget, createPrivateScratch, defaultPrivateScratchIo, removePrivateScratch, } from "./localSubjectScratch.js";
+import { resolveScalingProjectProfiles } from "./projectProfile.js";
+function toRepositoryRelative(repositoryRoot, file) {
+    const slashed = file.replace(/\\/g, "/");
+    if (path.isAbsolute(file)) {
+        try {
+            return relativeWithinRoot(repositoryRoot, file);
+        }
+        catch {
+            return slashed;
+        }
+    }
+    return slashed.replace(/^\.\//, "");
+}
+/** Safe local constructors: raw context from eligible files only; guided retrieval over the original root. */
+function createSafeLocalDependencies(subject, guidedExclusions) {
+    const eligible = new Set(subject.eligibleFiles);
+    return {
+        constructRawContext: (evaluationCase) => runRawFullFileBaseline(evaluationCase, { eligibleFiles: subject.eligibleFiles }),
+        constructGuidedContext: async ({ evaluationCase, kitCommand, outputDir }) => {
+            const result = await runMyDevKitRetrieval({
+                evaluationCase,
+                kitCommand,
+                outputDir,
+                requireKit: false,
+                excludePaths: guidedExclusions,
+            });
+            const returned = [...result.filesRead, ...(result.selectedFile ? [result.selectedFile] : [])];
+            const outside = returned.filter((file) => !eligible.has(toRepositoryRelative(subject.repositoryRoot, file)));
+            if (outside.length > 0) {
+                throw new Error(`Guided retrieval returned ${outside.length} file(s) outside the eligible subject universe: ${outside
+                    .map((file) => toRepositoryRelative(subject.repositoryRoot, file))
+                    .join(", ")}`);
+            }
+            return result;
+        },
+    };
+}
+/**
+ * Internal programmatic seam: runs a loaded Batch 1 local subject through the existing context-window core with
+ * safe raw and guided constructors, a private scratch outside the target, and pre/post target-immutability
+ * enforcement. Order: validate work root, derive exclusions, capture before, create scratch, execute, capture after,
+ * compare, remove scratch, then decide. Success is returned only when execution, immutability and cleanup all pass.
+ * A mutated target is never reverted.
+ */
+export async function executeLocalRepositorySubjectContextWindowScaling(args) {
+    const { subject } = args;
+    await assertWorkRootOutsideTarget(args.workRoot, subject.repositoryRoot);
+    const guidedExclusions = deriveGuidedIndexExclusions({
+        eligibleFiles: subject.eligibleFiles,
+        excludedFiles: [...subject.runtimeSafetyExclusions.gitIgnoredFiles, ...subject.runtimeSafetyExclusions.oversizedFiles],
+    });
+    const snapshotConfig = { targetRootPath: subject.repositoryRoot, relativeFilePaths: subject.eligibleFiles };
+    const snapshotOptions = { externalLocalSafe: { maxHashedFileBytes: subject.manifest.safetyPolicy.maxFileBytes } };
+    const before = await captureTargetSnapshot(snapshotConfig, snapshotOptions);
+    if (!before.ok) {
+        throw new LocalSubjectExecutionError([
+            { code: "BEFORE_SNAPSHOT_FAILED", message: `target snapshot before execution failed (${before.code}).` },
+        ]);
+    }
+    const scratch = await createPrivateScratch(args.workRoot, subject.repositoryRoot);
+    const privatePaths = [subject.repositoryRoot, scratch.path, path.resolve(args.workRoot)];
+    const redact = (message) => redactPrivatePaths(message, privatePaths);
+    const issues = [];
+    let caseEvidence = null;
+    try {
+        const projectProfiles = resolveScalingProjectProfiles(subject.evaluationCases, [], { eligibleFiles: subject.eligibleFiles });
+        caseEvidence = await executeContextWindowScalingCases({
+            cases: subject.evaluationCases,
+            contextBudgets: args.contextBudgets,
+            kitCommand: args.kitCommand,
+            outputRoot: scratch.path,
+            projectProfiles,
+            cwd: scratch.path,
+            env: args.env,
+            dependencies: { ...createSafeLocalDependencies(subject, guidedExclusions), ...args.dependencies },
+        });
+    }
+    catch (error) {
+        issues.push({
+            code: "EXECUTION_FAILED",
+            message: redact(`execution threw: ${error instanceof Error ? error.message : String(error)}`),
+        });
+    }
+    if (caseEvidence) {
+        for (const caseResult of caseEvidence) {
+            for (const treatment of caseResult.treatments) {
+                if (treatment.status === "failed" || treatment.errors.length > 0) {
+                    issues.push({
+                        code: "EXECUTION_FAILED",
+                        message: redact(`case ${caseResult.caseId} treatment ${treatment.variantId} failed: ${treatment.errors
+                            .map((entry) => `${entry.code}: ${entry.message}`)
+                            .join("; ")}`),
+                    });
+                }
+            }
+        }
+    }
+    let comparison = null;
+    const after = await captureTargetSnapshot(snapshotConfig, snapshotOptions);
+    if (!after.ok) {
+        issues.push({ code: "AFTER_SNAPSHOT_FAILED", message: `target snapshot after execution failed (${after.code}).` });
+    }
+    else {
+        comparison = compareTargetSnapshots(before.snapshot, after.snapshot);
+        if (comparison.status === "mutated") {
+            issues.push({
+                code: "TARGET_MUTATED",
+                message: `the target changed during execution (${comparison.mutations.map((mutation) => mutation.id).join(", ")}); it was not restored.`,
+            });
+        }
+    }
+    const cleanupFailure = await removePrivateScratch(scratch, args.scratchIo ?? defaultPrivateScratchIo);
+    if (cleanupFailure) {
+        issues.push({ code: "SCRATCH_CLEANUP_FAILED", message: redact(cleanupFailure) });
+    }
+    if (issues.length > 0 || !caseEvidence || !comparison) {
+        throw new LocalSubjectExecutionError(issues, { caseEvidence, immutability: comparison });
+    }
+    return {
+        caseEvidence,
+        immutability: {
+            status: "unchanged",
+            preExistingGitStatusEntryCount: comparison.preExistingGitStatusEntryCount,
+            newMutationCount: 0,
+        },
+    };
+}