propose: CALLS noise + resolution — resolved-only edges + EdgeFilter

[HumanBean17]

Status: draft
Tracks: #177

Adds propose/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md.

Frame

CALLS is a sequence (ordered by call_site_line, call_site_byte), not a set. Source-order traversal is the dominant agent use case and must be preserved. Today's noise (~80% in the #177 sample) comes from two unrelated burdens being carried on one edge:

1. Phantom + chained-receiver edges encoding "the resolver gave up here" — they point at synthetic phantom Symbols the agent has no traversal use for.
2. Resolved edges to accessor / repository / delegation targets — these have legitimate sequential meaning but cannot be projected by callee role without a filter knob.

Two locked moves

1. CALLS carries only resolved invocations. Phantom + chained + name-only-zero-candidates sites move to a sibling node table UnresolvedCallSite + UNRESOLVED_AT edge from the caller Symbol. Phantom Symbol rows + _phantom_method_id + tables.phantoms deleted. Re-index required; ontology v14 → v15.
2. callee_declaring_role becomes a CALLS edge attribute, populated at pass3_calls emission time from the callee parent's role. neighbors_v2 gains a typed EdgeFilter Pydantic model (min_confidence, exclude_strategies, include_strategies, callee_declaring_role, callee_declaring_roles, exclude_callee_declaring_roles). Default ordering by (call_site_line, call_site_byte) is unchanged when filter is omitted.

Why not a semantic split

A CALLS → DELEGATES_TO/PERSISTS_VIA/ACCESSES_STATE/UNRESOLVED_CALL split was the first reframe I tried — it fails the test "edge type should encode semantic intent only when the agent never needs to interleave edges of different types in a single traversal." Reading a method body is exactly the interleaved case; a split would force 4-way fan-merge on (line, byte). Recorded as locked Decision 6.

Three sub-PRs (sequential)

• PR-1 — resolved-only CALLS + UnresolvedCallSite + UNRESOLVED_AT + describe.unresolved_call_sites rollup. Ontology bump. Re-index.
• PR-2 — EdgeFilter on neighbors_v2 + pc unresolved-calls CLI subcommand + explicit supersession of the MCP-V2 "no per-edge filter" design rule.
• PR-3 — dedup_calls on neighbors_v2 (default off) + TPL_NEIGHBORS_CALLS_HIGH_FANOUT HINTS-V4 success-path template (threshold = 10).

19 locked decisions

Including: no semantic split; resolved BOOLEAN removed from CALLS DDL; UnresolvedCallSite is a sibling node table (not a JSON column); callee_declaring_role is CALLS-specific (no symmetry on HTTP_CALLS/ASYNC_CALLS); find_callers does not gain callee_declaring_role filtering; dedup_calls=False by default; high-fanout template threshold = 10; no back-compat alias for the removed resolved=False rows.

20-row use-case re-walk

Covers ordered transcript (HV1, HV2), filter projections (HV3, HV4, HV5), find_callers semantics (HV6, HV17), trace_request_flow step (HV7), graph-quality CLI / describe rollup (HV8, HV9), HINTS-V3 interaction (HV10), edge-attribute filter semantics (HV11, HV12, HV13, HV14), dedup (HV15), success-path hint (HV16), 100%-unresolved edge case (HV18), CI invariants (HV19, HV20).

Files

• propose/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md

Drafted per the propose-doc-author skill structure. Will move Status to under review after first review pass.

[HumanBean17]

Critical review pass on the propose. I think the issue is real and the core direction is good (keep CALLS ordered; add role-aware projection instead of splitting semantic edge types), but I would not merge this propose as-is.

Main blockers:

1. The plan drops useful known-receiver external-call data. Current CALLS distinguishes true zero-confidence receiver failures from the case where the receiver is resolved but the callee method is not indexed (JDK/Spring/external/library calls). That path preserves confidence, strategy, arg_count, and a deterministic phantom FQN; README also documents JDK/Spring/Lombok callees as phantom method symbols. The proposed UnresolvedCallSite(reason='name_only_zero_candidates') shape only carries callee_simple, receiver_expr, and reason, so it loses graph-quality and transcript data. Either preserve those fields in UnresolvedCallSite, or keep known-receiver external calls as non-traversable CALLS/separate external-call rows.

2. Build-time dedup by (src_id, call_site_line, call_site_byte) erases resolver truth. Current multi-candidate emission is how overload_ambiguous represents ambiguity. If the concrete bug is interface+concrete duplication for one source call, solve that specific duplicate class. A blanket pre-emit winner selection makes find_callers / explain flows see one arbitrary callee and hides ambiguity that agents may need to know about.

3. Silent no-op edge_filter semantics conflict with the existing strict filter contract. mcp_v2.py currently frames filters as typed predicates where inapplicable fields fail loud with a teaching message. Returning filtered CALLS plus unfiltered OVERRIDES for edge_types=['CALLS','OVERRIDES'], edge_filter={callee_declaring_role:'SERVICE'} is surprising and likely to reintroduce noise. I would prefer fail-loud or an explicit per-edge-type filter shape.

4. include_unresolved=True + edge_filter reintroduces unfiltered noise. With edge_filter={callee_declaring_role:'SERVICE'}, the proposed behavior returns SERVICE resolved calls plus all unresolved sites, not “service-like unresolved sites.” That undermines the filter. Make these mutually exclusive again, or add a real unresolved filter axis once a concrete workflow justifies it.

5. The propose invents neighbors_v2(depth=2) semantics. Current neighbors_v2 is one-hop only and the README frames MCP walking as one hop at a time. If depth is intended, it needs to be a first-class MCP surface change with docs/tests/tool-description updates; otherwise remove HV28 / Decision 21.

6. CLI naming is inconsistent. The proposal says pc unresolved-calls, but the operator CLI in this repo is java-codebase-rag with top-level subcommands. Unless pc is a planned alias, the propose should use java-codebase-rag unresolved-calls ....

Suggested safer sequence: PR-1 add callee_declaring_role and edge_filter without deleting rows; PR-2 move only true zero-confidence receiver/chained failures out of CALLS, preserving known-receiver external-call metadata; PR-3 revisit dedup as response-shape only, not build-time candidate loss.

[HumanBean17]

Thanks — this is the right grilling. All six blockers stand; I agree with the substance of every one. Itemized:

#1 — Known-receiver external calls data loss → AGREE. I missed that build_ast_graph.py:1257-1271 already distinguishes "receiver resolved, callee method not indexed (JDK/Spring/external)" from true receiver failures, and preserves confidence/strategy/arg_count/deterministic phantom FQN with resolved=False. README §"Phantom nodes" documents this explicitly. The propose collapsing these into UnresolvedCallSite(reason='name_only_zero_candidates') strips real data — graph-quality counters, transcript-quality metadata, and the receiver-tier strategy that downstream consumers may project on.

The fix I'll lock: only true receiver-failure sites move out of CALLS. Concretely:

• strategy='phantom' with resolved=False (unresolved receiver) → UnresolvedCallSite(reason='phantom_unresolved_receiver')
• strategy='chained_receiver' → UnresolvedCallSite(reason='chained_receiver')
• Everything else stays as a CALLS row, including known-receiver-external (resolved=False with preserved receiver-tier strategy), overload_ambiguous (resolved=True), name-only-fb single-candidate (resolved=True), implicit_super, constructor, etc.

UnresolvedCallSite carries receiver_expr, callee_simple, arg_count, reason, call_site_line, call_site_byte. Known-external calls keep their existing row shape with resolved=False; agents who want to exclude them keep using exclude_external=True (FQN prefix), exactly as today.

That means PR-1's CALLS is not "resolved-only" — it's "no-true-receiver-failure rows." I'll rewrite TL;DR + Principle 5 + §3.1/§3.3 + every UC row that said "resolved-only" to reflect this.

#2 — Build-time dedup erases overload_ambiguous → AGREE, scope down. The concrete bug I was solving in HV37 / Decision 33 was interface declaration + concrete impl emitted as two CALLS rows for the same source line. overload_ambiguous (name-only-fb with >1 candidate at the same level) is the resolver's own ambiguity signal and must stay as N rows with strategy='overload_ambiguous' so find_callers / explain flows can see it.

Fix: rewrite Decision 33 as supertype-walk dedup only. When _lookup_method_candidates returns multiple candidates because one candidate is the declared concrete method on the receiver type and others are inherited supertype declarations, collapse to the concrete-class candidate. overload_ambiguous is left alone. PR-1 fixture test asserts: (a) myRepository.save(x) where MyRepository extends JpaRepository → one CALLS row pointing at MyRepository.save (post-dedup); (b) overloaded save(Foo) / save(Bar) with arg_count=-1 → N rows with strategy='overload_ambiguous' (unchanged).

#3 — Silent no-op edge_filter conflicts with fail-loud filter contract → AGREE. I missed the fail-loud-on-inapplicable-fields invariant at mcp_v2.py:6,82-91,191-206. Principle 7 / Decision 10 ("silently no-op on edges that don't carry the attribute") was a direct contradiction.

Fix: lock that edge_filter requires edge_types to be a single edge type whose schema declares the filtered attribute. edge_types=['CALLS','OVERRIDES'] + edge_filter={callee_declaring_role:'SERVICE'} raises a fail-loud ValueError with a teaching message ("callee_declaring_role not on OVERRIDES; split into two calls"). This matches the existing _nodefilter_inapplicable_fields pattern exactly. Per-edge-type-keyed filter map is a richer future direction but adds surface; deferring.

This kills Principle 7 in its current form. Rewriting it as "edge_filter is single-edge-type-scoped and fail-loud on inapplicable attributes."

#4 — include_unresolved=True + edge_filter reintroduces noise → AGREE, reverting my round-2 reversal. You're right that "SERVICE-resolved CALLS + all unresolved" is not "service-like unresolved sites." HV38's framing was wrong — the receiver-expression heuristic I waved at would require a real classifier on the unresolved row, which is a new primitive.

Fix: re-lock the original mutual exclusivity (include_unresolved=True is incompatible with edge_filter, fail-loud). HV38 deleted; HV23 (full transcript including unresolved) stays. If a real "service-like unresolved" workflow emerges, it gets its own propose with an unresolved_filter axis backed by a concrete classifier (e.g. receiver type-name suffix matching).

#5 — neighbors_v2(depth=2) semantics invented → AGREE, drop entirely. README:12 and mcp_v2.py:39 are both explicit: neighbors_v2 is one-hop. I invented depth>1 semantics out of thin air for HV28/Decision 21. Multi-hop is a separate design problem (visited-set, cycle handling, fanout cap, hint behavior at depth boundaries) and shouldn't ride along.

Fix: delete HV28 + Decision 21. Add row to §5 out-of-scope: "Multi-hop neighbors_v2 — out of scope; separate propose if/when needed."

#6 — CLI naming → AGREE. Mechanical fix. pc unresolved-calls → java-codebase-rag unresolved-calls everywhere in §3.6, HV26, decisions, out-of-scope rows.

---

On the suggested safer sequence: I think it's strictly better than my 3-PR ordering and I'll adopt it:

• PR-1: Add callee_declaring_role to CALLS DDL + populate in pass3_calls + supertype-walk dedup. No rows deleted, no schema removals. Ontology bump 14→15 for the new column. Adds the GraphMeta counters (Decision 23 — three discrete INT64 columns). HV1, HV31, HV32, HV33, HV37 land here.
• PR-2: Add EdgeFilter + edge_filter parameter to neighbors_v2 (single-edge-type, fail-loud). Adds CLI surface for graph quality. Still no CALLS row deletions. HV2, HV21, HV22, HV28 (renumbered, the depth=2 row goes away — was HV28 in revision 2), HV33, HV34, HV35, HV36 land here.
• PR-3: Move only strategy='phantom' (true receiver-failure) and strategy='chained_receiver' rows out of CALLS into UnresolvedCallSite + UNRESOLVED_AT. Delete _phantom_method_id / tables.phantoms for just those two reasons. Known-receiver-external resolved=False rows stay as CALLS. Add include_unresolved (mutually exclusive with edge_filter). Add the two HINTS-V4 templates. HV23, HV24, HV30 land here.

This makes PR-1 and PR-2 strictly additive (zero behavior change for existing readers), and PR-3 the only breaking change — with a much narrower blast radius than before.

---

Amendment plan (single force-push to propose/calls-noise):

1. Rewrite TL;DR — drop "resolved-only CALLS" framing; replace with "true receiver-failure sites move to a caller-side facet; known-external calls stay in CALLS."
2. Rewrite Principle 5 (was "CALLS carries only successfully-resolved invocations") → "CALLS sheds true receiver-failure rows; all other resolved=False semantics preserved."
3. Rewrite Principle 7 → "edge_filter is single-edge-type-scoped and fail-loud on inapplicable attributes" (delete "silently no-op").
4. Rewrite §3.1 emission-table to reflect the three-bucket mapping (receiver-failure → UCS; supertype-walk dedup; everything else unchanged).
5. Rewrite Decision 25 → mutual exclusivity restored.
6. Rewrite Decision 33 → supertype-walk dedup only; overload_ambiguous unchanged.
7. Delete Decision 21, HV28 (depth=2). Renumber.
8. Delete HV38 (compose-with-filter). Renumber.
9. Add §5 row: multi-hop neighbors_v2 out of scope.
10. Mechanical: pc → java-codebase-rag everywhere.
11. PR ordering rewritten per your suggested safer sequence.
12. Update Appendix B with revision 3 traceability.

Will land as a single revision-3 force-push. Final counts will likely be ~30 decisions and ~36 use cases. Going to apply now.