[squid-protocol]

Summary

Part of the Level 2 call-graph work (epic #3265). Stacked on #3708 (decorator edges): this PR's base is that branch, so the diff shows only the reference work. Merge #3708 first, then retarget this to main.

Problem. A function name used as a value (Depends(get_db), key=sort_key, callback=self.on_done, return wrapper) is a function the framework or caller invokes later. It's how frameworks wire programs together, and it was recorded nowhere. In the classification of pyan3's unlinked Python edges, these were ~330 edges (~9%).

Fix.

• Detector (_python_references; python and embedded_python via a top-level reference_edges flag, per orphaned_logic reports 100% dead code for five languages whose invocation model never names the callee — the family #2727 closed without covering #2806):
  • Records candidates in argument, keyword, assignment, return / yield / lambda and collection positions as references_to / references_qualifiers (self.on_done becomes on_done via self).
  • Variables are excluded, because a bare name is far more often a variable than a function:
    • the function's parameters and locals, including tuple and starred targets and with / except / walrus;
    • every nested def's parameters;
    • the bindings of every enclosing function (closure variables);
    • the module's own variables (app = FastAPI());
    • in a signature, anything but a default or a call argument, so Sequence[Depends] isn't a reference but Depends(get_db) is;
    • names the function also invokes: those are already call edges. A nested def f( header is not an invocation, so return f is a reference.
• Resolver: a reference becomes a row only when it resolves to a function through a scoped step (class, qualified, typed, file, import). unique isn't enough: a local variable named like the repo's one function of that name is still a variable.
  • Rows are fcall_data kind 'reference', counted in references_by_step and never in the call rates.
  • They reach fan-in and PageRank, like decorators.
• Nested definitions win: a bare call or reference to a name the caller defines nested inside itself now resolves to that nested definition, not the first one in the file. This is the every-decorator-has-its-own-wrapper case.
  • It also fixed the long-standing iter_data wrong-target examples for plain calls.
  • The rehydrator now restores loc, so the caller's span survives a delta scan.
• Persistence: function_data.references_to / references_qualifiers (healed), restored by the state rehydrator.
• The module unit carries no references yet: synthetic_unit_data doesn't persist them, and a delta scan must resolve exactly like a fresh one. That's a follow-up.
• Tool: call_graph_resolution.py scores reference edges separately and adds reference_precision_pct, reference_judged and recall_all_kinds_pct to the baseline, reported but not gated.

Type of change

• Bug fix
• Parsing or engine logic (detector.py, call_resolver.py, record_keeper.py, state_rehydrator.py, python profiles)

Measured: call_graph_resolution.py python (pyan3 reference, language-crucible)

metric	before (#3708)	after
confident precision (calls, gated)	99.4% (1,806 judged)	99.8% (1,806 judged)
edge recall (calls, gated)	51.4%	51.6%
resolution recall (calls, gated)	97.0%	97.5%
reference precision (not gated)	n/a	99.7% (322 agree / 1 wrong)
edge recall, calls + decorators + references	67.9%	77.3%

How the precision got there, since these rules read the real source:

• The first cut was 99.6% on fewer links, with 122 unconfirmed rows (pyan has no edge at all). Sampling them against source found module-level variables (TestClient(app) resolving to an inner app in routing.py), tuple targets, closure variables, signature annotations and a truncated 2,000-char signature. All are fixed, which brought unconfirmed down to 65.
• Adding return <nested def> then dropped precision to 90.5% (31 wrong: the file's first wrapper). The nested-definition rule brought it back to 99.7%.
• The remaining 69 unconfirmed, sampled:
  • mostly @property reads (self._data, self.code, self.timeOut; reading them runs a function, and pyan doesn't count that);
  • fastapi's app.dependency_overrides[common_parameters] = ..., where the key is the function.
• Known imperfection: for a property with both a getter and a setter, a read can land on the setter's definition.

Golden masters

crucible_check.py --mode both --update --yes: no drift. The changes are function-level and within a file.

Tests

• New tests/extraction/languages/test_python_references.py:
  • value positions;
  • variables of every kind excluded;
  • nested parameters and closure variables;
  • called names and the module unit carry no references;
  • languages without the flag record nothing.
• tests/core_engine/test_call_resolver.py: a reference is kept only when it reaches an in-scope function (not a unique variable, not a class); a nested definition wins over the file's first, for calls and references.
• tests/tools_recorders/test_fcall_data.py: the reference columns and loc persist and rehydrate.
• test_calls_out_nested_decl_3360.py::test_no_false_fcall_edge_from_outer_to_nested_declaration: the C5 claim (a nested header isn't a call) now checks call-kind rows. return helper draws the new reference edge, which is asserted explicitly.
• test_call_graph_resolution_gate.py: covers the new baseline fields.

Verification

$ pytest tests/                                               -- 11479 passed; the 1 failure (the C5 test above) fixed in 34cdc58d
$ PATH=.venv/bin:$PATH python tests/tools/audit_check.py      -- all clear (after 34cdc58d)
$ python tests/tools/call_graph_accuracy.py --ci              -- OK
$ python tests/tools/call_graph_resolution.py python --regenerate
$ python tests/tools/crucible_check.py --mode both --update --yes   -- no drift

🤖 Generated with Claude Code

https://claude.ai/code/session_01GCpfMCUMpco98QGbsuv2sr

---

Generated by Claude Code

[github-actions]

🐦‍⬛ Muninn Security Scan

✅ No security issues found.

🐦‍⬛ Powered by Muninn · Skald Lab