fix: cross-file call resolution — preserve N-way collision signal

[jackshiung]

Summary

Fixes a silent data-loss bug in cross-file call resolution (introduced in #348 / 5c77d9c) where global_label_to_nid: dict[str, str] drops all but one candidate when multiple nodes share the same normalised label.

Problem

When multiple functions/methods across files share a name (e.g. .get() defined in 32 files of a Laravel/CodeIgniter monorepo):

global_label_to_nid: dict[str, str] = {}
for n in all_nodes:
    global_label_to_nid[normalised.lower()] = n["id"]   # N-1 candidates silently dropped

Every call-site of .get() gets routed to whichever nid happened to be iterated last, producing a pseudo-god-node. All ambiguity_degree=0 — the ambiguity signal is gone.

Observed on a real 5-subsystem monorepo (997 files):

• .get(): 32 unique nodes, but only 1 received all 321 INFERRED incoming edges
• Similar collapse for .all(), .delete(), .create(), .update()

Approach

Three layered commits (pickable individually):

1. refactor — bucket the lookup: dict[str, list[str]] preserving all candidates, with per-bucket dedup and consumption-site invariant assert.
2. fix — on multi-candidate resolution, emit one AMBIGUOUS edge per candidate (confidence=AMBIGUOUS, confidence_score=0.2, ambiguity_degree=N). Single-candidate paths remain INFERRED@0.8 unchanged.
3. feat — add a fan-out cap (max_ambiguity_fanout, default 20, override via kwarg or GRAPHIFY_MAX_AMBIGUITY_FANOUT). Above the cap, emit no edges and record to cross_file_call_stats (propagated into graph.json by build/export/watch).

The cap exists because generic verbs (.get() with 30+ candidates) produce fan-outs that are AST-undecidable — the edges would be semantically noise. Default of 20 is conservative; fleet users can raise it via env var without code change.

Evidence

Tests: 441 pass (4 existing + 4 new collision tests; all existing extract/confidence/pipeline/etc. green). No regressions.

Real monorepo validation (TBA-backend, 997 files):

Metric	Before (v0.4.16)	After (this PR)
Total edges	10,214	10,529 (+3.1%)
INFERRED calls	2,580	1,230 (collisions correctly reclassified)
AMBIGUOUS calls	0	1,426
truncated_high_degree	n/a	1,079 (examples: update, all, get, create, delete)
Communities	474	449 (-5.3%, no collapse)
Top god nodes	stable	stable

Without the cap, TBA-backend exploded to 37,166 edges (+264%) — this was the motivation for commit 3.

Notes

• ambiguity_degree field is additive — consumers that don't read it are unaffected.
• cross_file_call_stats is optional and present in graph.json only when cross-file resolution runs.
• Default cap can be raised for fleet users (monorepo-heavy codebases) via GRAPHIFY_MAX_AMBIGUITY_FANOUT=40 graphify update . without patching.

Testing

pytest tests/test_cross_file_collision.py -v   # 8/8 new
pytest tests/                                   # 441/441

Happy to split into multiple PRs if preferred (each commit stands alone).

---

🤖 Authored with assistance from Claude Opus 4.6