java-codebase-rag 0.9.4__py3-none-any.whl → 0.9.5__py3-none-any.whl

mcp_v2.py

@@ -31,6 +31,9 @@ if TYPE_CHECKING:
     # installs ship without torch/lancedb); it is imported lazily in _get_sentence_transformer.
     from sentence_transformers import SentenceTransformer
 
+from absence_types import AbsenceDiagnosis
+from absence_diagnosis import diagnose
+from absence_vocab import get_vocabulary_index
 from graph_types import (
     NodeRef,
     StructuredHint,
@@ -74,6 +77,7 @@ __all__ = [
     "EdgeFilter",
     "StructuredHint",
     "set_hints_enabled",
+    "set_absence_config",
 ]
 
 DeclarationSymbolKind = Literal["class", "interface", "enum", "record", "annotation", "method", "constructor"]
@@ -147,6 +151,35 @@ _METHOD_SYMBOL_KINDS_FOR_OVERRIDE_ROLLUP = frozenset({"method"})
 _fail_loud_counts: dict[str, int] = {}
 _fail_loud_lock = threading.Lock()
 
+# Module-level holder for absence diagnosis config (set by server.py)
+_absence_config: Any = None
+
+
+def set_absence_config(cfg: Any) -> None:
+    """Set the global absence diagnosis config for MCP tools.
+
+    Mirrors set_hints_enabled: called from server.py to make cfg reachable
+    in tool functions without threading it through every signature.
+    """
+    global _absence_config
+    _absence_config = cfg
+
+
+def _get_absence_config() -> Any:
+    """Get the absence diagnosis config, with safe fallback.
+
+    Returns the module-level config if set; otherwise falls back to a
+    default config (for direct tool calls in tests without server init).
+    """
+    if _absence_config is not None:
+        return _absence_config
+
+    # Fallback: resolve from cwd for direct test calls
+    from java_codebase_rag.config import resolve_operator_config
+    from pathlib import Path
+
+    return resolve_operator_config(source_root=Path.cwd())
+
 
 def _log_fail_loud(category: str) -> None:
     """Increment process-local fail-loud counter and emit one stderr line (PR-FRAME-3).
@@ -191,6 +224,8 @@ class NodeFilter(BaseModel):
     source_layer: SourceLayer | None = None
     role: Role | None = None
     exclude_roles: list[Role] | None = None
+    generated_only: bool = False
+    exclude_generated: bool = False
     annotation: str | None = None
     capability: str | None = None
     fqn_contains: str | None = None
@@ -273,6 +308,8 @@ _NODEFILTER_APPLICABLE_FIELDS: dict[Literal["symbol", "route", "client", "produc
         "module",
         "role",
         "exclude_roles",
+        "generated_only",
+        "exclude_generated",
         "annotation",
         "capability",
         "fqn_contains",
@@ -317,6 +354,9 @@ def _populated_nodefilter_fields(nf: NodeFilter) -> set[str]:
             continue
         if isinstance(value, list) and not value:
             continue
+        if isinstance(value, bool) and not value:
+            # default-False NodeFilter fields (generated_only, exclude_generated) must not count as "populated"
+            continue
         populated.add(field_name)
     return populated
 
@@ -364,6 +404,8 @@ def _populated_edgefilter_fields(ef: EdgeFilter) -> set[str]:
             continue
         if isinstance(value, list) and not value:
             continue
+        if isinstance(value, bool) and not value:
+            continue
         populated.add(field_name)
     return populated
 
@@ -464,6 +506,8 @@ class SearchHit(BaseModel):
     microservice: str | None = None
     module: str | None = None
     role: str | None = None
+    generated: bool | None = None
+    generated_by: str | None = None
     filename: str | None = None
     start_line: int | None = None
     score_components: dict[str, float] | None = None
@@ -520,6 +564,11 @@ class SearchOutput(BaseModel):
     )
     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)
+    lexical_mode: bool = Field(
+        default=False,
+        description="True when results come from the graph-only lexical (keyword) backend instead of semantic/vector search.",
+    )
+    absence: AbsenceDiagnosis | None = None
 
 
 class FindOutput(BaseModel):
@@ -541,6 +590,7 @@ class FindOutput(BaseModel):
     )
     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)
+    absence: AbsenceDiagnosis | None = None
 
 
 class DescribeOutput(BaseModel):
@@ -549,6 +599,7 @@ class DescribeOutput(BaseModel):
     message: 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)
+    absence: AbsenceDiagnosis | None = None
 
 
 class NeighborsOutput(BaseModel):
@@ -567,6 +618,7 @@ class NeighborsOutput(BaseModel):
     )
     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)
+    absence: AbsenceDiagnosis | None = None
 
 
 # Re-exported from resolve_service.py (imported at end of module to avoid circular import)
@@ -608,6 +660,8 @@ def _row_to_search_hit(row: dict[str, Any], explain: bool = False) -> 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,
+        generated=bool(row.get("generated")) if row.get("generated") is not None else None,
+        generated_by=str(row.get("generated_by")) if row.get("generated_by") else None,
         filename=filename,
         start_line=start_line,
         score_components=row.get("_score_components") if explain else None,
@@ -649,6 +703,10 @@ def _symbol_where_from_filter(f: NodeFilter) -> tuple[str, dict[str, Any]]:
     if f.exclude_roles:
         preds.append("NOT s.role IN $exclude_roles")
         params["exclude_roles"] = list(f.exclude_roles)
+    if f.generated_only:
+        preds.append("s.generated = true")
+    if f.exclude_generated:
+        preds.append("(s.generated IS NULL OR s.generated = false)")
     if f.annotation:
         preds.append("list_contains(s.annotations, $annotation)")
         params["annotation"] = f.annotation
@@ -681,7 +739,7 @@ def _load_node_record(
             "n.start_line AS start_line, n.end_line AS end_line, n.start_byte AS start_byte, "
             "n.end_byte AS end_byte, n.modifiers AS modifiers, n.annotations AS annotations, "
             "n.capabilities AS capabilities, n.role AS role, n.signature AS signature, "
-            "n.parent_id AS parent_id, n.resolved AS resolved"
+            "n.parent_id AS parent_id, n.resolved AS resolved, n.generated AS generated, n.generated_by AS generated_by"
         )
         label = "Symbol"
     elif kind == "route":
@@ -778,6 +836,11 @@ def _node_matches_filter(
             return False
         if f.exclude_roles and role in set(f.exclude_roles):
             return False
+        generated = row.get("generated")
+        if f.generated_only and not generated:
+            return False
+        if f.exclude_generated and generated:
+            return False
         if f.annotation and f.annotation not in list(row.get("annotations") or []):
             return False
         if f.capability and f.capability not in list(row.get("capabilities") or []):
@@ -850,97 +913,135 @@ 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 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,
-            )
-        # hybrid + table='all' is unsupported (hybrid fuses vector+FTS on ONE
-        # table); fail fast with a clean envelope BEFORE loading the embedding
-        # model. run_search also guards this — this is the user-facing fast path.
-        if hybrid and table == "all":
-            return SearchOutput(
-                success=False,
-                message="hybrid search requires a single table; use java, sql, or yaml (not all)",
-                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)
-        uri = os.environ.get("JAVA_CODEBASE_RAG_INDEX_DIR", "").strip() or str(
-            (Path.cwd() / ".java-codebase-rag").resolve()
-        )
-        uri_path = Path(uri)
-        if not uri.startswith(("s3://", "gs://", "az://")) and uri_path.exists():
-            uri = str(uri_path.resolve())
-        table_keys = list(TABLES) if table == "all" else [table]
-
-        # Graceful fallback: if hybrid=True and FTS index is missing (old index),
-        # retry with hybrid=False and return vector-only results with an advisory.
         advisories: list[str] = []
-        try:
-            rows = run_search(
+        lexical_mode = run_search is None
+        if lexical_mode:
+            # Graph-only install (macOS Intel: no torch/lancedb). Fall back to lexical
+            # (keyword) search over the symbol graph that graph-only mode already builds.
+            # run_lexical_search returns rows in the same shape as run_search, so the
+            # shared row->hit loop below works unchanged. It raises (message contains
+            # "lexical search unavailable") when no graph exists — caught by the outer
+            # try -> success=False. It returns [] for sql/yaml (advisory below) and for
+            # empty-but-valid results.
+            try:
+                from search_lexical import run_lexical_search
+            except ImportError:  # pragma: no cover - search_lexical has no heavy deps
+                run_lexical_search = None  # type: ignore[assignment]
+            if run_lexical_search is None:
+                return SearchOutput(
+                    success=False,
+                    message="search unavailable: graph-only mode and lexical backend not importable.",
+                    advisories=[],
+                    limit=None,
+                    offset=None,
+                )
+            advisories.append(
+                "lexical (graph-only) mode — keyword ranking only; "
+                "semantic/vector search requires Apple Silicon, Linux, or Windows"
+            )
+            if table in ("sql", "yaml", "all"):
+                advisories.append(
+                    "sql/yaml tables are not indexed in graph-only mode; only Java symbols were searched"
+                )
+            if hybrid:
+                advisories.append("hybrid is ignored in graph-only lexical mode")
+            rows = run_lexical_search(
                 query,
-                uri=uri,
-                table_keys=table_keys,
-                hybrid=hybrid,
+                table=table,
                 limit=limit,
                 offset=offset,
-                path_substring=path_contains,
-                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,
-                dedup_by_fqn=dedup,
+                path_contains=path_contains,
+                filter=nf,
+                explain=explain,
+                dedup=dedup,
+                advisories=advisories,
+                graph=graph,
+            )
+        else:
+            # hybrid + table='all' is unsupported (hybrid fuses vector+FTS on ONE
+            # table); fail fast with a clean envelope BEFORE loading the embedding
+            # model. run_search also guards this — this is the user-facing fast path.
+            if hybrid and table == "all":
+                return SearchOutput(
+                    success=False,
+                    message="hybrid search requires a single table; use java, sql, or yaml (not all)",
+                    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)
+            uri = os.environ.get("JAVA_CODEBASE_RAG_INDEX_DIR", "").strip() or str(
+                (Path.cwd() / ".java-codebase-rag").resolve()
             )
-        except Exception as exc:
-            # Check if this is a missing-FTS error (old index built before PR-SEARCH-3)
-            exc_text = str(exc).lower()
-            is_fts_missing = "full text search" in exc_text or "inverted index" in exc_text
-            if hybrid and is_fts_missing:
-                # Retry with vector-only search
+            uri_path = Path(uri)
+            if not uri.startswith(("s3://", "gs://", "az://")) and uri_path.exists():
+                uri = str(uri_path.resolve())
+            table_keys = list(TABLES) if table == "all" else [table]
+
+            # Graceful fallback: if hybrid=True and FTS index is missing (old index),
+            # retry with hybrid=False and return vector-only results with an advisory.
+            try:
                 rows = run_search(
                     query,
                     uri=uri,
                     table_keys=table_keys,
-                    hybrid=False,  # Fallback to vector-only
+                    hybrid=hybrid,
                     limit=limit,
                     offset=offset,
                     path_substring=path_contains,
                     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,
+                    exclude_generated=nf.exclude_generated if nf else None,
+                    generated_only=nf.generated_only if nf else None,
                     dedup_by_fqn=dedup,
                 )
-                advisories.append(
-                    f"hybrid unavailable on table '{table}' (FTS index missing on this index built before "
-                    f"PR-SEARCH-3); fell back to vector-only — reindex to enable hybrid"
-                )
-            else:
-                # Non-FTS error: surface as structured failure
-                raise
+            except Exception as exc:
+                # Check if this is a missing-FTS error (old index built before PR-SEARCH-3)
+                exc_text = str(exc).lower()
+                is_fts_missing = "full text search" in exc_text or "inverted index" in exc_text
+                if hybrid and is_fts_missing:
+                    # Retry with vector-only search
+                    rows = run_search(
+                        query,
+                        uri=uri,
+                        table_keys=table_keys,
+                        hybrid=False,  # Fallback to vector-only
+                        limit=limit,
+                        offset=offset,
+                        path_substring=path_contains,
+                        model_name=model_name,
+                        device=device,
+                        model=model,
+                        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,
+                        exclude_generated=nf.exclude_generated if nf else None,
+                        generated_only=nf.generated_only if nf else None,
+                        dedup_by_fqn=dedup,
+                    )
+                    advisories.append(
+                        f"hybrid unavailable on table '{table}' (FTS index missing on this index built before "
+                        f"PR-SEARCH-3); fell back to vector-only — reindex to enable hybrid"
+                    )
+                else:
+                    # Non-FTS error: surface as structured failure
+                    raise
         hits: list[SearchHit] = []
         for row in rows:
             if path_contains and path_contains not in str(row.get("filename") or ""):
@@ -950,6 +1051,25 @@ def search_v2(
                 if not _node_matches_filter(row_kind, row, nf):
                     continue
             hits.append(_row_to_search_hit(row, explain=explain))
+
+        # Absence diagnosis for empty results
+        cfg = _get_absence_config()
+        diag: AbsenceDiagnosis | None = None
+        if not hits:
+            g = graph or LadybugGraph.get()
+            vocab = get_vocabulary_index(g, cfg)
+            diag = diagnose(
+                tool="search",
+                query=query,
+                filt=None,
+                filter_kind=None,
+                root_node=None,
+                scope={},
+                vocab=vocab,
+                graph=g,
+                cfg=cfg,
+            )
+
         hint_payload = {
             "success": True,
             "results": [h.model_dump() for h in hits],
@@ -964,6 +1084,8 @@ def search_v2(
             offset=offset,
             advisories=advisories + raw_advisories,  # Merge fallback + hints advisories
             hints_structured=_to_structured_hints(raw_struct),
+            lexical_mode=lexical_mode,
+            absence=diag,
         )
     except Exception as exc:
         return SearchOutput(success=False, message=str(exc), advisories=[], limit=None, offset=None)
@@ -1001,7 +1123,7 @@ def find_v2(
             params["lim"] = fetch_cap
             rows = g._rows(  # noqa: SLF001
                 f"MATCH (s:Symbol) {where} 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 ORDER BY s.fqn LIMIT $lim",
+                "s.module AS module, s.role AS role, s.kind AS symbol_kind, s.generated AS generated, s.generated_by AS generated_by ORDER BY s.fqn LIMIT $lim",
                 params,
             )
         elif kind == "route":
@@ -1035,6 +1157,24 @@ def find_v2(
         rows = rows[offset : offset + limit]
         refs = [_node_ref_from_row(kind, r) for r in rows]
         filter_dump = nf.model_dump(exclude_none=True)
+
+        # Absence diagnosis for empty results
+        cfg = _get_absence_config()
+        diag: AbsenceDiagnosis | None = None
+        if not refs:
+            vocab = get_vocabulary_index(g, cfg)
+            diag = diagnose(
+                tool="find",
+                query=None,
+                filt=filter_dump,
+                filter_kind=kind,
+                root_node=None,
+                scope={},
+                vocab=vocab,
+                graph=g,
+                cfg=cfg,
+            )
+
         hint_payload: dict[str, Any] = {
             "success": True,
             "kind": kind,
@@ -1058,6 +1198,7 @@ def find_v2(
             has_more_results=has_more_results,
             advisories=raw_advisories,
             hints_structured=_to_structured_hints(raw_struct),
+            absence=diag,
         )
     except Exception as exc:
         return FindOutput(success=False, message=str(exc), advisories=[], limit=None, offset=None)
@@ -1094,7 +1235,25 @@ def describe_v2(
                 {"fqn": fqn_val},
             )
             if not rows:
-                return DescribeOutput(success=False, message=f"No Symbol found for fqn='{fqn_val}'")
+                # FQN not found: run diagnosis with query=fqn
+                cfg = _get_absence_config()
+                vocab = get_vocabulary_index(g, cfg)
+                diag = diagnose(
+                    tool="describe",
+                    query=fqn_val,
+                    filt=None,
+                    filter_kind=None,
+                    root_node=None,
+                    scope={},
+                    vocab=vocab,
+                    graph=g,
+                    cfg=cfg,
+                )
+                return DescribeOutput(
+                    success=False,
+                    message=f"No Symbol found for fqn='{fqn_val}'",
+                    absence=diag,
+                )
             node_id = str(rows[0]["id"] or "")
             if len(rows) > 1:
                 hint_message = (
@@ -1107,7 +1266,26 @@ def describe_v2(
             return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE, advisories=[])
         row = _load_node_record(g, node_id, kind)
         if row is None:
-            return DescribeOutput(success=False, message=f"No node found for `{node_id}`", advisories=[])
+            # Node ID not found: run diagnosis with query=None (minimal refine)
+            cfg = _get_absence_config()
+            vocab = get_vocabulary_index(g, cfg)
+            diag = diagnose(
+                tool="describe",
+                query=None,
+                filt=None,
+                filter_kind=None,
+                root_node=None,
+                scope={},
+                vocab=vocab,
+                graph=g,
+                cfg=cfg,
+            )
+            return DescribeOutput(
+                success=False,
+                message=f"No node found for `{node_id}`",
+                advisories=[],
+                absence=diag,
+            )
         ref = _node_ref_from_row(kind, row)
         edge_summary = _edge_summary_for_node(g, node_id, kind=kind, row=row)
         data = dict(row)
@@ -1618,6 +1796,26 @@ def neighbors_v2(
         first_origin = origins[0]
         origin_kind = _resolve_node_kind(g, first_origin)
         subject_record = _load_node_record(g, first_origin, origin_kind)
+
+        # Absence diagnosis for empty results
+        cfg = _get_absence_config()
+        diag: AbsenceDiagnosis | None = None
+        if not sliced:
+            # Build root_node from first_origin + subject_record
+            root_node = _node_ref_from_row(origin_kind, subject_record) if subject_record else None
+            vocab = get_vocabulary_index(g, cfg)
+            diag = diagnose(
+                tool="neighbors",
+                query=None,
+                filt=None,
+                filter_kind=None,
+                root_node=root_node,
+                scope={},
+                vocab=vocab,
+                graph=g,
+                cfg=cfg,
+            )
+
         neigh_payload = {
             "success": True,
             "results": [e.model_dump(exclude_none=True) for e in sliced],
@@ -1643,6 +1841,7 @@ def neighbors_v2(
             has_more_results=neighbors_has_more,
             advisories=raw_advisories,
             hints_structured=_to_structured_hints(raw_struct),
+            absence=diag,
         )
     except ValidationError:
         raise

resolve_service.py

@@ -6,10 +6,13 @@ by the CLI layer. Provides resolve_v2(identifier, hint_kind, graph) -> ResolveOu
 
 from __future__ import annotations
 
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from absence_types import AbsenceDiagnosis
+from absence_diagnosis import diagnose
+from absence_vocab import get_vocabulary_index
 from graph_types import (
     NodeRef,
     StructuredHint,
@@ -28,6 +31,7 @@ __all__ = [
     "ResolveCandidate",
     "ResolveStatus",
     "set_hints_enabled",
+    "set_absence_config",
 ]
 
 
@@ -35,6 +39,35 @@ ResolveStatus = Literal["one", "many", "none"]
 
 _RESOLVE_CANDIDATE_CAP = 10
 
+# Module-level holder for absence diagnosis config (set by server.py)
+_absence_config: Any = None
+
+
+def set_absence_config(cfg: Any) -> None:
+    """Set the global absence diagnosis config for resolve service.
+
+    Mirrors set_hints_enabled: called from server.py to make cfg reachable
+    in resolve functions without threading it through every signature.
+    """
+    global _absence_config
+    _absence_config = cfg
+
+
+def _get_absence_config() -> Any:
+    """Get the absence diagnosis config, with safe fallback.
+
+    Returns the module-level config if set; otherwise falls back to a
+    default config (for direct tool calls in tests without server init).
+    """
+    if _absence_config is not None:
+        return _absence_config
+
+    # Fallback: resolve from cwd for direct test calls
+    from java_codebase_rag.config import resolve_operator_config
+    from pathlib import Path
+
+    return resolve_operator_config(source_root=Path.cwd())
+
 _RESOLVE_REASON_PRIORITY: dict[ResolveReason, int] = {
     "exact_id": 0,
     "exact_fqn": 1,
@@ -129,6 +162,7 @@ class ResolveOutput(BaseModel):
     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)
+    absence: AbsenceDiagnosis | None = None
 
 
 def _resolve_validate_identifier(raw: str) -> tuple[str | None, str | None]:
@@ -566,6 +600,9 @@ def _resolve_finalize_success(
     trimmed: str,
     hint_kind: Literal["symbol", "route", "client", "producer"] | None,
     matches: list[ResolveCandidate],
+    graph: LadybugGraph | None = None,
+    microservice: str = "",
+    module: str = "",
 ) -> ResolveOutput:
     if not matches:
         out = ResolveOutput(
@@ -591,6 +628,28 @@ def _resolve_finalize_success(
             resolved_identifier=trimmed,
         )
 
+    # Absence diagnosis for empty results (status="none")
+    cfg = _get_absence_config()
+    diag: AbsenceDiagnosis | None = None
+    if not matches:
+        g = graph
+        vocab = get_vocabulary_index(g, cfg)
+        # Map hint_kind to filter_kind (symbol -> "symbol", etc.)
+        filter_kind = hint_kind if hint_kind in ("symbol", "route", "client", "producer") else None
+        # Build scope from microservice/module params
+        scope = {"microservice": microservice or "", "module": module or ""}
+        diag = diagnose(
+            tool="resolve",
+            query=trimmed,
+            filt=None,
+            filter_kind=filter_kind,
+            root_node=None,
+            scope=scope,
+            vocab=vocab,
+            graph=g,
+            cfg=cfg,
+        )
+
     path_prefix_seed, target_service_seed = _resolve_seeds_for_hints(trimmed)
     hint_payload = {
         "status": out.status,
@@ -604,6 +663,7 @@ def _resolve_finalize_success(
     out = out.model_copy(update={
         "advisories": raw_advisories,
         "hints_structured": _to_structured_hints(raw_struct),
+        "absence": diag,
     })
     _resolve_assert_invariants(out)
     return out
@@ -660,7 +720,14 @@ def resolve_v2(
         deduped = _resolve_dedupe_candidates(raw)
         ranked = _resolve_rank_candidates(deduped)
         capped = ranked[:_RESOLVE_CANDIDATE_CAP]
-        return _resolve_finalize_success(trimmed, hint_kind, capped)
+        return _resolve_finalize_success(
+            trimmed,
+            hint_kind,
+            capped,
+            graph=g,
+            microservice=microservice,
+            module=module,
+        )
     except Exception as exc:
         out = ResolveOutput(
             success=False,