pi-lens 3.8.73 → 4.0.0

package/dist/clients/call-graph.js

@@ -4,12 +4,17 @@
  * Builds a bidirectional function-level call graph by resolving symbol
  * references across files. Provides BFS impact analysis with severity tiers.
  * Uses the Symbol/SymbolRef data produced by TreeSitterSymbolExtractor and
- * persists the result with per-file mtime tracking for incremental sessions.
+ * persists the result under the canonical review-graph identity; freshness is
+ * owned exclusively by the review-graph snapshot.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "./file-utils.js";
-const CACHE_VERSION = 3;
+import { writeFileAtomic } from "./atomic-write.js";
+import { parseSymbolKey as parseCanonicalSymbolKey } from "./review-graph/symbol-id.js";
+import { normalizeMapKey, toProjectRelativePath } from "./path-utils.js";
+/** Persisted call-graph cache format version. Bump on breaking format changes. */
+export const CALL_GRAPH_CACHE_VERSION = 5;
 function severityForDepth(depth) {
     if (depth === 1)
         return "WillBreak";
@@ -65,6 +70,19 @@ export function impact(graph, startKey, maxDepth = 3, minWeight = 0.1) {
     // Sort by depth then symbolKey for stable output
     return results.sort((a, b) => a.depth - b.depth || a.symbolKey.localeCompare(b.symbolKey));
 }
+/**
+ * Splits a `SymbolKey` into its file and symbol-name parts. Two shapes exist
+ * (see `buildCallGraph` above): the normal `"filePath:symbolName"` form, and
+ * the file-level fallback `"file:filePath"` used when no enclosing symbol was
+ * found for a call site (module-level code). Splitting at the LAST colon
+ * (rather than a naive `split(":")`) means a Windows drive letter in
+ * `filePath` (`C:\...`) is never mistaken for the name/file separator; the
+ * `"file:"` fallback is matched as a literal prefix first so it isn't
+ * misparsed by the same last-colon rule.
+ */
+export function parseSymbolKey(key, knownFilePath) {
+    return parseCanonicalSymbolKey(key, knownFilePath);
+}
 /**
  * Format an impact result set as a compact human-readable summary.
  * Example: "handleToolResult (WillBreak) → handleAgentEnd (MayBreak) → 3 Review callers"
@@ -77,12 +95,9 @@ export function formatImpact(results, projectRoot) {
     const review = results.filter((r) => r.severity === "Review");
     const parts = [];
     const label = (r) => {
-        const name = r.symbolKey.includes(":")
-            ? r.symbolKey.split(":").pop() ?? r.symbolKey
-            : r.symbolKey;
-        const file = r.symbolKey.includes(":")
-            ? r.symbolKey.split(":").slice(0, -1).join(":").replace(projectRoot, "").replace(/^[/\\]/, "")
-            : "";
+        const parsed = parseSymbolKey(r.symbolKey);
+        const name = parsed.symbolName ?? r.symbolKey;
+        const file = toProjectRelativePath(parsed.filePath, projectRoot);
         return file ? `${name} (${file})` : name;
     };
     if (willBreak.length > 0) {
@@ -113,15 +128,15 @@ const STDLIB_NAMES = new Set([
     "open", "isinstance", "issubclass", "type", "super", "hasattr", "getattr",
     "setattr", "enumerate", "zip", "map", "filter", "sorted", "reversed",
     // Go
-    "fmt", "log", "os", "io", "err", "make", "append", "len", "cap", "copy",
+    "fmt", "log", "os", "io", "err", "make", "append", "cap", "copy",
     "close", "delete", "panic", "recover", "new",
     // Rust
-    "println", "eprintln", "print", "eprint", "vec", "Some", "None", "Ok", "Err",
-    "Box", "Rc", "Arc", "String", "Vec", "HashMap", "HashSet", "format",
+    "eprintln", "eprint", "vec", "Some", "None", "Ok", "Err",
+    "Box", "Rc", "Arc", "Vec", "HashMap", "HashSet", "format",
     // Java/Kotlin
-    "System", "println", "toString", "equals", "hashCode", "Objects",
+    "System", "toString", "equals", "hashCode", "Objects",
     // Generic
-    "new", "this", "self", "super", "nil", "null", "undefined", "true", "false",
+    "this", "self", "nil", "null", "undefined", "true", "false",
 ]);
 // ── Core resolution ────────────────────────────────────────────────────────────
 /**
@@ -130,29 +145,34 @@ const STDLIB_NAMES = new Set([
  * discounts edges when many files define the same name.
  */
 function buildDefIndex(allSymbols) {
-    const index = new Map();
+    const byName = new Map();
+    const byId = new Map();
     for (const [, symbols] of allSymbols) {
         for (const sym of symbols) {
-            if (!sym.name)
+            if (!sym.name || !sym.id)
                 continue;
-            const key = `${sym.filePath}:${sym.name}`;
-            const existing = index.get(sym.name) ?? [];
+            const key = sym.id;
+            byId.set(key, sym);
+            const existing = byName.get(sym.name) ?? [];
             if (!existing.includes(key))
                 existing.push(key);
-            index.set(sym.name, existing);
+            byName.set(sym.name, existing);
         }
     }
-    return index;
+    return { byName, byId };
 }
 /**
- * Find the enclosing function/method for a ref at `refLine` using a
- * "last start-line before ref" heuristic. Returns the symbol whose
- * start line is closest to (and not after) the ref's line.
+ * Find the enclosing function/method for a ref at `refLine`. A symbol with
+ * an end line is eligible only while the reference is inside its inclusive
+ * source range; symbols without an end line retain the conservative start-line
+ * fallback. Returns undefined when no symbol encloses the reference so callers
+ * can use the file-level module key.
  */
 function findEnclosingSymbol(symbols, refLine) {
     let best;
     for (const sym of symbols) {
         if (sym.line <= refLine &&
+            (sym.endLine === undefined || refLine <= sym.endLine) &&
             (sym.kind === "function" || sym.kind === "method")) {
             if (!best || sym.line > best.line)
                 best = sym;
@@ -161,74 +181,224 @@ function findEnclosingSymbol(symbols, refLine) {
     return best;
 }
 /**
- * Build the function-level call graph from extracted symbols and refs.
+ * Build the function-level call graph from normalized review-graph evidence.
  *
- * Two passes:
- *   1. Index all defs by name across all files.
- *   2. For each ref, resolve to cross-file defs; find enclosing caller.
+ * The adapter supplies canonical target ids for graph evidence. Such evidence
+ * is accepted only when it points at a concrete symbol and has a non-ambiguous
+ * resolution. The old name-only path remains for legacy SymbolRef callers, but
+ * it is deliberately not used by the review-graph adapter (#1070).
  */
-export function buildCallGraph(allSymbols, allRefs) {
-    const defIndex = buildDefIndex(allSymbols);
+export function buildCallGraph(
+/** Keys are normalizeMapKey-canonical file paths; Symbol.filePath values retain their display spelling. */
+allSymbols, 
+/** Keys are normalizeMapKey-canonical caller file paths; SymbolRef.filePath retains its display spelling. */
+allRefs, inputCoverage) {
+    // Keep the lookup index canonical even for legacy direct callers that still
+    // construct these maps from display paths; persisted/review-graph callers
+    // already satisfy the canonical-key contract documented above. A caller that
+    // supplies TWO raw spellings of the same file gets last-writer-wins here —
+    // raw compatibility is best-effort tolerance, not a merge contract.
+    const canonicalSymbols = new Map();
+    for (const [filePath, symbols] of allSymbols)
+        canonicalSymbols.set(normalizeMapKey(filePath), symbols);
+    const defIndex = buildDefIndex(canonicalSymbols);
     const callees = new Map();
     const callers = new Map();
     const inDegree = new Map();
-    const edges = [];
+    const edgeByPair = new Map();
     let unresolvedRefs = 0;
     let totalRefs = 0;
+    const hasInputCoverage = inputCoverage !== undefined;
+    const coverage = inputCoverage
+        ? { ...inputCoverage }
+        : {
+            totalEvidence: 0,
+            callsEvidence: 0,
+            referencesEvidence: 0,
+            eligibleEvidence: 0,
+            resolvedEvidence: 0,
+            unresolvedEvidence: 0,
+            typeOnlyEvidence: 0,
+            unsupportedEvidence: 0,
+            sameFileEvidence: 0,
+            duplicateEvidence: 0,
+            complete: false,
+        };
     for (const [callerFile, refs] of allRefs) {
-        const callerSymbols = allSymbols.get(callerFile) ?? [];
+        const callerFileKey = normalizeMapKey(callerFile);
+        const callerSymbols = canonicalSymbols.get(callerFileKey) ?? [];
         for (const ref of refs) {
             totalRefs++;
-            // ref.symbolId is "filePath:name" from the extractor; we only need the name.
-            const refName = ref.symbolId.split(":").pop() ?? ref.symbolId;
-            if (STDLIB_NAMES.has(refName) || !refName)
+            if (!hasInputCoverage) {
+                // Legacy callers do not carry an evidenceKind, but each ref is still
+                // raw call-graph evidence and must contribute to coverage totals.
+                coverage.totalEvidence++;
+                if (ref.evidenceKind === "references" || ref.referenceKind === "type")
+                    coverage.referencesEvidence++;
+                else
+                    coverage.callsEvidence++;
+            }
+            if (ref.referenceKind === "type") {
+                if (!hasInputCoverage)
+                    coverage.typeOnlyEvidence++;
                 continue;
-            const defs = defIndex.get(refName);
-            if (!defs || defs.length === 0) {
-                unresolvedRefs++;
+            }
+            if (ref.evidenceKind && ref.referenceKind !== "call") {
+                if (!hasInputCoverage)
+                    coverage.unsupportedEvidence++;
                 continue;
             }
-            // Only cross-file refs are interesting for the call graph.
-            const crossFileDefs = defs.filter((d) => !d.startsWith(`${callerFile}:`));
-            if (crossFileDefs.length === 0)
+            const candidates = [];
+            if (ref.targetId) {
+                // Canonical graph identity is authoritative. Never recover a name by
+                // splitting an id: symbol ids contain kind and line components.
+                const callee = defIndex.byId.get(ref.targetId);
+                if (!callee || ref.resolution === "name-only" || ref.resolution === "unresolved") {
+                    if (!hasInputCoverage) {
+                        unresolvedRefs++;
+                        coverage.unresolvedEvidence++;
+                    }
+                    continue;
+                }
+                candidates.push({
+                    callee,
+                    resolution: ref.resolution ?? "exact",
+                    candidateCount: 1,
+                });
+            }
+            else {
+                // Compatibility for pre-#1070 callers that supplied only name refs.
+                // There is no typed/import evidence to select one definition, so retain
+                // every cross-file candidate and discount each edge. Picking [0] made
+                // graph iteration order decide which caller was reported.
+                const refName = ref.symbolName ?? parseSymbolKey(ref.symbolId, callerFile).symbolName ?? "";
+                if (STDLIB_NAMES.has(refName) || !refName) {
+                    if (!hasInputCoverage)
+                        coverage.unsupportedEvidence++;
+                    continue;
+                }
+                const defs = defIndex.byName.get(refName);
+                if (!defs || defs.length === 0) {
+                    if (!hasInputCoverage) {
+                        unresolvedRefs++;
+                        coverage.unresolvedEvidence++;
+                    }
+                    continue;
+                }
+                const crossFileDefs = defs
+                    .map((id) => defIndex.byId.get(id))
+                    .filter((candidate) => candidate !== undefined && normalizeMapKey(candidate.filePath) !== callerFileKey);
+                if (crossFileDefs.length === 0) {
+                    if (!hasInputCoverage)
+                        coverage.unsupportedEvidence++;
+                    continue;
+                }
+                const resolution = crossFileDefs.length === 1 ? "exact" : "name-only";
+                for (const callee of crossFileDefs) {
+                    candidates.push({ callee, resolution, candidateCount: crossFileDefs.length });
+                }
+            }
+            if (ref.evidenceKind && candidates.some(({ resolution }) => resolution === "name-only")) {
+                if (!hasInputCoverage) {
+                    unresolvedRefs++;
+                    coverage.unresolvedEvidence++;
+                }
                 continue;
-            const weight = 1.0 / crossFileDefs.length;
-            // Enclosing function is the caller; fall back to file-level key.
-            const enclosing = findEnclosingSymbol(callerSymbols, ref.line);
-            const callerKey = enclosing
-                ? `${callerFile}:${enclosing.name}`
-                : `file:${callerFile}`;
-            for (const calleeKey of crossFileDefs) {
-                const calleeFile = calleeKey.split(":").slice(0, -1).join(":");
-                const calleeSymbol = calleeKey.split(":").pop() ?? calleeKey;
-                // Bidirectional maps (deduplicated by Set).
-                const callerCallees = callees.get(callerKey) ?? new Set();
-                callerCallees.add(calleeKey);
-                callees.set(callerKey, callerCallees);
-                const calleeCallers = callers.get(calleeKey) ?? new Set();
-                calleeCallers.add(callerKey);
-                callers.set(calleeKey, calleeCallers);
-                // Weighted in-degree accumulation.
-                inDegree.set(calleeKey, (inDegree.get(calleeKey) ?? 0) + weight);
-                edges.push({
+            }
+            const caller = ref.callerSymbolId
+                ? defIndex.byId.get(ref.callerSymbolId)
+                : undefined;
+            const enclosing = caller ?? findEnclosingSymbol(callerSymbols, ref.line);
+            const callerKey = enclosing?.id ?? `file:${callerFile}`;
+            let producedEdge = false;
+            let duplicateRef = false;
+            for (const { callee, resolution, candidateCount } of candidates) {
+                if (normalizeMapKey(callee.filePath) === callerFileKey) {
+                    // This projection is intentionally cross-file-only. A canonical
+                    // same-file target is resolved by the source graph, but is represented
+                    // by an explicit coverage category rather than as unsupported evidence.
+                    // That keeps the projection contract while allowing complete coverage
+                    // to gate user-facing cross-file impact honestly.
+                    coverage.sameFileEvidence++;
+                    if (hasInputCoverage) {
+                        coverage.eligibleEvidence--;
+                        coverage.resolvedEvidence--;
+                    }
+                    continue;
+                }
+                producedEdge = true;
+                const pairKey = `${callerKey}\u0000${callee.id}`;
+                const existing = edgeByPair.get(pairKey);
+                if (existing) {
+                    existing.evidenceCount = (existing.evidenceCount ?? 1) + 1;
+                    existing.evidenceKind = existing.evidenceKind === ref.evidenceKind
+                        ? existing.evidenceKind
+                        : "mixed";
+                    // Duplicate evidence is a property of the logical pair, not of
+                    // whether the producer happened to tag the record. Keep the edge,
+                    // coverage, and centrality views consistent for legacy refs too.
+                    duplicateRef = true;
+                    continue;
+                }
+                const weight = ref.evidenceKind ? 1 : 1 / Math.max(1, candidateCount);
+                const edge = {
                     callerFile,
                     callerSymbol: enclosing?.name,
                     callerKey,
-                    calleeFile,
-                    calleeSymbol,
-                    calleeKey,
+                    callerKind: enclosing?.kind,
+                    callerLine: enclosing?.line,
+                    callerColumn: enclosing?.column,
+                    calleeFile: callee.filePath,
+                    calleeSymbol: callee.name,
+                    calleeKey: callee.id,
+                    calleeKind: callee.kind,
+                    calleeLine: callee.line,
+                    calleeColumn: callee.column,
+                    evidenceKind: ref.evidenceKind,
+                    resolution,
+                    evidenceCount: 1,
                     weight,
-                });
+                };
+                edgeByPair.set(pairKey, edge);
+                const callerCallees = callees.get(callerKey) ?? new Set();
+                callerCallees.add(callee.id);
+                callees.set(callerKey, callerCallees);
+                const calleeCallers = callers.get(callee.id) ?? new Set();
+                calleeCallers.add(callerKey);
+                callers.set(callee.id, calleeCallers);
+                inDegree.set(callee.id, (inDegree.get(callee.id) ?? 0) + weight);
+            }
+            if (!hasInputCoverage && producedEdge) {
+                // Legacy name-only ambiguity can fan one raw record out to several
+                // weighted edges. Coverage remains a count of raw records, so account
+                // for eligibility and duplicates once per reference, not once per
+                // candidate edge.
+                coverage.eligibleEvidence++;
+                coverage.resolvedEvidence++;
+                if (duplicateRef)
+                    coverage.duplicateEvidence++;
             }
+            if (hasInputCoverage && producedEdge && duplicateRef)
+                coverage.duplicateEvidence++;
         }
     }
+    // With adapter-supplied coverage, totalRefs is the raw evidence count. Some
+    // raw records (for example an external node with no caller file) cannot be
+    // represented in allRefs, but they must not disappear from accounting.
+    if (hasInputCoverage)
+        totalRefs = coverage.totalEvidence;
+    const languagesKnownComplete = Object.values(coverage.languages ?? {}).every((status) => status === "complete");
+    coverage.complete = coverage.complete && hasInputCoverage &&
+        coverage.unsupportedEvidence === 0 && languagesKnownComplete &&
+        (allSymbols.size > 0 || coverage.totalEvidence > 0);
     return {
         callees,
         callers,
         inDegree,
-        edges,
-        unresolvedRefs,
+        edges: [...edgeByPair.values()],
+        unresolvedRefs: hasInputCoverage ? coverage.unresolvedEvidence : unresolvedRefs,
         totalRefs,
+        coverage,
         builtAt: new Date().toISOString(),
     };
 }
@@ -240,39 +410,252 @@ function metaFilePath(cwd) {
     return path.join(getProjectDataDir(cwd), "cache", "call-graph.meta.json");
 }
 /**
- * Persist the call graph to disk with per-file mtime tracking.
- * On the next session-start, stale files can be identified without a full rebuild.
+ * Persist a call-graph projection. Current callers pass the canonical
+ * review-graph identity. There is deliberately no independent file/mtime
+ * freshness argument: callers must use the review graph's canonical identity.
  */
-export function saveCallGraph(cwd, graph, fileMtimes) {
+export function saveCallGraph(cwd, graph, identity) {
     const cacheFile = cacheFilePath(cwd);
     const metaFile = metaFilePath(cwd);
     try {
         fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
         const persisted = {
-            version: CACHE_VERSION,
+            version: CALL_GRAPH_CACHE_VERSION,
             builtAt: graph.builtAt,
-            fileMtimes: Object.fromEntries(fileMtimes),
+            reviewGraphVersion: identity.reviewGraphVersion,
+            reviewGraphSignature: identity.reviewGraphSignature,
             edges: graph.edges,
             callees: [...graph.callees.entries()].map(([k, v]) => [k, [...v]]),
             callers: [...graph.callers.entries()].map(([k, v]) => [k, [...v]]),
             inDegree: [...graph.inDegree.entries()],
+            totalRefs: graph.totalRefs,
+            unresolvedRefs: graph.unresolvedRefs,
+            coverage: graph.coverage,
         };
-        fs.writeFileSync(cacheFile, JSON.stringify(persisted), "utf-8");
-        fs.writeFileSync(metaFile, JSON.stringify({ savedAt: new Date().toISOString(), edgeCount: graph.edges.length }), "utf-8");
+        writeFileAtomic(cacheFile, JSON.stringify(persisted));
+        writeFileAtomic(metaFile, JSON.stringify({ savedAt: new Date().toISOString(), edgeCount: graph.edges.length }));
     }
     catch {
         // Non-fatal — next session rebuilds from scratch.
     }
 }
+function inferLegacyCoverage(edges) {
+    let weightedTotalEvidence = 0;
+    let weightedReferencesEvidence = 0;
+    let weightedDuplicateEvidence = 0;
+    for (const edge of edges) {
+        const count = Number.isFinite(edge.evidenceCount) && (edge.evidenceCount ?? 0) > 0
+            ? Math.floor(edge.evidenceCount)
+            : 1;
+        const weight = Number.isFinite(edge.weight) && edge.weight >= 0 ? edge.weight : 1;
+        weightedTotalEvidence += count * weight;
+        weightedDuplicateEvidence += Math.max(0, count - 1) * weight;
+        if (edge.evidenceKind === "references")
+            weightedReferencesEvidence += count * weight;
+    }
+    const totalEvidence = Math.max(0, Math.round(weightedTotalEvidence));
+    const referencesEvidence = Math.max(0, Math.round(weightedReferencesEvidence));
+    const duplicateEvidence = Math.max(0, Math.round(weightedDuplicateEvidence));
+    return {
+        totalEvidence,
+        callsEvidence: totalEvidence - referencesEvidence,
+        referencesEvidence,
+        eligibleEvidence: totalEvidence,
+        resolvedEvidence: totalEvidence,
+        unresolvedEvidence: 0,
+        typeOnlyEvidence: 0,
+        unsupportedEvidence: 0,
+        sameFileEvidence: 0,
+        duplicateEvidence,
+        // A legacy graph can still be queried, but it cannot prove that the old
+        // extractor covered every source/reference kind.
+        complete: false,
+    };
+}
+function loadCoverage(rawCoverage, edges) {
+    const inferred = inferLegacyCoverage(edges);
+    return rawCoverage
+        ? {
+            ...inferred,
+            ...rawCoverage,
+        }
+        : inferred;
+}
+function finiteCount(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function countsMatch(left, right) {
+    return Math.abs(left - right) <= 1e-9 * Math.max(1, Math.abs(left), Math.abs(right));
+}
+function validatePersistedCallGraph(raw, coverage) {
+    const nonEmptyString = (value) => typeof value === "string" && value.trim().length > 0;
+    const enumValue = (value, values) => typeof value === "string" && values.includes(value);
+    const edgeKinds = ["calls", "references", "mixed"];
+    const resolutions = ["exact", "import", "receiver-type", "name-only", "unresolved"];
+    if (!raw || raw.version !== CALL_GRAPH_CACHE_VERSION || !nonEmptyString(raw.builtAt))
+        return false;
+    if (!nonEmptyString(raw.reviewGraphVersion) || !nonEmptyString(raw.reviewGraphSignature))
+        return false;
+    if (raw.coverage !== undefined &&
+        (!raw.coverage || typeof raw.coverage !== "object" || Array.isArray(raw.coverage)))
+        return false;
+    if (!Array.isArray(raw.edges) || !Array.isArray(raw.callees) || !Array.isArray(raw.callers) || !Array.isArray(raw.inDegree))
+        return false;
+    const coverageValues = [
+        coverage.totalEvidence,
+        coverage.callsEvidence,
+        coverage.referencesEvidence,
+        coverage.eligibleEvidence,
+        coverage.resolvedEvidence,
+        coverage.unresolvedEvidence,
+        coverage.typeOnlyEvidence,
+        coverage.unsupportedEvidence,
+        coverage.sameFileEvidence,
+        coverage.duplicateEvidence,
+    ];
+    if (typeof coverage.complete !== "boolean" || coverageValues.some((value) => !finiteCount(value)))
+        return false;
+    if (coverage.languages !== undefined &&
+        (!coverage.languages || typeof coverage.languages !== "object" || Array.isArray(coverage.languages) ||
+            Object.entries(coverage.languages).some(([language, status]) => !nonEmptyString(language) || !enumValue(status, ["complete", "partial", "unavailable"]))))
+        return false;
+    if (coverage.callsEvidence + coverage.referencesEvidence !== coverage.totalEvidence)
+        return false;
+    if (coverage.resolvedEvidence > coverage.eligibleEvidence)
+        return false;
+    if (coverage.eligibleEvidence !== coverage.resolvedEvidence)
+        return false;
+    if (coverage.resolvedEvidence + coverage.unresolvedEvidence + coverage.typeOnlyEvidence + coverage.unsupportedEvidence + coverage.sameFileEvidence !== coverage.totalEvidence)
+        return false;
+    if (coverage.complete && coverage.unsupportedEvidence > 0)
+        return false;
+    if (coverage.complete && Object.values(coverage.languages ?? {}).some((status) => status !== "complete"))
+        return false;
+    const expectedCallees = new Map();
+    const expectedCallers = new Map();
+    const expectedInDegree = new Map();
+    const pairKeys = new Set();
+    let weightedEdgeEvidence = 0;
+    let weightedDuplicateEvidence = 0;
+    for (const edge of raw.edges) {
+        if (!edge || typeof edge !== "object" || !nonEmptyString(edge.callerKey) || !nonEmptyString(edge.calleeKey) ||
+            !nonEmptyString(edge.callerFile) || !nonEmptyString(edge.calleeFile) ||
+            !nonEmptyString(edge.calleeSymbol) || typeof edge.weight !== "number" || !Number.isFinite(edge.weight) || edge.weight <= 0 || edge.weight > 1)
+            return false;
+        if (edge.callerSymbol !== undefined && !nonEmptyString(edge.callerSymbol))
+            return false;
+        if (edge.callerKind !== undefined && !nonEmptyString(edge.callerKind))
+            return false;
+        if (edge.calleeKind !== undefined && !nonEmptyString(edge.calleeKind))
+            return false;
+        if (edge.evidenceKind !== undefined && !enumValue(edge.evidenceKind, edgeKinds))
+            return false;
+        if (edge.resolution !== undefined && !enumValue(edge.resolution, resolutions))
+            return false;
+        if (edge.evidenceCount !== undefined && (!finiteCount(edge.evidenceCount) || edge.evidenceCount < 1))
+            return false;
+        const evidenceCount = edge.evidenceCount ?? 1;
+        const callerIdentity = parseCanonicalSymbolKey(edge.callerKey, edge.callerFile);
+        const calleeIdentity = parseCanonicalSymbolKey(edge.calleeKey, edge.calleeFile);
+        if (normalizeMapKey(callerIdentity.filePath) !== normalizeMapKey(edge.callerFile) ||
+            normalizeMapKey(calleeIdentity.filePath) !== normalizeMapKey(edge.calleeFile) ||
+            (calleeIdentity.symbolName !== undefined && calleeIdentity.symbolName !== edge.calleeSymbol) ||
+            (callerIdentity.symbolName !== undefined && edge.callerSymbol !== undefined && callerIdentity.symbolName !== edge.callerSymbol))
+            return false;
+        const pair = `${edge.callerKey}\u0000${edge.calleeKey}`;
+        if (pairKeys.has(pair))
+            return false;
+        pairKeys.add(pair);
+        // Ambiguous legacy name-only evidence may fan one raw record out to
+        // multiple weighted edges. Weight the persisted evidence back to raw
+        // records so semantic validation agrees with coverage accounting.
+        weightedEdgeEvidence += evidenceCount * edge.weight;
+        weightedDuplicateEvidence += (evidenceCount - 1) * edge.weight;
+        const callees = expectedCallees.get(edge.callerKey) ?? new Set();
+        callees.add(edge.calleeKey);
+        expectedCallees.set(edge.callerKey, callees);
+        const callers = expectedCallers.get(edge.calleeKey) ?? new Set();
+        callers.add(edge.callerKey);
+        expectedCallers.set(edge.calleeKey, callers);
+        expectedInDegree.set(edge.calleeKey, (expectedInDegree.get(edge.calleeKey) ?? 0) + edge.weight);
+    }
+    if (!countsMatch(weightedEdgeEvidence, coverage.resolvedEvidence))
+        return false;
+    if (!countsMatch(weightedDuplicateEvidence, coverage.duplicateEvidence))
+        return false;
+    if (!countsMatch(coverage.totalEvidence, weightedEdgeEvidence + coverage.unresolvedEvidence + coverage.typeOnlyEvidence + coverage.unsupportedEvidence + coverage.sameFileEvidence))
+        return false;
+    if (raw.totalRefs !== undefined && !finiteCount(raw.totalRefs))
+        return false;
+    if (raw.unresolvedRefs !== undefined && !finiteCount(raw.unresolvedRefs))
+        return false;
+    if (raw.totalRefs !== undefined && raw.totalRefs !== coverage.totalEvidence)
+        return false;
+    if (raw.unresolvedRefs !== undefined && raw.unresolvedRefs !== coverage.unresolvedEvidence)
+        return false;
+    const readAdjacency = (entries) => {
+        const result = new Map();
+        if (!Array.isArray(entries))
+            return undefined;
+        for (const entry of entries) {
+            if (!Array.isArray(entry) || !nonEmptyString(entry[0]) || !Array.isArray(entry[1]) || entry[1].some((key) => !nonEmptyString(key)))
+                return undefined;
+            const keys = entry[1];
+            if (new Set(keys).size !== keys.length || result.has(entry[0]))
+                return undefined;
+            result.set(entry[0], new Set(keys));
+        }
+        return result;
+    };
+    const actualCallees = readAdjacency(raw.callees);
+    const actualCallers = readAdjacency(raw.callers);
+    if (!actualCallees || !actualCallers || actualCallees.size !== expectedCallees.size || actualCallers.size !== expectedCallers.size)
+        return false;
+    const sameSets = (actual, expected) => {
+        for (const [key, values] of expected) {
+            const got = actual.get(key);
+            if (!got || got.size !== values.size || [...values].some((value) => !got.has(value)))
+                return false;
+        }
+        return true;
+    };
+    if (!sameSets(actualCallees, expectedCallees) || !sameSets(actualCallers, expectedCallers))
+        return false;
+    const actualInDegree = new Map();
+    for (const entry of raw.inDegree) {
+        if (!Array.isArray(entry) || !nonEmptyString(entry[0]) || typeof entry[1] !== "number" || !Number.isFinite(entry[1]) || entry[1] < 0 || actualInDegree.has(entry[0]))
+            return false;
+        actualInDegree.set(entry[0], entry[1]);
+    }
+    if (actualInDegree.size !== expectedInDegree.size)
+        return false;
+    for (const [key, value] of expectedInDegree) {
+        if (actualInDegree.get(key) !== value)
+            return false;
+    }
+    return true;
+}
 /**
  * Load the persisted call graph from disk.
  * Returns undefined if the cache is missing, version-mismatched, or corrupt.
  */
-export function loadCallGraph(cwd) {
+export function loadCallGraph(cwd, expectedIdentity) {
     const cacheFile = cacheFilePath(cwd);
     try {
         const raw = JSON.parse(fs.readFileSync(cacheFile, "utf-8"));
-        if (raw.version !== CACHE_VERSION)
+        if (raw.version !== CALL_GRAPH_CACHE_VERSION)
+            return undefined;
+        if (typeof raw.reviewGraphVersion !== "string" || typeof raw.reviewGraphSignature !== "string")
+            return undefined;
+        const identity = {
+            reviewGraphVersion: raw.reviewGraphVersion,
+            reviewGraphSignature: raw.reviewGraphSignature,
+        };
+        if (expectedIdentity && (identity.reviewGraphVersion !== expectedIdentity.reviewGraphVersion ||
+            identity.reviewGraphSignature !== expectedIdentity.reviewGraphSignature))
+            return undefined;
+        const coverage = loadCoverage(raw.coverage, raw.edges);
+        if (!validatePersistedCallGraph(raw, coverage))
             return undefined;
         return {
             graph: {
@@ -280,46 +663,15 @@ export function loadCallGraph(cwd) {
                 callers: new Map(raw.callers.map(([k, v]) => [k, new Set(v)])),
                 inDegree: new Map(raw.inDegree),
                 edges: raw.edges,
-                unresolvedRefs: 0,
-                totalRefs: 0,
+                unresolvedRefs: raw.unresolvedRefs ?? coverage.unresolvedEvidence,
+                totalRefs: raw.totalRefs ?? coverage.totalEvidence,
+                coverage,
                 builtAt: raw.builtAt,
             },
-            fileMtimes: new Map(Object.entries(raw.fileMtimes)),
+            identity,
         };
     }
     catch {
         return undefined;
     }
 }
-/**
- * Returns the set of file paths whose mtime has changed since the cache was saved.
- * Files not in the mtime map are treated as new (stale).
- */
-export function staleFiles(fileMtimes, currentFiles) {
-    return currentFiles.filter((f) => {
-        const cached = fileMtimes.get(f);
-        if (cached === undefined)
-            return true; // new file
-        try {
-            return fs.statSync(f).mtimeMs !== cached;
-        }
-        catch {
-            return true; // deleted or unreadable
-        }
-    });
-}
-/**
- * Read current mtimes for a set of files.
- */
-export function readMtimes(files) {
-    const mtimes = new Map();
-    for (const f of files) {
-        try {
-            mtimes.set(f, fs.statSync(f).mtimeMs);
-        }
-        catch {
-            // skip
-        }
-    }
-    return mtimes;
-}