fix(pr-3 review): ucs: ids, describe/CLI tests, fan-out hint uses true CALLS count

UnresolvedCallSite ids use ucs: prefix with NodeRef.kind unresolved_call_site so
describe is not mis-routed. Add rollup and CLI smoke tests; wire --reason choices;
fix pass3 UCS percentage denominator and README graph section.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HumanBean17

README.md

@@ -361,7 +361,7 @@ For `reprocess`, the pipeline runs `cocoindex` with `cwd` set to the bundle dire
 
 ## 6. Graph layer
 
-A deterministic property graph derived from tree-sitter Java parsing lives next to the LanceDB tables under the index directory (default `${JAVA_CODEBASE_RAG_INDEX_DIR:-./.java-codebase-rag}/code_graph.kuzu`). Current ontology version: **14** (see [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) for edge shapes).
+A deterministic property graph derived from tree-sitter Java parsing lives next to the LanceDB tables under the index directory (default `${JAVA_CODEBASE_RAG_INDEX_DIR:-./.java-codebase-rag}/code_graph.kuzu`). Current ontology version: **15** (see [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) for MCP-traversable edge shapes).
 
 ### Node kinds
 
@@ -370,10 +370,11 @@ A deterministic property graph derived from tree-sitter Java parsing lives next
 | `Symbol` | `package`, `file`, `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor` |
 | `Route` | HTTP endpoint or async listener (one row per declared route) |
 | `Client` | Outbound HTTP / messaging call site |
+| `UnresolvedCallSite` | Receiver-failure call site (`chained_receiver`, `phantom_unresolved_receiver`) — not a `Symbol`; ids use the `ucs:` prefix |
 
-Unresolved targets become **phantom** nodes (`resolved=false`, FQN guessed from imports / `java.lang`).
+Known-receiver-external JDK / Spring / Lombok callees stay on **`CALLS`** as phantom **method** symbols (`resolved=false`). Receiver-failure sites (unresolved receiver or chained receiver) are **`UnresolvedCallSite`** nodes linked by **`UNRESOLVED_AT`** (not in `EDGE_SCHEMA`; use `describe`, `neighbors(..., include_unresolved=True)`, or `java-codebase-rag unresolved-calls`).
 
-### Edge types (10)
+### Edge types (MCP-traversable)
 
 | Edge | Direction | Meaning |
 |---|---|---|
@@ -388,7 +389,7 @@ Unresolved targets become **phantom** nodes (`resolved=false`, FQN guessed from
 | `HTTP_CALLS` | client → route | Cross-service HTTP call (caller-side Client to target Route). |
 | `ASYNC_CALLS` | producer → route | Cross-service async (Kafka, Rabbit, JMS, …). |
 
-JDK / Spring / Lombok callees are represented as **phantom** method symbols at index time. Caller/callee traversals default to `exclude_external=true` so those edges are filtered by FQN prefix without dropping them from the graph.
+Caller/callee traversals default to `exclude_external=true` on **`find_callers`** so library FQN prefixes are filtered without dropping edges from the graph.
 
 ### Call-graph notes
 

build_ast_graph.py

@@ -1223,7 +1223,7 @@ def _collapse_supertype_duplicates(
 
 
 def _unresolved_call_site_id(caller_id: str, call: CallSite) -> str:
-    return f"{caller_id}:{call.line}:{call.byte}"
+    return f"ucs:{caller_id}:{call.line}:{call.byte}"
 
 
 def _emit_unresolved_call_site(
@@ -1438,9 +1438,11 @@ def pass3_calls(tables: GraphTables, asts: dict[str, JavaFileAst], *, verbose: b
                 _process_file_calls(file_ast, rel_path, tables, stats)
             except Exception as e:
                 log.error("Call extraction failed for %s: %s", rel_path, e)
-    pct_chained = 100.0 * stats.phantom_chained / max(1, stats.total)
-    pct_callee_unres = 100.0 * stats.callee_unresolved / max(1, stats.total)
-    pct_phantom_recv = 100.0 * stats.phantom_other / max(1, stats.total)
+    denom_calls = max(1, stats.total)
+    denom_sites = max(1, stats.total + stats.phantom_chained + stats.phantom_other)
+    pct_chained = 100.0 * stats.phantom_chained / denom_sites
+    pct_callee_unres = 100.0 * stats.callee_unresolved / denom_calls
+    pct_phantom_recv = 100.0 * stats.phantom_other / denom_sites
     tables.pass3_skipped_cross_service = int(stats.skipped_cross_service)
     tables.pass3_unresolved_phantom_receiver = int(stats.phantom_other)
     tables.pass3_unresolved_chained = int(stats.phantom_chained)

docs/AGENT-GUIDE.md

@@ -219,7 +219,7 @@ Returns **edges** with `attrs` (`confidence`, `strategy`, `match`, … on cross-
 
 **Cross-service edges** (`HTTP_CALLS`, `ASYNC_CALLS`): read `attrs.confidence` and `attrs.match` — low confidence or `unresolved`/`phantom`/`ambiguous` means treat as a resolver signal, not ground truth.
 
-**`CALLS` edges:** source-ordered (`call_site_line`, `call_site_byte`). After ontology 15 PR-3, true receiver-failure sites are **not** on `CALLS` — they are `UnresolvedCallSite` nodes (`reason`: `chained_receiver` or `phantom_unresolved_receiver`). `attrs.resolved=false` on remaining `CALLS` rows means known-receiver-external (JDK/Spring) callees, not receiver failure. **`include_unresolved=True`** (CALLS + `direction=out` only) interleaves unresolved sites with resolved `CALLS` (`row_kind` discriminator); **mutually exclusive with `edge_filter`**. **`dedup_calls=True`** collapses identical `(origin, callee)` `CALLS` to one row with `call_site_lines`. **`filter` + `edge_filter` together** load the ordered CALLS stream then apply callee `NodeFilter` in Python — expect higher latency on hot methods than `edge_filter` alone. Optional **`edge_filter`** projects before pagination: `min_confidence`; `include_strategies` / `exclude_strategies` (mutually exclusive); `callee_declaring_role`, `callee_declaring_roles`, `exclude_callee_declaring_roles` (`["OTHER"]` also drops known-external rows). **`filter.role` filters the neighbor method (usually `OTHER`), not the callee stereotype** — use `edge_filter.callee_declaring_role` for repository/service hops. **`exclude_external` applies to `find_callers` / `find_callees` only** (FQN-prefix); trim JDK noise on `neighbors` CALLS via `edge_filter`. Accessor noise: role excludes help; getter/setter heuristics in [`propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map`.
+**`CALLS` edges:** source-ordered (`call_site_line`, `call_site_byte`). After ontology 15 PR-3, true receiver-failure sites are **not** on `CALLS` — they are `UnresolvedCallSite` nodes (`reason`: `chained_receiver` or `phantom_unresolved_receiver`; ids use the `ucs:` prefix, `other.kind=unresolved_call_site` — **not** describable via `describe(id=…)`). `UNRESOLVED_AT` is graph storage only (not in `EDGE_SCHEMA` / `neighbors` edge_types). `attrs.resolved=false` on remaining `CALLS` rows means known-receiver-external (JDK/Spring) callees, not receiver failure. **`include_unresolved=True`** (CALLS + `direction=out` only) interleaves unresolved sites with resolved `CALLS` (`row_kind` discriminator); **mutually exclusive with `edge_filter`**. **`dedup_calls=True`** collapses identical `(origin, callee)` `CALLS` to one row with `call_site_lines`. **`filter` + `edge_filter` together** load the ordered CALLS stream then apply callee `NodeFilter` in Python — expect higher latency on hot methods than `edge_filter` alone. Optional **`edge_filter`** projects before pagination: `min_confidence`; `include_strategies` / `exclude_strategies` (mutually exclusive); `callee_declaring_role`, `callee_declaring_roles`, `exclude_callee_declaring_roles` (`["OTHER"]` also drops known-external rows). **`filter.role` filters the neighbor method (usually `OTHER`), not the callee stereotype** — use `edge_filter.callee_declaring_role` for repository/service hops. **`exclude_external` applies to `find_callers` / `find_callees` only** (FQN-prefix); trim JDK noise on `neighbors` CALLS via `edge_filter`. Accessor noise: role excludes help; getter/setter heuristics in [`propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map`.
 
 ### Ontology glossary
 

java_codebase_rag/cli.py

@@ -22,6 +22,7 @@
     resolve_operator_config,
 )
 from java_codebase_rag.pipeline import clip, run_build_ast_graph, run_cocoindex_drop, run_cocoindex_update
+from java_ontology import VALID_UNRESOLVED_CALL_REASONS
 
 KUZU_INCREMENTAL_TRACKING_ISSUE_URL = "https://github.com/HumanBean17/java-codebase-rag/issues/73"
 
@@ -705,7 +706,13 @@ def build_parser() -> argparse.ArgumentParser:
     uc_list = unresolved_sub.add_parser("list", help="List unresolved call sites.")
     _add_index_embedding_flags(uc_list)
     uc_list.add_argument("--method-id", type=str, default=None, help="Caller Symbol id")
-    uc_list.add_argument("--reason", type=str, default=None, help="phantom_unresolved_receiver or chained_receiver")
+    uc_list.add_argument(
+        "--reason",
+        type=str,
+        default=None,
+        choices=sorted(VALID_UNRESOLVED_CALL_REASONS),
+        help="Filter by UnresolvedCallSite.reason",
+    )
     uc_list.add_argument("--microservice", type=str, default=None)
     uc_list.add_argument("--callee-simple", type=str, default=None, dest="callee_simple")
     uc_list.add_argument("--limit", type=int, default=100)

mcp_hints.py

@@ -372,13 +372,14 @@ def neighbors_calls_fanout_hints(payload: dict[str, Any]) -> list[tuple[int, str
         return pairs
     if payload.get("include_unresolved"):
         return pairs
-    n = len(list(payload.get("results") or []))
+    page_n = len(list(payload.get("results") or []))
+    calls_n = int(payload.get("calls_row_count") or 0) or page_n
     unresolved = int(payload.get("unresolved_count") or 0)
-    if not payload.get("edge_filter_provided") and n >= _CALLS_HIGH_FANOUT_THRESHOLD:
-        pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_NEIGHBORS_CALLS_HIGH_FANOUT.format(n=n)))
+    if not payload.get("edge_filter_provided") and calls_n >= _CALLS_HIGH_FANOUT_THRESHOLD:
+        pairs.append((PRIORITY_LEAF_FOLLOWUP, TPL_NEIGHBORS_CALLS_HIGH_FANOUT.format(n=calls_n)))
     if unresolved > 0:
         pairs.append(
-            (PRIORITY_LEAF_FOLLOWUP, TPL_NEIGHBORS_CALLS_HAS_UNRESOLVED.format(n=n, k=unresolved))
+            (PRIORITY_LEAF_FOLLOWUP, TPL_NEIGHBORS_CALLS_HAS_UNRESOLVED.format(n=page_n, k=unresolved))
         )
     return pairs
 

mcp_v2.py

@@ -392,7 +392,7 @@ class SearchHit(BaseModel):
 
 class NodeRef(BaseModel):
     id: str
-    kind: Literal["symbol", "route", "client", "producer"]
+    kind: Literal["symbol", "route", "client", "producer", "unresolved_call_site"]
     fqn: str
     symbol_kind: str | None = None
     microservice: str | None = None
@@ -550,7 +550,11 @@ class ResolveOutput(BaseModel):
     hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
 
 
-def _node_kind_from_id(id_str: str) -> Literal["symbol", "route", "client", "producer"]:
+def _node_kind_from_id(
+    id_str: str,
+) -> Literal["symbol", "route", "client", "producer", "unresolved_call_site"]:
+    if id_str.startswith("ucs:"):
+        return "unresolved_call_site"
     if id_str.startswith("sym:"):
         return "symbol"
     if id_str.startswith("route:") or id_str.startswith("r:"):
@@ -562,7 +566,10 @@ def _node_kind_from_id(id_str: str) -> Literal["symbol", "route", "client", "pro
     raise ValueError(f"Unknown id prefix for `{id_str}`")
 
 
-def _resolve_node_kind(graph: KuzuGraph, node_id: str) -> Literal["symbol", "route", "client", "producer"]:
+def _resolve_node_kind(
+    graph: KuzuGraph,
+    node_id: str,
+) -> Literal["symbol", "route", "client", "producer", "unresolved_call_site"]:
     try:
         return _node_kind_from_id(node_id)
     except ValueError:
@@ -1464,7 +1471,7 @@ def _unresolved_site_to_edge(origin_id: str, row: dict[str, Any]) -> Edge:
         origin_id=origin_id,
         edge_type="CALLS",
         direction="out",
-        other=NodeRef(id=ucs_id, kind="symbol", fqn=ucs_id, name=callee),
+        other=NodeRef(id=ucs_id, kind="unresolved_call_site", fqn="", name=callee),
         attrs={
             "row_kind": "unresolved_call_site",
             "unresolved_call_site_id": ucs_id,
@@ -1711,8 +1718,10 @@ def neighbors_v2(
         results: list[Edge] = []
         unfiltered_calls_count: int | None = None
         unresolved_count: int | None = None
+        calls_row_count: int | None = None
         if use_calls_path and len(origins) == 1 and direction == "out":
             unresolved_count = g.count_unresolved_for_caller(origins[0])
+            calls_row_count = g.count_calls_for_symbol(origins[0], direction=direction)
         for origin_id in origins:
             origin_kind = _resolve_node_kind(g, origin_id)
             if composed_keys:
@@ -1867,6 +1876,7 @@ def neighbors_v2(
             "dedup_calls": dedup_calls,
             "unfiltered_calls_count": unfiltered_calls_count,
             "unresolved_count": unresolved_count,
+            "calls_row_count": calls_row_count,
         }
         return NeighborsOutput(
             success=True,

tests/test_java_codebase_rag_cli.py

@@ -42,9 +42,17 @@ def _base_env(corpus_root: Path, kuzu_db_path: Path | None = None) -> dict[str,
     return env
 
 
-def _run_cli(args: list[str], *, env: dict[str, str], stdin: str | None = None) -> subprocess.CompletedProcess:
+def _java_codebase_rag_exe() -> str:
+    venv_exe = Path(sys.executable).parent / "java-codebase-rag"
+    if venv_exe.is_file():
+        return str(venv_exe)
     exe = shutil.which("java-codebase-rag")
     assert exe is not None, "expected installed java-codebase-rag entrypoint"
+    return exe
+
+
+def _run_cli(args: list[str], *, env: dict[str, str], stdin: str | None = None) -> subprocess.CompletedProcess:
+    exe = _java_codebase_rag_exe()
     return subprocess.run(
         [exe, *args],
         capture_output=True,
@@ -76,7 +84,7 @@ def test_cli_erase_refuses_non_tty_without_yes(tmp_path: Path) -> None:
     env["JAVA_CODEBASE_RAG_INDEX_DIR"] = str(idx)
     env["JAVA_CODEBASE_RAG_SOURCE_ROOT"] = str(tmp_path)
     proc = subprocess.run(
-        [shutil.which("java-codebase-rag"), "erase", "--source-root", str(tmp_path), "--index-dir", str(idx)],
+        [_java_codebase_rag_exe(), "erase", "--source-root", str(tmp_path), "--index-dir", str(idx)],
         capture_output=True,
         text=True,
         env=env,
@@ -439,6 +447,53 @@ def test_cli_tables_lists_known_table(corpus_root, kuzu_db_path) -> None:
     assert "graph" in payload
 
 
+def test_cli_unresolved_calls_list_and_stats(corpus_root, kuzu_db_path) -> None:
+    env = _base_env(corpus_root, kuzu_db_path)
+    stats_proc = _run_cli(
+        ["unresolved-calls", "stats", "--source-root", str(corpus_root), "--by", "reason"],
+        env=env,
+    )
+    assert stats_proc.returncode == 0, stats_proc.stderr
+    stats = json.loads(stats_proc.stdout)
+    assert stats.get("success") is True
+    assert int(stats.get("total") or 0) >= 1
+    assert stats.get("buckets")
+
+    list_proc = _run_cli(
+        [
+            "unresolved-calls",
+            "list",
+            "--source-root",
+            str(corpus_root),
+            "--reason",
+            "chained_receiver",
+            "--limit",
+            "5",
+        ],
+        env=env,
+    )
+    assert list_proc.returncode == 0, list_proc.stderr
+    listed = json.loads(list_proc.stdout)
+    assert listed.get("success") is True
+    sites = listed.get("sites") or []
+    assert sites
+    assert all(str(s.get("id") or "").startswith("ucs:") for s in sites)
+    assert all(s.get("reason") == "chained_receiver" for s in sites)
+
+    bad_reason = _run_cli(
+        [
+            "unresolved-calls",
+            "list",
+            "--source-root",
+            str(corpus_root),
+            "--reason",
+            "phantom",
+        ],
+        env=env,
+    )
+    assert bad_reason.returncode != 0
+
+
 def test_cli_diagnose_ignore_walked_path(corpus_root, kuzu_db_path) -> None:
     env = _base_env(corpus_root, kuzu_db_path)
     path = "chat-assign/src/main/java/com/bank/chat/assign/service/ChatManagementService.java"

tests/test_mcp_hints.py

@@ -501,10 +501,13 @@ def test_hints_neighbors_multi_origin_fuzzy_emits_once() -> None:
 
 def test_hints_neighbors_calls_high_fanout(kuzu_graph) -> None:
     mid = client_message_processor_process_id(kuzu_graph)
-    out = neighbors_v2(mid, direction="out", edge_types=["CALLS"], limit=500, graph=kuzu_graph)
+    out = neighbors_v2(mid, direction="out", edge_types=["CALLS"], limit=25, graph=kuzu_graph)
     assert out.success is True
-    assert len(out.results) >= 10
-    assert mcp_hints.TPL_NEIGHBORS_CALLS_HIGH_FANOUT.format(n=len(out.results)) in out.hints
+    assert len(out.results) == 25
+    total_calls = kuzu_graph.count_calls_for_symbol(mid, direction="out")
+    assert total_calls >= 10
+    assert mcp_hints.TPL_NEIGHBORS_CALLS_HIGH_FANOUT.format(n=total_calls) in out.hints
+    assert mcp_hints.TPL_NEIGHBORS_CALLS_HIGH_FANOUT.format(n=len(out.results)) not in out.hints
 
 
 def test_hints_neighbors_calls_has_unresolved(kuzu_graph) -> None:

tests/test_mcp_v2.py

@@ -1501,6 +1501,12 @@ def test_neighbors_include_unresolved_interleaved_order(kuzu_graph) -> None:
     kinds = [e.attrs.get("row_kind") for e in out.results]
     assert "unresolved_call_site" in kinds
     assert "resolved" in kinds
+    ucs_edges = [e for e in out.results if (e.attrs or {}).get("row_kind") == "unresolved_call_site"]
+    assert ucs_edges
+    for e in ucs_edges:
+        assert e.other.kind == "unresolved_call_site"
+        assert e.other.id.startswith("ucs:")
+        assert not e.other.id.startswith("sym:")
     keys = [
         (
             int(e.attrs.get("call_site_line") or 0),
@@ -1553,10 +1559,18 @@ def test_neighbors_dedup_calls_collapses_identical_dst(kuzu_graph) -> None:
     assert multi, "dedup_calls should emit call_site_count on collapsed rows"
 
 
-def test_find_callers_no_phantom_chained_strategy(kuzu_graph) -> None:
-    edges = kuzu_graph.find_callers("process", depth=1, limit=200)
-    strategies = {e.strategy for e in edges}
-    assert "phantom" not in strategies
-    assert "chained_receiver" not in strategies
+def test_describe_unresolved_call_sites_rollup_cap_footer_and_total(kuzu_graph) -> None:
+    mid = client_message_processor_process_id(kuzu_graph)
+    out = describe_v2(mid, graph=kuzu_graph)
+    assert out.success and out.record
+    data = out.record.data
+    total = int(data.get("unresolved_call_sites_total") or 0)
+    assert total >= 6, "ClientMessageProcessor#process should have multiple unresolved sites"
+    inline = data.get("unresolved_call_sites") or []
+    assert 1 <= len(inline) <= 5
+    if total > len(inline):
+        footer = str(data.get("unresolved_call_sites_footer") or "")
+        assert "unresolved-calls list" in footer
+        assert mid in footer