java-codebase-rag 0.12.0__py3-none-any.whl → 0.12.2__py3-none-any.whl

java_codebase_rag/mcp/mcp_hints.py

@@ -1,932 +0,0 @@
-"""Pure MCP v2 road-sign hint generation (no graph I/O, no search, no LLM).
-
-Locked v1 catalog: ``propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md`` Appendix A
-(issue #161 producer/override-route amendments in that appendix).
-v2 resolve + neighbors fuzzy-strategy catalog: ``propose/completed/HINTS-V2-PROPOSE.md`` Appendix A.
-v3 empty-neighbors structural catalog: ``propose/completed/HINTS-V3-PROPOSE.md`` §3.1–3.3.
-v4 success-path catalog: ``propose/completed/HINTS-V4-SUCCESS-PATH-PROPOSE.md``.
-Priority cap: same propose §7.12 / ``plans/completed/PLAN-HINTS.md`` principles.
-"""
-
-from __future__ import annotations
-
-import json
-from typing import Any, Literal, NamedTuple
-
-from java_codebase_rag.graph.java_ontology import EDGE_SCHEMA, FUZZY_STRATEGY_SET
-
-# Normative schema description (propose §3.1) — imported by ``mcp_v2`` for Field(description=...).
-MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION = (
-    "Machine-parseable next-action objects. Each element has "
-    "label (short semantic name, e.g. 'routes via members', 'implementors'), "
-    "tool (MCP tool name), args (ready-to-use parameters), and actionable "
-    "(True = direct call with complete args; False = advisory/partial — agent "
-    "fills missing values or uses as guidance). reason explains why the hint was emitted. "
-    "Advisories (separate field) carry pure informational text with no tool call suggestion."
-)
-
-# --- Internal structured hint representation (no mcp_v2 import) ---
-
-
-class _StructuredHint(NamedTuple):
-    tool: str
-    args: dict[str, Any]
-    actionable: bool
-    priority: int
-    label: str = ""
-    reason: str = ""
-
-
-def finalize_structured_hints(scored: list[_StructuredHint]) -> list[_StructuredHint]:
-    """Dedupe by ``(tool, json.dumps(args, sort_keys=True))``, keep highest priority, cap to 5."""
-    best: dict[tuple[str, str], tuple[int, int]] = {}
-    hints: dict[tuple[str, str], _StructuredHint] = {}
-    for idx, h in enumerate(scored):
-        key = (h.tool, json.dumps(h.args, sort_keys=True))
-        prev = best.get(key)
-        if prev is None or h.priority > prev[0]:
-            best[key] = (h.priority, idx)
-            hints[key] = h
-        elif h.priority == prev[0]:
-            best[key] = (h.priority, min(prev[1], idx))
-    ordered = sorted(best.items(), key=lambda kv: (-kv[1][0], kv[1][1]))
-    return [hints[k] for k, _ in ordered[:5]]
-
-
-def finalize_advisories(scored: list[tuple[int, str]]) -> list[str]:
-    """Dedupe identical strings keeping the highest priority; cap to 5 (drop lowest).
-
-    Within the same priority tier, keep advisories in emission order (first scored wins the cap).
-    """
-    best: dict[str, tuple[int, int]] = {}
-    for idx, (pri, text) in enumerate(scored):
-        if not text:
-            continue
-        prev = best.get(text)
-        if prev is None or pri > prev[0]:
-            best[text] = (pri, idx)
-        elif pri == prev[0]:
-            best[text] = (pri, min(prev[1], idx))
-    ordered = sorted(best.items(), key=lambda kv: (-kv[1][0], kv[1][1]))
-    return [text for text, _pri in ordered[:5]]
-
-
-_MEMBER_ONLY_DOT_KEY: dict[str, str] = {
-    "DECLARES_CLIENT": "DECLARES.DECLARES_CLIENT",
-    "DECLARES_PRODUCER": "DECLARES.DECLARES_PRODUCER",
-    "EXPOSES": "DECLARES.EXPOSES",
-}
-
-_CALLS_HIGH_FANOUT_THRESHOLD = 10
-_EDGE_DECLARES_CLIENT = frozenset({"DECLARES_CLIENT", "DECLARES.DECLARES_CLIENT"})
-_EDGE_DECLARES_PRODUCER = frozenset({"DECLARES_PRODUCER", "DECLARES.DECLARES_PRODUCER"})
-
-
-
-
-
-
-def _extract_other_ids(results: list[dict[str, Any]]) -> list[str]:
-    ids: list[str] = []
-    for r in results:
-        other = r.get("other")
-        if isinstance(other, dict):
-            oid = other.get("id")
-            if isinstance(oid, str) and oid:
-                ids.append(oid)
-    return ids
-
-
-# --- Labels for structured hints (semantic name of each hint) ---
-
-LABEL_CLIENTS_VIA_MEMBERS = "clients via members"
-LABEL_ROUTES_VIA_MEMBERS = "routes via members"
-LABEL_PRODUCERS_VIA_MEMBERS = "producers via members"
-LABEL_OVERRIDERS = "overriders"
-LABEL_CLIENTS_IN_OVERRIDERS = "clients in overriders"
-LABEL_PRODUCERS_IN_OVERRIDERS = "producers in overriders"
-LABEL_ROUTES_IN_OVERRIDERS = "routes in overriders"
-LABEL_OUTBOUND_CLIENT = "outbound client"
-LABEL_OUTBOUND_PRODUCER = "outbound producer"
-LABEL_INBOUND_ROUTE = "inbound route"
-LABEL_HIGH_FANOUT = "high fanout"
-LABEL_DECLARING_METHOD = "declaring method"
-LABEL_IMPLEMENTORS = "implementors"
-LABEL_IMPLEMENTS = "implements"
-LABEL_DEPENDENCIES = "dependencies"
-LABEL_INJECTORS = "injectors"
-LABEL_OUTBOUND_CALLS = "outbound calls"
-LABEL_SUPER_DECLARATION = "super declaration"
-LABEL_UNRESOLVED = "unresolved"
-LABEL_TRY_RESOLVE = "try resolve"
-LABEL_PAGE_FULL = "page full"
-LABEL_HANDLER = "handler"
-LABEL_HTTP_TARGETS = "HTTP targets"
-LABEL_ASYNC_TARGETS = "async targets"
-LABEL_WEAK_RESULTS = "weak results"
-LABEL_TRY_SEARCH = "try search"
-LABEL_TRY_FIND_ROUTE = "try find route"
-LABEL_TRY_FIND_CLIENT = "try find client"
-LABEL_TIGHTEN_IDENTIFIER = "tighten identifier"
-LABEL_FUZZY_STRATEGY = "fuzzy strategy"
-LABEL_CALLERS = "callers"
-LABEL_WRONG_SUBJECT_KIND = "wrong subject kind"
-LABEL_WRONG_DIRECTION = "wrong direction"
-LABEL_TYPE_LEVEL_REQUERY = "type-level requery"
-
-# §7.12 priority: DECLARES.* type rollups > OVERRIDDEN_BY.* > leaf follow-ups > meta.
-PRIORITY_DECLARES_TYPE_ROLLUP = 4
-PRIORITY_OVERRIDDEN_AXIS = 3
-PRIORITY_LEAF_FOLLOWUP = 2
-PRIORITY_META = 1
-
-_TYPE_SYMBOL_KINDS = frozenset({"class", "interface", "enum", "record", "annotation"})
-_METHOD_SYMBOL_KINDS = frozenset({"method", "constructor"})
-
-_COMPOSED_DOT_KEY_PREFIXES = ("DECLARES.", "OVERRIDDEN_BY.")
-# Row 4 (brownfield absence): only when the subject is a resolver endpoint node, not a
-# structurally valid Symbol query that happens to be empty (DECLARES_CLIENT, EXPOSES, …).
-_BROWNFIELD_ABSENCE_SUBJECT_LABELS = frozenset({"Client", "Producer", "Route"})
-_REQUIRED_TRAVERSAL_ROLE_KEYS = frozenset({"type_subject", "member_subject", "alien_subject"})
-
-_IDENTIFIER_FILTER_FIELDS: dict[str, tuple[str, ...]] = {
-    "symbol": ("fqn_contains",),
-    "route": ("path_contains",),
-    "client": ("target_service", "target_path_contains"),
-}
-
-
-def _out_count(edge_summary: dict[str, Any] | None, key: str) -> int:
-    if not edge_summary or key not in edge_summary:
-        return 0
-    cell = edge_summary[key]
-    if not isinstance(cell, dict):
-        return 0
-    return int(cell.get("out", 0) or 0)
-
-
-def _in_count(edge_summary: dict[str, Any] | None, key: str) -> int:
-    if not edge_summary or key not in edge_summary:
-        return 0
-    cell = edge_summary[key]
-    if not isinstance(cell, dict):
-        return 0
-    return int(cell.get("in", 0) or 0)
-
-
-def _record_role(rec: dict[str, Any]) -> str:
-    return str((rec.get("data") or {}).get("role") or rec.get("role") or "")
-
-
-def _type_rollup_would_emit(edge_summary: dict[str, Any] | None) -> bool:
-    return (
-        _out_count(edge_summary, "DECLARES.DECLARES_CLIENT") > 0
-        or _out_count(edge_summary, "DECLARES.EXPOSES") > 0
-        or _out_count(edge_summary, "DECLARES.DECLARES_PRODUCER") > 0
-    )
-
-
-def _symbol_declaration_kind(record: dict[str, Any]) -> str | None:
-    data = record.get("data")
-    if isinstance(data, dict):
-        k = data.get("kind")
-        if k is not None:
-            return str(k).strip() or None
-    return None
-
-
-def _subject_node_label(subject_record: dict[str, Any]) -> str:
-    if "producer_kind" in subject_record:
-        return "Producer"
-    if "client_kind" in subject_record:
-        return "Client"
-    if "framework" in subject_record:
-        return "Route"
-    return "Symbol"
-
-
-def _traversal_role_for_wrong_kind(subject_label: str, subject_record: dict[str, Any]) -> str:
-    if subject_label == "Symbol":
-        sk = str(subject_record.get("kind") or "")
-        if sk in _METHOD_SYMBOL_KINDS:
-            return "member_subject"
-        if sk in _TYPE_SYMBOL_KINDS:
-            return "alien_subject"
-    return "alien_subject"
-
-
-def typical_traversal_for(
-    edge: str,
-    role_key: str,
-    *,
-    subject_id: str,
-    direction: str,
-) -> str:
-    template = EDGE_SCHEMA[edge].typical_traversals[role_key]
-    return template.format(id=subject_id, direction=direction, edge=edge)
-
-
-
-
-
-
-def _neighbors_success_subject_is_type(subject_record: dict[str, Any]) -> bool:
-    return (
-        _subject_node_label(subject_record) == "Symbol"
-        and str(subject_record.get("kind") or "") in _TYPE_SYMBOL_KINDS
-    )
-
-
-def _neighbors_results_homogeneous(
-    results: list[dict[str, Any]],
-    *,
-    endpoint_kind: str | None = None,
-    symbol_kinds: frozenset[str] | None = None,
-) -> bool:
-    if not results:
-        return False
-    for row in results:
-        other = row.get("other")
-        if not isinstance(other, dict):
-            return False
-        ok = str(other.get("kind") or "")
-        if endpoint_kind is not None and ok != endpoint_kind:
-            return False
-        if symbol_kinds is not None:
-            if ok != "symbol":
-                return False
-            if str(other.get("symbol_kind") or "") not in symbol_kinds:
-                return False
-    return True
-
-
-
-
-
-
-
-
-
-
-def _any_fuzzy_strategy(edges: list[dict[str, Any]]) -> bool:
-    for e in edges:
-        attrs = e.get("attrs") if isinstance(e.get("attrs"), dict) else {}
-        s = attrs.get("strategy") if isinstance(attrs, dict) else None
-        if isinstance(s, str) and s in FUZZY_STRATEGY_SET:
-            return True
-    return False
-
-
-def _find_has_identifier_shaped_filter(kind: str, flt: dict[str, Any]) -> bool:
-    for name in _IDENTIFIER_FILTER_FIELDS.get(kind, ()):
-        val = flt.get(name)
-        if val is None:
-            continue
-        if isinstance(val, str) and val.strip():
-            return True
-        if not isinstance(val, str):
-            return True
-    return False
-
-
-
-
-def _neighbors_empty_structured_hints(
-    *,
-    subject_record: dict[str, Any],
-    requested_edge_types: list[str],
-    requested_direction: Literal["in", "out"],
-) -> list[_StructuredHint]:
-    """Structured counterparts to neighbors empty results (Rows 1–3)."""
-    out: list[_StructuredHint] = []
-    subject_label = _subject_node_label(subject_record)
-    subject_id = str(subject_record.get("id") or "")
-
-    for edge in requested_edge_types:
-        spec = EDGE_SCHEMA.get(edge)
-        if spec is None:
-            continue
-
-        # Row 1: wrong subject kind
-        if subject_label != spec.src and subject_label != spec.dst:
-            role = _traversal_role_for_wrong_kind(subject_label, subject_record)
-            if role != "alien_subject":
-                template = spec.typical_traversals.get(role, "")
-                # Parse template like "neighbors(['{id}'],'out',['DECLARES_CLIENT'])"
-                # Intentionally removed regex fallback — the schema-controlled format
-                # is stable; silence on format mismatch is acceptable for this low-risk
-                # requery hint (main users are search→neighbors divergences, not edge types).
-                parts = template.split("'")
-                if len(parts) >= 6:
-                    direction = parts[3]
-                    edge_type = parts[5].replace("']", "").replace("['", "")
-                    out.append(_StructuredHint(
-                        "neighbors",
-                        {"ids": [subject_id], "direction": direction, "edge_types": [edge_type]},
-                        False,
-                        PRIORITY_META,
-                        LABEL_WRONG_SUBJECT_KIND,
-                        f"'{edge}' connects {spec.src} → {spec.dst}; this is a {subject_label}.",
-                    ))
-            continue
-
-        # Row 2: wrong direction
-        wrong_direction = spec.src != spec.dst and (
-            (requested_direction == "out" and subject_label == spec.dst)
-            or (requested_direction == "in" and subject_label == spec.src)
-        )
-        if wrong_direction:
-            correct_dir = "in" if requested_direction == "out" else "out"
-            out.append(_StructuredHint(
-                "neighbors",
-                {"ids": [subject_id], "direction": correct_dir, "edge_types": [edge]},
-                False,
-                PRIORITY_META,
-                LABEL_WRONG_DIRECTION,
-                f"'{edge}' is {spec.src} → {spec.dst}; you requested direction='{requested_direction}'.",
-            ))
-            continue
-
-        # Row 3: type-level requery
-        if (
-            subject_label == "Symbol"
-            and str(subject_record.get("kind") or "") in _TYPE_SYMBOL_KINDS
-            and spec.member_only
-        ):
-            dot_key = _MEMBER_ONLY_DOT_KEY.get(edge)
-            if dot_key:
-                out.append(_StructuredHint(
-                    "neighbors",
-                    {"ids": [subject_id], "direction": requested_direction, "edge_types": [dot_key]},
-                    False,
-                    PRIORITY_META,
-                    LABEL_TYPE_LEVEL_REQUERY,
-                    f"'{edge}' lives on methods, not on {subject_label}.",
-                ))
-    return out
-
-
-def _neighbors_success_structured_hints(payload: dict[str, Any]) -> list[_StructuredHint]:
-    """Structured counterparts to ``neighbors_success_hints`` (N1a–N7)."""
-    if not payload.get("success"):
-        return []
-    results = list(payload.get("results") or [])
-    if not results or int(payload.get("offset") or 0) != 0:
-        return []
-    req_types = payload.get("requested_edge_types")
-    if not isinstance(req_types, list) or len(req_types) != 1:
-        return []
-    edge = str(req_types[0]).strip()
-    if not edge:
-        return []
-    direction = payload.get("requested_direction")
-    if direction not in ("in", "out"):
-        return []
-
-    out: list[_StructuredHint] = []
-    origin_id = str(payload.get("origin_id") or "")
-    if not origin_id:
-        origin_id = str(results[0].get("origin_id") or "")
-    subject_record = payload.get("subject_record")
-    is_type_subject = (
-        isinstance(subject_record, dict) and _neighbors_success_subject_is_type(subject_record)
-    )
-
-    # N1a/N1b: DECLARES out from type → dot-key clients/routes
-    if (
-        edge == "DECLARES"
-        and direction == "out"
-        and is_type_subject
-        and _neighbors_results_homogeneous(results, symbol_kinds=_METHOD_SYMBOL_KINDS)
-    ):
-        if origin_id:
-            out.append(_StructuredHint(
-                "neighbors",
-                {"ids": [origin_id], "direction": "out", "edge_types": ["DECLARES.DECLARES_CLIENT"]},
-                True,
-                PRIORITY_LEAF_FOLLOWUP,
-                LABEL_CLIENTS_VIA_MEMBERS,
-                "type has members with DECLARES_CLIENT edges",
-            ))
-            out.append(_StructuredHint(
-                "neighbors",
-                {"ids": [origin_id], "direction": "out", "edge_types": ["DECLARES.EXPOSES"]},
-                True,
-                PRIORITY_LEAF_FOLLOWUP,
-                LABEL_ROUTES_VIA_MEMBERS,
-                "type has members with EXPOSES edges",
-            ))
-
-    # N2: DECLARES_CLIENT / DECLARES.DECLARES_CLIENT out → HTTP_CALLS
-    if edge in _EDGE_DECLARES_CLIENT and direction == "out":
-        if _neighbors_results_homogeneous(results, endpoint_kind="client"):
-            other_ids = _extract_other_ids(results)
-            out.append(_StructuredHint(
-                "neighbors",
-                {"ids": other_ids, "direction": "out", "edge_types": ["HTTP_CALLS"]},
-                bool(other_ids),
-                PRIORITY_LEAF_FOLLOWUP,
-                LABEL_HTTP_TARGETS,
-                "clients have outbound HTTP_CALLS edges",
-            ))
-
-    # N3: DECLARES_PRODUCER / DECLARES.DECLARES_PRODUCER out → ASYNC_CALLS
-    if edge in _EDGE_DECLARES_PRODUCER and direction == "out":
-        if _neighbors_results_homogeneous(results, endpoint_kind="producer"):
-            other_ids = _extract_other_ids(results)
-            out.append(_StructuredHint(
-                "neighbors",
-                {"ids": other_ids, "direction": "out", "edge_types": ["ASYNC_CALLS"]},
-                bool(other_ids),
-                PRIORITY_LEAF_FOLLOWUP,
-                LABEL_ASYNC_TARGETS,
-                "producers have outbound ASYNC_CALLS edges",
-            ))
-
-    # N4: EXPOSES in → CALLS (callers)
-    if (
-        edge == "EXPOSES"
-        and direction == "in"
-        and _neighbors_results_homogeneous(results, symbol_kinds=_METHOD_SYMBOL_KINDS)
-    ):
-        other_ids = _extract_other_ids(results)
-        out.append(_StructuredHint(
-            "neighbors",
-            {"ids": other_ids, "direction": "in", "edge_types": ["CALLS"]},
-            bool(other_ids),
-            PRIORITY_LEAF_FOLLOWUP,
-            LABEL_CALLERS,
-            "handler methods may have inbound CALLS edges",
-        ))
-
-    # N5: HTTP_CALLS in → DECLARES_CLIENT
-    if edge == "HTTP_CALLS" and direction == "in":
-        if _neighbors_results_homogeneous(results, endpoint_kind="client"):
-            other_ids = _extract_other_ids(results)
-            out.append(_StructuredHint(
-                "neighbors",
-                {"ids": other_ids, "direction": "in", "edge_types": ["DECLARES_CLIENT"]},
-                bool(other_ids),
-                PRIORITY_LEAF_FOLLOWUP,
-                LABEL_DECLARING_METHOD,
-                "clients are declared on methods",
-            ))
-
-    # N6: ASYNC_CALLS in → DECLARES_PRODUCER
-    if edge == "ASYNC_CALLS" and direction == "in":
-        if _neighbors_results_homogeneous(results, endpoint_kind="producer"):
-            other_ids = _extract_other_ids(results)
-            out.append(_StructuredHint(
-                "neighbors",
-                {"ids": other_ids, "direction": "in", "edge_types": ["DECLARES_PRODUCER"]},
-                bool(other_ids),
-                PRIORITY_LEAF_FOLLOWUP,
-                LABEL_DECLARING_METHOD,
-                "producers are declared on methods",
-            ))
-
-    # N7: DECLARES.EXPOSES out → EXPOSES (handler)
-    if edge == "DECLARES.EXPOSES" and direction == "out":
-        if _neighbors_results_homogeneous(results, endpoint_kind="route"):
-            other_ids = _extract_other_ids(results)
-            out.append(_StructuredHint(
-                "neighbors",
-                {"ids": other_ids, "direction": "in", "edge_types": ["EXPOSES"]},
-                bool(other_ids),
-                PRIORITY_LEAF_FOLLOWUP,
-                LABEL_HANDLER,
-                "routes expose handler methods",
-            ))
-
-    return out
-
-
-def generate_hints(
-    output_kind: Literal["search", "find", "describe", "neighbors", "resolve"],
-    payload: dict[str, Any],
-) -> tuple[list[_StructuredHint], list[str]]:
-    """Return structured hints and advisories for a success-only MCP v2 payload dict.
-
-    Returns (structured_hints, advisories) where structured_hints are machine-parseable
-    next-action objects and advisories are pure informational strings.
-    """
-    struct_pairs: list[_StructuredHint] = []
-    advisories: list[tuple[int, str]] = []
-
-    if output_kind == "resolve":
-        if payload.get("success") is False:
-            return ([], [])
-        status = str(payload.get("status") or "")
-        if status == "one":
-            return ([], [])
-        if status == "many":
-            n = len(payload.get("candidates") or [])
-            if n > 1:
-                advisories.append((PRIORITY_META, f"{n} candidates — tighten identifier or pick a candidate by id"))
-                struct_pairs.append(_StructuredHint(
-                    "resolve",
-                    {"identifier": str(payload.get("resolved_identifier") or ""), "hint_kind": str(payload.get("hint_kind") or "")},
-                    False, PRIORITY_META,
-                    LABEL_TIGHTEN_IDENTIFIER,
-                    "multiple matches found for identifier",
-                ))
-            return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-        if status == "none":
-            identifier = payload.get("resolved_identifier")
-            hint_kind = payload.get("hint_kind")
-            if not isinstance(identifier, str) or not identifier.strip():
-                return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-            if any(w in identifier for w in ("*", "?")):
-                return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-            if hint_kind == "route":
-                seed = payload.get("path_prefix_seed")
-                if isinstance(seed, str) and seed.strip():
-                    advisories.append((PRIORITY_META, f"no match — try find(kind='route', filter={{path_contains: '{seed}'}})"))
-                    struct_pairs.append(_StructuredHint(
-                        "find", {"kind": "route", "filter": {"path_contains": seed}}, True, PRIORITY_META,
-                        LABEL_TRY_FIND_ROUTE,
-                        "no route found for path seed",
-                    ))
-            elif hint_kind == "client":
-                seed = payload.get("target_service_seed")
-                if isinstance(seed, str) and seed.strip():
-                    advisories.append((PRIORITY_META, f"no match — try find(kind='client', filter={{target_service: '{seed}'}})"))
-                    struct_pairs.append(_StructuredHint(
-                        "find", {"kind": "client", "filter": {"target_service": seed}}, True, PRIORITY_META,
-                        LABEL_TRY_FIND_CLIENT,
-                        "no client found for target service seed",
-                    ))
-            else:
-                advisories.append((PRIORITY_META, f"no match — try search(query='{identifier}') for ranked fuzzy lookup"))
-                struct_pairs.append(_StructuredHint(
-                    "search", {"query": identifier}, True, PRIORITY_META,
-                    LABEL_TRY_SEARCH,
-                    "no exact match found for identifier",
-                ))
-            return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-        return ([], [])
-
-    if not payload.get("success"):
-        return ([], [])
-
-    if output_kind == "search":
-        results: list[dict[str, Any]] = list(payload.get("results") or [])
-        lim = payload.get("limit")
-        if lim is not None and len(results) == int(lim) and results:
-            scores = [float(r.get("score", 0.0) or 0.0) for r in results]
-            mx = max(scores)
-            mn = min(scores)
-            if mx > 0.0 and (mx - mn) < 0.1 * mx:
-                advisories.append((PRIORITY_META, "results look weak — narrow the query or try find(role=…)"))
-                struct_pairs.append(_StructuredHint(
-                    "find", {"kind": "symbol", "filter": {"role": "SERVICE"}}, False, PRIORITY_META,
-                    LABEL_WEAK_RESULTS,
-                    "search results have low score variance",
-                ))
-        return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-
-    if output_kind == "find":
-        kind = str(payload.get("kind") or "")
-        results = list(payload.get("results") or [])
-        flt = payload.get("filter") if isinstance(payload.get("filter"), dict) else {}
-        lim = payload.get("limit")
-        if not results and _find_has_identifier_shaped_filter(kind, flt):
-            advisories.append((PRIORITY_META, f"no matches — try resolve(identifier, hint_kind='{kind}') for canonical lookup"))
-            identifier = ""
-            for fname in _IDENTIFIER_FILTER_FIELDS.get(kind, ()):
-                val = flt.get(fname)
-                if isinstance(val, str) and val.strip():
-                    identifier = val.strip()
-                    break
-            struct_pairs.append(_StructuredHint(
-                "resolve", {"identifier": identifier, "hint_kind": kind}, True, PRIORITY_META,
-                LABEL_TRY_RESOLVE,
-                f"no {kind} found with filter",
-            ))
-        if lim is not None and len(results) >= int(lim) and payload.get("has_more_results") is True:
-            advisories.append((PRIORITY_META, f"result page full at {lim} — narrow filter or paginate"))
-            struct_pairs.append(_StructuredHint(
-                "find", {"kind": kind, "filter": flt, "limit": int(lim)}, False, PRIORITY_META,
-                LABEL_PAGE_FULL,
-                f"result page full at {lim}",
-            ))
-        if results and (lim is None or len(results) < int(lim)):
-            node_id = str(results[0].get("id") or "")
-            if node_id:
-                if kind == "route":
-                    struct_pairs.append(_StructuredHint(
-                        "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["EXPOSES"]},
-                        True, PRIORITY_LEAF_FOLLOWUP,
-                        LABEL_HANDLER,
-                        "route exposes handler method",
-                    ))
-                elif kind == "client":
-                    struct_pairs.append(_StructuredHint(
-                        "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["HTTP_CALLS"]},
-                        True, PRIORITY_LEAF_FOLLOWUP,
-                        LABEL_HTTP_TARGETS,
-                        "client has outbound HTTP_CALLS edges",
-                    ))
-                elif kind == "producer":
-                    struct_pairs.append(_StructuredHint(
-                        "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["ASYNC_CALLS"]},
-                        True, PRIORITY_LEAF_FOLLOWUP,
-                        LABEL_ASYNC_TARGETS,
-                        "producer has outbound ASYNC_CALLS edges",
-                    ))
-        return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-
-    if output_kind == "neighbors":
-        results = list(payload.get("results") or [])
-        req_types = payload.get("requested_edge_types")
-        if not isinstance(req_types, list):
-            req_types = []
-        edge_labels = [str(x).strip() for x in req_types if str(x).strip()]
-        offset = int(payload.get("offset") or 0)
-        subject_record = payload.get("subject_record")
-        requested_direction = payload.get("requested_direction")
-        struct_empty: list[_StructuredHint] = []
-        struct_success: list[_StructuredHint] = []
-        struct_meta: list[_StructuredHint] = []
-        if not results and edge_labels and offset == 0:
-            if (
-                isinstance(subject_record, dict)
-                and subject_record
-                and requested_direction in ("in", "out")
-            ):
-                struct_empty.extend(
-                    _neighbors_empty_structured_hints(
-                        subject_record=subject_record,
-                        requested_edge_types=edge_labels,
-                        requested_direction=requested_direction,
-                    )
-                )
-                # Brownfield absence advisory (Row 4)
-                subject_label = _subject_node_label(subject_record)
-                if subject_label in _BROWNFIELD_ABSENCE_SUBJECT_LABELS:
-                    for edge in edge_labels:
-                        spec = EDGE_SCHEMA.get(edge)
-                        if spec is not None and spec.brownfield_resolver_sourced:
-                            advisories.append((PRIORITY_META, f"edges on '{edge}' are emitted by the brownfield resolver — absence here may mean unresolved (no matching annotation/target), not absent from the codebase"))
-                            break
-        elif results and offset == 0:
-            struct_success.extend(_neighbors_success_structured_hints(payload))
-        # CALLS-specific meta hints
-        if isinstance(req_types, list) and req_types == ["CALLS"]:
-            if not payload.get("edge_filter_provided") and not payload.get("include_unresolved"):
-                calls_n = int(payload.get("calls_row_count") or 0) or len(results)
-                if calls_n >= _CALLS_HIGH_FANOUT_THRESHOLD:
-                    origin_id = str(payload.get("origin_id") or "")
-                    if origin_id:
-                        struct_meta.append(_StructuredHint(
-                            "neighbors",
-                            {"ids": [origin_id], "direction": "out", "edge_types": ["CALLS"], "edge_filter": {}},
-                            False, PRIORITY_LEAF_FOLLOWUP,
-                            LABEL_HIGH_FANOUT,
-                            f"{calls_n} CALLS — noisy axes are callee_declaring_role and per-call-site multiplicity",
-                        ))
-            # Unresolved sites advisory
-            unresolved = int(payload.get("unresolved_count") or 0)
-            if unresolved > 0:
-                page_n = len(results)
-                # Advisory shortened to stay under 200 char cap (test_advisories_char_cap)
-                advisories.append((PRIORITY_LEAF_FOLLOWUP, f"{page_n} CALLS shown; {unresolved} unresolved — see describe().unresolved_call_sites or neighbors(include_unresolved=True)"))
-            # Fuzzy strategy advisory
-            if results and _any_fuzzy_strategy(results):
-                advisories.append((PRIORITY_META, "some edges resolved via brownfield/fallback strategy — check attrs.strategy on each row"))
-            # Role-filter OTHER fallback advisory
-            edge_flt = payload.get("edge_filter") if isinstance(payload.get("edge_filter"), dict) else {}
-            role_exact = edge_flt.get("callee_declaring_role")
-            if (
-                role_exact in ("SERVICE", "REPOSITORY")
-                and not results
-                and int(payload.get("unfiltered_calls_count") or 0) >= 5
-            ):
-                advisories.append((PRIORITY_META, "0 CALLS matched callee_declaring_role filter but method has many callees — targets may be OTHER (interface/JDK); try edge_filter={{exclude_callee_declaring_roles: ['ENTITY','DTO']}} instead of role exact match"))
-            # NodeFilter.role collision advisory
-            node_flt = payload.get("node_filter") if isinstance(payload.get("node_filter"), dict) else {}
-            node_role = node_flt.get("role")
-            if node_role and results:
-                method_rows = [
-                    r
-                    for r in results
-                    if str(((r.get("other") or {}) if isinstance(r.get("other"), dict) else {}).get("symbol_kind") or "")
-                    == "method"
-                ]
-                if method_rows:
-                    other_roles = [
-                        str(
-                            ((r.get("other") or {}) if isinstance(r.get("other"), dict) else {}).get("role")
-                            or ""
-                        )
-                        for r in method_rows
-                    ]
-                    if other_roles and sum(1 for role in other_roles if role == "OTHER") >= max(
-                        1, (len(other_roles) * 3) // 4
-                    ):
-                        advisories.append((PRIORITY_META, "NodeFilter.role filters the neighbor method's role (usually OTHER), not the callee's declaring type — use edge_filter={{callee_declaring_role: 'SERVICE'}} (or REPOSITORY) for CALLS stereotype projection"))
-        return (finalize_structured_hints(struct_empty + struct_success + struct_meta), finalize_advisories(advisories))
-
-    if output_kind == "describe":
-        rec = payload.get("record")
-        if not isinstance(rec, dict):
-            return ([], [])
-        node_id = str(rec.get("id") or "")
-        if not node_id:
-            return ([], [])
-        kind = str(rec.get("kind") or "")
-        es = rec.get("edge_summary")
-        edge_summary = es if isinstance(es, dict) else None
-
-        if kind == "route":
-            struct_pairs.append(_StructuredHint(
-                "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["EXPOSES"]},
-                True, PRIORITY_LEAF_FOLLOWUP,
-                LABEL_DECLARING_METHOD,
-                "route exposes handler method",
-            ))
-            return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-        if kind == "client":
-            struct_pairs.append(_StructuredHint(
-                "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["DECLARES_CLIENT"]},
-                True, PRIORITY_LEAF_FOLLOWUP,
-                LABEL_DECLARING_METHOD,
-                "client is declared on a method",
-            ))
-            if _out_count(edge_summary, "HTTP_CALLS") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["HTTP_CALLS"]},
-                    True, PRIORITY_LEAF_FOLLOWUP,
-                    LABEL_HTTP_TARGETS,
-                    "client has outbound HTTP_CALLS edges",
-                ))
-            return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-        if kind == "producer":
-            struct_pairs.append(_StructuredHint(
-                "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["DECLARES_PRODUCER"]},
-                True, PRIORITY_LEAF_FOLLOWUP,
-                LABEL_DECLARING_METHOD,
-                "producer is declared on a method",
-            ))
-            if _out_count(edge_summary, "ASYNC_CALLS") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["ASYNC_CALLS"]},
-                    True, PRIORITY_LEAF_FOLLOWUP,
-                    LABEL_ASYNC_TARGETS,
-                    "producer has outbound ASYNC_CALLS edges",
-                ))
-            return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-
-        if kind != "symbol":
-            return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-
-        decl_kind = _symbol_declaration_kind(rec)
-        is_type = decl_kind in _TYPE_SYMBOL_KINDS
-        is_method = decl_kind in _METHOD_SYMBOL_KINDS
-
-        if is_type:
-            if _out_count(edge_summary, "DECLARES.DECLARES_CLIENT") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES.DECLARES_CLIENT"]},
-                    True, PRIORITY_DECLARES_TYPE_ROLLUP,
-                    LABEL_CLIENTS_VIA_MEMBERS,
-                    "type has members with DECLARES_CLIENT edges",
-                ))
-            if _out_count(edge_summary, "DECLARES.EXPOSES") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES.EXPOSES"]},
-                    True, PRIORITY_DECLARES_TYPE_ROLLUP,
-                    LABEL_ROUTES_VIA_MEMBERS,
-                    "type has members with EXPOSES edges",
-                ))
-            if _out_count(edge_summary, "DECLARES.DECLARES_PRODUCER") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES.DECLARES_PRODUCER"]},
-                    True, PRIORITY_DECLARES_TYPE_ROLLUP,
-                    LABEL_PRODUCERS_VIA_MEMBERS,
-                    "type has members with DECLARES_PRODUCER edges",
-                ))
-
-            if not _type_rollup_would_emit(edge_summary):
-                if decl_kind == "interface" and _in_count(edge_summary, "IMPLEMENTS") > 0:
-                    struct_pairs.append(_StructuredHint(
-                        "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["IMPLEMENTS"]},
-                        True, PRIORITY_LEAF_FOLLOWUP,
-                        LABEL_IMPLEMENTORS,
-                        "interface is implemented by other types",
-                    ))
-                if decl_kind == "class" and _out_count(edge_summary, "IMPLEMENTS") > 0:
-                    struct_pairs.append(_StructuredHint(
-                        "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["IMPLEMENTS"]},
-                        True, PRIORITY_LEAF_FOLLOWUP,
-                        LABEL_IMPLEMENTS,
-                        "class implements other types",
-                    ))
-                if decl_kind == "class" and _record_role(rec) == "SERVICE" and _out_count(edge_summary, "INJECTS") > 0:
-                    struct_pairs.append(_StructuredHint(
-                        "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["INJECTS"]},
-                        True, PRIORITY_LEAF_FOLLOWUP,
-                        LABEL_DEPENDENCIES,
-                        "SERVICE injects other types",
-                    ))
-                if decl_kind in {"interface", "class"} and _in_count(edge_summary, "INJECTS") > 0:
-                    struct_pairs.append(_StructuredHint(
-                        "neighbors", {"ids": [node_id], "direction": "in", "edge_types": ["INJECTS"]},
-                        True, PRIORITY_LEAF_FOLLOWUP,
-                        LABEL_INJECTORS,
-                        "type is injected by other types",
-                    ))
-
-            return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-
-        if is_method:
-            if _out_count(edge_summary, "OVERRIDDEN_BY") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDDEN_BY"]},
-                    True, PRIORITY_OVERRIDDEN_AXIS,
-                    LABEL_OVERRIDERS,
-                    "method is overridden by other methods",
-                ))
-            if _out_count(edge_summary, "OVERRIDDEN_BY.DECLARES_CLIENT") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDDEN_BY.DECLARES_CLIENT"]},
-                    True, PRIORITY_OVERRIDDEN_AXIS,
-                    LABEL_CLIENTS_IN_OVERRIDERS,
-                    "overriding methods have DECLARES_CLIENT edges",
-                ))
-            if _out_count(edge_summary, "OVERRIDDEN_BY.DECLARES_PRODUCER") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDDEN_BY.DECLARES_PRODUCER"]},
-                    True, PRIORITY_OVERRIDDEN_AXIS,
-                    LABEL_PRODUCERS_IN_OVERRIDERS,
-                    "overriding methods have DECLARES_PRODUCER edges",
-                ))
-            if _out_count(edge_summary, "OVERRIDDEN_BY.EXPOSES") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDDEN_BY.EXPOSES"]},
-                    True, PRIORITY_OVERRIDDEN_AXIS,
-                    LABEL_ROUTES_IN_OVERRIDERS,
-                    "overriding methods have EXPOSES edges",
-                ))
-            if _out_count(edge_summary, "DECLARES_CLIENT") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES_CLIENT"]},
-                    True, PRIORITY_LEAF_FOLLOWUP,
-                    LABEL_OUTBOUND_CLIENT,
-                    "method declares outbound HTTP client",
-                ))
-            if _out_count(edge_summary, "DECLARES_PRODUCER") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["DECLARES_PRODUCER"]},
-                    True, PRIORITY_LEAF_FOLLOWUP,
-                    LABEL_OUTBOUND_PRODUCER,
-                    "method declares outbound async producer",
-                ))
-            if _out_count(edge_summary, "EXPOSES") > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["EXPOSES"]},
-                    True, PRIORITY_LEAF_FOLLOWUP,
-                    LABEL_INBOUND_ROUTE,
-                    "method is exposed as a route handler",
-                ))
-            calls_out = _out_count(edge_summary, "CALLS")
-            if 1 <= calls_out <= 9:
-                method_role = _record_role(rec)
-                if method_role != "OTHER" or calls_out >= 3:
-                    struct_pairs.append(_StructuredHint(
-                        "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["CALLS"]},
-                        True, PRIORITY_LEAF_FOLLOWUP,
-                        LABEL_OUTBOUND_CALLS,
-                        "method has outbound CALLS edges",
-                    ))
-            if _out_count(edge_summary, "OVERRIDES") > 0:
-                if _out_count(edge_summary, "OVERRIDDEN_BY") == 0:
-                    struct_pairs.append(_StructuredHint(
-                        "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["OVERRIDES"]},
-                        True, PRIORITY_LEAF_FOLLOWUP,
-                        LABEL_SUPER_DECLARATION,
-                        "method overrides a super declaration",
-                    ))
-            data = rec.get("data")
-            unresolved = 0
-            if isinstance(data, dict):
-                unresolved = int(data.get("unresolved_call_sites_total") or 0)
-            if unresolved > 0:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["CALLS"], "include_unresolved": True},
-                    True, PRIORITY_LEAF_FOLLOWUP,
-                    LABEL_UNRESOLVED,
-                    f"method has {unresolved} unresolved call sites",
-                ))
-            if _out_count(edge_summary, "CALLS") >= 10:
-                struct_pairs.append(_StructuredHint(
-                    "neighbors", {"ids": [node_id], "direction": "out", "edge_types": ["CALLS"]},
-                    False, PRIORITY_LEAF_FOLLOWUP,
-                    LABEL_HIGH_FANOUT,
-                    f"method has {_out_count(edge_summary, 'CALLS')} CALLS — consider filtering",
-                ))
-                # Advisory for many CALLS
-                advisories.append((PRIORITY_LEAF_FOLLOWUP, "many CALLS — consider filtering by target microservice"))
-            return (finalize_structured_hints(struct_pairs), finalize_advisories(advisories))
-
-        return ([], [])