java-codebase-rag 0.6.6__py3-none-any.whl → 0.8.0__py3-none-any.whl

mcp_v2.py

@@ -4,9 +4,9 @@ Strict frame contract
 ---------------------
 NodeFilter is a typed predicate bag: each populated field maps to one stored graph
 attribute for the selected kind; inapplicable fields fail loud with a teaching message.
-The ``search`` tool's ``query`` parameter is the ranked-text carve-out; structured
-prefix fields (``fqn_prefix``, ``path_prefix``, ``target_path_prefix``) reject ``*``
-and ``?`` — see ``_validate_no_wildcards``.
+The ``search`` tool's ``query`` parameter is the ranked-text carve-out; the substring
+fields (``fqn_contains``, ``path_contains``, ``target_path_contains``, ``topic_contains``)
+match literally (Cypher ``CONTAINS``) — no wildcard/metacharacter handling.
 
 Revisit trigger (``propose/completed/MCP-FILTER-FRAME-PROPOSE.md`` section 3.4.6)
 --------------------------------------------------------------
@@ -22,29 +22,59 @@ import os
 import sys
 from pathlib import Path
 import threading
-from typing import Annotated, Any, Literal, get_args
+from typing import Annotated, Any, Literal, TYPE_CHECKING, get_args
 
 from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError, model_validator, validate_call
-from sentence_transformers import SentenceTransformer
 
+if TYPE_CHECKING:
+    # Eager import would pull torch at module load. The vector stack is optional (graph-only
+    # installs ship without torch/lancedb); it is imported lazily in _get_sentence_transformer.
+    from sentence_transformers import SentenceTransformer
+
+from graph_types import (
+    NodeRef,
+    StructuredHint,
+    _hints_or_skip,
+    _node_ref_from_row,
+    _resolve_node_kind,
+    _to_structured_hints,
+    set_hints_enabled,
+)
 from index_common import SBERT_MODEL
 from java_codebase_rag.config import resolved_sbert_model_for_process_env
-from java_ontology import EDGE_SCHEMA, ResolveReason
+from java_ontology import EDGE_SCHEMA
 from ladybug_queries import LadybugGraph, OVERRIDE_AXIS_COMPOSED_EDGE_TYPES
-from mcp_hints import generate_hints, MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION
-from search_lancedb import TABLES, run_search
-
-# Module-level flag set by server.py at startup from resolved config.
-_hints_enabled: bool = True
-
-
-def set_hints_enabled(enabled: bool) -> None:
-    global _hints_enabled
-    _hints_enabled = enabled
-
-
-def _hints_or_skip(tool: str, payload: dict) -> tuple[list, list]:
-    return generate_hints(tool, payload) if _hints_enabled else ([], [])
+from mcp_hints import MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION
+
+# The vector stack (lancedb/torch, reached via search_lancedb) is optional — it is absent on
+# graph-only installs (macOS Intel). Import eagerly when available so ``run_search``/``TABLES``
+# exist as module attributes (tests monkeypatch ``mcp_v2.run_search``; callers use ``TABLES``);
+# fall back to sentinels on ImportError so importing this module never fails and ``search_v2``
+# can return a clean "vector search unavailable" envelope instead of crashing.
+try:
+    from search_lancedb import TABLES, run_search
+except ImportError:  # graph-only install: no torch/lancedb
+    TABLES = {}
+    run_search = None
+__all__ = [
+    "search_v2",
+    "find_v2",
+    "describe_v2",
+    "neighbors_v2",
+    "resolve_v2",
+    "SearchOutput",
+    "FindOutput",
+    "DescribeOutput",
+    "NeighborsOutput",
+    "ResolveOutput",
+    "ResolveCandidate",
+    "ResolveStatus",
+    "NodeRef",
+    "NodeFilter",
+    "EdgeFilter",
+    "StructuredHint",
+    "set_hints_enabled",
+]
 
 DeclarationSymbolKind = Literal["class", "interface", "enum", "record", "annotation", "method", "constructor"]
 
@@ -119,11 +149,18 @@ _fail_loud_lock = threading.Lock()
 
 
 def _log_fail_loud(category: str) -> None:
-    """Increment process-local fail-loud counter and emit one stderr line (PR-FRAME-3)."""
+    """Increment process-local fail-loud counter and emit one stderr line (PR-FRAME-3).
+
+    The stderr line is gated on ``JAVA_CODEBASE_RAG_FAIL_LOUD`` (default ``"1"`` =
+    emit) so the MCP server keeps its operator diagnostic while the agent-facing
+    ``jrag`` CLI (which surfaces the same failure as a clean status:error
+    envelope) can run it with the diagnostic silenced.
+    """
     with _fail_loud_lock:
         _fail_loud_counts[category] = _fail_loud_counts.get(category, 0) + 1
         n = _fail_loud_counts[category]
-    print(f"[filter-frame] fail-loud category={category} count={n}", file=sys.stderr, flush=True)
+    if os.environ.get("JAVA_CODEBASE_RAG_FAIL_LOUD", "1") != "0":
+        print(f"[filter-frame] fail-loud category={category} count={n}", file=sys.stderr, flush=True)
 
 
 def filter_frame_counters() -> dict[str, int]:
@@ -134,6 +171,8 @@ def filter_frame_counters() -> dict[str, int]:
 
 def _get_sentence_transformer(model_name: str, device: str | None) -> SentenceTransformer:
     global _st_model
+    from sentence_transformers import SentenceTransformer
+
     with _st_lock:
         if _st_model is None:
             _st_model = SentenceTransformer(
@@ -154,26 +193,26 @@ class NodeFilter(BaseModel):
     exclude_roles: list[Role] | None = None
     annotation: str | None = None
     capability: str | None = None
-    fqn_prefix: str | None = None
+    fqn_contains: str | None = None
     symbol_kind: DeclarationSymbolKind | None = None
     symbol_kinds: list[DeclarationSymbolKind] | None = None
     http_method: str | None = Field(
         default=None,
         description="HTTP verb (commonly GET/POST/PUT/DELETE/PATCH; user route annotations may yield others).",
     )
-    path_prefix: str | None = None
+    path_contains: str | None = None
     framework: Framework | None = None
     client_kind: ClientKind | None = Field(
         default=None,
         description="Outbound HTTP client kind: feign_method, rest_template, or web_client.",
     )
     target_service: str | None = None
-    target_path_prefix: str | None = None
+    target_path_contains: str | None = None
     producer_kind: ProducerKind | None = Field(
         default=None,
         description="Outbound async producer kind: kafka_send or stream_bridge_send.",
     )
-    topic_prefix: str | None = None
+    topic_contains: str | None = None
 
 
 class EdgeFilter(BaseModel):
@@ -213,12 +252,8 @@ _NODEFILTER_FIELD_ORDER: tuple[str, ...] = tuple(NodeFilter.model_fields.keys())
 _EDGEFILTER_FIELD_ORDER: tuple[str, ...] = tuple(EdgeFilter.model_fields.keys())
 
 
-class StructuredHint(BaseModel):
-    label: str = ""
-    tool: Literal["search", "find", "describe", "neighbors", "resolve"]
-    args: dict[str, Any]
-    actionable: bool = True
-    reason: str = ""
+# StructuredHint is now defined in graph_types.py and imported above
+
 
 # Populated EdgeFilter field -> EDGE_SCHEMA attribute name used in Cypher pushdown.
 _EDGEFILTER_FIELD_TO_ATTR: dict[str, str] = {
@@ -240,7 +275,7 @@ _NODEFILTER_APPLICABLE_FIELDS: dict[Literal["symbol", "route", "client", "produc
         "exclude_roles",
         "annotation",
         "capability",
-        "fqn_prefix",
+        "fqn_contains",
         "symbol_kind",
         "symbol_kinds",
     ),
@@ -248,7 +283,7 @@ _NODEFILTER_APPLICABLE_FIELDS: dict[Literal["symbol", "route", "client", "produc
         "microservice",
         "module",
         "http_method",
-        "path_prefix",
+        "path_contains",
         "framework",
     ),
     "client": (
@@ -257,7 +292,7 @@ _NODEFILTER_APPLICABLE_FIELDS: dict[Literal["symbol", "route", "client", "produc
         "source_layer",
         "client_kind",
         "target_service",
-        "target_path_prefix",
+        "target_path_contains",
         "http_method",
     ),
     "producer": (
@@ -265,7 +300,7 @@ _NODEFILTER_APPLICABLE_FIELDS: dict[Literal["symbol", "route", "client", "produc
         "module",
         "source_layer",
         "producer_kind",
-        "topic_prefix",
+        "topic_contains",
     ),
 }
 
@@ -308,20 +343,6 @@ def _nodefilter_applicability_error(
     )
 
 
-def _validate_no_wildcards(nf: NodeFilter) -> str | None:
-    """Reject ``*`` / ``?`` in prefix-match fields; wildcards belong in ``search(query=…)``."""
-    for field_name in ("fqn_prefix", "path_prefix", "target_path_prefix"):
-        val = getattr(nf, field_name)
-        if val is None:
-            continue
-        if "*" in val or "?" in val:
-            return (
-                f"Wildcards (* and ?) are not supported in structured filter field `{field_name}`; "
-                "use search(query=...) for ranked text match instead."
-            )
-    return None
-
-
 def _filter_validation_error_message(exc: ValidationError) -> str:
     items: list[str] = []
     for err in exc.errors():
@@ -385,8 +406,7 @@ def _edgefilter_applicability_error(edge_types: list[str], ef: EdgeFilter) -> st
     return None
 
 
-def _to_structured_hints(raw: list[Any]) -> list[StructuredHint]:
-    return [StructuredHint(label=h.label, tool=h.tool, args=h.args, actionable=h.actionable, reason=h.reason) for h in raw]
+# _to_structured_hints is now defined in graph_types.py and imported above
 
 
 def _coerce_edge_filter(
@@ -444,16 +464,11 @@ class SearchHit(BaseModel):
     microservice: str | None = None
     module: str | None = None
     role: str | None = None
+    filename: str | None = None
+    start_line: int | None = None
 
 
-class NodeRef(BaseModel):
-    id: str
-    kind: Literal["symbol", "route", "client", "producer", "unresolved_call_site"]
-    fqn: str
-    symbol_kind: str | None = None
-    microservice: str | None = None
-    module: str | None = None
-    role: str | None = None
+# NodeRef is now defined in graph_types.py and imported above
 
 
 class NodeRecord(BaseModel):
@@ -517,6 +532,11 @@ class FindOutput(BaseModel):
         default=None,
         description="Echoed from the request — the page offset the server applied. None on success=False.",
     )
+    has_more_results: bool | None = Field(
+        default=None,
+        description="True when additional pages remain beyond offset+limit (more matches exist). "
+        "None when unset (e.g. success=False).",
+    )
     advisories: list[str] = Field(default_factory=list, description="Pure informational text with no tool call suggestion")
     hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
@@ -537,114 +557,21 @@ class NeighborsOutput(BaseModel):
         default_factory=list,
         description="Echo of neighbors(edge_types=...) from the request; empty when success=False.",
     )
+    has_more_results: bool | None = Field(
+        default=None,
+        description="True when additional pages remain beyond offset+limit. None when unset or "
+        "when the single-origin CALLS path paginated in SQL (use unfiltered_calls_count / "
+        "calls_row_count there).",
+    )
     advisories: list[str] = Field(default_factory=list, description="Pure informational text with no tool call suggestion")
     hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
-ResolveStatus = Literal["one", "many", "none"]
-
-_RESOLVE_CANDIDATE_CAP = 10
-
-_RESOLVE_REASON_PRIORITY: dict[ResolveReason, int] = {
-    "exact_id": 0,
-    "exact_fqn": 1,
-    "route_method_path": 1,
-    "client_target_path": 1,
-    "producer_topic_prefix": 1,
-    "fqn_suffix": 2,
-    "route_template": 2,
-    "short_name": 3,
-    "client_target": 3,
-    "producer_topic": 3,
-}
-
-_SYMBOL_RESOLVE_RETURN = (
-    "s.id AS id, s.fqn AS fqn, s.microservice AS microservice, "
-    "s.module AS module, s.role AS role, s.kind AS symbol_kind"
-)
-
-_ROUTE_RESOLVE_RETURN = (
-    "r.id AS id, r.kind AS kind, r.framework AS framework, r.method AS method, "
-    "r.path AS path, r.path_template AS path_template, r.path_regex AS path_regex, "
-    "r.topic AS topic, r.broker AS broker, r.feign_name AS feign_name, r.feign_url AS feign_url, "
-    "r.microservice AS microservice, r.module AS module, r.filename AS filename, "
-    "r.start_line AS start_line, r.end_line AS end_line, r.resolved AS resolved"
-)
-
-_CLIENT_RESOLVE_RETURN = (
-    "c.id AS id, c.client_kind AS client_kind, c.target_service AS target_service, "
-    "c.method AS method, c.path AS path, c.path_template AS path_template, "
-    "c.path_regex AS path_regex, c.member_fqn AS member_fqn, c.member_id AS member_id, "
-    "c.microservice AS microservice, c.module AS module, c.filename AS filename, "
-    "c.start_line AS start_line, c.end_line AS end_line, c.resolved AS resolved, "
-    "c.source_layer AS source_layer"
-)
-
-_PRODUCER_RESOLVE_RETURN = (
-    "p.id AS id, p.producer_kind AS producer_kind, p.topic AS topic, p.broker AS broker, "
-    "p.direction AS direction, p.member_fqn AS member_fqn, p.member_id AS member_id, "
-    "p.microservice AS microservice, p.module AS module, p.filename AS filename, "
-    "p.start_line AS start_line, p.end_line AS end_line, p.resolved AS resolved, "
-    "p.source_layer AS source_layer"
-)
-
-_RESOLVE_PRE_DEDUP_LIMIT = 50
+# Re-exported from resolve_service.py (imported at end of module to avoid circular import)
+# resolve_v2, ResolveOutput, ResolveCandidate, ResolveStatus are imported below
 
 
-class ResolveCandidate(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    node: NodeRef
-    score: float
-    reason: ResolveReason
-
-
-class ResolveOutput(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    success: bool
-    status: ResolveStatus
-    node: NodeRef | None = None
-    candidates: list[ResolveCandidate] = Field(default_factory=list)
-    message: str | None = None
-    resolved_identifier: str | None = None
-    advisories: list[str] = Field(default_factory=list, description="Pure informational text with no tool call suggestion")
-    hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
-
-
-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:"):
-        return "route"
-    if id_str.startswith("client:") or id_str.startswith("c:"):
-        return "client"
-    if id_str.startswith("producer:") or id_str.startswith("p:"):
-        return "producer"
-    raise ValueError(f"Unknown id prefix for `{id_str}`")
-
-
-def _resolve_node_kind(
-    graph: LadybugGraph,
-    node_id: str,
-) -> Literal["symbol", "route", "client", "producer", "unresolved_call_site"]:
-    try:
-        return _node_kind_from_id(node_id)
-    except ValueError:
-        pass
-    if graph._rows("MATCH (n:Symbol) WHERE n.id = $id RETURN n.id AS id LIMIT 1", {"id": node_id}):  # noqa: SLF001
-        return "symbol"
-    if graph._rows("MATCH (n:Route) WHERE n.id = $id RETURN n.id AS id LIMIT 1", {"id": node_id}):  # noqa: SLF001
-        return "route"
-    if graph._rows("MATCH (n:Client) WHERE n.id = $id RETURN n.id AS id LIMIT 1", {"id": node_id}):  # noqa: SLF001
-        return "client"
-    if graph._rows("MATCH (n:Producer) WHERE n.id = $id RETURN n.id AS id LIMIT 1", {"id": node_id}):  # noqa: SLF001
-        return "producer"
-    raise ValueError(f"Unknown id prefix for `{node_id}`")
+# _node_kind_from_id and _resolve_node_kind are now defined in graph_types.py and imported above
 
 
 def _chunk_id_from_row(row: dict[str, Any]) -> str:
@@ -658,6 +585,16 @@ def _chunk_id_from_row(row: dict[str, Any]) -> str:
 
 def _row_to_search_hit(row: dict[str, Any]) -> SearchHit:
     score = float(row.get("_rrf_score") or row.get("_score") or 0.0)
+    filename = str(row.get("filename") or "") or None
+    start_line: int | None = None
+    start = row.get("start")
+    if isinstance(start, dict):
+        ln = start.get("line")
+        if ln is not None:
+            try:
+                start_line = int(ln)
+            except (TypeError, ValueError):
+                start_line = None
     return SearchHit(
         chunk_id=_chunk_id_from_row(row),
         symbol_id=_chunk_to_symbol_id(row),
@@ -667,6 +604,8 @@ def _row_to_search_hit(row: dict[str, Any]) -> SearchHit:
         microservice=str(row.get("microservice")) if row.get("microservice") else None,
         module=str(row.get("module")) if row.get("module") else None,
         role=str(row.get("role")) if row.get("role") else None,
+        filename=filename,
+        start_line=start_line,
     )
 
 
@@ -710,9 +649,9 @@ def _symbol_where_from_filter(f: NodeFilter) -> tuple[str, dict[str, Any]]:
     if f.capability:
         preds.append("$capability IN s.capabilities")
         params["capability"] = f.capability
-    if f.fqn_prefix:
-        preds.append("s.fqn STARTS WITH $fqn_prefix")
-        params["fqn_prefix"] = f.fqn_prefix
+    if f.fqn_contains:
+        preds.append("s.fqn CONTAINS $fqn_contains")
+        params["fqn_contains"] = f.fqn_contains
     if f.symbol_kind:
         preds.append("s.kind = $symbol_kind")
         params["symbol_kind"] = f.symbol_kind
@@ -723,38 +662,7 @@ def _symbol_where_from_filter(f: NodeFilter) -> tuple[str, dict[str, Any]]:
     return where, params
 
 
-def _node_ref_from_row(kind: Literal["symbol", "route", "client", "producer"], row: dict[str, Any]) -> NodeRef:
-    symbol_kind: str | None = None
-    if kind == "symbol":
-        fqn = str(row.get("fqn") or "")
-        role = str(row.get("role") or "") or None
-        symbol_kind_val = str(row.get("symbol_kind") or row.get("kind") or "").strip()
-        symbol_kind = symbol_kind_val or None
-    elif kind == "route":
-        method = str(row.get("method") or "")
-        path = str(row.get("path_template") or row.get("path") or "")
-        fqn = f"{method} {path}".strip()
-        role = None
-    elif kind == "client":
-        method = str(row.get("method") or "")
-        target = str(row.get("target_service") or "")
-        path = str(row.get("path_template") or row.get("path") or "")
-        fqn = f"{target} {method} {path}".strip()
-        role = None
-    else:
-        topic = str(row.get("topic") or "")
-        broker = str(row.get("broker") or "")
-        fqn = f"{topic} {broker}".strip()
-        role = None
-    return NodeRef(
-        id=str(row.get("id") or ""),
-        kind=kind,
-        fqn=fqn,
-        symbol_kind=symbol_kind,
-        microservice=str(row.get("microservice") or "") or None,
-        module=str(row.get("module") or "") or None,
-        role=role,
-    )
+# _node_ref_from_row is now defined in graph_types.py and imported above
 
 
 def _load_node_record(
@@ -868,7 +776,7 @@ def _node_matches_filter(
             return False
         if f.capability and f.capability not in list(row.get("capabilities") or []):
             return False
-        if f.fqn_prefix and not fqn_val.startswith(f.fqn_prefix):
+        if f.fqn_contains and f.fqn_contains not in fqn_val:
             return False
         if f.symbol_kind and symbol_kind_val != f.symbol_kind:
             return False
@@ -877,9 +785,9 @@ def _node_matches_filter(
     elif kind == "route":
         if f.http_method and str(row.get("method") or "") != f.http_method:
             return False
-        if f.path_prefix:
+        if f.path_contains:
             path = str(row.get("path") or "")
-            if not path.startswith(f.path_prefix):
+            if f.path_contains not in path:
                 return False
         if f.framework and str(row.get("framework") or "") != f.framework:
             return False
@@ -888,18 +796,18 @@ def _node_matches_filter(
             return False
         if f.target_service and str(row.get("target_service") or "") != f.target_service:
             return False
-        if f.target_path_prefix:
+        if f.target_path_contains:
             path = str(row.get("path") or "")
-            if not path.startswith(f.target_path_prefix):
+            if f.target_path_contains not in path:
                 return False
         if f.http_method and str(row.get("method") or "") != f.http_method:
             return False
     else:
         if f.producer_kind and str(row.get("producer_kind") or "") != f.producer_kind:
             return False
-        if f.topic_prefix:
+        if f.topic_contains:
             topic = str(row.get("topic") or "")
-            if not topic.startswith(f.topic_prefix):
+            if f.topic_contains not in topic:
                 return False
     return True
 
@@ -934,9 +842,16 @@ def search_v2(
         if nf and (err := _nodefilter_applicability_error("symbol", nf)):
             _log_fail_loud("applicability")
             return SearchOutput(success=False, message=err, advisories=[], limit=None, offset=None)
-        if nf and (err := _validate_no_wildcards(nf)):
-            _log_fail_loud("wildcard")
-            return SearchOutput(success=False, message=err, advisories=[], limit=None, offset=None)
+        if run_search is None:
+            # Graph-only install (no torch/lancedb): the vector stack is absent. Return a
+            # clean failure rather than crashing so the server keeps serving graph tools.
+            return SearchOutput(
+                success=False,
+                message="Vector search unavailable: graph-only mode (vector stack not installed).",
+                advisories=[],
+                limit=None,
+                offset=None,
+            )
         model_name = resolved_sbert_model_for_process_env(SBERT_MODEL)
         device = os.environ.get("SBERT_DEVICE") or None
         model = _get_sentence_transformer(model_name, device)
@@ -958,6 +873,17 @@ def search_v2(
             model_name=model_name,
             device=device,
             model=model,
+            # Push the NodeFilter structural predicates into the LanceDB query so
+            # they apply BEFORE pagination (issue #353) — previously they were only
+            # a post-filter on the already-paginated page, which could shrink or
+            # empty filtered pages even when many matches existed deeper in the
+            # ranking. _node_matches_filter below still re-checks every row (it
+            # covers the non-pushdownable fields and is the contract guarantee).
+            role=nf.role if nf else None,
+            module=nf.module if nf else None,
+            microservice=nf.microservice if nf else None,
+            capability=nf.capability if nf else None,
+            exclude_roles=nf.exclude_roles if nf else None,
         )
         hits: list[SearchHit] = []
         for row in rows:
@@ -1013,9 +939,6 @@ def find_v2(
         if err := _nodefilter_applicability_error(kind, nf):
             _log_fail_loud("applicability")
             return FindOutput(success=False, message=err, advisories=[], limit=None, offset=None)
-        if err := _validate_no_wildcards(nf):
-            _log_fail_loud("wildcard")
-            return FindOutput(success=False, message=err, advisories=[], limit=None, offset=None)
         fetch_cap = int(limit) + int(offset) + 1
         if kind == "symbol":
             where, params = _symbol_where_from_filter(nf)
@@ -1029,7 +952,7 @@ def find_v2(
             rows = g.list_routes(
                 microservice=nf.microservice,
                 framework=nf.framework,
-                path_prefix=nf.path_prefix,
+                path_contains=nf.path_contains,
                 method=nf.http_method,
                 limit=max(500, fetch_cap),
             )
@@ -1039,7 +962,7 @@ def find_v2(
                 microservice=nf.microservice,
                 client_kind=nf.client_kind,
                 target_service=nf.target_service,
-                path_prefix=nf.target_path_prefix,
+                path_contains=nf.target_path_contains,
                 method=nf.http_method,
                 limit=max(500, fetch_cap),
             )
@@ -1048,7 +971,7 @@ def find_v2(
             rows = g.list_producers(
                 microservice=nf.microservice,
                 producer_kind=nf.producer_kind,
-                topic_prefix=nf.topic_prefix,
+                topic_contains=nf.topic_contains,
                 limit=max(500, fetch_cap),
             )
             rows = [r for r in rows if _node_matches_filter("producer", r, nf)]
@@ -1059,7 +982,12 @@ def find_v2(
         hint_payload: dict[str, Any] = {
             "success": True,
             "kind": kind,
-            "results": [r.model_dump() for r in refs],
+            # exclude_none: this dict feeds generate_hints (which reads fields
+            # defensively via .get), not the tool result (FindOutput below holds the
+            # pydantic objects). Drop null fields -- including the NodeRef.name field
+            # that is None for every structured ref -- to match filter_dump above and
+            # avoid spurious "name": null noise in the hint input.
+            "results": [r.model_dump(exclude_none=True) for r in refs],
             "limit": limit,
             "offset": offset,
             "filter": filter_dump,
@@ -1071,6 +999,7 @@ def find_v2(
             results=refs,
             limit=limit,
             offset=offset,
+            has_more_results=has_more_results,
             advisories=raw_advisories,
             hints_structured=_to_structured_hints(raw_struct),
         )
@@ -1159,379 +1088,28 @@ def describe_v2(
         return DescribeOutput(success=False, message=str(exc), advisories=[])
 
 
-def _resolve_validate_identifier(raw: str) -> tuple[str | None, str | None]:
-    trimmed = raw.strip()
-    if not trimmed:
-        detail = "empty string" if raw == "" else "whitespace only"
-        return None, f"Invalid identifier: {detail}"
-    return trimmed, None
-
-
-def _resolve_kinds_to_search(
-    hint_kind: Literal["symbol", "route", "client", "producer"] | None,
-) -> list[Literal["symbol", "route", "client", "producer"]]:
-    if hint_kind is None:
-        return ["symbol", "route", "client", "producer"]
-    return [hint_kind]
-
-
-def _resolve_parse_route_method_path(identifier: str) -> tuple[str, str] | None:
-    parts = identifier.split(None, 1)
-    if len(parts) != 2:
-        return None
-    method, path = parts[0].upper(), parts[1].strip()
-    if not method.isalpha() or not path.startswith("/"):
-        return None
-    return method, path
-
-
-def _resolve_parse_microservice_route(identifier: str) -> tuple[str, str, str] | None:
-    parts = identifier.split(None, 2)
-    if len(parts) != 3:
-        return None
-    microservice, method, path = parts[0], parts[1].upper(), parts[2].strip()
-    if not method.isalpha() or not path.startswith("/"):
-        return None
-    return microservice, method, path
-
-
-def _resolve_symbol_candidates(
-    g: LadybugGraph,
-    identifier: str,
-) -> list[tuple[NodeRef, ResolveReason, int]]:
-    out: list[tuple[NodeRef, ResolveReason, int]] = []
-    lim = _RESOLVE_PRE_DEDUP_LIMIT
-
-    rows = g._rows(  # noqa: SLF001
-        f"MATCH (s:Symbol) WHERE s.id = $id RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
-        {"id": identifier, "lim": lim},
-    )
-    for row in rows:
-        out.append((_node_ref_from_row("symbol", row), "exact_id", len(identifier)))
-
-    rows = g._rows(  # noqa: SLF001
-        f"MATCH (s:Symbol) WHERE s.fqn = $fqn RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
-        {"fqn": identifier, "lim": lim},
-    )
-    for row in rows:
-        out.append((_node_ref_from_row("symbol", row), "exact_fqn", len(identifier)))
-
-    suffix = f".{identifier}"
-    rows = g._rows(  # noqa: SLF001
-        f"MATCH (s:Symbol) WHERE s.fqn = $ident OR s.fqn ENDS WITH $suffix "
-        f"RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
-        {"ident": identifier, "suffix": suffix, "lim": lim},
-    )
-    for row in rows:
-        fqn = str(row.get("fqn") or "")
-        spec = len(fqn)
-        out.append((_node_ref_from_row("symbol", row), "fqn_suffix", spec))
-
-    rows = g._rows(  # noqa: SLF001
-        f"MATCH (s:Symbol) WHERE s.name = $name RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
-        {"name": identifier, "lim": lim},
-    )
-    for row in rows:
-        out.append((_node_ref_from_row("symbol", row), "short_name", len(identifier)))
-
-    return out
-
-
-def _resolve_route_candidates(
-    g: LadybugGraph,
-    identifier: str,
-) -> list[tuple[NodeRef, ResolveReason, int]]:
-    out: list[tuple[NodeRef, ResolveReason, int]] = []
-    lim = _RESOLVE_PRE_DEDUP_LIMIT
-
-    rows = g._rows(  # noqa: SLF001
-        f"MATCH (r:Route) WHERE r.id = $id RETURN {_ROUTE_RESOLVE_RETURN} LIMIT $lim",
-        {"id": identifier, "lim": lim},
-    )
-    for row in rows:
-        out.append((_node_ref_from_row("route", row), "exact_id", len(identifier)))
-
-    ms_route = _resolve_parse_microservice_route(identifier)
-    if ms_route is not None:
-        microservice, method, path = ms_route
-        rows = g._rows(  # noqa: SLF001
-            f"MATCH (r:Route) WHERE r.microservice = $ms AND r.method = $method "
-            f"AND (r.path = $path OR r.path_template = $path) "
-            f"RETURN {_ROUTE_RESOLVE_RETURN} LIMIT $lim",
-            {"ms": microservice, "method": method, "path": path, "lim": lim},
-        )
-        for row in rows:
-            spec = len(path)
-            out.append((_node_ref_from_row("route", row), "route_method_path", spec))
-
-    method_path = _resolve_parse_route_method_path(identifier)
-    if method_path is not None:
-        method, path = method_path
-        rows = g._rows(  # noqa: SLF001
-            f"MATCH (r:Route) WHERE r.method = $method "
-            f"AND (r.path = $path OR r.path_template = $path) "
-            f"RETURN {_ROUTE_RESOLVE_RETURN} LIMIT $lim",
-            {"method": method, "path": path, "lim": lim},
-        )
-        for row in rows:
-            out.append((_node_ref_from_row("route", row), "route_method_path", len(path)))
-
-    if identifier.startswith("/"):
-        rows = g._rows(  # noqa: SLF001
-            f"MATCH (r:Route) WHERE r.path = $path OR r.path_template = $path "
-            f"RETURN {_ROUTE_RESOLVE_RETURN} LIMIT $lim",
-            {"path": identifier, "lim": lim},
-        )
-        for row in rows:
-            path_val = str(row.get("path_template") or row.get("path") or "")
-            out.append((_node_ref_from_row("route", row), "route_template", len(path_val)))
 
-    return out
 
-
-def _resolve_client_candidates(
-    g: LadybugGraph,
-    identifier: str,
-) -> list[tuple[NodeRef, ResolveReason, int]]:
-    out: list[tuple[NodeRef, ResolveReason, int]] = []
-    lim = _RESOLVE_PRE_DEDUP_LIMIT
-
-    rows = g._rows(  # noqa: SLF001
-        f"MATCH (c:Client) WHERE c.id = $id RETURN {_CLIENT_RESOLVE_RETURN} LIMIT $lim",
-        {"id": identifier, "lim": lim},
-    )
-    for row in rows:
-        out.append((_node_ref_from_row("client", row), "exact_id", len(identifier)))
-
-    if " " in identifier:
-        target, path_prefix = identifier.split(" ", 1)
-        target = target.strip()
-        path_prefix = path_prefix.strip()
-        if target and path_prefix:
-            rows = g._rows(  # noqa: SLF001
-                f"MATCH (c:Client) WHERE c.target_service = $target "
-                f"AND (c.path STARTS WITH $path OR c.path_template STARTS WITH $path) "
-                f"RETURN {_CLIENT_RESOLVE_RETURN} LIMIT $lim",
-                {"target": target, "path": path_prefix, "lim": lim},
-            )
-            for row in rows:
-                spec = len(path_prefix)
-                out.append((_node_ref_from_row("client", row), "client_target_path", spec))
-    elif not identifier.startswith("/"):
-        rows = g._rows(  # noqa: SLF001
-            f"MATCH (c:Client) WHERE c.target_service = $target RETURN {_CLIENT_RESOLVE_RETURN} LIMIT $lim",
-            {"target": identifier, "lim": lim},
-        )
-        for row in rows:
-            out.append((_node_ref_from_row("client", row), "client_target", len(identifier)))
-
-    return out
-
-
-def _resolve_producer_candidates(
-    g: LadybugGraph,
-    identifier: str,
-) -> list[tuple[NodeRef, ResolveReason, int]]:
-    out: list[tuple[NodeRef, ResolveReason, int]] = []
-    lim = _RESOLVE_PRE_DEDUP_LIMIT
-
-    rows = g._rows(  # noqa: SLF001
-        f"MATCH (p:Producer) WHERE p.id = $id RETURN {_PRODUCER_RESOLVE_RETURN} LIMIT $lim",
-        {"id": identifier, "lim": lim},
-    )
-    for row in rows:
-        out.append((_node_ref_from_row("producer", row), "exact_id", len(identifier)))
-
-    rows = g._rows(  # noqa: SLF001
-        f"MATCH (p:Producer) WHERE p.topic = $topic RETURN {_PRODUCER_RESOLVE_RETURN} LIMIT $lim",
-        {"topic": identifier, "lim": lim},
-    )
-    for row in rows:
-        out.append((_node_ref_from_row("producer", row), "producer_topic", len(identifier)))
-
-    if not identifier.startswith("/"):
-        rows = g._rows(  # noqa: SLF001
-            f"MATCH (p:Producer) WHERE p.topic STARTS WITH $topic RETURN {_PRODUCER_RESOLVE_RETURN} LIMIT $lim",
-            {"topic": identifier, "lim": lim},
-        )
-        for row in rows:
-            out.append((_node_ref_from_row("producer", row), "producer_topic_prefix", len(identifier)))
-
-    return out
-
-
-def _resolve_dedupe_candidates(
-    raw: list[tuple[NodeRef, ResolveReason, int]],
-) -> list[tuple[NodeRef, ResolveReason, int]]:
-    best: dict[str, tuple[NodeRef, ResolveReason, int]] = {}
-    for node, reason, specificity in raw:
-        prev = best.get(node.id)
-        if prev is None:
-            best[node.id] = (node, reason, specificity)
-            continue
-        prev_pri = _RESOLVE_REASON_PRIORITY[prev[1]]
-        new_pri = _RESOLVE_REASON_PRIORITY[reason]
-        if new_pri < prev_pri or (new_pri == prev_pri and specificity > prev[2]):
-            best[node.id] = (node, reason, specificity)
-    return list(best.values())
-
-
-def _resolve_rank_candidates(
-    deduped: list[tuple[NodeRef, ResolveReason, int]],
-) -> list[ResolveCandidate]:
-    ordered = sorted(
-        deduped,
-        key=lambda item: (_RESOLVE_REASON_PRIORITY[item[1]], -item[2], item[0].id),
-    )
-    total = len(ordered)
-    return [
-        ResolveCandidate(
-            node=node,
-            reason=reason,
-            score=(1.0 - (idx / total)) if total else 0.0,
-        )
-        for idx, (node, reason, _spec) in enumerate(ordered)
-    ]
-
-
-def _resolve_assert_invariants(out: ResolveOutput) -> None:
-    if not out.success:
-        assert out.status == "none"
-        assert out.node is None
-        assert not out.candidates
-        assert out.message
-        return
-    if out.status == "one":
-        assert out.node is not None
-        assert not out.candidates
-    elif out.status == "many":
-        assert out.node is None
-        assert len(out.candidates) >= 2
-    elif out.status == "none":
-        assert out.node is None
-        assert not out.candidates
-        assert out.message
-
-
-def _resolve_seeds_for_hints(identifier: str) -> tuple[str | None, str | None]:
-    path_prefix_seed: str | None = None
-    method_path = _resolve_parse_route_method_path(identifier)
-    if method_path is not None:
-        path_prefix_seed = method_path[1]
-    else:
-        ms_route = _resolve_parse_microservice_route(identifier)
-        if ms_route is not None:
-            path_prefix_seed = ms_route[2]
-        elif identifier.startswith("/"):
-            path_prefix_seed = identifier
-
-    target_service_seed: str | None = None
-    if " " in identifier:
-        target, _path_prefix = identifier.split(" ", 1)
-        target = target.strip()
-        if target:
-            target_service_seed = target
-    elif not identifier.startswith("/"):
-        target_service_seed = identifier
-
-    return path_prefix_seed, target_service_seed
-
-
-def _resolve_finalize_success(
-    trimmed: str,
-    hint_kind: Literal["symbol", "route", "client", "producer"] | None,
-    matches: list[ResolveCandidate],
-) -> ResolveOutput:
-    if not matches:
-        out = ResolveOutput(
-            success=True,
-            status="none",
-            message=(
-                "No matches for identifier; use search(query=...) for ranked fuzzy lookup."
-            ),
-            resolved_identifier=trimmed,
-        )
-    elif len(matches) == 1:
-        out = ResolveOutput(
-            success=True,
-            status="one",
-            node=matches[0].node,
-            resolved_identifier=trimmed,
-        )
-    else:
-        out = ResolveOutput(
-            success=True,
-            status="many",
-            candidates=matches,
-            resolved_identifier=trimmed,
-        )
-
-    path_prefix_seed, target_service_seed = _resolve_seeds_for_hints(trimmed)
-    hint_payload = {
-        "status": out.status,
-        "resolved_identifier": trimmed,
-        "candidates": out.candidates,
-        "hint_kind": hint_kind,
-        "path_prefix_seed": path_prefix_seed,
-        "target_service_seed": target_service_seed,
-    }
-    raw_struct, raw_advisories = _hints_or_skip("resolve", hint_payload)
-    out = out.model_copy(update={
-        "advisories": raw_advisories,
-        "hints_structured": _to_structured_hints(raw_struct),
-    })
-    _resolve_assert_invariants(out)
-    return out
-
-
-def resolve_v2(
-    identifier: str,
-    hint_kind: Literal["symbol", "route", "client", "producer"] | None = None,
-    graph: LadybugGraph | None = None,
-) -> ResolveOutput:
-    try:
-        trimmed, err = _resolve_validate_identifier(identifier)
-        if err is not None:
-            out = ResolveOutput(
-                success=False,
-                status="none",
-                message=err,
-                advisories=[],
-                resolved_identifier=None,
-            )
-            _resolve_assert_invariants(out)
-            return out
-
-        assert trimmed is not None
-        if "*" in trimmed or "?" in trimmed:
-            return _resolve_finalize_success(trimmed, hint_kind, [])
-
-        g = graph or LadybugGraph.get()
-        raw: list[tuple[NodeRef, ResolveReason, int]] = []
-        for kind in _resolve_kinds_to_search(hint_kind):
-            if kind == "symbol":
-                raw.extend(_resolve_symbol_candidates(g, trimmed))
-            elif kind == "route":
-                raw.extend(_resolve_route_candidates(g, trimmed))
-            elif kind == "client":
-                raw.extend(_resolve_client_candidates(g, trimmed))
-            else:
-                raw.extend(_resolve_producer_candidates(g, trimmed))
-
-        deduped = _resolve_dedupe_candidates(raw)
-        ranked = _resolve_rank_candidates(deduped)
-        capped = ranked[:_RESOLVE_CANDIDATE_CAP]
-        return _resolve_finalize_success(trimmed, hint_kind, capped)
-    except Exception as exc:
-        out = ResolveOutput(
-            success=False,
-            status="none",
-            message=str(exc),
-            advisories=[],
-            resolved_identifier=None,
-        )
-        _resolve_assert_invariants(out)
-        return out
+# Per-edge-type attribute columns selected by the generic (flat-label) neighbors
+# query (issue #356). RETURNing a fixed superset of columns regardless of which
+# edge type matched is the typed-union RETURN anti-pattern: a stricter binder
+# (e.g. Kùzu) errors when a RETURNed column does not exist on the matched type.
+# Selecting columns per edge type keeps the query portable; _neighbor_edge_attrs
+# still drops None/"" so each edge exposes only the attrs that exist for its type.
+# Aligned with the REL TABLE schemas in build_ast_graph.py.
+_FLAT_EDGE_ATTR_COLUMNS: dict[str, tuple[str, ...]] = {
+    "CALLS": ("confidence", "strategy", "source", "call_site_line", "call_site_byte", "arg_count", "resolved"),
+    "HTTP_CALLS": ("confidence", "strategy", "match"),
+    "ASYNC_CALLS": ("confidence", "strategy", "match"),
+    "EXPOSES": ("confidence", "strategy"),
+    "DECLARES_CLIENT": ("confidence", "strategy"),
+    "DECLARES_PRODUCER": ("confidence", "strategy"),
+    "INJECTS": ("mechanism", "annotation", "field_or_param", "resolved"),
+    "EXTENDS": ("resolved",),
+    "IMPLEMENTS": ("resolved",),
+    "DECLARES": (),
+    "OVERRIDES": (),
+}
 
 
 def _neighbor_edge_attrs(row: dict[str, Any]) -> dict[str, Any]:
@@ -1813,9 +1391,6 @@ def neighbors_v2(
                 message=err,
                 requested_edge_types=requested_edge_types,
             )
-        if nf and (err := _validate_no_wildcards(nf)):
-            _log_fail_loud("wildcard")
-            return NeighborsOutput(success=False, message=err, requested_edge_types=[])
         if composed_keys and direction != "out":
             return NeighborsOutput(
                 success=False,
@@ -1896,33 +1471,25 @@ def neighbors_v2(
                 results.extend(origin_edges)
                 continue
             if flat_labels:
-                # Some Cypher binders can drop `label(e) IN $list` in WHERE; use OR of scalar equalities.
-                label_params = [f"l{i}" for i in range(len(flat_labels))]
-                label_predicate = "(" + " OR ".join(f"label(e) = ${name}" for name in label_params) + ")"
-                q_params = {"id": origin_id, **dict(zip(label_params, flat_labels, strict=True))}
-                if direction == "out":
-                    rows = g._rows(  # noqa: SLF001
-                        "MATCH (a)-[e]->(b) WHERE a.id = $id AND "
-                        f"{label_predicate} "
-                        "RETURN b.id AS other_id, label(e) AS edge_type, e.confidence AS confidence, "
-                        "e.strategy AS strategy, e.match AS match, e.mechanism AS mechanism, "
-                        "e.annotation AS annotation, e.field_or_param AS field_or_param, "
-                        "e.source AS source, e.call_site_line AS call_site_line, "
-                        "e.call_site_byte AS call_site_byte, e.arg_count AS arg_count, "
-                        "e.resolved AS resolved",
-                        q_params,
-                    )
-                else:
-                    rows = g._rows(  # noqa: SLF001
-                        "MATCH (a)<-[e]-(b) WHERE a.id = $id AND "
-                        f"{label_predicate} "
-                        "RETURN b.id AS other_id, label(e) AS edge_type, e.confidence AS confidence, "
-                        "e.strategy AS strategy, e.match AS match, e.mechanism AS mechanism, "
-                        "e.annotation AS annotation, e.field_or_param AS field_or_param, "
-                        "e.source AS source, e.call_site_line AS call_site_line, "
-                        "e.call_site_byte AS call_site_byte, e.arg_count AS arg_count, "
-                        "e.resolved AS resolved",
-                        q_params,
+                # Select attribute columns per edge type (issue #356). A single
+                # multi-label query RETURNing a fixed column superset references
+                # columns that don't exist on every matched type — the typed-union
+                # RETURN anti-pattern, which errors on stricter binders (e.g. Kùzu).
+                # Run one single-label query per type, RETURNing only that type's
+                # columns, and merge the rows. `label(e) = $label` scalar equality
+                # (not `label(e) IN [...]`) per the AGENTS.md Cypher note.
+                rows: list[dict[str, Any]] = []
+                match_clause = "MATCH (a)-[e]->(b)" if direction == "out" else "MATCH (a)<-[e]-(b)"
+                for label in flat_labels:
+                    cols = _FLAT_EDGE_ATTR_COLUMNS.get(label, ())
+                    select = "b.id AS other_id, label(e) AS edge_type"
+                    if cols:
+                        select += ", " + ", ".join(f"e.{c} AS {c}" for c in cols)
+                    rows.extend(
+                        g._rows(  # noqa: SLF001
+                            f"{match_clause} WHERE a.id = $id AND label(e) = $label RETURN {select}",
+                            {"id": origin_id, "label": label},
+                        )
                     )
                 for row in rows:
                     other_id = str(row.get("other_id") or "")
@@ -1979,14 +1546,25 @@ def neighbors_v2(
                     )
         if use_calls_path and len(origins) > 1:
             sliced = results[offset : offset + limit]
+            neighbors_has_more = len(results) > offset + limit
+        elif use_calls_path:
+            # Single-origin CALLS path. When paginate_in_sql is True the SQL did
+            # the OFFSET/LIMIT and the row/unfiltered counts carry the has-more
+            # signal, so this field stays None (unknown). When paginate_in_sql is
+            # False (a node_filter is set, include_unresolved, or dedup_calls) we
+            # loaded the FULL matching set with no pushdown, so the client already
+            # has every edge -> False (not None), so a paging client need not probe.
+            sliced = results
+            neighbors_has_more = None if paginate_in_sql else False
         else:
-            sliced = results if use_calls_path else results[offset : offset + limit]
+            sliced = results[offset : offset + limit]
+            neighbors_has_more = len(results) > offset + limit
         first_origin = origins[0]
         origin_kind = _resolve_node_kind(g, first_origin)
         subject_record = _load_node_record(g, first_origin, origin_kind)
         neigh_payload = {
             "success": True,
-            "results": [e.model_dump() for e in sliced],
+            "results": [e.model_dump(exclude_none=True) for e in sliced],
             "requested_edge_types": requested_edge_types,
             "requested_direction": direction,
             "offset": offset,
@@ -2006,6 +1584,7 @@ def neighbors_v2(
             success=True,
             results=sliced,
             requested_edge_types=requested_edge_types,
+            has_more_results=neighbors_has_more,
             advisories=raw_advisories,
             hints_structured=_to_structured_hints(raw_struct),
         )
@@ -2013,3 +1592,12 @@ def neighbors_v2(
         raise
     except Exception as exc:
         return NeighborsOutput(success=False, message=str(exc), advisories=[], requested_edge_types=[])
+
+
+# Re-export resolve symbols from resolve_service.py (imported here to avoid circular import)
+from resolve_service import (  # noqa: E402
+    ResolveCandidate,
+    ResolveOutput,
+    ResolveStatus,
+    resolve_v2,
+)