fix(resolver): resolveByGlobal picks the single best match, not every candidate

resolveByGlobal's exact-name lookup returned every same-named symbol in the
codebase that cleared the 0.5 directory-proximity confidence threshold, and
resolveCallTargets/emitDirectCallEdgesForCall then emitted a calls edge to
each one instead of the single most likely target. A bare (no-receiver) or
this/self/super call carries no type info to disambiguate, so fanning out
turned one real call site into N-1 false edges (e.g. four object-literal
close() methods in src/db/connection.ts each getting a calls edge from every
caller that destructures a close() handle).

Fix: reduce the exact-name lookup to the single unambiguous highest-confidence
candidate. A genuine tie at the top confidence has no principled winner and
now resolves to nothing rather than betting on all of them, falling through
to the narrower same-class-sibling fallback instead.

Mirrored in both engines: src/domain/graph/resolver/strategy.ts (WASM/TS) and
crates/codegraph-core/src/domain/graph/builder/stages/build_edges.rs (native).

Updates two pre-existing tests whose fixtures/assertions had baked in the old
fan-out behavior as expected (#1519's byName suite, #1752's reverse-dep
reconnect baseline, which had already flagged this exact scenario as a
"separate, pre-existing concern — filed independently").

Impact: 2 functions changed, 10 affected

Author: carlos-alm

crates/codegraph-core/src/domain/graph/builder/stages/build_edges.rs

@@ -934,6 +934,40 @@ fn find_enclosing_caller<'a>(defs: &[DefWithId<'a>], call_line: u32, file_node_i
     (file_node_id, "")
 }
 
+/// Step 2 of the scoped (this/self/super or no-receiver) fallback: exact global
+/// name lookup. Mirrors `resolveExactGlobalMatch` in
+/// `src/domain/graph/resolver/strategy.ts`.
+///
+/// A bare/this/self/super call carries no type qualifier, so `nodes_by_name`
+/// can return every same-named symbol in the codebase, filtered only by the
+/// loose directory-proximity confidence threshold. Returning all of them
+/// turns a single real call site into N-1 false `calls` edges (#1863). Only
+/// a single highest-confidence candidate is trustworthy — a tie at the top
+/// confidence (e.g. several files at the same directory depth from the
+/// caller) is genuinely ambiguous and returns nothing, letting the caller
+/// fall through to the narrower same-class-sibling fallback.
+fn resolve_exact_global_match<'a>(
+    ctx: &EdgeContext<'a>,
+    call_name: &str,
+    rel_path: &str,
+) -> Vec<&'a NodeInfo> {
+    let scored: Vec<(&'a NodeInfo, f64)> = ctx.nodes_by_name
+        .get(call_name)
+        .map(|v| v.iter()
+            .map(|&n| (n, resolve::compute_confidence(rel_path, &n.file, None)))
+            .filter(|&(_, confidence)| confidence >= 0.5)
+            .collect())
+        .unwrap_or_default();
+    if scored.is_empty() { return Vec::new(); }
+
+    let best_confidence = scored.iter().map(|&(_, confidence)| confidence).fold(f64::MIN, f64::max);
+    let best: Vec<&'a NodeInfo> = scored.iter()
+        .filter(|&&(_, confidence)| confidence == best_confidence)
+        .map(|&(n, _)| n)
+        .collect();
+    if best.len() == 1 { best } else { Vec::new() }
+}
+
 /// Multi-strategy call target resolution: import-aware → same-file → type-aware → scoped.
 /// `caller_name` is the enclosing function/method name (e.g. `"Shape.describe"`) used to scope
 /// `this`/`self`/`super` dispatch to the caller's own class before falling back to a broader scan.
@@ -1180,12 +1214,7 @@ fn resolve_call_targets<'a>(
         }
 
         // First try exact name match (e.g. an unqualified function named "area").
-        let exact: Vec<&NodeInfo> = ctx.nodes_by_name
-            .get(call.name.as_str())
-            .map(|v| v.iter()
-                .filter(|n| resolve::compute_confidence(rel_path, &n.file, None) >= 0.5)
-                .copied().collect())
-            .unwrap_or_default();
+        let exact = resolve_exact_global_match(ctx, call.name.as_str(), rel_path);
         if !exact.is_empty() { return exact; }
 
         // Class-scoped exact lookup: prefer `ClassName.method` when the caller is a qualified
@@ -2854,6 +2883,67 @@ mod call_edge_tests {
         );
     }
 
+    /// Issue #1863: several same-named object-literal `close() {}` methods
+    /// scattered under sibling directories two levels below the caller all
+    /// score the same 0.5 "grandparent proximity" confidence. A bare `close()`
+    /// call must not fan out into a `calls` edge to every one of them — a
+    /// genuine top-confidence tie is ambiguous and must resolve to nothing.
+    #[test]
+    fn global_fallback_tie_does_not_fan_out() {
+        let all_nodes = vec![
+            node(1, "caller", "function", "src/presentation/caller.ts", 3),
+            node(2, "close", "method", "src/db/connection.ts", 10),
+            node(3, "close", "method", "src/domain/target2.ts", 20),
+            node(4, "close", "method", "src/features/target3.ts", 30),
+        ];
+        let files = vec![make_file(
+            "src/presentation/caller.ts",
+            10,
+            vec![def("caller", "function", 3, 8)],
+            vec![call("close", 5, None)],
+            vec![],
+            vec![],
+        )];
+        let edges = build_call_edges(files, all_nodes, vec![], MAX_SOLVER_ITERATIONS);
+        assert!(
+            !edges.iter().any(|e| e.kind == "calls" && e.source_id == 1),
+            "ambiguous same-confidence candidates must not fan out into calls edges; got: {:?}",
+            edges.iter().map(|e| (&e.kind, e.source_id, e.target_id)).collect::<Vec<_>>()
+        );
+    }
+
+    /// Companion to `global_fallback_tie_does_not_fan_out`: when one candidate
+    /// has a strictly higher confidence than the rest, the clear single winner
+    /// must still resolve — only genuine top-confidence ties are dropped.
+    #[test]
+    fn global_fallback_resolves_unambiguous_best_match() {
+        let all_nodes = vec![
+            node(1, "caller", "function", "src/presentation/caller.ts", 3),
+            // Same directory as the caller → confidence 0.7, the clear winner.
+            node(2, "close", "method", "src/presentation/sibling.ts", 10),
+            // Two directories away → confidence 0.5, tied with each other but not with node 2.
+            node(3, "close", "method", "src/domain/target2.ts", 20),
+            node(4, "close", "method", "src/features/target3.ts", 30),
+        ];
+        let files = vec![make_file(
+            "src/presentation/caller.ts",
+            10,
+            vec![def("caller", "function", 3, 8)],
+            vec![call("close", 5, None)],
+            vec![],
+            vec![],
+        )];
+        let edges = build_call_edges(files, all_nodes, vec![], MAX_SOLVER_ITERATIONS);
+        let call_edges: Vec<_> = edges.iter().filter(|e| e.kind == "calls" && e.source_id == 1).collect();
+        assert_eq!(
+            call_edges.len(),
+            1,
+            "expected exactly one calls edge (the unambiguous best match); got: {:?}",
+            edges.iter().map(|e| (&e.kind, e.source_id, e.target_id)).collect::<Vec<_>>()
+        );
+        assert_eq!(call_edges[0].target_id, 2, "expected the same-directory candidate to win");
+    }
+
     /// Receiver-edge confidence must propagate the stored typeMap confidence
     /// (e.g. 0.85 from a pts property-write) instead of a flat 0.9 — mirrors
     /// `typeConfidence ?? (typeName ? 0.9 : 0.7)` in resolveReceiverEdge.

src/domain/graph/resolver/strategy.ts

@@ -325,14 +325,47 @@ function resolveViaSameClassSibling(
     .filter((t) => t.kind === 'method' && computeConfidence(relPath, t.file, null) >= 0.5);
 }
 
+/**
+ * Step 2: exact global name lookup.
+ *
+ * Unlike `resolveByReceiver`'s cascade, a bare (no-receiver) or `this`/`self`/
+ * `super` call carries no type qualifier to narrow the search — `lookup.byName`
+ * can return every unrelated symbol in the codebase that happens to share the
+ * name, filtered only by the loose directory-proximity confidence threshold.
+ * Emitting a `calls` edge to every one of those turns a single real call site
+ * into N-1 false edges (#1863). With no receiver/type info to break a tie,
+ * only a single highest-confidence candidate is trustworthy:
+ *   - a unique highest-confidence candidate wins outright.
+ *   - a tie at the highest confidence (e.g. several files at the same
+ *     directory depth from the caller — the exact #1863 repro) is genuinely
+ *     ambiguous: there is no principled way to prefer one over another, so
+ *     the match is dropped rather than fanning out, letting the caller fall
+ *     through to the narrower resolveViaSameClassSibling fallback.
+ */
+function resolveExactGlobalMatch(
+  lookup: StrategyLookup,
+  call: { name: string },
+  relPath: string,
+): ReadonlyArray<{ id: number; file: string }> {
+  const scored = lookup
+    .byName(call.name)
+    .map((target) => ({ target, confidence: computeConfidence(relPath, target.file, null) }))
+    .filter((candidate) => candidate.confidence >= 0.5);
+  if (scored.length === 0) return [];
+
+  const bestConfidence = Math.max(...scored.map((candidate) => candidate.confidence));
+  const best = scored.filter((candidate) => candidate.confidence === bestConfidence);
+  return best.length === 1 ? [best[0]!.target] : [];
+}
+
 /**
  * Resolve a call site with no receiver, or whose receiver is `this`, `self`,
  * or `super`.
  *
  * Resolution cascade:
  *   1. resolveViaAccessorThisDispatch — Object.defineProperty this-dispatch (Phase 8.3f).
- *   2. Exact global name lookup with confidence filter.
- *   3. resolveViaSameClassSibling — same-class sibling method fallback.
+ *   2. resolveExactGlobalMatch        — exact global name lookup, unambiguous best match only.
+ *   3. resolveViaSameClassSibling     — same-class sibling method fallback.
  */
 export function resolveByGlobal(
   lookup: StrategyLookup,
@@ -344,9 +377,7 @@ export function resolveByGlobal(
   const viaAccessor = resolveViaAccessorThisDispatch(lookup, typeMap, call, relPath, callerName);
   if (viaAccessor.length > 0) return viaAccessor;
 
-  const exact = lookup
-    .byName(call.name)
-    .filter((t) => computeConfidence(relPath, t.file, null) >= 0.5);
+  const exact = resolveExactGlobalMatch(lookup, call, relPath);
   if (exact.length > 0) return exact;
 
   const sameClass = resolveViaSameClassSibling(lookup, call, relPath, callerName);

tests/integration/issue-1519-confidence-sorted-dedup.test.ts

@@ -5,16 +5,31 @@
  * buildFileCallEdges (build-edges.ts lines 1126-1132) before the emit loop,
  * and matching sorts to the Phase 8.3 pts alias loops.
  *
- * WHAT THESE TESTS GUARD
- * ──────────────────────
- * Both fixtures resolve multiple candidates with distinct node IDs (different
- * files → different graph nodes). The `seenCallEdges` / `ptsEdgeRows` dedup key
- * is `${caller.id}|${t.id}`, so dedup never fires across distinct nodes.
+ * WHAT THE byName SUITE GUARDS (updated for #1863)
+ * ──────────────────────────────────────────────────
+ * `resolveByGlobal`'s exact-name lookup (the byName fixture below) used to
+ * emit a `calls` edge to every same-named candidate it found, regardless of
+ * how many there were. #1863 fixed this: when candidates have a unique
+ * highest-confidence winner, only that one resolves — a lower-confidence
+ * candidate is dropped rather than fanning out into a false edge. A genuine
+ * tie at the top confidence (no candidate strictly wins) resolves to no edge
+ * at all, since there is no receiver/type info to break it.
  *
- * These tests therefore verify the confidence SCORING invariant:
- *   • A near-directory target always receives a higher confidence value than a
- *     far-directory target for the same call site.
- *   • Both edges are emitted (neither is suppressed by sort logic).
+ * The byName suite below now verifies:
+ *   • The near-directory (higher-confidence) candidate is the one that
+ *     resolves, with confidence ≥ 0.7.
+ *   • The far-directory (lower-confidence) candidate does NOT get an edge —
+ *     it is a strictly worse match, not a genuine tie.
+ *
+ * WHAT THE pts-alias SUITE GUARDS (unchanged by #1863)
+ * ──────────────────────────────────────────────────────
+ * The pts alias fixture resolves through a separate points-to alias
+ * mechanism (Phase 8.3), not `resolveByGlobal` — #1863 does not touch it.
+ * That fixture can still resolve multiple candidates with distinct node IDs;
+ * the `ptsEdgeRows` dedup key is `${caller.id}|${t.id}`, so dedup never fires
+ * across distinct nodes there. It verifies the confidence SCORING invariant:
+ * the local, highest-confidence alias target wins the `ptsEdgeRows` slot
+ * ahead of a lower-confidence one.
  *
  * WHAT THESE TESTS DO NOT GUARD
  * ──────────────────────────────
@@ -42,12 +57,14 @@ import { buildGraph } from '../../src/domain/graph/builder.js';
 // src/consumer.js calls helper() without importing it.
 // Two files define helper(): one in the same directory (high confidence),
 // one in a different directory (low confidence).
-// Both edges are expected, each with the correct confidence for its file proximity.
+// Since #1863, only the unambiguous highest-confidence candidate (near)
+// resolves — the far, lower-confidence candidate is dropped rather than
+// fanning out into a false edge.
 
 const MULTI_TARGET_FIXTURE: Record<string, string> = {
   'src/consumer.js': `
 export function process() {
-  helper(); // no import — resolves via byName to both src/helper.js and other/helper.js
+  helper(); // no import — resolves via byName; only the near candidate wins (#1863)
 }
 `.trimStart(),
 
@@ -127,7 +144,7 @@ function writeFixture(baseDir: string, files: Record<string, string>): void {
 
 // ── Multi-target byName suite ──────────────────────────────────────────────────
 
-describe('confidence-sorted dedup: multi-target byName resolution (#1519)', () => {
+describe('confidence-sorted dedup: multi-target byName resolution (#1519, #1863)', () => {
   let tmpDir: string;
 
   beforeAll(async () => {
@@ -166,31 +183,24 @@ describe('confidence-sorted dedup: multi-target byName resolution (#1519)', () =
     expect(nearEdge!.confidence).toBeGreaterThanOrEqual(0.7);
   });
 
-  it('far-target edge (other/helper.js) has confidence < 0.7 (different-directory proximity)', () => {
+  it('does not emit an edge to the far, lower-confidence helper (other/helper.js) (#1863)', () => {
     const edges = readEdgesWithConfidence(path.join(tmpDir, '.codegraph', 'graph.db'));
     const farEdge = edges.find(
       (e) => e.source === 'process' && e.target === 'helper' && e.target_file === 'other/helper.js',
     );
-    expect(farEdge).toBeDefined();
-    // computeConfidence: different parent directory → 0.3 or 0.5.
-    // The far target must score lower than the near target.
-    expect(farEdge!.confidence).toBeLessThan(0.7);
+    // computeConfidence: different parent directory → 0.3 or 0.5, strictly below
+    // the near candidate's 0.7. Since #1863, a strictly-worse candidate is
+    // dropped rather than emitted alongside the winner as a false edge.
+    expect(farEdge).toBeUndefined();
   });
 
-  it('near-target confidence is strictly greater than far-target confidence', () => {
+  it('emits exactly one calls edge for the ambiguous helper() call site (#1863)', () => {
     const edges = readEdgesWithConfidence(path.join(tmpDir, '.codegraph', 'graph.db'));
-    const nearEdge = edges.find(
-      (e) => e.source === 'process' && e.target === 'helper' && e.target_file === 'src/helper.js',
-    );
-    const farEdge = edges.find(
-      (e) => e.source === 'process' && e.target === 'helper' && e.target_file === 'other/helper.js',
-    );
-    expect(nearEdge).toBeDefined();
-    expect(farEdge).toBeDefined();
-    // The sort at build-edges.ts:1126-1132 processes high-confidence targets first.
-    // Both edges are stored (different node IDs); this assertion verifies the
-    // confidence ordering invariant that the sort enforces.
-    expect(nearEdge!.confidence).toBeGreaterThan(farEdge!.confidence);
+    const helperEdges = edges.filter((e) => e.source === 'process' && e.target === 'helper');
+    // Only the unambiguous highest-confidence candidate resolves — no fan-out
+    // to every same-named candidate the global fallback finds.
+    expect(helperEdges).toHaveLength(1);
+    expect(helperEdges[0]!.target_file).toBe('src/helper.js');
   });
 });