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

resolve_service.py

@@ -0,0 +1,649 @@
+"""Resolve service for mapping identifiers to graph nodes.
+
+Transport-agnostic resolve pipeline extracted from mcp_v2.py for reuse
+by the CLI layer. Provides resolve_v2(identifier, hint_kind, graph) -> ResolveOutput.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from graph_types import (
+    NodeRef,
+    StructuredHint,
+    _hints_or_skip,
+    _node_ref_from_row,
+    _to_structured_hints,
+    set_hints_enabled,
+)
+from java_ontology import ResolveReason
+from ladybug_queries import LadybugGraph
+from mcp_hints import MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION
+
+__all__ = [
+    "resolve_v2",
+    "ResolveOutput",
+    "ResolveCandidate",
+    "ResolveStatus",
+    "set_hints_enabled",
+]
+
+
+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,
+    "client_fqn": 2,
+    "short_name": 3,
+    "client_target": 3,
+    "client_name": 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
+
+
+def _scope_clause(
+    alias: str,
+    microservice: str = "",
+    module: str = "",
+) -> tuple[str, dict[str, str]]:
+    """Build a Cypher AND-clause scoping a node alias by microservice/module.
+
+    Returns ``(clause, params)`` where ``clause`` is ``""`` or
+    ``" AND <alias>.microservice = $ms AND <alias>.module = $mod"`` and
+    ``params`` carries only the bound scope values. Used by the candidate
+    matchers to push ``--service``/``--module`` down into resolve so they act
+    as resolve-time filters (not just traversal post-filters).
+    """
+    preds: list[str] = []
+    params: dict[str, str] = {}
+    if microservice:
+        preds.append(f"{alias}.microservice = $ms")
+        params["ms"] = microservice
+    if module:
+        preds.append(f"{alias}.module = $mod")
+        params["mod"] = module
+    clause = (" AND " + " AND ".join(preds)) if preds else ""
+    return clause, params
+
+
+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 _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,
+    *,
+    microservice: str = "",
+    module: str = "",
+) -> list[tuple[NodeRef, ResolveReason, int]]:
+    out: list[tuple[NodeRef, ResolveReason, int]] = []
+    lim = _RESOLVE_PRE_DEDUP_LIMIT
+    scope, scope_params = _scope_clause("s", microservice, module)
+
+    rows = g._rows(  # noqa: SLF001
+        f"MATCH (s:Symbol) WHERE s.id = $id{scope} RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
+        {"id": identifier, "lim": lim, **scope_params},
+    )
+    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{scope} RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
+        {"fqn": identifier, "lim": lim, **scope_params},
+    )
+    for row in rows:
+        out.append((_node_ref_from_row("symbol", row), "exact_fqn", len(identifier)))
+
+    # Method FQN without arg signature (e.g. "pkg.Cls#method"): the stored method
+    # fqn is "pkg.Cls#method(Type,Type)", so an argless identifier misses the
+    # exact match above. Prefix-match on "<identifier>(" so the agent doesn't
+    # have to type the exact "(Type,Type)" signature. Multiple overloads → the
+    # resolve "many" path surfaces them honestly as ambiguous candidates.
+    if "#" in identifier and "(" not in identifier:
+        rows = g._rows(  # noqa: SLF001
+            f"MATCH (s:Symbol) WHERE s.fqn STARTS WITH $mp{scope} "
+            f"RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
+            {"mp": identifier + "(", "lim": lim, **scope_params},
+        )
+        for row in rows:
+            out.append((_node_ref_from_row("symbol", row), "fqn_suffix", len(identifier) + 1))
+        # Short "Cls#method" form (no package): the identifier is "<Class>#<method>"
+        # with no dot in the class part. Match symbols whose fqn contains
+        # "<Class>#<method>(" so overloads surface honestly as ambiguous.
+        if "." not in identifier.split("#", 1)[0]:
+            class_part, _, method_part = identifier.partition("#")
+            if class_part and method_part:
+                contains = f".{class_part}#{method_part}("
+                rows = g._rows(  # noqa: SLF001
+                    f"MATCH (s:Symbol) WHERE s.fqn CONTAINS $mp{scope} "
+                    f"RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
+                    {"mp": contains, "lim": lim, **scope_params},
+                )
+                for row in rows:
+                    fqn = str(row.get("fqn") or "")
+                    out.append(
+                        (_node_ref_from_row("symbol", row), "fqn_suffix", len(identifier) + 1)
+                    )
+
+    suffix = f".{identifier}"
+    rows = g._rows(  # noqa: SLF001
+        f"MATCH (s:Symbol) WHERE s.fqn = $ident OR s.fqn ENDS WITH $suffix{scope} "
+        f"RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
+        {"ident": identifier, "suffix": suffix, "lim": lim, **scope_params},
+    )
+    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{scope} RETURN {_SYMBOL_RESOLVE_RETURN} LIMIT $lim",
+        {"name": identifier, "lim": lim, **scope_params},
+    )
+    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,
+    *,
+    microservice: str = "",
+    module: str = "",
+) -> list[tuple[NodeRef, ResolveReason, int]]:
+    out: list[tuple[NodeRef, ResolveReason, int]] = []
+    lim = _RESOLVE_PRE_DEDUP_LIMIT
+    scope, scope_params = _scope_clause("r", microservice, module)
+
+    rows = g._rows(  # noqa: SLF001
+        f"MATCH (r:Route) WHERE r.id = $id{scope} RETURN {_ROUTE_RESOLVE_RETURN} LIMIT $lim",
+        {"id": identifier, "lim": lim, **scope_params},
+    )
+    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_ms, 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){scope} "
+            f"RETURN {_ROUTE_RESOLVE_RETURN} LIMIT $lim",
+            {"ms": microservice_ms, "method": method, "path": path, "lim": lim, **scope_params},
+        )
+        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){scope} "
+            f"RETURN {_ROUTE_RESOLVE_RETURN} LIMIT $lim",
+            {"method": method, "path": path, "lim": lim, **scope_params},
+        )
+        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{scope} "
+            f"RETURN {_ROUTE_RESOLVE_RETURN} LIMIT $lim",
+            {"path": identifier, "lim": lim, **scope_params},
+        )
+        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 _drop_route_mirrors(g, out)
+
+
+def _drop_route_mirrors(
+    g: LadybugGraph,
+    cands: list[tuple[NodeRef, ResolveReason, int]],
+) -> list[tuple[NodeRef, ResolveReason, int]]:
+    """Drop client-side Route mirrors that collide with a server-exposed route.
+
+    A path can resolve to TWO Route nodes: the server route (exposed by a
+    controller via an inbound ``EXPOSES`` edge, ``microservice`` set) and a
+    client-side mirror (no ``EXPOSES``, often ``microservice=''``) created when
+    a Client's HTTP call couldn't be linked to the server route. The mirror is
+    an artifact — drop it when a server-exposed route shares the same
+    ``(method, path_template)`` so the no-flags ``jrag callers '/path'`` flow
+    resolves to the single server route instead of stalling on "ambiguous".
+    GENUINE ambiguity (two server-exposed routes in different microservices
+    sharing a path) is preserved — both have ``EXPOSES`` and survive.
+    """
+    if len(cands) < 2:
+        return cands
+    ids = [c[0].id for c in cands if c[0].id]
+    if not ids:
+        return cands
+    id_list = ", ".join("'" + cid.replace("'", "''") + "'" for cid in ids)
+    exposed_rows = g._rows(  # noqa: SLF001
+        "MATCH (s:Symbol)-[:EXPOSES]->(r:Route) "
+        f"WHERE r.id IN [{id_list}] "
+        "RETURN r.id AS rid",
+        {},
+    )
+    exposed_ids = {str(r.get("rid") or "") for r in exposed_rows}
+    if not exposed_ids:
+        return cands
+
+    # Group candidates by their route fqn ("METHOD path"); within a colliding
+    # group, drop non-exposed (mirror) entries only when an exposed entry exists.
+    groups: dict[str, list[tuple[NodeRef, ResolveReason, int]]] = {}
+    for node, reason, spec in cands:
+        groups.setdefault(str(node.fqn or ""), []).append((node, reason, spec))
+
+    keep: list[tuple[NodeRef, ResolveReason, int]] = []
+    for group in groups.values():
+        has_exposed = any(c[0].id in exposed_ids for c in group)
+        for node, reason, spec in group:
+            if has_exposed and node.id not in exposed_ids:
+                continue  # mirror colliding with a server route — drop
+            keep.append((node, reason, spec))
+    return keep
+
+
+def _resolve_client_candidates(
+    g: LadybugGraph,
+    identifier: str,
+    *,
+    microservice: str = "",
+    module: str = "",
+) -> list[tuple[NodeRef, ResolveReason, int]]:
+    out: list[tuple[NodeRef, ResolveReason, int]] = []
+    lim = _RESOLVE_PRE_DEDUP_LIMIT
+    scope, scope_params = _scope_clause("c", microservice, module)
+
+    rows = g._rows(  # noqa: SLF001
+        f"MATCH (c:Client) WHERE c.id = $id{scope} RETURN {_CLIENT_RESOLVE_RETURN} LIMIT $lim",
+        {"id": identifier, "lim": lim, **scope_params},
+    )
+    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){scope} "
+                f"RETURN {_CLIENT_RESOLVE_RETURN} LIMIT $lim",
+                {"target": target, "path": path_prefix, "lim": lim, **scope_params},
+            )
+            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{scope} "
+            f"RETURN {_CLIENT_RESOLVE_RETURN} LIMIT $lim",
+            {"target": identifier, "lim": lim, **scope_params},
+        )
+        for row in rows:
+            out.append((_node_ref_from_row("client", row), "client_target", len(identifier)))
+
+    # Client-by-name/FQN: reach a Client root via its declaring Symbol (the
+    # method that declares the client). Only SUFFIX/NAME matches are used — a
+    # full method FQN identifier (e.g. 'pkg.Cls#method(Arg)') is intentionally
+    # left to resolve to the method Symbol (exact_fqn) rather than ALSO matching
+    # the Client declared by that same method, which would surface a spurious
+    # "ambiguous" result. A bare class name (no '#') does not suffix-match a
+    # Client's member_fqn (which carries '#method(args)'), so it resolves to the
+    # type Symbol; a bare method name ('joinOperator') matches Client(s) via the
+    # declaring symbol name and surfaces honest ambiguity across clients.
+    if " " not in identifier and not identifier.startswith("/"):
+        sym_scope, sym_scope_params = _scope_clause("s", microservice, module)
+        # Declaring symbol name match (e.g. 'joinOperator').
+        rows = g._rows(  # noqa: SLF001
+            "MATCH (s:Symbol)-[:DECLARES_CLIENT]->(c:Client) "
+            f"WHERE s.name = $name{sym_scope} "
+            f"RETURN {_CLIENT_RESOLVE_RETURN} LIMIT $lim",
+            {"name": identifier, "lim": lim, **sym_scope_params},
+        )
+        for row in rows:
+            out.append((_node_ref_from_row("client", row), "client_name", len(identifier)))
+        # Declaring symbol FQN / member_fqn SUFFIX match (safe: a full method
+        # FQN with args never suffix-matches because stored fqns carry the arg
+        # suffix; '.<identifier>' only matches a class-level identifier).
+        suffix = "." + identifier
+        rows = g._rows(  # noqa: SLF001
+            "MATCH (s:Symbol)-[:DECLARES_CLIENT]->(c:Client) "
+            f"WHERE s.fqn ENDS WITH $suffix OR c.member_fqn ENDS WITH $suffix{sym_scope} "
+            f"RETURN {_CLIENT_RESOLVE_RETURN} LIMIT $lim",
+            {"suffix": suffix, "lim": lim, **sym_scope_params},
+        )
+        for row in rows:
+            fqn = str(row.get("member_fqn") or "")
+            out.append((_node_ref_from_row("client", row), "client_fqn", len(fqn) or len(identifier)))
+
+    return out
+
+
+def _resolve_producer_candidates(
+    g: LadybugGraph,
+    identifier: str,
+    *,
+    microservice: str = "",
+    module: str = "",
+) -> list[tuple[NodeRef, ResolveReason, int]]:
+    out: list[tuple[NodeRef, ResolveReason, int]] = []
+    lim = _RESOLVE_PRE_DEDUP_LIMIT
+    scope, scope_params = _scope_clause("p", microservice, module)
+
+    rows = g._rows(  # noqa: SLF001
+        f"MATCH (p:Producer) WHERE p.id = $id{scope} RETURN {_PRODUCER_RESOLVE_RETURN} LIMIT $lim",
+        {"id": identifier, "lim": lim, **scope_params},
+    )
+    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{scope} RETURN {_PRODUCER_RESOLVE_RETURN} LIMIT $lim",
+        {"topic": identifier, "lim": lim, **scope_params},
+    )
+    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{scope} "
+            f"RETURN {_PRODUCER_RESOLVE_RETURN} LIMIT $lim",
+            {"topic": identifier, "lim": lim, **scope_params},
+        )
+        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,
+    *,
+    microservice: str = "",
+    module: str = "",
+) -> 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:
+            out = ResolveOutput(
+                success=False,
+                status="none",
+                message=(
+                    "Wildcards (* and ?) are not supported in resolve; "
+                    "use search(query=...) for ranked text search."
+                ),
+                advisories=[],
+                resolved_identifier=trimmed,
+            )
+            _resolve_assert_invariants(out)
+            return out
+
+        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, microservice=microservice, module=module))
+            elif kind == "route":
+                raw.extend(_resolve_route_candidates(g, trimmed, microservice=microservice, module=module))
+            elif kind == "client":
+                raw.extend(_resolve_client_candidates(g, trimmed, microservice=microservice, module=module))
+            else:
+                raw.extend(_resolve_producer_candidates(g, trimmed, microservice=microservice, module=module))
+
+        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

search_lancedb.py

@@ -534,6 +534,15 @@ def _search_one_table(
     for r in rows:
         r["_kind"] = kind
         r["_hybrid"] = False
+        # Populate `_score` from `_distance` so the SearchHit.score reflects
+        # relevance. The hybrid branch sets `_score` from `_relevance_score`
+        # above; without this, non-hybrid (default) search left `_score` unset
+        # and mcp_v2._row_to_search_hit fell back to 0.0 for EVERY hit —
+        # ranking still worked (the sort key uses `_distance` directly) but the
+        # exposed score was always 0.0, making results look unranked.
+        d = r.get("_distance")
+        if d is not None:
+            r["_score"] = l2_distance_to_score(float(d))
         r["start"] = coerce_position_field(r.get("start"))
         r["end"] = coerce_position_field(r.get("end"))
     return rows
@@ -853,7 +862,7 @@ def run_search(
         capability=capability, capability_in=capability_in,
     ) if "java" in table_keys else []
 
-    skip_role_weight = bool(role or role_in)
+    skip_role_weight = bool(role or role_in or exclude_roles)
     query_toks = _query_tokens(query)
 
     if len(table_keys) == 1: