ucn 4.0.2 → 4.1.0

package/core/analysis.js

@@ -12,7 +12,7 @@ const path = require('path');
 const { execFileSync } = require('child_process');
 const { parse } = require('./parser');
 const { detectLanguage, langTraits } = require('../languages');
-const { NON_CALLABLE_TYPES, addTestExclusions, countTextBlindspots } = require('./shared');
+const { NON_CALLABLE_TYPES, addTestExclusions, countTextBlindspots, codeUnitCompare } = require('./shared');
 const { computeReachability, symbolKey } = require('./entrypoints');
 const { getLanguageModule } = require('../languages');
 
@@ -154,10 +154,12 @@ function tagCallersReachable(callers, reachableSet) {
     for (const c of callers) {
         if (c.callerFile && c.callerStartLine != null) {
             c.reachable = reachableSet.has(symbolKey(c.callerFile, c.callerStartLine));
-        } else {
-            // Module-level / unknown caller — treat as unreachable (no enclosing function)
-            c.reachable = false;
         }
+        // Module-level callers get NO verdict (fix #256, rich-measured:
+        // every examples/*.py module-level `console.print(table)` rendered
+        // [unreachable]): the site executes at IMPORT time — function-graph
+        // reachability cannot speak for it, and "unreachable" invites
+        // deleting live code. Formatters mark only `reachable === false`.
     }
     return callers;
 }
@@ -255,7 +257,7 @@ function callNotResolvedEntries(index, account, options = {}) {
     return entries.map(e => {
         let content = '';
         try {
-            content = (index._readFile(e.file).split('\n')[e.line - 1] || '').trim();
+            content = (index._getFileLines(e.file)[e.line - 1] || '').trim();
         } catch { /* unreadable since scan — keep bare */ }
         return {
             file: e.file,
@@ -286,6 +288,13 @@ function context(index, name, options = {}) {
         return null;
     }
 
+    // Default includeMethods like about/impact (fix #234, campaign-measured:
+    // the same pinned method was confirmed in about but unverified in
+    // context — the tier depended on which command asked): true for method
+    // targets, where method calls are the primary invocation form.
+    const includeMethods = options.includeMethods ??
+        !!(def.isMethod || def.type === 'method' || def.className);
+
     // Special handling for class/struct/interface types
     if (['class', 'struct', 'interface', 'type'].includes(def.type)) {
         const methods = index.findMethodsForType(name);
@@ -293,7 +302,7 @@ function context(index, name, options = {}) {
         // Pin caller resolution to the resolved class definition — same as the
         // function path below. Without this, same-name classes in other files
         // conflate (their usages attribute to whichever def displays).
-        let typeCallers = index.findCallers(name, { includeMethods: options.includeMethods, includeUncertain: options.includeUncertain, collectAccount: true, targetDefinitions: [def] });
+        let typeCallers = index.findCallers(name, { includeMethods, includeUncertain: options.includeUncertain, collectAccount: true, targetDefinitions: [def] });
         const rawTypeCallers = typeCallers;
         const typeFilteredByFlag = { exclude: 0, minConfidence: 0, unreachableOnly: 0 };
         // Tier partition — same contract as the function path: constructor/usage
@@ -313,7 +322,7 @@ function context(index, name, options = {}) {
         const byFileLine = (a, b) => {
             const fa = a.relativePath || a.file || '';
             const fb = b.relativePath || b.file || '';
-            if (fa !== fb) return fa.localeCompare(fb);
+            if (fa !== fb) return codeUnitCompare(fa, fb);
             return (a.line || 0) - (b.line || 0);
         };
         const typeAccount = composeAccount(index, name, rawTypeCallers,
@@ -352,7 +361,7 @@ function context(index, name, options = {}) {
 
     const stats = { uncertain: 0 };
     let callers = index.findCallers(name, {
-        includeMethods: options.includeMethods,
+        includeMethods,
         includeUncertain: options.includeUncertain,
         stats,
         targetDefinitions: [def],
@@ -360,7 +369,11 @@ function context(index, name, options = {}) {
         // --all lifts the unverified enrichment cap (content + caller lookup)
         unverifiedEnrichLimit: options.all ? Infinity : undefined,
     });
-    let callees = index.findCallees(def, { includeMethods: options.includeMethods, includeUncertain: options.includeUncertain, stats });
+    // Callee side runs the contract too (v4): uncertain/unresolved calls in
+    // the def's scope become VISIBLE unverifiedCallees entries + a conserved
+    // per-node calleeAccount instead of silently dropping (#223 machinery).
+    let callees = index.findCallees(def, { includeMethods, includeUncertain: options.includeUncertain, stats, collectAccount: true });
+    const rawCallees = callees;
     // Pre-display-filter result for the conservation account (filters below
     // build new arrays and would lose the non-enumerable accountRaw).
     const rawCallers = callers;
@@ -405,7 +418,7 @@ function context(index, name, options = {}) {
     const byFileLine = (a, b) => {
         const fa = a.relativePath || a.file || '';
         const fb = b.relativePath || b.file || '';
-        if (fa !== fb) return fa.localeCompare(fb);
+        if (fa !== fb) return codeUnitCompare(fa, fb);
         return (a.line || 0) - (b.line || 0);
     };
     callers = [...callers].sort(byFileLine);
@@ -417,7 +430,7 @@ function context(index, name, options = {}) {
         // Tiebreaker: file then line, for determinism
         const fa = a.relativePath || a.file || '';
         const fb = b.relativePath || b.file || '';
-        if (fa !== fb) return fa.localeCompare(fb);
+        if (fa !== fb) return codeUnitCompare(fa, fb);
         return (a.startLine || 0) - (b.startLine || 0);
     });
 
@@ -433,9 +446,9 @@ function context(index, name, options = {}) {
     // Optional: filter to unreachable-only (helps surface dead-path callers/callees)
     if (options.unreachableOnly) {
         const before = callers.length;
-        callers = callers.filter(c => !c.reachable);
+        callers = callers.filter(c => c.reachable === false);
         filteredByFlag.unreachableOnly = before - callers.length;
-        callees = callees.filter(c => !c.reachable);
+        callees = callees.filter(c => c.reachable === false);
     }
 
     // Conservation account: reconciles the caller answer against the text
@@ -470,6 +483,7 @@ function context(index, name, options = {}) {
         callers,
         unverifiedCallers,
         callees,
+        unverifiedCallees: rawCallees.unverifiedCallees || [],
         callerHistogram,
         calleeHistogram,
         meta: {
@@ -478,9 +492,10 @@ function context(index, name, options = {}) {
             dynamicImports,
             uncertain: stats.uncertain,
             confidenceFiltered,
-            includeMethods: !!options.includeMethods,
+            includeMethods: !!includeMethods,
             projectLanguage: index._getPredominantLanguage(),
             account,
+            calleeAccount: rawCallees.calleeAccount,
             // No detected entry points (e.g. library code) — reachability
             // markers are meaningless and suppressed by formatters.
             hasEntrypoints: reachableSet.size > 0,
@@ -492,6 +507,19 @@ function context(index, name, options = {}) {
         }
     };
 
+    // Constructor pins surface their invocation sites under the CLASS pin
+    // (`new Widget()` indexes under 'Widget' — the fix #239 liveness rule;
+    // fix #254 makes it discoverable): a bare empty answer sent readers
+    // hunting for callers the class pin already has.
+    if (def.className && callers.length === 0 &&
+        (def.type === 'constructor' || name === 'constructor' || name === '__init__') &&
+        index.getCalleeFiles(def.className)) {
+        warnings.push({
+            type: 'hint',
+            message: `Constructor invocations (\`new ${def.className}(...)\` / \`${def.className}(...)\`) are indexed under the class name — query \`${def.className}\` for the call sites.`,
+        });
+    }
+
     if (warnings.length > 0) {
         result.warnings = warnings;
     }
@@ -517,7 +545,12 @@ function smart(index, name, options = {}) {
     }
     const code = index.extractCode(def);
     const stats = { uncertain: 0 };
-    const callees = index.findCallees(def, { includeMethods: options.includeMethods, includeUncertain: options.includeUncertain, stats });
+    // Method-target default like about/impact/context (fix #234).
+    const includeMethods = options.includeMethods ??
+        !!(def.isMethod || def.type === 'method' || def.className);
+    // Callee contract (v4): uncertain/unresolved calls surface as visible
+    // unverifiedCallees + a conserved calleeAccount, never a silent drop.
+    const callees = index.findCallees(def, { includeMethods, includeUncertain: options.includeUncertain, stats, collectAccount: true });
 
     const filesInScope = new Set([def.file]);
     callees.forEach(c => filesInScope.add(c.file));
@@ -557,6 +590,7 @@ function smart(index, name, options = {}) {
         }
     }
 
+    const smartUnverified = callees.unverifiedCallees || [];
     return {
         target: {
             ...def,
@@ -564,12 +598,14 @@ function smart(index, name, options = {}) {
         },
         dependencies,
         types,
+        unverifiedCallees: smartUnverified,
         meta: {
-            complete: stats.uncertain === 0 && dynamicImports === 0,
+            complete: stats.uncertain === 0 && dynamicImports === 0 && smartUnverified.length === 0,
             skipped: 0,
             dynamicImports,
             uncertain: stats.uncertain,
-            projectLanguage: index._getPredominantLanguage()
+            projectLanguage: index._getPredominantLanguage(),
+            calleeAccount: callees.calleeAccount
         }
     };
     } finally { index._endOp(); }
@@ -668,6 +704,10 @@ function related(index, name, options = {}) {
         return null;
     }
     const related = {
+        // Advisory command (v4 two-tier surface): ranked similarity
+        // heuristics, not a verified claim — formatters print the label,
+        // JSON consumers read the field.
+        advisory: 'similarity-heuristics',
         target: {
             name: def.name,
             file: def.relativePath,
@@ -696,6 +736,12 @@ function related(index, name, options = {}) {
         related.sameFile.sort((a, b) =>
             Math.abs(a.line - def.startLine) - Math.abs(b.line - def.startLine)
         );
+        // --top caps every section the same way (fix #230 — sameFile ignored
+        // it, so JSON consumers got the full list while similarNames et al.
+        // were capped).
+        const sameFileLimit = options.top || (options.all ? Infinity : 10);
+        related.sameFileTotal = related.sameFile.length;
+        if (related.sameFile.length > sameFileLimit) related.sameFile = related.sameFile.slice(0, sameFileLimit);
     }
 
     // 2. Similar names (shared prefix/suffix, camelCase similarity)
@@ -868,144 +914,15 @@ function impact(index, name, options = {}) {
         impactAccountRaw = callerResults.accountRaw;
         impactRoutedUnverified = callerResults.unverifiedEntries || [];
 
-        // When the target definition has a className (including Go/Rust methods which
-        // now get className from receiver), filter out method calls whose receiver
-        // clearly belongs to a different type. This helps with common method names
-        // like .close(), .get() etc. where many types have the same method.
-        if (def.className) {
-            const targetClassName = def.className;
-            // Pre-compute how many types share this method name
-            const _impMethodDefs = index.symbols.get(name);
-            const _impClassNames = new Set();
-            if (_impMethodDefs) {
-                for (const d of _impMethodDefs) {
-                    if (d.className) _impClassNames.add(d.className);
-                    else if (d.receiver) _impClassNames.add(d.receiver.replace(/^\*/, ''));
-                }
-            }
-            const keepForTargetClass = (c) => {
-                // Keep non-method calls and self/this/cls calls (already resolved by findCallers)
-                if (!c.isMethod) return true;
-                const r = c.receiver;
-                if (r && ['self', 'cls', 'this', 'super'].includes(r)) return true;
-                // Use receiverType from findCallers when available (Go/Java/Rust type inference)
-                if (c.receiverType) {
-                    return c.receiverType === targetClassName ? 'strong' : false;
-                }
-                // No receiver (chained/complex expression): only include if method is
-                // unique or rare across types — otherwise too many false positives
-                if (!r) {
-                    return _impClassNames.size <= 1;
-                }
-                // Check if receiver matches the target class name (case-insensitive camelCase convention)
-                if (r.toLowerCase().includes(targetClassName.toLowerCase())) return true;
-                // Check if receiver is an instance of the target class using local variable type inference
-                if (c.callerFile) {
-                    const callerDef = c.callerStartLine ? { file: c.callerFile, startLine: c.callerStartLine, endLine: c.callerEndLine } : null;
-                    if (callerDef) {
-                        const callerCalls = index.getCachedCalls(c.callerFile);
-                        if (callerCalls && Array.isArray(callerCalls)) {
-                            const localTypes = new Map();
-                            for (const call of callerCalls) {
-                                if (call.line >= callerDef.startLine && call.line <= callerDef.endLine) {
-                                    if (!call.isMethod && !call.receiver) {
-                                        const syms = index.symbols.get(call.name);
-                                        if (syms && syms.some(s => s.type === 'class')) {
-                                            // Found a constructor call — check for assignment pattern
-                                            const fileEntry = index.files.get(c.callerFile);
-                                            if (fileEntry) {
-                                                const content = index._readFile(c.callerFile);
-                                                const lines = content.split('\n');
-                                                const line = lines[call.line - 1] || '';
-                                                // Match "var = ClassName(...)" or "var = new ClassName(...)" or "Type var = new ClassName<>(...)"
-                                                const m = line.match(/(\w+)\s*=\s*(?:await\s+)?(?:new\s+)?(\w+)\s*(?:<[^>]*>)?\s*\(/);
-                                                if (m && m[2] === call.name) {
-                                                    localTypes.set(m[1], call.name);
-                                                }
-                                            }
-                                        }
-                                    }
-                                }
-                            }
-                            const receiverType = localTypes.get(r);
-                            if (receiverType) {
-                                return receiverType === targetClassName ? 'strong' : false;
-                            }
-                        }
-                    }
-                }
-                // Check class field declarations for receiver type: private DataService service
-                if (c.callerFile) {
-                    const callerEnclosing = index.findEnclosingFunction(c.callerFile, c.line, true);
-                    if (callerEnclosing?.className) {
-                        const classSyms = index.symbols.get(callerEnclosing.className);
-                        if (classSyms) {
-                            const classDef = classSyms.find(s => s.type === 'class' || s.type === 'struct' || s.type === 'interface');
-                            if (classDef) {
-                                const content = index._readFile(c.callerFile);
-                                const lines = content.split('\n');
-                                // Scan class body for field declarations matching the receiver
-                                for (let li = classDef.startLine - 1; li < (classDef.endLine || classDef.startLine + 50) && li < lines.length; li++) {
-                                    const line = lines[li];
-                                    // Match Java/TS field: [modifiers] TypeName<...> receiverName [= ...]
-                                    const fieldMatch = line.match(new RegExp(`\\b(\\w+)(?:<[^>]*>)?\\s+${r.replace(/[.*+?^${}()|[\]\\]/g, '\\\\$&')}\\s*[;=]`));
-                                    if (fieldMatch) {
-                                        const fieldType = fieldMatch[1];
-                                        if (fieldType === targetClassName) return 'strong';
-                                        break;
-                                    }
-                                }
-                            }
-                        }
-                    }
-                }
-                // Check parameter type annotations: def foo(tracker: SourceTracker) → tracker.record()
-                if (c.callerFile && c.callerStartLine) {
-                    const callerSymbol = index.findEnclosingFunction(c.callerFile, c.line, true);
-                    if (callerSymbol && callerSymbol.paramsStructured) {
-                        for (const param of callerSymbol.paramsStructured) {
-                            if (param.name === r && param.type) {
-                                // Check if the type annotation contains the target class name
-                                const typeMatches = param.type.match(/\b([A-Za-z_]\w*)\b/g);
-                                if (typeMatches && typeMatches.some(t => t === targetClassName)) {
-                                    return 'strong';
-                                }
-                                // Type annotation exists but doesn't match target class — filter out
-                                return false;
-                            }
-                        }
-                    }
-                }
-                // Unique method heuristic: if the called method exists on exactly one class/type
-                // and it matches the target, include the call (no other class could match)
-                if (_impClassNames.size === 1 && _impClassNames.has(targetClassName)) {
-                    return true;
-                }
-                // Type-scoped query but receiver type unknown — filter it out.
-                // Unknown receivers are likely unrelated.
-                return false;
-            };
-            // Conservation: post-hoc rejects are positive type-mismatch evidence —
-            // they MOVE into the excluded bucket instead of vanishing. Survivors
-            // verified by STRONG evidence (receiverType / local constructor /
-            // field declaration / param annotation match) are upgraded to the
-            // confirmed tier — the filter just proved the receiver's type.
-            callerResults = callerResults.filter(c => {
-                const keep = keepForTargetClass(c);
-                if (!keep) {
-                    impactPostHocExcluded.push({ file: c.file, line: c.line, reason: 'receiver-type-mismatch' });
-                    return false;
-                }
-                if (keep === 'strong' && c.tier === 'unverified') {
-                    c.tier = 'confirmed';
-                    c.resolution = 'receiver-hint';
-                    c.confidence = 0.80;
-                }
-                return true;
-            });
-        }
+        // No post-hoc receiver filter here (fix #228, the #225 precedent):
+        // the engine's receiver physics (#198/#202/#204/#206/#219/#220) decide
+        // tier and exclusion inside findCallers with the pinned definition.
+        // The old hand-rolled filter re-derived receiver types with regexes
+        // and DROPPED confirmed field-hop/embedding callers that context and
+        // about kept — impact answered differently from its siblings on the
+        // same pin.
 
-        callSites = [];
+        callSites = [];        callSites = [];
         for (const c of callerResults) {
             const analysis = index.analyzeCallSite(
                 { file: c.file, relativePath: c.relativePath, line: c.line, content: c.content },
@@ -1143,7 +1060,7 @@ function impact(index, name, options = {}) {
         });
     }
     unverifiedSites.sort((a, b) => {
-        if (a.file !== b.file) return a.file.localeCompare(b.file);
+        if (a.file !== b.file) return codeUnitCompare(a.file, b.file);
         return (a.line || 0) - (b.line || 0);
     });
 
@@ -1164,13 +1081,12 @@ function impact(index, name, options = {}) {
     for (const site of filteredSites) {
         if (site.callerFile && site.callerStartLine != null) {
             site.reachable = impactReachable.has(symbolKey(site.callerFile, site.callerStartLine));
-        } else {
-            site.reachable = false;
         }
+        // Module-level sites: no verdict — import-time execution (fix #256).
     }
     if (options.unreachableOnly) {
         const before = filteredSites.length;
-        filteredSites = filteredSites.filter(s => !s.reachable);
+        filteredSites = filteredSites.filter(s => s.reachable === false);
         impactFilteredByFlag.unreachableOnly = before - filteredSites.length;
     }
     const callerHistogram = buildHistogram(filteredSites);
@@ -1205,7 +1121,7 @@ function impact(index, name, options = {}) {
         }));
     if (impactNotResolved.length > 0) {
         unverifiedSites = [...unverifiedSites, ...impactNotResolved].sort((a, b) => {
-            if (a.file !== b.file) return a.file.localeCompare(b.file);
+            if (a.file !== b.file) return codeUnitCompare(a.file, b.file);
             return (a.line || 0) - (b.line || 0);
         });
     }
@@ -1266,7 +1182,7 @@ function impact(index, name, options = {}) {
         callerHistogram,
         // Stable ordering: files alphabetical, sites by line ascending. Documented contract.
         byFile: Array.from(byFile.entries())
-            .sort((a, b) => a[0].localeCompare(b[0]))
+            .sort((a, b) => codeUnitCompare(a[0], b[0]))
             .map(([file, sites]) => ({
                 file,
                 count: sites.length,
@@ -1359,9 +1275,14 @@ function about(index, name, options = {}) {
             const extra = visibleOthers.length - shown.length;
             const alsoIn = shown.map(d => `${d.relativePath}:${d.startLine}`).join(', ');
             const suffix = extra > 0 ? `, and ${extra} more` : '';
+            // Same-file collisions can't be resolved with file= (fix #246).
+            const allSameFile = visibleOthers.every(d => d.relativePath === primary.relativePath);
+            const hint = allSameFile
+                ? 'Use line= or class_name= to disambiguate.'
+                : 'Use file= to disambiguate.';
             aboutWarnings.push({
                 type: 'ambiguous',
-                message: `Found ${visible.length} definitions for "${name}". Using ${primary.relativePath}:${primary.startLine}. Also in: ${alsoIn}${suffix}. Use file= to disambiguate.`,
+                message: `Found ${visible.length} definitions for "${name}". Using ${primary.relativePath}:${primary.startLine}. Also in: ${alsoIn}${suffix}. ${hint}`,
                 alternatives: visibleOthers.map(d => ({ file: d.relativePath, line: d.startLine })),
             });
         }
@@ -1453,7 +1374,7 @@ function about(index, name, options = {}) {
         // Optional: filter to unreachable-only callers
         if (options.unreachableOnly) {
             const before = allCallers.length;
-            allCallers = allCallers.filter(c => !c.reachable);
+            allCallers = allCallers.filter(c => c.reachable === false);
             aboutFilteredByFlag.unreachableOnly = before - allCallers.length;
             // Apply same filter to shadows using their callerStartLine/file when available.
             // Shadows lack callerStartLine, so they're treated as reachable=false (conservative,
@@ -1468,6 +1389,17 @@ function about(index, name, options = {}) {
         aboutAccount = composeAccount(index, symbolName, rawCallers,
             aboutFilteredTotal > 0 ? { total: aboutFilteredTotal, byFlag: aboutFilteredByFlag } : undefined);
         unverifiedPool.push(...callNotResolvedEntries(index, aboutAccount, options));
+        // The USAGES fast path hardcodes references:0 (counting them needs a
+        // text scan) — but the account just DID that scan and classified the
+        // reference lines. Reconcile so the USAGES header never contradicts
+        // the ACCOUNT line rendered below it (fix #237: `about with_logging`
+        // said "0 references" while the account counted the @with_logging
+        // decorator application).
+        if (usagesByType && usagesByType.references === 0 &&
+            aboutAccount?.nonCall?.references > 0) {
+            usagesByType.references = aboutAccount.nonCall.references;
+            usagesByType.total += aboutAccount.nonCall.references;
+        }
         // Stash the post-filter total on allCallers so the result builder can use it.
         Object.defineProperty(allCallers, '__postFilterTotal', {
             value: allCallers.length + shadowSurvivors.length,
@@ -1502,7 +1434,7 @@ function about(index, name, options = {}) {
         unverifiedPool.sort((a, b) => {
             const fa = a.relativePath || '';
             const fb = b.relativePath || '';
-            if (fa !== fb) return fa.localeCompare(fb);
+            if (fa !== fb) return codeUnitCompare(fa, fb);
             return (a.line || 0) - (b.line || 0);
         });
         aboutUnverified = {
@@ -1701,6 +1633,17 @@ function about(index, name, options = {}) {
         completeness: detectCompleteness(index)
     };
 
+    // Constructor pins surface their invocation sites under the CLASS pin
+    // (`new Widget()` indexes under 'Widget' — fix #254, same hint as context).
+    if (primary.className && (callers?.length ?? 0) === 0 &&
+        (primary.type === 'constructor' || symbolName === 'constructor' || symbolName === '__init__') &&
+        index.getCalleeFiles(primary.className)) {
+        result.warnings = [...(result.warnings || []), {
+            type: 'hint',
+            message: `Constructor invocations (\`new ${primary.className}(...)\` / \`${primary.className}(...)\`) are indexed under the class name — query \`${primary.className}\` for the call sites.`,
+        }];
+    }
+
     return result;
     } finally { index._endOp(); }
 }
@@ -1743,13 +1686,22 @@ function diffImpact(index, options = {}) {
 
     let diffText;
     try {
-        diffText = execFileSync('git', diffArgs, { cwd: index.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+        // Capture stderr (fix #230): an invalid ref used to leak git's raw
+        // "fatal: ambiguous argument" straight to the terminal AND repeat it
+        // inside the error message.
+        diffText = execFileSync('git', diffArgs, {
+            cwd: index.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
     } catch (e) {
         // git diff exits non-zero when there are diff errors, but also for invalid refs
         if (e.stdout) {
             diffText = e.stdout;
         } else {
-            throw new Error(`git diff failed: ${e.message}`, { cause: e });
+            const fatal = String(e.stderr || '').split('\n').find(l => l.startsWith('fatal:'));
+            throw new Error(fatal
+                ? `git diff failed — ${fatal.replace(/^fatal:\s*/, '')}`
+                : `git diff failed: ${e.message}`, { cause: e });
         }
     }
 
@@ -1760,7 +1712,7 @@ function diffImpact(index, options = {}) {
             moduleLevelChanges: [],
             newFunctions: [],
             deletedFunctions: [],
-            summary: { modifiedFunctions: 0, deletedFunctions: 0, newFunctions: 0, totalCallSites: 0, affectedFiles: 0 }
+            summary: { modifiedFunctions: 0, deletedFunctions: 0, newFunctions: 0, totalCallSites: 0, unverifiedCallSites: 0, affectedFiles: 0 }
         };
     }
 
@@ -1789,6 +1741,7 @@ function diffImpact(index, options = {}) {
     const deletedFunctions = [];
     const callerFileSet = new Set();
     let totalCallSites = 0;
+    let totalUnverifiedSites = 0;
 
     for (const change of changes) {
         const lang = detectLanguage(change.filePath);
@@ -1829,6 +1782,7 @@ function diffImpact(index, options = {}) {
         // line-arithmetic guess that was wrong for tightly-packed 1-line functions.
         // The identity key is `name\0className` (matches deletion-detection below).
         let oldSymbolIdentities = null; // null = unknown (file untracked or git failed)
+        let oldCallables = null;        // old symbols WITH ranges — deleted lines are old-file coordinates
         if (change.deletedLines.length > 0 || change.addedLines.length > 0) {
             const ref = staged ? 'HEAD' : base;
             try {
@@ -1840,7 +1794,8 @@ function diffImpact(index, options = {}) {
                 if (fileLang) {
                     const oldParsed = parse(oldContent, fileLang);
                     oldSymbolIdentities = new Set();
-                    for (const oldFn of extractCallableSymbols(oldParsed)) {
+                    oldCallables = extractCallableSymbols(oldParsed);
+                    for (const oldFn of oldCallables) {
                         oldSymbolIdentities.add(`${oldFn.name}\0${oldFn.className || ''}`);
                     }
                 }
@@ -1873,46 +1828,81 @@ function diffImpact(index, options = {}) {
             }
         }
 
+        // Current callable symbols by identity — used to map an OLD symbol that
+        // still exists to its CURRENT definition for modification attribution.
+        const currentByIdentity = new Map();
+        for (const s of fileEntry.symbols) {
+            if (NON_CALLABLE_TYPES.has(s.type)) continue;
+            const k = `${s.name}\0${s.className || ''}`;
+            if (!currentByIdentity.has(k)) currentByIdentity.set(k, []);
+            currentByIdentity.get(k).push(s);
+        }
+
         for (const line of change.deletedLines) {
-            // For deleted lines, we can't use findEnclosingFunction on the current file
-            // since those lines no longer exist. Track as module-level unless they map
-            // to a function that still exists (the function was modified, not deleted).
-            // We approximate: if a deleted line is within the range of a known symbol, it's a modification.
-            // Pick the MOST-SPECIFIC match: prefer exact-contained over tolerance-contained,
-            // and among ties prefer the smallest range (innermost). This avoids an earlier
-            // symbol's expanded ±2 range claiming a line that actually belongs to a later
-            // 1-line function in tightly-packed files (BUG-F).
-            let bestSymbol = null;
-            let bestExact = false;
-            let bestRange = Infinity;
-            for (const symbol of fileEntry.symbols) {
-                if (NON_CALLABLE_TYPES.has(symbol.type)) continue;
-                const exact = line >= symbol.startLine && line <= symbol.endLine;
-                const tolerant = line >= symbol.startLine - 2 && line <= symbol.endLine + 2;
-                if (!exact && !tolerant) continue;
-                const range = symbol.endLine - symbol.startLine;
-                // Prefer exact-contained over tolerance-contained; among same kind, smaller range wins.
-                const better = bestSymbol === null
-                    || (exact && !bestExact)
-                    || (exact === bestExact && range < bestRange);
-                if (better) {
-                    bestSymbol = symbol;
-                    bestExact = exact;
-                    bestRange = range;
-                }
-            }
+            // Deleted line numbers are OLD-file coordinates. Matching them
+            // against CURRENT symbol ranges mis-attributes whenever the file
+            // shifted (an untouched function reported modified because it now
+            // occupies a deleted function's old lines). When the old parse is
+            // available, attribute by the OLD symbol's range and map its
+            // identity to the current definition; fall back to the old
+            // current-range heuristic only when git couldn't produce the base.
             let matched = false;
-            if (bestSymbol) {
-                // Only attribute to a symbol that ALSO existed in the old file. If we
-                // know the old identities and this symbol wasn't there, it's a brand-new
-                // function — its "deleted line" is really a neighboring line that gets
-                // pushed up by the diff hunk header. Treat as module-level so the new
-                // symbol stays cleanly in newFunctions[] (BUG-F).
-                const identityKey = `${bestSymbol.name}\0${bestSymbol.className || ''}`;
-                const existedBefore = oldSymbolIdentities === null
-                    ? true
-                    : oldSymbolIdentities.has(identityKey);
-                if (existedBefore) {
+            if (oldCallables !== null) {
+                let bestOld = null;
+                let bestRange = Infinity;
+                for (const oldFn of oldCallables) {
+                    const end = oldFn.endLine || oldFn.startLine;
+                    if (line < oldFn.startLine || line > end) continue;
+                    const range = end - oldFn.startLine;
+                    if (bestOld === null || range < bestRange) {
+                        bestOld = oldFn;
+                        bestRange = range;
+                    }
+                }
+                if (bestOld) {
+                    const identityKey = `${bestOld.name}\0${bestOld.className || ''}`;
+                    const candidates = currentByIdentity.get(identityKey);
+                    if (candidates && candidates.length > 0) {
+                        // Function still exists — a modification. Nearest
+                        // startLine disambiguates same-identity overloads.
+                        let cur = candidates[0];
+                        for (const c of candidates) {
+                            if (Math.abs(c.startLine - bestOld.startLine) < Math.abs(cur.startLine - bestOld.startLine)) cur = c;
+                        }
+                        const key = `${cur.name}:${cur.startLine}`;
+                        if (!affectedSymbols.has(key)) {
+                            affectedSymbols.set(key, { symbol: cur, addedLines: [], deletedLines: [] });
+                        }
+                        affectedSymbols.get(key).deletedLines.push(line);
+                    }
+                    // Identity gone → the whole function was deleted; the
+                    // deletion detection below reports it. Its body lines are
+                    // neither a modification nor a module-level change.
+                    matched = true;
+                }
+            } else {
+                // Fallback (old file unreachable): current-range heuristic.
+                // Pick the MOST-SPECIFIC match: prefer exact-contained over
+                // tolerance-contained, then smallest range (BUG-F).
+                let bestSymbol = null;
+                let bestExact = false;
+                let bestRange = Infinity;
+                for (const symbol of fileEntry.symbols) {
+                    if (NON_CALLABLE_TYPES.has(symbol.type)) continue;
+                    const exact = line >= symbol.startLine && line <= symbol.endLine;
+                    const tolerant = line >= symbol.startLine - 2 && line <= symbol.endLine + 2;
+                    if (!exact && !tolerant) continue;
+                    const range = symbol.endLine - symbol.startLine;
+                    const better = bestSymbol === null
+                        || (exact && !bestExact)
+                        || (exact === bestExact && range < bestRange);
+                    if (better) {
+                        bestSymbol = symbol;
+                        bestExact = exact;
+                        bestRange = range;
+                    }
+                }
+                if (bestSymbol) {
                     const key = `${bestSymbol.name}:${bestSymbol.startLine}`;
                     if (!affectedSymbols.has(key)) {
                         affectedSymbols.set(key, { symbol: bestSymbol, addedLines: [], deletedLines: [] });
@@ -1966,55 +1956,47 @@ function diffImpact(index, options = {}) {
 
         // Detect deleted functions: compare old file symbols with current by identity.
         // Uses name+className counts to handle overloads (e.g. Java method overloading).
-        if (change.deletedLines.length > 0) {
-            const ref = staged ? 'HEAD' : base;
-            try {
-                const oldContent = execFileSync(
-                    'git', ['show', `${ref}:${change.gitRelativePath}`],
-                    { cwd: index.root, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }
-                );
-                const fileLang = detectLanguage(change.filePath);
-                if (fileLang) {
-                    const oldParsed = parse(oldContent, fileLang);
-                    // Count current symbols by identity (name + className)
-                    const currentCounts = new Map();
-                    for (const s of fileEntry.symbols) {
-                        if (NON_CALLABLE_TYPES.has(s.type)) continue;
-                        const key = `${s.name}\0${s.className || ''}`;
-                        currentCounts.set(key, (currentCounts.get(key) || 0) + 1);
-                    }
-                    // Count old symbols by identity and detect deletions
-                    const oldCounts = new Map();
-                    const oldSymbols = extractCallableSymbols(oldParsed);
-                    for (const oldFn of oldSymbols) {
-                        const key = `${oldFn.name}\0${oldFn.className || ''}`;
-                        oldCounts.set(key, (oldCounts.get(key) || 0) + 1);
-                    }
-                    // For each identity, if old count > current count, the difference are deletions
-                    for (const [key, oldCount] of oldCounts) {
-                        const curCount = currentCounts.get(key) || 0;
-                        if (oldCount > curCount) {
-                            // Find the specific old symbols with this identity that were deleted
-                            const matching = oldSymbols.filter(s => `${s.name}\0${s.className || ''}` === key);
-                            // Report the extra ones (by startLine descending — later ones more likely deleted)
-                            const toReport = matching.slice(curCount);
-                            for (const oldFn of toReport) {
-                                deletedFunctions.push({
-                                    name: oldFn.name,
-                                    filePath: change.filePath,
-                                    relativePath: change.relativePath,
-                                    startLine: oldFn.startLine
-                                });
-                            }
-                        }
+        // oldCallables was parsed from the same base revision above.
+        if (change.deletedLines.length > 0 && oldCallables !== null) {
+            const currentCounts = new Map();
+            for (const s of fileEntry.symbols) {
+                if (NON_CALLABLE_TYPES.has(s.type)) continue;
+                const key = `${s.name}\0${s.className || ''}`;
+                currentCounts.set(key, (currentCounts.get(key) || 0) + 1);
+            }
+            // Count old symbols by identity and detect deletions
+            const oldCounts = new Map();
+            for (const oldFn of oldCallables) {
+                const key = `${oldFn.name}\0${oldFn.className || ''}`;
+                oldCounts.set(key, (oldCounts.get(key) || 0) + 1);
+            }
+            // For each identity, if old count > current count, the difference are deletions
+            for (const [key, oldCount] of oldCounts) {
+                const curCount = currentCounts.get(key) || 0;
+                if (oldCount > curCount) {
+                    // Find the specific old symbols with this identity that were deleted
+                    const matching = oldCallables.filter(s => `${s.name}\0${s.className || ''}` === key);
+                    // Report the extra ones (by startLine descending — later ones more likely deleted)
+                    const toReport = matching.slice(curCount);
+                    for (const oldFn of toReport) {
+                        deletedFunctions.push({
+                            name: oldFn.name,
+                            filePath: change.filePath,
+                            relativePath: change.relativePath,
+                            startLine: oldFn.startLine
+                        });
                     }
                 }
-            } catch (e) {
-                // File didn't exist in base, or git error — skip
             }
         }
 
-        // For each affected function, find callers
+        // For each affected function, find callers under the tiered caller
+        // contract (v4): confirmed edges populate `callers`; evidence-less
+        // candidates render in `unverifiedCallers` with reasons; positively
+        // excluded sites reconcile in the per-symbol conservation account.
+        // The pre-v4 hand-rolled nominal receiver filter is gone — the engine's
+        // receiver physics (#198/#202/#204/#206/#220) decide tier and exclusion,
+        // and its same-dir heuristic could silently drop true callers.
         for (const [, data] of affectedSymbols) {
             const { symbol, addedLines: aLines, deletedLines: dLines } = data;
 
@@ -2022,59 +2004,34 @@ function diffImpact(index, options = {}) {
             const allDefs = index.symbols.get(symbol.name) || [];
             const targetDefs = allDefs.filter(d => d.file === change.filePath && d.startLine === symbol.startLine);
 
-            let callers = index.findCallers(symbol.name, {
+            const rawCallers = index.findCallers(symbol.name, {
                 targetDefinitions: targetDefs.length > 0 ? targetDefs : undefined,
                 includeMethods: true,
-                includeUncertain: false,
+                collectAccount: true,
             });
 
-            // For Go/Java/Rust methods with a className, filter callers whose
-            // receiver clearly belongs to a different type (same logic as impact()).
-            const targetDef = targetDefs[0] || symbol;
-            if (targetDef.className && langTraits(lang)?.typeSystem === 'nominal') {
-                const targetClassName = targetDef.className;
-                // Pre-compute how many types share this method name
-                const methodDefs = index.symbols.get(symbol.name);
-                const classNames = new Set();
-                if (methodDefs) {
-                    for (const d of methodDefs) {
-                        if (d.className) classNames.add(d.className);
-                        else if (d.receiver) classNames.add(d.receiver.replace(/^\*/, ''));
-                    }
-                }
-                const isWidelyShared = classNames.size > 3;
-                callers = callers.filter(c => {
-                    if (!c.isMethod) return true;
-                    const r = c.receiver;
-                    if (r && ['self', 'cls', 'this', 'super'].includes(r)) return true;
-                    // No receiver (chained/complex expression): only include if method is
-                    // unique or rare across types — otherwise too many false positives
-                    if (!r) {
-                        return classNames.size <= 1;
-                    }
-                    // Use receiverType from findCallers when available
-                    if (c.receiverType) {
-                        return c.receiverType === targetClassName ||
-                               c.receiverType === targetDef.receiver?.replace(/^\*/, '');
-                    }
-                    // Unique method heuristic: if the method exists on exactly one class/type, include
-                    if (classNames.size === 1 && classNames.has(targetClassName)) return true;
-                    // For widely shared method names (Get, Set, Run, etc.), require same-package
-                    // evidence when receiver type is unknown
-                    if (isWidelyShared) {
-                        const callerFile = c.file || '';
-                        const targetDir = path.dirname(change.filePath);
-                        return path.dirname(callerFile) === targetDir;
-                    }
-                    // Unknown receiver + multiple classes with this method → filter out
-                    return false;
-                });
-            }
+            const confirmed = rawCallers.filter(c => c.tier !== 'unverified');
+            let unverified = rawCallers.filter(c => c.tier === 'unverified')
+                .concat(rawCallers.unverifiedEntries || []);
+
+            // Per-symbol conservation account over the text ground set (same
+            // ring as impact — every changed symbol is a root the user touched
+            // directly). Ground call-lines no candidate claimed become visible
+            // one-liners (call-not-resolved), never silent gaps.
+            const account = composeAccount(index, symbol.name, rawCallers);
+            for (const e of callNotResolvedEntries(index, account)) unverified.push(e);
+            unverified.sort((a, b) => {
+                const ap = a.relativePath || '';
+                const bp = b.relativePath || '';
+                if (ap !== bp) return codeUnitCompare(ap, bp);
+                return (a.line || 0) - (b.line || 0);
+            });
 
-            for (const c of callers) {
+            for (const c of confirmed) {
                 callerFileSet.add(c.file);
             }
-            totalCallSites += callers.length;
+            totalCallSites += confirmed.length;
+            totalUnverifiedSites += unverified.length;
 
             functions.push({
                 name: symbol.name,
@@ -2085,17 +2042,68 @@ function diffImpact(index, options = {}) {
                 signature: index.formatSignature(symbol),
                 addedLines: aLines,
                 deletedLines: dLines,
-                callers: callers.map(c => ({
+                callers: confirmed.map(c => ({
                     file: c.file,
                     relativePath: c.relativePath,
                     line: c.line,
                     callerName: c.callerName,
-                    content: c.content.trim()
-                }))
+                    content: (c.content || '').trim(),
+                    confidence: c.confidence,
+                    resolution: c.resolution,
+                    ...(c.tier && { tier: c.tier }),
+                })),
+                unverifiedCallers: unverified.map(u => ({
+                    file: u.file,
+                    relativePath: u.relativePath,
+                    line: u.line,
+                    callerName: u.callerName ?? null,
+                    content: (u.content || '').trim(),
+                    tier: 'unverified',
+                    ...(u.reason && { reason: u.reason }),
+                    ...(u.dispatchVia && { dispatchVia: u.dispatchVia }),
+                    ...(u.dispatchCandidates != null && { dispatchCandidates: u.dispatchCandidates }),
+                })),
+                account,
             });
         }
     }
 
+    // Deleted-but-still-called: a deleted function whose NAME still has call
+    // sites in the current tree is a likely runtime/compile break. The def is
+    // gone, so no receiver physics can pin these — they are name-level
+    // candidates and are labeled as such (same epistemic tier as `usages`).
+    if (deletedFunctions.length > 0) {
+        const { getCachedCalls } = require('./callers');
+        for (const del of deletedFunctions) {
+            const remaining = [];
+            const calleeFiles = index.getCalleeFiles(del.name);
+            if (calleeFiles) {
+                for (const f of calleeFiles) {
+                    const calls = getCachedCalls(index, f);
+                    if (!Array.isArray(calls)) continue;
+                    const fe = index.files.get(f);
+                    let lines = null;
+                    for (const c of calls) {
+                        if (c.name !== del.name && c.resolvedName !== del.name) continue;
+                        if (lines === null) {
+                            try { lines = index._getFileLines(f); } catch { lines = []; }
+                        }
+                        remaining.push({
+                            file: f,
+                            relativePath: fe ? fe.relativePath : path.relative(index.root, f),
+                            line: c.line,
+                            content: (lines[c.line - 1] || '').trim(),
+                        });
+                    }
+                }
+            }
+            remaining.sort((a, b) => a.relativePath === b.relativePath
+                ? a.line - b.line
+                : codeUnitCompare(a.relativePath, b.relativePath));
+            del.remainingCallSites = remaining;
+        }
+    }
+
     return {
         base: staged ? '(staged)' : base,
         functions,
@@ -2107,6 +2115,7 @@ function diffImpact(index, options = {}) {
             deletedFunctions: deletedFunctions.length,
             newFunctions: newFunctions.length,
             totalCallSites,
+            unverifiedCallSites: totalUnverifiedSites,
             affectedFiles: callerFileSet.size
         }
     };
@@ -2119,19 +2128,28 @@ function diffImpact(index, options = {}) {
 
 /**
  * Extract all callable symbols (functions + class methods) from a parse result,
- * matching how indexFile builds the symbol list. Methods get className added.
+ * matching how indexFile builds the symbol list — the identity keys
+ * (`name\0className`) derived here are compared against INDEXED symbols, so
+ * both normalizations indexFile applies must happen here too:
+ * - Go/Rust methods are standalone functions with a `receiver`; indexFile
+ *   derives className from it. Without this, every modified method's identity
+ *   misses the old set and it reads as new + phantom-deleted.
+ * - Class members include FIELDS; the indexed side filters NON_CALLABLE_TYPES,
+ *   so the old side must too or every field in a changed file reads deleted.
  * @param {object} parsed - Result from parse()
  * @returns {Array<{name, className, startLine}>}
  */
 function extractCallableSymbols(parsed) {
     const symbols = [];
     for (const fn of parsed.functions) {
-        symbols.push({ name: fn.name, className: fn.className || '', startLine: fn.startLine });
+        const className = fn.className || (fn.receiver ? fn.receiver.replace(/^\*/, '') : '');
+        symbols.push({ name: fn.name, className, startLine: fn.startLine, endLine: fn.endLine });
     }
     for (const cls of parsed.classes) {
         if (cls.members) {
             for (const m of cls.members) {
-                symbols.push({ name: m.name, className: cls.name, startLine: m.startLine });
+                if (NON_CALLABLE_TYPES.has(m.memberType || 'method')) continue;
+                symbols.push({ name: m.name, className: cls.name, startLine: m.startLine, endLine: m.endLine });
             }
         }
     }
@@ -2608,12 +2626,12 @@ function auditAsync(index, options = {}) {
 
         // Stable ordering (rule #11): sort by (file, line, callerName, calleeName).
         issues.sort((a, b) => {
-            const fc = String(a.file).localeCompare(String(b.file));
+            const fc = codeUnitCompare(String(a.file), String(b.file));
             if (fc !== 0) return fc;
             if (a.line !== b.line) return a.line - b.line;
-            const cc = String(a.callerName || '').localeCompare(String(b.callerName || ''));
+            const cc = codeUnitCompare(String(a.callerName || ''), String(b.callerName || ''));
             if (cc !== 0) return cc;
-            return String(a.calleeName || '').localeCompare(String(b.calleeName || ''));
+            return codeUnitCompare(String(a.calleeName || ''), String(b.calleeName || ''));
         });
 
         return {