java-codebase-rag 0.9.6__py3-none-any.whl → 0.10.0__py3-none-any.whl

java_codebase_rag/absence/absence_vocab.py

@@ -375,8 +375,13 @@ def get_vocabulary_index(graph: Any, cfg: Any) -> VocabularyIndex:
         # (JSONDecodeError/KeyError) — all subsumed by Exception; rebuild.
         log.debug(f"Vocab index missing/stale/corrupt ({e}), rebuilding from graph")
 
-        # Build from graph
-        index = VocabularyIndex.build(graph, q=cfg.absence_ngram_q)
+        # Build from graph. Coerce q to int (mirror absence_diagnosis.py's
+        # int(getattr(cfg, ...)) pattern): a non-int cfg.absence_ngram_q (e.g. a
+        # MagicMock cfg from a leaked test mock, or a YAML string) would otherwise
+        # crash _qgrams at `len(text) < q` ('int < MagicMock'). Default 3 = the
+        # config default for absence_ngram_q.
+        q = int(getattr(cfg, "absence_ngram_q", 3) or 3)
+        index = VocabularyIndex.build(graph, q=q)
 
         # Save to sidecar (best-effort)
         try:

java_codebase_rag/analysis/pr_analysis.py

@@ -377,6 +377,31 @@ def _route_ids_for_symbol(graph: Any, symbol_id: str) -> list[str]:
     return out
 
 
+def _route_natural_id(graph: Any, rid: str) -> str:
+    """Map a raw Route node id to its agent-facing natural identifier.
+
+    Mirrors the envelope contract (``METHOD path`` for HTTP endpoints,
+    ``topic:<name>`` for kafka topics surfaced as :Route) so ``routes_touched``
+    in the PR risk report is readable instead of leaking raw graph ids like
+    ``r:970ffaa960a4f65d``. Falls back to ``rid`` only if the route vanished.
+    """
+    rows = graph._rows(
+        "MATCH (r:Route {id: $rid}) "
+        "RETURN r.method AS method, r.path_template AS path_template, "
+        "r.path AS path, r.topic AS topic LIMIT 1",
+        {"rid": rid},
+    )
+    if not rows:
+        return rid
+    r = rows[0]
+    method = str(r.get("method") or "")
+    path = str(r.get("path_template") or r.get("path") or "")
+    if method or path:
+        return f"{method} {path}".strip()
+    topic = str(r.get("topic") or "")
+    return f"topic:{topic}" if topic else rid
+
+
 def compute_risk(graph: Any, changed: list[ChangedSymbol]) -> PrRiskReport:
     """Aggregate blast radius, routes, cross-service callers, and v1 risk score.
 
@@ -415,7 +440,9 @@ def compute_risk(graph: Any, changed: list[ChangedSymbol]) -> PrRiskReport:
         needle = _impact_needle_for_changed(graph, fqn, cs.kind)
         ia = graph.impact_analysis(needle, depth=2, limit=400)
         n = len(ia)
-        blast_by[cs.symbol_id] = n
+        # Key blast radius by the symbol's FQN (agent-facing identifier), not
+        # its raw graph id — the report is operator-facing JSON.
+        blast_by[fqn or cs.symbol_id] = n
         blast_total += n
 
         for e in graph.find_callers(cs.fqn, depth=2, limit=400):
@@ -429,8 +456,11 @@ def compute_risk(graph: Any, changed: list[ChangedSymbol]) -> PrRiskReport:
         cs_cross_service = 0
         route_ids = _route_ids_for_symbol(graph, cs.symbol_id)
         for rid in route_ids:
-            if rid not in routes:
-                routes.append(rid)
+            # Record the route by its natural identifier (METHOD path /
+            # topic:name), not the raw graph id.
+            label = _route_natural_id(graph, rid)
+            if label and label not in routes:
+                routes.append(label)
             callers = graph._rows(
                 "MATCH (s:Symbol)-[:DECLARES_CLIENT]->(c:Client)-[e:HTTP_CALLS]->(r:Route {id: $rid}) "
                 "WHERE e.match = 'cross_service' "

java_codebase_rag/ast/ast_java.py

@@ -84,7 +84,8 @@ _DTO_LOMBOK_ANNOTATIONS: frozenset[str] = frozenset({
 # Phase 11: `EDGE_SCHEMA` in `java_ontology.py` (canonical edge navigation schema; v14 re-index).
 # Phase 12: CALLS `callee_declaring_role`, supertype-walk dedup, pass3 unresolved counters (v15 re-index).
 # Bumps whenever extraction / enrichment semantics change.
-ONTOLOGY_VERSION = 18
+# Phase 13: Symbol.search_text + LadybugDB FTS (Okapi BM25) index for lexical search (v19 re-index).
+ONTOLOGY_VERSION = 19
 
 ROLE_ANNOTATIONS: dict[str, str] = {
     # Spring Web

java_codebase_rag/cli.py

@@ -846,7 +846,15 @@ def _cmd_unresolved_calls_list(args: argparse.Namespace) -> int:
         callee_simple=args.callee_simple,
         limit=int(args.limit),
     )
-    _emit({"success": True, "count": len(rows), "sites": rows})
+    # Drop the raw caller symbol id: the row already carries the agent-facing
+    # ``caller_fqn``, so ``caller_id`` is redundant noise in an operator-facing
+    # report. The call-site ``id`` (``ucs:``) is kept — it's each site's
+    # primary key, not a caller reference.
+    sites = [
+        {k: v for k, v in row.items() if k != "caller_id"}
+        for row in rows
+    ]
+    _emit({"success": True, "count": len(sites), "sites": sites})
     return 0
 
 
@@ -1060,12 +1068,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     _add_index_embedding_flags(erase)
     erase.add_argument("--yes", action="store_true", help="Confirm destructive deletion (required in CI)")
-    erase.add_argument(
-        "--quiet", "-q",
-        action="store_true",
-        dest="quiet",
-        help="Suppress stderr progress relay; stdout payload unchanged.",
-    )
+    _add_verbosity_flags(erase)
     erase.set_defaults(handler=_cmd_erase)
 
     meta = subparsers.add_parser("meta", help="Print graph meta and embedding resolution.")
@@ -1162,8 +1165,20 @@ def _console_script_main() -> None:
     racy teardown — the command has already done its work and emitted its result.
     ``main()`` stays return-based so in-process test callers (``cli.main(...)``)
     keep working.
+
+    ``KeyboardInterrupt`` (Ctrl+C during a long indexing step) is caught here
+    rather than left to propagate: an uncaught interrupt bypasses this function
+    and runs full interpreter finalization (traceback + thread teardown),
+    whereas routing it through the same flush + ``os._exit`` path gives a clean,
+    immediate exit (code 130) and avoids the finalization-time SIGABRT noted
+    above for commands that loaded lancedb.
     """
-    rc = main()
+    try:
+        rc = main()
+    except KeyboardInterrupt:
+        sys.stderr.write("\nInterrupted.\n")
+        sys.stderr.flush()
+        rc = 130
     sys.stdout.flush()
     sys.stderr.flush()
     os._exit(rc)

java_codebase_rag/config.py

@@ -378,6 +378,14 @@ class ResolvedOperatorConfig:
     # used with no config file). Recorded into the index dir at index time so a
     # later discovery run from a sibling/cwd can relocate this config.
     yaml_config_path: Path | None = None
+    # ``watch:`` block knobs (jrag watch / watcher). Defaults make the block
+    # optional; no env vars are introduced for these (CLI flag > YAML > default).
+    watch_debounce_ms: int = 1500
+    watch_backend: str = "auto"
+    watch_poll_interval_ms: int = 2000
+    watch_debounce_ms_source: SettingSource = "default"
+    watch_backend_source: SettingSource = "default"
+    watch_poll_interval_ms_source: SettingSource = "default"
 
     def apply_to_os_environ(self) -> None:
         """Make downstream modules (server, ladybug_queries, flows) see a consistent environment.
@@ -506,16 +514,20 @@ def _pick_float(
 
 def _pick_int(
     *,
+    cli_val: int | None = None,
     env_key: str,
     yaml_dict: dict[str, Any],
     yaml_path: tuple[str, ...],
     default: int,
 ) -> tuple[int, SettingSource]:
-    """Pick an int setting from env (parsed via int(...)), YAML, or default.
+    """Pick an int setting from CLI, env (parsed via int(...)), YAML, or default.
 
     Precedence: CLI > env > YAML > default. Env values that fail to parse as int
     fall back to the default (matching the brief's requirement for graceful degradation).
+    ``cli_val`` defaults to ``None`` so existing callers are unaffected.
     """
+    if cli_val is not None:
+        return int(cli_val), "cli"
     env_raw = os.environ.get(env_key, "").strip()
     if env_raw:
         try:
@@ -577,6 +589,9 @@ def resolve_operator_config(
     cli_index_dir: str | None = None,
     cli_embedding_model: str | None = None,
     cli_embedding_device: str | None = None,
+    cli_watch_debounce_ms: int | None = None,
+    cli_watch_backend: str | None = None,
+    cli_watch_poll_interval_ms: int | None = None,
 ) -> ResolvedOperatorConfig:
     # Phase 1: Find the config file directory
     if source_root is not None:
@@ -671,6 +686,52 @@ def resolve_operator_config(
         yaml_path=("absence", "diag_enabled"),
         default=True,
     )
+    # ``watch:`` block knobs. No env vars are introduced for watch (CLI > YAML >
+    # default), so an empty env_key is passed to the ``_pick_*`` helpers —
+    # ``os.environ.get("", "")`` never matches, leaving the env tier inert.
+    w_debounce, w_debounce_src = _pick_int(
+        cli_val=cli_watch_debounce_ms,
+        env_key="",
+        yaml_dict=yaml_dict,
+        yaml_path=("watch", "debounce_ms"),
+        default=1500,
+    )
+    w_backend, w_backend_src = _pick_str(
+        cli_val=cli_watch_backend,
+        env_key="",
+        yaml_dict=yaml_dict,
+        yaml_path=("watch", "backend"),
+        default="auto",
+    )
+    w_poll, w_poll_src = _pick_int(
+        cli_val=cli_watch_poll_interval_ms,
+        env_key="",
+        yaml_dict=yaml_dict,
+        yaml_path=("watch", "poll_interval_ms"),
+        default=2000,
+    )
+    # Inline floors/validation (mirror the existing graceful-degradation style).
+    if w_debounce < 100:
+        print(
+            f"java-codebase-rag: watch.debounce_ms={w_debounce} is below the 100 ms "
+            "floor; falling back to 1500.",
+            file=sys.stderr,
+        )
+        w_debounce, w_debounce_src = 1500, "default"
+    if w_backend not in ("auto", "watchdog", "polling"):
+        print(
+            f"java-codebase-rag: watch.backend={w_backend!r} is not one of "
+            "auto/watchdog/polling; falling back to 'auto'.",
+            file=sys.stderr,
+        )
+        w_backend, w_backend_src = "auto", "default"
+    if w_poll < 200:
+        print(
+            f"java-codebase-rag: watch.poll_interval_ms={w_poll} is below the 200 ms "
+            "floor; falling back to 2000.",
+            file=sys.stderr,
+        )
+        w_poll, w_poll_src = 2000, "default"
     ku = index_dir / "code_graph.lbug"
     coco = index_dir / "cocoindex.db"
     return ResolvedOperatorConfig(
@@ -696,6 +757,12 @@ def resolve_operator_config(
         absence_ngram_q_source=abs_q_src,
         absence_diag_enabled_source=abs_diag_src,
         yaml_config_path=find_yaml_config_file(config_dir),
+        watch_debounce_ms=w_debounce,
+        watch_backend=w_backend,
+        watch_poll_interval_ms=w_poll,
+        watch_debounce_ms_source=w_debounce_src,
+        watch_backend_source=w_backend_src,
+        watch_poll_interval_ms_source=w_poll_src,
     )
 
 

java_codebase_rag/graph/build_ast_graph.py

@@ -68,6 +68,7 @@ from java_codebase_rag.graph.graph_enrich import (
     symbol_id,
 )
 from java_codebase_rag.graph.path_filtering import LayeredIgnore, iter_java_source_files
+from java_codebase_rag.search.search_scoring import SYMBOL_FTS_INDEX as _SYMBOL_FTS_INDEX, _split_identifier
 from java_codebase_rag.graph.java_ontology import (
     CLIENT_KIND_FEIGN_METHOD,
     CLIENT_KIND_REST_TEMPLATE,
@@ -801,6 +802,12 @@ def _delete_file_scope(
     Producer nodes use DETACH DELETE as a safety net for any edges missed in
     Phase 1.
     """
+    # Symbol DELETEs below maintain the FTS index, which needs the extension loaded on
+    # this connection. Idempotent + best-effort (no-op when no index exists / FTS absent).
+    try:
+        conn.execute("LOAD EXTENSION FTS")
+    except Exception:
+        pass
     scope_files = changed_files | dependent_files
     scope_list = list(scope_files)
     changed_list = list(changed_files)
@@ -2927,7 +2934,8 @@ _SCHEMA_NODE = (
     "start_byte INT64, end_byte INT64, "
     "modifiers STRING[], annotations STRING[], capabilities STRING[], "
     "role STRING, signature STRING, parent_id STRING, resolved BOOLEAN, "
-    "generated BOOLEAN, generated_by STRING"
+    "generated BOOLEAN, generated_by STRING, "
+    "search_text STRING"
     ")"
 )
 
@@ -3050,7 +3058,28 @@ _SCHEMA_ASYNC_CALLS = (
 )
 
 
+def _drop_symbol_fts_index_if_present(conn: ladybug.Connection) -> None:
+    """Drop the Symbol FTS index so the table drop below succeeds.
+
+    LadybugDB refuses ``DROP TABLE Symbol`` while an FTS index references it ("Cannot
+    delete node table ... referenced by index"), so the index must go first. No-op when
+    FTS is unavailable (offline first-run) or the index was never created — in those
+    cases nothing blocks the table drop. Best-effort: any failure is swallowed.
+    """
+    try:
+        conn.execute("LOAD EXTENSION FTS")
+        existing = conn.execute("CALL SHOW_INDEXES() RETURN index_name")
+        names: set[str] = set()
+        while existing.has_next():
+            names.add(existing.get_next()[0])
+        if _SYMBOL_FTS_INDEX in names:
+            conn.execute(f"CALL DROP_FTS_INDEX('Symbol', '{_SYMBOL_FTS_INDEX}')")
+    except Exception:
+        pass
+
+
 def _drop_all(conn: ladybug.Connection) -> None:
+    _drop_symbol_fts_index_if_present(conn)
     for stmt in (
         "DROP TABLE IF EXISTS DECLARES_CLIENT",
         "DROP TABLE IF EXISTS DECLARES_PRODUCER",
@@ -3101,6 +3130,80 @@ def _create_schema(conn: ladybug.Connection) -> None:
         conn.execute(stmt)
 
 
+_IDENT_RE = re.compile(r"[A-Za-z][A-Za-z0-9]*")
+
+
+def _compute_symbol_search_text(
+    name: str,
+    fqn: str,
+    signature: str,
+    annotations: list[str],
+    capabilities: list[str],
+    package: str = "",
+) -> str:
+    """Build the BM25-indexable token soup for a Symbol (fork A).
+
+    camelCase / snake_case identifiers are split into lowercase tokens via the SAME
+    ``_split_identifier`` the query path uses (index- and query-time tokenization
+    must agree), then space-joined into one STRING that LadybugDB FTS porter-stems.
+    Name + fqn carry the strongest discovery signal; signature / annotations /
+    capabilities / package segments are weaker corroborators. Members reach this via
+    the same ``_node_row`` constructor as types.
+    """
+    toks: list[str] = []
+    for field in (name, fqn, signature, package):
+        for m in _IDENT_RE.findall(str(field or "")):
+            toks.extend(_split_identifier(m))
+    for lst in (annotations, capabilities):
+        for item in (lst or []):
+            for m in _IDENT_RE.findall(str(item)):
+                toks.extend(_split_identifier(m))
+    seen: set[str] = set()
+    out: list[str] = []
+    for t in toks:
+        if len(t) >= 2 and t not in seen:
+            seen.add(t)
+            out.append(t)
+    return " ".join(out)
+
+
+def _ensure_symbol_fts_index(conn: ladybug.Connection, *, verbose: bool) -> None:
+    """Best-effort create the Symbol FTS (Okapi BM25) index if absent (fork A).
+
+    Idempotent: skips when the index already exists. The FTS extension is fetched
+    from extension.ladybugdb.com on first ``INSTALL FTS`` (cached locally after); an
+    offline first run fails softly — ``run_lexical_search`` then falls back to the
+    heuristic over the bare Symbol scan. The index auto-maintains on later
+    COPY / MERGE / DELETE (verified), so this only runs on full builds and as a
+    cheap self-heal at the end of an incremental rebuild.
+    """
+    try:
+        try:
+            conn.execute("INSTALL FTS")  # already-installed raises; swallow
+        except Exception:
+            pass
+        conn.execute("LOAD EXTENSION FTS")
+        existing = conn.execute("CALL SHOW_INDEXES() RETURN index_name")
+        names: set[str] = set()
+        while existing.has_next():
+            names.add(existing.get_next()[0])
+        if _SYMBOL_FTS_INDEX not in names:
+            conn.execute(
+                f"CALL CREATE_FTS_INDEX('Symbol', '{_SYMBOL_FTS_INDEX}', "
+                "['search_text'], stemmer := 'porter')"
+            )
+            if verbose:
+                _verbose_stderr_line(
+                    f"[graph] fts · created Symbol {_SYMBOL_FTS_INDEX} (BM25 over search_text)"
+                )
+    except Exception as e:
+        if verbose:
+            _verbose_stderr_line(
+                f"[graph] fts · unavailable ({type(e).__name__}: {e}); "
+                "lexical search will use the heuristic scan"
+            )
+
+
 def _node_row(**kwargs) -> dict:
     base = {
         "kind": "", "name": "", "fqn": "", "package": "",
@@ -3109,9 +3212,16 @@ def _node_row(**kwargs) -> dict:
         "start_byte": 0, "end_byte": 0,
         "modifiers": [], "annotations": [], "capabilities": [],
         "role": "OTHER", "signature": "", "parent_id": "", "resolved": True,
-        "generated": False, "generated_by": None,
+        "generated": False, "generated_by": None, "search_text": "",
     }
     base.update(kwargs)
+    # Derive the BM25 token soup unless the caller set it explicitly.
+    if not base.get("search_text"):
+        base["search_text"] = _compute_symbol_search_text(
+            base.get("name", ""), base.get("fqn", ""), base.get("signature", ""),
+            base.get("annotations", []), base.get("capabilities", []),
+            base.get("package", ""),
+        )
     return base
 
 
@@ -3161,7 +3271,7 @@ _NODE_COLUMNS = [
     "id", "kind", "name", "fqn", "package", "module", "microservice",
     "filename", "start_line", "end_line", "start_byte", "end_byte",
     "modifiers", "annotations", "capabilities", "role", "signature", "parent_id", "resolved",
-    "generated", "generated_by"
+    "generated", "generated_by", "search_text"
 ]
 
 # Type declaration kinds. Tuple (not set) so the rendered SQL `IN` clause is
@@ -3185,7 +3295,7 @@ _SET_SYMBOL_BY_ID = (
     "n.modifiers = $modifiers, n.annotations = $annotations, "
     "n.capabilities = $capabilities, n.role = $role, "
     "n.signature = $signature, n.parent_id = $parent_id, n.resolved = $resolved, "
-    "n.generated = $generated, n.generated_by = $generated_by"
+    "n.generated = $generated, n.generated_by = $generated_by, n.search_text = $search_text"
 )
 
 # Refresh every mutable Route field on an existing Route node by id. Mirrors the
@@ -3835,6 +3945,13 @@ def incremental_rebuild(
 
     db = ladybug.Database(str(ladybug_path))
     conn = ladybug.Connection(db)
+    # If a Symbol FTS index exists, the scoped DELETE/MERGE/COPY below must maintain it,
+    # which needs the FTS extension loaded on THIS connection. Best-effort: when FTS is
+    # unavailable no index exists, so there's nothing to maintain and DML proceeds fine.
+    try:
+        conn.execute("LOAD EXTENSION FTS")
+    except Exception:
+        pass
 
     # Check ontology version
     try:
@@ -4007,6 +4124,7 @@ def incremental_rebuild(
 
         # Update GraphMeta
         _write_meta(conn, tables_for_global, source_root)
+        _ensure_symbol_fts_index(conn, verbose=verbose)
 
         # Remove crash marker
         crash_marker_path.unlink(missing_ok=True)
@@ -4236,6 +4354,7 @@ def write_ladybug(
         if verbose:
             _verbose_stderr_line(f"[graph] writing · routes/exposes written in {time.time() - t2:.2f}s")
         _write_meta(conn, tables, source_root)
+        _ensure_symbol_fts_index(conn, verbose=verbose)
         conn.close()
         db.close()
 

java_codebase_rag/graph/graph_types.py

@@ -36,6 +36,24 @@ class NodeRef(BaseModel):
     role: str | None = None
     generated: bool | None = None
     generated_by: str | None = None
+    # Identity-adjacent fields consumed by ``jrag_envelope.node_key`` (keying)
+    # and ``project_node`` allow-lists (rendering) so find filter-mode nodes
+    # carry the same rich shape as the dedicated listings (http-routes /
+    # http-clients / producers). All optional with default None: existing
+    # NodeRef constructors are unaffected and ``_drop_empty`` strips unset
+    # fields at the JSON boundary.
+    method: str | None = None
+    path: str | None = None
+    framework: str | None = None
+    member_fqn: str | None = None
+    target_service: str | None = None
+    client_kind: str | None = None
+    topic: str | None = None
+    broker: str | None = None
+    producer_kind: str | None = None
+    filename: str | None = None
+    start_line: int | None = None
+    resolved: bool | None = None
 
 
 class StructuredHint(BaseModel):
@@ -98,38 +116,107 @@ def _resolve_node_kind(
 
 
 def _node_ref_from_row(kind: Literal["symbol", "route", "client", "producer"], row: dict[str, Any]) -> NodeRef:
-    symbol_kind: str | None = None
+    """Map a graph store row to a :class:`NodeRef`.
+
+    ``fqn`` is set to each kind's documented natural identifier (README
+    §"jrag — agent CLI") so ``jrag_envelope.node_key`` (which checks ``fqn``
+    first) keys nodes correctly and no raw graph id leaks:
+
+      * symbol  -> symbol fqn
+      * route   -> ``"METHOD path"`` (HTTP endpoint); ``"topic:<name>"`` when a
+                   kafka topic surfaces as :Route; ``""`` for a phantom route
+                   (node_key then falls through to the composed ``file``)
+      * client  -> ``"member_fqn->target_service"``
+      * producer-> ``"topic:<name>"``
+
+    Rich detail (member_fqn / target_service / method / path / topic /
+    framework / filename / start_line / resolved) is populated alongside so
+    find filter-mode nodes render with the same shape as the dedicated
+    listings (``http-routes`` / ``http-clients`` / ``producers``) instead of
+    collapsing to ``{"kind": ...}`` after the envelope's projection+drop-empty.
+    """
+    microservice = str(row.get("microservice") or "") or None
+    module = str(row.get("module") or "") or None
+    filename = str(row.get("filename") or "") or None
+    start_line = row.get("start_line")
+    try:
+        start_line = int(start_line) if start_line not in (None, "") else None
+    except (TypeError, ValueError):
+        start_line = None
+    resolved_raw = row.get("resolved")
+    resolved = bool(resolved_raw) if resolved_raw is not None else None
+    nid = str(row.get("id") or "")
+
     if kind == "symbol":
         fqn = str(row.get("fqn") or "")
         role = str(row.get("role") or "") or None
         symbol_kind_val = str(row.get("symbol_kind") or row.get("kind") or "").strip()
         symbol_kind = symbol_kind_val or None
-    elif kind == "route":
+        return NodeRef(
+            id=nid, kind="symbol", fqn=fqn,
+            name=str(row.get("name") or "") or None,
+            symbol_kind=symbol_kind,
+            microservice=microservice, module=module, role=role,
+            filename=filename, start_line=start_line,
+            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,
+        )
+
+    if kind == "route":
         method = str(row.get("method") or "")
         path = str(row.get("path_template") or row.get("path") or "")
-        fqn = f"{method} {path}".strip()
-        role = None
-    elif kind == "client":
+        topic = str(row.get("topic") or "") or None
+        if method or path:
+            fqn = f"{method} {path}".strip()
+        elif topic:
+            fqn = f"topic:{topic}"
+        else:
+            fqn = ""
+        return NodeRef(
+            id=nid, kind="route", fqn=fqn, name=(path or topic),
+            method=method or None, path=path or None, topic=topic,
+            framework=str(row.get("framework") or "") or None,
+            microservice=microservice, module=module,
+            filename=filename, start_line=start_line, resolved=resolved,
+        )
+
+    if kind == "client":
+        mfqn = str(row.get("member_fqn") or "")
+        tgt = str(row.get("target_service") or "")
         method = str(row.get("method") or "")
-        target = str(row.get("target_service") or "")
         path = str(row.get("path_template") or row.get("path") or "")
-        fqn = f"{target} {method} {path}".strip()
-        role = None
-    else:
-        topic = str(row.get("topic") or "")
-        broker = str(row.get("broker") or "")
-        fqn = f"{topic} {broker}".strip()
-        role = None
+        member_fqn = mfqn or None
+        target_service = tgt or None
+        member_simple = (mfqn.rsplit(".", 1)[-1] if mfqn else "") or None
+        # Build the contract id ``member_fqn->target_service`` from the RAW
+        # strings: ``member_fqn`` was normalized to None above, so interpolating
+        # it would emit ``"None-><target>"`` for member-less (brownfield/meta)
+        # clients. Fall back to whichever half is present; never a dangling arrow.
+        fqn = f"{mfqn}->{tgt}" if (mfqn and tgt) else (mfqn or tgt)
+        return NodeRef(
+            id=nid, kind="client",
+            fqn=fqn,
+            name=member_simple,
+            member_fqn=member_fqn, target_service=target_service,
+            method=method or None, path=path or None,
+            client_kind=str(row.get("client_kind") or "") or None,
+            microservice=microservice, module=module,
+            filename=filename, start_line=start_line, resolved=resolved,
+        )
+
+    # producer
+    topic = str(row.get("topic") or "") or None
+    member_fqn = str(row.get("member_fqn") or "") or None
+    member_simple = (member_fqn.rsplit(".", 1)[-1] if member_fqn else "") or None
     return NodeRef(
-        id=str(row.get("id") or ""),
-        kind=kind,
-        fqn=fqn,
-        symbol_kind=symbol_kind,
-        microservice=str(row.get("microservice") or "") or None,
-        module=str(row.get("module") or "") or None,
-        role=role,
-        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,
+        id=nid, kind="producer",
+        fqn=(f"topic:{topic}" if topic else ""),
+        name=(topic or member_simple),
+        topic=topic, broker=str(row.get("broker") or "") or None,
+        producer_kind=str(row.get("producer_kind") or "") or None,
+        member_fqn=member_fqn,
+        microservice=microservice, module=module,
+        filename=filename, start_line=start_line, resolved=resolved,
     )
 
 

java_codebase_rag/graph/ladybug_queries.py

@@ -396,6 +396,22 @@ class LadybugGraph:
         # Ladybug represents DB as a directory; allow file form too (single-file DBs).
         return True
 
+    @classmethod
+    def reset_for_path(cls, db_path: str | None) -> None:
+        """Drop the cached singleton so the next ``get`` reopens.
+
+        Clears the cache when ``db_path is None`` (unconditional) or when ``db_path``
+        resolves to the currently cached instance path (resolved the same way
+        ``get`` resolves it, so ``~``-relative / non-normalized paths match); a
+        non-matching ``db_path`` is a no-op. The watch daemon uses this to manage
+        its copy-on-write graph snapshot lifecycle (drop the original reader
+        before a subprocess reindex writes it; drop the sidecar reader on commit).
+        """
+        with cls._lock:
+            if db_path is None or cls._instance_path == resolve_ladybug_path(db_path):
+                cls._instance = None
+                cls._instance_path = None
+
     # ---- low-level ----
 
     def _rows(self, query: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
@@ -997,8 +1013,35 @@ class LadybugGraph:
     def find_by_name_or_fqn(self, name_or_fqn: str, *, kinds: list[str] | None = None,
                             module: str | None = None,
                             microservice: str | None = None,
-                            limit: int = 50) -> list[SymbolHit]:
-        filters = ["(s.name = $needle OR s.fqn = $needle)"]
+                            limit: int = 50,
+                            mode: str = "exact") -> list[SymbolHit]:
+        # ``mode`` selects the name/FQN predicate. ``exact`` (default) preserves the
+        # original ``s.name = $needle OR s.fqn = $needle``. ``prefix`` / ``contains``
+        # use STARTS WITH / CONTAINS (Ladybug Cypher supports both — see
+        # resolve_service.py); they back the ``find --fuzzy`` fallback (issue #375).
+        # Fuzzy modes additionally exclude file/package Symbol nodes: their fqn is a
+        # filesystem path, so a substring/prefix would leak filename rows (mirrors
+        # the find_v2 fix, #411). Exact mode is unchanged for back-compat.
+        # Empty needle: STARTS WITH '' / CONTAINS '' match every string, so a
+        # fuzzy mode would silently return up to `limit` arbitrary Symbols. The
+        # CLI guards this (query mode requires a positional), but keep the
+        # backend safe-by-construction for any future caller.
+        if mode != "exact" and not name_or_fqn:
+            return []
+        if mode == "exact":
+            filters = ["(s.name = $needle OR s.fqn = $needle)"]
+        elif mode == "prefix":
+            filters = [
+                "(s.name STARTS WITH $needle OR s.fqn STARTS WITH $needle)",
+                "(s.kind <> 'file' AND s.kind <> 'package')",
+            ]
+        elif mode == "contains":
+            filters = [
+                "(s.name CONTAINS $needle OR s.fqn CONTAINS $needle)",
+                "(s.kind <> 'file' AND s.kind <> 'package')",
+            ]
+        else:
+            raise ValueError(f"unknown find_by_name_or_fqn mode: {mode!r}")
         params: dict[str, Any] = {"needle": name_or_fqn}
         if kinds:
             params["kinds"] = kinds