java-codebase-rag 0.6.3__py3-none-any.whl → 0.6.4__py3-none-any.whl

ast_java.py

@@ -14,8 +14,8 @@ from __future__ import annotations
 
 import posixpath
 import sys
+import threading
 from dataclasses import dataclass, field
-from functools import lru_cache
 from typing import Iterable
 
 import tree_sitter_java as _ts_java
@@ -215,10 +215,23 @@ _ANON_SUPER_AS_INTERFACE: frozenset[str] = frozenset({
 })
 
 
-@lru_cache(maxsize=1)
+# tree-sitter's ``Parser`` mutates internal state during ``parse()`` and is NOT
+# thread-safe, so each OS thread gets its own instance. ``parse_java`` is called
+# concurrently from worker threads when indexing runs with cocoindex's inflight
+# parallelism — both directly (java_index_flow_lancedb.py: process_java_file
+# offloads parse+enrich to asyncio.to_thread) and transitively
+# (graph_enrich.collect_annotation_meta_chain -> _collect_annotation_decl_index
+# -> parse_java, reached from enrich_chunk). The ``Language`` is immutable and
+# shared; per-thread ``Parser`` construction is lazy and cheap (once per thread),
+# which also preserves parse parallelism instead of serializing it.
+_parser_tls = threading.local()
+
+
 def _parser() -> Parser:
-    lang = Language(_ts_java.language())
-    return Parser(lang)
+    p = getattr(_parser_tls, "parser", None)
+    if p is None:
+        _parser_tls.parser = p = Parser(Language(_ts_java.language()))
+    return p
 
 
 # ---------- dataclasses ----------
@@ -1565,62 +1578,20 @@ def _parse_codebase_http_route_inner_annotation(
     return out
 
 
-def _codebase_route_inner_annotation_nodes(container_ann: Node, src: bytes) -> list[Node]:
-    found: list[Node] = []
-
-    def visit(n: Node) -> None:
-        if n.type == "annotation":
-            name_node = n.child_by_field_name("name")
-            n_simple = _txt(name_node, src).rsplit(".", 1)[-1] if name_node is not None else ""
-            if n_simple == "CodebaseHttpRoute":
-                found.append(n)
-        for c in n.children:
-            visit(c)
+def _inner_annotation_nodes(container_ann: Node, src: bytes, target_simple: str) -> list[Node]:
+    """Collect nested ``@<target_simple>`` annotations anywhere under ``container_ann``.
 
-    visit(container_ann)
-    return found
-
-
-def _codebase_async_route_inner_annotation_nodes(container_ann: Node, src: bytes) -> list[Node]:
-    found: list[Node] = []
-
-    def visit(n: Node) -> None:
-        if n.type == "annotation":
-            name_node = n.child_by_field_name("name")
-            n_simple = _txt(name_node, src).rsplit(".", 1)[-1] if name_node is not None else ""
-            if n_simple == "CodebaseAsyncRoute":
-                found.append(n)
-        for c in n.children:
-            visit(c)
-
-    visit(container_ann)
-    return found
-
-
-def _codebase_http_client_inner_annotation_nodes(container_ann: Node, src: bytes) -> list[Node]:
-    found: list[Node] = []
-
-    def visit(n: Node) -> None:
-        if n.type == "annotation":
-            name_node = n.child_by_field_name("name")
-            n_simple = _txt(name_node, src).rsplit(".", 1)[-1] if name_node is not None else ""
-            if n_simple == "CodebaseHttpClient":
-                found.append(n)
-        for c in n.children:
-            visit(c)
-
-    visit(container_ann)
-    return found
-
-
-def _codebase_producer_inner_annotation_nodes(container_ann: Node, src: bytes) -> list[Node]:
+    Shared by the four brownfield container walkers — ``CodebaseHttpRoute``,
+    ``CodebaseAsyncRoute``, ``CodebaseHttpClient``, ``CodebaseProducer`` — which
+    differ only by the target annotation simple name.
+    """
     found: list[Node] = []
 
     def visit(n: Node) -> None:
         if n.type == "annotation":
             name_node = n.child_by_field_name("name")
             n_simple = _txt(name_node, src).rsplit(".", 1)[-1] if name_node is not None else ""
-            if n_simple == "CodebaseProducer":
+            if n_simple == target_simple:
                 found.append(n)
         for c in n.children:
             visit(c)
@@ -1842,7 +1813,7 @@ def _outgoing_calls_from_codebase_http_client_producer_annotations(
                 ),
             )
         elif simple == "CodebaseHttpClients":
-            for inner in _codebase_http_client_inner_annotation_nodes(ann, src):
+            for inner in _inner_annotation_nodes(ann, src, "CodebaseHttpClient"):
                 out.append(
                     _parse_codebase_http_client_annotation(
                         inner,
@@ -1869,7 +1840,7 @@ def _outgoing_calls_from_codebase_http_client_producer_annotations(
                 ),
             )
         elif simple == "CodebaseProducers":
-            for inner in _codebase_producer_inner_annotation_nodes(ann, src):
+            for inner in _inner_annotation_nodes(ann, src, "CodebaseProducer"):
                 out.append(
                     _parse_codebase_producer_annotation(
                         inner,
@@ -2343,7 +2314,7 @@ def _collect_routes(
                 ),
             )
         elif simple == "CodebaseHttpRoutes":
-            for inner in _codebase_route_inner_annotation_nodes(node, src):
+            for inner in _inner_annotation_nodes(node, src, "CodebaseHttpRoute"):
                 routes.extend(
                     _parse_codebase_http_route_inner_annotation(
                         inner,
@@ -2359,7 +2330,7 @@ def _collect_routes(
         elif simple in ("CodebaseAsyncRoute", "CodebaseAsyncRoutes"):
             nodes = [node]
             if simple == "CodebaseAsyncRoutes":
-                nodes = list(_codebase_async_route_inner_annotation_nodes(node, src))
+                nodes = list(_inner_annotation_nodes(node, src, "CodebaseAsyncRoute"))
             for ann in nodes:
                 pairs, _ = _annotation_kv_nodes(ann, src)
                 topic_node = pairs.get("topic")

build_ast_graph.py

@@ -2010,8 +2010,21 @@ def _producer_id(
     return f"p:{hashlib.sha1(key.encode()).hexdigest()[:16]}"
 
 
+# The four brownfield source layers — single source of truth. Consumed by the
+# client/producer source-layer classifiers, the *_from_brownfield_pct stats
+# (via brownfield_strategies), and the brownfield_only authoritativeness gate in
+# _is_brownfield_sourced. codebase_client/codebase_producer are caller-side
+# declaration strategies, not layers — they extend brownfield_strategies only.
+_BROWNFIELD_LAYERS = frozenset({
+    "layer_a_meta",
+    "layer_b_ann",
+    "layer_b_fqn",
+    "layer_c_source",
+})
+
+
 def _client_source_layer(strategy: str) -> str:
-    if strategy in {"layer_a_meta", "layer_b_ann", "layer_b_fqn", "layer_c_source"}:
+    if strategy in _BROWNFIELD_LAYERS:
         return strategy
     # Some caller extraction paths emit client kind as strategy; treat those
     # as builtin-source declarations instead of warning on every row.
@@ -2023,7 +2036,7 @@ def _client_source_layer(strategy: str) -> str:
 
 
 def _producer_source_layer(strategy: str) -> str:
-    if strategy in {"layer_a_meta", "layer_b_ann", "layer_b_fqn", "layer_c_source"}:
+    if strategy in _BROWNFIELD_LAYERS:
         return strategy
     if strategy in VALID_PRODUCER_KINDS:
         return "builtin"
@@ -2458,15 +2471,14 @@ def pass5_imperative_edges(
         tables.producer_stats.producers_by_kind = defaultdict(int)
         for row in tables.producer_rows:
             tables.producer_stats.producers_by_kind[row.producer_kind] += 1
-        brownfield_strategies = frozenset(
-            (
-                "layer_b_ann",
-                "layer_a_meta",
-                "layer_c_source",
-                "layer_b_fqn",
-                "codebase_client",
-                "codebase_producer",
-            ),
+        # brownfield_strategies = the four brownfield layers plus the two
+        # caller-side declaration strategies (@CodebaseHttpClient /
+        # @CodebaseProducer). These extend _BROWNFIELD_LAYERS deliberately:
+        # the *_from_brownfield_pct stats count annotation-declared callers as
+        # brownfield-sourced even though they are not "layers" and so do not
+        # gate brownfield_only authoritativeness in _is_brownfield_sourced.
+        brownfield_strategies = _BROWNFIELD_LAYERS | frozenset(
+            {"codebase_client", "codebase_producer"},
         )
         if tables.call_edge_stats.http_calls_total:
             n_http = sum(
@@ -2568,14 +2580,6 @@ def _match_call_edge(
     return "cross_service", candidates
 
 
-_BROWNFIELD_LAYERS = frozenset({
-    "layer_c_source",
-    "layer_b_ann",
-    "layer_b_fqn",
-    "layer_a_meta",
-})
-
-
 def _is_brownfield_sourced(
     call_strategy: str,
     candidates: list[RouteRow],

graph_enrich.py

@@ -23,7 +23,7 @@ import sys
 from dataclasses import dataclass, field, replace
 from functools import lru_cache
 from pathlib import Path
-from typing import Any
+from typing import Any, TypeVar
 from ast_java import (
     AnnotationRef,
     JavaFileAst,
@@ -820,7 +820,15 @@ def _route_path_atom(raw_value: str, value_kind: str | None) -> tuple[str, str,
     return "", "constant_ref", 0.7, False
 
 
-def _route_hint_lookup(ann: AnnotationRef, hints: dict[str, RouteHint]) -> RouteHint | None:
+_HINT = TypeVar("_HINT")
+
+
+def _hint_lookup(ann: AnnotationRef, hints: dict[str, _HINT]) -> _HINT | None:
+    """Resolve a brownfield hint by qualified name, then simple name, then suffix.
+
+    Shared by route / http-client / async-producer hint resolution; the three
+    former copies differed only in the hint value type.
+    """
     q = ann.qualified.strip()
     if q in hints:
         return hints[q]
@@ -1118,7 +1126,7 @@ def resolve_routes_for_method(
 
     # ----- Step 2: Layer B — annotation route hints -----
     for _is_m, ann in combined_anns:
-        hint = _route_hint_lookup(ann, overrides.annotation_to_route_hint)
+        hint = _hint_lookup(ann, overrides.annotation_to_route_hint)
         if hint is None:
             continue
         working.append(
@@ -1172,36 +1180,6 @@ def resolve_routes_for_method(
     return working
 
 
-def _client_hint_lookup(
-    ann: AnnotationRef,
-    hints: dict[str, HttpClientHint],
-) -> HttpClientHint | None:
-    q = ann.qualified.strip()
-    if q in hints:
-        return hints[q]
-    if ann.name in hints:
-        return hints[ann.name]
-    for k, h in sorted(hints.items(), key=lambda kv: kv[0]):
-        if k.endswith("." + ann.name):
-            return h
-    return None
-
-
-def _async_hint_lookup(
-    ann: AnnotationRef,
-    hints: dict[str, AsyncProducerHint],
-) -> AsyncProducerHint | None:
-    q = ann.qualified.strip()
-    if q in hints:
-        return hints[q]
-    if ann.name in hints:
-        return hints[ann.name]
-    for k, h in sorted(hints.items(), key=lambda kv: kv[0]):
-        if k.endswith("." + ann.name):
-            return h
-    return None
-
-
 def _call_from_http_hint(
     *,
     hint: HttpClientHint,
@@ -1296,7 +1274,7 @@ def resolve_http_client_for_method(
     anchor = builtin_http[0] if builtin_http else (layer_c_src[0] if layer_c_src else None)
 
     for _is_m, ann in combined_anns:
-        hint = _client_hint_lookup(ann, overrides.annotation_to_http_client_hint)
+        hint = _hint_lookup(ann, overrides.annotation_to_http_client_hint)
         if hint is None:
             continue
         brownfield_calls.append(
@@ -1388,7 +1366,7 @@ def resolve_async_producer_for_method(
     anchor = builtin_async[0] if builtin_async else (layer_c_src[0] if layer_c_src else None)
 
     for _is_m, ann in combined_anns:
-        hint = _async_hint_lookup(ann, overrides.annotation_to_async_producer_hint)
+        hint = _hint_lookup(ann, overrides.annotation_to_async_producer_hint)
         if hint is None:
             continue
         brownfield_calls.append(

java_codebase_rag/cli.py

@@ -251,7 +251,7 @@ def _startup_hints(cfg: ResolvedOperatorConfig) -> None:
 
 def _add_index_embedding_flags(p: argparse.ArgumentParser) -> None:
     p.add_argument("--source-root", type=str, default=None, help="Java repository root (default: cwd)")
-    p.add_argument("--index-dir", type=str, default=None, help="Index directory (Lance + Kuzu + cocoindex state)")
+    p.add_argument("--index-dir", type=str, default=None, help="Index directory (Lance + LadybugDB + cocoindex state)")
     p.add_argument("--embedding-model", type=str, default=None, help="Override SBERT_MODEL / YAML embedding.model")
     p.add_argument("--embedding-device", type=str, default=None, help="Override SBERT_DEVICE / YAML embedding.device")
 
@@ -536,7 +536,7 @@ def _cmd_reprocess(args: argparse.Namespace) -> int:
             _emit_reprocess_outcome(payload, selective_tty_mode="graph" if ok else None)
             return _reprocess_exit_code(payload)
 
-        import server  # lazy: pulls sentence_transformers/torch/lancedb/kuzu
+        import server  # lazy: pulls sentence_transformers/torch/lancedb/ladybug
 
         result = asyncio.run(
             server.run_refresh_pipeline(
@@ -715,7 +715,7 @@ def _cmd_unresolved_calls_list(args: argparse.Namespace) -> int:
     from ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
-        _emit({"success": False, "message": "Kuzu graph not found"})
+        _emit({"success": False, "message": "LadybugDB graph not found"})
         return 1
     graph = LadybugGraph.get()
     rows = graph.list_unresolved_call_sites(
@@ -736,7 +736,7 @@ def _cmd_unresolved_calls_stats(args: argparse.Namespace) -> int:
     from ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
-        _emit({"success": False, "message": "Kuzu graph not found"})
+        _emit({"success": False, "message": "LadybugDB graph not found"})
         return 1
     graph = LadybugGraph.get()
     buckets = graph.stats_unresolved_call_sites(by=args.by)
@@ -761,7 +761,7 @@ def _cmd_analyze_pr(args: argparse.Namespace) -> int:
     from ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
-        _emit({"success": False, "message": "Kuzu graph not found"})
+        _emit({"success": False, "message": "LadybugDB graph not found"})
         return 1
     graph = LadybugGraph.get()
     report = pr_analysis.analyze_pr_pipeline(graph, diff_text)
@@ -801,7 +801,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Create a fresh index from a Java repository.",
         description=(
             "First-time index creation. Refuses if the resolved index directory "
-            "already contains a Kuzu graph or Lance tables. Exit 2 on refusal."
+            "already contains a LadybugDB graph or Lance tables. Exit 2 on refusal."
         ),
     )
     _add_index_embedding_flags(init)
@@ -870,7 +870,7 @@ def build_parser() -> argparse.ArgumentParser:
     increment = subparsers.add_parser(
         "increment",
         help="Pick up changes since the last index update.",
-        description="Runs cocoindex catch-up and incremental Kuzu graph update. Use --vectors-only to skip graph update.",
+        description="Runs cocoindex catch-up and incremental LadybugDB graph update. Use --vectors-only to skip graph update.",
     )
     _add_index_embedding_flags(increment)
     _add_verbosity_flags(increment)
@@ -883,9 +883,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     reprocess = subparsers.add_parser(
         "reprocess",
-        help="Rebuild vectors and/or Kuzu (default: both full phases).",
+        help="Rebuild vectors and/or LadybugDB (default: both full phases).",
         description=(
-            "Default: full Lance reprocess (cocoindex --full-reprocess) then full Kuzu graph rebuild. "
+            "Default: full Lance reprocess (cocoindex --full-reprocess) then full LadybugDB graph rebuild. "
             "Use --vectors-only or --graph-only to run a single phase (mutually exclusive)."
         ),
     )
@@ -907,7 +907,7 @@ def build_parser() -> argparse.ArgumentParser:
     erase = subparsers.add_parser(
         "erase",
         help="Delete the index from disk.",
-        description="Runs cocoindex drop, removes Kuzu, and drops Lance tables. Requires --yes or TTY confirmation.",
+        description="Runs cocoindex drop, removes LadybugDB, and drops Lance tables. Requires --yes or TTY confirmation.",
     )
     _add_index_embedding_flags(erase)
     erase.add_argument("--yes", action="store_true", help="Confirm destructive deletion (required in CI)")

java_codebase_rag/install_data/agents/explorer-rag-enhanced.md

@@ -151,15 +151,15 @@ Simple types in parentheses; generics erased. No spaces after commas. No-arg: `(
 
 ### Shared NodeFilter
 
-For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`.
+For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`; invalid enum values (e.g. wrong case) are rejected earlier at the schema layer with the valid set listed.
 
 | Keys | Applies to |
 | ---- | ---------- |
 | `microservice`, `module` | All kinds |
 | `role`, `exclude_roles`, `annotation`, `capability`, `fqn_prefix`, `symbol_kind`, `symbol_kinds` | **symbol** |
 | `http_method`, `path_prefix`, `framework` | **route** |
-| `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
-| `producer_kind`, `topic_prefix` | **producer** |
+| `source_layer`, `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
+| `source_layer`, `producer_kind`, `topic_prefix` | **producer** |
 
 No wildcards in prefix fields — use `search(query=…)` for fuzzy text.
 

java_codebase_rag/install_data/skills/explore-codebase/SKILL.md

@@ -125,15 +125,15 @@ Use these strings **verbatim** in `neighbors(..., edge_types=[...])`.
 
 ### NodeFilter (`find`, `search.filter`, `neighbors.filter`)
 
-For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`.
+For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`; invalid enum values (e.g. wrong case) are rejected earlier at the schema layer with the valid set listed.
 
 | Applicable to | Keys |
 | ------------- | ---- |
 | All kinds | `microservice`, `module` |
 | **symbol** only | `role`, `exclude_roles`, `annotation`, `capability`, `fqn_prefix`, `symbol_kind`, `symbol_kinds` |
 | **route** only | `http_method`, `path_prefix`, `framework` |
-| **client** only | `client_kind`, `target_service`, `target_path_prefix`, `http_method` |
-| **producer** only | `producer_kind`, `topic_prefix` |
+| **client** only | `source_layer`, `client_kind`, `target_service`, `target_path_prefix`, `http_method` |
+| **producer** only | `source_layer`, `producer_kind`, `topic_prefix` |
 
 No wildcards in prefix fields — use `search(query=…)` for ranked text.
 
@@ -166,8 +166,8 @@ Exclude `DTO`, `OTHER`, `MAPPER` with `exclude_roles` when tracing business logi
 
 **Symbol kinds:** `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
 
-**Route frameworks:** `spring_mvc`, `webflux`, `kafka`, `rabbitmq`, `jms`, `stream`, `codebase_async_route`, …
-**Client kinds:** `feign_method`, `rest_template`, `web_client`. **Producer kinds:** `kafka_send`, `stream_bridge_send`.
+**Route frameworks:** `spring_mvc`, `webflux`. (Route *kinds* are `http_endpoint`, `http_consumer`, `kafka_topic`, `rabbit_queue`, `jms_destination`, `stream_binding`.)
+**Client kinds:** `feign_method`, `rest_template`, `web_client`. **Producer kinds:** `kafka_send`, `stream_bridge_send`. **Source layers (client/producer):** `builtin`, `layer_a_meta`, `layer_b_ann`, `layer_b_fqn`, `layer_c_source`.
 **Match types:** `cross_service`, `intra_service`, `ambiguous`, `phantom`, `unresolved`.
 
 ---

{java_codebase_rag-0.6.3.dist-info → java_codebase_rag-0.6.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.6.3
+Version: 0.6.4
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
 
 A graph-native code intelligence layer for Java microservice estates, exposed to LLM agents via the **Model Context Protocol (MCP)**.
 
-The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **Kuzu** (graph) alongside a **LanceDB** vector index (chunks), and exposes a deliberately small MCP surface — **five tools**: `search`, `find`, `describe`, `neighbors`, `resolve` — that collapse onto three primitive agent operations: **locate**, **inspect**, **walk**.
+The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **LadybugDB** (graph) alongside a **LanceDB** vector index (chunks), and exposes a deliberately small MCP surface — **five tools**: `search`, `find`, `describe`, `neighbors`, `resolve` — that collapse onto three primitive agent operations: **locate**, **inspect**, **walk**.
 
 > **What this MCP is:** a **GPS for code navigation**, not a reasoning engine.
 > Agents use a simple loop:
@@ -63,9 +63,9 @@ For the design rationale, the GPS metaphor, and the full ontology, see [`docs/pa
 
 Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real Java microservice estates: they find files but lose the structure that makes a Spring/JAX-RS system navigable. This project is built around five choices that target that gap.
 
-- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (Kuzu property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `DECLARES_ROUTE`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
+- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (LadybugDB property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `EXPOSES`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
 
-- **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `CLIENT`, `PRODUCER`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
+- **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `COMPONENT`, `CONFIG`, `ENTITY`, `CLIENT`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
 
 - **Ranking specialized for Java codebases.** The composite ranker is aware of role, microservice, and FQN structure — not a generic BM25. A search for `"chat ingress"` surfaces controllers before utility classes; a search scoped to one microservice doesn't drown in matches from the other 19. Defaults are tuned on the bank-chat fixture and exposed in `docs/CONFIGURATION.md` for per-repo overrides.
 
@@ -113,7 +113,7 @@ All indexing lifecycle commands (`init`, `increment`, `reprocess`, `install`, `u
 
 If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) for the full CLI reference.
 
-> **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
+> **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/LadybugDB schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
 
 ---
 
@@ -126,7 +126,7 @@ This repo ships a small multi-module Spring fixture under [`tests/bank-chat-syst
 git clone https://github.com/HumanBean17/java-codebase-rag
 cd java-codebase-rag
 
-# 2. Build the index (Lance vectors + Kuzu graph). First run downloads the
+# 2. Build the index (Lance vectors + LadybugDB graph). First run downloads the
 #    embedding model (~90 MB) and takes ~30-60s on the fixture.
 java-codebase-rag init --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
 
@@ -141,7 +141,7 @@ Smoke-test the index with two checks (`search_lancedb` ships with the package):
 JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
   python -m search_lancedb "chat ingress controller" --table java --limit 3
 
-# Vector + graph expansion — proves Kuzu is wired in
+# Vector + graph expansion — proves LadybugDB is wired in
 JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
   python -m search_lancedb "chat ingress controller" --table java --limit 3 \
     --graph-expand --expand-depth 2
@@ -241,8 +241,8 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | Setup | `install` | Interactive setup wizard: config, MCP registration, skill/agent deployment, indexing. |
 | Setup | `update` | Refresh shipped artifacts (skill, agent, MCP entry) + incremental Lance/graph catch-up after pip upgrade. |
 | Lifecycle | `init` | First-time index. Refuses if artifacts already exist. |
-| Lifecycle | `increment` | CocoIndex catch-up + incremental Kuzu update. `--vectors-only` for Lance only. |
-| Lifecycle | `reprocess` | Full Lance + Kuzu rebuild. `--vectors-only` / `--graph-only` for a single phase. |
+| Lifecycle | `increment` | CocoIndex catch-up + incremental LadybugDB update. `--vectors-only` for Lance only. |
+| Lifecycle | `reprocess` | Full Lance + LadybugDB rebuild. `--vectors-only` / `--graph-only` for a single phase. |
 | Lifecycle | `erase` | Delete index artifacts. Requires `--yes` or TTY confirm. |
 | Introspection | `meta`, `tables`, `diagnose-ignore`, `unresolved-calls` | Health, table listing, ignore-layer diagnostics, receiver-failure call sites. |
 | Analysis | `analyze-pr` | Blast-radius / risk from a unified diff. |
@@ -277,7 +277,7 @@ python3 -m venv .venv
 
 The `cocoindex` package powers lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation do not invoke it directly.
 
-The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `EMBEDDING_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
+The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `SBERT_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
 
 ---
 

{java_codebase_rag-0.6.3.dist-info → java_codebase_rag-0.6.4.dist-info}/RECORD

@@ -1,22 +1,22 @@
-ast_java.py,sha256=NQgZzstbsMq-PdowoD6r_ixJKxEEFzTP9xUzqDpiXeU,99661
+ast_java.py,sha256=Paee3ZV9G5iy8LqfkVq0Ah_1fV0k632oS5JPkiWzwB8,99206
 brownfield_events.py,sha256=yxXkKDgMb3VPtaiakGzncHM_EGnda8xIue6w90yYp8s,2055
-build_ast_graph.py,sha256=LNU1rIHwgEpbrWnWoywg4JdqbwwT4UKcx1iDay_GemM,156776
+build_ast_graph.py,sha256=vXWUuNC_k6-yKv6XawlHCXiC_dTNs1RoSKdZTXYBxgA,157374
 chunk_heuristics.py,sha256=aQk2NOKxzUdqoUAJUO3G3LE0MN_bYZWNLQ0tkmj5uts,1813
-graph_enrich.py,sha256=POT4LwSkTsrjUmP67bsm2UezUam70cunuPDYDh-v1Bs,63332
+graph_enrich.py,sha256=W_OQK7YRU1K8wi-vfrxZWUd-EErTqWx840UBrhVpNsM,62788
 index_common.py,sha256=HT6FKHFJ084eFvd3fR1j8z8gf4eWoPHVW8GXLpw464I,285
-java_index_flow_lancedb.py,sha256=7CS-sdbzhCkUsHfpCZ85uM7vy4aoZI8n-RowLocfiKc,20267
+java_index_flow_lancedb.py,sha256=HClxupO2uHpGw9GNVIDs24bjoCQzg3VLbOZoA0hE_Gc,23761
 java_index_v1_common.py,sha256=nF1KrSqboF_RRvWerG9knRRFmWwsrG_CvhgnsoZ8KqA,1154
 java_ontology.py,sha256=71bCLDNvMy0SpZPzSR5apJ0qJXNd6y5ggkLdBEw_PFo,16682
-ladybug_queries.py,sha256=912j9VAYDjcU4ReVorWQ6R4DZl0tteKic-Pqu0jyBS0,90837
+ladybug_queries.py,sha256=7vSP7WsUKQYXHFenBMlCdpUFed39h3oul-WRkf55YVc,90330
 mcp_hints.py,sha256=3swh05LSiWur3tm3-yssndBsLxIxFhy501kBtJI8jJ0,42509
-mcp_v2.py,sha256=o94GJI7j6dLJDIA3R_1ZiQhjzQfMAEW3etdeZYnHOUc,80637
-path_filtering.py,sha256=-oX16SYLWYwX9pcV1fu3vbVTIhY1GzFflT7J1E2tqPY,17122
-pr_analysis.py,sha256=3-5L8_G5XupdJsl9RN73Lq-ejPoK11B3m_VzAx2fGG8,18413
-search_lancedb.py,sha256=scG6HBUrsgIeSWFrGcLcGdhWv1qODOx4JOBMAlLDY_E,36793
+mcp_v2.py,sha256=S8PiVGDlyI7cvTmeMdQobhKUxWqKoY2YxXXr4pu9lQI,80348
+path_filtering.py,sha256=cN_znZRXIY1CfTIWlfiOrnNqafb2BZs00oDaqjTxmFE,17169
+pr_analysis.py,sha256=zrmZZD5yotJtM02Kif6_jgI_oeformOao793akp0N6Y,18394
+search_lancedb.py,sha256=ga_qySeCzA6hCibxUPXpCbTxW9mCjTdwirMhMhfNCz4,36801
 server.py,sha256=DcJwocSknBy0vwsUvYiC5hr-hrD_rRT-u9_DmuRTC9k,35035
 java_codebase_rag/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 java_codebase_rag/_fdlimit.py,sha256=WroFdfSNbcriKok6q8znTf74dqlznxea_1Fd5bHl_3o,1930
-java_codebase_rag/cli.py,sha256=uTCpgsE3gbDPSqPDNJeJ7hZu_MhyKYm4tqHIMkM67LM,38650
+java_codebase_rag/cli.py,sha256=TIrKNQMxu3_dSF2LXKsRKWY5RqRnSLQMrbKAoN4uQBQ,38698
 java_codebase_rag/cli_format.py,sha256=CT7-xdwZ0bMCdP68_UOwkvm-mnLluU3LutlM-mDNk60,1839
 java_codebase_rag/cli_progress.py,sha256=q6Wh97yzLGs1B8UFk_WAKivfQu7Y5RnUUE-T2YHWkIs,3237
 java_codebase_rag/config.py,sha256=bfwYI4R8PU9YV_M4r8-03iaUZ_0TW-qN_NuhIsDXy2M,18769
@@ -24,11 +24,11 @@ java_codebase_rag/installer.py,sha256=sXsHPo24aoDFoTr0D_vYLg0MFdGAV2wdL05FqRaul6
 java_codebase_rag/lance_optimize.py,sha256=25Rwj7HNO8F-35MxhFK6naqgbjd3H-T0zKb3pXB4H0s,9268
 java_codebase_rag/pipeline.py,sha256=ydNktEGL1YniAjJsr37yKBo_bGV4cN_LTGVTmmrsrZw,14688
 java_codebase_rag/progress.py,sha256=2IxdMALDM0wAQCyJrrfZ975zM_85C-4BfHxf4AtYifE,23212
-java_codebase_rag/install_data/agents/explorer-rag-enhanced.md,sha256=APl9d-No12qZNZLjU7mwNRwxHIgnT3ZtQZiD4clWlyU,14413
-java_codebase_rag/install_data/skills/explore-codebase/SKILL.md,sha256=pIM-Xdwq_fXkhhBJCdb-fA2nes5c_mMPcdUXb7Adyxo,12040
-java_codebase_rag-0.6.3.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
-java_codebase_rag-0.6.3.dist-info/METADATA,sha256=zDwRolQN2GTSexo7J2ngIqB-RnqmsnTZLRQ-lWuqBL4,17197
-java_codebase_rag-0.6.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-java_codebase_rag-0.6.3.dist-info/entry_points.txt,sha256=wsPZwot0Ui4JI3TIgW8LcbN8bNtKFbwQAlHAAJXfYgQ,117
-java_codebase_rag-0.6.3.dist-info/top_level.txt,sha256=syQgi8XPBwY2ws_NZ1uRCxTf_s41NpshwEHNdcdnk3A,245
-java_codebase_rag-0.6.3.dist-info/RECORD,,
+java_codebase_rag/install_data/agents/explorer-rag-enhanced.md,sha256=BkdQpBEWqSdvGHgbqMdRb5CWfEiFRJK4Dgqbyal3l6s,14551
+java_codebase_rag/install_data/skills/explore-codebase/SKILL.md,sha256=YkRnrM7Wh5E8raFjAW3RrN2V9-ov8upaGC3UdpSx6U8,12346
+java_codebase_rag-0.6.4.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
+java_codebase_rag-0.6.4.dist-info/METADATA,sha256=FR0VQ3dS_OS2v-n_zxOqcE0pZsHRvhDAiOGLse0pAoI,17242
+java_codebase_rag-0.6.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+java_codebase_rag-0.6.4.dist-info/entry_points.txt,sha256=wsPZwot0Ui4JI3TIgW8LcbN8bNtKFbwQAlHAAJXfYgQ,117
+java_codebase_rag-0.6.4.dist-info/top_level.txt,sha256=syQgi8XPBwY2ws_NZ1uRCxTf_s41NpshwEHNdcdnk3A,245
+java_codebase_rag-0.6.4.dist-info/RECORD,,

java_index_flow_lancedb.py

@@ -16,6 +16,7 @@ Usage:
 """
 from __future__ import annotations
 
+import asyncio
 import inspect
 import os
 import sys
@@ -50,7 +51,7 @@ from java_index_v1_common import (
 )
 from path_filtering import LayeredIgnore
 from ast_java import ONTOLOGY_VERSION, parse_java
-from graph_enrich import enrich_chunk
+from graph_enrich import collect_annotation_meta_chain, enrich_chunk, load_brownfield_overrides
 
 # Older cocoindex (e.g. 1.0.0a43) uses ``tracked=False``; newer releases renamed
 # the flag to ``detect_change`` (default False) and reject ``tracked``.
@@ -198,12 +199,12 @@ def _approximate_vectors_total(project_root: Path) -> int:
                 continue
             # Java: **/*.java
             if fn.endswith(".java"):
-                if not ignore.is_ignored(full)[0]:
+                if not ignore.is_ignored(full):
                     total += 1
                 continue
             # SQL: **/src/main/resources/db/migration/*.sql
             if fn.endswith(".sql") and "/db/migration/" in rel:
-                if not ignore.is_ignored(full)[0]:
+                if not ignore.is_ignored(full):
                     total += 1
                 continue
             # YAML: **/src/main/resources/application*.yml / .yaml
@@ -214,7 +215,7 @@ def _approximate_vectors_total(project_root: Path) -> int:
             # total below the actual done count. The ``rel``-based
             # ``"/src/main/resources/"`` gate stays (full path component).
             if fn.endswith((".yml", ".yaml")) and fn.startswith("application") and "/src/main/resources/" in rel:
-                if not ignore.is_ignored(full)[0]:
+                if not ignore.is_ignored(full):
                     total += 1
     return total
 
@@ -306,6 +307,40 @@ async def coco_lifespan(builder: coco.EnvironmentBuilder) -> AsyncIterator[None]
     yield
 
 
+def _parse_and_enrich_java(
+    content_bytes: bytes,
+    chunks: list[Any],
+    rel: str,
+    project_root: Path,
+) -> list[Any]:
+    """Parse one Java file and enrich every chunk, off the event loop.
+
+    Returns a list of :class:`graph_enrich.ChunkEnrichment` aligned 1:1 with
+    ``chunks``. Intended to run via ``asyncio.to_thread`` from
+    ``process_java_file`` (vectors perf lever #2): while the worker thread
+    parses + enriches, the event loop is free to drive other files and keep the
+    embedder's batching queue fed.
+
+    Thread-safety: ``parse_java`` uses a per-thread tree-sitter ``Parser``
+    (see ``ast_java._parser``), so it is safe to call concurrently from these
+    worker threads — including the transitive ``parse_java`` that ``enrich_chunk``
+    triggers via ``collect_annotation_meta_chain`` → ``_collect_annotation_decl_index``.
+    ``enrich_chunk`` is otherwise pure-Python over the now-immutable AST; its
+    ``lru_cache`` reads are thread-safe under the GIL.
+    """
+    ast = parse_java(content_bytes)
+    return [
+        enrich_chunk(
+            ast,
+            chunk_start_byte=ch.start.byte_offset,
+            chunk_end_byte=ch.end.byte_offset,
+            file_path=rel,
+            project_root=project_root,
+        )
+        for ch in chunks
+    ]
+
+
 @coco.fn(memo=True)
 async def process_java_file(
     file: localfs.File,
@@ -313,7 +348,7 @@ async def process_java_file(
 ) -> None:
     embedder = coco.use_context(EMBEDDER)
     project_root = coco.use_context(PROJECT_ROOT)
-    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve())[0]:
+    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve()):
         return
     try:
         content = await file.read_text()
@@ -326,6 +361,9 @@ async def process_java_file(
 
     language = detect_code_language(filename=file.file_path.path.name) or "text"
     cs, mn, ov = JAVA_CHUNK
+    # ``splitter.split`` stays inline: the module-level ``RecursiveSplitter``
+    # shares one Rust object, so keeping split on the event loop preserves its
+    # existing single-threaded access (no new cross-file concurrency hazard).
     chunks = splitter.split(
         content,
         cs,
@@ -335,18 +373,21 @@ async def process_java_file(
     )
     rel = file.file_path.path.as_posix()
     content_bytes = content.encode("utf-8", errors="replace")
-    ast = parse_java(content_bytes)
 
-    for ch in chunks:
+    # (vectors perf lever #2) parse + enrich off the event loop so the loop can
+    # keep the embedder's batching queue fed while this file is being parsed.
+    # parse_java is thread-safe (per-thread tree-sitter Parser in ast_java).
+    enrichments = await asyncio.to_thread(
+        _parse_and_enrich_java, content_bytes, chunks, rel, project_root
+    )
+    # (vectors perf lever #1) embed all chunks concurrently so the batched
+    # embedder groups them into one ``model.encode(...)`` (max_batch_size=64)
+    # instead of N serial batch-of-1 calls. Dominant win for ``increment``
+    # (few changed files → little cross-file concurrency → otherwise no batching).
+    embeddings = await asyncio.gather(*(embedder.embed(ch.text) for ch in chunks))
+
+    for ch, enrich, emb in zip(chunks, enrichments, embeddings):
         rs, re = chunk_key_range(ch)
-        enrich = enrich_chunk(
-            ast,
-            chunk_start_byte=ch.start.byte_offset,
-            chunk_end_byte=ch.end.byte_offset,
-            file_path=rel,
-            project_root=project_root,
-        )
-        emb = await embedder.embed(ch.text)
         table.declare_row(
             row=JavaLanceChunk(
                 id=str(uuid.uuid4()),
@@ -379,7 +420,7 @@ async def process_sql_file(
 ) -> None:
     embedder = coco.use_context(EMBEDDER)
     project_root = coco.use_context(PROJECT_ROOT)
-    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve())[0]:
+    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve()):
         return
     try:
         content = await file.read_text()
@@ -401,9 +442,11 @@ async def process_sql_file(
     )
     rel = file.file_path.path.as_posix()
 
-    for ch in chunks:
+    # (vectors perf lever #1) embed chunks concurrently → batched encode.
+    embeddings = await asyncio.gather(*(embedder.embed(ch.text) for ch in chunks))
+
+    for ch, emb in zip(chunks, embeddings):
         rs, re = chunk_key_range(ch)
-        emb = await embedder.embed(ch.text)
         table.declare_row(
             row=SqlLanceChunk(
                 id=str(uuid.uuid4()),
@@ -425,7 +468,7 @@ async def process_yaml_file(
 ) -> None:
     embedder = coco.use_context(EMBEDDER)
     project_root = coco.use_context(PROJECT_ROOT)
-    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve())[0]:
+    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve()):
         return
     try:
         content = await file.read_text()
@@ -448,9 +491,11 @@ async def process_yaml_file(
     )
     rel = file.file_path.path.as_posix()
 
-    for ch in chunks:
+    # (vectors perf lever #1) embed chunks concurrently → batched encode.
+    embeddings = await asyncio.gather(*(embedder.embed(ch.text) for ch in chunks))
+
+    for ch, emb in zip(chunks, embeddings):
         rs, re = chunk_key_range(ch)
-        emb = await embedder.embed(ch.text)
         table.declare_row(
             row=YamlLanceChunk(
                 id=str(uuid.uuid4()),
@@ -501,6 +546,26 @@ async def app_main() -> None:
     )
 
     project_root = coco.use_context(PROJECT_ROOT)
+    # Warm per-project enrichment caches ONCE on the event-loop thread, BEFORE
+    # coco.mount_each fans files into worker threads. collect_annotation_meta_chain
+    # and load_brownfield_overrides are lru_cached per (resolved) project root;
+    # without warming, the first wave of concurrent process_java_file worker
+    # threads each cold-miss and redundantly walk+parse the ENTIRE project (a
+    # thundering herd that would offset the embedding-batching win on large
+    # repos — perf lever #2 made enrich concurrent). With warming, every worker
+    # hits a populated cache (lru_cache reads are thread-safe). Key derivation
+    # mirrors enrich_chunk exactly so the warmed entries are the ones workers hit.
+    try:
+        load_brownfield_overrides(project_root)
+        try:
+            prs = str(Path(project_root).resolve())
+        except OSError:
+            prs = str(project_root)
+        collect_annotation_meta_chain(prs)
+    except Exception:
+        # Warm-up must never break indexing — a failure just means workers
+        # cold-miss lazily (the pre-warming behavior). Swallow and continue.
+        pass
     _ignore = LayeredIgnore(project_root)
     _walk_excludes = _ignore.cocoindex_excluded_patterns()
     # Emit ONE approximate total so the parent's renderer can show a determinate

ladybug_queries.py

@@ -1161,8 +1161,11 @@ class LadybugGraph:
         )
         return [str(r["id"]) for r in rows2 if r.get("id")]
 
-    def find_callers(
-        self, needle: str, *,
+    def _walk_calls(
+        self,
+        needle: str,
+        *,
+        side: str,
         depth: int = 1,
         limit: int = 100,
         min_confidence: float = 0.0,
@@ -1170,6 +1173,17 @@ class LadybugGraph:
         module: str | None = None,
         microservice: str | None = None,
     ) -> list[CallEdge]:
+        """BFS the CALLS graph outward from ``needle`` along one relationship end.
+
+        ``side="callers"`` treats the needle as the callee: the frontier matches
+        the ``callee`` end and discovered/expanded/external-filtered nodes are the
+        ``caller`` (src) end. ``side="callees"`` is the mirror. The two public
+        methods differ only in that orientation, so the BFS body is shared here.
+        """
+        if side == "callers":
+            scope_alias, frontier_end, discovered = "caller", "callee", "src"
+        else:
+            scope_alias, frontier_end, discovered = "callee", "caller", "dst"
         frontier = self._method_ids_for_call_graph_needle(needle, limit=max(limit, 50))
         if not frontier:
             return []
@@ -1182,8 +1196,8 @@ class LadybugGraph:
                 "frontier": list(frontier),
                 "minc": float(min_confidence),
             }
-            sc = _scope_filters("caller", module=module, microservice=microservice, params=params)
-            wh_parts = ["callee.id IN $frontier", "c.confidence >= $minc"]
+            sc = _scope_filters(scope_alias, module=module, microservice=microservice, params=params)
+            wh_parts = [f"{frontier_end}.id IN $frontier", "c.confidence >= $minc"]
             wh_parts.extend(sc)
             wh = " AND ".join(wh_parts)
             q = (
@@ -1197,16 +1211,19 @@ class LadybugGraph:
             next_frontier: list[str] = []
             for row in self._rows(q, params):
                 ce = _row_to_call_edge(row)
-                # Filter only discovered callers (src). Needle may be external
-                # (e.g. java.util.List#add) while still listing internal callers.
-                if exclude_external and _is_external_fqn(ce.src.fqn):
+                # The needle itself may be external (e.g. java.util.List#add);
+                # filter only the discovered end so internal callers/callees
+                # that touch it are still surfaced.
+                disc_fqn = ce.src.fqn if discovered == "src" else ce.dst.fqn
+                disc_id = ce.src.id if discovered == "src" else ce.dst.id
+                if exclude_external and _is_external_fqn(disc_fqn):
                     continue
                 key = (ce.src.id, ce.dst.id, ce.call_site_line, ce.call_site_byte)
                 if key in seen:
                     continue
                 seen.add(key)
                 out.append(ce)
-                next_frontier.append(ce.src.id)
+                next_frontier.append(disc_id)
                 if len(out) >= limit:
                     return out
             frontier = list(dict.fromkeys(next_frontier))
@@ -1214,6 +1231,21 @@ class LadybugGraph:
                 break
         return out
 
+    def find_callers(
+        self, needle: str, *,
+        depth: int = 1,
+        limit: int = 100,
+        min_confidence: float = 0.0,
+        exclude_external: bool = True,
+        module: str | None = None,
+        microservice: str | None = None,
+    ) -> list[CallEdge]:
+        return self._walk_calls(
+            needle, side="callers", depth=depth, limit=limit,
+            min_confidence=min_confidence, exclude_external=exclude_external,
+            module=module, microservice=microservice,
+        )
+
     def find_callees(
         self, needle: str, *,
         depth: int = 1,
@@ -1223,49 +1255,11 @@ class LadybugGraph:
         module: str | None = None,
         microservice: str | None = None,
     ) -> list[CallEdge]:
-        frontier = self._method_ids_for_call_graph_needle(needle, limit=max(limit, 50))
-        if not frontier:
-            return []
-        caller_proj = ", ".join(f"caller.{c} AS caller_{c}" for c in _SYM_COLS)
-        callee_proj = ", ".join(f"callee.{c} AS callee_{c}" for c in _SYM_COLS)
-        out: list[CallEdge] = []
-        seen: set[tuple[str, str, int, int]] = set()
-        for _ in range(max(1, int(depth))):
-            params: dict[str, Any] = {
-                "frontier": list(frontier),
-                "minc": float(min_confidence),
-            }
-            sc = _scope_filters("callee", module=module, microservice=microservice, params=params)
-            wh_parts = ["caller.id IN $frontier", "c.confidence >= $minc"]
-            wh_parts.extend(sc)
-            wh = " AND ".join(wh_parts)
-            q = (
-                f"MATCH (caller:Symbol)-[c:CALLS]->(callee:Symbol) WHERE {wh} "
-                f"RETURN {caller_proj}, {callee_proj}, "
-                f"c.call_site_line AS call_site_line, c.call_site_byte AS call_site_byte, "
-                f"c.arg_count AS arg_count, c.confidence AS confidence, c.strategy AS strategy, "
-                f"c.source AS source, c.resolved AS resolved "
-                f"LIMIT {int(limit) * 8}"
-            )
-            next_frontier: list[str] = []
-            for row in self._rows(q, params):
-                ce = _row_to_call_edge(row)
-                # Filter only discovered callees (dst). Needle may be external while
-                # still listing non-external outbound calls when any exist.
-                if exclude_external and _is_external_fqn(ce.dst.fqn):
-                    continue
-                key = (ce.src.id, ce.dst.id, ce.call_site_line, ce.call_site_byte)
-                if key in seen:
-                    continue
-                seen.add(key)
-                out.append(ce)
-                next_frontier.append(ce.dst.id)
-                if len(out) >= limit:
-                    return out
-            frontier = list(dict.fromkeys(next_frontier))
-            if not frontier:
-                break
-        return out
+        return self._walk_calls(
+            needle, side="callees", depth=depth, limit=limit,
+            min_confidence=min_confidence, exclude_external=exclude_external,
+            module=module, microservice=microservice,
+        )
 
     def expand_methods(
         self, fqns: list[str], *, depth: int = 1,

mcp_v2.py

@@ -817,7 +817,7 @@ def _merge_overrides_edge_summary(
     """Reconcile `OVERRIDES` with `override_axis_rollup_for` without clobbering stored `in`.
 
     Rollup rows reuse the ``OVERRIDES`` key for dispatch-up counts only (``in`` is always
-    zero there). Stored ``[:OVERRIDES]`` edges contribute real ``in``/``out`` from Kuzu;
+    zero there). Stored ``[:OVERRIDES]`` edges contribute real ``in``/``out`` from LadybugDB;
     merge per direction with ``max`` so inbound override edges stay visible.
     """
     roll = _incident_counts(summary_after_rollups.get("OVERRIDES"))
@@ -1095,9 +1095,9 @@ def describe_v2(
         has_id = bool(id and str(id).strip())
         has_fqn = bool(fqn and str(fqn).strip())
         if not has_id and not has_fqn:
-            return DescribeOutput(success=False, message="id or fqn required", hints=[])
+            return DescribeOutput(success=False, message="id or fqn required")
         if has_id and str(id).strip().startswith("ucs:"):
-            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE, hints=[])
+            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE)
         hint_message: str | None = None
         node_id: str
         if has_id:
@@ -1109,7 +1109,7 @@ def describe_v2(
                 {"fqn": fqn_val},
             )
             if not rows:
-                return DescribeOutput(success=False, message=f"No Symbol found for fqn='{fqn_val}'", hints=[])
+                return DescribeOutput(success=False, message=f"No Symbol found for fqn='{fqn_val}'")
             node_id = str(rows[0]["id"] or "")
             if len(rows) > 1:
                 hint_message = (
@@ -1784,7 +1784,7 @@ def neighbors_v2(
             )
         except ValueError as exc:
             _log_fail_loud("edge_filter")
-            return NeighborsOutput(success=False, message=str(exc), hints=[], requested_edge_types=[])
+            return NeighborsOutput(success=False, message=str(exc), requested_edge_types=[])
         if include_unresolved and ef is not None:
             return NeighborsOutput(
                 success=False,
@@ -1792,21 +1792,18 @@ def neighbors_v2(
                     "include_unresolved=True is incompatible with edge_filter; "
                     "UnresolvedCallSite rows have no edge attributes to filter on"
                 ),
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if include_unresolved and requested_edge_types != ["CALLS"]:
             return NeighborsOutput(
                 success=False,
                 message="include_unresolved requires edge_types=['CALLS']",
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if include_unresolved and direction != "out":
             return NeighborsOutput(
                 success=False,
                 message='include_unresolved requires direction="out"',
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if ef and (err := _edgefilter_applicability_error(requested_edge_types, ef)):
@@ -1814,17 +1811,15 @@ def neighbors_v2(
             return NeighborsOutput(
                 success=False,
                 message=err,
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if nf and (err := _validate_no_wildcards(nf)):
             _log_fail_loud("wildcard")
-            return NeighborsOutput(success=False, message=err, hints=[], requested_edge_types=[])
+            return NeighborsOutput(success=False, message=err, requested_edge_types=[])
         if composed_keys and direction != "out":
             return NeighborsOutput(
                 success=False,
                 message='Composed edge types require direction="out"',
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         use_calls_path = flat_labels == ["CALLS"] and not composed_keys
@@ -1849,7 +1844,6 @@ def neighbors_v2(
                     return NeighborsOutput(
                         success=False,
                         message=axis_msg,
-                        hints=[],
                         requested_edge_types=requested_edge_types,
                     )
                 origin_row = _load_node_record(g, origin_id, "symbol")
@@ -1865,7 +1859,6 @@ def neighbors_v2(
                     return NeighborsOutput(
                         success=False,
                         message=err,
-                        hints=[],
                         requested_edge_types=requested_edge_types,
                     )
             if use_calls_path:
@@ -1891,7 +1884,6 @@ def neighbors_v2(
                     return NeighborsOutput(
                         success=False,
                         message=str(exc),
-                        hints=[],
                         requested_edge_types=requested_edge_types,
                     )
                 if (
@@ -1904,7 +1896,7 @@ def neighbors_v2(
                 results.extend(origin_edges)
                 continue
             if flat_labels:
-                # Kuzu 0.11.x can drop `label(e) IN $list` in WHERE; use OR of scalar equalities.
+                # Some Cypher binders can drop `label(e) IN $list` in WHERE; use OR of scalar equalities.
                 label_params = [f"l{i}" for i in range(len(flat_labels))]
                 label_predicate = "(" + " OR ".join(f"label(e) = ${name}" for name in label_params) + ")"
                 q_params = {"id": origin_id, **dict(zip(label_params, flat_labels, strict=True))}
@@ -1941,7 +1933,7 @@ def neighbors_v2(
                     if nf and (err := _nodefilter_applicability_error(other_kind, nf)):
                         _log_fail_loud("applicability")
                         return NeighborsOutput(
-                            success=False, message=err, hints=[], requested_edge_types=[]
+                            success=False, message=err, requested_edge_types=[]
                         )
                     if not _node_matches_filter(other_kind, other_rec, nf):
                         continue
@@ -1968,7 +1960,7 @@ def neighbors_v2(
                     if nf and (err := _nodefilter_applicability_error(other_kind, nf)):
                         _log_fail_loud("applicability")
                         return NeighborsOutput(
-                            success=False, message=err, hints=[], requested_edge_types=[]
+                            success=False, message=err, requested_edge_types=[]
                         )
                     if not _node_matches_filter(other_kind, other_rec, nf):
                         continue

path_filtering.py

@@ -342,24 +342,22 @@ class LayeredIgnore:
         )
         return mega, GitIgnoreSpec.from_lines(mega), meta
 
-    def is_ignored(self, path: Path) -> tuple[bool, IgnoreLayer | None]:
-        """Return whether ``path`` is ignored and which layer last matched."""
+    def is_ignored(self, path: Path) -> bool:
+        """Return whether ``path`` is ignored by any configured layer.
+
+        Boolean-only fast path for the per-file index walk. It deliberately does
+        not compute *which* layer/source last matched: that attribution is
+        O(rules²) via :func:`_winning_row` (one ``GitIgnoreSpec`` rebuild per
+        rule prefix) and is only needed for ``diagnose-ignore``, so it lives in
+        :meth:`diagnose_dict` and is never paid on the hot path.
+        """
         rel = self._rel_project(path)
         if rel is None:
-            return False, None
-        mega, spec, meta = self._mega(rel)
+            return False
+        mega, spec, _ = self._mega(rel)
         if not mega:
-            return False, None
-        ignored = spec.match_file(rel)
-        if not ignored:
-            return False, None
-        src, fp, ln, _pat = _winning_row(rel, mega, meta)
-        return True, IgnoreLayer(
-            root=self.project_root,
-            spec=spec,
-            source=src,
-            ignore_file=fp,
-        )
+            return False
+        return spec.match_file(rel)
 
     def diagnose(self, path: Path) -> str:
         """Human-readable, multi-line explanation of the ignore decision."""
@@ -466,7 +464,6 @@ def iter_java_source_files(
             if not fn.endswith(".java"):
                 continue
             p = Path(dirpath) / fn
-            ign, _ = ignore_ctx.is_ignored(p)
-            if ign:
+            if ignore_ctx.is_ignored(p):
                 continue
             yield p

pr_analysis.py

@@ -152,7 +152,7 @@ def _resolve_graph_filename(
     *,
     ambiguity_notes: list[str] | None = None,
 ) -> str | None:
-    """Map a diff path to `Symbol.filename` values stored in Kuzu."""
+    """Map a diff path to `Symbol.filename` values stored in LadybugDB."""
     variants = {_strip_ab_prefix(path)}
     for v in list(variants):
         if v.startswith("./"):
@@ -362,7 +362,7 @@ def _is_public_interface_method(graph: Any, sym: SymbolHit) -> bool:
 
 
 def _route_ids_for_symbol(graph: Any, symbol_id: str) -> list[str]:
-    # Note: Kuzu rejects `ORDER BY r.id` together with `RETURN DISTINCT r.id` (binder loses `r`).
+    # Note: LadybugDB rejects `ORDER BY r.id` together with `RETURN DISTINCT r.id` (binder loses `r`).
     q = (
         "MATCH (s:Symbol)-[e:EXPOSES]->(r:Route) WHERE s.id = $sid "
         "RETURN r.id AS id ORDER BY id"
@@ -384,7 +384,6 @@ def compute_risk(graph: Any, changed: list[ChangedSymbol]) -> PrRiskReport:
     bump (up to +1.0) after normalization so they influence rank while
     preserving the public scalar contract.
     """
-    notes: list[str] = []
     blast_by: dict[str, int] = {}
     blast_total = 0
     routes: list[str] = []
@@ -495,7 +494,7 @@ def compute_risk(graph: Any, changed: list[ChangedSymbol]) -> PrRiskReport:
         routes_touched=routes,
         risk_score=score,
         risk_band=band,
-        notes=notes,
+        notes=[],
     )
 
 

search_lancedb.py

@@ -677,8 +677,8 @@ def _graph_expand_merge(
     expand_depth: int,
     ladybug_path: str | None,
 ) -> list[dict]:
-    """Expand vector top-k through the Kuzu graph and fuse (RRF) with the original list."""
-    # Lazy import so the module works without kuzu installed when graph_expand=False.
+    """Expand vector top-k through the LadybugDB graph and fuse (RRF) with the original list."""
+    # Lazy import so the module works without ladybug installed when graph_expand=False.
     try:
         from ladybug_queries import LadybugGraph
     except Exception: