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

search_lexical.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""Lexical (keyword) search over the LadybugDB symbol graph.
+
+Graph-only fallback for the `search` tool on macOS Intel installs, where the
+vector stack (lancedb / torch / sentence-transformers) is unavailable (see the
+PEP 508 markers in pyproject.toml). Returns row-dicts in the SAME shape as
+`search_lancedb.run_search`, so `mcp_v2._row_to_search_hit` and the rest of
+`search_v2` work unchanged — `search` simply ranks by keyword relevance instead
+of embeddings, with an advisory noting the mode.
+
+This module imports only LadybugDB (always installed) and `search_scoring`
+(dependency-free). It MUST NOT import lancedb/torch, and it MUST NOT import
+`mcp_v2` (circular: mcp_v2 dispatches to this module). The NodeFilter is
+duck-typed; `_lexical_where` mirrors `mcp_v2._symbol_where_from_filter` and is
+guarded by a parity unit test.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ladybug_queries import LadybugGraph
+from search_scoring import (
+    _ROLE_SCORE_WEIGHTS,
+    _TYPE_MATCH_BONUS_CAP,
+    _TYPE_MATCH_BONUS_PER_HIT,
+    _clamp01,
+    _dedup_by_fqn,
+    _query_tokens,
+    _split_identifier,
+)
+
+if TYPE_CHECKING:
+    from mcp_v2 import NodeFilter
+
+# Lexical relevance weights. The class/file name is the strongest discovery
+# signal (mirrors the type-name bonus rationale in search_scoring); fqn/package
+# overlap is next; signature/annotation/capability text is a weaker corroborator.
+_NAME_MATCH_WEIGHT = 0.45
+_FQN_MATCH_WEIGHT = 0.20
+_TEXT_MATCH_WEIGHT = 0.15
+
+# Display-score normalization denominator. Mirrors search_scoring._HYBRID_SCORE_MAX
+# discipline: sum of each additive component's maximum so the displayed score is
+# rank-monotonic in [0, 1]. (= 0.45 + 0.10 + 0.20 + 0.15 + 0.10 = 1.00)
+LEXICAL_SCORE_MAX = (
+    _NAME_MATCH_WEIGHT
+    + _TYPE_MATCH_BONUS_CAP
+    + _FQN_MATCH_WEIGHT
+    + _TEXT_MATCH_WEIGHT
+    + max(_ROLE_SCORE_WEIGHTS.values())
+)
+
+_SNIPPET_MAX_LINES = 20
+_SNIPPET_MAX_CHARS = 800
+# Safety bound on the candidate fetch (full scan over Symbols; bounded so huge
+# repos don't pull unbounded rows into Python).
+_CANDIDATE_LIMIT_CAP = 5000
+
+_SYMBOL_RETURN = (
+    "s.id AS id, s.kind AS kind, s.name AS name, s.fqn AS fqn, "
+    "s.package AS package, s.module AS module, s.microservice AS microservice, "
+    "s.filename AS filename, s.start_line AS start_line, s.end_line AS end_line, "
+    "s.start_byte AS start_byte, s.end_byte AS end_byte, "
+    "s.annotations AS annotations, s.capabilities AS capabilities, "
+    "s.role AS role, s.signature AS signature, s.parent_id AS parent_id"
+)
+
+
+def _lexical_where(f: Any, *, path_contains: str | None) -> tuple[str, dict[str, Any]]:
+    """Cypher WHERE for Symbol nodes from a NodeFilter (+ path_contains pushdown).
+
+    Mirrors ``mcp_v2._symbol_where_from_filter``; kept local so this module stays
+    import-isolated from mcp_v2 (and unit-testable standalone). ``path_contains``
+    is pushed down into Cypher because ``search_v2`` only re-filters the windowed
+    page post-fetch — without pushdown a path filter could empty the page even
+    when deeper-ranked rows match. A parity unit test guards drift.
+    """
+    preds: list[str] = []
+    params: dict[str, Any] = {}
+    if f is not None:
+        if getattr(f, "microservice", None):
+            preds.append("s.microservice = $microservice")
+            params["microservice"] = f.microservice
+        if getattr(f, "module", None):
+            preds.append("s.module = $module")
+            params["module"] = f.module
+        if getattr(f, "role", None):
+            preds.append("s.role = $role")
+            params["role"] = f.role
+        if getattr(f, "exclude_roles", None):
+            preds.append("NOT s.role IN $exclude_roles")
+            params["exclude_roles"] = list(f.exclude_roles)
+        if getattr(f, "generated_only", False):
+            preds.append("s.generated = true")
+        if getattr(f, "exclude_generated", False):
+            preds.append("(s.generated IS NULL OR s.generated = false)")
+        if getattr(f, "annotation", None):
+            preds.append("list_contains(s.annotations, $annotation)")
+            params["annotation"] = f.annotation
+        if getattr(f, "capability", None):
+            preds.append("$capability IN s.capabilities")
+            params["capability"] = f.capability
+        if getattr(f, "fqn_contains", None):
+            preds.append("s.fqn CONTAINS $fqn_contains")
+            params["fqn_contains"] = f.fqn_contains
+        if getattr(f, "symbol_kind", None):
+            preds.append("s.kind = $symbol_kind")
+            params["symbol_kind"] = f.symbol_kind
+        if getattr(f, "symbol_kinds", None):
+            preds.append("s.kind IN $symbol_kinds")
+            params["symbol_kinds"] = list(f.symbol_kinds)
+    if path_contains:
+        preds.append("s.filename CONTAINS $path_contains")
+        params["path_contains"] = path_contains
+    where = f"WHERE {' AND '.join(preds)}" if preds else ""
+    return where, params
+
+
+def _enclosing_type_fqn(fqn: str) -> str:
+    """Member fqn ``{parent_fqn}#{signature}`` -> parent type fqn; type fqn (no '#') unchanged."""
+    return fqn.split("#", 1)[0] if fqn else fqn
+
+
+def _resolve_source_root(graph: LadybugGraph) -> str:
+    """Authoritative source root is the one cached on the graph at index time."""
+    try:
+        root = str(graph.meta().get("source_root") or "")
+    except Exception:
+        root = ""
+    return root or os.environ.get("JAVA_CODEBASE_RAG_SOURCE_ROOT", "").strip()
+
+
+def _read_snippet(
+    source_root: str, filename: str, start_line: Any, end_line: Any, signature: str, fqn: str
+) -> str:
+    """Real source snippet for [start_line, end_line] from disk (capped); synthesized
+    from `signature` (fallback `fqn`) on any failure."""
+    synth = (signature or "").strip() or fqn
+    try:
+        sl = int(start_line) if start_line else 0
+        el = int(end_line) if end_line else sl
+    except (TypeError, ValueError):
+        return synth
+    if sl <= 0 or not filename:
+        return synth
+    try:
+        p = Path(filename)
+        full = p if p.is_absolute() else (Path(source_root) / filename)
+        if not p.is_absolute() and not source_root:
+            return synth
+        text = full.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return synth
+    lines = text.splitlines()
+    lo = max(sl - 1, 0)
+    hi = min(el if el >= sl else sl, lo + _SNIPPET_MAX_LINES)
+    chunk = "\n".join(lines[lo:hi]).strip()
+    if len(chunk) > _SNIPPET_MAX_CHARS:
+        chunk = chunk[: _SNIPPET_MAX_CHARS - 1] + "…"
+    return chunk or synth
+
+
+def _token_overlap(haystack_toks: set[str], needle_toks: set[str]) -> float:
+    """Fraction of needle tokens present in haystack (0..1)."""
+    if not needle_toks:
+        return 0.0
+    return len(needle_toks & haystack_toks) / len(needle_toks)
+
+
+def run_lexical_search(
+    query: str,
+    *,
+    table: str = "java",
+    limit: int = 5,
+    offset: int = 0,
+    path_contains: str | None = None,
+    filter: NodeFilter | None = None,
+    explain: bool = False,
+    dedup: bool = True,
+    advisories: list[str] | None = None,
+    graph: LadybugGraph | None = None,
+) -> list[dict]:
+    """Keyword search over Symbol nodes; returns ``run_search``-shaped row-dicts.
+
+    Raises ``RuntimeError`` (message contains "lexical search unavailable") if no
+    symbol graph exists — the caller maps that to a clean failure envelope. Returns
+    ``[]`` for ``table in ("sql", "yaml")`` (those LanceDB tables aren't built in
+    graph-only mode) and when the graph exists but nothing matches.
+    """
+    # sql/yaml LanceDB tables don't exist in graph-only mode.
+    if table in ("sql", "yaml"):
+        return []
+
+    if graph is None and not LadybugGraph.exists():
+        raise RuntimeError(
+            "lexical search unavailable: no symbol graph found; "
+            "run `java-codebase-rag init` or `java-codebase-rag reprocess` to build one"
+        )
+    g = graph or LadybugGraph.get()
+
+    where, params = _lexical_where(filter, path_contains=path_contains)
+    # Always exclude structural Symbol nodes. Files and packages are :Symbol-labeled
+    # (kind='file'/'package') but aren't searchable code declarations — without this
+    # a token that appears in a filename (e.g. 'distribution' in
+    # 'DistributionChunkService.java') would surface the file node as a hit.
+    struct_pred = "(s.kind <> 'file' AND s.kind <> 'package')"
+    where = f"WHERE {struct_pred}" if not where else where.replace("WHERE ", f"WHERE {struct_pred} AND ", 1)
+    # Lexical ranking is done in Python (LadybugDB/kuzu has no keyword ranking without
+    # FTS5, which is deferred), and the MATCH scan returns rows in storage order — there
+    # is NO DB-side relevance ORDER BY. So fetch the FULL candidate pool up to the safety
+    # cap and rank here. A pagination-derived LIMIT (4x the page) is correct on the vector
+    # path where LanceDB returns rows pre-ranked by similarity, but on this unordered scan
+    # it would return only the first ~N symbols in arbitrary storage order and silently
+    # miss the best match on any non-trivial repo.
+    params["lim"] = _CANDIDATE_LIMIT_CAP
+    cypher = f"MATCH (s:Symbol) {where} RETURN {_SYMBOL_RETURN} LIMIT $lim"
+    rows = g._rows(cypher, params)  # noqa: SLF001 — de facto public read API (see find_v2)
+    # If the fetch hit the safety cap, deeper matches were never ranked (the scan has no
+    # ORDER BY — kuzu returns an arbitrary, storage-order-dependent subset). Surface it so
+    # a user on a large repo isn't silently shown an incomplete result set; refining the
+    # query or adding a filter narrows the pool below the cap. Raising the cap / FTS5 is
+    # the deferred long-term fix (see the plan's "Out of scope" note).
+    if advisories is not None and len(rows) >= _CANDIDATE_LIMIT_CAP:
+        advisories.append(
+            f"lexical search scanned the first {_CANDIDATE_LIMIT_CAP} matching symbols "
+            "(repo cap); deeper matches were not ranked — refine the query or add a filter"
+        )
+
+    query_toks = _query_tokens(query)
+    source_root = _resolve_source_root(g)
+    role_locked = bool(
+        filter and (getattr(filter, "role", None) or getattr(filter, "exclude_roles", None))
+    )
+
+    out: list[dict] = []
+    for r in rows:
+        name = str(r.get("name") or "")
+        fqn = str(r.get("fqn") or "")
+        type_fqn = _enclosing_type_fqn(fqn)
+        sig = str(r.get("signature") or "")
+        anns = list(r.get("annotations") or [])
+        caps = list(r.get("capabilities") or [])
+        role_raw = str(r.get("role") or "")
+
+        name_toks = set(_split_identifier(name))
+        type_toks = set(_split_identifier(type_fqn.rsplit(".", 1)[-1]))
+        fqn_toks = set(_split_identifier(fqn))
+        sig_toks = _query_tokens(
+            " ".join([sig, " ".join(anns), " ".join(caps), str(r.get("package") or "")])
+        )
+
+        name_overlap = len(query_toks & name_toks)
+        name_match = (
+            1.0
+            if (query_toks and query_toks <= name_toks)
+            else (min(name_overlap / max(len(name_toks), 1), 1.0) if name_toks else 0.0)
+        )
+        type_hits = len(query_toks & type_toks)
+        type_match = min(type_hits * _TYPE_MATCH_BONUS_PER_HIT, _TYPE_MATCH_BONUS_CAP)
+        fqn_match = _token_overlap(fqn_toks, query_toks)
+        text_overlap = _token_overlap(sig_toks, query_toks)
+        text_match = text_overlap * _TEXT_MATCH_WEIGHT
+
+        # A keyword search must require at least one lexical hit — role alone never
+        # qualifies a row (it only boosts/reorders matches). Degenerate queries with
+        # no usable tokens fall through to role-ranked listing.
+        if query_toks and not (name_overlap or type_hits or fqn_match or text_overlap):
+            continue
+
+        role_w = 0.0 if role_locked else _ROLE_SCORE_WEIGHTS.get(role_raw.upper(), 0.0)
+
+        if query_toks:
+            raw = (
+                _NAME_MATCH_WEIGHT * name_match
+                + type_match
+                + _FQN_MATCH_WEIGHT * fqn_match
+                + text_match
+                + role_w
+            )
+        else:
+            raw = role_w  # degenerate query: rank by role only
+        score = _clamp01(raw / LEXICAL_SCORE_MAX)
+
+        comps = {
+            "name_match": round(name_match, 4),
+            "type_match": round(type_match, 4),
+            "fqn_match": round(fqn_match, 4),
+            "lexical_relevance": round(raw, 4),
+            "role_weight": role_w,
+        }
+
+        sl, el, sb, eb = r.get("start_line"), r.get("end_line"), r.get("start_byte"), r.get("end_byte")
+        out.append(
+            {
+                "_score": score,
+                "_kind": "java",
+                "_score_components": comps,
+                "filename": str(r.get("filename") or ""),
+                "text": _read_snippet(source_root, str(r.get("filename") or ""), sl, el, sig, fqn),
+                "primary_type_fqn": type_fqn or None,
+                # Raw node fqn (members are 'Type#method(...)') feeds
+                # _node_matches_filter's fqn_contains re-check (mcp_v2.py). Without it the
+                # post-filter falls back to primary_type_fqn (the bare type) and drops
+                # member-level matches the Cypher pushdown already accepted.
+                "fqn": fqn,
+                "microservice": r.get("microservice"),
+                "module": r.get("module"),
+                "role": role_raw or None,
+                "kind": r.get("kind"),
+                "symbol_id": r.get("id"),
+                "annotations": anns,
+                "capabilities": caps,
+                "start": {
+                    "line": int(sl) if sl is not None else None,
+                    "byte_offset": int(sb) if sb is not None else 0,
+                },
+                "end": {
+                    "line": int(el) if el is not None else None,
+                    "byte_offset": int(eb) if eb is not None else 0,
+                },
+            }
+        )
+
+    out.sort(key=lambda d: float(d.get("_score", 0.0)), reverse=True)
+    out = _dedup_by_fqn(out, dedup_by_fqn=dedup)
+    return out[offset : offset + limit]

search_scoring.py

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""Dependency-free scoring & dedup primitives shared by the search backends.
+
+Imported by both the vector backend (`search_lancedb`) and the lexical backend
+(`search_lexical`). This module MUST NOT import lancedb / torch /
+sentence_transformers / cocoindex — it is imported on graph-only (macOS Intel)
+installs where those packages are absent (see pyproject.toml PEP 508 markers).
+
+Everything here is pure-Python dict/list math with no third-party deps.
+"""
+
+from __future__ import annotations
+
+import json
+
+# Over-fetch multiplier for dedup: fetch 4x to absorb per-FQN chunk multiplicity
+# so that after collapsing by primary_type_fqn, a page stays full and the +1
+# truncation sentinel survives. The formula: need = max((limit + offset) * 4, limit + offset + 1)
+DEDUP_OVERFETCH = 4
+
+_IMPORT_DISTANCE_PENALTY = 0.08
+_IMPORT_HYBRID_SCORE_FACTOR = 0.88
+
+# Bonus for chunks whose declared symbols (method / field names) share tokens with
+# the query. Behavioural queries like "what happens when a client message arrives"
+# should float chunks containing `processClientMessage` above ones that only
+# enqueue; this is a cheap, query-dependent signal computed at rank time.
+_SYMBOL_MATCH_BONUS_PER_HIT = 0.03
+_SYMBOL_MATCH_BONUS_CAP = 0.06
+
+# Action verbs that typically mark behavioural entry points in this codebase.
+# A chunk whose symbols begin with one of these verbs earns a small flat bump
+# — again only for java chunks and only when role-filtering is off.
+_ACTION_VERB_PREFIXES: tuple[str, ...] = (
+    "process", "handle", "on", "pick", "select", "assign",
+    "notify", "dispatch", "publish", "consume", "route",
+    "trigger", "enqueue", "distribute", "update", "create",
+    "apply", "resolve", "reassign", "close", "open",
+)
+_ACTION_VERB_BONUS = 0.02
+
+# Type-name overlap bonus. The class name is a much stronger discovery signal
+# than any individual method, because class naming in this codebase encodes
+# the domain concept (`DistributionChunkService`, `OperatorSessionService`,
+# `JoinOperatorController`). So we reward overlap between query tokens and the
+# simple name of `primary_type_fqn` more heavily than per-method overlap, and
+# we stack it on top of the existing `_symbol_bonus`.
+_TYPE_MATCH_BONUS_PER_HIT = 0.05
+_TYPE_MATCH_BONUS_CAP = 0.10
+
+_STOPWORDS: frozenset[str] = frozenset({
+    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+    "to", "of", "in", "on", "at", "by", "for", "with", "from", "as", "or",
+    "and", "but", "if", "then", "else", "when", "what", "how", "why", "does",
+    "do", "did", "has", "have", "had", "this", "that", "these", "those", "it",
+    "its", "new", "no", "not", "will", "would", "should", "can", "could",
+    "may", "might", "happens", "happen", "happened", "get", "gets", "got",
+})
+
+# Role-aware reweighting for Java chunks. Positive values favour actionable
+# behavioural code (entrypoints, orchestrators, integrations) over configuration,
+# schema, and persistence stubs for "what happens when..."-style queries.
+# Applied to the similarity score (higher = better); distance-based sort subtracts
+# the weight. Skipped when caller filters explicitly by role.
+_ROLE_SCORE_WEIGHTS: dict[str, float] = {
+    "CONTROLLER": 0.10,
+    "SERVICE": 0.08,
+    "CLIENT": 0.06,
+    "COMPONENT": 0.03,
+    "REPOSITORY": 0.02,
+    "MAPPER": 0.00,
+    "OTHER": 0.00,
+    "ENTITY": -0.06,
+    "CONFIG": -0.10,
+    # DTOs are passive data carriers; they almost never answer "how/what
+    # happens" queries. Penalty is slightly stronger than ENTITY so a DTO
+    # with a great embedding match still loses to a mediocre SERVICE hit.
+    "DTO": -0.08,
+}
+
+# Theoretical maximum for hybrid composite score (used for display normalization).
+# Hybrid sort metric: raw_rrf * (import_factor if import_heavy else 1)
+#                   + role_weight + symbol_bonus
+# where raw_rrf ≤ 2/(k+1) for 2-list RRF, role_weight ≤ max(_ROLE_SCORE_WEIGHTS),
+# and symbol_bonus ≤ _SYMBOL_MATCH_BONUS_CAP + _TYPE_MATCH_BONUS_CAP + _ACTION_VERB_BONUS.
+# The import factor is ≤ 1, so we use the raw max (2/61).
+_HYBRID_SCORE_MAX = (2.0 / 61.0) + max(_ROLE_SCORE_WEIGHTS.values()) + _SYMBOL_MATCH_BONUS_CAP + _TYPE_MATCH_BONUS_CAP + _ACTION_VERB_BONUS
+
+
+def _query_tokens(query: str) -> set[str]:
+    """Lowercased alpha-only tokens from the query, minus stopwords, len >= 3.
+
+    Used to score symbol-name overlap; we keep it simple and locale-free.
+    """
+    out: set[str] = set()
+    cur: list[str] = []
+
+    def _flush() -> None:
+        if cur:
+            tok = "".join(cur).lower()
+            cur.clear()
+            if len(tok) >= 3 and tok not in _STOPWORDS:
+                out.add(tok)
+
+    for c in query:
+        if c.isalpha():
+            cur.append(c)
+        else:
+            _flush()
+    _flush()
+    return out
+
+
+def _split_identifier(name: str) -> list[str]:
+    """camelCase / snake_case -> lowercase token list."""
+    parts: list[str] = []
+    cur: list[str] = []
+    for c in name:
+        if c == "_":
+            if cur:
+                parts.append("".join(cur).lower())
+                cur = []
+        elif c.isupper() and cur:
+            parts.append("".join(cur).lower())
+            cur = [c]
+        else:
+            cur.append(c)
+    if cur:
+        parts.append("".join(cur).lower())
+    return [p for p in parts if p]
+
+
+def _symbol_bonus(r: dict, query_toks: set[str]) -> float:
+    """Symbol-name overlap + action-verb bump for java chunks.
+
+    Caps at `_SYMBOL_MATCH_BONUS_CAP + _ACTION_VERB_BONUS` to avoid runaway
+    ranks on chunks declaring many symbols.
+    """
+    if str(r.get("_kind", "")) != "java":
+        return 0.0
+    raw = r.get("symbols") or []
+    if isinstance(raw, str):
+        # Legacy JSON-encoded list column; parse defensively.
+        try:
+            parsed = json.loads(raw)
+            raw = parsed if isinstance(parsed, list) else []
+        except Exception:
+            raw = []
+    symbols = [str(s) for s in raw if s]
+
+    overlap_hits = 0
+    has_action = False
+    for s in symbols:
+        bare = s.split("(", 1)[0].strip()
+        if not bare:
+            continue
+        toks = _split_identifier(bare)
+        if toks:
+            if toks[0] in _ACTION_VERB_PREFIXES:
+                has_action = True
+            if query_toks & set(toks):
+                overlap_hits += 1
+
+    bonus = min(overlap_hits * _SYMBOL_MATCH_BONUS_PER_HIT, _SYMBOL_MATCH_BONUS_CAP)
+    if has_action:
+        bonus += _ACTION_VERB_BONUS
+
+    # Type-name overlap: strongest single lexical signal for "which class is
+    # the answer?" queries. Uses the simple name of primary_type_fqn.
+    fqn = str(r.get("primary_type_fqn") or "")
+    if fqn:
+        simple = fqn.rsplit(".", 1)[-1]
+        type_toks = set(_split_identifier(simple))
+        type_hits = len(query_toks & type_toks)
+        if type_hits:
+            bonus += min(type_hits * _TYPE_MATCH_BONUS_PER_HIT, _TYPE_MATCH_BONUS_CAP)
+    return bonus
+
+
+def _role_weight(r: dict) -> float:
+    """Effective role weight for a row, captured into `_score_components.role_weight`."""
+    comps = r.setdefault("_score_components", {})
+    cached = comps.get("role_weight")
+    if cached is not None:
+        return float(cached)
+    if r.get("_skip_role_weight") or str(r.get("_kind", "")) != "java":
+        comps["role_weight"] = 0.0
+        return 0.0
+    role = (r.get("role") or "").upper()
+    w = _ROLE_SCORE_WEIGHTS.get(role, 0.0)
+    comps["role_weight"] = w
+    return w
+
+
+def _apply_symbol_bonus(rows: list[dict], query_toks: set[str]) -> None:
+    """Pre-compute symbol-match bonus into `_score_components.symbol_bonus`."""
+    if not query_toks:
+        return
+    for r in rows:
+        if r.get("_skip_role_weight"):
+            # When the caller locked role, respect their intent everywhere.
+            continue
+        b = _symbol_bonus(r, query_toks)
+        if b:
+            r.setdefault("_score_components", {})["symbol_bonus"] = b
+
+
+def l2_distance_to_score(distance: float) -> float:
+    """Map L2 distance to a similarity score for unit-normalized embeddings."""
+    return 1.0 - distance * distance / 2.0
+
+
+def _effective_distance(comps: dict[str, float]) -> float:
+    """Compute the adjusted distance used for sorting.
+
+    Matches _vector_sort_key logic: distance + import_penalty - role_weight - symbol_bonus.
+    """
+    d = comps.get("distance", 0.0)
+    d += comps.get("import_penalty", 0.0)
+    d -= comps.get("role_weight", 0.0)
+    d -= comps.get("symbol_bonus", 0.0)
+    return d
+
+
+def _clamp01(x: float) -> float:
+    """Clamp a value to the [0.0, 1.0] range."""
+    if x < 0.0:
+        return 0.0
+    if x > 1.0:
+        return 1.0
+    return x
+
+
+def explain_score_components(
+    comps: dict[str, float] | None,
+    *,
+    role: str | None = None,
+    hybrid: bool = False,
+    graph_expanded: bool = False,
+    lexical: bool = False,
+) -> str:
+    """Compact human-readable 'why' string for a ranked hit.
+
+    Joins the interesting components of `_score_components` in a stable order
+    so agents can reason about rankings without chasing raw floats. Returns
+    "" if there's nothing worth mentioning.
+    """
+    if not comps:
+        comps = {}
+    parts: list[str] = []
+    if lexical:
+        rel = comps.get("lexical_relevance")
+        if rel is not None:
+            parts.append(f"relevance={float(rel):.2f}")
+        nm = comps.get("name_match")
+        if nm is not None:
+            parts.append(f"name={float(nm):.2f}")
+        ty = comps.get("type_match")
+        if ty:
+            parts.append(f"type:{float(ty):+.2f}")
+        fq = comps.get("fqn_match")
+        if fq:
+            parts.append(f"fqn:{float(fq):+.2f}")
+    elif hybrid:
+        # Prefer rrf_raw (added by PR-SEARCH-1a) for explanation
+        rrf = comps.get("rrf_raw") or comps.get("hybrid_rrf")
+        if rrf is not None:
+            parts.append(f"rrf={float(rrf):.3f}")
+    else:
+        d = comps.get("distance")
+        if d is not None:
+            parts.append(f"dist={float(d):.2f}")
+    rw = comps.get("role_weight")
+    if rw:
+        label = f"role:{role}" if role else "role"
+        parts.append(f"{label}:{float(rw):+.02f}")
+    sb = comps.get("symbol_bonus")
+    if sb:
+        parts.append(f"symbol:{float(sb):+.02f}")
+    ip = comps.get("import_penalty")
+    if ip:
+        parts.append(f"import_penalty:{float(ip):+.02f}")
+    if graph_expanded:
+        parts.append("graph")
+    return " ".join(parts)
+
+
+def _dedup_by_fqn(rows: list[dict], dedup_by_fqn: bool = True) -> list[dict]:
+    """Deduplicate rows by primary_type_fqn (java table only).
+
+    When dedup_by_fqn is True, collapses multiple chunks of the same
+    primary_type_fqn into one row (first-seen-wins, since rows are pre-sorted
+    so the first is the best chunk). Each survivor gets a _chunks_collapsed
+    field (>=1) counting how many rows were collapsed into it.
+
+    Rows without primary_type_fqn (sql/yaml tables) get a unique __id:<id>
+    key so they pass through unchanged (each row is unique).
+
+    When dedup_by_fqn is False, returns rows unchanged (regression guard).
+    """
+    if not dedup_by_fqn:
+        # Non-dedup path: return unchanged, byte-identical to prior behavior
+        return rows
+
+    deduped: list[dict] = []
+    seen_keys: dict[str, dict] = {}
+    collapsed_counts: dict[str, int] = {}
+
+    for row in rows:
+        # Build dedup key: primary_type_fqn for java rows, unique __id:<id> for sql/yaml
+        fqn = row.get("primary_type_fqn")
+        if fqn:
+            key = str(fqn)
+        else:
+            # sql/yaml rows have no primary_type_fqn → unique key per row
+            row_id = row.get("id") or id(row)
+            key = f"__id:{row_id}"
+
+        if key not in seen_keys:
+            # First occurrence: keep it
+            seen_keys[key] = row
+            collapsed_counts[key] = 1
+            deduped.append(row)
+        else:
+            # Duplicate: increment collapse count, discard this row
+            collapsed_counts[key] += 1
+
+    # Annotate each survivor with _chunks_collapsed
+    for row in deduped:
+        fqn = row.get("primary_type_fqn")
+        if fqn:
+            key = str(fqn)
+        else:
+            row_id = row.get("id") or id(row)
+            key = f"__id:{row_id}"
+        row["_chunks_collapsed"] = collapsed_counts[key]
+
+    return deduped