@duckmind/dm-linux-x64 0.63.9 → 0.64.2

package/extensions/dm-lens/clients/review-graph/builder.js

@@ -0,0 +1,3664 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Worker } from "node:worker_threads";
+import { constants as zlibConstants, gunzipSync, gzipSync } from "node:zlib";
+import { fileURLToPath } from "node:url";
+import { writeFileAtomic } from "../atomic-write.js";
+import { fileContentProvider } from "../dispatch/facts/file-content.js";
+import { lazyEnvNumber } from "../env-utils.js";
+import { featureHintMetadata } from "../feature-hints.js";
+import { detectFileKind, KIND_EXTENSIONS } from "../file-kinds.js";
+import { detectFileRole } from "../file-role.js";
+import { getProjectDataDir } from "../file-utils.js";
+import { collectUntrackedIgnoredIds } from "../git-tracked-ignore.js";
+import { realIsPidAlive } from "../instance-reaper.js";
+import { logLatency } from "../latency-logger.js";
+import {
+  containerNameChain,
+  getOpenDocumentSymbols,
+  lspSymbolKindName
+} from "../lsp-document-symbols.js";
+import {
+  isAtOrAboveHomeDir,
+  normalizeFilePath,
+  normalizeMapKey,
+  toProjectRelativePath
+} from "../path-utils.js";
+import { collectProjectSourceFilesWithBudgetAsync } from "../project-scan-policy.js";
+import { getReviewGraphMaxFilesDerived } from "../project-scale.js";
+import { compareOrdinal } from "../string-utils.js";
+import { BoundedLruCache } from "../bounded-cache.js";
+import {
+  jsTsCandidatePaths,
+  resolveAliasedImport,
+  resolveImportToFiles,
+  resolveProjectReferenceImport,
+  resolveWorkspacePackageImport
+} from "./import-resolvers.js";
+import { RUNTIME_CONFIG } from "../runtime-config.js";
+import {
+  buildReverseDependencyIndexFromGraph,
+  rankFilesByReverseDependencyCentrality
+} from "../reverse-deps.js";
+import { buildQualifiedName, findOwnerName } from "../symbol-containment.js";
+import { logTreeSitterCacheStats } from "../tree-sitter-logger.js";
+import {
+  flushReviewGraphLogSync,
+  logReviewGraph,
+  makeReviewGraphBuildMetadata
+} from "../review-graph-logger.js";
+import { getSharedTreeSitterClient } from "../tree-sitter-shared.js";
+import {
+  symbolExtractionGrammar,
+  TreeSitterSymbolExtractor
+} from "../tree-sitter-symbol-extractor.js";
+import { withTreeSitterRoot } from "../tree-sitter-shared.js";
+import { incrementDegradationCount } from "../degradation-ledger.js";
+import { resolveGitIdentity } from "./git-identity.js";
+import {
+  formatReviewGraphRevisionDriftNote
+} from "./revision-drift.js";
+import { buildSymbolId } from "./symbol-id.js";
+import {
+  clearReviewGraphFileIr,
+  getFreshReviewGraphFileIr,
+  reviewGraphIrContentHash
+} from "./shared-extraction-ir.js";
+export const REVIEW_GRAPH_VERSION = "v8";
+const MAIN_KINDS = new Set([
+  "jsts",
+  "python",
+  "go",
+  "rust",
+  "ruby",
+  "cxx",
+  "java",
+  "kotlin",
+  "dart",
+  "elixir",
+  "csharp",
+  "php",
+  "swift",
+  "lua",
+  "ocaml",
+  "zig",
+  "shell"
+]);
+const MAIN_KIND_EXTENSIONS = Array.from(MAIN_KINDS).flatMap((kind) => KIND_EXTENSIONS[kind] ?? []);
+export const REVIEW_GRAPH_SOURCE_EXTENSIONS = MAIN_KIND_EXTENSIONS;
+const CHANGED_SYMBOLS_PREFIX = "session.reviewGraph.changedSymbols:";
+const extractorCache = new Map;
+const REVIEW_GRAPH_MAX_WARM_WORKSPACES = 8;
+const REVIEW_GRAPH_SOURCE_PATH_MEMO_ENTRIES = 16384;
+const _sourcePathMemos = new BoundedLruCache(REVIEW_GRAPH_MAX_WARM_WORKSPACES);
+function sourcePathMemo(cwd) {
+  const key = normalizeMapKey(path.resolve(cwd));
+  const existing = _sourcePathMemos.get(key);
+  if (existing)
+    return existing;
+  const memo = {
+    cache: new BoundedLruCache(REVIEW_GRAPH_SOURCE_PATH_MEMO_ENTRIES),
+    normalizeCalls: { value: 0 }
+  };
+  _sourcePathMemos.set(key, memo);
+  return memo;
+}
+function normalizeGraphSourcePath(memo, raw) {
+  const cached = memo.cache.get(raw);
+  if (cached !== undefined)
+    return cached;
+  const normalized = normalizeMapKey(raw);
+  if (fs.existsSync(raw))
+    memo.cache.set(raw, normalized);
+  memo.normalizeCalls.value++;
+  return normalized;
+}
+export function _resetReviewGraphSourcePathMemoForTests() {
+  _sourcePathMemos.clear();
+}
+const _buildCache = new Map;
+const _workspaceGraphCache = new Map;
+const REVIEW_GRAPH_IDLE_EVICT_MS_DEFAULT = 20 * 60000;
+let _workspaceCacheEpoch = 0;
+const _workspaceCacheEpochs = new Map;
+function workspaceCacheEpoch(key) {
+  return _workspaceCacheEpoch + (_workspaceCacheEpochs.get(key) ?? 0);
+}
+function reviewGraphIdleEvictMs() {
+  const value = Number.parseInt(process.env.DM_LENS_REVIEW_GRAPH_IDLE_EVICT_MS ?? "", 10);
+  return Number.isSafeInteger(value) && value > 0 ? value : REVIEW_GRAPH_IDLE_EVICT_MS_DEFAULT;
+}
+function clearWorkspaceGraphTimer(entry) {
+  if (entry.idleTimer)
+    clearTimeout(entry.idleTimer);
+  entry.idleTimer = undefined;
+}
+function buildCacheWorkspaceKey(cwd) {
+  return normalizeMapKey(path.resolve(cwd));
+}
+function buildCacheKeyWorkspace(buildKey) {
+  const separator = buildKey.indexOf("|");
+  return separator >= 0 ? buildKey.slice(0, separator) : undefined;
+}
+function evictWorkspaceGraph(key, entry) {
+  if (_workspaceGraphCache.get(key) !== entry)
+    return;
+  clearWorkspaceGraphTimer(entry);
+  const buildWorkspace = buildCacheWorkspaceKey(key);
+  for (const buildKey of _buildCache.keys()) {
+    if (buildCacheKeyWorkspace(buildKey) === buildWorkspace) {
+      _buildCache.delete(buildKey);
+    }
+  }
+  _sourcePathMemos.delete(key);
+  _workspaceCacheEpochs.set(key, (_workspaceCacheEpochs.get(key) ?? 0) + 1);
+  _workspaceGraphCache.delete(key);
+}
+function scheduleWorkspaceGraphEviction(key, entry) {
+  clearWorkspaceGraphTimer(entry);
+  const epoch = workspaceCacheEpoch(key);
+  entry.idleTimer = setTimeout(() => {
+    entry.idleTimer = undefined;
+    if (_workspaceGraphCache.get(key) !== entry || workspaceCacheEpoch(key) !== epoch)
+      return;
+    evictWorkspaceGraph(key, entry);
+  }, reviewGraphIdleEvictMs());
+  entry.idleTimer.unref?.();
+}
+function touchWorkspaceGraph(key) {
+  const entry = _workspaceGraphCache.get(key);
+  if (!entry)
+    return;
+  entry.lastUsedAt = Date.now();
+  scheduleWorkspaceGraphEviction(key, entry);
+}
+function setWorkspaceGraph(key, entry, epoch) {
+  if (epoch !== undefined && workspaceCacheEpoch(key) !== epoch)
+    return false;
+  const previous = _workspaceGraphCache.get(key);
+  if (previous)
+    clearWorkspaceGraphTimer(previous);
+  const boundedGraph = retainedGraph(key, entry.graph);
+  const resident = {
+    ...entry,
+    graph: boundedGraph,
+    lastUsedAt: Date.now()
+  };
+  _workspaceGraphCache.set(key, resident);
+  scheduleWorkspaceGraphEviction(key, resident);
+  while (_workspaceGraphCache.size > REVIEW_GRAPH_MAX_WARM_WORKSPACES) {
+    const victim = [..._workspaceGraphCache.entries()].sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt)[0];
+    if (!victim)
+      break;
+    evictWorkspaceGraph(victim[0], victim[1]);
+  }
+  return true;
+}
+let _graphGenerationCounter = 0;
+let _buildIdCounter = 0;
+const SEQ_FASTPATH_MAX_CHANGES = 32;
+const SEQ_FASTPATH_REVERIFY_MS = 5 * 60000;
+const SEQ_FASTPATH_REVERIFY_EVERY = 20;
+function graphLogMetadata(graph, options = {}) {
+  return makeReviewGraphBuildMetadata(graph, options);
+}
+function seqFastpathEnabled() {
+  const raw = process.env.DM_LENS_GRAPH_SEQ_FASTPATH;
+  return raw !== "0" && raw !== "false";
+}
+let _lastGraphBuildInfo = {
+  reused: false,
+  mode: "full",
+  graphChanged: true
+};
+const _graphBuildInfoByGraph = new WeakMap;
+let _anyGraphStamped = false;
+function setGraphBuildInfo(graph, info) {
+  _lastGraphBuildInfo = info;
+  _graphBuildInfoByGraph.set(graph, info);
+  _anyGraphStamped = true;
+}
+export function getGraphBuildInfoForGraph(graph) {
+  return _graphBuildInfoByGraph.get(graph) ?? _lastGraphBuildInfo;
+}
+export function graphBuildInfoIsTrustworthy(graph) {
+  return _graphBuildInfoByGraph.has(graph) || !_anyGraphStamped;
+}
+function updateGraphBuildInfo(graph, patch) {
+  const info = { ...getGraphBuildInfoForGraph(graph), ...patch };
+  setGraphBuildInfo(graph, info);
+  return info;
+}
+export function clearGraphCache() {
+  _buildCache.clear();
+}
+export function clearReviewGraphWorkspaceCache(cwd) {
+  if (cwd === undefined) {
+    _buildCache.clear();
+    for (const entry of _workspaceGraphCache.values())
+      clearWorkspaceGraphTimer(entry);
+    _workspaceGraphCache.clear();
+    _sourcePathMemos.clear();
+    _workspaceCacheEpoch++;
+    _sizeSkipVerdicts.clear();
+    _retainedGraphSites.clear();
+  } else {
+    const normalized = normalizeMapKey(cwd);
+    const buildWorkspace = buildCacheWorkspaceKey(cwd);
+    for (const key of _buildCache.keys()) {
+      if (buildCacheKeyWorkspace(key) === buildWorkspace) {
+        _buildCache.delete(key);
+      }
+    }
+    const entry = _workspaceGraphCache.get(normalized);
+    if (entry)
+      clearWorkspaceGraphTimer(entry);
+    _workspaceCacheEpochs.set(normalized, (_workspaceCacheEpochs.get(normalized) ?? 0) + 1);
+    _workspaceGraphCache.delete(normalized);
+    _sourcePathMemos.delete(normalized);
+    _sizeSkipVerdicts.delete(normalized);
+  }
+  _lastGraphBuildInfo = { reused: false, mode: "full", graphChanged: true };
+  _anyGraphStamped = false;
+}
+let _reviewGraphBuildGateForTests;
+export function _setReviewGraphBuildGateForTests(gate) {
+  _reviewGraphBuildGateForTests = gate;
+}
+const REVIEW_GRAPH_NODE_RESIDENT_BYTES = 450.5;
+const REVIEW_GRAPH_EDGE_RESIDENT_BYTES = 243;
+export function estimateReviewGraphStoreBytes(totalNodes, totalEdges) {
+  return totalNodes * REVIEW_GRAPH_NODE_RESIDENT_BYTES + totalEdges * REVIEW_GRAPH_EDGE_RESIDENT_BYTES;
+}
+export const GRAPH_MAX_IN_MEMORY_BYTES_DEFAULT = 512 * 1024 * 1024;
+function graphMaxInMemoryBytes() {
+  const raw = Number(process.env.DM_LENS_GRAPH_MAX_IN_MEMORY_BYTES);
+  return Number.isFinite(raw) && raw > 0 ? raw : GRAPH_MAX_IN_MEMORY_BYTES_DEFAULT;
+}
+function retainedGraph(cwd, graph) {
+  const nodes = graph.nodes.size;
+  const edges = graph.edges.length;
+  const bytes = estimateReviewGraphStoreBytes(nodes, edges);
+  const budget = graphMaxInMemoryBytes();
+  if (bytes <= budget)
+    return graph;
+  const elementCap = Math.max(1, Math.floor((nodes + edges) * budget / bytes));
+  let capped = capGraphForPersist(cwd, graph, elementCap);
+  if (capped.nodes.size === 0 && nodes > 0) {
+    capped = headSliceGraph(graph, elementCap);
+    incrementDegradationCount({
+      kind: "review-graph-memory-cap-floor",
+      subject: cwd,
+      reason: `centrality selection retained 0 of ${nodes} nodes at cap ${elementCap}; fell back to a ${capped.nodes.size}-node head slice`
+    });
+  }
+  const cappedNodes = capped.nodes.size;
+  const cappedEdges = capped.edges.length;
+  capped.persistCoverage = {
+    ...capped.persistCoverage ?? graphCoverage(capped, elementCap),
+    partial: true,
+    capTrimmed: true
+  };
+  incrementDegradationCount({
+    kind: "review-graph-memory-cap",
+    subject: cwd,
+    reason: `live graph ${nodes}n/${edges}e ~${Math.round(bytes / (1024 * 1024))}MiB over ${Math.round(budget / (1024 * 1024))}MiB budget; trimmed to ${cappedNodes}n/${cappedEdges}e ~${Math.round(estimateReviewGraphStoreBytes(cappedNodes, cappedEdges) / (1024 * 1024))}MiB`
+  });
+  return capped;
+}
+function headSliceGraph(graph, cap) {
+  const nodeBudget = Math.max(1, Math.floor(cap * graph.nodes.size / (graph.nodes.size + graph.edges.length)));
+  const keptIds = new Set;
+  for (const [id] of graph.nodes) {
+    if (keptIds.size >= nodeBudget)
+      break;
+    keptIds.add(id);
+  }
+  const nodes = new Map([...graph.nodes].filter(([id]) => keptIds.has(id)));
+  const edgeBudget = Math.max(0, cap - nodes.size);
+  const edges = graph.edges.filter((edge) => keptIds.has(edge.from) && keptIds.has(edge.to)).slice(0, edgeBudget);
+  const sliced = {
+    ...graph,
+    nodes,
+    edges,
+    edgesByFrom: new Map,
+    edgesByTo: new Map,
+    fileNodes: new Map,
+    symbolNodesByFile: new Map,
+    changedSymbolsByFile: new Map,
+    persistCoverage: undefined
+  };
+  rebuildIndexes(sliced);
+  return sliced;
+}
+function setSessionReviewGraphFact(cwd, facts, graph) {
+  const retained = retainedGraph(cwd, graph);
+  registerRetainedGraph(`fact:${cwd}`, retained);
+  facts.setSessionFact("session.reviewGraph", retained);
+}
+const _retainedGraphSites = new Map;
+function registerRetainedGraph(site, graph) {
+  for (const [key, ref] of _retainedGraphSites) {
+    if (ref.deref() === undefined)
+      _retainedGraphSites.delete(key);
+  }
+  _retainedGraphSites.set(site, new WeakRef(graph));
+}
+export function getReviewGraphWorkspaceCacheSnapshot() {
+  let totalNodes = 0;
+  let totalEdges = 0;
+  const counted = new Set;
+  const count = (graph) => {
+    if (counted.has(graph))
+      return;
+    counted.add(graph);
+    totalNodes += graph.nodes.size;
+    totalEdges += graph.edges.length;
+  };
+  for (const entry of _workspaceGraphCache.values())
+    count(entry.graph);
+  for (const [key, ref] of _retainedGraphSites) {
+    const graph = ref.deref();
+    if (graph === undefined) {
+      _retainedGraphSites.delete(key);
+      continue;
+    }
+    count(graph);
+  }
+  return {
+    cacheEntries: _workspaceGraphCache.size,
+    totalNodes,
+    totalEdges,
+    residentBytes: estimateReviewGraphStoreBytes(totalNodes, totalEdges)
+  };
+}
+export function _getReviewGraphWorkspaceCacheKeysForTests() {
+  return [..._workspaceGraphCache.entries()].sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt).map(([key]) => key);
+}
+export function _setReviewGraphWorkspaceEntryForTests(key, graph) {
+  setWorkspaceGraph(key, {
+    signature: "test",
+    fileSignatures: new Map,
+    graph
+  });
+}
+export function _setSessionReviewGraphFactForTests(cwd, facts, graph) {
+  setSessionReviewGraphFact(cwd, facts, graph);
+}
+export function _persistedCoverageForTests(coverage) {
+  return stripProcessLocalCoverage(coverage);
+}
+export function _getReviewGraphWorkspaceGraphForTests(key) {
+  return _workspaceGraphCache.get(key)?.graph;
+}
+export function _getReviewGraphCacheStateForTests(cwd) {
+  const cached = _workspaceGraphCache.get(normalizeMapKey(cwd));
+  if (!cached)
+    return;
+  touchWorkspaceGraph(normalizeMapKey(cwd));
+  return {
+    signature: cached.signature,
+    fileSignatures: new Map(cached.fileSignatures),
+    fileHashes: cached.fileHashes ? new Map(cached.fileHashes) : undefined
+  };
+}
+export function getReviewGraphCacheIdentity(cwd, graph) {
+  const cached = _workspaceGraphCache.get(normalizeMapKey(cwd));
+  if (!cached)
+    return;
+  touchWorkspaceGraph(normalizeMapKey(cwd));
+  if (graph) {
+    if (cached.buildGeneration === undefined && graph.buildGeneration === undefined) {
+      if (cached.graph !== graph)
+        return;
+    } else if (cached.buildGeneration !== graph.buildGeneration) {
+      return;
+    }
+  }
+  const version = graph?.version ?? cached.graph.version;
+  if (typeof version !== "string" || version.length === 0 || typeof cached.signature !== "string") {
+    return;
+  }
+  return { version, signature: cached.signature };
+}
+const _cwdWorktreeCheckedCwds = new Set;
+export function _resetCwdWorktreeMismatchLogForTests() {
+  _cwdWorktreeCheckedCwds.clear();
+}
+function logCwdWorktreeMismatchOnce(cwd) {
+  const key = normalizeMapKey(cwd);
+  if (_cwdWorktreeCheckedCwds.has(key))
+    return;
+  _cwdWorktreeCheckedCwds.add(key);
+  const identity = resolveGitIdentity(cwd);
+  if (!identity)
+    return;
+  if (identity.worktreeRoot === normalizeFilePath(path.resolve(cwd)))
+    return;
+  logLatency({
+    type: "phase",
+    phase: "review_graph_cwd_worktree_mismatch",
+    filePath: cwd,
+    durationMs: 0,
+    metadata: { cwd, worktreeRoot: identity.worktreeRoot }
+  });
+}
+export function getLastGraphBuildInfo() {
+  return _lastGraphBuildInfo;
+}
+export function _setLastGraphBuildInfoForTests(info) {
+  _lastGraphBuildInfo = info;
+}
+function ensureIndexed(graph) {
+  if (graph.edges.length > 0 && graph.edgesByFrom.size === 0) {
+    rebuildIndexes(graph);
+  }
+}
+export function getCachedReviewGraph(cwd) {
+  const key = normalizeMapKey(cwd);
+  if (getReviewGraphSizeSkipVerdict(cwd))
+    return;
+  const cached = _workspaceGraphCache.get(key);
+  if (cached) {
+    touchWorkspaceGraph(key);
+    ensureIndexed(cached.graph);
+    return cached.graph;
+  }
+  const disk = loadPersistedGraph(cwd, {
+    verifyWorktreeIdentity: true,
+    allowPartial: true
+  });
+  if (!disk)
+    return;
+  setWorkspaceGraph(key, {
+    signature: disk.signature,
+    fileSignatures: disk.fileSignatures,
+    fileHashes: disk.fileHashes,
+    graph: disk.graph,
+    ...disk.stampedHead ? { snapshotStampedHead: disk.stampedHead } : {}
+  });
+  return disk.graph;
+}
+export function getReviewGraphRevisionDrift(cwd) {
+  const entry = _workspaceGraphCache.get(normalizeMapKey(cwd));
+  const stampedHead = entry?.snapshotStampedHead;
+  if (!stampedHead)
+    return;
+  const current = resolveGitIdentity(cwd);
+  if (!current || current.headCommit === stampedHead)
+    return;
+  return { stampedHead, currentHead: current.headCommit };
+}
+
+export { formatReviewGraphRevisionDriftNote };
+function makeCtx(filePath, cwd, facts) {
+  return {
+    filePath,
+    cwd,
+    kind: detectFileKind(filePath),
+    fileRole: detectFileRole(filePath),
+    pi: { getFlag: () => {
+      return;
+    } },
+    autofix: false,
+    deltaMode: false,
+    facts,
+    blockingOnly: false,
+    modifiedRanges: undefined,
+    hasTool: async () => false,
+    log: () => {}
+  };
+}
+function escapeRegExp(string) {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function createEmptyGraph() {
+  return {
+    version: REVIEW_GRAPH_VERSION,
+    builtAt: new Date().toISOString(),
+    nodes: new Map,
+    edges: [],
+    edgesByFrom: new Map,
+    edgesByTo: new Map,
+    fileNodes: new Map,
+    symbolNodesByFile: new Map,
+    changedSymbolsByFile: new Map
+  };
+}
+function cloneGraph(graph) {
+  return {
+    version: graph.version,
+    builtAt: graph.builtAt,
+    nodes: new Map(graph.nodes),
+    edges: [...graph.edges],
+    edgesByFrom: new Map,
+    edgesByTo: new Map,
+    fileNodes: new Map,
+    symbolNodesByFile: new Map,
+    changedSymbolsByFile: new Map(graph.changedSymbolsByFile),
+    persistCoverage: graph.persistCoverage
+  };
+}
+function refreshGraphBuiltAt(graph) {
+  graph.builtAt = new Date().toISOString();
+}
+function sourceSignatureEntry(file) {
+  try {
+    const stat = fs.statSync(file);
+    return `${stat.size}:${stat.mtimeMs}`;
+  } catch {
+    return "missing";
+  }
+}
+const STAT_YIELD_EVERY = 100;
+const yieldToLoop = () => new Promise((resolve) => setImmediate(resolve));
+async function sourceSignatureMapAsync(files) {
+  const signatures = new Map;
+  let sinceYield = 0;
+  for (const file of files) {
+    signatures.set(file, sourceSignatureEntry(file));
+    if (++sinceYield >= STAT_YIELD_EVERY) {
+      sinceYield = 0;
+      await yieldToLoop();
+    }
+  }
+  return signatures;
+}
+function sourceSignatureFromMap(signatures) {
+  return [...signatures.entries()].sort(([a], [b]) => compareOrdinal(a, b)).map(([file, signature]) => `${file}:${signature}`).join("|");
+}
+function contentHashEntry(file) {
+  try {
+    return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+  } catch {
+    return "missing";
+  }
+}
+async function confirmContentChanged(candidates, previousHashes) {
+  const prior = previousHashes ?? new Map;
+  const hashes = new Map(prior);
+  const trulyChanged = [];
+  let sinceYield = 0;
+  for (const file of candidates) {
+    const hash = contentHashEntry(file);
+    hashes.set(file, hash);
+    if (prior.get(file) !== hash)
+      trulyChanged.push(file);
+    if (++sinceYield >= STAT_YIELD_EVERY) {
+      sinceYield = 0;
+      await yieldToLoop();
+    }
+  }
+  return { trulyChanged, hashes };
+}
+function diffSignatureMaps(previous, next) {
+  const added = [];
+  const changed = [];
+  for (const [file, signature] of next) {
+    const oldSignature = previous.get(file);
+    if (oldSignature === undefined)
+      added.push(file);
+    else if (oldSignature !== signature)
+      changed.push(file);
+  }
+  const removed = [];
+  for (const file of previous.keys()) {
+    if (!next.has(file))
+      removed.push(file);
+  }
+  return { added, removed, changed };
+}
+export function getReviewGraphMaxFiles(cwd) {
+  const override = Number.parseInt(process.env.DM_LENS_REVIEW_GRAPH_MAX_FILES ?? "", 10);
+  return Number.isFinite(override) && override > 0 ? override : getReviewGraphMaxFilesDerived(cwd);
+}
+function getReviewGraphMaxFileBytes() {
+  const override = Number.parseInt(process.env.DM_LENS_REVIEW_GRAPH_MAX_FILE_BYTES ?? "", 10);
+  return Number.isFinite(override) && override > 0 ? override : RUNTIME_CONFIG.reviewGraph.maxFileBytes;
+}
+function isWithinReviewGraphSizeLimit(file) {
+  try {
+    return fs.statSync(file).size <= getReviewGraphMaxFileBytes();
+  } catch {
+    return false;
+  }
+}
+const DEFAULT_REVIEW_GRAPH_SIZE_SKIP_TTL_MS = 15 * 60000;
+const _sizeSkipTtl = lazyEnvNumber("DM_LENS_REVIEW_GRAPH_SIZE_SKIP_TTL_MS", DEFAULT_REVIEW_GRAPH_SIZE_SKIP_TTL_MS);
+export const _resetReviewGraphSizeSkipTtlForTests = _sizeSkipTtl._resetForTests;
+const _buildAttempts = new Map;
+export function getLastReviewGraphBuildAttempt(cwd) {
+  return _buildAttempts.get(normalizeMapKey(cwd));
+}
+export function _resetReviewGraphBuildAttemptsForTests() {
+  _buildAttempts.clear();
+}
+function recordBuildAttempt(cwd, outcome, reason, buildId) {
+  const key = normalizeMapKey(cwd);
+  const prior = _buildAttempts.get(key);
+  if (prior?.buildId !== undefined && (buildId === undefined || buildId < prior.buildId)) {
+    return;
+  }
+  _buildAttempts.set(key, {
+    when: new Date().toISOString(),
+    outcome,
+    ...buildId === undefined ? {} : { buildId },
+    ...reason ? { reason } : {}
+  });
+}
+function recordPersistFailure(cwd, reason, error, pending, workerState) {
+  const prior = _buildAttempts.get(normalizeMapKey(cwd));
+  const pendingBuildId = pending?.graphMetadata.buildId;
+  const belongsToCurrentBuild = pendingBuildId === undefined || prior?.buildId === pendingBuildId;
+  if (belongsToCurrentBuild && (prior === undefined || prior.outcome === "succeeded")) {
+    recordBuildAttempt(cwd, "succeeded", `graph built but persistence failed: ${error}`, pendingBuildId);
+  }
+  logReviewGraph({
+    cwd,
+    phase: "persist_failed",
+    reason,
+    error,
+    ...pending ? {
+      observability: persistObservability(pending, {
+        status: "failed",
+        reason: workerState?.fallbackReason ?? reason,
+        workerStarted: workerState?.started,
+        workerCompleted: workerState?.completed,
+        ...workerState?.fallbackReason ? { workerFallback: true } : {}
+      })
+    } : {}
+  });
+}
+const _sizeSkipVerdicts = new Map;
+export function _resetReviewGraphSizeSkipVerdictsForTests() {
+  _sizeSkipVerdicts.clear();
+}
+function recordReviewGraphSizeSkip(cwd, sourceFileCount, maxFileCount) {
+  _sizeSkipVerdicts.set(normalizeMapKey(cwd), {
+    sourceFileCount,
+    maxFileCount,
+    sourceFileCountTruncated: true,
+    skippedAt: Date.now()
+  });
+}
+function clearReviewGraphSizeSkip(cwd) {
+  _sizeSkipVerdicts.delete(normalizeMapKey(cwd));
+}
+const REVIEW_GRAPH_SIZE_NEAR_MISS_RATIO = 0.05;
+function isReviewGraphSizeNearMiss(sourceFileCount, maxFileCount) {
+  return sourceFileCount > maxFileCount && sourceFileCount <= maxFileCount * (1 + REVIEW_GRAPH_SIZE_NEAR_MISS_RATIO);
+}
+export function getReviewGraphSizeSkipVerdict(cwd, now = Date.now()) {
+  const key = normalizeMapKey(cwd);
+  const verdict = _sizeSkipVerdicts.get(key);
+  if (!verdict)
+    return;
+  if (now - verdict.skippedAt >= _sizeSkipTtl.get()) {
+    _sizeSkipVerdicts.delete(key);
+    return;
+  }
+  return verdict;
+}
+let _reviewGraphEntryBudgetForTests;
+export function _setReviewGraphEntryBudgetForTests(maxScanEntries) {
+  _reviewGraphEntryBudgetForTests = maxScanEntries;
+}
+let _reviewGraphEntryCounterForTests;
+export function _setReviewGraphEntryCounterForTests(counter) {
+  _reviewGraphEntryCounterForTests = counter;
+}
+export async function getGraphSourceFiles(cwd) {
+  const sourceMemo = sourcePathMemo(cwd);
+  const normalizeCallsBefore = sourceMemo.normalizeCalls.value;
+  const maxGraphFiles = getReviewGraphMaxFiles(cwd);
+  const { files: collected, entryBudgetExceeded } = await collectProjectSourceFilesWithBudgetAsync(cwd, {
+    extensions: MAIN_KIND_EXTENSIONS,
+    maxFiles: maxGraphFiles + 1,
+    ..._reviewGraphEntryBudgetForTests === undefined ? {} : { maxScanEntries: _reviewGraphEntryBudgetForTests },
+    ..._reviewGraphEntryCounterForTests === undefined ? {} : { onEntryVisited: _reviewGraphEntryCounterForTests }
+  });
+  if (entryBudgetExceeded) {
+    logLatency({
+      type: "phase",
+      phase: "review_graph_source_walk_entry_budget",
+      filePath: cwd,
+      durationMs: 0,
+      metadata: { cwd, collectedFiles: collected.length }
+    });
+  }
+  if (collected.length > maxGraphFiles) {
+    return {
+      files: collected,
+      pathNormalizeCalls: sourceMemo.normalizeCalls.value - normalizeCallsBefore,
+      sourceFileCount: collected.length,
+      maxFileCount: maxGraphFiles,
+      entryBudgetExceeded
+    };
+  }
+  const result = [];
+  let sinceYield = 0;
+  for (const raw of collected) {
+    const file = normalizeGraphSourcePath(sourceMemo, raw);
+    const kind = detectFileKind(file);
+    if (!!kind && MAIN_KINDS.has(kind) && detectFileRole(file) !== "test" && isWithinReviewGraphSizeLimit(file)) {
+      result.push(file);
+    }
+    if (++sinceYield >= STAT_YIELD_EVERY) {
+      sinceYield = 0;
+      await yieldToLoop();
+    }
+  }
+  return {
+    files: result,
+    pathNormalizeCalls: sourceMemo.normalizeCalls.value - normalizeCallsBefore,
+    sourceFileCount: result.length,
+    maxFileCount: maxGraphFiles,
+    entryBudgetExceeded
+  };
+}
+function addNode(graph, node) {
+  const isNew = !graph.nodes.has(node.id);
+  graph.nodes.set(node.id, node);
+  if (node.kind === "file" && node.filePath) {
+    graph.fileNodes.set(node.filePath, node.id);
+    return;
+  }
+  if (isNew && node.kind === "symbol" && node.filePath) {
+    const ids = graph.symbolNodesByFile.get(node.filePath) ?? [];
+    ids.push(node.id);
+    graph.symbolNodesByFile.set(node.filePath, ids);
+  }
+}
+function indexEdge(graph, edge) {
+  const from = graph.edgesByFrom.get(edge.from) ?? [];
+  from.push(edge);
+  graph.edgesByFrom.set(edge.from, from);
+  const to = graph.edgesByTo.get(edge.to) ?? [];
+  to.push(edge);
+  graph.edgesByTo.set(edge.to, to);
+}
+function unindexEdge(graph, edge) {
+  const from = graph.edgesByFrom.get(edge.from);
+  if (from) {
+    _rebuildCounters.removeOwnedEdgePositions += from.length;
+    const at = from.indexOf(edge);
+    if (at >= 0)
+      from.splice(at, 1);
+    if (from.length === 0)
+      graph.edgesByFrom.delete(edge.from);
+  }
+  const to = graph.edgesByTo.get(edge.to);
+  if (to) {
+    _rebuildCounters.removeOwnedEdgePositions += to.length;
+    const at = to.indexOf(edge);
+    if (at >= 0)
+      to.splice(at, 1);
+    if (to.length === 0)
+      graph.edgesByTo.delete(edge.to);
+  }
+}
+function unindexEdges(graph, removedEdges) {
+  const fromIds = new Set;
+  const toIds = new Set;
+  for (const edge of removedEdges) {
+    fromIds.add(edge.from);
+    toIds.add(edge.to);
+  }
+  for (const fromId of fromIds) {
+    const bucket = graph.edgesByFrom.get(fromId);
+    if (!bucket)
+      continue;
+    const kept = [];
+    for (const edge of bucket) {
+      _rebuildCounters.removeOwnedEdgePositions++;
+      if (!removedEdges.has(edge))
+        kept.push(edge);
+    }
+    if (kept.length === 0)
+      graph.edgesByFrom.delete(fromId);
+    else
+      graph.edgesByFrom.set(fromId, kept);
+  }
+  for (const toId of toIds) {
+    const bucket = graph.edgesByTo.get(toId);
+    if (!bucket)
+      continue;
+    const kept = [];
+    for (const edge of bucket) {
+      _rebuildCounters.removeOwnedEdgePositions++;
+      if (!removedEdges.has(edge))
+        kept.push(edge);
+    }
+    if (kept.length === 0)
+      graph.edgesByTo.delete(toId);
+    else
+      graph.edgesByTo.set(toId, kept);
+  }
+}
+function addEdge(graph, edge) {
+  graph.edges.push(edge);
+  indexEdge(graph, edge);
+}
+function rebuildIndexes(graph) {
+  graph.edgesByFrom = new Map;
+  graph.edgesByTo = new Map;
+  graph.fileNodes = new Map;
+  graph.symbolNodesByFile = new Map;
+  for (const node of graph.nodes.values()) {
+    if (node.kind === "file" && node.filePath) {
+      graph.fileNodes.set(node.filePath, node.id);
+    }
+    if (node.kind === "symbol" && node.filePath) {
+      const ids = graph.symbolNodesByFile.get(node.filePath) ?? [];
+      ids.push(node.id);
+      graph.symbolNodesByFile.set(node.filePath, ids);
+    }
+  }
+  for (const edge of graph.edges) {
+    const from = graph.edgesByFrom.get(edge.from) ?? [];
+    from.push(edge);
+    graph.edgesByFrom.set(edge.from, from);
+    const to = graph.edgesByTo.get(edge.to) ?? [];
+    to.push(edge);
+    graph.edgesByTo.set(edge.to, to);
+  }
+}
+const GRAPH_CACHE_FILENAME = "review-graph.json.gz";
+const LEGACY_GRAPH_CACHE_FILENAME = "review-graph.json";
+const GRAPH_CHECKPOINT_FILENAME = "review-graph.checkpoint.json.gz";
+function logSnapshotReadVerdict(cwd, phase, reason) {
+  const verdict = phase === "snapshot_read_dropped" ? "dropped" : "drifted";
+  const isRisingEdge = incrementDegradationCount({
+    kind: "review-graph-snapshot-read",
+    subject: `${verdict}:${normalizeMapKey(cwd)}`,
+    reason
+  });
+  if (!isRisingEdge)
+    return;
+  logReviewGraph({ cwd, phase, reason });
+}
+function loadPersistedGraph(cwd, opts) {
+  const cacheDir = path.join(getProjectDataDir(cwd), "cache");
+  const cachePath = path.join(cacheDir, GRAPH_CACHE_FILENAME);
+  const legacyPath = path.join(cacheDir, LEGACY_GRAPH_CACHE_FILENAME);
+  try {
+    const raw = fs.existsSync(cachePath) ? gunzipSync(fs.readFileSync(cachePath)).toString("utf-8") : fs.readFileSync(legacyPath, "utf-8");
+    const data = JSON.parse(raw);
+    if (data.version !== REVIEW_GRAPH_VERSION || typeof data.signature !== "string" || typeof data.builtAt !== "string" || !Array.isArray(data.nodes) || !Array.isArray(data.edges))
+      return null;
+    if (data.coverage?.partial && !opts?.allowPartial)
+      return null;
+    let stampedHead;
+    if (opts?.verifyWorktreeIdentity && data.gitStamp) {
+      const current = resolveGitIdentity(cwd);
+      if (current && current.worktreeRoot !== data.gitStamp.worktreeRoot) {
+        logSnapshotReadVerdict(cwd, "snapshot_read_dropped", "worktree_mismatch");
+        return null;
+      }
+      if (current && current.headCommit !== data.gitStamp.headCommit) {
+        stampedHead = data.gitStamp.headCommit;
+        logSnapshotReadVerdict(cwd, "snapshot_read_drifted", "head_moved");
+      }
+    }
+    const graph = {
+      version: data.version,
+      builtAt: data.builtAt,
+      nodes: new Map(data.nodes),
+      edges: data.edges,
+      edgesByFrom: new Map,
+      edgesByTo: new Map,
+      fileNodes: new Map,
+      symbolNodesByFile: new Map,
+      changedSymbolsByFile: new Map,
+      persistCoverage: data.coverage
+    };
+    rebuildIndexes(graph);
+    return {
+      signature: data.signature,
+      fileSignatures: new Map(data.fileSignatures ?? []),
+      fileHashes: new Map(data.fileHashes ?? []),
+      graph,
+      ...stampedHead ? { stampedHead } : {}
+    };
+  } catch {
+    return null;
+  }
+}
+function getPersistedReviewGraphVersion(cwd) {
+  const cacheDir = path.join(getProjectDataDir(cwd), "cache");
+  const cachePath = path.join(cacheDir, GRAPH_CACHE_FILENAME);
+  const legacyPath = path.join(cacheDir, LEGACY_GRAPH_CACHE_FILENAME);
+  if (fs.existsSync(cachePath)) {
+    let fd;
+    try {
+      fd = fs.openSync(cachePath, "r");
+      const compressed = Buffer.alloc(4096);
+      const n = fs.readSync(fd, compressed, 0, compressed.length, 0);
+      const head = gunzipSync(compressed.subarray(0, n), {
+        finishFlush: zlibConstants.Z_SYNC_FLUSH
+      }).toString("utf-8");
+      const match = head.match(/"version"\s*:\s*"([^"]+)"/);
+      return match ? match[1] : null;
+    } catch {
+      return null;
+    } finally {
+      if (fd !== undefined) {
+        try {
+          fs.closeSync(fd);
+        } catch {}
+      }
+    }
+  }
+  let fd;
+  try {
+    fd = fs.openSync(legacyPath, "r");
+    const buf = Buffer.alloc(200);
+    const n = fs.readSync(fd, buf, 0, 200, 0);
+    const match = buf.toString("utf-8", 0, n).match(/"version"\s*:\s*"([^"]+)"/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {}
+    }
+  }
+}
+export function isReviewGraphMigrationNeeded(cwd) {
+  const version = getPersistedReviewGraphVersion(cwd);
+  return version !== null && version !== REVIEW_GRAPH_VERSION;
+}
+const GRAPH_PERSIST_DEBOUNCE_MS_DEFAULT = 1500;
+export const GRAPH_PERSIST_MAX_ELEMENTS_DEFAULT = 500000;
+function graphPersistDebounceMs() {
+  const raw = Number(process.env.DM_LENS_GRAPH_PERSIST_DEBOUNCE_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : GRAPH_PERSIST_DEBOUNCE_MS_DEFAULT;
+}
+function graphPersistMaxElements() {
+  const raw = Number(process.env.DM_LENS_GRAPH_PERSIST_MAX_ELEMENTS);
+  return Number.isFinite(raw) && raw > 0 ? raw : GRAPH_PERSIST_MAX_ELEMENTS_DEFAULT;
+}
+const _pendingPersist = new Map;
+const _persistTimers = new Map;
+const _persistGenerations = new Map;
+const _workerRequests = new Map;
+let _persistWorker;
+let _persistWorkerRequestId = 0;
+let _persistAttemptId = 0;
+let _workerDisabled = false;
+let _persistWorkerUnavailableReason;
+let _lastWorkerFallbackReasonForTests;
+const _checkpointGenerations = new Map;
+const _checkpointWorkerRequests = new Map;
+let _checkpointOffloadCountForTests = 0;
+function persistedData(pending) {
+  return {
+    version: pending.graph.version,
+    builtAt: pending.graph.builtAt,
+    signature: pending.signature,
+    fileSignatures: Array.from(pending.fileSignatures.entries()),
+    fileHashes: pending.fileHashes ? Array.from(pending.fileHashes.entries()) : undefined,
+    nodes: Array.from(pending.graph.nodes.entries()),
+    edges: pending.graph.edges,
+    coverage: stripProcessLocalCoverage(pending.graph.persistCoverage),
+    gitStamp: pending.gitStamp
+  };
+}
+function stripProcessLocalCoverage(coverage) {
+  if (!coverage?.capTrimmed)
+    return coverage;
+  const { capTrimmed: _capTrimmed, ...persisted } = coverage;
+  return persisted;
+}
+function countRetainedSourceFiles(graph, sourceFilePaths) {
+  if (sourceFilePaths === undefined)
+    return graph.fileNodes.size;
+  const sourceKeys = new Set(sourceFilePaths);
+  let retained = 0;
+  for (const filePath of sourceKeys) {
+    if (graph.fileNodes.has(filePath))
+      retained++;
+  }
+  return retained;
+}
+function graphCoverage(graph, cap, sourceFileCount = graph.persistCoverage?.totalFiles ?? graph.fileNodes.size, sourceFilesTruncated = graph.persistCoverage?.sourceFilesTruncated === true, sourceFilePaths) {
+  const inherited = graph.persistCoverage;
+  return {
+    partial: inherited?.partial === true || sourceFilesTruncated,
+    cap,
+    totalNodes: graph.nodes.size,
+    totalEdges: graph.edges.length,
+    persistedNodes: graph.nodes.size,
+    persistedEdges: graph.edges.length,
+    totalFiles: sourceFileCount,
+    persistedFiles: countRetainedSourceFiles(graph, sourceFilePaths),
+    ...sourceFilesTruncated ? { sourceFilesTruncated: true } : {},
+    ...inherited?.inProgress ? { inProgress: true } : {}
+  };
+}
+function capGraphForPersist(cwd, graph, cap, options = {}) {
+  const totalElements = graph.nodes.size + graph.edges.length;
+  const nodeBudget = Math.max(1, Math.floor(cap * graph.nodes.size / totalElements));
+  const reverseDeps = buildReverseDependencyIndexFromGraph({ cwd, graph });
+  const rankedFiles = rankFilesByReverseDependencyCentrality(reverseDeps);
+  const indexNodesByFile = (fold) => {
+    const byFile = new Map;
+    for (const [id, node] of graph.nodes) {
+      if (!node.filePath)
+        continue;
+      const fileKey = fold ? normalizeMapKey(node.filePath) : node.filePath;
+      const ids = byFile.get(fileKey) ?? [];
+      ids.push(id);
+      byFile.set(fileKey, ids);
+    }
+    return byFile;
+  };
+  const reachableNodes = (byFile) => {
+    let reached = 0;
+    for (const filePath of rankedFiles)
+      reached += byFile.get(filePath)?.length ?? 0;
+    return reached;
+  };
+  let placeableNodes = 0;
+  for (const node of graph.nodes.values())
+    if (node.filePath)
+      placeableNodes++;
+  let nodeIdsByFile = indexNodesByFile(false);
+  if (reachableNodes(nodeIdsByFile) < placeableNodes) {
+    const folded = indexNodesByFile(true);
+    if (reachableNodes(folded) > reachableNodes(nodeIdsByFile)) {
+      nodeIdsByFile = folded;
+    }
+  }
+  const keptIds = new Set;
+  for (const filePath of rankedFiles) {
+    const ids = nodeIdsByFile.get(filePath) ?? [];
+    if (ids.length === 0)
+      continue;
+    const effectiveNodeBudget = keptIds.size === 0 ? Math.max(nodeBudget, Math.min(cap, ids.length)) : nodeBudget;
+    if (keptIds.size + ids.length > effectiveNodeBudget)
+      continue;
+    for (const id of ids)
+      keptIds.add(id);
+  }
+  const nodes = new Map([...graph.nodes].filter(([id]) => keptIds.has(id)));
+  const edgeBudget = Math.max(0, cap - nodes.size);
+  const edges = graph.edges.filter((edge) => keptIds.has(edge.from) && keptIds.has(edge.to)).slice(0, edgeBudget);
+  const coverage = {
+    partial: true,
+    cap,
+    totalNodes: graph.nodes.size,
+    totalEdges: graph.edges.length,
+    persistedNodes: nodes.size,
+    persistedEdges: edges.length,
+    totalFiles: options.sourceFileCount ?? graph.persistCoverage?.totalFiles ?? graph.fileNodes.size,
+    persistedFiles: 0,
+    ...options.sourceFilesTruncated || graph.persistCoverage?.sourceFilesTruncated ? { sourceFilesTruncated: true } : {},
+    ...graph.persistCoverage?.inProgress ? { inProgress: true } : {}
+  };
+  const capped = {
+    ...graph,
+    nodes,
+    edges,
+    edgesByFrom: new Map,
+    edgesByTo: new Map,
+    fileNodes: new Map,
+    symbolNodesByFile: new Map,
+    changedSymbolsByFile: new Map,
+    persistCoverage: undefined
+  };
+  rebuildIndexes(capped);
+  coverage.persistedFiles = countRetainedSourceFiles(capped, options.sourceFilePaths);
+  capped.persistCoverage = coverage;
+  return capped;
+}
+function persistObservability(pending, patch) {
+  return {
+    graph: pending.graphMetadata,
+    persistence: { ...pending.persistenceMetadata, ...patch }
+  };
+}
+function logPersistSuccess(key, pending, stats, workerState = { started: false, completed: false }) {
+  logLatency({
+    type: "phase",
+    phase: "review_graph_persist",
+    filePath: pending.cachePath,
+    durationMs: stats.durationMs,
+    metadata: { elements: pending.elementCount, ...stats }
+  });
+  logReviewGraph({
+    cwd: key,
+    phase: "persist_succeeded",
+    elements: pending.elementCount,
+    ...stats,
+    durationMs: stats.durationMs,
+    observability: persistObservability(pending, {
+      status: "succeeded",
+      workerStarted: workerState.started,
+      workerCompleted: workerState.completed,
+      ...workerState.fallback ? { workerFallback: true } : {}
+    })
+  });
+}
+function writePendingOnMainThread(key, pending, reason, workerState = { started: false, completed: false }) {
+  const persistStarted = performance.now();
+  const serializeStarted = performance.now();
+  try {
+    const json = JSON.stringify(persistedData(pending));
+    const serializeMs = performance.now() - serializeStarted;
+    const rawBytes = Buffer.byteLength(json);
+    const writeStarted = performance.now();
+    const gzip = gzipSync(json);
+    fs.mkdirSync(pending.cacheDir, { recursive: true });
+    writeFileAtomic(pending.cachePath, gzip, { bestEffort: false });
+    fs.rmSync(path.join(pending.cacheDir, LEGACY_GRAPH_CACHE_FILENAME), {
+      force: true
+    });
+    logPersistSuccess(key, pending, {
+      rawBytes,
+      gzBytes: gzip.byteLength,
+      serializeMs,
+      writeMs: performance.now() - writeStarted,
+      durationMs: performance.now() - persistStarted,
+      offloaded: false
+    }, {
+      started: workerState.started,
+      completed: workerState.completed,
+      fallback: Boolean(reason)
+    });
+    if (reason) {
+      _lastWorkerFallbackReasonForTests = reason;
+      logReviewGraph({
+        cwd: key,
+        phase: "worker_fallback",
+        reason: "worker_fallback",
+        error: reason,
+        offloaded: false,
+        observability: persistObservability(pending, {
+          status: "fallback",
+          workerStarted: workerState.started,
+          workerCompleted: workerState.completed,
+          workerFallback: true,
+          reason: workerState.fallbackReason ?? "worker_fallback"
+        })
+      });
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    recordPersistFailure(key, "cache_write_failed", message, pending, workerState);
+  }
+}
+function handleWorkerResult(result) {
+  const checkpoint = _checkpointWorkerRequests.get(result.id);
+  if (checkpoint) {
+    handleCheckpointWorkerResult(checkpoint, result);
+    return;
+  }
+  const request = _workerRequests.get(result.id);
+  if (!request) {
+    fs.rm(result.stagePath, { force: true }, () => {});
+    return;
+  }
+  _workerRequests.delete(result.id);
+  const { key, pending } = request;
+  const currentGeneration = _persistGenerations.get(key);
+  if (currentGeneration !== result.generation) {
+    try {
+      fs.rmSync(result.stagePath, { force: true });
+    } catch (reapErr) {
+      logReviewGraph({
+        cwd: key,
+        phase: "persist_failed",
+        reason: `superseded-stage reap failed: ${String(reapErr)}`
+      });
+    }
+    logReviewGraph({
+      cwd: key,
+      phase: "persist_skipped",
+      reason: "superseded",
+      observability: persistObservability(pending, {
+        status: "superseded",
+        supersededByGeneration: currentGeneration,
+        reason: "newer_generation_scheduled",
+        workerStarted: true,
+        workerCompleted: true
+      })
+    });
+    return;
+  }
+  if (result.error || result.rawBytes === undefined || result.gzBytes === undefined || result.serializeMs === undefined || result.writeMs === undefined || result.durationMs === undefined) {
+    fs.rm(result.stagePath, { force: true }, () => {});
+    writePendingOnMainThread(key, pending, result.error ?? "invalid worker result", {
+      started: true,
+      completed: true,
+      fallbackReason: result.error ? "worker_error" : "invalid_worker_result"
+    });
+    return;
+  }
+  try {
+    fs.renameSync(result.stagePath, pending.cachePath);
+    fs.rmSync(path.join(pending.cacheDir, LEGACY_GRAPH_CACHE_FILENAME), {
+      force: true
+    });
+    logPersistSuccess(key, pending, {
+      rawBytes: result.rawBytes,
+      gzBytes: result.gzBytes,
+      serializeMs: result.serializeMs,
+      writeMs: result.writeMs,
+      durationMs: result.durationMs,
+      offloaded: true
+    }, { started: true, completed: true });
+  } catch (err) {
+    fs.rm(result.stagePath, { force: true }, () => {});
+    writePendingOnMainThread(key, pending, err instanceof Error ? err.message : String(err), {
+      started: true,
+      completed: true,
+      fallbackReason: "promotion_failed"
+    });
+  }
+}
+function handleCheckpointWorkerResult(cp, result) {
+  _checkpointWorkerRequests.delete(result.id);
+  if (result.error || result.gzBytes === undefined) {
+    logReviewGraph({
+      cwd: cp.cwd,
+      phase: "checkpoint_write_failed",
+      reason: "worker_error",
+      error: result.error ?? "worker returned no gz metrics"
+    });
+    fs.rm(result.stagePath, { force: true }, () => {});
+    return;
+  }
+  if (_checkpointGenerations.get(cp.cwd) !== cp.generation) {
+    fs.rm(result.stagePath, { force: true }, () => {});
+    return;
+  }
+  try {
+    fs.renameSync(result.stagePath, cp.checkpointPath);
+    logReviewGraph({
+      cwd: cp.cwd,
+      phase: "checkpoint_written",
+      nodes: cp.nodes,
+      edges: cp.edges,
+      processed: cp.processed,
+      target: cp.target,
+      offloaded: true
+    });
+  } catch (err) {
+    logReviewGraph({
+      cwd: cp.cwd,
+      phase: "checkpoint_write_failed",
+      reason: "promote_failed",
+      error: err instanceof Error ? err.message : String(err)
+    });
+    fs.rm(result.stagePath, { force: true }, () => {});
+  }
+}
+function handleWorkerDeath(reason) {
+  _persistWorkerUnavailableReason = reason;
+  _persistWorker = undefined;
+  _workerDisabled = true;
+  const requests = [..._workerRequests.values()];
+  _workerRequests.clear();
+  for (const { key, pending } of requests) {
+    if (_persistGenerations.get(key) !== pending.generation) {
+      logReviewGraph({
+        cwd: key,
+        phase: "persist_skipped",
+        reason: "superseded",
+        observability: persistObservability(pending, {
+          status: "superseded",
+          supersededByGeneration: _persistGenerations.get(key),
+          reason: "worker_death_after_newer_generation",
+          workerStarted: true,
+          workerCompleted: false
+        })
+      });
+      continue;
+    }
+    writePendingOnMainThread(key, pending, reason, {
+      started: true,
+      completed: false,
+      fallbackReason: "worker_death"
+    });
+  }
+  const checkpoints = [..._checkpointWorkerRequests.values()];
+  _checkpointWorkerRequests.clear();
+  for (const cp of checkpoints) {
+    logReviewGraph({
+      cwd: cp.cwd,
+      phase: "checkpoint_write_failed",
+      reason: "worker_death",
+      error: reason
+    });
+    fs.rm(cp.stagePath, { force: true }, () => {});
+  }
+}
+function resolvePersistWorkerPath() {
+  const candidates = [
+    new URL("./persist-worker.js", import.meta.url),
+    new URL("./clients/review-graph/persist-worker.js", import.meta.url)
+  ];
+  for (const url of candidates) {
+    try {
+      const resolved = fileURLToPath(url);
+      if (fs.existsSync(resolved))
+        return resolved;
+    } catch {}
+  }
+  return;
+}
+function getPersistWorker() {
+  if (_workerDisabled)
+    return;
+  if (_persistWorker)
+    return _persistWorker;
+  try {
+    const workerPath = resolvePersistWorkerPath();
+    if (workerPath === undefined) {
+      handleWorkerDeath("persist worker script not found in any layout");
+      return;
+    }
+    const worker = new Worker(workerPath);
+    worker.on("message", handleWorkerResult);
+    worker.on("error", (err) => handleWorkerDeath(err.message));
+    worker.on("exit", (code) => {
+      if (_persistWorker !== worker)
+        return;
+      const hasPendingRequests = _workerRequests.size > 0 || _checkpointWorkerRequests.size > 0;
+      if (code !== 0 || hasPendingRequests) {
+        handleWorkerDeath(code !== 0 ? `persist worker exited with code ${code}` : "persist worker exited with pending requests");
+      } else {
+        _persistWorker = undefined;
+      }
+    });
+    worker.unref();
+    _persistWorker = worker;
+    return worker;
+  } catch (err) {
+    handleWorkerDeath(err instanceof Error ? err.message : String(err));
+    return;
+  }
+}
+function writePending(key) {
+  const pending = _pendingPersist.get(key);
+  if (!pending)
+    return;
+  _pendingPersist.delete(key);
+  const timer = _persistTimers.get(key);
+  if (timer) {
+    clearTimeout(timer);
+    _persistTimers.delete(key);
+  }
+  const worker = getPersistWorker();
+  if (!worker) {
+    const unavailableReason = _persistWorkerUnavailableReason ?? "persist worker unavailable";
+    writePendingOnMainThread(key, pending, unavailableReason, {
+      started: false,
+      completed: false,
+      fallbackReason: unavailableReason
+    });
+    return;
+  }
+  const id = ++_persistWorkerRequestId;
+  const stagePath = `${pending.cachePath}.stage-${process.pid}-${pending.generation}`;
+  const request = {
+    id,
+    cwd: key,
+    generation: pending.generation,
+    stagePath,
+    data: persistedData(pending),
+    elements: pending.elementCount,
+    testDelayMs: undefined
+  };
+  _workerRequests.set(id, { key, pending });
+  worker.postMessage(request);
+}
+let _persistExitHookInstalled = false;
+function flushPendingReviewGraphPersistsAtExit() {
+  const keys = new Set([
+    ..._pendingPersist.keys(),
+    ...[..._workerRequests.values()].map((request) => request.key)
+  ]);
+  for (const key of keys) {
+    flushReviewGraphPersist(key, "exit_hook");
+  }
+  flushReviewGraphLogSync();
+  _persistWorker?.terminate();
+}
+export function flushReviewGraphPersistsForExitForTests() {
+  flushPendingReviewGraphPersistsAtExit();
+}
+function ensurePersistExitHook() {
+  if (_persistExitHookInstalled)
+    return;
+  _persistExitHookInstalled = true;
+  process.once("exit", flushPendingReviewGraphPersistsAtExit);
+}
+const _sweptStageDirs = new Set;
+const REVIEW_GRAPH_ARTIFACT_PREFIX = "review-graph.";
+const STAGE_PID_PATTERN = /\.stage-(\d+)-/;
+function isStaleReviewGraphStageFile(entry) {
+  if (!entry.startsWith(REVIEW_GRAPH_ARTIFACT_PREFIX))
+    return false;
+  const match = STAGE_PID_PATTERN.exec(entry);
+  if (!match)
+    return false;
+  const pid = Number(match[1]);
+  if (pid === process.pid)
+    return false;
+  return !realIsPidAlive(pid);
+}
+function sweepStaleStageFiles(cacheDir) {
+  if (_sweptStageDirs.has(cacheDir))
+    return;
+  _sweptStageDirs.add(cacheDir);
+  fs.readdir(cacheDir, (err, entries) => {
+    if (err)
+      return;
+    for (const entry of entries) {
+      if (!isStaleReviewGraphStageFile(entry))
+        continue;
+      fs.rm(path.join(cacheDir, entry), { force: true }, () => {});
+    }
+  });
+}
+export function _resetReviewGraphStageSweepForTests() {
+  _sweptStageDirs.clear();
+}
+function persistGraph(cwd, signature, fileSignatures, fileHashes, graph, options = {}) {
+  const totalElementCount = graph.nodes.size + graph.edges.length;
+  const cap = graphPersistMaxElements();
+  const sourceFileCount = options.sourceFileCount ?? fileSignatures.size;
+  const sourceFilePaths = options.sourceFilePaths ?? fileSignatures.keys();
+  const persistedGraph = totalElementCount > cap ? capGraphForPersist(cwd, graph, cap, {
+    sourceFileCount,
+    sourceFilesTruncated: options.sourceFilesTruncated,
+    sourceFilePaths
+  }) : {
+    ...graph,
+    persistCoverage: graphCoverage(graph, cap, sourceFileCount, options.sourceFilesTruncated, sourceFilePaths)
+  };
+  const elementCount = persistedGraph.nodes.size + persistedGraph.edges.length;
+  const sourceWalkPartial = persistedGraph.persistCoverage?.sourceFilesTruncated === true;
+  let persistReason;
+  if (totalElementCount > cap) {
+    const coverage = persistedGraph.persistCoverage;
+    if (!coverage)
+      return;
+    logLatency({
+      type: "phase",
+      phase: "review_graph_persist",
+      filePath: cwd,
+      durationMs: 0,
+      metadata: {
+        partial: true,
+        totalElements: totalElementCount,
+        persistedElements: elementCount,
+        cap
+      }
+    });
+    persistReason = `persisted partial review graph (${elementCount}/${totalElementCount} elements; ` + `${coverage.persistedNodes}/${coverage.totalNodes} nodes, ` + `${coverage.persistedEdges}/${coverage.totalEdges} edges; ${cap} cap)`;
+  } else if (sourceWalkPartial) {
+    persistReason = "persisted partial review graph (source walk entry budget)";
+  }
+  const cacheDir = path.join(getProjectDataDir(cwd), "cache");
+  const cachePath = path.join(cacheDir, GRAPH_CACHE_FILENAME);
+  sweepStaleStageFiles(cacheDir);
+  const gitStamp = resolveGitIdentity(cwd);
+  const key = normalizeMapKey(cwd);
+  const priorGeneration = _persistGenerations.get(key);
+  const existingPending = _pendingPersist.get(key);
+  const existingTimer = _persistTimers.get(key);
+  const generation = (priorGeneration ?? 0) + 1;
+  const attemptId = ++_persistAttemptId;
+  const coalesced = Boolean(existingPending || existingTimer);
+  _persistGenerations.set(key, generation);
+  const graphMetadata = graphLogMetadata(persistedGraph, {
+    ...options,
+    sourceFileCount,
+    sourceFileCountTruncated: persistedGraph.persistCoverage?.sourceFilesTruncated === true
+  });
+  const persistenceMetadata = {
+    generation,
+    attemptId,
+    status: "scheduled",
+    ...priorGeneration === undefined ? {} : {
+      supersededGeneration: priorGeneration,
+      coalesced,
+      reason: coalesced ? "debounced_coalescing" : "in_flight_supersession"
+    }
+  };
+  const pending = {
+    cacheDir,
+    cachePath,
+    signature,
+    fileSignatures,
+    fileHashes,
+    graph: persistedGraph,
+    gitStamp,
+    elementCount,
+    generation,
+    attemptId,
+    graphMetadata,
+    persistenceMetadata
+  };
+  if (existingPending) {
+    logReviewGraph({
+      cwd: key,
+      phase: "persist_skipped",
+      reason: "superseded",
+      observability: persistObservability(existingPending, {
+        status: "superseded",
+        supersededByGeneration: generation,
+        reason: "newer_generation_scheduled",
+        workerStarted: false,
+        workerCompleted: false
+      })
+    });
+  }
+  _pendingPersist.set(key, pending);
+  if (totalElementCount > cap || sourceWalkPartial) {
+    logReviewGraph({
+      cwd,
+      phase: "persist_partial",
+      reason: totalElementCount > cap ? "element_cap_exceeded" : "source_walk_entry_budget",
+      elements: totalElementCount,
+      persistedElements: elementCount,
+      cap,
+      observability: {
+        graph: graphMetadata,
+        persistence: persistenceMetadata
+      }
+    });
+  }
+  logReviewGraph({
+    cwd,
+    phase: "persist_scheduled",
+    elements: elementCount,
+    cap,
+    observability: {
+      graph: graphMetadata,
+      persistence: persistenceMetadata
+    }
+  });
+  ensurePersistExitHook();
+  const debounce = graphPersistDebounceMs();
+  const existing = _persistTimers.get(key);
+  if (existing)
+    clearTimeout(existing);
+  if (debounce === 0) {
+    writePending(key);
+    return persistReason;
+  }
+  const timer = setTimeout(() => writePending(key), debounce);
+  if (typeof timer.unref === "function")
+    timer.unref();
+  _persistTimers.set(key, timer);
+  return persistReason;
+}
+const GRAPH_CHECKPOINT_EVERY_FILES_DEFAULT = 250;
+const GRAPH_CHECKPOINT_MIN_INTERVAL_MS_DEFAULT = 5000;
+function graphCheckpointEveryFiles() {
+  const raw = Number(process.env.DM_LENS_GRAPH_CHECKPOINT_EVERY_FILES);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : GRAPH_CHECKPOINT_EVERY_FILES_DEFAULT;
+}
+function graphCheckpointMinIntervalMs() {
+  const raw = Number(process.env.DM_LENS_GRAPH_CHECKPOINT_MIN_INTERVAL_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : GRAPH_CHECKPOINT_MIN_INTERVAL_MS_DEFAULT;
+}
+function reviewGraphCheckpointPath(cwd) {
+  return path.join(getProjectDataDir(cwd), "cache", GRAPH_CHECKPOINT_FILENAME);
+}
+function hashIgnoredIds(ignoredIds) {
+  if (ignoredIds === undefined)
+    return "unavailable";
+  const joined = [...ignoredIds].sort((a, b) => compareOrdinal(a, b)).join("\x00");
+  return createHash("sha256").update(joined).digest("hex");
+}
+function buildReviewGraphCheckpointData(cwd, graph, processedHashes, targetFileCount, ignoredIds) {
+  return {
+    version: REVIEW_GRAPH_VERSION,
+    builtAt: new Date().toISOString(),
+    inProgress: true,
+    targetFileCount,
+    processedFiles: Array.from(processedHashes.entries()),
+    ignoredIdsHash: hashIgnoredIds(ignoredIds),
+    nodes: Array.from(graph.nodes.entries()),
+    edges: graph.edges,
+    gitStamp: resolveGitIdentity(cwd)
+  };
+}
+function writeReviewGraphCheckpoint(cwd, graph, processedHashes, targetFileCount, ignoredIds) {
+  const generation = (_checkpointGenerations.get(cwd) ?? 0) + 1;
+  _checkpointGenerations.set(cwd, generation);
+  let data;
+  try {
+    data = buildReviewGraphCheckpointData(cwd, graph, processedHashes, targetFileCount, ignoredIds);
+  } catch {
+    return;
+  }
+  const worker = _workerDisabled ? undefined : getPersistWorker();
+  if (!worker) {
+    writeReviewGraphCheckpointSync(cwd, data, {
+      nodes: graph.nodes.size,
+      edges: graph.edges.length,
+      processed: processedHashes.size,
+      target: targetFileCount
+    });
+    return;
+  }
+  const checkpointPath = reviewGraphCheckpointPath(cwd);
+  const cacheDir = path.dirname(checkpointPath);
+  try {
+    fs.mkdirSync(cacheDir, { recursive: true });
+  } catch (err) {
+    logReviewGraph({
+      cwd,
+      phase: "checkpoint_write_failed",
+      reason: "mkdir_failed",
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return;
+  }
+  sweepStaleStageFiles(cacheDir);
+  ensurePersistExitHook();
+  const id = ++_persistWorkerRequestId;
+  const stagePath = `${checkpointPath}.stage-${process.pid}-${generation}`;
+  _checkpointWorkerRequests.set(id, {
+    cwd,
+    generation,
+    checkpointPath,
+    stagePath,
+    nodes: graph.nodes.size,
+    edges: graph.edges.length,
+    processed: processedHashes.size,
+    target: targetFileCount
+  });
+  const request = {
+    id,
+    cwd,
+    generation,
+    stagePath,
+    data,
+    elements: graph.nodes.size + graph.edges.length,
+    testDelayMs: undefined
+  };
+  worker.postMessage(request);
+  _checkpointOffloadCountForTests++;
+}
+function writeReviewGraphCheckpointSync(cwd, data, counts) {
+  try {
+    const gzip = gzipSync(JSON.stringify(data));
+    fs.mkdirSync(path.dirname(reviewGraphCheckpointPath(cwd)), {
+      recursive: true
+    });
+    writeFileAtomic(reviewGraphCheckpointPath(cwd), gzip, { bestEffort: true });
+    logReviewGraph({
+      cwd,
+      phase: "checkpoint_written",
+      nodes: counts.nodes,
+      edges: counts.edges,
+      processed: counts.processed,
+      target: counts.target
+    });
+  } catch (err) {
+    logReviewGraph({
+      cwd,
+      phase: "checkpoint_write_failed",
+      reason: "sync_write_failed",
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function deleteReviewGraphCheckpoint(cwd) {
+  _checkpointGenerations.set(cwd, (_checkpointGenerations.get(cwd) ?? 0) + 1);
+  fs.rm(reviewGraphCheckpointPath(cwd), { force: true }, () => {});
+}
+function loadReviewGraphCheckpoint(cwd) {
+  const checkpointPath = reviewGraphCheckpointPath(cwd);
+  let data;
+  try {
+    if (!fs.existsSync(checkpointPath))
+      return null;
+    data = JSON.parse(gunzipSync(fs.readFileSync(checkpointPath)).toString("utf-8"));
+  } catch {
+    logReviewGraph({ cwd, phase: "checkpoint_discarded", reason: "corrupt" });
+    deleteReviewGraphCheckpoint(cwd);
+    return null;
+  }
+  if (data.version !== REVIEW_GRAPH_VERSION || data.inProgress !== true) {
+    logReviewGraph({
+      cwd,
+      phase: "checkpoint_discarded",
+      reason: data.version !== REVIEW_GRAPH_VERSION ? "version_mismatch" : "not_in_progress"
+    });
+    deleteReviewGraphCheckpoint(cwd);
+    return null;
+  }
+  if (data.gitStamp) {
+    const current = resolveGitIdentity(cwd);
+    if (current && current.worktreeRoot !== data.gitStamp.worktreeRoot) {
+      logReviewGraph({
+        cwd,
+        phase: "checkpoint_discarded",
+        reason: "worktree_mismatch"
+      });
+      deleteReviewGraphCheckpoint(cwd);
+      return null;
+    }
+  }
+  const totalNodes = data.nodes.length;
+  const totalEdges = data.edges.length;
+  const graph = {
+    version: data.version,
+    builtAt: data.builtAt,
+    nodes: new Map(data.nodes),
+    edges: data.edges,
+    edgesByFrom: new Map,
+    edgesByTo: new Map,
+    fileNodes: new Map,
+    symbolNodesByFile: new Map,
+    changedSymbolsByFile: new Map,
+    persistCoverage: {
+      partial: true,
+      inProgress: true,
+      cap: 0,
+      totalNodes,
+      totalEdges,
+      persistedNodes: totalNodes,
+      persistedEdges: totalEdges,
+      totalFiles: data.targetFileCount,
+      persistedFiles: 0
+    }
+  };
+  rebuildIndexes(graph);
+  if (graph.persistCoverage) {
+    graph.persistCoverage.persistedFiles = countRetainedSourceFiles(graph, data.processedFiles.map(([filePath]) => filePath));
+  }
+  return {
+    graph,
+    processedHashes: new Map(data.processedFiles),
+    ignoredIdsHash: data.ignoredIdsHash,
+    targetFileCount: data.targetFileCount
+  };
+}
+function pruneOrphanNonFileNodes(graph) {
+  const referenced = new Set;
+  for (const edge of graph.edges) {
+    referenced.add(edge.from);
+    referenced.add(edge.to);
+  }
+  for (const [id, node] of graph.nodes) {
+    if (!node.filePath && !referenced.has(id))
+      graph.nodes.delete(id);
+  }
+}
+async function tryResumeFromCheckpoint(cwd, filesToBuild, ignoredIds) {
+  const loaded = loadReviewGraphCheckpoint(cwd);
+  if (!loaded)
+    return null;
+  if (loaded.ignoredIdsHash !== hashIgnoredIds(ignoredIds)) {
+    logReviewGraph({
+      cwd,
+      phase: "checkpoint_discarded",
+      reason: "ignored_ids_mismatch",
+      processed: loaded.processedHashes.size,
+      target: filesToBuild.length
+    });
+    deleteReviewGraphCheckpoint(cwd);
+    return null;
+  }
+  const targetSet = new Set(filesToBuild);
+  for (const file of loaded.processedHashes.keys()) {
+    if (!targetSet.has(file)) {
+      logReviewGraph({
+        cwd,
+        phase: "checkpoint_discarded",
+        reason: "removed_file",
+        processed: loaded.processedHashes.size,
+        target: filesToBuild.length
+      });
+      deleteReviewGraphCheckpoint(cwd);
+      return null;
+    }
+  }
+  const reusableHashes = new Map;
+  const stale = [];
+  let sinceYield = 0;
+  for (const [file, priorHash] of loaded.processedHashes) {
+    const currentHash = contentHashEntry(file);
+    if (currentHash === priorHash)
+      reusableHashes.set(file, currentHash);
+    else
+      stale.push(file);
+    if (++sinceYield >= STAT_YIELD_EVERY) {
+      sinceYield = 0;
+      await yieldToLoop();
+    }
+  }
+  if (reusableHashes.size === 0) {
+    logReviewGraph({
+      cwd,
+      phase: "checkpoint_discarded",
+      reason: "all_stale",
+      stale: stale.length,
+      target: filesToBuild.length
+    });
+    deleteReviewGraphCheckpoint(cwd);
+    return null;
+  }
+  const graph = loaded.graph;
+  const removedEdges = new Set;
+  for (const file of stale)
+    removeFileOwnedGraphData(graph, file, removedEdges);
+  if (removedEdges.size > 0) {
+    unindexEdges(graph, removedEdges);
+    graph.edges = graph.edges.filter((edge) => !removedEdges.has(edge));
+  }
+  pruneOrphanNonFileNodes(graph);
+  graph.changedSymbolsByFile = new Map;
+  const remaining = filesToBuild.filter((file) => !reusableHashes.has(file));
+  logReviewGraph({
+    cwd,
+    phase: "checkpoint_resumed",
+    reused: reusableHashes.size,
+    stale: stale.length,
+    remaining: remaining.length,
+    target: filesToBuild.length
+  });
+  return { graph, fileHashes: reusableHashes, remaining };
+}
+export function _readReviewGraphCheckpointForTests(cwd) {
+  const loaded = loadReviewGraphCheckpoint(cwd);
+  if (!loaded)
+    return null;
+  return {
+    inProgress: loaded.graph.persistCoverage?.inProgress === true,
+    processedFiles: [...loaded.processedHashes.keys()],
+    nodeCount: loaded.graph.nodes.size,
+    edgeCount: loaded.graph.edges.length,
+    persistCoverage: loaded.graph.persistCoverage
+  };
+}
+export function flushReviewGraphPersistsForTests() {
+  for (const key of _pendingPersist.keys()) {
+    const pending = _pendingPersist.get(key);
+    if (!pending)
+      continue;
+    _pendingPersist.delete(key);
+    const timer = _persistTimers.get(key);
+    if (timer)
+      clearTimeout(timer);
+    _persistTimers.delete(key);
+    writePendingOnMainThread(key, pending);
+  }
+}
+export async function waitForReviewGraphPersistsForTests() {
+  for (let attempts = 0;attempts < 200 && (_workerRequests.size > 0 || _checkpointWorkerRequests.size > 0); attempts++) {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+export async function terminateReviewGraphPersistWorkerForTests() {
+  const worker = _persistWorker;
+  if (worker)
+    await worker.terminate();
+}
+export function resetReviewGraphPersistWorkerForTests() {
+  _workerDisabled = false;
+  _persistWorker = undefined;
+  _persistWorkerUnavailableReason = undefined;
+  _lastWorkerFallbackReasonForTests = undefined;
+  _checkpointWorkerRequests.clear();
+  _checkpointGenerations.clear();
+  _checkpointOffloadCountForTests = 0;
+}
+export function getCheckpointOffloadCountForTests() {
+  return _checkpointOffloadCountForTests;
+}
+export function getReviewGraphWorkerFallbackReasonForTests() {
+  return _lastWorkerFallbackReasonForTests;
+}
+export function reviewGraphCachePath(cwd) {
+  return path.join(getProjectDataDir(cwd), "cache", GRAPH_CACHE_FILENAME);
+}
+export function flushReviewGraphPersist(cwd, source = "cli") {
+  const key = normalizeMapKey(cwd);
+  let pending = _pendingPersist.get(key);
+  const removedWorkerRequests = [];
+  let selectedWorkerRequest;
+  for (const [id, request] of _workerRequests) {
+    if (request.key !== key)
+      continue;
+    _workerRequests.delete(id);
+    removedWorkerRequests.push(request.pending);
+    if (!pending || request.pending.generation > pending.generation) {
+      pending = request.pending;
+      selectedWorkerRequest = request.pending;
+    }
+  }
+  for (const removed of removedWorkerRequests) {
+    if (!pending || removed.generation === pending.generation)
+      continue;
+    logReviewGraph({
+      cwd: key,
+      phase: "persist_skipped",
+      reason: "superseded",
+      observability: persistObservability(removed, {
+        status: "superseded",
+        supersededByGeneration: pending.generation,
+        reason: "forced_flush_newest_generation",
+        workerStarted: true,
+        workerCompleted: false
+      })
+    });
+  }
+  if (!pending) {
+    return {
+      ok: false,
+      reason: "no graph snapshot was queued for persistence"
+    };
+  }
+  _persistGenerations.set(key, Math.max(_persistGenerations.get(key) ?? 0, pending.generation) + 1);
+  _pendingPersist.delete(key);
+  const timer = _persistTimers.get(key);
+  if (timer) {
+    clearTimeout(timer);
+    _persistTimers.delete(key);
+  }
+  const startedAt = performance.now();
+  try {
+    const serializeStarted = performance.now();
+    const json = JSON.stringify(persistedData(pending));
+    const serializeMs = performance.now() - serializeStarted;
+    const rawBytes = Buffer.byteLength(json);
+    const writeStarted = performance.now();
+    const gzip = gzipSync(json);
+    fs.mkdirSync(pending.cacheDir, { recursive: true });
+    writeFileAtomic(pending.cachePath, gzip, { bestEffort: false });
+    fs.rmSync(path.join(pending.cacheDir, LEGACY_GRAPH_CACHE_FILENAME), {
+      force: true
+    });
+    const writeMs = performance.now() - writeStarted;
+    logLatency({
+      type: "phase",
+      phase: "review_graph_persist",
+      filePath: pending.cachePath,
+      durationMs: performance.now() - startedAt,
+      metadata: {
+        elements: pending.elementCount,
+        rawBytes,
+        gzBytes: gzip.byteLength,
+        serializeMs,
+        writeMs,
+        offloaded: false
+      }
+    });
+    logReviewGraph({
+      cwd,
+      phase: "persist_succeeded",
+      durationMs: performance.now() - startedAt,
+      elements: pending.elementCount,
+      rawBytes,
+      gzBytes: gzip.byteLength,
+      serializeMs,
+      writeMs,
+      offloaded: false,
+      observability: persistObservability(pending, {
+        status: "succeeded",
+        reason: source === "exit_hook" ? "exit_flush" : "forced_flush",
+        workerStarted: selectedWorkerRequest !== undefined,
+        workerCompleted: false
+      })
+    });
+    return {
+      ok: true,
+      path: pending.cachePath,
+      bytes: gzip.byteLength,
+      elements: pending.elementCount,
+      coverage: pending.graph.persistCoverage
+    };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    recordPersistFailure(cwd, source === "exit_hook" ? "exit_flush_failed" : "forced_flush_failed", reason, pending, selectedWorkerRequest ? {
+      started: true,
+      completed: false,
+      fallbackReason: "forced_flush_write_failed"
+    } : undefined);
+    return { ok: false, reason };
+  }
+}
+function localImportToFile(cwd, filePath, source, ignoredIds) {
+  if (!source.startsWith(".")) {
+    const aliased = resolveAliasedImport(cwd, source, path.dirname(filePath));
+    const referenced = aliased.length ? [] : resolveProjectReferenceImport(cwd, source, path.dirname(filePath));
+    const resolved = aliased.length ? aliased : referenced.length ? referenced : resolveWorkspacePackageImport(cwd, source);
+    for (const normalized of resolved) {
+      if (ignoredIds?.has(normalized))
+        continue;
+      return normalized;
+    }
+    return;
+  }
+  const root = path.resolve(cwd);
+  for (const candidate of jsTsCandidatePaths(filePath, source)) {
+    const relative = path.relative(root, candidate);
+    if (relative.startsWith("..") && (relative.length === 2 || relative.startsWith(`..${path.sep}`)) || path.isAbsolute(relative) || !fs.existsSync(candidate))
+      continue;
+    const normalized = normalizeMapKey(candidate);
+    if (ignoredIds?.has(normalized))
+      continue;
+    return normalized;
+  }
+  return;
+}
+function upsertChangedSymbols(graph, facts, filePath) {
+  if (detectFileRole(filePath) === "test")
+    return;
+  const normalized = normalizeMapKey(filePath);
+  const changed = facts.getBoundedSessionFact(`${CHANGED_SYMBOLS_PREFIX}${normalized}`);
+  if (changed && changed.length > 0) {
+    graph.changedSymbolsByFile.set(normalized, [...changed]);
+  } else {
+    graph.changedSymbolsByFile.delete(normalized);
+  }
+}
+async function ensureReviewGraphFacts(filePath, cwd, facts, contentOverride) {
+  const ctx = makeCtx(filePath, cwd, facts);
+  if (contentOverride === undefined) {
+    await fileContentProvider.run(ctx, facts);
+  } else {
+    facts.setFileFact(filePath, "file.content", contentOverride);
+  }
+  try {
+    const [{ importFactProvider }, { functionFactProvider }] = await Promise.all([
+      import("../dispatch/facts/import-facts.js"),
+      import("../dispatch/facts/function-facts.js")
+    ]);
+    await importFactProvider.run(ctx, facts);
+    await functionFactProvider.run(ctx, facts);
+  } catch (err) {
+    logReviewGraph({
+      cwd,
+      phase: "build_skipped",
+      reason: "structural_facts_disabled",
+      error: err?.message ?? String(err)
+    });
+  }
+}
+function addJsTsFile(graph, cwd, filePath, facts, ignoredIds) {
+  const normalized = normalizeMapKey(filePath);
+  const hintPath = toProjectRelativePath(normalized, cwd);
+  const content = facts.getFileFact(normalized, "file.content") ?? "";
+  const fileNodeId = `file:${normalized}`;
+  const warmCallCoverage = facts.getFileFact(normalized, "file.functionFactsCoverage") ?? "unavailable";
+  const importCoverage = facts.getFileFact(normalized, "file.importFactsCoverage") ?? "unavailable";
+  addNode(graph, {
+    id: fileNodeId,
+    kind: "file",
+    language: "jsts",
+    filePath: normalized,
+    metadata: {
+      lineCount: content.split(`
+`).length,
+      extractionCoverage: {
+        definitions: warmCallCoverage,
+        references: warmCallCoverage,
+        imports: importCoverage,
+        calls: warmCallCoverage
+      },
+      ...featureHintMetadata(hintPath)
+    }
+  });
+  const imports = facts.getFileFact(normalized, "file.imports") ?? [];
+  const functions = facts.getFileFact(normalized, "file.functionSummaries") ?? [];
+  for (const entry of imports) {
+    const localFile = localImportToFile(cwd, normalized, entry.source, ignoredIds);
+    if (localFile) {
+      const targetId = `file:${localFile}`;
+      if (!graph.nodes.has(targetId)) {
+        addNode(graph, {
+          id: targetId,
+          kind: "file",
+          language: detectFileKind(localFile) ?? "jsts",
+          filePath: localFile
+        });
+      }
+      addEdge(graph, { from: fileNodeId, to: targetId, kind: "imports" });
+    } else {
+      const targetId = `${entry.source.startsWith(".") ? "module" : "external"}:${entry.source}`;
+      if (!graph.nodes.has(targetId)) {
+        addNode(graph, {
+          id: targetId,
+          kind: entry.source.startsWith(".") ? "module" : "external",
+          language: "jsts",
+          metadata: { source: entry.source }
+        });
+      }
+      addEdge(graph, { from: fileNodeId, to: targetId, kind: "imports" });
+    }
+  }
+  const importedNameToFile = new Map;
+  for (const entry of imports) {
+    const localFile = localImportToFile(cwd, normalized, entry.source, ignoredIds);
+    if (!localFile)
+      continue;
+    for (const name of entry.names)
+      importedNameToFile.set(name, localFile);
+    if (entry.defaultName)
+      importedNameToFile.set(entry.defaultName, localFile);
+  }
+  const methodsByQualifiedName = new Map;
+  for (const fn of functions) {
+    const symbolId = buildSymbolId(normalized, fn.name, "function", fn.line);
+    const qualifiedName = buildQualifiedName(fn.owner, fn.name);
+    if (qualifiedName) {
+      const existing = methodsByQualifiedName.get(qualifiedName) ?? [];
+      existing.push(symbolId);
+      methodsByQualifiedName.set(qualifiedName, existing);
+    }
+    addNode(graph, {
+      id: symbolId,
+      kind: "symbol",
+      language: "jsts",
+      filePath: normalized,
+      symbolName: fn.name,
+      symbolKind: "function",
+      ...qualifiedName ? { qualifiedName } : {},
+      exported: new RegExp(String.raw`export\s+(?:async\s+)?(?:function|const|let|var)\s+${escapeRegExp(fn.name)}\b`).test(content),
+      metadata: {
+        line: fn.line,
+        endLine: fn.endLine,
+        column: fn.column,
+        cyclomaticComplexity: fn.cyclomaticComplexity,
+        maxNestingDepth: fn.maxNestingDepth,
+        isBoundaryWrapper: fn.isBoundaryWrapper,
+        isPassThroughWrapper: fn.isPassThroughWrapper,
+        ...featureHintMetadata(`${fn.name} ${hintPath}`)
+      }
+    });
+    addEdge(graph, { from: fileNodeId, to: symbolId, kind: "contains" });
+    addEdge(graph, { from: fileNodeId, to: symbolId, kind: "defines" });
+  }
+  for (const fn of functions) {
+    const symbolId = buildSymbolId(normalized, fn.name, "function", fn.line);
+    const memberCallTexts = new Set;
+    for (const site of fn.memberCallSites ?? []) {
+      const callText = `${site.receiver}.${site.method}`;
+      memberCallTexts.add(callText);
+      const receiverClass = fn.receiverTypes?.[site.receiver];
+      const candidates = receiverClass ? methodsByQualifiedName.get(`${receiverClass}.${site.method}`) ?? [] : [];
+      if (candidates.length === 1) {
+        addEdge(graph, {
+          from: symbolId,
+          to: candidates[0],
+          kind: "calls",
+          metadata: {
+            unresolvedName: callText,
+            receiver: site.receiver,
+            receiverType: receiverClass
+          },
+          resolution: "receiver-type"
+        });
+        continue;
+      }
+      if (candidates.length > 1) {
+        const qualifiedPlaceholderId = `symbol-qualified-name:${receiverClass}.${site.method}`;
+        if (!graph.nodes.has(qualifiedPlaceholderId)) {
+          addNode(graph, {
+            id: qualifiedPlaceholderId,
+            kind: "symbol",
+            language: "jsts",
+            symbolName: site.method,
+            qualifiedName: `${receiverClass}.${site.method}`,
+            metadata: {
+              unresolvedName: callText,
+              ambiguousCandidates: candidates.length
+            }
+          });
+        }
+        addEdge(graph, {
+          from: symbolId,
+          to: qualifiedPlaceholderId,
+          kind: "calls",
+          metadata: {
+            unresolvedName: callText,
+            receiver: site.receiver,
+            receiverType: receiverClass
+          },
+          resolution: "name-only"
+        });
+        continue;
+      }
+      const externalId = `external:${callText}`;
+      if (!graph.nodes.has(externalId)) {
+        addNode(graph, {
+          id: externalId,
+          kind: "external",
+          language: "jsts",
+          metadata: { unresolvedName: callText }
+        });
+      }
+      addEdge(graph, {
+        from: symbolId,
+        to: externalId,
+        kind: "calls",
+        metadata: { unresolvedName: callText }
+      });
+    }
+    for (const callee of fn.outgoingCalls) {
+      if (memberCallTexts.has(callee))
+        continue;
+      const targetId = callee.includes(".") ? `external:${callee}` : `symbol-name:${callee}`;
+      if (!graph.nodes.has(targetId)) {
+        addNode(graph, {
+          id: targetId,
+          kind: callee.includes(".") ? "external" : "symbol",
+          language: "jsts",
+          symbolName: callee.includes(".") ? undefined : callee,
+          metadata: { unresolvedName: callee }
+        });
+      }
+      const importHintFile = !callee.includes(".") ? importedNameToFile.get(callee) : undefined;
+      addEdge(graph, {
+        from: symbolId,
+        to: targetId,
+        kind: "calls",
+        metadata: {
+          unresolvedName: callee,
+          ...importHintFile ? { importHintFile } : {}
+        },
+        ...callee.includes(".") ? {} : { resolution: "name-only" }
+      });
+    }
+  }
+}
+export function mapKindToTreeSitterLanguage(kind, filePath) {
+  return symbolExtractionGrammar(kind, filePath);
+}
+async function getExtractor(languageId) {
+  if (extractorCache.has(languageId))
+    return extractorCache.get(languageId);
+  const client = getSharedTreeSitterClient();
+  if (!client)
+    return null;
+  const extractor = new TreeSitterSymbolExtractor(languageId, client);
+  const ok = await extractor.init();
+  if (!ok) {
+    extractorCache.set(languageId, null);
+    return null;
+  }
+  extractorCache.set(languageId, extractor);
+  return extractor;
+}
+async function extractTreeSitterSymbols(filePath, languageId, contentOverride) {
+  const empty = {
+    symbols: [],
+    refs: [],
+    imports: [],
+    coverage: {
+      definitions: "unavailable",
+      references: "unavailable",
+      imports: "unavailable"
+    }
+  };
+  if (contentOverride === null)
+    return empty;
+  const treeSitterClient = getSharedTreeSitterClient();
+  if (!treeSitterClient)
+    return empty;
+  const initialized = await treeSitterClient.init();
+  if (!initialized)
+    return empty;
+  const extractor = await getExtractor(languageId);
+  if (!extractor)
+    return empty;
+  const content = contentOverride ?? fs.readFileSync(filePath, "utf-8");
+  const extracted = await treeSitterClient.withParsedTree(filePath, languageId, content, (tree) => extractor.extract(tree, filePath, content));
+  return extracted.parsed ? extracted.value : empty;
+}
+export async function captureReviewGraphStructuralIr(filePath, cwd, content, facts) {
+  const kind = detectFileKind(filePath);
+  if (!kind || !MAIN_KINDS.has(kind) || detectFileRole(filePath) === "test") {
+    return { complete: true };
+  }
+  if (kind === "jsts") {
+    if (!facts.hasFileFact(filePath, "file.imports") || !facts.hasFileFact(filePath, "file.reexports") || !facts.hasFileFact(filePath, "file.functionSummaries")) {
+      await ensureReviewGraphFacts(filePath, cwd, facts, content);
+    }
+    const parsed = await withTreeSitterRoot(filePath, content, () => true);
+    if (!parsed.parsed)
+      return { complete: false };
+    const functionCoverage = facts.getFileFact(filePath, "file.functionFactsCoverage") ?? "unavailable";
+    const importCoverage = facts.getFileFact(filePath, "file.importFactsCoverage") ?? "unavailable";
+    const coverage = {
+      definitions: functionCoverage,
+      references: functionCoverage,
+      imports: importCoverage,
+      calls: functionCoverage
+    };
+    if (Object.values(coverage).some((status) => status !== "complete")) {
+      return { complete: false };
+    }
+    return {
+      complete: true,
+      structural: {
+        kind: "jsts",
+        imports: facts.getFileFact(filePath, "file.imports") ?? [],
+        reexports: facts.getFileFact(filePath, "file.reexports") ?? [],
+        functionSummaries: facts.getFileFact(filePath, "file.functionSummaries") ?? [],
+        coverage
+      }
+    };
+  }
+  const languageId = mapKindToTreeSitterLanguage(kind, filePath);
+  if (!languageId)
+    return { complete: false };
+  const client = getSharedTreeSitterClient();
+  if (!client || !await client.init())
+    return { complete: false };
+  const extractor = await getExtractor(languageId);
+  if (!extractor)
+    return { complete: false };
+  const result = await client.withParsedTree(filePath, languageId, content, (tree) => extractor.extract(tree, filePath, content));
+  if (!result.parsed)
+    return { complete: false };
+  return {
+    complete: true,
+    structural: {
+      kind: "tree-sitter",
+      languageId,
+      extracted: result.value
+    }
+  };
+}
+const SYMBOL_KIND_SPECIFICITY = {
+  method: 2,
+  property: 2
+};
+function dedupeSamePositionSymbols(symbols) {
+  const bestByKey = new Map;
+  for (const symbol of symbols) {
+    const key = `${symbol.name}0000${symbol.line}0000${symbol.column}`;
+    const existing = bestByKey.get(key);
+    if (!existing) {
+      bestByKey.set(key, symbol);
+      continue;
+    }
+    const existingScore = SYMBOL_KIND_SPECIFICITY[existing.kind] ?? 0;
+    const candidateScore = SYMBOL_KIND_SPECIFICITY[symbol.kind] ?? 0;
+    if (candidateScore > existingScore)
+      bestByKey.set(key, symbol);
+  }
+  return [...bestByKey.values()];
+}
+function addTreeSitterFile(graph, cwd, filePath, languageId, extracted, ignoredIds) {
+  const normalized = normalizeMapKey(filePath);
+  const hintPath = toProjectRelativePath(normalized, cwd);
+  const fileNodeId = `file:${normalized}`;
+  addNode(graph, {
+    id: fileNodeId,
+    kind: "file",
+    language: languageId,
+    filePath: normalized,
+    metadata: {
+      ...featureHintMetadata(hintPath),
+      extractionCoverage: extracted.coverage
+    }
+  });
+  const dedupedSymbols = dedupeSamePositionSymbols(extracted.symbols);
+  const containers = dedupedSymbols.map((s) => ({
+    name: s.name,
+    startLine: s.line,
+    endLine: s.endLine ?? s.line
+  }));
+  for (const symbol of dedupedSymbols) {
+    const symbolId = buildSymbolId(normalized, symbol.name, symbol.kind, symbol.line);
+    const owner = findOwnerName(containers, symbol.line, symbol.endLine ?? symbol.line);
+    const qualifiedName = buildQualifiedName(owner, symbol.name);
+    addNode(graph, {
+      id: symbolId,
+      kind: "symbol",
+      language: languageId,
+      filePath: normalized,
+      symbolName: symbol.name,
+      symbolKind: symbol.kind,
+      ...qualifiedName ? { qualifiedName } : {},
+      exported: symbol.isExported,
+      metadata: {
+        line: symbol.line,
+        endLine: symbol.endLine,
+        column: symbol.column,
+        signature: symbol.signature,
+        ...featureHintMetadata(`${symbol.name} ${hintPath}`)
+      }
+    });
+    addEdge(graph, { from: fileNodeId, to: symbolId, kind: "contains" });
+    addEdge(graph, { from: fileNodeId, to: symbolId, kind: "defines" });
+  }
+  for (const ref of extracted.refs) {
+    const refName = ref.symbolName ?? ref.symbolId;
+    const targetId = `symbol-name:${refName}`;
+    if (!graph.nodes.has(targetId)) {
+      addNode(graph, {
+        id: targetId,
+        kind: "symbol",
+        language: languageId,
+        symbolName: refName,
+        metadata: { unresolvedName: refName }
+      });
+    }
+    addEdge(graph, {
+      from: fileNodeId,
+      to: targetId,
+      kind: "references",
+      metadata: {
+        line: ref.line,
+        column: ref.column,
+        referenceKind: ref.referenceKind ?? "unknown"
+      },
+      resolution: "name-only"
+    });
+  }
+  for (const imp of extracted.imports) {
+    const resolved = resolveImportToFiles(cwd, filePath, languageId, imp.source).filter((target) => !ignoredIds?.has(target));
+    if (resolved.length > 0) {
+      for (const target of resolved) {
+        const toNode = ensureFileNode(graph, target, cwd, mapKindToTreeSitterLanguage(detectFileKind(target), target) ?? languageId);
+        addEdge(graph, {
+          from: fileNodeId,
+          to: toNode,
+          kind: "imports",
+          metadata: { line: imp.line, source: imp.source }
+        });
+      }
+      continue;
+    }
+    const isRelative = imp.source.startsWith(".");
+    const targetId = `${isRelative ? "module" : "external"}:${imp.source}`;
+    if (!graph.nodes.has(targetId)) {
+      addNode(graph, {
+        id: targetId,
+        kind: isRelative ? "module" : "external",
+        language: languageId,
+        metadata: { source: imp.source }
+      });
+    }
+    addEdge(graph, {
+      from: fileNodeId,
+      to: targetId,
+      kind: "imports",
+      metadata: { line: imp.line }
+    });
+  }
+}
+export function addLspFallbackSymbols(graph, filePath, languageId, symbols) {
+  const normalized = normalizeMapKey(filePath);
+  const fileNodeId = `file:${normalized}`;
+  let added = 0;
+  const flatOwnerIds = new Map;
+  for (const symbol of symbols) {
+    const range = symbol.range ?? symbol.location?.range;
+    if (!range)
+      continue;
+    const kind = lspSymbolKindName(symbol.kind);
+    const id = buildSymbolId(normalized, symbol.name, kind, range.start.line + 1);
+    flatOwnerIds.set(symbol.name, id);
+    if (symbol.containerName) {
+      flatOwnerIds.set(`${symbol.containerName}.${symbol.name}`, id);
+    }
+  }
+  const visit = (items, parentId, ancestry) => {
+    for (const symbol of items) {
+      const range = symbol.range ?? symbol.location?.range;
+      if (!range)
+        continue;
+      const line = range.start.line + 1;
+      const kind = lspSymbolKindName(symbol.kind);
+      const symbolId = buildSymbolId(normalized, symbol.name, kind, line);
+      const owners = ancestry.length > 0 ? ancestry : containerNameChain(symbol, symbols);
+      const qualifiedName = owners.length > 0 ? [...owners, symbol.name].join(".") : undefined;
+      addNode(graph, {
+        id: symbolId,
+        kind: "symbol",
+        language: languageId,
+        filePath: normalized,
+        symbolName: symbol.name,
+        symbolKind: kind,
+        ...qualifiedName ? { qualifiedName } : {},
+        provenance: "lsp",
+        metadata: {
+          line,
+          column: range.start.character,
+          endLine: range.end.line + 1,
+          ...featureHintMetadata(`${symbol.name} ${normalized}`)
+        }
+      });
+      const resolvedParentId = ancestry.length === 0 && symbol.containerName ? flatOwnerIds.get(symbol.containerName) ?? parentId : parentId;
+      addEdge(graph, {
+        from: resolvedParentId,
+        to: symbolId,
+        kind: "contains"
+      });
+      addEdge(graph, { from: fileNodeId, to: symbolId, kind: "defines" });
+      added++;
+      if (symbol.children) {
+        visit(symbol.children, symbolId, [...owners, symbol.name]);
+      }
+    }
+  };
+  visit(symbols, fileNodeId, []);
+  return added;
+}
+function ensureFileNode(graph, filePath, cwd, languageId) {
+  const normalized = normalizeMapKey(filePath);
+  const hintPath = toProjectRelativePath(normalized, cwd);
+  const existing = graph.fileNodes.get(normalized);
+  if (existing)
+    return existing;
+  const fileNodeId = `file:${normalized}`;
+  addNode(graph, {
+    id: fileNodeId,
+    kind: "file",
+    language: languageId,
+    filePath: normalized,
+    metadata: featureHintMetadata(hintPath)
+  });
+  return fileNodeId;
+}
+function resolveCxxInclude(cwd, filePath, source) {
+  const candidates = [
+    path.resolve(path.dirname(filePath), source),
+    path.resolve(cwd, source),
+    path.resolve(cwd, "include", source),
+    path.resolve(cwd, "src", source)
+  ];
+  const root = path.resolve(cwd);
+  for (const candidate of candidates) {
+    if (!candidate.startsWith(root + path.sep) && candidate !== root)
+      continue;
+    if (fs.existsSync(candidate) && detectFileKind(candidate) === "cxx") {
+      return normalizeMapKey(candidate);
+    }
+  }
+  return;
+}
+function parseLocalCxxInclude(line) {
+  let i = 0;
+  while (i < line.length && (line[i] === " " || line[i] === "\t"))
+    i += 1;
+  if (line[i] !== "#")
+    return;
+  i += 1;
+  while (i < line.length && (line[i] === " " || line[i] === "\t"))
+    i += 1;
+  if (!line.startsWith("include", i))
+    return;
+  i += "include".length;
+  if (i >= line.length || line[i] !== " " && line[i] !== "\t") {
+    return;
+  }
+  while (i < line.length && (line[i] === " " || line[i] === "\t"))
+    i += 1;
+  if (line[i] !== '"')
+    return;
+  i += 1;
+  const start = i;
+  while (i < line.length && line[i] !== '"')
+    i += 1;
+  if (i >= line.length || i === start)
+    return;
+  return line.slice(start, i);
+}
+function addCxxIncludeEdges(graph, cwd, filePath, ignoredIds, contentOverride) {
+  let content = contentOverride;
+  if (content === undefined) {
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      return;
+    }
+  }
+  if (content === null)
+    return;
+  const fromNode = ensureFileNode(graph, filePath, cwd, "cpp");
+  for (const line of content.split(/\r?\n/)) {
+    const source = parseLocalCxxInclude(line);
+    if (!source)
+      continue;
+    const target = resolveCxxInclude(cwd, filePath, source);
+    if (!target || ignoredIds?.has(target))
+      continue;
+    const languageId = mapKindToTreeSitterLanguage("cxx", target) ?? "cpp";
+    const toNode = ensureFileNode(graph, target, cwd, languageId);
+    addEdge(graph, {
+      from: fromNode,
+      to: toNode,
+      kind: "imports",
+      metadata: { source }
+    });
+  }
+}
+function removeFileOwnedGraphData(graph, filePath, removedEdges) {
+  const normalized = normalizeMapKey(filePath);
+  const fileNodeId = graph.fileNodes.get(normalized) ?? `file:${normalized}`;
+  const removedSymbolIds = new Set(graph.symbolNodesByFile.get(normalized));
+  const removedIds = new Set(removedSymbolIds);
+  if (graph.nodes.has(fileNodeId))
+    removedIds.add(fileNodeId);
+  const candidates = new Set;
+  for (const id of removedIds) {
+    for (const edge of graph.edgesByFrom.get(id) ?? []) {
+      _rebuildCounters.removeOwnedEdgeVisits++;
+      candidates.add(edge);
+    }
+    for (const edge of graph.edgesByTo.get(id) ?? []) {
+      _rebuildCounters.removeOwnedEdgeVisits++;
+      candidates.add(edge);
+    }
+  }
+  const preservedIncomingSymbolEdges = [];
+  for (const edge of candidates) {
+    if (removedEdges.has(edge))
+      continue;
+    const fromRemoved = removedIds.has(edge.from);
+    if (!fromRemoved && edge.to === fileNodeId)
+      continue;
+    if (!fromRemoved && removedSymbolIds.has(edge.to)) {
+      preservedIncomingSymbolEdges.push({ ...edge });
+    }
+    removedEdges.add(edge);
+  }
+  for (const id of removedIds) {
+    const node = graph.nodes.get(id);
+    graph.nodes.delete(id);
+    if (!node?.filePath)
+      continue;
+    if (node.kind === "file") {
+      if (graph.fileNodes.get(node.filePath) === id) {
+        graph.fileNodes.delete(node.filePath);
+      }
+    } else if (node.kind === "symbol") {
+      const ids = graph.symbolNodesByFile.get(node.filePath);
+      if (!ids)
+        continue;
+      const at = ids.indexOf(id);
+      if (at >= 0)
+        ids.splice(at, 1);
+      if (ids.length === 0)
+        graph.symbolNodesByFile.delete(node.filePath);
+    }
+  }
+  return preservedIncomingSymbolEdges;
+}
+async function addFileToGraph(graph, cwd, file, facts, ignoredIds, contentOverride) {
+  const kind = detectFileKind(file);
+  if (!kind || !MAIN_KINDS.has(kind))
+    return;
+  if (detectFileRole(file) === "test")
+    return;
+  const contentHash = typeof contentOverride === "string" ? reviewGraphIrContentHash(contentOverride) : undefined;
+  const sharedIr = contentHash ? getFreshReviewGraphFileIr(cwd, file, contentHash)?.structural : undefined;
+  if (kind === "jsts") {
+    const dispatchOwnsContent = facts.getFileFact(file, "file.content") !== undefined && contentOverride == null;
+    try {
+      if (sharedIr?.kind === "jsts") {
+        facts.setFileFact(file, "file.content", contentOverride ?? "");
+        facts.setFileFact(file, "file.imports", sharedIr.imports);
+        facts.setFileFact(file, "file.reexports", sharedIr.reexports);
+        facts.setFileFact(file, "file.functionSummaries", sharedIr.functionSummaries);
+        facts.setFileFact(file, "file.functionFactsCoverage", sharedIr.coverage.calls);
+        facts.setFileFact(file, "file.importFactsCoverage", sharedIr.coverage.imports);
+      } else {
+        await ensureReviewGraphFacts(file, cwd, facts, contentOverride);
+      }
+      addJsTsFile(graph, cwd, file, facts, ignoredIds);
+    } finally {
+      if (!dispatchOwnsContent)
+        facts.deleteFileFact(file, "file.content");
+    }
+    return;
+  }
+  const languageId = mapKindToTreeSitterLanguage(kind, file);
+  if (!languageId)
+    return;
+  const irExtracted = sharedIr?.kind === "tree-sitter" && sharedIr.languageId === languageId ? sharedIr.extracted : undefined;
+  const extracted = irExtracted ?? await extractTreeSitterSymbols(file, languageId, contentOverride);
+  addTreeSitterFile(graph, cwd, file, languageId, extracted, ignoredIds);
+  if (extracted.symbols.length === 0) {
+    const lspSymbols = await getOpenDocumentSymbols(file);
+    const added = lspSymbols ? addLspFallbackSymbols(graph, file, languageId, lspSymbols) : 0;
+    logReviewGraph({
+      phase: "lsp_symbol_fallback",
+      cwd,
+      reason: lspSymbols ? added > 0 ? "added" : "empty-response" : "unavailable-or-failed",
+      nodes: added
+    });
+  }
+  if (kind === "cxx") {
+    addCxxIncludeEdges(graph, cwd, file, ignoredIds, contentOverride);
+  }
+}
+const _rebuildCounters = {
+  restoreComparisons: 0,
+  importTargetEdgeScans: 0,
+  removeOwnedEdgeVisits: 0,
+  removeOwnedEdgePositions: 0
+};
+export function _getReviewGraphRebuildCountersForTests() {
+  return { ..._rebuildCounters };
+}
+export function _resetReviewGraphRebuildCountersForTests() {
+  _rebuildCounters.restoreComparisons = 0;
+  _rebuildCounters.importTargetEdgeScans = 0;
+  _rebuildCounters.removeOwnedEdgeVisits = 0;
+  _rebuildCounters.removeOwnedEdgePositions = 0;
+}
+function edgeIdentityKey(edge) {
+  _rebuildCounters.restoreComparisons++;
+  return JSON.stringify([edge.from, edge.kind, edge.metadata ?? {}]);
+}
+function restoreValidIncomingEdges(graph, edges) {
+  const seenByTarget = new Map;
+  for (const edge of edges) {
+    if (!graph.nodes.has(edge.from) || !graph.nodes.has(edge.to))
+      continue;
+    let seen = seenByTarget.get(edge.to);
+    if (!seen) {
+      seen = new Set;
+      for (const candidate of graph.edgesByTo.get(edge.to) ?? []) {
+        seen.add(edgeIdentityKey(candidate));
+      }
+      seenByTarget.set(edge.to, seen);
+    }
+    const key = edgeIdentityKey(edge);
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    addEdge(graph, edge);
+  }
+}
+function dedupeResolvedEdges(graph, replacements) {
+  const resolvedEdges = new Set(replacements.map(([, after]) => after));
+  const seenByTarget = new Map;
+  const removed = new Set;
+  for (const [, edge] of replacements) {
+    if (removed.has(edge))
+      continue;
+    let seen = seenByTarget.get(edge.to);
+    if (!seen) {
+      seen = new Set;
+      for (const candidate of graph.edgesByTo.get(edge.to) ?? []) {
+        if (!resolvedEdges.has(candidate)) {
+          seen.add(edgeIdentityKey(candidate));
+        }
+      }
+      seenByTarget.set(edge.to, seen);
+    }
+    const key = edgeIdentityKey(edge);
+    if (seen.has(key)) {
+      removed.add(edge);
+      unindexEdge(graph, edge);
+      continue;
+    }
+    seen.add(key);
+  }
+  if (removed.size > 0) {
+    graph.edges = graph.edges.filter((edge) => !removed.has(edge));
+  }
+}
+const _graphImportChanges = new WeakMap;
+export function getGraphImportChanges(graph) {
+  return _graphImportChanges.get(graph);
+}
+function importTargetsForFile(graph, filePath) {
+  const normalized = normalizeMapKey(filePath);
+  const fileNodeId = graph.fileNodes.get(normalized) ?? `file:${normalized}`;
+  const targets = new Set;
+  for (const edge of graph.edgesByFrom.get(fileNodeId) ?? []) {
+    _rebuildCounters.importTargetEdgeScans++;
+    if (edge.kind !== "imports")
+      continue;
+    const target = graph.nodes.get(edge.to)?.filePath;
+    if (target)
+      targets.add(normalizeMapKey(target));
+  }
+  return [...targets].sort((a, b) => compareOrdinal(a, b));
+}
+async function updateGraphFiles(graph, cwd, files, facts, ignoredIds) {
+  rebuildIndexes(graph);
+  const prior = files.map((file) => ({
+    filePath: normalizeMapKey(file),
+    existedBefore: graph.fileNodes.has(normalizeMapKey(file)),
+    priorTargets: importTargetsForFile(graph, file)
+  }));
+  const preservedIncoming = [];
+  const removedEdges = new Set;
+  for (const file of files) {
+    preservedIncoming.push(...removeFileOwnedGraphData(graph, file, removedEdges));
+    await addFileToGraph(graph, cwd, file, facts, ignoredIds);
+  }
+  if (removedEdges.size > 0) {
+    unindexEdges(graph, removedEdges);
+    graph.edges = graph.edges.filter((edge) => !removedEdges.has(edge));
+  }
+  restoreValidIncomingEdges(graph, preservedIncoming);
+  resolveDeferredSymbolEdges(graph, false);
+  graph.changedSymbolsByFile.clear();
+  for (const file of files) {
+    upsertChangedSymbols(graph, facts, file);
+  }
+  return prior.map(({ filePath, existedBefore, priorTargets }) => ({
+    filePath,
+    existedBefore,
+    existsAfter: graph.fileNodes.has(filePath),
+    priorTargets,
+    newTargets: importTargetsForFile(graph, filePath)
+  }));
+}
+function resolveDeferredSymbolEdges(graph, rebuild = true) {
+  const symbolNameToIds = new Map;
+  for (const node of graph.nodes.values()) {
+    if (node.kind !== "symbol" || !node.symbolName)
+      continue;
+    if (node.metadata?.unresolvedName)
+      continue;
+    const ids = symbolNameToIds.get(node.symbolName) ?? [];
+    ids.push(node.id);
+    symbolNameToIds.set(node.symbolName, ids);
+  }
+  const replacements = [];
+  graph.edges = graph.edges.map((edge) => {
+    const targetNode = graph.nodes.get(edge.to);
+    if (!targetNode?.metadata?.unresolvedName)
+      return edge;
+    const candidates = symbolNameToIds.get(targetNode.symbolName ?? "") ?? [];
+    const importHintFile = edge.metadata?.importHintFile;
+    if (importHintFile) {
+      const scoped = candidates.filter((id) => graph.nodes.get(id)?.filePath === importHintFile);
+      if (scoped.length === 1) {
+        const resolved = {
+          ...edge,
+          to: scoped[0],
+          resolution: "import"
+        };
+        replacements.push([edge, resolved]);
+        return resolved;
+      }
+    }
+    if (candidates.length === 1) {
+      const resolved = {
+        ...edge,
+        to: candidates[0],
+        resolution: "exact"
+      };
+      replacements.push([edge, resolved]);
+      return resolved;
+    }
+    return edge;
+  });
+  if (rebuild) {
+    rebuildIndexes(graph);
+    return;
+  }
+  if (replacements.length === 0)
+    return;
+  const affectedTargets = new Set;
+  for (const [before, after] of replacements) {
+    const fromBucket = graph.edgesByFrom.get(before.from);
+    if (fromBucket) {
+      const at = fromBucket.indexOf(before);
+      if (at >= 0)
+        fromBucket[at] = after;
+    }
+    affectedTargets.add(before.to);
+    affectedTargets.add(after.to);
+  }
+  for (const target of affectedTargets)
+    graph.edgesByTo.set(target, []);
+  for (const edge of graph.edges) {
+    if (affectedTargets.has(edge.to))
+      graph.edgesByTo.get(edge.to)?.push(edge);
+  }
+  for (const target of affectedTargets) {
+    if (graph.edgesByTo.get(target)?.length === 0) {
+      graph.edgesByTo.delete(target);
+    }
+  }
+  dedupeResolvedEdges(graph, replacements);
+}
+function verifiedCacheFields(seqAtBuildStart) {
+  return {
+    builtAtProjectSeq: seqAtBuildStart,
+    lastFullVerifyMs: Date.now(),
+    fastPathSinceVerify: 0
+  };
+}
+async function tryIncrementalFromCache(cached, ctx) {
+  if (cached.fileSignatures.size === 0)
+    return;
+  const { added, removed, changed } = diffSignatureMaps(cached.fileSignatures, ctx.fileSignatures);
+  if (removed.length > 0)
+    return;
+  if (added.length === 0 && changed.length === 0)
+    return;
+  const { trulyChanged, hashes } = await confirmContentChanged(changed, cached.fileHashes);
+  const filesToUpdate = [...added, ...trulyChanged];
+  if (filesToUpdate.length === 0) {
+    const generation = cached.buildGeneration ?? ++_graphGenerationCounter;
+    const graph = cloneGraph(cached.graph);
+    rebuildIndexes(graph);
+    graph.changedSymbolsByFile.clear();
+    for (const file of ctx.normalizedChanged) {
+      upsertChangedSymbols(graph, ctx.facts, file);
+    }
+    setWorkspaceGraph(ctx.normalizedCwd, {
+      signature: ctx.signature,
+      fileSignatures: new Map(ctx.fileSignatures),
+      fileHashes: hashes,
+      graph: cloneGraph(cached.graph),
+      buildGeneration: generation,
+      ...verifiedCacheFields(ctx.seqAtBuildStart)
+    }, ctx.cacheEpoch);
+    setGraphBuildInfo(graph, {
+      reused: true,
+      mode: "cached",
+      graphChanged: false
+    });
+    graph.buildGeneration = generation;
+    setSessionReviewGraphFact(ctx.cwd, ctx.facts, graph);
+    return graph;
+  }
+  for (const file of added) {
+    hashes.set(file, contentHashEntry(file));
+  }
+  const priorGeneration = cached.graph.buildGeneration;
+  const graph = cloneGraph(cached.graph);
+  const importChanges = await updateGraphFiles(graph, ctx.cwd, filesToUpdate, ctx.facts, ctx.ignoredIds);
+  refreshGraphBuiltAt(graph);
+  const generation = ++_graphGenerationCounter;
+  graph.buildGeneration = generation;
+  setWorkspaceGraph(ctx.normalizedCwd, {
+    signature: ctx.signature,
+    fileSignatures: new Map(ctx.fileSignatures),
+    fileHashes: hashes,
+    graph,
+    buildGeneration: generation,
+    ...verifiedCacheFields(ctx.seqAtBuildStart)
+  }, ctx.cacheEpoch);
+  const persistReason = persistGraph(ctx.cwd, ctx.signature, ctx.fileSignatures, hashes, graph, {
+    buildId: ctx.buildId,
+    projectSeq: ctx.seqAtBuildStart,
+    seqHint: ctx.seqHint,
+    mode: ctx.mode
+  });
+  setGraphBuildInfo(graph, {
+    reused: true,
+    mode: "incremental",
+    ...persistReason ? { persistReason } : {},
+    graphChanged: true
+  });
+  _graphImportChanges.set(graph, {
+    fromGeneration: priorGeneration,
+    changes: importChanges
+  });
+  setSessionReviewGraphFact(ctx.cwd, ctx.facts, graph);
+  return graph;
+}
+function hasGraphKindExtension(file) {
+  const kind = detectFileKind(file);
+  return !!kind && MAIN_KINDS.has(kind) && detectFileRole(file) !== "test";
+}
+async function trySeqFastpath(cwd, buildId, normalizedCwd, normalizedChanged, facts, seqHint, seqAtBuildStart, ignoredIds, cacheEpoch) {
+  const cached = _workspaceGraphCache.get(normalizedCwd);
+  const cachedCoverage = cached?.graph.persistCoverage;
+  if (cachedCoverage?.partial && cachedCoverage.capTrimmed !== true) {
+    return { fallback: "partial-base" };
+  }
+  if (!cached || cached.builtAtProjectSeq === undefined) {
+    return { fallback: "no-seq" };
+  }
+  const now = Date.now();
+  const ageMs = cached.lastFullVerifyMs === undefined ? Number.POSITIVE_INFINITY : now - cached.lastFullVerifyMs;
+  const sinceVerify = cached.fastPathSinceVerify ?? 0;
+  if (ageMs > SEQ_FASTPATH_REVERIFY_MS || sinceVerify >= SEQ_FASTPATH_REVERIFY_EVERY) {
+    return { fallback: "verify-due" };
+  }
+  const changedSet = new Set(seqHint.getFilesChangedSince(cached.builtAtProjectSeq).map((file) => normalizeMapKey(file)));
+  for (const file of normalizedChanged)
+    changedSet.add(file);
+  const changed = [...changedSet];
+  if (changed.length > SEQ_FASTPATH_MAX_CHANGES) {
+    return { fallback: "too-many-changes" };
+  }
+  const candidateFiles = [];
+  for (const file of changed) {
+    const known = cached.fileSignatures.has(file);
+    let existsOnDisk = false;
+    try {
+      existsOnDisk = fs.statSync(file).isFile();
+    } catch {
+      existsOnDisk = false;
+    }
+    if (!existsOnDisk) {
+      if (known) {
+        return { fallback: "removed-file" };
+      }
+      continue;
+    }
+    if (!known) {
+      if (!hasGraphKindExtension(file))
+        continue;
+    }
+    candidateFiles.push(file);
+  }
+  const { trulyChanged, hashes } = await confirmContentChanged(candidateFiles, cached.fileHashes);
+  if (trulyChanged.length === 0) {
+    const graph = cloneGraph(cached.graph);
+    rebuildIndexes(graph);
+    graph.changedSymbolsByFile.clear();
+    for (const file of normalizedChanged) {
+      upsertChangedSymbols(graph, facts, file);
+    }
+    const nextSignatures = new Map(cached.fileSignatures);
+    for (const file of candidateFiles) {
+      nextSignatures.set(file, sourceSignatureEntry(file));
+    }
+    cached.signature = sourceSignatureFromMap(nextSignatures);
+    cached.fileSignatures = nextSignatures;
+    cached.fileHashes = hashes;
+    cached.builtAtProjectSeq = seqAtBuildStart;
+    cached.fastPathSinceVerify = sinceVerify + 1;
+    const generation = cached.buildGeneration ??= ++_graphGenerationCounter;
+    setGraphBuildInfo(graph, {
+      reused: true,
+      mode: "seq-fastpath",
+      graphChanged: false
+    });
+    graph.buildGeneration = generation;
+    setSessionReviewGraphFact(cwd, facts, graph);
+    return { graph };
+  }
+  const filesToUpdate = trulyChanged;
+  const priorGeneration = cached.graph.buildGeneration;
+  const graph = cloneGraph(cached.graph);
+  let importChanges;
+  try {
+    importChanges = await updateGraphFiles(graph, cwd, filesToUpdate, facts, ignoredIds);
+  } catch {
+    return { fallback: "stat-error" };
+  }
+  refreshGraphBuiltAt(graph);
+  const nextSignatures = new Map(cached.fileSignatures);
+  for (const file of candidateFiles) {
+    nextSignatures.set(file, sourceSignatureEntry(file));
+  }
+  const nextSignature = sourceSignatureFromMap(nextSignatures);
+  const generation = ++_graphGenerationCounter;
+  graph.buildGeneration = generation;
+  setWorkspaceGraph(normalizedCwd, {
+    signature: nextSignature,
+    fileSignatures: nextSignatures,
+    fileHashes: hashes,
+    graph,
+    buildGeneration: generation,
+    builtAtProjectSeq: seqAtBuildStart,
+    lastFullVerifyMs: cached.lastFullVerifyMs,
+    fastPathSinceVerify: sinceVerify + 1
+  }, cacheEpoch);
+  const persistReason = persistGraph(cwd, nextSignature, nextSignatures, hashes, graph, {
+    buildId,
+    projectSeq: seqAtBuildStart,
+    seqHint: true,
+    mode: "seq-fastpath"
+  });
+  setGraphBuildInfo(graph, {
+    reused: true,
+    mode: "seq-fastpath",
+    ...persistReason ? { persistReason } : {},
+    graphChanged: true
+  });
+  _graphImportChanges.set(graph, {
+    fromGeneration: priorGeneration,
+    changes: importChanges
+  });
+  setSessionReviewGraphFact(cwd, facts, graph);
+  return { graph };
+}
+async function _doBuildGraph(cwd, changedFiles, facts, seqHint, buildId) {
+  const normalizedCwd = normalizeMapKey(cwd);
+  const cacheEpoch = workspaceCacheEpoch(normalizedCwd);
+  if (_reviewGraphBuildGateForTests)
+    await _reviewGraphBuildGateForTests();
+  const normalizedChanged = changedFiles.map((file) => normalizeMapKey(file));
+  const normalizedChangedSet = new Set(normalizedChanged);
+  logCwdWorktreeMismatchOnce(cwd);
+  if (isAtOrAboveHomeDir(path.resolve(cwd))) {
+    const graph = createEmptyGraph();
+    for (const file of normalizedChanged) {
+      upsertChangedSymbols(graph, facts, file);
+    }
+    setGraphBuildInfo(graph, {
+      reused: false,
+      mode: "skipped",
+      skipReason: "unsafe_root",
+      graphChanged: true
+    });
+    setSessionReviewGraphFact(cwd, facts, graph);
+    return graph;
+  }
+  const seqAtBuildStart = seqHint?.projectSeq();
+  const ignoredIdsPromise = collectUntrackedIgnoredIds(cwd);
+  let seqFastpathFallback;
+  if (seqHint && seqAtBuildStart !== undefined && seqFastpathEnabled()) {
+    const fast = await trySeqFastpath(cwd, buildId, normalizedCwd, normalizedChanged, facts, seqHint, seqAtBuildStart, await ignoredIdsPromise, cacheEpoch);
+    if ("graph" in fast)
+      return fast.graph;
+    seqFastpathFallback = fast.fallback;
+  }
+  const sourceCollection = await getGraphSourceFiles(cwd);
+  const filesToBuild = sourceCollection.files;
+  const sourceFileCount = sourceCollection.sourceFileCount;
+  const pathNormalizeCalls = sourceCollection.pathNormalizeCalls;
+  const sourceFilesTruncated = sourceCollection.entryBudgetExceeded;
+  const ignoredIds = await ignoredIdsPromise;
+  const maxGraphFiles = sourceCollection.maxFileCount;
+  if (filesToBuild.length > maxGraphFiles) {
+    const graph = createEmptyGraph();
+    graph.version = REVIEW_GRAPH_VERSION;
+    graph.builtAt = new Date().toISOString();
+    for (const file of normalizedChanged) {
+      upsertChangedSymbols(graph, facts, file);
+    }
+    recordReviewGraphSizeSkip(cwd, sourceFileCount, maxGraphFiles);
+    logLatency({
+      type: "phase",
+      phase: "review_graph_size_skip",
+      filePath: cwd,
+      durationMs: 0,
+      metadata: {
+        cwd,
+        sourceFileCount,
+        maxFileCount: maxGraphFiles,
+        sourceFileCountLabel: `more than ${maxGraphFiles} files`,
+        sourceFileCountTruncated: true
+      }
+    });
+    if (isReviewGraphSizeNearMiss(sourceFileCount, maxGraphFiles)) {
+      logLatency({
+        type: "phase",
+        phase: "review_graph_size_near_miss",
+        filePath: cwd,
+        durationMs: 0,
+        metadata: {
+          cwd,
+          maxFileCount: maxGraphFiles,
+          sourceFileCount,
+          sourceFileCountLabel: `more than ${maxGraphFiles} files`,
+          sourceFileCountTruncated: true
+        }
+      });
+    }
+    setGraphBuildInfo(graph, {
+      reused: false,
+      mode: "skipped",
+      skipReason: "too_many_files",
+      sourceFileCount,
+      sourceFileCountTruncated: sourceFilesTruncated || filesToBuild.length > maxGraphFiles,
+      maxFileCount: maxGraphFiles,
+      pathNormalizeCalls,
+      seqFastpathFallback,
+      graphChanged: true
+    });
+    setSessionReviewGraphFact(cwd, facts, graph);
+    return graph;
+  }
+  if (!sourceFilesTruncated)
+    clearReviewGraphSizeSkip(cwd);
+  const fileSignatures = await sourceSignatureMapAsync(filesToBuild);
+  const signature = sourceSignatureFromMap(fileSignatures);
+  let memCached = sourceFilesTruncated ? undefined : _workspaceGraphCache.get(normalizedCwd);
+  const memCoverage = memCached?.graph.persistCoverage;
+  if (memCoverage?.partial && memCoverage.capTrimmed !== true) {
+    memCached = undefined;
+  }
+  if (memCached?.signature === signature) {
+    touchWorkspaceGraph(normalizedCwd);
+    const graph = cloneGraph(memCached.graph);
+    rebuildIndexes(graph);
+    graph.changedSymbolsByFile.clear();
+    for (const file of normalizedChanged) {
+      upsertChangedSymbols(graph, facts, file);
+    }
+    Object.assign(memCached, verifiedCacheFields(seqAtBuildStart));
+    const generation = memCached.buildGeneration ??= ++_graphGenerationCounter;
+    setGraphBuildInfo(graph, {
+      reused: true,
+      mode: "cached",
+      seqFastpathFallback,
+      graphChanged: false
+    });
+    graph.buildGeneration = generation;
+    setSessionReviewGraphFact(cwd, facts, graph);
+    return graph;
+  }
+  if (memCached) {
+    const incremental = await tryIncrementalFromCache(memCached, {
+      cwd,
+      buildId,
+      seqHint: seqHint !== undefined,
+      mode: "incremental",
+      normalizedCwd,
+      normalizedChanged,
+      fileSignatures,
+      signature,
+      facts,
+      seqAtBuildStart,
+      ignoredIds,
+      cacheEpoch
+    });
+    if (incremental) {
+      updateGraphBuildInfo(incremental, { seqFastpathFallback });
+      return incremental;
+    }
+  }
+  const diskCached = sourceFilesTruncated ? null : loadPersistedGraph(cwd);
+  if (diskCached?.signature === signature) {
+    const graph = cloneGraph(diskCached.graph);
+    rebuildIndexes(graph);
+    graph.changedSymbolsByFile.clear();
+    for (const file of normalizedChanged) {
+      upsertChangedSymbols(graph, facts, file);
+    }
+    const generation = ++_graphGenerationCounter;
+    setWorkspaceGraph(normalizedCwd, {
+      signature,
+      fileSignatures: new Map(fileSignatures),
+      fileHashes: diskCached.fileHashes,
+      graph: cloneGraph(diskCached.graph),
+      buildGeneration: generation,
+      ...verifiedCacheFields(seqAtBuildStart)
+    }, cacheEpoch);
+    setGraphBuildInfo(graph, {
+      reused: true,
+      mode: "cached",
+      seqFastpathFallback,
+      graphChanged: false
+    });
+    graph.buildGeneration = generation;
+    setSessionReviewGraphFact(cwd, facts, graph);
+    return graph;
+  }
+  if (diskCached) {
+    const incremental = await tryIncrementalFromCache({
+      signature: diskCached.signature,
+      fileSignatures: diskCached.fileSignatures,
+      fileHashes: diskCached.fileHashes,
+      graph: diskCached.graph
+    }, {
+      cwd,
+      buildId,
+      seqHint: seqHint !== undefined,
+      mode: "incremental",
+      normalizedCwd,
+      normalizedChanged,
+      fileSignatures,
+      signature,
+      facts,
+      seqAtBuildStart,
+      ignoredIds
+    });
+    if (incremental) {
+      updateGraphBuildInfo(incremental, { seqFastpathFallback });
+      return incremental;
+    }
+  }
+  const resumed = sourceFilesTruncated ? null : await tryResumeFromCheckpoint(cwd, filesToBuild, ignoredIds);
+  const graph = resumed?.graph ?? createEmptyGraph();
+  const filesToExtract = resumed?.remaining ?? filesToBuild;
+  const treeSitterClient = getSharedTreeSitterClient();
+  treeSitterClient?.ensureTreeCacheCapacity(filesToExtract.length);
+  const extractionStartedAt = Date.now();
+  const fileHashes = resumed?.fileHashes ?? new Map;
+  const checkpointEvery = graphCheckpointEveryFiles();
+  const checkpointMinIntervalMs = graphCheckpointMinIntervalMs();
+  const testStopAfter = Number(process.env.DM_LENS_GRAPH_CHECKPOINT_TEST_STOP_AFTER);
+  let filesSinceCheckpoint = 0;
+  let lastCheckpointMs = Date.now();
+  let extractedCount = 0;
+  const extractFiles = async () => {
+    for (const file of filesToExtract) {
+      let content;
+      try {
+        const bytes = fs.readFileSync(file);
+        content = bytes.toString("utf-8");
+        fileHashes.set(file, createHash("sha256").update(bytes).digest("hex"));
+      } catch {
+        content = null;
+        fileHashes.set(file, "missing");
+      }
+      await addFileToGraph(graph, cwd, file, facts, ignoredIds, content);
+      if (normalizedChangedSet.has(file)) {
+        upsertChangedSymbols(graph, facts, file);
+      }
+      extractedCount++;
+      filesSinceCheckpoint++;
+      if (Number.isFinite(testStopAfter) && testStopAfter > 0 && extractedCount >= testStopAfter) {
+        writeReviewGraphCheckpointSync(cwd, buildReviewGraphCheckpointData(cwd, graph, fileHashes, filesToBuild.length, ignoredIds), {
+          nodes: graph.nodes.size,
+          edges: graph.edges.length,
+          processed: fileHashes.size,
+          target: filesToBuild.length
+        });
+        throw new Error("__review_graph_checkpoint_test_abort__");
+      }
+      const remainingAfter = filesToExtract.length - extractedCount;
+      if (filesSinceCheckpoint >= checkpointEvery && remainingAfter >= checkpointEvery && Date.now() - lastCheckpointMs >= checkpointMinIntervalMs) {
+        writeReviewGraphCheckpoint(cwd, graph, fileHashes, filesToBuild.length, ignoredIds);
+        filesSinceCheckpoint = 0;
+        lastCheckpointMs = Date.now();
+      }
+    }
+  };
+  const extractAndDrainIr = async () => {
+    try {
+      await extractFiles();
+    } finally {
+      clearReviewGraphFileIr(cwd);
+    }
+  };
+  if (treeSitterClient) {
+    await treeSitterClient.withParseCacheMeasurement(extractAndDrainIr, (stats) => {
+      logTreeSitterCacheStats({
+        scope: "review_graph_full",
+        filePath: cwd,
+        fileCount: filesToBuild.length,
+        durationMs: Date.now() - extractionStartedAt,
+        stats,
+        astGrep: { durationMs: 0, fileCount: 0 }
+      });
+    });
+  } else {
+    await extractAndDrainIr();
+  }
+  if (resumed) {
+    for (const file of normalizedChangedSet) {
+      if (resumed.fileHashes.has(file)) {
+        upsertChangedSymbols(graph, facts, file);
+      }
+    }
+  }
+  resolveDeferredSymbolEdges(graph);
+  graph.version = REVIEW_GRAPH_VERSION;
+  graph.builtAt = new Date().toISOString();
+  graph.persistCoverage = sourceFilesTruncated ? graphCoverage(graph, graphPersistMaxElements(), sourceFileCount, true, filesToBuild) : undefined;
+  deleteReviewGraphCheckpoint(cwd);
+  const generation = ++_graphGenerationCounter;
+  const retained = retainedGraph(cwd, graph);
+  const wasCapped = retained !== graph;
+  const graphSnapshot = wasCapped ? retained : cloneGraph(graph);
+  if (!wasCapped)
+    rebuildIndexes(graphSnapshot);
+  graphSnapshot.buildGeneration = generation;
+  setWorkspaceGraph(normalizedCwd, {
+    signature,
+    fileSignatures: new Map(fileSignatures),
+    fileHashes,
+    graph: graphSnapshot,
+    buildGeneration: generation,
+    ...verifiedCacheFields(seqAtBuildStart)
+  }, cacheEpoch);
+  const persistReason = persistGraph(cwd, signature, fileSignatures, fileHashes, graphSnapshot, {
+    buildId,
+    projectSeq: seqAtBuildStart,
+    seqHint: seqHint !== undefined,
+    mode: "full",
+    sourceFileCount,
+    sourceFilesTruncated
+  });
+  setGraphBuildInfo(graph, {
+    reused: false,
+    mode: "full",
+    sourceFileCount,
+    sourceFileCountTruncated: sourceFilesTruncated,
+    pathNormalizeCalls,
+    seqFastpathFallback,
+    ...persistReason ? { persistReason } : {},
+    graphChanged: true
+  });
+  graph.buildGeneration = generation;
+  setSessionReviewGraphFact(cwd, facts, graphSnapshot);
+  return graph;
+}
+function buildCacheKey(cwd, changedFiles) {
+  return `${buildCacheWorkspaceKey(cwd)}|${[...changedFiles].sort((a, b) => compareOrdinal(a, b)).join(",")}`;
+}
+export function isGraphBuildInFlight(cwd, changedFiles = []) {
+  return _buildCache.has(buildCacheKey(cwd, changedFiles));
+}
+export function buildOrUpdateGraph(cwd, changedFiles, facts, seqHint) {
+  const cacheKey = buildCacheKey(cwd, changedFiles);
+  const cached = _buildCache.get(cacheKey);
+  if (cached)
+    return cached;
+  const startedAt = Date.now();
+  const buildId = ++_buildIdCounter;
+  recordBuildAttempt(cwd, "running", undefined, buildId);
+  const startedProjectSeq = seqHint?.projectSeq();
+  logReviewGraph({
+    cwd,
+    phase: "build_started",
+    observability: {
+      graph: {
+        buildId,
+        ...startedProjectSeq === undefined ? {} : { projectSeq: startedProjectSeq },
+        ...seqHint === undefined ? {} : { seqHint: true },
+        nodes: 0,
+        edges: 0
+      }
+    }
+  });
+  const promise = _doBuildGraph(cwd, changedFiles, facts, seqHint, buildId).then((graph) => {
+    const buildInfo = getGraphBuildInfoForGraph(graph);
+    if (buildInfo.mode === "skipped") {
+      const reason = buildInfo.skipReason ?? "skipped";
+      recordBuildAttempt(cwd, "skipped", reason, buildId);
+      logReviewGraph({
+        cwd,
+        phase: "build_skipped",
+        reason,
+        durationMs: Date.now() - startedAt,
+        observability: {
+          graph: graphLogMetadata(graph, {
+            buildId,
+            projectSeq: startedProjectSeq,
+            seqHint: seqHint !== undefined,
+            mode: buildInfo.mode,
+            sourceFileCount: buildInfo.sourceFileCount,
+            sourceFileCountTruncated: buildInfo.sourceFileCountTruncated,
+            pathNormalizeCalls: buildInfo.pathNormalizeCalls
+          })
+        }
+      });
+    } else {
+      const reason = buildInfo.persistReason;
+      recordBuildAttempt(cwd, "succeeded", reason, buildId);
+      logReviewGraph({
+        cwd,
+        phase: "build_succeeded",
+        durationMs: Date.now() - startedAt,
+        nodes: graph.nodes.size,
+        edges: graph.edges.length,
+        ...reason ? { reason } : {},
+        observability: {
+          graph: graphLogMetadata(graph, {
+            buildId,
+            projectSeq: startedProjectSeq,
+            seqHint: seqHint !== undefined,
+            mode: buildInfo.mode,
+            sourceFileCount: buildInfo.sourceFileCount,
+            sourceFileCountTruncated: buildInfo.sourceFileCountTruncated,
+            pathNormalizeCalls: buildInfo.pathNormalizeCalls
+          })
+        }
+      });
+    }
+    return graph;
+  }).catch((err) => {
+    const reason = err instanceof Error ? err.message : String(err);
+    recordBuildAttempt(cwd, "failed", reason, buildId);
+    logReviewGraph({
+      cwd,
+      phase: "build_failed",
+      reason,
+      durationMs: Date.now() - startedAt,
+      error: reason,
+      observability: {
+        graph: {
+          buildId,
+          ...seqHint === undefined ? {} : { seqHint: true },
+          nodes: 0,
+          edges: 0
+        }
+      }
+    });
+    throw err;
+  });
+  _buildCache.set(cacheKey, promise);
+  const release = () => {
+    if (_buildCache.get(cacheKey) === promise)
+      _buildCache.delete(cacheKey);
+  };
+  promise.then(release, release);
+  return promise;
+}
+export function extractSymbolsAndRefsFromGraph(graph) {
+  const allSymbols = new Map;
+  const allRefs = new Map;
+  const nodeSymbols = new Map;
+  const coverage = {
+    totalEvidence: 0,
+    callsEvidence: 0,
+    referencesEvidence: 0,
+    eligibleEvidence: 0,
+    resolvedEvidence: 0,
+    unresolvedEvidence: 0,
+    typeOnlyEvidence: 0,
+    unsupportedEvidence: 0,
+    sameFileEvidence: 0,
+    duplicateEvidence: 0,
+    complete: graph.persistCoverage?.partial !== true && graph.persistCoverage?.inProgress !== true,
+    languages: {}
+  };
+  const numberMetadata = (node, key) => {
+    const value = node?.metadata?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+  };
+  const symbolKind = (node) => {
+    switch (node.symbolKind) {
+      case "class":
+      case "interface":
+      case "type":
+      case "variable":
+      case "method":
+      case "property":
+      case "function":
+        return node.symbolKind;
+      default:
+        return "function";
+    }
+  };
+  for (const node of graph.nodes.values()) {
+    if (node.kind !== "symbol" || !node.filePath || !node.symbolName)
+      continue;
+    const sym = {
+      id: node.id,
+      name: node.symbolName,
+      kind: symbolKind(node),
+      filePath: node.filePath,
+      line: numberMetadata(node, "line") ?? 1,
+      endLine: numberMetadata(node, "endLine"),
+      column: numberMetadata(node, "column") ?? 1,
+      isExported: node.exported === true
+    };
+    nodeSymbols.set(node.id, sym);
+    const list = allSymbols.get(node.filePath) ?? [];
+    list.push(sym);
+    allSymbols.set(node.filePath, list);
+  }
+  const addRef = (ref) => {
+    const list = allRefs.get(ref.filePath) ?? [];
+    list.push(ref);
+    allRefs.set(ref.filePath, list);
+  };
+  for (const edge of graph.edges) {
+    if (edge.kind !== "calls" && edge.kind !== "references")
+      continue;
+    coverage.totalEvidence++;
+    if (edge.kind === "calls")
+      coverage.callsEvidence++;
+    else
+      coverage.referencesEvidence++;
+    const fromNode = graph.nodes.get(edge.from);
+    const targetNode = graph.nodes.get(edge.to);
+    const callerFile = fromNode?.kind === "symbol" ? fromNode.filePath : fromNode?.kind === "file" ? fromNode.filePath : edge.from.startsWith("file:") ? edge.from.slice("file:".length) : undefined;
+    if (!callerFile) {
+      coverage.unsupportedEvidence++;
+      continue;
+    }
+    const metadata = edge.metadata ?? {};
+    const referenceKind = edge.kind === "calls" ? "call" : metadata.referenceKind === "call" ? "call" : metadata.referenceKind === "type" ? "type" : "unknown";
+    const resolution = edge.resolution ?? (targetNode && !targetNode.metadata?.unresolvedName ? "exact" : "unresolved");
+    const targetSymbol = nodeSymbols.get(edge.to);
+    const targetName = targetNode?.symbolName ?? (edge.to.startsWith("symbol-name:") ? edge.to.slice("symbol-name:".length) : undefined);
+    const line = typeof metadata.line === "number" ? metadata.line : numberMetadata(fromNode, "line") ?? 1;
+    const column = typeof metadata.column === "number" ? metadata.column : numberMetadata(fromNode, "column") ?? 1;
+    addRef({
+      symbolId: targetName ? `${callerFile}:${targetName}` : edge.to,
+      filePath: callerFile,
+      line,
+      column,
+      evidenceKind: edge.kind,
+      referenceKind,
+      targetId: edge.to,
+      callerSymbolId: fromNode?.kind === "symbol" ? fromNode.id : undefined,
+      resolution,
+      targetName,
+      targetKind: targetNode?.symbolKind,
+      targetFilePath: targetNode?.filePath,
+      targetLine: numberMetadata(targetNode, "line"),
+      targetColumn: numberMetadata(targetNode, "column")
+    });
+    if (referenceKind === "type")
+      coverage.typeOnlyEvidence++;
+    else if (referenceKind !== "call")
+      coverage.unsupportedEvidence++;
+    else if (!targetSymbol || resolution === "name-only" || resolution === "unresolved") {
+      coverage.unresolvedEvidence++;
+    } else {
+      coverage.eligibleEvidence++;
+      coverage.resolvedEvidence++;
+    }
+  }
+  let sawRelevantFileNode = false;
+  for (const node of graph.nodes.values()) {
+    if (node.kind !== "file")
+      continue;
+    sawRelevantFileNode = true;
+    const extraction = node.metadata?.extractionCoverage;
+    const statuses = extraction ? Object.values(extraction) : [];
+    const languageStatus = !extraction || statuses.length === 0 || statuses.includes("unavailable") ? "unavailable" : statuses.includes("partial") ? "partial" : "complete";
+    if (languageStatus !== "complete")
+      coverage.complete = false;
+    if (node.language) {
+      const prior = coverage.languages[node.language];
+      coverage.languages[node.language] = prior === "unavailable" || languageStatus === "unavailable" ? "unavailable" : prior === "partial" || languageStatus === "partial" ? "partial" : languageStatus;
+    }
+  }
+  if (!sawRelevantFileNode)
+    coverage.complete = false;
+  return { allSymbols, allRefs, coverage };
+}