fix(pr-3 review r2): fail-loud describe(ucs:), EDGE-NAVIGATION appendix, tests

describe rejects ucs: ids with a teaching message; generator documents
UnresolvedCallSite storage; tighten has-unresolved hint and combined dedup+interleave tests.

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

Author: HumanBean17

README.md

@@ -372,7 +372,7 @@ A deterministic property graph derived from tree-sitter Java parsing lives next
 | `Client` | Outbound HTTP / messaging call site |
 | `UnresolvedCallSite` | Receiver-failure call site (`chained_receiver`, `phantom_unresolved_receiver`) — not a `Symbol`; ids use the `ucs:` prefix |
 
-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`).
+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(method_id).unresolved_call_sites`, `neighbors(..., include_unresolved=True)`, or `java-codebase-rag unresolved-calls`).
 
 ### Edge types (MCP-traversable)
 

docs/AGENT-GUIDE.md

@@ -213,7 +213,7 @@ Identifier lookup; three statuses above. Args: `identifier`, optional `hint_kind
 
 One hop. Args: `ids` (string or array), **`direction`**, **`edge_types`**, `limit` (default 25), `offset`, optional `filter` on the other node, optional **`edge_filter`** (`edge_types` must be exactly `['CALLS']` — no composed dot-keys or second stored label; fail-loud otherwise).
 
-**Multiple origin ids:** each id loads the full CALLS stream (or generic hop) in list order; `offset`/`limit` apply to the **concatenated** edge list (`ids[0]` edges first, then `ids[1]`, …), not global source order across origins — a large first origin can leave no rows for later ids within the same page. High fan-out methods are slow; prefer one id per call or a smaller `limit`.
+**Multiple origin ids:** each id loads the full CALLS stream (or generic hop) in list order; `offset`/`limit` apply to the **concatenated** edge list (`ids[0]` edges first, then `ids[1]`, …), not global source order across origins — a large first origin can leave no rows for later ids within the same page. High fan-out methods are slow; prefer one id per call or a smaller `limit`. **Hints:** `TPL_NEIGHBORS_CALLS_HIGH_FANOUT` / `TPL_NEIGHBORS_CALLS_HAS_UNRESOLVED` fire only for a **single** origin id (multi-origin CALLS skips those nudges).
 
 Returns **edges** with `attrs` (`confidence`, `strategy`, `match`, … on cross-service edges) and **`other`** node.
 

docs/EDGE-NAVIGATION.md

@@ -252,3 +252,20 @@
 - `member_subject`: neighbors(['{id}'],'out',['DECLARES_PRODUCER']) then neighbors(producer_ids,'out',['ASYNC_CALLS'])
 - `route_subject`: neighbors(['{id}'],'in',['ASYNC_CALLS']) then neighbors(producer_ids,'in',['DECLARES_PRODUCER']) for declaring method
 - `alien_subject`: ASYNC_CALLS connects Producer→Route; use DECLARES_PRODUCER from a method Symbol, or neighbors(producer_id,'out',['ASYNC_CALLS']) from a Producer id
+
+
+## Graph storage (not MCP `neighbors` edge_types)
+
+### `UnresolvedCallSite` + `UNRESOLVED_AT` (ontology 15 / CALLS-NOISE PR-3)
+
+Receiver-failure call sites (`chained_receiver`, `phantom_unresolved_receiver`) are **not** `CALLS` rows. They are `UnresolvedCallSite` nodes (`id` prefix `ucs:`) linked from the caller method Symbol via `UNRESOLVED_AT`.
+
+| Surface | How to read them |
+| --- | --- |
+| `describe(method_id)` | `record.data.unresolved_call_sites` (capped at 5) + footer when more exist |
+| `neighbors(..., ['CALLS'], include_unresolved=True)` | Interleaved transcript; `row_kind='unresolved_call_site'`; `other.kind=unresolved_call_site` |
+| CLI | `java-codebase-rag unresolved-calls list|stats` |
+
+- **Not** in `EDGE_SCHEMA` — do not pass `UNRESOLVED_AT` to `neighbors(edge_types=…)`.
+- **`describe(ucs:…)`** is invalid (fail-loud); describe the **caller method** instead.
+- Fresh graphs: `CALLS.strategy` no longer includes `phantom` or `chained_receiver` for receiver failure (those literals remain on HTTP/ASYNC `match` and brownfield resolver sets).

mcp_v2.py

@@ -1012,6 +1012,13 @@ def find_v2(
         return FindOutput(success=False, message=str(exc), hints=[], limit=None, offset=None)
 
 
+_DESCRIBE_UCS_ID_MESSAGE = (
+    "UnresolvedCallSite ids (ucs:…) are not describable — use describe(caller_method_id) "
+    "for record.data.unresolved_call_sites, neighbors(..., include_unresolved=True), "
+    "or java-codebase-rag unresolved-calls list --method-id <caller_id>"
+)
+
+
 def describe_v2(
     id: str | None = None,
     fqn: str | None = None,
@@ -1023,6 +1030,8 @@ def describe_v2(
         has_fqn = bool(fqn and str(fqn).strip())
         if not has_id and not has_fqn:
             return DescribeOutput(success=False, message="id or fqn required", hints=[])
+        if has_id and str(id).strip().startswith("ucs:"):
+            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE, hints=[])
         hint_message: str | None = None
         node_id: str
         if has_id:
@@ -1043,6 +1052,8 @@ def describe_v2(
                     "then describe(id=...) on the chosen node"
                 )
         kind = _resolve_node_kind(g, node_id)
+        if kind == "unresolved_call_site":
+            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE, hints=[])
         row = _load_node_record(g, node_id, kind)
         if row is None:
             return DescribeOutput(success=False, message=f"No node found for `{node_id}`", hints=[])

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

@@ -1,6 +1,6 @@
 # CALLS-NOISE-AND-RESOLUTION — clean the CALLS edge by removing one bucket and projecting the other
 
-**Status**: under review
+**Status**: landed (PR-3)
 **Author**: Dmitriy Teriaev + Perplexity Computer
 **Date**: 2026-05-18
 **Tracks**: [#177](https://github.com/HumanBean17/java-codebase-rag/issues/177)

scripts/generate_edge_navigation.py

@@ -18,6 +18,24 @@
 
 _COMPOSED_MEMBER_EDGE_NAMES = frozenset({"EXPOSES", "DECLARES_CLIENT", "DECLARES_PRODUCER"})
 
+_GRAPH_STORAGE_APPENDIX = """
+## Graph storage (not MCP `neighbors` edge_types)
+
+### `UnresolvedCallSite` + `UNRESOLVED_AT` (ontology 15 / CALLS-NOISE PR-3)
+
+Receiver-failure call sites (`chained_receiver`, `phantom_unresolved_receiver`) are **not** `CALLS` rows. They are `UnresolvedCallSite` nodes (`id` prefix `ucs:`) linked from the caller method Symbol via `UNRESOLVED_AT`.
+
+| Surface | How to read them |
+| --- | --- |
+| `describe(method_id)` | `record.data.unresolved_call_sites` (capped at 5) + footer when more exist |
+| `neighbors(..., ['CALLS'], include_unresolved=True)` | Interleaved transcript; `row_kind='unresolved_call_site'`; `other.kind=unresolved_call_site` |
+| CLI | `java-codebase-rag unresolved-calls list|stats` |
+
+- **Not** in `EDGE_SCHEMA` — do not pass `UNRESOLVED_AT` to `neighbors(edge_types=…)`.
+- **`describe(ucs:…)`** is invalid (fail-loud); describe the **caller method** instead.
+- Fresh graphs: `CALLS.strategy` no longer includes `phantom` or `chained_receiver` for receiver failure (those literals remain on HTTP/ASYNC `match` and brownfield resolver sets).
+"""
+
 _DEFAULT_OUT = _REPO_ROOT / "docs" / "EDGE-NAVIGATION.md"
 _BANNER = (
     "# Edge Navigation Schema\n\n"
@@ -75,6 +93,7 @@ def generate_markdown() -> str:
     parts.append("")
     for spec in EDGE_SCHEMA.values():
         parts.extend(_render_edge(spec))
+    parts.append(_GRAPH_STORAGE_APPENDIX.rstrip())
     return "\n".join(parts).rstrip() + "\n"
 
 

tests/test_mcp_hints.py

@@ -512,11 +512,12 @@ def test_hints_neighbors_calls_high_fanout(kuzu_graph) -> None:
 
 def test_hints_neighbors_calls_has_unresolved(kuzu_graph) -> None:
     mid = client_message_processor_process_id(kuzu_graph)
+    unresolved = kuzu_graph.count_unresolved_for_caller(mid)
+    assert unresolved >= 1
     out = neighbors_v2(mid, direction="out", edge_types=["CALLS"], limit=5, graph=kuzu_graph)
     assert out.success is True
-    assert any(
-        mcp_hints.TPL_NEIGHBORS_CALLS_HAS_UNRESOLVED.split("{")[0] in h for h in out.hints
-    )
+    want = mcp_hints.TPL_NEIGHBORS_CALLS_HAS_UNRESOLVED.format(n=len(out.results), k=unresolved)
+    assert want in out.hints
 
 
 def test_hints_neighbors_calls_high_fanout_suppressed_with_edge_filter(kuzu_graph) -> None:

tests/test_mcp_v2.py

@@ -17,6 +17,7 @@
 from java_ontology import VALID_RESOLVE_REASONS
 
 from mcp_v2 import (
+    Edge,
     NodeFilter,
     _NODEFILTER_APPLICABLE_FIELDS,
     describe_v2,
@@ -1559,6 +1560,49 @@ 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_describe_ucs_id_not_describable(kuzu_graph) -> None:
+    rows = kuzu_graph._rows(  # noqa: SLF001
+        "MATCH (u:UnresolvedCallSite) RETURN u.id AS id LIMIT 1",
+    )
+    assert rows
+    ucs_id = str(rows[0]["id"])
+    assert ucs_id.startswith("ucs:")
+    out = describe_v2(ucs_id, graph=kuzu_graph)
+    assert out.success is False
+    assert out.record is None
+    assert "not describable" in (out.message or "").lower()
+    assert "unresolved-calls" in (out.message or "").lower()
+
+
+def test_neighbors_dedup_calls_include_unresolved(kuzu_graph) -> None:
+    mid = client_message_processor_process_id(kuzu_graph)
+    out = neighbors_v2(
+        mid,
+        direction="out",
+        edge_types=["CALLS"],
+        include_unresolved=True,
+        dedup_calls=True,
+        limit=500,
+        graph=kuzu_graph,
+    )
+    assert out.success is True
+    kinds = {str((e.attrs or {}).get("row_kind") or "resolved") for e in out.results}
+    assert "resolved" in kinds
+    assert "unresolved_call_site" in kinds
+    keys = [_calls_transcript_sort_key_from_edge(e) for e in out.results]
+    assert keys == sorted(keys)
+    resolved = [e for e in out.results if (e.attrs or {}).get("row_kind") == "resolved"]
+    assert any(int((e.attrs or {}).get("call_site_count") or 0) > 1 for e in resolved)
+
+
+def _calls_transcript_sort_key_from_edge(edge: Edge) -> tuple[int, int, int]:
+    attrs = edge.attrs or {}
+    line = int(attrs.get("call_site_line") or 0)
+    byte = int(attrs.get("call_site_byte") or 0)
+    kind_rank = 0 if str(attrs.get("row_kind") or "resolved") == "resolved" else 1
+    return (line, byte, kind_rank)
+
+
 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)