feat(schema): add callee_declaring_role to CALLS; supertype-walk dedup; unresolved counters

[HumanBean17]

Summary

• Bump ONTOLOGY_VERSION 14 → 15; add CALLS.callee_declaring_role (DDL, emission, EDGE_SCHEMA).
• Implement collapse_supertype_duplicates per propose §3.3.1 — runs only before the overload_ambiguous emit loop; never collapses overload_ambiguous rows.
• Add GraphMeta.pass3_unresolved_phantom_receiver and pass3_unresolved_chained (counts today's phantom-receiver / chained-receiver CALLS rows).
• README + AGENT-GUIDE: v15 re-index callout includes row-count delta from supertype dedup at duplicate sites.

Implements PR-1 from plans/PLAN-CALLS-NOISE.md / propose CALLS-NOISE-AND-RESOLUTION-PROPOSE.md §6 PR-1.

Test plan

• PR-1 named tests (7): test_pass3_supertype_dedup_jpa_repository_save_one_row, test_pass3_overload_ambiguous_still_n_rows, test_pass3_callee_declaring_role_bank_annotated_types, test_calls_edge_has_callee_declaring_role_column, test_graph_meta_unresolved_counters_present, test_edge_schema_calls_registers_callee_declaring_role, plus existing test_overload_sameArity_emits_two_overload_ambiguous_edges
• Sentinels: no UnresolvedCallSite / EdgeFilter / phantoms deletion in diff
• Manual: fresh bank-chat-system build → ontology 15, counters present, callee_declaring_role on CALLS

rm -rf /tmp/calls-pr1 && .venv/bin/python build_ast_graph.py \
  --source-root tests/bank-chat-system --kuzu-path /tmp/calls-pr1 --verbose
# Kuzu: ontology_version=15, pass3_unresolved_phantom_receiver=138, pass3_unresolved_chained=77

• .venv/bin/ruff check .
• Targeted pytest for PR-1 tests
• Full pytest tests: 625 passed, 13 skipped; failures are pre-existing env (CLI entrypoint not on PATH, cocoindex/numpy in heavy lance tests) plus fixed test_kuzu_graph_refuses_ontology_version_below_required / regenerated EDGE-NAVIGATION.md

Made with Cursor

[HumanBean17]

PR-1 review (CALLS-NOISE)

Verdict: Looks good to merge as PR-1 scope, with one follow-up I’d treat as important before PR-2 edge_filter lands on brownfield codebases.

What works well

• Scope matches PLAN-CALLS-NOISE.md PR-1: ontology 15, CALLS.callee_declaring_role, supertype dedup before overload_ambiguous, GraphMeta counters, EDGE_SCHEMA + docs — no PR-2/PR-3 leakage.
• _collapse_supertype_duplicates matches propose §3.3.1 (single concrete on receiver, supertype signature match, unrelated-candidate bail-out, never collapses overload_ambiguous).
• Smoke tests cover dedup (SupertypeDedupPatterns) and overload preservation (OverloadPatterns#sameArity).
• Manual bank build: ontology_version=15, counters present, all CALLS rows populated with callee_declaring_role; spot-check shows 0 mismatches vs parent Symbol.role on bank (expected — bank has no brownfield role stubs).

Request: brownfield role parity (medium)

Propose §3.1 / HV31 says callee_declaring_role should match the declaring type’s role including brownfield (same as parent Symbol.role at write time).

_callee_declaring_role_for_dst recomputes via resolve_role_and_capabilities(..., overrides=_PASS3_ROLE_OVERRIDES) where _PASS3_ROLE_OVERRIDES is empty and meta_chain is omitted. _write_nodes uses load_brownfield_overrides(project_root) + meta_chain.

On @CodebaseRole / brownfield-only typing, CALLS.callee_declaring_role can diverge from parent.role while bank tests stay green. PR-2 edge_filter={callee_declaring_role: ...} would be wrong on those codebases.

Suggested fix (either):

1. Pass source_root into pass3_calls and use the same overrides + meta_chain as _write_nodes, or
2. Populate callee_declaring_role at _write_edges when overrides are already loaded.

A small brownfield stub test (@CodebaseRole on declaring type → edge attr == parent Symbol.role) would lock this.

Notes (non-blocking)

• Dedup applicability: Fixture uses concrete-typed JpaStyleRepoImpl repo. Typical JpaStyleRepo repo (interface-typed) often already yields a single candidate (lookup walks supertypes, not implementors), so dedup’s main win is concrete-typed receivers. Worth one README sentence so operators don’t expect dedup on every JPA site.
• Perf: _callee_declaring_role_for_dst scans all tables.members per emit — fine for bank; consider member_by_id if this shows up in profiles.
• Docs drift: AGENTS.md / cursor rules still say v14 — fine out of PR-1 scope; small chore PR would help agents.

Correctness (no blockers)

• overload_ambiguous guard on dedup path ✓
• Phantom/chained still on CALLS with counters for PR-3 ✓
• Known-external phantoms → OTHER ✓
• DDL / EDGE_SCHEMA / write Cypher aligned ✓

Assuming CI green — thanks for keeping PR-1 tight.