clinkx 0.2.3 → 0.3.0

package/dist/context-builder/discovery.js

@@ -0,0 +1,1829 @@
+import { constants as fsConstants } from "node:fs";
+import { lstat as fsLstat, open as fsOpen, readdir as fsReaddir, realpath as fsRealpath, stat as fsStat, } from "node:fs/promises";
+import path from "node:path";
+import { isSamePathOrDescendant } from "../allowed-roots.js";
+import { CancellationError } from "../errors.js";
+import { CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS, } from "./config.js";
+import { CONTEXT_BUILDER_REQUESTED_EVIDENCE_OMISSION_REASON, requestedEvidenceOmission, } from "./diagnostics.js";
+import { compileContextBuilderGlobs, CONTEXT_BUILDER_DEFAULT_EXCLUDE_GLOBS, } from "./globs.js";
+import { normalizeContextBuilderRootRelativePath, rootRelativePathForAbsolutePath, } from "./paths.js";
+import { directoryDistance, genericPathKind, isTestPath, normalizedPathStem, } from "./path-signals.js";
+import { isBlockingSecretFinding, redactHighConfidenceAssignmentSecrets, scanHighConfidenceSecretContent, scanSecretPath, } from "./secrets.js";
+import { CONTEXT_BUILDER_PUBLIC_BUDGET_HARD_LIMITS, } from "./schema.js";
+const SEARCH_WINDOW_LINES_BEFORE = 19;
+const SEARCH_WINDOW_LINES_AFTER = 20;
+const SEARCH_BRIDGE_GAP_LINES = 20;
+const SEARCH_MAX_MERGED_SPAN_LINES = 160;
+const DEFAULT_MAX_FULL_FOCUS_SLICE_BYTES = 48_000;
+const DEFAULT_MAX_FULL_IMPLEMENTATION_FOCUS_SLICE_BYTES = 96_000;
+const IMPORT_EXPANSION_PASSES = 3;
+const PROJECT_SUPPORT_FILENAMES = Object.freeze([
+    "package.json",
+    "vitest.config.ts",
+    "vite.config.ts",
+]);
+export async function discoverContextBuilderCandidates(options) {
+    const internalCaps = options.internal_caps ?? CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS;
+    const matcher = compileContextBuilderGlobs({
+        include: [...(options.include_globs ?? [])],
+        exclude: [
+            ...CONTEXT_BUILDER_DEFAULT_EXCLUDE_GLOBS,
+            ...(options.exclude_globs ?? []),
+        ],
+    });
+    const state = {
+        tree: [],
+        contentCandidates: [],
+        omissions: [],
+        requestedEvidenceOmissionKeys: new Set(),
+        processedFileKeys: new Set(),
+        metrics: {
+            files_seen: 0,
+            files_considered: 0,
+            scan_cap_hit: false,
+            search_cap_hit: false,
+            discovery_byte_cap_hit: false,
+            discovery_candidate_cap_hit: false,
+            candidate_cap_hit: false,
+            bytes_read: 0,
+        },
+        stopped: false,
+    };
+    for (const root of options.roots) {
+        if (state.stopped) {
+            break;
+        }
+        assertNotAborted(options.signal);
+        await processExactFocusFiles({
+            root,
+            focusPaths: options.focus_paths ?? [],
+            matcher,
+            budget: options.budget,
+            internalCaps,
+            ...(options.signal == null ? {} : { signal: options.signal }),
+            fs: {
+                readdir: options.fs?.readdir ?? fsReaddir,
+                lstat: options.fs?.lstat ?? fsLstat,
+                open: options.fs?.open ?? fsOpen,
+                realpath: options.fs?.realpath ?? fsRealpath,
+                stat: options.fs?.stat ?? fsStat,
+            },
+            state,
+        });
+        await traverseDirectory({
+            root,
+            absoluteDir: root.path,
+            relativeDir: "",
+            matcher,
+            focusPaths: options.focus_paths ?? [],
+            budget: options.budget,
+            internalCaps,
+            excludedRealRoots: options.excluded_real_roots ?? [],
+            ...(options.signal == null ? {} : { signal: options.signal }),
+            fs: {
+                readdir: options.fs?.readdir ?? fsReaddir,
+                lstat: options.fs?.lstat ?? fsLstat,
+                open: options.fs?.open ?? fsOpen,
+                realpath: options.fs?.realpath ?? fsRealpath,
+                stat: options.fs?.stat ?? fsStat,
+            },
+            state,
+        });
+        await processImportAndSupportFiles({
+            root,
+            matcher,
+            focusPaths: options.focus_paths ?? [],
+            budget: options.budget,
+            internalCaps,
+            ...(options.signal == null ? {} : { signal: options.signal }),
+            fs: {
+                readdir: options.fs?.readdir ?? fsReaddir,
+                lstat: options.fs?.lstat ?? fsLstat,
+                open: options.fs?.open ?? fsOpen,
+                realpath: options.fs?.realpath ?? fsRealpath,
+                stat: options.fs?.stat ?? fsStat,
+            },
+            state,
+        });
+    }
+    state.tree.sort(compareTreeFiles);
+    state.contentCandidates.sort(compareContentCandidates);
+    const search = buildCandidateSearchRecords({
+        candidates: state.contentCandidates,
+        ...(options.task == null ? {} : { task: options.task }),
+        focusPaths: [...(options.focus_paths ?? [])],
+        searchTerms: expandSearchTerms([...(options.search_terms ?? [])]),
+        maxSearchResults: options.budget.max_search_results,
+        maxPreviewBytes: internalCaps.max_search_preview_bytes,
+        maxCandidateBytes: internalCaps.max_candidate_bytes,
+        ...(options.signal == null ? {} : { signal: options.signal }),
+    });
+    if (search.capHit) {
+        state.metrics.search_cap_hit = true;
+    }
+    const slices = buildCandidateSliceRecords({
+        candidates: state.contentCandidates,
+        focusPaths: [...(options.focus_paths ?? [])],
+        searchRecords: search.records,
+        maxCandidateSlices: internalCaps.max_candidate_slices,
+        maxCandidateBytes: Math.max(0, internalCaps.max_candidate_bytes - search.candidateBytes),
+        maxSearchSliceBytesPerCandidate: options.budget.max_bytes_per_file,
+        maxFullFocusSliceBytes: Math.min(options.budget.max_bytes_per_file, DEFAULT_MAX_FULL_IMPLEMENTATION_FOCUS_SLICE_BYTES),
+        ...(options.signal == null ? {} : { signal: options.signal }),
+    });
+    state.omissions.push(...slices.omissions);
+    if (slices.capHit) {
+        state.metrics.candidate_cap_hit = true;
+    }
+    auditScanCapFocusedPaths({
+        focusPaths: [...(options.focus_paths ?? [])],
+        state,
+    });
+    return {
+        tree: state.tree,
+        content_candidates: state.contentCandidates,
+        search: search.records,
+        slices: slices.records,
+        omissions: state.omissions,
+        metrics: state.metrics,
+    };
+}
+function expandSearchTerms(searchTerms) {
+    const expanded = [];
+    const seen = new Set();
+    for (const term of searchTerms) {
+        addExpandedSearchTerm(expanded, seen, term);
+        for (const derived of deriveGenericSearchTerms(term)) {
+            addExpandedSearchTerm(expanded, seen, derived);
+        }
+    }
+    return expanded;
+}
+function addExpandedSearchTerm(expanded, seen, term) {
+    const normalized = term.trim();
+    if (normalized.length === 0) {
+        return;
+    }
+    const key = normalized.toLowerCase();
+    if (seen.has(key)) {
+        return;
+    }
+    expanded.push(normalized);
+    seen.add(key);
+}
+function deriveGenericSearchTerms(term) {
+    const tokens = tokenizeGenericSearchTerm(term);
+    const terms = new Set(tokens);
+    for (let index = 0; index < tokens.length - 1; index++) {
+        const current = tokens[index];
+        const next = tokens[index + 1];
+        if (current == null || next == null) {
+            continue;
+        }
+        terms.add(`${current}_${next}`);
+        terms.add(`${current}${next}`);
+    }
+    return [...terms].filter((value) => value.length >= 3).sort();
+}
+function tokenizeGenericSearchTerm(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/\.[A-Za-z0-9]+$/g, " ")
+        .split(/[^A-Za-z0-9]+/)
+        .map((word) => normalizeGenericSearchWord(word))
+        .filter((word) => word.length >= 3 && !GENERIC_SEARCH_STOPWORDS.has(word));
+}
+function normalizeGenericSearchWord(word) {
+    const lower = word.toLowerCase();
+    if (lower.length > 4 && lower.endsWith("ies")) {
+        return `${lower.slice(0, -3)}y`;
+    }
+    if (lower.length > 3 && lower.endsWith("s")) {
+        return lower.slice(0, -1);
+    }
+    return lower;
+}
+const GENERIC_SEARCH_STOPWORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "that",
+    "this",
+    "from",
+    "into",
+    "without",
+    "change",
+    "fix",
+    "add",
+    "new",
+    "safe",
+    "safely",
+    "test",
+    "tests",
+]);
+async function processImportAndSupportFiles(input) {
+    for (let pass = 0; pass < IMPORT_EXPANSION_PASSES; pass++) {
+        const before = input.state.contentCandidates.length;
+        const dependencies = dependencyPathChoicesForCandidates(input.root, input.state.contentCandidates.filter((candidate) => candidate.root_index === input.root.root_index));
+        for (const choices of dependencies) {
+            assertNotAborted(input.signal);
+            const relativePath = await firstExistingPath(input.root, choices, input.fs);
+            if (relativePath == null) {
+                continue;
+            }
+            await processFile({
+                root: input.root,
+                absolutePath: path.join(input.root.path, relativePath),
+                relativePath,
+                matcher: input.matcher,
+                focusPaths: input.focusPaths,
+                budget: input.budget,
+                internalCaps: input.internalCaps,
+                ignoreIncludeGlob: true,
+                ignoreScanCap: true,
+                selectionHint: "local_dependency",
+                ...(input.signal == null ? {} : { signal: input.signal }),
+                fs: input.fs,
+                state: input.state,
+            });
+        }
+        if (input.state.contentCandidates.length === before) {
+            break;
+        }
+    }
+    const supportFiles = projectSupportFilesForCandidates(input.root, input.state.contentCandidates.filter((candidate) => candidate.root_index === input.root.root_index));
+    for (const relativePath of supportFiles) {
+        assertNotAborted(input.signal);
+        if ((await firstExistingPath(input.root, [relativePath], input.fs)) == null) {
+            continue;
+        }
+        await processFile({
+            root: input.root,
+            absolutePath: path.join(input.root.path, relativePath),
+            relativePath,
+            matcher: input.matcher,
+            focusPaths: input.focusPaths,
+            budget: input.budget,
+            internalCaps: input.internalCaps,
+            ignoreIncludeGlob: true,
+            ignoreScanCap: true,
+            selectionHint: "project_support",
+            ...(input.signal == null ? {} : { signal: input.signal }),
+            fs: input.fs,
+            state: input.state,
+        });
+    }
+}
+function dependencyPathChoicesForCandidates(root, candidates) {
+    const choices = [];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        for (const specifier of importSpecifiers(candidate.content)) {
+            const resolved = resolveImportSpecifierChoices(root, candidate.path, specifier);
+            const useful = resolved.filter((pathChoice) => isUsefulLocalDependency(candidate.path, pathChoice));
+            if (useful.length === 0) {
+                continue;
+            }
+            const key = useful.join("\u0000");
+            if (!seen.has(key)) {
+                choices.push(useful);
+                seen.add(key);
+            }
+        }
+    }
+    return choices.sort((left, right) => left[0].localeCompare(right[0]));
+}
+async function firstExistingPath(root, choices, fs) {
+    for (const relativePath of choices) {
+        try {
+            const stats = await fs.stat(path.join(root.path, relativePath));
+            if (stats.isFile()) {
+                return relativePath;
+            }
+        }
+        catch (error) {
+            if (isExpectedDescendantFilesystemError(error)) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    return null;
+}
+function projectSupportFilesForCandidates(root, candidates) {
+    const prefixes = new Set();
+    for (const candidate of candidates) {
+        const prefix = projectPackagePrefix(candidate.path);
+        if (prefix != null) {
+            prefixes.add(prefix);
+        }
+    }
+    const paths = [];
+    for (const prefix of [...prefixes].sort()) {
+        for (const filename of PROJECT_SUPPORT_FILENAMES) {
+            const relativePath = prefix.length === 0 ? filename : `${prefix}/${filename}`;
+            if (isSamePathOrDescendant(path.join(root.path, relativePath), root.path)) {
+                paths.push(relativePath);
+            }
+        }
+    }
+    return paths;
+}
+function importSpecifiers(content) {
+    const specifiers = [];
+    const patterns = [
+        /\bimport\s+(?:type\s+)?(?:[^'";]+?\s+from\s+)?['"]([^'"]+)['"]/g,
+        /\bexport\s+(?:type\s+)?[^'";]+?\s+from\s+['"]([^'"]+)['"]/g,
+        /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+        /^\s*from\s+([A-Za-z_][\w.]*|\.+[\w.]*)\s+import\b/gm,
+        /^\s*import\s+(app(?:\.[A-Za-z_][\w]*)+)\b/gm,
+    ];
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(content)) != null) {
+            const specifier = match[1];
+            if (specifier != null) {
+                specifiers.push(specifier);
+            }
+        }
+    }
+    return specifiers;
+}
+function resolveImportSpecifierChoices(root, importerPath, specifier) {
+    const base = resolveImportBase(importerPath, specifier);
+    if (base == null) {
+        return [];
+    }
+    const choices = [];
+    for (const candidate of importResolutionCandidates(base)) {
+        const absolute = path.join(root.path, candidate);
+        if (!isSamePathOrDescendant(absolute, root.path)) {
+            continue;
+        }
+        try {
+            const normalized = normalizeContextBuilderRootRelativePath(candidate);
+            if (normalized === candidate) {
+                choices.push(candidate);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return choices;
+}
+function resolveImportBase(importerPath, specifier) {
+    if (specifier.startsWith("@/")) {
+        const srcPrefix = sourceRootPrefix(importerPath);
+        return srcPrefix == null ? null : `${srcPrefix}/${specifier.slice(2)}`;
+    }
+    if (specifier.startsWith("app.") && importerPath.endsWith(".py")) {
+        const appPrefix = pythonAppRootPrefix(importerPath);
+        return appPrefix == null
+            ? null
+            : `${appPrefix}/${specifier.slice("app.".length).replaceAll(".", "/")}`;
+    }
+    if (specifier.startsWith(".") && importerPath.endsWith(".py")) {
+        return resolvePythonRelativeImportBase(importerPath, specifier);
+    }
+    if (specifier.startsWith("./") || specifier.startsWith("../")) {
+        return normalizeSlash(path.normalize(path.join(path.dirname(importerPath), specifier)));
+    }
+    return null;
+}
+function importResolutionCandidates(base) {
+    if (/\.(?:[cm]?[jt]sx?|json)$/.test(base)) {
+        return [base];
+    }
+    return [
+        `${base}.ts`,
+        `${base}.tsx`,
+        `${base}.js`,
+        `${base}.jsx`,
+        `${base}.py`,
+        `${base}.json`,
+        `${base}/index.ts`,
+        `${base}/index.tsx`,
+        `${base}/index.js`,
+        `${base}/index.jsx`,
+        `${base}/__init__.py`,
+    ];
+}
+// Adjacency radius (in directory hops) within which an imported file is treated
+// as a useful local dependency regardless of stem/kind heuristics.
+const LOCAL_DEPENDENCY_MAX_DIRECTORY_DISTANCE = 6;
+function isUsefulLocalDependency(importerPath, dependencyPath) {
+    if (importerPath === dependencyPath) {
+        return false;
+    }
+    if (directoryDistance(importerPath, dependencyPath) <=
+        LOCAL_DEPENDENCY_MAX_DIRECTORY_DISTANCE) {
+        return true;
+    }
+    if (normalizedPathStem(importerPath) !== normalizedPathStem(dependencyPath)) {
+        return false;
+    }
+    return genericPathKind(importerPath) !== genericPathKind(dependencyPath);
+}
+function sourceRootPrefix(importerPath) {
+    const srcIndex = importerPath.indexOf("/src/");
+    if (srcIndex < 0) {
+        return importerPath.startsWith("src/") ? "src" : null;
+    }
+    return importerPath.slice(0, srcIndex + "/src".length);
+}
+function projectPackagePrefix(candidatePath) {
+    const srcIndex = candidatePath.indexOf("/src/");
+    if (srcIndex < 0) {
+        return null;
+    }
+    return candidatePath.slice(0, srcIndex);
+}
+function pythonAppRootPrefix(importerPath) {
+    const appIndex = importerPath.indexOf("/app/");
+    if (appIndex >= 0) {
+        return importerPath.slice(0, appIndex + "/app".length);
+    }
+    return importerPath.startsWith("app/") ? "app" : null;
+}
+function resolvePythonRelativeImportBase(importerPath, specifier) {
+    const match = /^(\.+)(.*)$/.exec(specifier);
+    if (match == null) {
+        return null;
+    }
+    const dots = match[1] ?? "";
+    const moduleTail = match[2] ?? "";
+    let baseDir = path.dirname(importerPath);
+    for (let index = 1; index < dots.length; index++) {
+        baseDir = path.dirname(baseDir);
+    }
+    const suffix = moduleTail.length === 0 ? "" : moduleTail.replaceAll(".", "/");
+    return normalizeSlash(path.normalize(suffix.length === 0 ? baseDir : path.join(baseDir, suffix)));
+}
+function normalizeSlash(value) {
+    return value.replaceAll(path.sep, "/");
+}
+async function processExactFocusFiles(input) {
+    const focusFiles = [...input.focusPaths]
+        .filter((focus) => focus.root_index === input.root.root_index)
+        .filter((focus) => focus.kind === "file")
+        .sort(compareFocusPathsForDiscovery);
+    for (const focus of focusFiles) {
+        assertNotAborted(input.signal);
+        await processFile({
+            root: input.root,
+            absolutePath: focus.absolute_path,
+            relativePath: focus.root_relative_path,
+            matcher: input.matcher,
+            focusPaths: input.focusPaths,
+            budget: input.budget,
+            internalCaps: input.internalCaps,
+            ignoreScanCap: true,
+            ...(input.signal == null ? {} : { signal: input.signal }),
+            fs: input.fs,
+            state: input.state,
+        });
+    }
+}
+export function buildCandidateSearchRecords(input) {
+    const maxPreviewBytes = input.maxPreviewBytes ??
+        CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS.max_search_preview_bytes;
+    const maxCandidateBytes = input.maxCandidateBytes ??
+        CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS.max_candidate_bytes;
+    const records = [];
+    let previewBytes = 0;
+    let candidateBytes = 0;
+    let capHit = false;
+    if (input.searchTerms.length === 0) {
+        return { records, capHit, candidateBytes };
+    }
+    const searchTerms = input.searchTerms
+        .map((term, index) => ({ term, index }))
+        .filter(({ term }) => term.trim().length > 0);
+    if (searchTerms.length === 0) {
+        return { records, capHit, candidateBytes };
+    }
+    const focusRank = new Map();
+    for (const focus of input.focusPaths ?? []) {
+        if (focus.kind !== "file") {
+            continue;
+        }
+        const key = candidateKey({
+            root_index: focus.root_index,
+            path: focus.root_relative_path,
+        });
+        if (!focusRank.has(key)) {
+            focusRank.set(key, focusRank.size);
+        }
+    }
+    const candidates = [...input.candidates].sort((left, right) => {
+        const leftRank = focusRank.get(candidateKey(left)) ?? Number.MAX_SAFE_INTEGER;
+        const rightRank = focusRank.get(candidateKey(right)) ?? Number.MAX_SAFE_INTEGER;
+        return (leftRank - rightRank ||
+            discoveryTaskClosureRank(left.path, input.task ?? "") -
+                discoveryTaskClosureRank(right.path, input.task ?? "") ||
+            compareContentCandidates(left, right));
+    });
+    const streams = [];
+    for (const candidate of candidates) {
+        assertNotAborted(input.signal);
+        const lines = splitTextLines(candidate.content);
+        for (const searchTerm of searchTerms) {
+            streams.push({
+                candidate,
+                searchTerm,
+                lines,
+                lineIndex: 0,
+                fromIndex: 0,
+                done: false,
+            });
+        }
+    }
+    let activeStreams = streams.length;
+    while (activeStreams > 0) {
+        let foundInRound = false;
+        for (const stream of streams) {
+            assertNotAborted(input.signal);
+            if (stream.done) {
+                continue;
+            }
+            const hit = nextSearchHit(stream);
+            if (hit == null) {
+                stream.done = true;
+                activeStreams--;
+                continue;
+            }
+            foundInRound = true;
+            if (records.length >= input.maxSearchResults) {
+                capHit = true;
+                return { records, capHit, candidateBytes };
+            }
+            const preview = boundedPreview(hit.line, hit.columnIndex, stream.searchTerm.term.length);
+            const previewSize = Buffer.byteLength(preview, "utf8");
+            const bounded = previewBytes + previewSize <= maxPreviewBytes ? preview : "";
+            const record = {
+                root_index: stream.candidate.root_index,
+                path: stream.candidate.path,
+                line: hit.lineIndex + 1,
+                column: hit.columnIndex + 1,
+                search_term: stream.searchTerm.term,
+                search_term_index: stream.searchTerm.index,
+                preview: bounded,
+            };
+            const recordBytes = Buffer.byteLength(`${JSON.stringify(record)}\n`, "utf8");
+            if (candidateBytes + recordBytes > maxCandidateBytes) {
+                capHit = true;
+                return { records, capHit, candidateBytes };
+            }
+            previewBytes += Buffer.byteLength(bounded, "utf8");
+            candidateBytes += recordBytes;
+            records.push(record);
+        }
+        if (!foundInRound) {
+            break;
+        }
+    }
+    return { records, capHit, candidateBytes };
+}
+export function buildCandidateSliceRecords(input) {
+    const maxCandidateSlices = input.maxCandidateSlices ??
+        CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS.max_candidate_slices;
+    const maxCandidateBytes = input.maxCandidateBytes ??
+        CONTEXT_BUILDER_INTERNAL_CAP_DEFAULTS.max_candidate_bytes;
+    const maxFullFocusSliceBytes = input.maxFullFocusSliceBytes ??
+        DEFAULT_MAX_FULL_FOCUS_SLICE_BYTES;
+    const candidateByIdentity = new Map(input.candidates.map((candidate) => [candidateKey(candidate), candidate]));
+    const records = [];
+    const omissions = [];
+    let bytes = 0;
+    let capHit = false;
+    const searchSliceBytesByCandidate = new Map();
+    const focusedLargeSearchCandidates = new Map();
+    const expectedFocusedSearchRanges = new Map();
+    const survivedFocusedSearchRanges = new Map();
+    const focusSliceSurvivors = new Set();
+    const omittedLargeFocusedCandidates = new Set();
+    const omittedRequestedCandidates = new Set();
+    const pushRequestedCandidateOmission = (candidate, kind, message) => {
+        const key = candidateKey(candidate);
+        if (omittedRequestedCandidates.has(key)) {
+            return;
+        }
+        omissions.push(requestedEvidenceOmission({
+            root_index: candidate.root_index,
+            kind,
+            message,
+            paths: [candidate.path],
+        }));
+        omittedRequestedCandidates.add(key);
+    };
+    const pushMissingFocusedSearchOmissions = (keys) => {
+        for (const key of keys) {
+            if (focusedSearchRangesCovered(expectedFocusedSearchRanges.get(key) ?? [], survivedFocusedSearchRanges.get(key) ?? []) ||
+                omittedRequestedCandidates.has(key)) {
+                continue;
+            }
+            const candidate = focusedLargeSearchCandidates.get(key);
+            if (candidate == null) {
+                continue;
+            }
+            pushRequestedCandidateOmission(candidate, "candidate_cap", "focused file had search evidence, but no bounded search slice survived max_bytes_per_file or candidate caps");
+        }
+    };
+    const pushMissingFocusedRangeOmissions = (keys) => {
+        for (const key of keys) {
+            if (focusSliceSurvivors.has(key) || omittedRequestedCandidates.has(key)) {
+                continue;
+            }
+            const candidate = candidateByIdentity.get(key);
+            if (candidate == null) {
+                continue;
+            }
+            pushRequestedCandidateOmission(candidate, "candidate_cap", "focused file slice could not be represented within candidate slice or byte caps");
+        }
+    };
+    const append = (record) => {
+        const key = candidateKey(record);
+        if (record.source === "search" &&
+            input.maxSearchSliceBytesPerCandidate != null) {
+            const contentBytes = Buffer.byteLength(record.content, "utf8");
+            const candidateBytes = searchSliceBytesByCandidate.get(key) ?? 0;
+            if (candidateBytes + contentBytes > input.maxSearchSliceBytesPerCandidate) {
+                capHit = true;
+                return true;
+            }
+            searchSliceBytesByCandidate.set(key, candidateBytes + contentBytes);
+        }
+        const recordBytes = Buffer.byteLength(`${JSON.stringify(record)}\n`, "utf8");
+        if (records.length >= maxCandidateSlices || bytes + recordBytes > maxCandidateBytes) {
+            capHit = true;
+            return false;
+        }
+        records.push(record);
+        bytes += recordBytes;
+        if (record.source === "search") {
+            const survived = survivedFocusedSearchRanges.get(key);
+            if (survived != null) {
+                survived.push({
+                    start_line: record.start_line,
+                    end_line: record.end_line,
+                    ...(record.search_term_index == null
+                        ? {}
+                        : { search_term_index: record.search_term_index }),
+                });
+            }
+        }
+        else {
+            focusSliceSurvivors.add(key);
+        }
+        return true;
+    };
+    const searchRanges = new Map();
+    for (const hit of [...input.searchRecords].sort(compareSearchRecords)) {
+        const candidate = candidateByIdentity.get(searchKey(hit));
+        if (candidate == null || candidate.line_count === 0) {
+            continue;
+        }
+        const ranges = searchRanges.get(candidateKey(candidate)) ?? [];
+        ranges.push({
+            start_line: Math.max(1, hit.line - SEARCH_WINDOW_LINES_BEFORE),
+            end_line: Math.min(candidate.line_count, hit.line + SEARCH_WINDOW_LINES_AFTER),
+            search_term_index: hit.search_term_index,
+        });
+        searchRanges.set(candidateKey(candidate), ranges);
+    }
+    const focusRanges = new Map();
+    for (const focus of [...input.focusPaths].sort(compareFocusPathsForDiscovery)) {
+        for (const candidate of input.candidates) {
+            if (candidate.root_index === focus.root_index &&
+                (candidate.path === focus.root_relative_path ||
+                    (focus.kind === "directory" &&
+                        isRootRelativeDescendant(candidate.path, focus.root_relative_path)))) {
+                const key = candidateKey(candidate);
+                if (candidate.byte_length > fullFocusSliceByteLimit(candidate.path, maxFullFocusSliceBytes)) {
+                    if (!searchRanges.has(key) && !omittedLargeFocusedCandidates.has(key)) {
+                        pushRequestedCandidateOmission(candidate, "too_large", "focused file exceeded bounded full-file focus size and had no per-file search evidence");
+                        omittedLargeFocusedCandidates.add(key);
+                    }
+                    else if (searchRanges.has(key)) {
+                        focusedLargeSearchCandidates.set(key, candidate);
+                        expectedFocusedSearchRanges.set(key, mergeLineRanges(searchRanges.get(key) ?? [], {
+                            bridgeGapLines: SEARCH_BRIDGE_GAP_LINES,
+                            maxMergedSpanLines: SEARCH_MAX_MERGED_SPAN_LINES,
+                        }));
+                        survivedFocusedSearchRanges.set(key, []);
+                    }
+                    continue;
+                }
+                const ranges = focusRanges.get(candidateKey(candidate)) ?? [];
+                ranges.push({ start_line: 1, end_line: Math.max(1, candidate.line_count) });
+                focusRanges.set(candidateKey(candidate), ranges);
+            }
+        }
+    }
+    const dependencyRanges = new Map();
+    for (const candidate of input.candidates) {
+        if (candidate.selection_hint == null || candidate.line_count === 0) {
+            continue;
+        }
+        if (candidate.byte_length >
+            (input.maxSearchSliceBytesPerCandidate ?? Number.MAX_SAFE_INTEGER)) {
+            continue;
+        }
+        dependencyRanges.set(candidateKey(candidate), [
+            { start_line: 1, end_line: Math.max(1, candidate.line_count) },
+        ]);
+    }
+    for (const [key, ranges] of [...searchRanges.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        assertNotAborted(input.signal);
+        const candidate = candidateByIdentity.get(key);
+        if (candidate == null || candidate.line_count === 0) {
+            continue;
+        }
+        for (const range of mergeLineRanges(ranges, {
+            bridgeGapLines: SEARCH_BRIDGE_GAP_LINES,
+            maxMergedSpanLines: SEARCH_MAX_MERGED_SPAN_LINES,
+        })) {
+            if (!append({
+                root_index: candidate.root_index,
+                path: candidate.path,
+                start_line: range.start_line,
+                end_line: range.end_line,
+                source: "search",
+                content: sliceContent(candidate.content, range.start_line, range.end_line),
+                ...(range.search_term_index == null
+                    ? {}
+                    : { search_term_index: range.search_term_index }),
+            })) {
+                pushMissingFocusedSearchOmissions(focusedLargeSearchCandidates.keys());
+                pushMissingFocusedRangeOmissions(focusRanges.keys());
+                return { records, capHit, omissions };
+            }
+        }
+    }
+    pushMissingFocusedSearchOmissions(focusedLargeSearchCandidates.keys());
+    for (const [key, ranges] of [...dependencyRanges.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        if (searchRanges.has(key) || focusRanges.has(key)) {
+            continue;
+        }
+        assertNotAborted(input.signal);
+        const candidate = candidateByIdentity.get(key);
+        if (candidate == null) {
+            continue;
+        }
+        for (const range of mergeLineRanges(ranges)) {
+            if (!append({
+                root_index: candidate.root_index,
+                path: candidate.path,
+                start_line: range.start_line,
+                end_line: range.end_line,
+                source: "search",
+                content: sliceContent(candidate.content, range.start_line, range.end_line),
+                search_term_index: Number.MAX_SAFE_INTEGER - 1,
+            })) {
+                pushMissingFocusedRangeOmissions(focusRanges.keys());
+                return { records, capHit, omissions };
+            }
+        }
+    }
+    for (const [key, ranges] of [...focusRanges.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        assertNotAborted(input.signal);
+        const candidate = candidateByIdentity.get(key);
+        if (candidate == null) {
+            continue;
+        }
+        for (const range of mergeLineRanges(ranges)) {
+            if (!append({
+                root_index: candidate.root_index,
+                path: candidate.path,
+                start_line: range.start_line,
+                end_line: range.end_line,
+                source: "focus",
+                content: sliceContent(candidate.content, range.start_line, range.end_line),
+            })) {
+                pushMissingFocusedRangeOmissions(focusRanges.keys());
+                return { records, capHit, omissions };
+            }
+        }
+    }
+    return { records, capHit, omissions };
+}
+export function splitTextLines(text) {
+    if (text.length === 0) {
+        return [];
+    }
+    const withoutFinalNewline = text.endsWith("\n")
+        ? text.slice(0, text.endsWith("\r\n") ? -2 : -1)
+        : text;
+    if (withoutFinalNewline.length === 0) {
+        return [""];
+    }
+    return withoutFinalNewline.split(/\r\n|\n/);
+}
+function nextSearchHit(stream) {
+    while (stream.lineIndex < stream.lines.length) {
+        const line = stream.lines[stream.lineIndex] ?? "";
+        const columnIndex = line.indexOf(stream.searchTerm.term, stream.fromIndex);
+        if (columnIndex >= 0) {
+            stream.fromIndex = columnIndex + stream.searchTerm.term.length;
+            return { lineIndex: stream.lineIndex, columnIndex, line };
+        }
+        stream.lineIndex++;
+        stream.fromIndex = 0;
+    }
+    return undefined;
+}
+export function mergeLineRanges(ranges, options = {}) {
+    const bridgeGapLines = options.bridgeGapLines ?? 0;
+    const maxMergedSpanLines = options.maxMergedSpanLines ?? Number.MAX_SAFE_INTEGER;
+    const sorted = [...ranges].sort((left, right) => left.start_line - right.start_line ||
+        left.end_line - right.end_line ||
+        (left.search_term_index ?? Number.MAX_SAFE_INTEGER) -
+            (right.search_term_index ?? Number.MAX_SAFE_INTEGER));
+    const merged = [];
+    for (const range of sorted) {
+        const last = merged.at(-1);
+        if (last != null &&
+            range.start_line <= last.end_line + bridgeGapLines + 1 &&
+            Math.max(last.end_line, range.end_line) - last.start_line + 1 <=
+                maxMergedSpanLines) {
+            last.end_line = Math.max(last.end_line, range.end_line);
+            last.search_term_index = Math.min(last.search_term_index ?? Number.MAX_SAFE_INTEGER, range.search_term_index ?? Number.MAX_SAFE_INTEGER);
+            if (last.search_term_index === Number.MAX_SAFE_INTEGER) {
+                delete last.search_term_index;
+            }
+            continue;
+        }
+        merged.push({ ...range });
+    }
+    return merged;
+}
+function fullFocusSliceByteLimit(path, maxFullFocusSliceBytes) {
+    if (isTestPath(path)) {
+        return Math.min(maxFullFocusSliceBytes, DEFAULT_MAX_FULL_FOCUS_SLICE_BYTES);
+    }
+    return maxFullFocusSliceBytes;
+}
+function focusedSearchRangesCovered(expected, survived) {
+    return expected.every((range) => rangeCoveredByRanges(range, survived));
+}
+function rangeCoveredByRanges(target, ranges) {
+    let nextLine = target.start_line;
+    for (const range of mergeLineRanges(ranges)) {
+        if (range.end_line < nextLine) {
+            continue;
+        }
+        if (range.start_line > nextLine) {
+            return false;
+        }
+        nextLine = Math.max(nextLine, range.end_line + 1);
+        if (nextLine > target.end_line) {
+            return true;
+        }
+    }
+    return false;
+}
+async function traverseDirectory(input) {
+    assertNotAborted(input.signal);
+    if (input.state.stopped) {
+        return;
+    }
+    if (input.relativeDir !== "" &&
+        (input.matcher.excludes(input.relativeDir) ||
+            input.matcher.excludes(`${input.relativeDir}/__dir__`))) {
+        input.state.omissions.push({
+            root_index: input.root.root_index,
+            reason: "exclude_glob",
+            message: "Directory omitted by exclude globs",
+            paths: [input.relativeDir],
+        });
+        pushRequestedFocusOmission({
+            root_index: input.root.root_index,
+            relativePath: input.relativeDir,
+            focusPaths: input.focusPaths,
+            state: input.state,
+            kind: "unavailable",
+            message: "focused path was omitted by exclude globs",
+        });
+        return;
+    }
+    const initialVerification = await verifyDirectoryStillExpected(input);
+    if (initialVerification.kind === "omitted") {
+        pushDirectoryOmission(input, initialVerification.omission);
+        pushRequestedFocusOmission({
+            root_index: input.root.root_index,
+            relativePath: input.relativeDir,
+            focusPaths: input.focusPaths,
+            state: input.state,
+            kind: "unavailable",
+            message: sanitizedFocusedOmissionMessage(initialVerification.omission.reason),
+        });
+        return;
+    }
+    if (isExcludedRealRoot(initialVerification.realPath, input.excludedRealRoots)) {
+        return;
+    }
+    let entries;
+    try {
+        entries = await input.fs.readdir(input.absoluteDir, {
+            withFileTypes: true,
+        });
+    }
+    catch (error) {
+        if (isExpectedDescendantFilesystemError(error)) {
+            pushDirectoryOmission(input, filesystemOmission("Directory omitted after filesystem error", error));
+            pushRequestedFocusOmission({
+                root_index: input.root.root_index,
+                relativePath: input.relativeDir,
+                focusPaths: input.focusPaths,
+                state: input.state,
+                kind: "unavailable",
+                message: sanitizedFocusedOmissionMessage("filesystem_error"),
+            });
+            return;
+        }
+        throw error;
+    }
+    assertNotAborted(input.signal);
+    const finalVerification = await verifyDirectoryStillExpected(input);
+    if (finalVerification.kind === "omitted") {
+        pushDirectoryOmission(input, finalVerification.omission);
+        pushRequestedFocusOmission({
+            root_index: input.root.root_index,
+            relativePath: input.relativeDir,
+            focusPaths: input.focusPaths,
+            state: input.state,
+            kind: "unavailable",
+            message: sanitizedFocusedOmissionMessage(finalVerification.omission.reason),
+        });
+        return;
+    }
+    if (isExcludedRealRoot(finalVerification.realPath, input.excludedRealRoots)) {
+        return;
+    }
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+        assertNotAborted(input.signal);
+        if (input.state.stopped) {
+            return;
+        }
+        const relativePath = normalizeContextBuilderRootRelativePath(input.relativeDir === "" ? entry.name : `${input.relativeDir}/${entry.name}`);
+        const absolutePath = path.join(input.absoluteDir, entry.name);
+        if (entry.isSymbolicLink()) {
+            input.state.omissions.push({
+                root_index: input.root.root_index,
+                reason: "symlink_omitted",
+                message: "Symlink omitted during context_builder discovery",
+                paths: [relativePath],
+            });
+            pushRequestedFocusOmission({
+                root_index: input.root.root_index,
+                relativePath,
+                focusPaths: input.focusPaths,
+                state: input.state,
+                kind: "unavailable",
+                message: sanitizedFocusedOmissionMessage("symlink_omitted"),
+            });
+            continue;
+        }
+        if (entry.isDirectory()) {
+            if (!input.matcher.canContainIncludedPath(relativePath)) {
+                pushRequestedFocusOmission({
+                    root_index: input.root.root_index,
+                    relativePath,
+                    focusPaths: input.focusPaths,
+                    state: input.state,
+                    kind: "unavailable",
+                    message: sanitizedFocusedOmissionMessage("caller_include_glob"),
+                });
+                continue;
+            }
+            await traverseDirectory({
+                ...input,
+                absoluteDir: absolutePath,
+                relativeDir: relativePath,
+            });
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        await processFile({
+            ...input,
+            absolutePath,
+            relativePath,
+        });
+    }
+}
+function pushDirectoryOmission(input, omission) {
+    input.state.omissions.push({
+        root_index: input.root.root_index,
+        reason: omission.reason,
+        message: omission.message,
+        ...(input.relativeDir === "" ? {} : { paths: [input.relativeDir] }),
+    });
+}
+async function processFile(input) {
+    const fileKey = candidateKey({
+        root_index: input.root.root_index,
+        path: input.relativePath,
+    });
+    const alreadyProcessed = input.state.processedFileKeys.has(fileKey);
+    if (alreadyProcessed &&
+        (input.ignoreIncludeGlob !== true ||
+            input.state.contentCandidates.some((candidate) => candidateKey(candidate) === fileKey))) {
+        return;
+    }
+    if (!alreadyProcessed) {
+        input.state.processedFileKeys.add(fileKey);
+    }
+    const omitted = (reason, message) => {
+        input.state.omissions.push({
+            root_index: input.root.root_index,
+            reason,
+            message,
+            paths: [input.relativePath],
+        });
+        pushRequestedFocusOmission({
+            root_index: input.root.root_index,
+            relativePath: input.relativePath,
+            focusPaths: input.focusPaths,
+            state: input.state,
+            kind: requestedOmissionKindForDiscoveryReason(reason),
+            message: sanitizedFocusedOmissionMessage(reason),
+        });
+    };
+    const requestedOmitted = (kind, message) => {
+        pushRequestedFocusOmission({
+            root_index: input.root.root_index,
+            relativePath: input.relativePath,
+            focusPaths: input.focusPaths,
+            state: input.state,
+            kind,
+            message,
+        });
+    };
+    const pushTree = (file) => {
+        input.state.tree.push({
+            root_index: input.root.root_index,
+            path: input.relativePath,
+            size_bytes: file.size_bytes ?? 0,
+            eligible: file.eligible,
+            content_eligible: file.content_eligible,
+            ...(file.omission_reason == null
+                ? {}
+                : { omission_reason: file.omission_reason }),
+        });
+    };
+    if (!isSamePathOrDescendant(input.absolutePath, input.root.path)) {
+        omitted("path_escape", "File path escaped root during discovery");
+        return;
+    }
+    const normalizedPath = rootRelativePathForAbsolutePath(input.root, input.absolutePath);
+    if (normalizedPath !== input.relativePath) {
+        omitted("path_normalized_mismatch", "File path changed after normalization");
+        return;
+    }
+    if (input.ignoreIncludeGlob !== true && !input.matcher.includes(input.relativePath)) {
+        requestedOmitted("unavailable", sanitizedFocusedOmissionMessage("caller_include_glob"));
+        pushTree({
+            eligible: false,
+            content_eligible: false,
+            omission_reason: "caller_include_glob",
+        });
+        return;
+    }
+    if (input.matcher.excludes(input.relativePath)) {
+        requestedOmitted("unavailable", sanitizedFocusedOmissionMessage("exclude_glob"));
+        pushTree({
+            eligible: false,
+            content_eligible: false,
+            omission_reason: "exclude_glob",
+        });
+        return;
+    }
+    if (input.ignoreScanCap !== true &&
+        input.state.metrics.files_seen >= input.budget.max_scan_files) {
+        input.state.metrics.scan_cap_hit = true;
+        pushRequestedFocusOmission({
+            root_index: input.root.root_index,
+            relativePath: input.relativePath,
+            focusPaths: input.focusPaths,
+            state: input.state,
+            kind: "unavailable",
+            message: "focused path was not reached before max_scan_files stopped discovery",
+        });
+        input.state.stopped = true;
+        return;
+    }
+    input.state.metrics.files_seen++;
+    const pathSecrets = scanSecretPath(input.relativePath);
+    if (pathSecrets.length > 0) {
+        omitted("secret_path", `Secret-looking path omitted (${pathSecrets[0]?.provenance})`);
+        pushTree({
+            eligible: false,
+            content_eligible: false,
+            omission_reason: "secret_path",
+        });
+        return;
+    }
+    let stats;
+    try {
+        stats = await input.fs.lstat(input.absolutePath);
+    }
+    catch (error) {
+        if (isExpectedDescendantFilesystemError(error)) {
+            omittedFromError("File omitted after lstat error", error);
+            return;
+        }
+        throw error;
+    }
+    assertNotAborted(input.signal);
+    if (stats.isSymbolicLink()) {
+        omitted("symlink_omitted", "Symlink omitted during context_builder discovery");
+        return;
+    }
+    if (!stats.isFile()) {
+        return;
+    }
+    const fileVerification = await verifyFileStillExpected({
+        root: input.root,
+        absolutePath: input.absolutePath,
+        relativePath: input.relativePath,
+        expectedStats: stats,
+        fs: input.fs,
+    });
+    if (fileVerification.kind === "omitted") {
+        omitted(fileVerification.omission.reason, fileVerification.omission.message);
+        return;
+    }
+    const sizeBytes = saneFileSize(stats.size);
+    if (sizeBytes == null) {
+        omitted("file_changed_during_read", "File size could not be verified safely");
+        return;
+    }
+    input.state.metrics.files_considered++;
+    if (isNoisyFile(input.relativePath, sizeBytes)) {
+        omitted("noisy_file", "Noisy generated file omitted");
+        pushTree({
+            size_bytes: sizeBytes,
+            eligible: false,
+            content_eligible: false,
+            omission_reason: "noisy_file",
+        });
+        return;
+    }
+    if (input.state.metrics.bytes_read + sizeBytes > input.internalCaps.max_discovery_bytes) {
+        input.state.metrics.discovery_byte_cap_hit = true;
+        requestedOmitted("unavailable", "focused file could not be read before the aggregate discovery byte cap");
+        pushTree({
+            size_bytes: sizeBytes,
+            eligible: true,
+            content_eligible: false,
+            omission_reason: "discovery_byte_cap",
+        });
+        return;
+    }
+    let read;
+    try {
+        read = await readBoundedRegularFile({
+            absolutePath: input.absolutePath,
+            relativePath: input.relativePath,
+            root: input.root,
+            maxBytes: Math.max(input.budget.max_bytes_per_file, CONTEXT_BUILDER_PUBLIC_BUDGET_HARD_LIMITS.max_bytes_per_file),
+            expectedStats: stats,
+            fs: input.fs,
+        });
+    }
+    catch (error) {
+        if (isExpectedDescendantFilesystemError(error)) {
+            const omission = filesystemOmission("File omitted after open/read error", error);
+            omitted(omission.reason, omission.message);
+            pushTree({
+                size_bytes: sizeBytes,
+                eligible: true,
+                content_eligible: false,
+                omission_reason: omission.reason,
+            });
+            return;
+        }
+        throw error;
+    }
+    assertNotAborted(input.signal);
+    if (read.kind === "omitted") {
+        omitted(read.omission.reason, read.omission.message);
+        requestedOmitted(read.omission.reason === "file_too_large" ? "too_large" : "unavailable", read.omission.message);
+        pushTree({
+            size_bytes: read.sizeBytes ?? sizeBytes,
+            eligible: true,
+            content_eligible: false,
+            omission_reason: read.omission.reason,
+        });
+        return;
+    }
+    const contentBuffer = read.buffer;
+    if (isBinaryBuffer(contentBuffer)) {
+        omitted("binary_file", "Binary file omitted from content-bearing artifacts");
+        pushTree({
+            size_bytes: sizeBytes,
+            eligible: true,
+            content_eligible: false,
+            omission_reason: "binary_file",
+        });
+        return;
+    }
+    const rawContent = contentBuffer.toString("utf8");
+    input.state.metrics.bytes_read += contentBuffer.byteLength;
+    const contentSecrets = scanHighConfidenceSecretContent(rawContent);
+    const blockingSecrets = contentSecrets.filter(isBlockingSecretFinding);
+    if (blockingSecrets.length > 0) {
+        omitted("content_secret", `Content omitted due to high-confidence secret (${summarizeSecretFindings(blockingSecrets)})`);
+        pushTree({
+            size_bytes: read.sizeBytes,
+            eligible: true,
+            content_eligible: false,
+            omission_reason: "content_secret",
+        });
+        return;
+    }
+    const content = contentSecrets.length > 0
+        ? redactHighConfidenceAssignmentSecrets(rawContent)
+        : rawContent;
+    const contentBytes = Buffer.byteLength(content, "utf8");
+    if (input.state.contentCandidates.length >= input.internalCaps.max_discovery_candidates) {
+        input.state.metrics.discovery_candidate_cap_hit = true;
+        requestedOmitted("discovery_candidate_cap", "focused file could not be represented because max_discovery_candidates was reached");
+        pushTree({
+            size_bytes: read.sizeBytes,
+            eligible: true,
+            content_eligible: false,
+            omission_reason: "discovery_candidate_cap",
+        });
+        return;
+    }
+    pushTree({
+        size_bytes: read.sizeBytes,
+        eligible: true,
+        content_eligible: true,
+    });
+    input.state.contentCandidates.push({
+        root_index: input.root.root_index,
+        path: input.relativePath,
+        absolute_path: input.absolutePath,
+        content,
+        byte_length: contentBytes,
+        line_count: splitTextLines(content).length,
+        has_final_newline: content.endsWith("\n"),
+        ...(input.selectionHint == null ? {} : { selection_hint: input.selectionHint }),
+    });
+    function omittedFromError(message, error) {
+        const omission = filesystemOmission(message, error);
+        omitted(omission.reason, omission.message);
+    }
+}
+async function verifyDirectoryStillExpected(input) {
+    let lstatStats;
+    try {
+        lstatStats = await input.fs.lstat(input.absoluteDir);
+    }
+    catch (error) {
+        if (isExpectedDescendantFilesystemError(error)) {
+            return {
+                kind: "omitted",
+                omission: filesystemOmission("Directory omitted after filesystem error", error),
+            };
+        }
+        throw error;
+    }
+    if (lstatStats.isSymbolicLink()) {
+        return {
+            kind: "omitted",
+            omission: {
+                reason: "symlink_omitted",
+                message: "Symlink omitted during context_builder discovery",
+            },
+        };
+    }
+    if (!lstatStats.isDirectory()) {
+        return {
+            kind: "omitted",
+            omission: {
+                reason: "file_changed_during_read",
+                message: "Directory changed before it could be read safely",
+            },
+        };
+    }
+    const target = await verifyPathTarget({
+        root: input.root,
+        absolutePath: input.absoluteDir,
+        relativePath: input.relativeDir,
+        expectedStats: lstatStats,
+        expectedKind: "directory",
+        fs: input.fs,
+    });
+    if (target.kind === "omitted") {
+        return target;
+    }
+    return { kind: "verified", realPath: target.realPath };
+}
+async function verifyFileStillExpected(input) {
+    return verifyPathTarget({
+        root: input.root,
+        absolutePath: input.absolutePath,
+        relativePath: input.relativePath,
+        expectedStats: input.expectedStats,
+        expectedKind: "file",
+        fs: input.fs,
+    });
+}
+async function verifyPathTarget(input) {
+    let realPath;
+    try {
+        realPath = await input.fs.realpath(input.absolutePath);
+    }
+    catch (error) {
+        if (isExpectedDescendantFilesystemError(error)) {
+            return {
+                kind: "omitted",
+                omission: filesystemOmission("Path omitted after filesystem error", error),
+            };
+        }
+        throw error;
+    }
+    if (!isSamePathOrDescendant(realPath, input.root.path)) {
+        return {
+            kind: "omitted",
+            omission: {
+                reason: "path_escape",
+                message: "Path resolved outside root during discovery",
+            },
+        };
+    }
+    const normalizedPath = rootRelativePathForAbsolutePath(input.root, realPath);
+    if (normalizedPath !== input.relativePath) {
+        return {
+            kind: "omitted",
+            omission: {
+                reason: "path_escape",
+                message: "Path resolved to an unexpected root-relative target",
+            },
+        };
+    }
+    let targetStats;
+    try {
+        targetStats = await input.fs.stat(realPath);
+    }
+    catch (error) {
+        if (isExpectedDescendantFilesystemError(error)) {
+            return {
+                kind: "omitted",
+                omission: filesystemOmission("Path omitted after filesystem error", error),
+            };
+        }
+        throw error;
+    }
+    const expectedKindMatches = input.expectedKind === "file"
+        ? targetStats.isFile()
+        : targetStats.isDirectory();
+    if (!expectedKindMatches || !sameFileIdentity(input.expectedStats, targetStats)) {
+        return {
+            kind: "omitted",
+            omission: {
+                reason: "file_changed_during_read",
+                message: "Path changed before it could be read safely",
+            },
+        };
+    }
+    return { kind: "verified", realPath };
+}
+function compareTreeFiles(left, right) {
+    return left.root_index - right.root_index || left.path.localeCompare(right.path);
+}
+function compareContentCandidates(left, right) {
+    return left.root_index - right.root_index || left.path.localeCompare(right.path);
+}
+function discoveryTaskClosureRank(path, task) {
+    const normalizedTask = task.toLowerCase();
+    if (normalizedTask.length === 0) {
+        return 0;
+    }
+    const taskTokens = new Set(tokenizeGenericSearchTerm(normalizedTask));
+    const normalizedPath = path.toLowerCase();
+    if (/\b(discover|discovery)\b.*\b(provider-specific|provider\s+semantics|providers?|claude|agent|symmetry)\b|\b(provider-specific|provider\s+semantics|providers?|claude|agent|symmetry)\b.*\b(discover|discovery)\b/.test(normalizedTask) &&
+        hasAnyToken(taskTokens, ["provider", "runtime", "claude", "agent", "symmetry"]) &&
+        [/\/claude_agent\.py$/, /\/runtime\/base\.py$/].some((pattern) => pattern.test(normalizedPath))) {
+        return -30;
+    }
+    if (/\b(discover|discovery)\b/.test(normalizedTask) &&
+        hasAnyToken(taskTokens, ["queue", "migration", "runtime", "schema", "setting", "selector"]) &&
+        [
+            /\/tasks\/chat_processor\.py$/,
+            /\/hooks\/usemessageactions\.ts$/,
+            /\/hooks\/usechatstreaming\.ts$/,
+            /\/hooks\/usechatruntimesettings\.ts$/,
+            /\/components\/chat\/chat-window\/chat\.tsx$/,
+            /\/components\/chat\/message-input\/input\.tsx$/,
+            /\/components\/chat\/message-input\/inputsettingspopover\.tsx$/,
+            /\/pages\/chatpage\.tsx$/,
+            /\/landingpage\.tsx$/,
+            /\/models\/db_models\/chat\.py$/,
+            /\/[^/]*(permission|thinking).*selector[^/]*\.(ts|tsx)$/,
+            /\/tests\/test_chat\.py$/,
+            /\/tests?\/.*runtime.*\.(py|ts|tsx)$/,
+        ].some((pattern) => pattern.test(normalizedPath))) {
+        return -24;
+    }
+    if (/\breview\b/.test(normalizedTask) &&
+        hasAnyToken(taskTokens, ["codex", "approval", "permission", "session", "runtime"]) &&
+        [
+            /\/api\/endpoints\/permissions\.py$/,
+            /\/services\/runtime\/codex_approval\.py$/,
+            /\/services\/permission_manager\.py$/,
+            /\/services\/chat\.py$/,
+            /\/api\/endpoints\/chat\.py$/,
+            /\/models\/db_models\/ai_model\.py$/,
+            /\/services\/chatservice\.ts$/,
+            /\/types\/chat\.types\.ts$/,
+            /\/core\/config\.py$/,
+            /\/constants\.py$/,
+            /\/hooks\/usepermissionrequest\.ts$/,
+            /\/tests\/test_permissions\.py$/,
+            /(^|\/)docs?\/.*(codex|approval|permission|session|runtime).*\.md$/,
+        ].some((pattern) => pattern.test(normalizedPath))) {
+        return -24;
+    }
+    if (/\b(debug|debugging|diagnose|diagnosis|diagnostic)\b/.test(normalizedTask) &&
+        hasAnyToken(taskTokens, ["devtool", "trace", "archive", "message"]) &&
+        [
+            /\/api\/endpoints\/devtools\.py$/,
+            /\/services\/session_trace_archive\.py$/,
+            /\/models\/db_models\/session_trace_archive\.py$/,
+            /\/.*trace.*archive.*\.test\.(ts|tsx|py)$/,
+            /\/tests?\/.*trace.*archive.*\.(py|ts|tsx)$/,
+            /\/messagerenderer\.tsx$/,
+            /\/devtools\.types\.ts$/,
+        ].some((pattern) => pattern.test(normalizedPath))) {
+        return -24;
+    }
+    return 0;
+}
+function hasAnyToken(tokens, candidates) {
+    return candidates.some((candidate) => tokens.has(candidate));
+}
+function compareSearchRecords(left, right) {
+    return (left.root_index - right.root_index ||
+        left.path.localeCompare(right.path) ||
+        left.line - right.line ||
+        left.search_term_index - right.search_term_index ||
+        left.column - right.column);
+}
+function compareFocusPathsForDiscovery(left, right) {
+    return (left.root_index - right.root_index ||
+        left.root_relative_path.localeCompare(right.root_relative_path) ||
+        left.input_index - right.input_index);
+}
+function auditScanCapFocusedPaths(input) {
+    if (!input.state.metrics.scan_cap_hit) {
+        return;
+    }
+    for (const focus of input.focusPaths) {
+        if (hasSurvivingFocusEvidence(input.state, focus) ||
+            hasRequestedEvidenceOmissionForPath(input.state.omissions, focus.root_index, focus.root_relative_path)) {
+            continue;
+        }
+        pushRequestedFocusOmission({
+            root_index: focus.root_index,
+            relativePath: focus.root_relative_path,
+            focusPaths: input.focusPaths,
+            state: input.state,
+            kind: "unavailable",
+            message: "focused path was not reached before max_scan_files stopped discovery",
+        });
+    }
+}
+function hasSurvivingFocusEvidence(state, focus) {
+    return (state.contentCandidates.some((candidate) => focusPathCoversEvidencePath(focus, candidate.root_index, candidate.path)) ||
+        state.tree.some((file) => focusPathCoversEvidencePath(focus, file.root_index, file.path)));
+}
+function focusPathCoversEvidencePath(focus, rootIndex, relativePath) {
+    return (focus.root_index === rootIndex &&
+        (relativePath === focus.root_relative_path ||
+            (focus.kind === "directory" &&
+                isRootRelativeDescendant(relativePath, focus.root_relative_path))));
+}
+function pushRequestedFocusOmission(input) {
+    const paths = requestedEvidencePathsForFocusedOmission(input.root_index, input.relativePath, input.focusPaths).filter((requestedPath) => {
+        const key = requestedEvidenceOmissionKey(input.root_index, requestedPath);
+        if (input.state.requestedEvidenceOmissionKeys.has(key)) {
+            return false;
+        }
+        if (hasRequestedEvidenceOmissionForPath(input.state.omissions, input.root_index, requestedPath)) {
+            input.state.requestedEvidenceOmissionKeys.add(key);
+            return false;
+        }
+        return true;
+    });
+    if (paths.length === 0) {
+        return;
+    }
+    input.state.omissions.push(requestedEvidenceOmission({
+        root_index: input.root_index,
+        kind: input.kind,
+        message: input.message,
+        paths,
+    }));
+    for (const requestedPath of paths) {
+        input.state.requestedEvidenceOmissionKeys.add(requestedEvidenceOmissionKey(input.root_index, requestedPath));
+    }
+}
+function requestedEvidencePathsForFocusedOmission(rootIndex, relativePath, focusPaths) {
+    const paths = new Set();
+    for (const focus of focusPaths) {
+        if (focus.root_index !== rootIndex) {
+            continue;
+        }
+        if (relativePath === focus.root_relative_path) {
+            paths.add(relativePath);
+            continue;
+        }
+        if (focus.kind === "directory" &&
+            isRootRelativeDescendant(relativePath, focus.root_relative_path)) {
+            paths.add(relativePath);
+            continue;
+        }
+        if (isRootRelativeDescendant(focus.root_relative_path, relativePath)) {
+            paths.add(focus.root_relative_path);
+        }
+    }
+    return [...paths].sort();
+}
+function hasRequestedEvidenceOmissionForPath(omissions, rootIndex, relativePath) {
+    return omissions.some((omission) => omission.reason === CONTEXT_BUILDER_REQUESTED_EVIDENCE_OMISSION_REASON &&
+        omission.root_index === rootIndex &&
+        (omission.paths ?? []).includes(relativePath));
+}
+function requestedEvidenceOmissionKey(rootIndex, relativePath) {
+    return `${rootIndex}\u0000${relativePath}`;
+}
+function requestedOmissionKindForDiscoveryReason(reason) {
+    return reason === "file_too_large" ? "too_large" : "unavailable";
+}
+function sanitizedFocusedOmissionMessage(reason) {
+    switch (reason) {
+        case "caller_include_glob":
+            return "focused path was outside include globs";
+        case "exclude_glob":
+            return "focused path was omitted by exclude globs";
+        case "secret_path":
+            return "focused path was omitted because it matched a secret-path rule";
+        case "symlink_omitted":
+            return "focused path was omitted because symlinks are not followed";
+        case "path_escape":
+        case "path_normalized_mismatch":
+            return "focused path could not be safely resolved within the root";
+        case "filesystem_error":
+            return "focused path could not be read due to an expected filesystem error";
+        case "file_changed_during_read":
+            return "focused path changed before it could be read safely";
+        case "noisy_file":
+            return "focused generated file was omitted as noisy";
+        case "binary_file":
+            return "focused binary file cannot be represented as text";
+        case "content_secret":
+            return "focused file content was omitted because secret-like content was detected";
+        case "file_too_large":
+            return "focused file exceeded max_bytes_per_file";
+        default:
+            return "focused path could not be represented as local evidence";
+    }
+}
+function candidateKey(candidate) {
+    return `${candidate.root_index}\u0000${candidate.path}`;
+}
+function searchKey(search) {
+    return `${search.root_index}\u0000${search.path}`;
+}
+function isRootRelativeDescendant(child, parent) {
+    if (parent === "") {
+        return true;
+    }
+    return child === parent || child.startsWith(`${parent}/`);
+}
+function isExcludedRealRoot(realPath, excludedRealRoots) {
+    return excludedRealRoots.some((root) => isSamePathOrDescendant(realPath, root));
+}
+function sliceContent(text, startLine, endLine) {
+    return splitTextLines(text)
+        .slice(startLine - 1, endLine)
+        .join("\n");
+}
+function boundedPreview(line, columnIndex, termLength) {
+    const radius = 80;
+    const start = Math.max(0, columnIndex - radius);
+    const end = Math.min(line.length, columnIndex + termLength + radius);
+    const prefix = start > 0 ? "..." : "";
+    const suffix = end < line.length ? "..." : "";
+    return `${prefix}${line.slice(start, end)}${suffix}`;
+}
+function isBinaryBuffer(buffer) {
+    if (buffer.length === 0) {
+        return false;
+    }
+    if (buffer.includes(0)) {
+        return true;
+    }
+    let suspicious = 0;
+    const sampleLength = Math.min(buffer.length, 8_192);
+    for (let index = 0; index < sampleLength; index++) {
+        const byte = buffer[index] ?? 0;
+        const allowedControl = byte === 0x09 || byte === 0x0a || byte === 0x0d || byte === 0x1b;
+        if (byte < 0x20 && !allowedControl) {
+            suspicious++;
+        }
+    }
+    return suspicious / sampleLength > 0.05;
+}
+function isNoisyFile(rootRelativePath, sizeBytes) {
+    const basename = path.posix.basename(rootRelativePath);
+    return sizeBytes > 20_000 && (basename.endsWith(".min.js") || basename.endsWith(".map"));
+}
+function summarizeSecretFindings(findings) {
+    return findings.map((finding) => finding.provenance).join(", ");
+}
+async function readBoundedRegularFile(input) {
+    const initialVerification = await verifyFileStillExpected({
+        root: input.root,
+        absolutePath: input.absolutePath,
+        relativePath: input.relativePath,
+        expectedStats: input.expectedStats,
+        fs: input.fs,
+    });
+    if (initialVerification.kind === "omitted") {
+        return {
+            kind: "omitted",
+            omission: initialVerification.omission,
+        };
+    }
+    let handle;
+    try {
+        handle = await input.fs.open(input.absolutePath, noFollowReadFlags());
+    }
+    catch (error) {
+        if (filesystemErrorCode(error) === "ELOOP") {
+            return {
+                kind: "omitted",
+                omission: {
+                    reason: "symlink_omitted",
+                    message: "Symlink omitted during context_builder discovery",
+                },
+            };
+        }
+        throw error;
+    }
+    try {
+        const openedStats = await handle.stat();
+        const openedVerification = await verifyFileStillExpected({
+            root: input.root,
+            absolutePath: input.absolutePath,
+            relativePath: input.relativePath,
+            expectedStats: openedStats,
+            fs: input.fs,
+        });
+        if (openedVerification.kind === "omitted") {
+            return {
+                kind: "omitted",
+                omission: openedVerification.omission,
+            };
+        }
+        const openedSize = saneFileSize(openedStats.size);
+        if (!openedStats.isFile() || openedSize == null) {
+            return {
+                kind: "omitted",
+                omission: {
+                    reason: "file_changed_during_read",
+                    message: "File changed before it could be read safely",
+                },
+            };
+        }
+        if (!sameFileIdentity(input.expectedStats, openedStats)) {
+            return {
+                kind: "omitted",
+                omission: {
+                    reason: "file_changed_during_read",
+                    message: "File changed before it could be read safely",
+                },
+                sizeBytes: openedSize,
+            };
+        }
+        if (openedSize > input.maxBytes) {
+            return {
+                kind: "omitted",
+                omission: {
+                    reason: "file_too_large",
+                    message: "File exceeded max_bytes_per_file while opening",
+                },
+                sizeBytes: openedSize,
+            };
+        }
+        const readLength = Math.min(input.maxBytes + 1, openedSize + 1);
+        const buffer = Buffer.alloc(readLength);
+        const { bytesRead } = await handle.read(buffer, 0, readLength, 0);
+        if (bytesRead !== openedSize) {
+            return {
+                kind: "omitted",
+                omission: {
+                    reason: "file_changed_during_read",
+                    message: "File changed before it could be read safely",
+                },
+                sizeBytes: openedSize,
+            };
+        }
+        const finalVerification = await verifyFileStillExpected({
+            root: input.root,
+            absolutePath: input.absolutePath,
+            relativePath: input.relativePath,
+            expectedStats: openedStats,
+            fs: input.fs,
+        });
+        if (finalVerification.kind === "omitted") {
+            return {
+                kind: "omitted",
+                omission: finalVerification.omission,
+                sizeBytes: openedSize,
+            };
+        }
+        return {
+            kind: "read",
+            buffer: buffer.subarray(0, bytesRead),
+            sizeBytes: openedSize,
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+let _noFollowAvailable;
+function noFollowReadFlags() {
+    if (_noFollowAvailable === undefined) {
+        _noFollowAvailable = typeof fsConstants.O_NOFOLLOW === "number";
+    }
+    return _noFollowAvailable
+        ? fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW
+        : fsConstants.O_RDONLY;
+}
+function sameFileIdentity(left, right) {
+    if (left.dev !== right.dev || left.ino !== right.ino) {
+        return false;
+    }
+    if (left.isFile() || right.isFile()) {
+        return left.isFile() && right.isFile()
+            && left.size === right.size
+            && left.mtimeMs === right.mtimeMs;
+    }
+    if (left.isDirectory() || right.isDirectory()) {
+        return left.isDirectory() && right.isDirectory();
+    }
+    return false;
+}
+function saneFileSize(size) {
+    return Number.isSafeInteger(size) && size >= 0 ? size : undefined;
+}
+const EXPECTED_DESCENDANT_FILESYSTEM_ERROR_CODES = new Set([
+    "EACCES",
+    "EPERM",
+    "ENOENT",
+    "ENOTDIR",
+    "ELOOP",
+]);
+function isExpectedDescendantFilesystemError(error) {
+    const code = filesystemErrorCode(error);
+    return (code != null &&
+        EXPECTED_DESCENDANT_FILESYSTEM_ERROR_CODES.has(code));
+}
+function filesystemOmission(message, error) {
+    const code = filesystemErrorCode(error);
+    if (code === "ELOOP") {
+        return {
+            reason: "symlink_omitted",
+            message: "Symlink omitted during context_builder discovery",
+        };
+    }
+    return {
+        reason: "filesystem_error",
+        message: code == null ? message : `${message} (${code})`,
+    };
+}
+function filesystemErrorCode(error) {
+    if (typeof error !== "object" || error == null || !("code" in error)) {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted === true) {
+        throw new CancellationError();
+    }
+}
+//# sourceMappingURL=discovery.js.map