CALLS-edge noise problem: neighbors(out, [CALLS]) returns ~80% noise on typical service methods

[HumanBean17]

Problem

neighbors(out, [CALLS]) on a typical service method returns a wall of edges where most are noise. An agent doing hop-based exploration (neighbors(out, [CALLS]) → pick target → repeat) floods its context window with ~30 noise items per ~5 signal items at each hop.

Evidence

Concrete example from the bank-chat-system fixture — ChatManagementService#assign(AssignmentRequest) returns 35 outgoing CALLS edges:

Category	Count	%	Examples	Signal
Business-logic delegation	~3	~8%	SplitResolverService#resolveSplitName(String), DistributionTriggerPublisher#publishTrigger()	High
Repository / persistence	~4	~12%	AssignChatRepository#findByConversationId(String), AssignQueueRepository#save(?)	Medium
Entity accessor noise	~15	~43%	AssignChatEntity#setEpkId(String), AssignmentRequest#getConversationId() ×3	Low
Phantom / chained / JDK	~13	~37%	?ResponseStatusException#<init>(2), ?c#setId(1), UUID#randomUUID(?), Instant#now(?), ?...#orElseGet(1)	Zero

After 3 hops: ~90 tokens of noise versus ~15 of signal.

Why NodeFilter on neighbors can't help today

• All targets (services, entities, phantoms) have role=OTHER — the role system doesn't distinguish "service I delegate to" from "entity I call a setter on."
• There's no filter on edge attributes (confidence, strategy, resolved) — these exist in attrs on the response but can't be used as input predicates.
• There's no exclude_phantom or min_confidence parameter.
• Duplicate edges (same callee called N times from different call sites) aren't deduplicated.

Noise taxonomy

The noise breaks into recognizable categories that could be filtered either server-side or client-side:

1. Phantom / chained-receiver edges: strategy in (phantom, chained_receiver) or confidence < 0.3. These are unresolved call sites — the graph builder couldn't determine the actual target.
2. JDK / library utility calls: fqn starts with java., javax., org.slf4j., org.apache.logging., lombok.. Standard library calls that never carry business logic.
3. Entity accessor calls: getter (get*), setter (set*), constructor (<init>) on DTO/Entity types. High volume, low information during hop traversal.
4. Duplicates: same callee FQN from multiple call sites within the same method.

Possible solution directions (not prescriptive)

• Skill-layer heuristic filtering — a skill (e.g. /mini-map) calls neighbors, receives all edges, and applies classification rules client-side. No MCP surface change. See PR propose: agent skills and commands — Layer 3 over the 4-tool MCP #59 (/mini-map skill).
• Server-side edge-attr filter — add min_confidence, exclude_phantom, or general edge-attr predicates to neighbors. Requires a propose for MCP surface change.
• Smarter role assignment — classify entity accessor methods differently from business-logic methods so NodeFilter can distinguish them. Requires ontology work.
• Deduplicate in response — collapse same-callee edges into one with a count. Small MCP change.

These are not mutually exclusive.

Reproduction

rm -rf /tmp/noise-check && .venv/bin/python build_ast_graph.py \
  --source-root tests/bank-chat-system --kuzu-path /tmp/noise-check/code_graph.kuzu --verbose

.venv/bin/python -c "
from mcp_v2 import neighbors_v2, find_v2
from kuzu_queries import KuzuGraph

g = KuzuGraph('/tmp/noise-check/code_graph.kuzu')
KuzuGraph._instance = g

result = find_v2(kind='symbol', filter={'fqn_prefix': 'com.bank.chat.assign.service.ChatManagementService#assign'}, limit=1, graph=g)
sym_id = result.results[0].id

nb = neighbors_v2(ids=sym_id, direction='out', edge_types=['CALLS'], limit=50, graph=g)
for e in nb.results:
    attrs = e.attrs
    print(f'{e.other.fqn}  strategy={attrs.get(\"strategy\",\"?\")} conf={attrs.get(\"confidence\",\"?\")} resolved={attrs.get(\"resolved\",\"?\")}')
print(f'\nTotal: {len(nb.results)} edges')
"

[HumanBean17]

Proposal: callee / invoked role (aligns with “smarter role assignment”)

Agree with the diagnosis that exclude_roles=OTHER is not a viable agent workaround today: on typical neighbors(out, [CALLS]) hops, callee endpoints are method/constructor Symbol nodes, and those are indexed with the default role=OTHER even when the declaring type is @Service, @Entity, etc. Stereotype inference runs on types; members are created without inheriting the parent type’s role. So NodeFilter.role / exclude_roles cannot separate “delegate to a service” from “call an entity setter” on CALLS neighbors.

Direction

Resolve “what role is being invoked” at call time — expose the architectural stereotype of the callee (usually from the declaring type of the target method):

• Option A (node): When indexing method/constructor symbols, set role from the enclosing type’s resolved role (with explicit overrides / brownfield still winning per existing rules).
• Option B (edge): Add something like invoked_role (or callee_declaring_role) on CALLS edges, populated from the callee’s declaring type at graph build time.

Either unlocks useful neighbors(..., filter=…) patterns, e.g.:

• filter={"role": "SERVICE"} — business delegation hops
• exclude_roles: ["ENTITY", "DTO"] — drop most accessor noise on entities/DTOs
• keep REPOSITORY when persistence hops matter

This is the same solution family as the issue’s “Smarter role assignment — … so NodeFilter can distinguish them” — ontology + indexer work, not an agent/skill-only fix.

Scope caveat (won’t fully close the issue alone)

Type-level stereotype on callees helps a lot but does not cover all noise buckets:

Category	Role-only fix
Entity getters/setters on @Entity types	Still ENTITY — need exclude_roles or finer labels (e.g. ACCESSOR)
Phantoms / chained / low-confidence	Often OTHER or unresolved — still need edge attrs (strategy, confidence, resolved) as filter predicates or client-side rules
JDK / utilities (java.*, UUID#now, etc.)	Mostly OTHER — consider LIBRARY / prefix rules
Duplicate call sites	Dedup / collapse, not role

Suggested phased approach:

1. Phase 1: Callee declaring-type role on method symbols or CALLS edges → unblocks NodeFilter for stereotype-based hop pruning.
2. Phase 2 (optional): Finer method-level labels (accessor vs “real” logic) and/or neighbors edge-attr filters (min_confidence, exclude_phantom) for the remaining buckets.

Happy to turn this into a short propose/*.md if we want an indexer/MCP surface change tracked formally.

[HumanBean17]

Grill

Method role=OTHER is a gap, not a design choice

build_ast_graph.py line 2443–2458 runs resolve_role_and_capabilities() for types — they get proper roles (SERVICE, ENTITY, REPOSITORY, etc.). But members (methods/constructors, lines 2463–2475) go through _node_row() which defaults to role="OTHER". No inference, no propagation, no comment explaining why. It's a seam between two features built at different times: role inference was designed for find(kind="symbol", filter={role: "SERVICE"}) (finding classes by stereotype), and when CALLS edges were added later (pass 3), nobody wired the declaring type's role down to method-level nodes.

This is the structural reason NodeFilter.role / exclude_roles is dead weight on CALLS neighbors today.

Don't mix type roles with method roles

Adding role=SERVICE to ChatManagementService#assign() would break every agent that uses find(kind="symbol", filter={role: "SERVICE"}) to locate classes — suddenly methods show up too. The role field has a clear semantic: "what architectural stereotype is this declaration?" A method is not a SERVICE; its declaring class is.

Two clean options that don't pollute existing semantics:

• Option A (node field): Add a separate declaring_role field on Symbol. Methods keep role=OTHER but gain declaring_role=SERVICE. Add declaring_role to NodeFilter. Simpler, no edge-attr filter infra needed.
• Option B (edge attr): Add callee_role (or invoked_role) on CALLS edges, populated at build time from the callee's declaring type. Then add edge-attribute predicates to neighbors. More invasive but puts the information where it naturally belongs — the call invokes a service, the method doesn't "have" a role.

Both require a re-index.

Phantom / confidence noise is a separate axis

The confidence system is a receiver-resolution quality score:

Strategy	Conf	Meaning
this_super / import_map	0.95	Receiver resolved with high certainty
unique_type_name	0.75	Only one type in codebase matches the simple name
suffix	0.55	Fuzzy suffix match
phantom	0.0	Receiver completely unresolvable
chained_receiver	0.0	foo().bar().baz() — can't resolve through chain

The 37% phantom/chained/JDK noise bucket is confidence=0.0 with resolved=false — the graph builder is saying "I have no idea what's on the other end." These edges exist so the graph is complete, but they're useless for hop traversal.

This bucket is filterable without any ontology change — a WHERE e.confidence >= $min_conf or WHERE e.strategy <> 'phantom' in the Cypher is all it takes. But it can't be done client-side when the noise eats into the limit and pushes real signal out of the response.

Suggested phasing

1. Phase 1 — edge-attr filters on neighbors: min_confidence and/or exclude_strategies parameter. Kills the phantom/chained bucket (~37%). No re-index, no ontology bump — pure MCP surface change.
2. Phase 2 — callee role on CALLS edges: callee_role populated from the declaring type at build time + edge-attr filter support from Phase 1 makes it immediately usable. Kills the entity-accessor bucket (~43%). Requires re-index + ontology bump.

Phase 1 unblocks Phase 2's UX and delivers standalone value.

[HumanBean17]

Took a grill pass that started somewhere else and walked itself back. Posting the conclusion + draft propose plan; the dead-end is included briefly so the reasoning is traceable.

Reframe attempt: "is this a typing problem, not a filtering problem?"

I asked: every other edge in this graph carries semantic intent in its name (HTTP_CALLS, ASYNC_CALLS, DECLARES_CLIENT, EXPOSES). CALLS carries only "the bytecode would invoke this." Could we split CALLS into typed sub-edges (DELEGATES_TO / PERSISTS_VIA / ACCESSES_STATE / UNRESOLVED_CALL) and skip filtering entirely?

Why that didn't survive

The reframe failed one test: CALLS is a sequence, not a set. CALLS already carries call_site_line and call_site_byte (DDL at build_ast_graph.py:2317-2319). Agents reading "what does this method do, in order?" rely on a single neighbors(out, [CALLS]) returning one ordered stream they can walk by line.

A semantic split would force agents to do a 4-way fan-merge on (line, byte) across edge types every time they want sequential traversal. trace_request_flow and the AMA "explain this method" use case get 4x worse, not better. The "narrow by callee role" win is real but it isn't worth losing source-order traversal.

Principle that fell out

Edge type should encode semantic intent only when the agent never needs to interleave edges of different types in a single traversal.

HTTP_CALLS vs ASYNC_CALLS passes the test — they're not sequenced against each other. DELEGATES_TO vs PERSISTS_VIA vs ACCESSES_STATE fails — reading a method body is exactly the interleaved-by-source-order case.

This is also the test that argues UNRESOLVED_CALL should be split off: phantom/chained edges point to synthetic phantom Symbols that don't take the agent anywhere. They have no sequential traversal value either — agents don't want to "step through" an unresolved call site.

Revised position

Two locked decisions, no edge-type explosion:

1. CALLS carries only resolved invocations. Phantom + chained sites move to a node-level facet of the caller (Symbol.unresolved_call_sites: list[{line, byte, callee_simple, receiver_expr, reason}] or a sibling row table keyed by caller). They are not a sub-edge type, because the agent has no traversal use for them. This kills the ~37% phantom/chained bucket from neighbors output completely, without losing the data for debuggability.

2. Filterability lives in edge attributes, not in edge type. Add callee_declaring_role to CALLS attrs at pass-3 (populated from the callee's declaring-type role). neighbors gains an edge_filter mechanism; CALLS stays one edge type; ordering by (call_site_line, call_site_byte) is preserved when no filter is applied; agents can project the stream by role when they want delegation vs accessor vs persistence.

Net effect: agents who want "in source order" get a clean ordered stream (resolved-only). Agents who want "where does this delegate?" project the same stream by attribute filter. No fan-merge. No 4-way query. The "noise" disappears either by removal (phantoms) or by selectable projection (callee role).

Three sub-PRs

1. PR-1 — resolved-only CALLS. Phantom + chained sites move to caller-side facet (node attribute or sibling row table — locked in propose). Ontology bump, re-index, removes the phantom Symbol nodes entirely.
2. PR-2 — callee_declaring_role attribute + neighbors edge_filter surface. Single MCP-surface change; revisits the MCP-V2 "no per-edge filter" design rule explicitly (this is the part of the issue's Phase 1 that I argued was a stop-gap but is the right shape — apology to the issue author, the grill earned its keep on Phase 2 not Phase 1).
3. PR-3 — CALLS-edge dedup + success-path hint on high-fanout CALLS. Dedup is CALLS-specific (it's the only edge with per-call-site multiplicity by design) — kept as a response-shape decision, not a generic neighbors knob. Hint nudges the agent toward the new filter / dedup options.

Phase ordering / re-index moments / ontology bump are recorded in the propose. Drafting propose/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md next.

What I'd still grill in the propose

• What defines callee_declaring_role? Pattern (getX/setX), annotation (@entity + name shape), type role (callee declared on a REPOSITORY/SERVICE/ENTITY-role type)? Lock the inputs.
• find_callers behavior: aggregate over filter values or expose the filter? Default = unfiltered.
• What replaces phantom Symbol nodes for the _phantom_method_id invariants? (Pass3 currently leans on phantoms as dst targets to preserve the "every CALLS row has dst" invariant — moving them out changes that invariant.)
• Should callee_declaring_role also live on HTTP_CALLS / ASYNC_CALLS for symmetry? Probably no — those edges already encode role in the endpoint kind (Client / Producer).

Propose PR incoming; gating on review of this comment first.