@ngockhoale/ukit 2.4.1 → 2.4.3

package/src/index/buildIndex.js

@@ -8,7 +8,103 @@ import { importsNeedAliasContext, loadImportAliasContextState, resolveImportSpec
 import { clearIndexArtifactCache } from './queryIndex.js';
 import { clearRelatedTestArtifactCache } from './relatedTests.js';
 
-const GIT_ENUMERATION_TIMEOUT_MS = 15_000;
+// One wall-clock ceiling for the WHOLE discovery phase: both `git ls-files`
+// enumerations AND the non-git fallback walk share this single budget. The
+// previous per-git-call 15s timeout let two hung enumerations cost 2 × 15s
+// before discovery ever fell back to the directory walk; now every stage
+// receives only the remaining budget and expiry throws a typed
+// IndexDiscoveryTimeoutError instead of degrading silently.
+export const DEFAULT_DISCOVERY_DEADLINE_MS = 30_000;
+
+// Upper bound on in-flight filesystem stat calls during discovery: git
+// candidate stats and the non-git fallback walk share this fixed pool.
+// The previous `Promise.all(candidates.map(stat))` produced one unbounded
+// promise per candidate, so a 10k-file listing held 10k concurrent stats
+// (descriptors + scheduler pressure) at once. With the pool, peak in-flight
+// I/O stays flat no matter the repository size.
+export const INDEX_IO_CONCURRENCY = 64;
+
+/**
+ * Typed cancellation failure for build phases beyond discovery (stat pools,
+ * file reads/parse, artifact publish) when the caller's AbortSignal fires.
+ * Discovery keeps its own deadline/abort classification in
+ * IndexDiscoveryTimeoutError; this error reports explicit caller cancellation
+ * of the rest of the pipeline.
+ */
+export class IndexCancelledError extends Error {
+  constructor({ phase } = {}) {
+    super(`Index work was cancelled by its AbortSignal (during ${phase}).`);
+    this.name = 'IndexCancelledError';
+    this.code = 'INDEX_CANCELLED';
+    this.phase = phase;
+  }
+}
+
+/**
+ * Fixed-concurrency worker pool over `items`.
+ *
+ * At most `limit` workers run at once, so in-flight I/O never scales with the
+ * item count. Each worker re-checks `signal` BEFORE claiming its next item, so
+ * an abort leaves queued work unstarted and the promise rejects with
+ * IndexCancelledError. A worker rejection maps that one item to `null` while
+ * the remaining items still process — a single failing stat/read can never
+ * hang or kill the pool.
+ *
+ * @returns {Promise<Array>} results in `items` order (null for failed items).
+ */
+export async function mapLimit(items, limit, worker, signal = null, phase = 'map') {
+  const concurrency = Math.max(1, Math.floor(Number(limit)) || 1);
+  const results = new Array(items.length);
+  let nextIndex = 0;
+
+  const runWorker = async () => {
+    while (nextIndex < items.length) {
+      if (signal?.aborted) {
+        throw new IndexCancelledError({ phase });
+      }
+      const index = nextIndex;
+      nextIndex += 1;
+      try {
+        results[index] = await worker(items[index], index);
+      } catch (error) {
+        if (error instanceof IndexDiscoveryTimeoutError || error instanceof IndexCancelledError) {
+          throw error;
+        }
+        results[index] = null;
+      }
+    }
+  };
+
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => runWorker()));
+  return results;
+}
+
+/** Gate for phases between discovery and publish: abort means nothing is written. */
+function assertNotAborted(signal, phase) {
+  if (signal?.aborted) {
+    throw new IndexCancelledError({ phase });
+  }
+}
+
+/**
+ * Typed liveness failure for project discovery. Thrown when the discovery
+ * wall-clock deadline expires or the caller's AbortSignal fires — never a
+ * silent partial result.
+ */
+export class IndexDiscoveryTimeoutError extends Error {
+  constructor({ deadlineMs, phase, elapsedMs, aborted = false }) {
+    super(aborted
+      ? `Index discovery was aborted ${elapsedMs}ms into its ${deadlineMs}ms deadline (during ${phase}).`
+      : `Index discovery exceeded its ${deadlineMs}ms wall-clock deadline (elapsed ${elapsedMs}ms, during ${phase}).`);
+    this.name = 'IndexDiscoveryTimeoutError';
+    this.code = 'INDEX_DISCOVERY_TIMEOUT';
+    this.deadlineMs = deadlineMs;
+    this.phase = phase;
+    this.elapsedMs = elapsedMs;
+    this.aborted = aborted;
+  }
+}
+
 const EXCLUDED_DIR_NAMES = new Set([
   'node_modules',
   '.git',
@@ -36,15 +132,36 @@ const STYLE_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
 const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.sql', '.json', '.yaml', '.yml', '.md', '.sh']);
 const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSIONS]);
 export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-const INDEX_PARSE_BATCH_SIZE = 8;
+// Bumped only when the snapshot shape itself changes; consumers must reject
+// snapshots from a different version instead of trusting unknown fields.
+export const DISCOVERY_SNAPSHOT_VERSION = 1;
+// Parse-phase read/extract concurrency — deliberately tighter than the
+// discovery stat pool because parsing holds file content in memory.
+export const INDEX_PARSE_BATCH_SIZE = 8;
 const CALL_IGNORE_WORDS = new Set([
   'if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'typeof',
 ]);
 
-export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
+export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = null, discoverySnapshot = null, signal = null, deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const indexDir = getIndexDir(absoluteRoot);
 
+  // ── Incremental fast path (TASK-023) ──
+  // Validated changed-file hints let an existing, schema-current index absorb
+  // the change set without a full repository discovery. Every unsafe hint, and
+  // every previous artifact that cannot be merged, falls back to the bounded
+  // full path below — correctness wins over the optimization, and incremental
+  // output must stay equivalent to a clean full rebuild.
+  const changedHintPlan = normalizeChangedFileHints(changedFiles);
+  if (changedHintPlan) {
+    const incremental = changedHintPlan.ok
+      ? await tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths: changedHintPlan.paths, signal })
+      : null;
+    if (incremental) {
+      return incremental;
+    }
+  }
+
   const previousFilesArtifact = await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.files);
   const canReusePrevious = previousFilesArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
   const previousCodeFileRecords = canReusePrevious
@@ -55,7 +172,16 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
     previousCodeFileRecords.map((item) => [item.filePath, { mtimeMs: Number(item.mtimeMs ?? -1), size: Number(item.size ?? -1) }]),
   );
 
-  const discoveredFiles = await discoverProjectFiles(absoluteRoot);
+  // Reuse the caller's discovery snapshot when it describes exactly this root
+  // under the current schema and snapshot version; anything else (foreign root,
+  // stale schema, wrong shape) is rejected and the repository is rediscovered
+  // once here. This is what keeps a stale-check + rebuild refresh at a single
+  // enumeration instead of two.
+  const discoveredFiles = isDiscoverySnapshotUsable(discoverySnapshot, absoluteRoot)
+    ? discoverySnapshot.files
+    // Discovery precedes every artifact write, so a deadline expiry here aborts
+    // the build before any prior index artifact can be replaced.
+    : await discoverProjectFiles(absoluteRoot, { signal, deadlineMs });
   const sourceFingerprint = createSourceFingerprint(absoluteRoot, discoveredFiles);
   const styleFilePaths = discoveredFiles
     .map((entry) => {
@@ -142,32 +268,36 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
   }
   const canReuseAllParsedArtifacts = canReuseParsedArtifacts && filesToParse.length === 0 && reusableCodeFiles.length === codeFiles.length;
 
-  for (let start = 0; start < filesToParse.length; start += INDEX_PARSE_BATCH_SIZE) {
-    const batch = filesToParse.slice(start, start + INDEX_PARSE_BATCH_SIZE);
-    const parsedBatch = (await Promise.all(batch.map(async (filePath) => {
-      try {
-        const absolutePath = path.join(absoluteRoot, filePath);
-        const content = await fs.readFile(absolutePath, 'utf8');
-        const scriptContent = extractScriptContent(filePath, content);
-        return {
-          filePath,
-          symbols: extractSymbols(filePath, scriptContent),
-          imports: [
-            ...extractImports(filePath, scriptContent),
-            ...extractSupplementalImports(filePath, content),
-          ],
-          calls: extractFunctionCalls(filePath, scriptContent),
-        };
-      } catch {
-        return null;
-      }
-    }))).filter(Boolean);
+  // Parse through the same fixed pool as discovery stats: reads stay bounded
+  // by INDEX_PARSE_BATCH_SIZE and the caller's signal is re-checked before
+  // every new file, so an abort stops the phase with queued files unread.
+  // Results come back in filesToParse order, matching the previous batch loop.
+  const parsedFiles = await mapLimit(filesToParse, INDEX_PARSE_BATCH_SIZE, async (filePath) => {
+    try {
+      const absolutePath = path.join(absoluteRoot, filePath);
+      const content = await fs.readFile(absolutePath, 'utf8');
+      const scriptContent = extractScriptContent(filePath, content);
+      return {
+        filePath,
+        symbols: extractSymbols(filePath, scriptContent),
+        imports: [
+          ...extractImports(filePath, scriptContent),
+          ...extractSupplementalImports(filePath, content),
+        ],
+        calls: extractFunctionCalls(filePath, scriptContent),
+      };
+    } catch {
+      return null;
+    }
+  }, signal, 'parse');
 
-    for (const parsedFile of parsedBatch) {
-      symbols.push(...parsedFile.symbols);
-      imports.push(...parsedFile.imports);
-      calls.push(...parsedFile.calls);
+  for (const parsedFile of parsedFiles) {
+    if (!parsedFile) {
+      continue;
     }
+    symbols.push(...parsedFile.symbols);
+    imports.push(...parsedFile.imports);
+    calls.push(...parsedFile.calls);
   }
 
   const canReuseTestsMapCandidate = canReusePrevious
@@ -270,6 +400,10 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
 
   const generatedAt = new Date().toISOString();
 
+  // No partial artifact publish: an abort landing after parsing (during the
+  // artifact-graph phases above) must not replace any artifact either, so the
+  // whole write block sits behind this gate.
+  assertNotAborted(signal, 'publish');
   await fs.mkdir(indexDir, { recursive: true });
   if (!canReuseFilesArtifact) {
     await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.files, {
@@ -347,6 +481,15 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
     generatedAt,
     rootDir: absoluteRoot,
     sourceFingerprint,
+    // Item counts let a later incremental update prove the artifacts it reuses
+    // were not truncated between builds (TASK-023 review, important #2).
+    artifactItemCounts: {
+      [INDEX_ARTIFACTS.files]: fileRecords.length,
+      [INDEX_ARTIFACTS.symbols]: symbols.length,
+      [INDEX_ARTIFACTS.imports]: imports.length,
+      [INDEX_ARTIFACTS.calls]: calls.length,
+      [INDEX_ARTIFACTS.relations]: relations.length,
+    },
   });
   const preservedRuntimeCaches = canReuseFilesArtifact
     && canReuseAllParsedArtifacts
@@ -379,20 +522,671 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
     reusedRelations: canReuseRelations,
     reusedAnalogs: canReuseAnalogs,
     preservedRuntimeCaches,
+    mode: 'full',
+    parsedFiles: filesToParse.slice(),
+    removedFiles: [],
+  };
+}
+
+// ── Incremental refresh (TASK-023) ──────────────────────────────────────────
+//
+// `changedFiles` hints let refresh skip repository discovery entirely: the
+// caller (a watcher or git-status driven hook) asserts which paths changed and
+// the update merges exactly those paths into the existing artifacts. The path
+// is taken only when EVERY gate holds:
+//   - every hint is a safe project-relative path (no absolute form, no `..`
+//     segment, no NUL byte), deduplicated and normalized;
+//   - the previous meta/files/symbols/imports/calls/relations artifacts all
+//     carry the current schema version and a source fingerprint to refresh;
+//   - every stat and read resolves unambiguously (ENOENT means deletion,
+//     anything else means "unknown" and falls back to full discovery);
+//   - every existing hint still resolves (through `realpath`) to a target
+//     inside the resolved root, so a symlink cannot pull external content into
+//     the index that a clean discovery would have excluded;
+//   - every reused artifact is a well-formed item array whose entries stay
+//     contained in the files artifact, so a truncated artifact cannot make the
+//     merge publish a partial artifact.
+// Style files need one extra gate: discovery lists them but files.json never
+// tracks them, so the previous style list only survives inside the relations
+// artifact's source snapshot — without it the refreshed fingerprint could not
+// match a clean rebuild.
+
+function normalizeChangedFileHints(changedFiles) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return null;
+  }
+
+  const paths = [];
+  const seen = new Set();
+  for (const raw of changedFiles) {
+    if (typeof raw !== 'string' || raw.includes('\0')) {
+      return { ok: false, paths: [] };
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+      continue;
+    }
+    // An absolute hint (POSIX or Windows drive form) can never describe a
+    // project-relative path, and a `..` segment cannot be trusted to stay
+    // contained — either rejects the whole hint set so the safe full
+    // discovery path runs instead.
+    if (path.isAbsolute(trimmed) || /^[A-Za-z]:[\\/]/.test(trimmed)) {
+      return { ok: false, paths: [] };
+    }
+    const segments = trimmed.split(/[\\/]+/);
+    if (segments.some((segment) => segment === '..')) {
+      return { ok: false, paths: [] };
+    }
+    const normalized = segments.filter((segment) => segment && segment !== '.').join('/');
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    paths.push(normalized);
+  }
+
+  if (paths.length === 0) {
+    // Hints were requested but none survived validation: treat the request as
+    // ambiguous instead of silently doing nothing.
+    return { ok: false, paths: [] };
+  }
+  return { ok: true, paths };
+}
+
+function isSafeContainedRelative(rootDir, relativePath) {
+  if (!relativePath || path.isAbsolute(relativePath)) {
+    return false;
+  }
+  // Round-trip containment check: joining and re-relativizing must return the
+  // exact hint, which rules out separator or prefix surprises.
+  return path.relative(rootDir, path.join(rootDir, relativePath)) === relativePath;
+}
+
+function isSafeArtifactItem(item) {
+  return Boolean(item)
+    && typeof item === 'object'
+    && !Array.isArray(item)
+    && isSafeArtifactItemPath(item.filePath);
+}
+
+function isSafeArtifactItemPath(relativePath) {
+  return typeof relativePath === 'string'
+    && relativePath !== ''
+    && !path.isAbsolute(relativePath)
+    && !relativePath.split(/[\\/]+/).some((segment) => segment === '..');
+}
+
+function isValidFileRecord(item) {
+  return isSafeArtifactItem(item)
+    && typeof item.domain === 'string'
+    && typeof item.ext === 'string'
+    && Number.isFinite(Number(item.mtimeMs))
+    && Number.isFinite(Number(item.size));
+}
+
+/**
+ * The merge reuses every item of these artifacts verbatim and groups them by
+ * the covered file path. They are only safe to reuse when the array is present
+ * and every entry is a well-formed item whose covered path the files artifact
+ * still tracks — a malformed or foreign entry falls back to the bounded full
+ * path instead of publishing a partial artifact.
+ */
+function isValidCoveredItems(items, fileRecords, keyFn) {
+  if (!Array.isArray(items)) {
+    return false;
+  }
+  const trackedPaths = new Set(fileRecords.map((record) => record.filePath));
+  return items.every((item) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      return false;
+    }
+    const key = keyFn(item);
+    return isSafeArtifactItemPath(key) && trackedPaths.has(key);
+  });
+}
+
+/**
+ * Item shapes alone cannot detect a schema-current artifact whose `items` array
+ * lost entries: every surviving entry still looks valid, yet the merge would
+ * reuse it verbatim and publish an artifact missing the unchanged files. Each
+ * required artifact therefore records its item count in meta, and the count must
+ * match the array actually loaded — a mismatch (or a pre-count meta) falls back
+ * to full discovery.
+ */
+function artifactItemCountsMatch(metaArtifact, counts) {
+  const recorded = metaArtifact?.artifactItemCounts;
+  if (!recorded || typeof recorded !== 'object' || Array.isArray(recorded)) {
+    return false;
+  }
+  return Object.entries(counts).every(([name, count]) => Number(recorded[name]) === count);
+}
+
+/**
+ * Stat every hinted path and classify it as an upsert, a removal, or — for
+ * extensions discovery never indexes — a no-op. Returns null when a hint
+ * cannot be resolved unambiguously so the caller falls back to full discovery.
+ *
+ * Containment is re-checked against the RESOLVED root for every hint that still
+ * exists: `fs.stat` and `fs.readFile` both follow symlinks, so the lexical check
+ * alone would let `src/escape.js -> /outside/secret.js` pull external content
+ * into an incremental update that a clean discovery excludes.
+ */
+async function resolveChangedHintUpdates(rootDir, changedPaths, previousRecordsByPath) {
+  const upserts = new Map();
+  const removals = new Set();
+  const styleUpserts = new Set();
+  const styleRemovals = new Set();
+
+  let rootRealPath = null;
+  try {
+    rootRealPath = await fs.realpath(rootDir);
+  } catch {
+    // The root itself cannot be resolved: no hint is trustworthy.
+    return null;
+  }
+
+  for (const relativePath of changedPaths) {
+    if (!isSafeContainedRelative(rootDir, relativePath)) {
+      return null;
+    }
+
+    const absolutePath = path.join(rootDir, relativePath);
+    let stat = null;
+    try {
+      stat = await fs.stat(absolutePath);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') {
+        return null;
+      }
+    }
+
+    if (stat && !stat.isFile()) {
+      return null;
+    }
+
+    if (stat) {
+      let realPath = null;
+      try {
+        realPath = await fs.realpath(absolutePath);
+      } catch {
+        // Vanished or unresolvable between stat and realpath: unknown state.
+        return null;
+      }
+      if (!isDiscoveryPathContained(rootRealPath, realPath)) {
+        return null;
+      }
+    }
+
+    const ext = path.extname(relativePath).toLowerCase();
+    if (!stat) {
+      // Missing file: a removal when the index knows it, a no-op otherwise.
+      if (previousRecordsByPath.has(relativePath)) {
+        removals.add(relativePath);
+      } else if (STYLE_EXTENSIONS.has(ext)) {
+        styleRemovals.add(relativePath);
+      }
+      continue;
+    }
+
+    if (TRACKED_EXTENSIONS.has(ext)) {
+      upserts.set(relativePath, {
+        filePath: relativePath,
+        domain: relativePath.split('/')[0] ?? 'other',
+        ext,
+        mtimeMs: Math.floor(stat.mtimeMs),
+        size: stat.size,
+      });
+    } else if (STYLE_EXTENSIONS.has(ext)) {
+      styleUpserts.add(relativePath);
+    }
+    // Any other extension is never discovered, so a full rebuild would ignore
+    // it too — the hint is a safe no-op.
+  }
+
+  return { upserts, removals, styleUpserts, styleRemovals };
+}
+
+async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths, signal }) {
+  assertNotAborted(signal, 'incremental-stat');
+
+  const [
+    metaArtifact,
+    filesArtifact,
+    symbolsArtifact,
+    importsArtifact,
+    callsArtifact,
+    testsMapArtifact,
+    hotspotsArtifact,
+    archetypesArtifact,
+    relationsArtifact,
+    analogsArtifact,
+  ] = await Promise.all([
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.meta),
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.files),
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.symbols),
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.imports),
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.calls),
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.testsMap),
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.hotspots),
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.archetypes),
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.relations),
+    readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.analogs),
+  ]);
+
+  // A schema version matching is not enough: the merge reuses these items
+  // verbatim, so each artifact must still be a well-formed item array whose
+  // entries belong to the files artifact, at the item count the meta artifact
+  // recorded when it was published. A schema-current but truncated
+  // symbols.json would otherwise cause the update to publish only the changed
+  // file's symbols and silently drop every unchanged file's.
+  const artifactItemCounts = {
+    [INDEX_ARTIFACTS.files]: filesArtifact?.items?.length ?? -1,
+    [INDEX_ARTIFACTS.symbols]: symbolsArtifact?.items?.length ?? -1,
+    [INDEX_ARTIFACTS.imports]: importsArtifact?.items?.length ?? -1,
+    [INDEX_ARTIFACTS.calls]: callsArtifact?.items?.length ?? -1,
+    [INDEX_ARTIFACTS.relations]: relationsArtifact?.items?.length ?? -1,
+  };
+  const previousArtifactsUsable = [
+    metaArtifact,
+    filesArtifact,
+    symbolsArtifact,
+    importsArtifact,
+    callsArtifact,
+    relationsArtifact,
+  ].every((artifact) => artifact?.schemaVersion === INDEX_SCHEMA_VERSION)
+    && Boolean(metaArtifact?.sourceFingerprint)
+    && Array.isArray(filesArtifact.items)
+    && filesArtifact.items.every((item) => isValidFileRecord(item))
+    && isValidCoveredItems(symbolsArtifact.items, filesArtifact.items, (item) => item.filePath)
+    && isValidCoveredItems(importsArtifact.items, filesArtifact.items, (item) => item.from)
+    && isValidCoveredItems(callsArtifact.items, filesArtifact.items, (item) => item.filePath)
+    && isValidCoveredItems(relationsArtifact.items, filesArtifact.items, (item) => item.filePath)
+    && Array.isArray(relationsArtifact?.sourceSnapshot?.styleFiles)
+    && artifactItemCountsMatch(metaArtifact, artifactItemCounts);
+  if (!previousArtifactsUsable) {
+    return null;
+  }
+
+  const previousRecordsByPath = new Map(filesArtifact.items.map((item) => [item.filePath, item]));
+  const hintUpdates = await resolveChangedHintUpdates(absoluteRoot, changedPaths, previousRecordsByPath);
+  if (!hintUpdates) {
+    return null;
+  }
+
+  // Merge the hint outcome into one sorted record set — the same shape and
+  // ordering the full discovery path produces.
+  const mergedRecordsByPath = new Map(previousRecordsByPath);
+  for (const removedPath of hintUpdates.removals) {
+    mergedRecordsByPath.delete(removedPath);
+  }
+  for (const [upsertedPath, record] of hintUpdates.upserts) {
+    mergedRecordsByPath.set(upsertedPath, record);
+  }
+  const mergedFileRecords = [...mergedRecordsByPath.values()]
+    .sort((a, b) => a.filePath.localeCompare(b.filePath));
+
+  const recordsChanged = !areFileRecordSnapshotsEqual(filesArtifact.items, mergedFileRecords);
+
+  // Only hinted code files whose on-disk identity actually moved are
+  // re-parsed; an unchanged hint must not rewrite anything.
+  const parsedFiles = [];
+  for (const [filePath, record] of hintUpdates.upserts) {
+    if (!CODE_EXTENSIONS.has(record.ext)) {
+      continue;
+    }
+    const previous = previousRecordsByPath.get(filePath);
+    const unchanged = previous
+      && Number(previous.mtimeMs ?? -1) === Number(record.mtimeMs)
+      && Number(previous.size ?? -1) === Number(record.size);
+    if (!unchanged) {
+      parsedFiles.push(filePath);
+    }
+  }
+  parsedFiles.sort((a, b) => a.localeCompare(b));
+
+  // Re-apply style hints to the persisted style list; a listed style file that
+  // vanished without a hint is real drift the update heals the same way a full
+  // rebuild would (by dropping it).
+  const styleSet = new Set(relationsArtifact.sourceSnapshot.styleFiles);
+  let styleListChanged = false;
+  for (const stylePath of hintUpdates.styleUpserts) {
+    if (!styleSet.has(stylePath)) {
+      styleSet.add(stylePath);
+      styleListChanged = true;
+    }
+  }
+  for (const stylePath of hintUpdates.styleRemovals) {
+    if (styleSet.has(stylePath)) {
+      styleSet.delete(stylePath);
+      styleListChanged = true;
+    }
+  }
+  const styleEntries = (await mapLimit([...styleSet].sort((a, b) => a.localeCompare(b)), INDEX_IO_CONCURRENCY, async (stylePath) => {
+    try {
+      const stat = await fs.stat(path.join(absoluteRoot, stylePath));
+      return {
+        absolutePath: path.join(absoluteRoot, stylePath),
+        mtimeMs: Math.floor(stat.mtimeMs),
+        size: stat.size,
+      };
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        styleListChanged = true;
+        return null;
+      }
+      // Unknown stat failure: cannot reconstruct the fingerprint input.
+      return { statError: true };
+    }
+  }, signal, 'stat-style'));
+  if (styleEntries.some((entry) => entry?.statError)) {
+    return null;
+  }
+  const styleFilePaths = styleEntries.filter(Boolean).map((entry) => normalizeRelative(absoluteRoot, entry.absolutePath));
+
+  const previousSymbolsByPath = groupBy(symbolsArtifact.items ?? [], (item) => item.filePath);
+  const previousImportsByPath = groupBy(importsArtifact.items ?? [], (item) => item.from);
+  const previousCallsByPath = groupBy(callsArtifact.items ?? [], (item) => item.filePath);
+
+  const parsedSet = new Set(parsedFiles);
+  const codeFiles = mergedFileRecords.filter((record) => CODE_EXTENSIONS.has(record.ext));
+  // A removal (or an add) changes code-file membership even when nothing is
+  // re-parsed — the merged artifacts must drop (or carry) that file's items.
+  const codeIdentitiesChanged = !haveStableTrackedFileIdentities(
+    filesArtifact.items.filter((item) => CODE_EXTENSIONS.has(item?.ext)),
+    codeFiles,
+  );
+  const parsedArtifactsChanged = parsedFiles.length > 0 || codeIdentitiesChanged;
+  const symbols = [];
+  const imports = [];
+  const calls = [];
+  let reusedCodeFileCount = 0;
+
+  // Full-path ordering: reused files first (sorted), then newly parsed files
+  // (sorted), so a merged artifact carries the same item order a rebuild
+  // produces for the same state.
+  for (const file of codeFiles) {
+    if (parsedSet.has(file.filePath)) {
+      continue;
+    }
+    symbols.push(...(previousSymbolsByPath.get(file.filePath) ?? []));
+    imports.push(...(previousImportsByPath.get(file.filePath) ?? []));
+    calls.push(...(previousCallsByPath.get(file.filePath) ?? []));
+    reusedCodeFileCount += 1;
+  }
+
+  if (parsedFiles.length > 0) {
+    const parsed = await mapLimit(parsedFiles, INDEX_PARSE_BATCH_SIZE, async (filePath) => {
+      try {
+        const absolutePath = path.join(absoluteRoot, filePath);
+        const content = await fs.readFile(absolutePath, 'utf8');
+        const scriptContent = extractScriptContent(filePath, content);
+        return {
+          filePath,
+          symbols: extractSymbols(filePath, scriptContent),
+          imports: [
+            ...extractImports(filePath, scriptContent),
+            ...extractSupplementalImports(filePath, content),
+          ],
+          calls: extractFunctionCalls(filePath, scriptContent),
+        };
+      } catch {
+        return null;
+      }
+    }, signal, 'parse');
+
+    for (const parsedFile of parsed) {
+      if (!parsedFile) {
+        continue;
+      }
+      symbols.push(...parsedFile.symbols);
+      imports.push(...parsedFile.imports);
+      calls.push(...parsedFile.calls);
+    }
+  }
+
+  // Derived artifacts are recomputed in memory from the merged inputs — the
+  // expensive work being avoided is discovery and re-parsing, not these pure
+  // transformations, so their output stays identical to a clean rebuild.
+  const canReuseTestsMap = haveStableTrackedFileIdentities(filesArtifact.items, mergedFileRecords)
+    && testsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+  const testsMap = canReuseTestsMap ? testsMapArtifact.items : buildTestsMap(mergedFileRecords);
+
+  const bugIndexSnapshot = await readBugIndexSnapshot(absoluteRoot);
+  const canReuseHotspots = hotspotsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && areBugIndexSnapshotsEqual(hotspotsArtifact?.sourceSnapshot, bugIndexSnapshot);
+  const hotspots = canReuseHotspots ? hotspotsArtifact.items : await buildHotspots(absoluteRoot, bugIndexSnapshot);
+
+  const archetypes = classifyArchetypes(mergedFileRecords, symbols);
+  const previousCodePaths = new Set(
+    filesArtifact.items.filter((item) => CODE_EXTENSIONS.has(item?.ext)).map((item) => item.filePath),
+  );
+  const currentCodePaths = new Set(codeFiles.map((file) => file.filePath));
+  const canReuseArchetypes = parsedFiles.length === 0
+    && !recordsChanged
+    && archetypesArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && codeFiles.every((file) => previousCodePaths.has(file.filePath))
+    && archetypesArtifact?.items?.length === archetypes.length
+    && (archetypesArtifact.items ?? []).every((item) => currentCodePaths.has(item?.filePath));
+  const archetypeItems = canReuseArchetypes ? archetypesArtifact.items : archetypes;
+
+  const needsAliasContext = importsNeedAliasContext(imports);
+  const importAliasState = needsAliasContext
+    ? await loadImportAliasContextState({ rootDir: absoluteRoot })
+    : null;
+  const importAliasContext = importAliasState?.context ?? null;
+  const styleSnapshot = {
+    styleFiles: styleFilePaths,
+    importAliasSnapshot: importAliasState?.snapshot ?? [],
+  };
+
+  const graphInputsChanged = parsedArtifactsChanged || styleListChanged;
+  const canReuseRelations = !graphInputsChanged
+    && areStringArraysEqual(relationsArtifact?.sourceSnapshot?.styleFiles, styleFilePaths)
+    && arePathSnapshotsEqual(relationsArtifact?.sourceSnapshot?.importAliasSnapshot, styleSnapshot.importAliasSnapshot);
+  const canReuseAnalogs = canReuseRelations
+    && analogsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+
+  let relations = relationsArtifact.items;
+  let analogs = analogsArtifact?.items ?? null;
+  if (!canReuseRelations || !canReuseAnalogs) {
+    const indexedFileSet = new Set(codeFiles.map((file) => file.filePath));
+    const resolvedImportsBySource = buildResolvedImportMap(absoluteRoot, imports, indexedFileSet, importAliasContext);
+    const resolvedStyleImportsBySource = buildResolvedImportMap(absoluteRoot, imports, new Set(styleFilePaths), importAliasContext);
+    if (!canReuseRelations) {
+      relations = buildRelations(mergedFileRecords, archetypeItems, testsMap, resolvedImportsBySource, resolvedStyleImportsBySource);
+    }
+    if (!canReuseAnalogs) {
+      analogs = buildAnalogs(mergedFileRecords, archetypeItems, relations, resolvedImportsBySource);
+    }
+  }
+
+  // The fingerprint covers the merged discovery view (tracked records +
+  // persisted style list), so recomputing it detects a style file whose
+  // content/mtime moved without changing list membership — something
+  // `styleListChanged` alone cannot see, and which a clean full rebuild would
+  // fold into `meta.sourceFingerprint`.
+  const mergedDiscoveredEntries = [
+    ...mergedFileRecords.map((record) => ({
+      absolutePath: path.join(absoluteRoot, record.filePath),
+      mtimeMs: record.mtimeMs,
+      size: record.size,
+    })),
+    ...styleEntries.filter(Boolean),
+  ];
+  const refreshedFingerprint = createSourceFingerprint(absoluteRoot, mergedDiscoveredEntries);
+  const fingerprintChanged = !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, refreshedFingerprint);
+
+  const stateChanged = recordsChanged
+    || parsedFiles.length > 0
+    || styleListChanged
+    || fingerprintChanged;
+  const generatedAt = new Date().toISOString();
+
+  // Same publish gate as the full path: an abort landing after parsing must
+  // not replace any artifact.
+  assertNotAborted(signal, 'publish');
+  await fs.mkdir(indexDir, { recursive: true });
+  if (recordsChanged) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.files, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: mergedFileRecords,
+    });
+  }
+  if (parsedArtifactsChanged) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.symbols, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: symbols,
+    });
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.imports, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: imports,
+    });
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.calls, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: calls,
+    });
+  }
+  if (!canReuseTestsMap) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.testsMap, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: testsMap,
+    });
+  }
+  if (!canReuseHotspots) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.hotspots, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      sourceSnapshot: bugIndexSnapshot,
+      items: hotspots,
+    });
+  }
+  if (!canReuseArchetypes) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.archetypes, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: archetypeItems,
+    });
+  }
+  if (!canReuseRelations) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.relations, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      sourceSnapshot: styleSnapshot,
+      items: relations,
+    });
+  }
+  if (!canReuseAnalogs) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.analogs, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      sourceSnapshot: styleSnapshot,
+      items: analogs,
+    });
+  }
+  if (stateChanged) {
+    // Refresh the fingerprint over the merged discovery view (tracked records
+    // + persisted style list), so staleness detection agrees with a clean
+    // rebuild of the same disk state.
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.meta, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      sourceFingerprint: refreshedFingerprint,
+      // Keep the truncation guard armed for the next incremental update: these
+      // are the counts of the artifacts that now hold those items.
+      artifactItemCounts: {
+        [INDEX_ARTIFACTS.files]: mergedFileRecords.length,
+        [INDEX_ARTIFACTS.symbols]: symbols.length,
+        [INDEX_ARTIFACTS.imports]: imports.length,
+        [INDEX_ARTIFACTS.calls]: calls.length,
+        [INDEX_ARTIFACTS.relations]: relations.length,
+      },
+    });
+  }
+
+  const preservedRuntimeCaches = !recordsChanged
+    && !parsedArtifactsChanged
+    && !styleListChanged
+    && canReuseTestsMap
+    && canReuseHotspots
+    && canReuseArchetypes
+    && canReuseRelations
+    && canReuseAnalogs;
+  if (!preservedRuntimeCaches) {
+    clearIndexArtifactCache(absoluteRoot);
+    clearRelatedTestArtifactCache(absoluteRoot);
+  }
+
+  return {
+    indexDir,
+    generatedAt,
+    generatedAtMs: Date.parse(generatedAt),
+    fileCount: mergedFileRecords.length,
+    symbolCount: symbols.length,
+    importCount: imports.length,
+    testsMapCount: testsMap.length,
+    hotspotCount: hotspots.length,
+    archetypeCount: archetypeItems.length,
+    relationCount: relations.length,
+    analogCount: analogs?.length ?? 0,
+    parsedCodeFileCount: parsedFiles.length,
+    reusedCodeFileCount,
+    reusedTestsMap: canReuseTestsMap,
+    reusedHotspots: canReuseHotspots,
+    reusedRelations: canReuseRelations,
+    reusedAnalogs: canReuseAnalogs,
+    preservedRuntimeCaches,
+    mode: 'incremental',
+    parsedFiles,
+    removedFiles: [...hintUpdates.removals].sort((a, b) => a.localeCompare(b)),
   };
 }
 
-async function collectFiles(scanRoots) {
+async function collectFiles(scanRoots, discovery = null) {
+  const budget = discovery ?? createDiscoveryBudget({});
   const result = [];
   const stack = [...scanRoots];
+  const rootPath = path.resolve(scanRoots[0]);
+  let rootRealPath = null;
+  try {
+    rootRealPath = await resolveDiscoveryPath(rootPath, budget, 'realpath-root');
+  } catch (error) {
+    if (error instanceof IndexDiscoveryTimeoutError) {
+      throw error;
+    }
+  }
+
+  const isInsideRoot = (realPath) => isDiscoveryPathContained(rootRealPath, realPath);
   const visitedDirectoryRealPaths = new Set();
 
   while (stack.length > 0) {
+    assertDiscoveryAlive(budget, 'walk');
     const current = stack.pop();
     let currentRealPath;
     try {
-      currentRealPath = await fs.realpath(current);
-    } catch {
+      currentRealPath = await resolveDiscoveryPath(current, budget, 'realpath');
+    } catch (error) {
+      if (error instanceof IndexDiscoveryTimeoutError) {
+        throw error;
+      }
+      continue;
+    }
+
+    if (!isInsideRoot(currentRealPath)) {
       continue;
     }
 
@@ -403,8 +1197,15 @@ async function collectFiles(scanRoots) {
 
     let entries;
     try {
-      entries = await fs.readdir(current, { withFileTypes: true });
-    } catch {
+      entries = await resolveDiscoveryOperation(
+        () => fs.readdir(current, { withFileTypes: true }),
+        budget,
+        'readdir',
+      );
+    } catch (error) {
+      if (error instanceof IndexDiscoveryTimeoutError) {
+        throw error;
+      }
       continue;
     }
 
@@ -420,15 +1221,35 @@ async function collectFiles(scanRoots) {
         directDirectories.push(fullPath);
       } else if (entry.isSymbolicLink()) {
         try {
-          const stat = await fs.stat(fullPath);
+          const stat = await resolveDiscoveryOperation(
+            () => fs.stat(fullPath),
+            budget,
+            'stat-symlink',
+          );
           if (stat.isDirectory() && !shouldSkipDirectory(entry.name)) {
+            // Containment is re-checked from the link's realpath when the
+            // directory is popped, so an escaping symlinked subtree is pruned.
             symlinkDirectories.push(fullPath);
             continue;
           }
 
           if (stat.isFile()) {
             const ext = path.extname(entry.name).toLowerCase();
-            if (DISCOVERED_EXTENSIONS.has(ext)) {
+            if (!DISCOVERED_EXTENSIONS.has(ext)) {
+              continue;
+            }
+            // A symlinked FILE is indexed only when its real path stays inside
+            // the root; the link itself may point anywhere on disk.
+            let realFilePath = null;
+            try {
+              realFilePath = await resolveDiscoveryPath(fullPath, budget, 'realpath-symlink');
+            } catch (error) {
+              if (error instanceof IndexDiscoveryTimeoutError) {
+                throw error;
+              }
+              realFilePath = null;
+            }
+            if (isInsideRoot(realFilePath)) {
               symlinkFiles.push({
                 absolutePath: fullPath,
                 mtimeMs: Math.floor(stat.mtimeMs),
@@ -436,7 +1257,13 @@ async function collectFiles(scanRoots) {
               });
             }
           }
-        } catch {
+        } catch (error) {
+          // A stalled stat/realpath past the shared deadline must surface as the
+          // typed timeout, not be misclassified as a broken symlink and resolve
+          // to silently truncated discovery.
+          if (error instanceof IndexDiscoveryTimeoutError) {
+            throw error;
+          }
           // broken symlink, skip
         }
       }
@@ -450,19 +1277,26 @@ async function collectFiles(scanRoots) {
       const ext = path.extname(entry.name).toLowerCase();
       return DISCOVERED_EXTENSIONS.has(ext);
     });
-    const fileStats = (await Promise.all(fileEntries.map(async (entry) => {
+    const fileStats = (await mapLimit(fileEntries, INDEX_IO_CONCURRENCY, async (entry) => {
       try {
         const fullPath = path.join(current, entry.name);
-        const stat = await fs.stat(fullPath);
+        const stat = await resolveDiscoveryOperation(
+          () => fs.stat(fullPath),
+          budget,
+          'stat-walk',
+        );
         return {
           absolutePath: fullPath,
           mtimeMs: Math.floor(stat.mtimeMs),
           size: stat.size,
         };
-      } catch {
+      } catch (error) {
+        if (error instanceof IndexDiscoveryTimeoutError) {
+          throw error;
+        }
         return null;
       }
-    }))).filter(Boolean);
+    }, budget.signal, 'stat-walk')).filter(Boolean);
     result.push(...fileStats, ...symlinkFiles);
   }
 
@@ -1062,21 +1896,152 @@ function areBugIndexSnapshotsEqual(previousSnapshot, nextSnapshot) {
  *
  * Non-git projects fall back to walking the root with the same exclusion rules.
  */
-async function discoverProjectFiles(rootDir) {
-  const gitFiles = await collectGitTrackedFiles(rootDir);
+/**
+ * Discover project files under ONE top-level wall-clock deadline.
+ *
+ * @param {string} rootDir - project root.
+ * @param {{ signal?: AbortSignal|null, deadlineMs?: number }} [options]
+ *   `deadlineMs` is a single ceiling divided across both git enumerations and
+ *   the non-git fallback walk — not a per-call timeout. `signal` cancels early
+ *   and surfaces through the same typed error. A non-positive or non-finite
+ *   `deadlineMs` means "no budget": discovery throws immediately.
+ * @returns {Promise<Array<{absolutePath: string, mtimeMs: number, size: number}>>}
+ * @throws {IndexDiscoveryTimeoutError} when the deadline expires or `signal` aborts.
+ */
+export async function discoverProjectFiles(rootDir, { signal = null, deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS } = {}) {
+  const budget = createDiscoveryBudget({ signal, deadlineMs });
+  assertDiscoveryAlive(budget, 'start');
+  const gitFiles = await collectGitTrackedFiles(rootDir, budget);
   if (gitFiles) {
     return gitFiles;
   }
 
-  return collectFiles([rootDir]);
+  return collectFiles([rootDir], budget);
+}
+
+function createDiscoveryBudget({ signal = null, deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS } = {}) {
+  const effectiveDeadlineMs = Number.isFinite(deadlineMs) && deadlineMs > 0 ? deadlineMs : 0;
+  const startedAt = Date.now();
+  return {
+    signal,
+    deadlineMs: effectiveDeadlineMs,
+    startedAt,
+    deadline: startedAt + effectiveDeadlineMs,
+  };
+}
+
+function assertDiscoveryAlive({ signal, deadlineMs, deadline, startedAt }, phase) {
+  const elapsedMs = Date.now() - startedAt;
+  if (signal?.aborted) {
+    throw new IndexDiscoveryTimeoutError({ deadlineMs, phase, elapsedMs, aborted: true });
+  }
+  if (Date.now() >= deadline) {
+    throw new IndexDiscoveryTimeoutError({ deadlineMs, phase, elapsedMs });
+  }
+}
+
+function discoveryOperationTimeout(budget, phase) {
+  assertDiscoveryAlive(budget, phase);
+  return Math.max(1, Math.ceil(remainingDiscoveryMs(budget)));
+}
+
+async function resolveDiscoveryOperation(operation, budget, phase) {
+  const timeoutMs = discoveryOperationTimeout(budget, phase);
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new IndexDiscoveryTimeoutError({
+        deadlineMs: budget.deadlineMs,
+        phase,
+        elapsedMs: Date.now() - budget.startedAt,
+      }));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([Promise.resolve().then(operation), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function resolveDiscoveryPath(filePath, budget, phase) {
+  return resolveDiscoveryOperation(() => fs.realpath(filePath), budget, phase);
+}
+
+function remainingDiscoveryMs({ deadline }) {
+  return deadline - Date.now();
+}
+
+function isDiscoveryPathContained(rootRealPath, realPath) {
+  if (!rootRealPath || !realPath) {
+    return false;
+  }
+  if (realPath === rootRealPath) {
+    return true;
+  }
+  const relative = path.relative(rootRealPath, realPath);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+function createDiscoverySnapshot(rootDir, files, fingerprint) {
+  // Deep-frozen, and each file entry is cloned into a fresh frozen record: the
+  // snapshot must stay byte-stable between the staleness inspection and the
+  // build that consumes it, and a caller that keeps a reference must not be able
+  // to redirect the build by mutating `entry.absolutePath` after inspection.
+  return Object.freeze({
+    snapshotVersion: DISCOVERY_SNAPSHOT_VERSION,
+    schemaVersion: INDEX_SCHEMA_VERSION,
+    rootDir,
+    fingerprint: Object.freeze({ ...fingerprint }),
+    files: Object.freeze(files.map((entry) => Object.freeze({
+      absolutePath: entry?.absolutePath,
+      mtimeMs: entry?.mtimeMs,
+      size: entry?.size,
+    }))),
+  });
 }
 
-function runGit(rootDir, args) {
+function isSnapshotPathContained(rootDir, absolutePath) {
+  if (typeof absolutePath !== 'string' || absolutePath === '' || !path.isAbsolute(absolutePath)) {
+    return false;
+  }
+  const resolved = path.resolve(absolutePath);
+  // A file entry can never be the root directory itself.
+  if (resolved === rootDir) {
+    return false;
+  }
+  const relative = path.relative(rootDir, resolved);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+function isDiscoverySnapshotUsable(discoverySnapshot, absoluteRoot) {
+  return Boolean(discoverySnapshot)
+    && discoverySnapshot.snapshotVersion === DISCOVERY_SNAPSHOT_VERSION
+    && discoverySnapshot.schemaVersion === INDEX_SCHEMA_VERSION
+    && typeof discoverySnapshot.rootDir === 'string'
+    && path.resolve(discoverySnapshot.rootDir) === absoluteRoot
+    && Array.isArray(discoverySnapshot.files)
+    // Fail closed: a snapshot is reusable only when EVERY entry is an absolute
+    // path contained by the snapshotted root. A mutated, relative, or foreign
+    // entry makes the whole snapshot untrusted — the repository is rediscovered
+    // once instead of letting caller-supplied paths steer the build.
+    && discoverySnapshot.files.every((entry) => Boolean(entry)
+      && typeof entry === 'object'
+      && isSnapshotPathContained(absoluteRoot, entry.absolutePath));
+}
+
+function runGit(rootDir, args, budgetMs) {
+  // spawnSync treats `timeout: 0` as "no timeout", so an exhausted budget must
+  // short-circuit here instead of ever reaching an unbounded git call.
+  if (!(budgetMs > 0)) {
+    return null;
+  }
+
   const result = spawnSync('git', args, {
     cwd: rootDir,
     encoding: 'utf8',
     maxBuffer: 256 * 1024 * 1024,
-    timeout: GIT_ENUMERATION_TIMEOUT_MS,
+    timeout: Math.ceil(budgetMs),
     windowsHide: true,
   });
 
@@ -1091,14 +2056,20 @@ function runGit(rootDir, args) {
  * @returns {Promise<Array<{absolutePath: string, mtimeMs: number, size: number}>|null>}
  *   `null` when this is not a usable git worktree, so the caller can fall back.
  */
-async function collectGitTrackedFiles(rootDir) {
+async function collectGitTrackedFiles(rootDir, discovery = null) {
+  const budget = discovery ?? createDiscoveryBudget({});
+  assertDiscoveryAlive(budget, 'git');
   // `-z` matters beyond separators: it also disables git's path quoting, which
   // would otherwise mangle non-ASCII filenames.
-  const tracked = runGit(rootDir, ['ls-files', '-z']);
+  const tracked = runGit(rootDir, ['ls-files', '-z'], remainingDiscoveryMs(budget));
   if (tracked === null) {
     return null;
   }
-  const untracked = runGit(rootDir, ['ls-files', '-z', '--others', '--exclude-standard']) ?? '';
+  // Both enumerations draw from the same budget: a first call that hung pays
+  // the whole ceiling, and the second call (and the fallback walk after it)
+  // only ever gets the remaining time.
+  assertDiscoveryAlive(budget, 'git');
+  const untracked = runGit(rootDir, ['ls-files', '-z', '--others', '--exclude-standard'], remainingDiscoveryMs(budget)) ?? '';
 
   const relativePaths = new Set();
   for (const entry of `${tracked}${untracked}`.split('\0')) {
@@ -1120,23 +2091,50 @@ async function collectGitTrackedFiles(rootDir) {
     return !relativePath.split('/').some((segment) => EXCLUDED_DIR_NAMES.has(segment));
   });
 
-  const entries = await Promise.all(candidates.map(async (relativePath) => {
+  // Fixed pool instead of one unbounded promise per candidate: peak in-flight
+  // stats stay at INDEX_IO_CONCURRENCY for a listing of any size, and an
+  // aborted signal stops the fan-out with queued candidates unstat'ed.
+  let rootRealPath;
+  try {
+    rootRealPath = await resolveDiscoveryPath(path.resolve(rootDir), budget, 'realpath-root');
+  } catch (error) {
+    if (error instanceof IndexDiscoveryTimeoutError) {
+      throw error;
+    }
+    return null;
+  }
+
+  const entries = await mapLimit(candidates, INDEX_IO_CONCURRENCY, async (relativePath) => {
     const absolutePath = path.join(rootDir, relativePath);
     try {
-      const stat = await fs.stat(absolutePath);
+      const stat = await resolveDiscoveryOperation(
+        () => fs.stat(absolutePath),
+        budget,
+        'stat-git',
+      );
       if (!stat.isFile()) {
         return null;
       }
+      // fs.stat follows symlinks. Resolve the final target before accepting a
+      // tracked path so Git cannot make an external file enter the index merely
+      // by tracking an escaping symlink.
+      const realPath = await resolveDiscoveryPath(absolutePath, budget, 'realpath-git');
+      if (!isDiscoveryPathContained(rootRealPath, realPath)) {
+        return null;
+      }
       return {
         absolutePath,
         mtimeMs: Math.floor(stat.mtimeMs),
         size: stat.size,
       };
-    } catch {
-      // staged deletion, or a symlink pointing outside the worktree
+    } catch (error) {
+      if (error instanceof IndexDiscoveryTimeoutError) {
+        throw error;
+      }
+      // staged deletion, broken symlink, or an unreadable path
       return null;
     }
-  }));
+  }, budget.signal, 'stat-git');
 
   return entries.filter(Boolean);
 }
@@ -1810,36 +2808,59 @@ export async function getIndexArtifactGeneratedAt({
   return parseArtifactGeneratedAt(artifact);
 }
 
-export async function isIndexStale({
-  rootDir = process.cwd(),
-  maxAgeMs = DEFAULT_INDEX_CACHE_MAX_AGE_MS,
-  now = Date.now(),
-  generatedAtMs = null,
-} = {}) {
+async function evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, enumerateForSnapshot, signal = null, deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS }) {
   const absoluteRoot = path.resolve(rootDir);
   const metaArtifact = await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.meta);
   const effectiveGeneratedAtMs = Number.isFinite(generatedAtMs)
     ? generatedAtMs
     : parseArtifactGeneratedAt(metaArtifact);
-  if (effectiveGeneratedAtMs === null) {
-    return true;
-  }
 
-  if (typeof maxAgeMs !== 'number' || Number.isNaN(maxAgeMs) || maxAgeMs < 0) {
-    return true;
-  }
+  const staleWithoutEnumeration = effectiveGeneratedAtMs === null
+    || typeof maxAgeMs !== 'number'
+    || Number.isNaN(maxAgeMs)
+    || maxAgeMs < 0
+    || (now - effectiveGeneratedAtMs) >= maxAgeMs
+    || !metaArtifact?.sourceFingerprint;
 
-  if ((now - effectiveGeneratedAtMs) >= maxAgeMs) {
-    return true;
+  // Legacy boolean callers (query-index, triage, verify-context) stop here and
+  // let buildCodeIndex do its own discovery when a rebuild is needed.
+  if (staleWithoutEnumeration && !enumerateForSnapshot) {
+    return { stale: true, snapshot: null };
   }
 
-  if (!metaArtifact?.sourceFingerprint) {
-    return true;
-  }
+  // Exactly one enumeration per inspection. In the refresh flow this snapshot is
+  // handed to buildCodeIndex, so stale-check + rebuild enumerates the repository
+  // once instead of twice.
+  const discoveredFiles = await discoverProjectFiles(absoluteRoot, { signal, deadlineMs });
+  const fingerprint = createSourceFingerprint(absoluteRoot, discoveredFiles);
 
-  const currentSourceFingerprint = createSourceFingerprint(
-    absoluteRoot,
-    await discoverProjectFiles(absoluteRoot),
-  );
-  return !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, currentSourceFingerprint);
+  return {
+    stale: staleWithoutEnumeration
+      ? true
+      : !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, fingerprint),
+    snapshot: createDiscoverySnapshot(absoluteRoot, discoveredFiles, fingerprint),
+  };
+}
+
+export async function inspectIndexStaleness({
+  rootDir = process.cwd(),
+  maxAgeMs = DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  now = Date.now(),
+  generatedAtMs = null,
+  signal = null,
+  deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS,
+} = {}) {
+  return evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, enumerateForSnapshot: true, signal, deadlineMs });
+}
+
+export async function isIndexStale({
+  rootDir = process.cwd(),
+  maxAgeMs = DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  now = Date.now(),
+  generatedAtMs = null,
+  signal = null,
+  deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS,
+} = {}) {
+  const { stale } = await evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, enumerateForSnapshot: false, signal, deadlineMs });
+  return stale;
 }