clinkx 0.2.3 → 1.0.0

package/dist/context-builder/discovery.js

@@ -0,0 +1,2129 @@
+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 { buildContextReviewObligations, } from "./review-coverage.js";
+import { sanitizeHighConfidenceSecretContent, 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;
+// Non-silent, material signal for an explicitly-focused file that exceeded the
+// bounded full-file focus size and had no per-file search evidence: instead of
+// dropping it, we include a bounded head slice and record this reason so the
+// receipt reflects a partial inclusion (not a silent omission).
+const CONTEXT_BUILDER_FOCUS_SLICED_REASON = "focus_sliced";
+// Non-silent, material signal for an explicitly-focused file whose FIRST logical
+// line alone exceeds the bounded focus-slice cap. The line-range model cannot
+// express a partial line, so emitting a head slice would blow the byte bound.
+// We omit the file with this explicit material reason instead — honoring both
+// the byte bound and "never silently drop an explicitly-focused file".
+const CONTEXT_BUILDER_FOCUS_OVER_CAP_REASON = "focus_over_cap";
+const IMPORT_EXPANSION_PASSES = 3;
+const MAX_EXPANDED_SEARCH_TERMS = 128;
+const MAX_EXPANDED_SEARCH_TERM_BYTES = 16_384;
+const MAX_DERIVED_SEARCH_TERM_LENGTH = 256;
+const PROJECT_SUPPORT_FILENAMES = Object.freeze([
+    "package.json",
+    "vitest.config.ts",
+    "vite.config.ts",
+]);
+export async function discoverContextBuilderCandidates(options) {
+    const allowSecrets = options.allowSecrets ?? true;
+    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(),
+        traversedDirectoryKeys: new Set(),
+        focusScanExemptFiles: 0,
+        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 ?? [],
+            allowSecrets,
+            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 processFocusDirectories({
+            root,
+            focusPaths: options.focus_paths ?? [],
+            allowSecrets,
+            matcher,
+            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 traverseDirectory({
+            root,
+            absoluteDir: root.path,
+            relativeDir: "",
+            matcher,
+            focusPaths: options.focus_paths ?? [],
+            allowSecrets,
+            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 ?? [],
+            allowSecrets,
+            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 expandedSearchTerms = expandSearchTerms([...(options.search_terms ?? [])]);
+    const search = buildCandidateSearchRecords({
+        candidates: state.contentCandidates,
+        focusPaths: [...(options.focus_paths ?? [])],
+        searchTerms: expandedSearchTerms.terms,
+        callerTermCount: expandedSearchTerms.callerTermCount,
+        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;
+    }
+    const reviewObligations = buildContextReviewObligations({
+        candidates: state.contentCandidates,
+        focusPaths: (options.focus_paths ?? []).map((focus) => ({
+            root_index: focus.root_index,
+            path: focus.root_relative_path,
+            kind: focus.kind,
+        })),
+        searchRecords: search.records,
+        slices: slices.records,
+        policy: options.coverage_policy,
+    });
+    classifyContextEvidenceCandidates({
+        candidates: state.contentCandidates,
+        focusPaths: options.focus_paths ?? [],
+        searchRecords: search.records,
+        policy: options.coverage_policy,
+        obligations: reviewObligations,
+    });
+    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,
+        search_coverage: search.coverage,
+        ...(reviewObligations == null ? {} : { review_obligations: reviewObligations }),
+    };
+}
+export function expandSearchTerms(searchTerms) {
+    const expanded = [];
+    const seen = new Set();
+    let aggregateBytes = 0;
+    // Caller terms are admitted first and are never displaced by heuristic
+    // expansion. Public post-parse validation owns their individual/aggregate
+    // bounds; this function only bounds derived fan-out before stream creation.
+    for (const term of searchTerms) {
+        const added = addExpandedSearchTerm(expanded, seen, term);
+        aggregateBytes += added;
+    }
+    const callerTermCount = expanded.length;
+    for (const term of searchTerms) {
+        for (const derived of deriveGenericSearchTerms(term)) {
+            const normalized = derived.trim();
+            if (normalized.length > MAX_DERIVED_SEARCH_TERM_LENGTH ||
+                expanded.length >= MAX_EXPANDED_SEARCH_TERMS) {
+                continue;
+            }
+            const bytes = Buffer.byteLength(normalized, "utf8");
+            if (aggregateBytes + bytes > MAX_EXPANDED_SEARCH_TERM_BYTES) {
+                continue;
+            }
+            aggregateBytes += addExpandedSearchTerm(expanded, seen, normalized);
+        }
+    }
+    return { terms: expanded, callerTermCount };
+}
+function classifyContextEvidenceCandidates(input) {
+    if (input.policy?.id == null) {
+        return;
+    }
+    const directSearchKeys = new Set(input.searchRecords.map(candidateKey));
+    const focusedFileKeys = new Set(input.focusPaths
+        .filter((focus) => focus.kind === "file")
+        .map((focus) => candidateKey({
+        root_index: focus.root_index,
+        path: focus.root_relative_path,
+    })));
+    const targetCandidateIds = new Set(input.obligations?.targets.map((target) => target.candidate_id) ?? []);
+    const regressionCandidateIds = new Set(input.obligations?.targets.flatMap((target) => target.regression_links.map((link) => link.candidate_id)) ?? []);
+    for (const candidate of input.candidates) {
+        const classes = [];
+        const key = candidateKey(candidate);
+        const packetCandidateId = `c:${String(candidate.root_index)}:${candidate.path}`;
+        const isReviewTarget = targetCandidateIds.has(packetCandidateId);
+        if (isReviewTarget) {
+            classes.push("review_target");
+        }
+        if (isTestPath(candidate.path) && regressionCandidateIds.has(packetCandidateId)) {
+            classes.push("regression_test");
+        }
+        const hasDiscoveryEvidence = directSearchKeys.has(key) ||
+            focusedFileKeys.has(key) ||
+            candidate.selection_hint != null;
+        if (genericPathKind(candidate.path) === "config" && hasDiscoveryEvidence) {
+            classes.push("configuration");
+        }
+        if (candidate.selection_hint === "local_dependency") {
+            classes.push("dependency");
+        }
+        candidate.evidence_classes = classes;
+    }
+}
+function addExpandedSearchTerm(expanded, seen, term) {
+    const normalized = term.trim();
+    if (normalized.length === 0) {
+        return 0;
+    }
+    const key = normalized.toLowerCase();
+    if (seen.has(key)) {
+        return 0;
+    }
+    expanded.push(normalized);
+    seen.add(key);
+    return Buffer.byteLength(normalized, "utf8");
+}
+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,
+                allowSecrets: input.allowSecrets,
+                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,
+            allowSecrets: input.allowSecrets,
+            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,
+            allowSecrets: input.allowSecrets,
+            budget: input.budget,
+            internalCaps: input.internalCaps,
+            focusScanExempt: true,
+            ...(input.signal == null ? {} : { signal: input.signal }),
+            fs: input.fs,
+            state: input.state,
+        });
+    }
+}
+// Pre-walk explicitly-focused directories before global traversal so a focus
+// directory late in sort order cannot be starved by max_scan_files exhaustion
+// from unrelated trees. Files processed here are focus-scan-exempt (they never
+// erode traversal headroom) but remain bounded by the discovery byte and
+// candidate caps; glob/secret/binary semantics are unchanged because the walk
+// reuses traverseDirectory/processFile verbatim.
+async function processFocusDirectories(input) {
+    const focusDirectories = [...input.focusPaths]
+        .filter((focus) => focus.root_index === input.root.root_index)
+        .filter((focus) => focus.kind === "directory")
+        .sort(compareFocusPathsForDiscovery);
+    for (const focus of focusDirectories) {
+        assertNotAborted(input.signal);
+        // A root-level focus gains nothing from a pre-walk (global traversal
+        // starts there immediately), and pre-walking it would exempt the entire
+        // root from max_scan_files.
+        if (focus.root_relative_path === "") {
+            continue;
+        }
+        // Leave include-glob-pruned focus directories to global traversal, which
+        // emits the existing requested-evidence omission for them.
+        if (!input.matcher.canContainIncludedPath(focus.root_relative_path)) {
+            continue;
+        }
+        await traverseDirectory({
+            root: input.root,
+            absoluteDir: focus.absolute_path,
+            relativeDir: focus.root_relative_path,
+            matcher: input.matcher,
+            focusPaths: input.focusPaths,
+            allowSecrets: input.allowSecrets,
+            budget: input.budget,
+            internalCaps: input.internalCaps,
+            excludedRealRoots: input.excludedRealRoots,
+            focusScanExempt: 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;
+    const callerTermCount = Math.max(0, Math.min(input.callerTermCount ?? 0, input.searchTerms.length));
+    const searchTerms = input.searchTerms
+        .map((term, index) => ({ term, index }))
+        .filter(({ term }) => term.trim().length > 0);
+    const callerTerms = searchTerms.filter(({ index }) => index < callerTermCount);
+    const derivedTerms = searchTerms.filter(({ index }) => index >= callerTermCount);
+    // Candidates whose content was examined for at least one term before a hard
+    // cap ended the walk. Key set is bounded by the candidate pool; only counts
+    // are surfaced.
+    const searchedCandidateKeys = new Set();
+    const callerTermCoverage = callerTerms.map(({ term, index }) => ({
+        term,
+        search_term_index: index,
+        hit_count: 0,
+        scan_complete: false,
+    }));
+    let callerRecordCount = 0;
+    const finalize = () => ({
+        records,
+        capHit,
+        candidateBytes,
+        coverage: {
+            eligible_candidate_count: input.candidates.length,
+            searched_candidate_count: searchedCandidateKeys.size,
+            unsearched_candidate_count: input.candidates.length - searchedCandidateKeys.size,
+            caller_term_count: callerTerms.length,
+            derived_term_count: derivedTerms.length,
+            caller_record_count: callerRecordCount,
+            derived_record_count: records.length - callerRecordCount,
+            caller_coverage_complete: callerTermCoverage.every((coverage) => coverage.scan_complete),
+            caller_terms: callerTermCoverage,
+        },
+    });
+    if (searchTerms.length === 0) {
+        return finalize();
+    }
+    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 ||
+            compareContentCandidates(left, right));
+    });
+    const candidateLines = [];
+    for (const candidate of candidates) {
+        assertNotAborted(input.signal);
+        candidateLines.push(splitTextLines(candidate.content));
+    }
+    // Emits one found hit unless a hard cap rejects it. Cap semantics match the
+    // pre-phasing scheduler: the record/byte caps are checked after the hit is
+    // found, and tripping either one ends the whole search with capHit set.
+    const emitSearchHit = (stream, hit) => {
+        if (records.length >= input.maxSearchResults) {
+            capHit = true;
+            return false;
+        }
+        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 false;
+        }
+        previewBytes += Buffer.byteLength(bounded, "utf8");
+        candidateBytes += recordBytes;
+        records.push(record);
+        return true;
+    };
+    if (callerTerms.length > 0) {
+        // Phase 1 — exact caller terms get first claim on the record budget. One
+        // cursor per caller term walks the complete candidate list (focus rank
+        // first, one hit per candidate per pass), and the scheduler round-robins
+        // across the term cursors, so neither a common sibling term nor an early
+        // alphabetical candidate prefix can starve a rare late-path caller hit.
+        const cursors = callerTermCoverage.map((coverage) => ({
+            coverage,
+            streams: candidates.map((candidate, candidateIndex) => ({
+                candidate,
+                searchTerm: { term: coverage.term, index: coverage.search_term_index },
+                lines: candidateLines[candidateIndex] ?? [],
+                lineIndex: 0,
+                fromIndex: 0,
+                done: false,
+            })),
+            cursor: 0,
+            active: candidates.length,
+            exhausted: false,
+        }));
+        let liveCursors = cursors.length;
+        while (liveCursors > 0) {
+            for (const cursor of cursors) {
+                assertNotAborted(input.signal);
+                if (cursor.exhausted) {
+                    continue;
+                }
+                const next = nextCallerTermHit(cursor, searchedCandidateKeys);
+                if (next == null) {
+                    // Natural exhaustion: this term's cursor examined every candidate.
+                    cursor.exhausted = true;
+                    cursor.coverage.scan_complete = true;
+                    liveCursors--;
+                    continue;
+                }
+                if (!emitSearchHit(next.stream, next.hit)) {
+                    return finalize();
+                }
+                cursor.coverage.hit_count++;
+                callerRecordCount++;
+            }
+        }
+    }
+    if (derivedTerms.length > 0) {
+        // Phase 2 — derived/heuristic terms spend whatever budget remains, using
+        // the pre-existing candidate-major one-hit-per-stream round-robin.
+        const streams = [];
+        for (const [candidateIndex, candidate] of candidates.entries()) {
+            assertNotAborted(input.signal);
+            const lines = candidateLines[candidateIndex] ?? [];
+            for (const searchTerm of derivedTerms) {
+                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;
+                }
+                searchedCandidateKeys.add(candidateKey(stream.candidate));
+                const hit = nextSearchHit(stream);
+                if (hit == null) {
+                    stream.done = true;
+                    activeStreams--;
+                    continue;
+                }
+                foundInRound = true;
+                if (!emitSearchHit(stream, hit)) {
+                    return finalize();
+                }
+            }
+            if (!foundInRound) {
+                break;
+            }
+        }
+    }
+    return finalize();
+}
+// Advances one caller term's cursor to its next hit, cycling the candidate
+// list one hit per candidate per pass. Scanning is free — only emitted records
+// consume the budget — so a rare term reaches late-sorting candidates even
+// when earlier candidates are saturated with other terms' hits. Returns
+// undefined exactly when every candidate stream is exhausted.
+function nextCallerTermHit(cursor, searchedCandidateKeys) {
+    const total = cursor.streams.length;
+    for (let visited = 0; visited < total && cursor.active > 0; visited++) {
+        const stream = cursor.streams[cursor.cursor];
+        cursor.cursor = (cursor.cursor + 1) % total;
+        if (stream == null || stream.done) {
+            continue;
+        }
+        searchedCandidateKeys.add(candidateKey(stream.candidate));
+        const hit = nextSearchHit(stream);
+        if (hit == null) {
+            stream.done = true;
+            cursor.active--;
+            continue;
+        }
+        return { stream, hit };
+    }
+    return undefined;
+}
+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 slicedLargeFocusedCandidates = 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 > maxFullFocusSliceBytes) {
+                    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, []);
+                    }
+                    else if (!slicedLargeFocusedCandidates.has(key)) {
+                        // Never silently drop an explicitly-focused file. With no per-file
+                        // search evidence, include a bounded head slice up to the focus
+                        // byte cap and record a material, non-silent partial-focus signal
+                        // instead of a too_large omission.
+                        if (firstLineExceedsCap(candidate.content, maxFullFocusSliceBytes)) {
+                            // The first logical line alone exceeds the cap (e.g. a minified
+                            // single-line file). The line-range model cannot express a partial
+                            // line, so a head slice would blow the byte bound. Omit the file
+                            // with an explicit material reason rather than exceeding the bound.
+                            omissions.push(focusOverCapNotice(candidate, maxFullFocusSliceBytes));
+                            slicedLargeFocusedCandidates.add(key);
+                            continue;
+                        }
+                        const headEndLine = headSliceEndLine(candidate.content, maxFullFocusSliceBytes);
+                        const ranges = focusRanges.get(key) ?? [];
+                        ranges.push({ start_line: 1, end_line: headEndLine });
+                        focusRanges.set(key, ranges);
+                        omissions.push(focusSlicedNotice(candidate, headEndLine));
+                        slicedLargeFocusedCandidates.add(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) },
+        ]);
+    }
+    // Focus slices are appended FIRST so max_candidate_slices/max_candidate_bytes
+    // pressure prunes search and dependency material before explicitly-focused
+    // ranges — never the other way around.
+    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());
+                pushMissingFocusedSearchOmissions(focusedLargeSearchCandidates.keys());
+                return { records, capHit, omissions };
+            }
+        }
+    }
+    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 };
+            }
+        }
+    }
+    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;
+}
+// Largest 1-based line count whose cumulative UTF-8 bytes (lines joined by
+// "\n", matching sliceContent) stay within capBytes. Always returns >= 1 so an
+// explicitly-focused file is never reduced to nothing.
+// CALLER COUPLING: line 1 is admitted unconditionally (the `count > 0 &&` guard
+// skips the cap check for the first line), so callers MUST pre-screen with
+// firstLineExceedsCap — otherwise an over-cap first line silently breaks the
+// byte bound.
+function headSliceEndLine(content, capBytes) {
+    const lines = splitTextLines(content);
+    let bytes = 0;
+    let count = 0;
+    for (const line of lines) {
+        const next = bytes + (count === 0 ? 0 : 1) + Buffer.byteLength(line, "utf8");
+        if (count > 0 && next > capBytes) {
+            break;
+        }
+        bytes = next;
+        count++;
+    }
+    return Math.max(1, count);
+}
+// True when even the first logical line's own UTF-8 byte length exceeds capBytes,
+// i.e. no head slice (which always covers at least line 1) can fit within the cap.
+function firstLineExceedsCap(content, capBytes) {
+    const lines = splitTextLines(content);
+    const first = lines[0];
+    if (first == null) {
+        return false;
+    }
+    return Buffer.byteLength(first, "utf8") > capBytes;
+}
+function focusOverCapNotice(candidate, capBytes) {
+    return {
+        root_index: candidate.root_index,
+        reason: CONTEXT_BUILDER_FOCUS_OVER_CAP_REASON,
+        message: "focused file's first line alone exceeded the bounded focus-slice cap " +
+            `(${capBytes} bytes); omitted rather than exceeding the byte bound`,
+        paths: [candidate.path],
+    };
+}
+function focusSlicedNotice(candidate, headEndLine) {
+    return {
+        root_index: candidate.root_index,
+        reason: CONTEXT_BUILDER_FOCUS_SLICED_REASON,
+        message: "focused file exceeded bounded full-file focus size and had no per-file " +
+            `search evidence; included a bounded head slice (lines 1-${headEndLine}) ` +
+            "instead of dropping it",
+        paths: [candidate.path],
+    };
+}
+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;
+    }
+    const directoryKey = candidateKey({
+        root_index: input.root.root_index,
+        path: input.relativeDir,
+    });
+    if (input.state.traversedDirectoryKeys.has(directoryKey)) {
+        return;
+    }
+    input.state.traversedDirectoryKeys.add(directoryKey);
+    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, secretFindings) => {
+        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, secretFindings),
+        });
+    };
+    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;
+    }
+    // files_seen stays accurate for observability, but focus-processed files are
+    // subtracted from the cap check so explicit focus never consumes the
+    // max_scan_files headroom reserved for global traversal.
+    if (input.ignoreScanCap !== true &&
+        input.focusScanExempt !== true &&
+        input.state.metrics.files_seen - input.state.focusScanExemptFiles >=
+            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++;
+    if (input.focusScanExempt === true) {
+        input.state.focusScanExemptFiles++;
+    }
+    const pathSecrets = input.allowSecrets ? [] : scanSecretPath(input.relativePath);
+    if (pathSecrets.length > 0) {
+        omitted("secret_path", `Secret-looking path omitted (${pathSecrets[0]?.provenance})`, pathSecrets);
+        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 sanitized = input.allowSecrets
+        ? { status: "unchanged", content: rawContent, findings: [] }
+        : sanitizeHighConfidenceSecretContent(rawContent);
+    if (sanitized.status === "blocked") {
+        omitted("content_secret", `Content omitted due to high-confidence secret (${summarizeSecretFindings(sanitized.findings)})`, sanitized.findings);
+        pushTree({
+            size_bytes: read.sizeBytes,
+            eligible: true,
+            content_eligible: false,
+            omission_reason: "content_secret",
+        });
+        return;
+    }
+    const content = sanitized.content;
+    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 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, secretFindings) {
+    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 withSecretFindingProvenance("focused path was omitted because it matched a secret-path rule", secretFindings);
+        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 withSecretFindingProvenance("focused file content was omitted because secret-like content was detected", secretFindings);
+        case "file_too_large":
+            return "focused file exceeded max_bytes_per_file";
+        default:
+            return "focused path could not be represented as local evidence";
+    }
+}
+const MAX_SECRET_FINDING_PROVENANCE_DETAILS = 3;
+// Appends detector provenance labels and line numbers (never matched secret
+// text or values) to a sanitized focused-omission message, e.g.
+// "... (aws_access_key_id at line 12)".
+function withSecretFindingProvenance(base, secretFindings) {
+    const details = [];
+    for (const finding of secretFindings ?? []) {
+        const detail = finding.line == null
+            ? finding.provenance
+            : `${finding.provenance} at line ${finding.line}`;
+        if (!details.includes(detail)) {
+            details.push(detail);
+        }
+        if (details.length >= MAX_SECRET_FINDING_PROVENANCE_DETAILS) {
+            break;
+        }
+    }
+    return details.length === 0 ? base : `${base} (${details.join(", ")})`;
+}
+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