java-codebase-rag 0.5.2__py3-none-any.whl → 0.6.0__py3-none-any.whl

java_codebase_rag/pipeline.py

@@ -1,6 +1,7 @@
 """Subprocess helpers for cocoindex + graph builder (no heavy ML imports at import time)."""
 from __future__ import annotations
 
+import asyncio
 import os
 import shutil
 import subprocess
@@ -11,6 +12,7 @@ from pathlib import Path
 
 from java_codebase_rag.cli_format import Spinner, is_noise_line, stderr_is_tty
 from java_codebase_rag.cli_progress import emit_vectors_finish, emit_vectors_start
+from java_codebase_rag.config import cocoindex_subprocess_env_defaults
 
 COCOINDEX_TARGET = "java_index_flow_lancedb.py:JavaCodeIndexLance"
 
@@ -110,6 +112,57 @@ def run_cocoindex_update(
     quiet: bool,
     verbose: bool = True,
     lance_project_root: Path | None = None,
+) -> subprocess.CompletedProcess[str]:
+    result = _run_cocoindex_update_impl(
+        env,
+        full_reprocess=full_reprocess,
+        quiet=quiet,
+        verbose=verbose,
+        lance_project_root=lance_project_root,
+    )
+    # After cocoindex returns exit 0 there are no concurrent writers, so this
+    # is the safe window to compact the Lance tables. The flow disabled its
+    # in-flight background optimize (see java_index_flow_lancedb.py), making
+    # this serialized pass the sole optimizer. Optimize failure does not flip
+    # the cocoindex CompletedProcess (a successful index is still usable, just
+    # not compacted); the outcome is logged to stderr only.
+    if result.returncode == 0:
+        _maybe_run_serialized_optimize(env, quiet=quiet)
+    return result
+
+
+def _maybe_run_serialized_optimize(env: dict[str, str], *, quiet: bool) -> None:
+    """Resolve the index dir from *env* and run the serialized Lance optimize.
+
+    The flow's lifespan reads ``JAVA_CODEBASE_RAG_INDEX_DIR`` (set by the CLI /
+    config.subprocess_env), so it is guaranteed present when cocoindex ran.
+    If it is somehow absent we skip optimize with a stderr warning rather than
+    crash — a successful index is still searchable un-compacted.
+    """
+    idx_raw = env.get("JAVA_CODEBASE_RAG_INDEX_DIR", "").strip()
+    if not idx_raw:
+        print(
+            "java-codebase-rag: optimize skipped — JAVA_CODEBASE_RAG_INDEX_DIR "
+            "not set in subprocess env",
+            file=sys.stderr,
+        )
+        return
+    try:
+        from java_codebase_rag.lance_optimize import optimize_lance_tables
+
+        asyncio.run(optimize_lance_tables(Path(idx_raw), quiet=quiet))
+    except Exception as exc:
+        # Never crash the CLI on an optimize failure — surface on stderr only.
+        print(f"java-codebase-rag: optimize failed: {exc}", file=sys.stderr)
+
+
+def _run_cocoindex_update_impl(
+    env: dict[str, str],
+    *,
+    full_reprocess: bool,
+    quiet: bool,
+    verbose: bool = True,
+    lance_project_root: Path | None = None,
 ) -> subprocess.CompletedProcess[str]:
     exe = cocoindex_bin()
     if not exe.is_file():
@@ -128,6 +181,11 @@ def run_cocoindex_update(
             stdout="",
             stderr=f"java_index_flow_lancedb.py not found under {bd}",
         )
+    # Cap CocoIndex concurrency to avoid EMFILE ("too many open files") under
+    # default OS fd limits. See: https://github.com/HumanBean17/java-codebase-rag/issues/306
+    env = env.copy()
+    for _k, _v in cocoindex_subprocess_env_defaults().items():
+        env.setdefault(_k, _v)
     cmd: list[str] = [str(exe), "update", COCOINDEX_TARGET]
     if full_reprocess:
         cmd.extend(["--full-reprocess", "-f"])
@@ -197,7 +255,7 @@ def run_cocoindex_drop(env: dict[str, str], *, quiet: bool) -> subprocess.Comple
 def run_build_ast_graph(
     *,
     source_root: Path,
-    kuzu_path: Path,
+    ladybug_path: Path,
     verbose: bool,
     quiet: bool = False,
     env: dict[str, str] | None = None,
@@ -215,8 +273,8 @@ def run_build_ast_graph(
         str(builder),
         "--source-root",
         str(source_root),
-        "--kuzu-path",
-        str(kuzu_path),
+        "--ladybug-path",
+        str(ladybug_path),
     ]
     # Three-tier: --quiet (silent) / default (filtered progress) / --verbose (raw).
     # Default passes --verbose so the builder emits per-pass progress lines,
@@ -250,7 +308,7 @@ def run_build_ast_graph(
 def run_incremental_graph(
     *,
     source_root: Path,
-    kuzu_path: Path,
+    ladybug_path: Path,
     verbose: bool,
     quiet: bool = False,
     env: dict[str, str] | None = None,
@@ -269,8 +327,8 @@ def run_incremental_graph(
         str(builder),
         "--source-root",
         str(source_root),
-        "--kuzu-path",
-        str(kuzu_path),
+        "--ladybug-path",
+        str(ladybug_path),
         "--incremental",
     ]
     # Three-tier: --quiet (silent) / default (filtered progress) / --verbose (raw).

{java_codebase_rag-0.5.2.dist-info → java_codebase_rag-0.6.0.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.5.2
+Version: 0.6.0
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumanBean17/java-codebase-rag
 Project-URL: Repository, https://github.com/HumanBean17/java-codebase-rag
 Project-URL: Issues, https://github.com/HumanBean17/java-codebase-rag/issues
-Keywords: mcp,java,rag,code-search,graph,lancedb,kuzu
+Keywords: mcp,java,rag,code-search,graph,lancedb,ladybug
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -19,7 +19,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cocoindex[lancedb]<2,>=1.0.0a43
-Requires-Dist: kuzu<0.12,>=0.11.3
+Requires-Dist: ladybug<0.18,>=0.17.1
 Requires-Dist: lancedb<0.31,>=0.25.3
 Requires-Dist: mcp<2,>=1.27.0
 Requires-Dist: numpy<2.5,>=1.26.4
@@ -103,7 +103,7 @@ java-codebase-rag install
 java-codebase-rag install --non-interactive --agent claude-code
 ```
 
-After `pip install --upgrade java-codebase-rag`, run `java-codebase-rag update` to refresh shipped artifacts.
+After `pip install --upgrade java-codebase-rag`, run `java-codebase-rag update` to refresh shipped artifacts and catch up the index (Lance + graph).
 
 ### Manual registration
 
@@ -235,7 +235,7 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | Group | Subcommand | What it does |
 |---|---|---|
 | Setup | `install` | Interactive setup wizard: config, MCP registration, skill/agent deployment, indexing. |
-| Setup | `update` | Refresh shipped artifacts (skill, agent, MCP entry) after pip upgrade. |
+| 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. |

java_codebase_rag-0.6.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+ast_java.py,sha256=TMesuv4SYqzkwfKxf_Pps0KaPLZNZOrhU8mL20bwqeQ,98882
+brownfield_events.py,sha256=yxXkKDgMb3VPtaiakGzncHM_EGnda8xIue6w90yYp8s,2055
+build_ast_graph.py,sha256=GNbjiIAwsXaJQ9Je6gbR-dB9SbnaLThya2pEw3tggQs,152396
+chunk_heuristics.py,sha256=aQk2NOKxzUdqoUAJUO3G3LE0MN_bYZWNLQ0tkmj5uts,1813
+graph_enrich.py,sha256=POT4LwSkTsrjUmP67bsm2UezUam70cunuPDYDh-v1Bs,63332
+index_common.py,sha256=HT6FKHFJ084eFvd3fR1j8z8gf4eWoPHVW8GXLpw464I,285
+java_index_flow_lancedb.py,sha256=MH9iTNF6HDHDTt5Jn7TOVE5hQ4WUPNt7PlQoh1tuh9o,13212
+java_index_v1_common.py,sha256=nF1KrSqboF_RRvWerG9knRRFmWwsrG_CvhgnsoZ8KqA,1154
+java_ontology.py,sha256=FcnOq1XWhUP03OfnTkRStslqrNyukzUKH7VNuK6Bme4,16425
+ladybug_queries.py,sha256=912j9VAYDjcU4ReVorWQ6R4DZl0tteKic-Pqu0jyBS0,90837
+mcp_hints.py,sha256=3swh05LSiWur3tm3-yssndBsLxIxFhy501kBtJI8jJ0,42509
+mcp_v2.py,sha256=64UDrQ27hAQtlz3pFp9A3Xlk95bUjYZ4VBscsyAPCIY,79116
+path_filtering.py,sha256=-oX16SYLWYwX9pcV1fu3vbVTIhY1GzFflT7J1E2tqPY,17122
+pr_analysis.py,sha256=3-5L8_G5XupdJsl9RN73Lq-ejPoK11B3m_VzAx2fGG8,18413
+search_lancedb.py,sha256=scG6HBUrsgIeSWFrGcLcGdhWv1qODOx4JOBMAlLDY_E,36793
+server.py,sha256=uGKT0PdM-bVrzIsfbxF6ZuHGcuRMSSlvkJk0e7Ff43Y,30556
+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=a5IFLWAsh77mfLv1Z9OdpvLaYvj4i0KR3_kLtL-ans8,34156
+java_codebase_rag/cli_format.py,sha256=arU7P9W6Fvm7X_wzR1wJ8EfyxK1rDP_ESEhdA0ub4Mo,2579
+java_codebase_rag/cli_progress.py,sha256=9jCqEagYOXs32SYVA31_sOCrONvYy7cl1CrdBD2Pg44,3168
+java_codebase_rag/config.py,sha256=u4OomvglTWHUmMpcxN8wPRnRGfXVp3qK_GJ5pY96O98,16267
+java_codebase_rag/installer.py,sha256=DlBuVVWbHXgcjaQkuXUeT9fNdmk7XZefVT3zzw47k18,45965
+java_codebase_rag/lance_optimize.py,sha256=MzACYlgwxmkJCK64qQLyIAdizSq5BARqaMYSZONlc1I,6069
+java_codebase_rag/pipeline.py,sha256=UcgluFAW9Ghnas8u40x45bVic0mQv6rjzcliDKsnYJI,11936
+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.0.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
+java_codebase_rag-0.6.0.dist-info/METADATA,sha256=GoMO3zFTb98w4rVV5SMXpcLK-irlDs7aUH0wBGlv5cQ,16887
+java_codebase_rag-0.6.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+java_codebase_rag-0.6.0.dist-info/entry_points.txt,sha256=mVVQJa0n73OWfhHXYCDoPRrWin_LJhH2Rn0CkJ2iax4,101
+java_codebase_rag-0.6.0.dist-info/top_level.txt,sha256=syQgi8XPBwY2ws_NZ1uRCxTf_s41NpshwEHNdcdnk3A,245
+java_codebase_rag-0.6.0.dist-info/RECORD,,

{java_codebase_rag-0.5.2.dist-info → java_codebase_rag-0.6.0.dist-info}/top_level.txt

@@ -8,7 +8,7 @@ java_codebase_rag
 java_index_flow_lancedb
 java_index_v1_common
 java_ontology
-kuzu_queries
+ladybug_queries
 mcp_hints
 mcp_v2
 path_filtering

java_index_flow_lancedb.py

@@ -4,7 +4,7 @@ CocoIndex 1.0 app: index Java, Flyway SQL, and YAML into LanceDB.
 LanceDB requires a single primary key per table; each chunk gets a UUID `id`.
 
 Environment:
-  JAVA_CODEBASE_RAG_INDEX_DIR — Lance tables + Kuzu + cocoindex state (default: ./.java-codebase-rag)
+  JAVA_CODEBASE_RAG_INDEX_DIR — Lance tables + LadybugDB + cocoindex state (default: ./.java-codebase-rag)
   JAVA_CODEBASE_RAG_SOURCE_ROOT — Java repo root for indexing (optional; else cocoindex cwd)
   SBERT_MODEL / SBERT_DEVICE — embedding (optional; YAML also supported via java-codebase-rag CLI)
 
@@ -36,6 +36,7 @@ from cocoindex.ops.text import RecursiveSplitter, detect_code_language
 from cocoindex.resources.file import PatternFilePathMatcher
 
 from java_codebase_rag.config import resolved_sbert_model_for_process_env
+from java_codebase_rag.lance_optimize import LANCE_TABLE_NAMES
 from java_index_v1_common import (
     JAVA_CHUNK,
     SBERT_MODEL,
@@ -68,6 +69,20 @@ else:
 
 splitter = RecursiveSplitter()
 
+# cocoindex 1.0.7 schedules ``table.optimize()`` (a LanceDB Rewrite/compaction
+# transaction) as a *background* asyncio task after every
+# ``num_transactions_before_optimize`` mutation batches (default 50). That
+# background Rewrite races the concurrent ``table.delete()`` (Delete)
+# transactions emitted by later batches, and LanceDB does not allow a Rewrite
+# to commit concurrently with a Delete (upstream lancedb#1504), which floods
+# stderr with "Retryable commit conflict ... preempted by concurrent
+# transaction Delete". Setting this effectively to infinity disables the
+# in-flight background optimize; the serialized post-flow optimize in
+# ``lance_optimize.optimize_lance_tables`` then compacts the table with no
+# concurrent writers. ``optimize()`` is pure maintenance (compact/prune/index);
+# upsert/delete correctness via merge_insert does not depend on it.
+_NUM_TXN_BEFORE_OPTIMIZE = 10**12
+
 
 @dataclass
 class JavaLanceChunk:
@@ -317,8 +332,9 @@ async def app_main() -> None:
     )
     java_table = await lancedb.mount_table_target(
         LANCE_DB,
-        "javacodeindex_java_code",
+        LANCE_TABLE_NAMES[0],
         java_schema,
+        num_transactions_before_optimize=_NUM_TXN_BEFORE_OPTIMIZE,
     )
 
     sql_schema = await lancedb.TableSchema.from_class(
@@ -327,8 +343,9 @@ async def app_main() -> None:
     )
     sql_table = await lancedb.mount_table_target(
         LANCE_DB,
-        "sqlschemaindex_sql_schema",
+        LANCE_TABLE_NAMES[1],
         sql_schema,
+        num_transactions_before_optimize=_NUM_TXN_BEFORE_OPTIMIZE,
     )
 
     yaml_schema = await lancedb.TableSchema.from_class(
@@ -337,8 +354,9 @@ async def app_main() -> None:
     )
     yaml_table = await lancedb.mount_table_target(
         LANCE_DB,
-        "yamlconfigindex_yaml_config",
+        LANCE_TABLE_NAMES[2],
         yaml_schema,
+        num_transactions_before_optimize=_NUM_TXN_BEFORE_OPTIMIZE,
     )
 
     project_root = coco.use_context(PROJECT_ROOT)

java_ontology.py

@@ -141,7 +141,7 @@ Cardinality = Literal["many_to_many", "many_to_one", "one_to_many", "one_to_one"
 @dataclass(frozen=True)
 class EdgeAttr:
     name: str
-    kuzu_type: str
+    graph_type: str
     purpose: str
 
 

kuzu_queries.py → ladybug_queries.py

@@ -1,9 +1,9 @@
-"""Read-only Cypher helpers over the Kuzu AST graph built by `build_ast_graph.py`.
+"""Read-only Cypher helpers over the Ladybug AST graph built by `build_ast_graph.py`.
 
-Each function opens a Kuzu connection on demand and returns plain JSON-ish dicts
+Each function opens a Ladybug connection on demand and returns plain JSON-ish dicts
 so the MCP server can serialize them without further mapping.
 
-The Kuzu database is opened read-only and cached per-process. This module is
+The Ladybug database is opened read-only and cached per-process. This module is
 intentionally dependency-light: nothing here imports LanceDB or sentence-transformers.
 
 Cypher pitfalls (see also ``AGENTS.md``): avoid ``label(e) IN $list`` in ``WHERE`` for
@@ -16,17 +16,37 @@ from __future__ import annotations
 import json
 import logging
 import os
+import re
 import threading
 from dataclasses import asdict, dataclass
 from pathlib import Path
 from typing import Any, Literal
 
-import kuzu
+import ladybug
 
 from ast_java import ONTOLOGY_VERSION as _ONTOLOGY_VERSION
 
 log = logging.getLogger(__name__)
 
+
+def _parse_ladybug_json(raw: str | None) -> dict[str, Any]:
+    """Parse JSON from LadybugDB which returns unquoted keys like {key: value}."""
+    if not raw:
+        return {}
+    # LadybugDB returns JSON without quotes around keys: {packages: 1, files: 2}
+    # Convert to standard JSON: {"packages": 1, "files": 2}
+    # This regex matches word characters followed by ':' at the start of a key
+    quoted = re.sub(r'(\w+):', r'"\1":', raw)
+    try:
+        return json.loads(quoted)
+    except Exception:
+        try:
+            # Fallback: try parsing as-is (for standard JSON)
+            return json.loads(raw)
+        except Exception:
+            log.warning("Failed to parse counts_json: %s", raw[:100])
+            return {}
+
 # Composed describe / neighbors dot-keys (not stored graph edge labels).
 _MEMBER_EDGE_COMPOSED_REL_MAP: tuple[tuple[str, str], ...] = (
     ("DECLARES.DECLARES_CLIENT", "DECLARES_CLIENT"),
@@ -46,7 +66,7 @@ OVERRIDE_AXIS_COMPOSED_EDGE_TYPES: frozenset[str] = frozenset(_OVERRIDE_AXIS_COM
 
 
 def _coerce_id_list(raw: Any) -> list[str]:
-    """Normalize Kuzu ``collect(DISTINCT ...)`` list results to string ids."""
+    """Normalize Ladybug ``collect(DISTINCT ...)`` list results to string ids."""
     if raw is None:
         return []
     if isinstance(raw, list):
@@ -56,8 +76,8 @@ def _coerce_id_list(raw: Any) -> list[str]:
 
 
 __all__ = [
-    "KuzuGraph",
-    "resolve_kuzu_path",
+    "LadybugGraph",
+    "resolve_ladybug_path",
     "SymbolHit",
     "EdgeHit",
     "CallEdge",
@@ -68,14 +88,14 @@ __all__ = [
 ]
 
 
-def resolve_kuzu_path(explicit: str | None = None) -> str:
-    """Resolve the Kuzu DB path the same way the builder does."""
+def resolve_ladybug_path(explicit: str | None = None) -> str:
+    """Resolve the Ladybug DB path the same way the builder does."""
     if explicit:
         return str(Path(explicit).expanduser())
     idx = os.environ.get("JAVA_CODEBASE_RAG_INDEX_DIR", "").strip()
     if idx and not idx.startswith(("s3://", "gs://", "az://")):
-        return str(Path(os.path.expanduser(idx.rstrip("/"))) / "code_graph.kuzu")
-    return str((Path.cwd() / ".java-codebase-rag" / "code_graph.kuzu").resolve())
+        return str(Path(os.path.expanduser(idx.rstrip("/"))) / "code_graph.lbug")
+    return str((Path.cwd() / ".java-codebase-rag" / "code_graph.lbug").resolve())
 
 
 @dataclass
@@ -165,10 +185,10 @@ class RouteCaller:
 
 
 def _symbol_return_for(alias: str) -> str:
-    """Kuzu RETURN projection for Symbol properties, using the given node alias.
+    """Ladybug RETURN projection for Symbol properties, using the given node alias.
 
     Centralised so queries that bind Symbol under a non-`s` alias (e.g. `n` in
-    graph-expansion / flow-tracing) don't emit `s.*` references that Kuzu
+    graph-expansion / flow-tracing) don't emit `s.*` references that Ladybug
     rejects with `Variable s is not in scope`.
     """
     return (
@@ -198,7 +218,7 @@ def _scope_filters(
 
     Mutates `params` to bind `$module` / `$microservice` only when the
     corresponding filter is set, so unused names don't leak into the
-    Kuzu plan.
+    Ladybug plan.
     """
     out: list[str] = []
     if module:
@@ -274,7 +294,7 @@ _SYM_COLS = (
 
 
 def find_symbols_in_file_range(
-    graph: "KuzuGraph",
+    graph: "LadybugGraph",
     *,
     filename: str,
     start_line: int,
@@ -324,25 +344,25 @@ def _call_graph_needle_phantom_arity_alt(needle: str) -> str | None:
     return needle[:i] + "(?)"
 
 
-class KuzuGraph:
-    """Thin wrapper around a read-only Kuzu connection.
+class LadybugGraph:
+    """Thin wrapper around a read-only Ladybug connection.
 
     Safe to share across threads: we hold a single `Connection`, guarded by a lock.
     """
 
     _lock = threading.Lock()
-    _instance: "KuzuGraph | None" = None
+    _instance: "LadybugGraph | None" = None
     _instance_path: str | None = None
 
     def __init__(self, db_path: str) -> None:
         self.db_path = db_path
-        self._db = kuzu.Database(db_path, read_only=True)
-        self._conn = kuzu.Connection(self._db)
+        self._db = ladybug.Database(db_path, read_only=True)
+        self._conn = ladybug.Connection(self._db)
         self._conn_lock = threading.Lock()
 
     @classmethod
-    def get(cls, db_path: str | None = None) -> "KuzuGraph":
-        resolved = resolve_kuzu_path(db_path)
+    def get(cls, db_path: str | None = None) -> "LadybugGraph":
+        resolved = resolve_ladybug_path(db_path)
         with cls._lock:
             if cls._instance is None or cls._instance_path != resolved:
                 instance = cls(resolved)
@@ -354,7 +374,7 @@ class KuzuGraph:
                         f"required version {_ONTOLOGY_VERSION}. "
                         "Rebuild the graph: `python build_ast_graph.py --source-root <repo>`, "
                         "or run `java-codebase-rag reprocess --source-root <repo>` for a full "
-                        "Lance+Kuzu re-index."
+                        "Lance+Ladybug re-index."
                     )
                 cls._instance = instance
                 cls._instance_path = resolved
@@ -362,11 +382,11 @@ class KuzuGraph:
 
     @classmethod
     def exists(cls, db_path: str | None = None) -> bool:
-        resolved = resolve_kuzu_path(db_path)
+        resolved = resolve_ladybug_path(db_path)
         p = Path(resolved)
         if not p.exists():
             return False
-        # Kuzu represents DB as a directory; allow file form too (single-file DBs).
+        # Ladybug represents DB as a directory; allow file form too (single-file DBs).
         return True
 
     # ---- low-level ----
@@ -481,11 +501,15 @@ class KuzuGraph:
         if not rows:
             return {"error": "no GraphMeta node"}
         row = rows[0]
-        counts: dict[str, Any]
-        try:
-            counts = json.loads(row.get("counts_json") or "{}")
-        except Exception:
-            counts = {}
+        counts: dict[str, Any] = _parse_ladybug_json(row.get("counts_json"))
+        # Ensure counts has expected keys even if empty
+        if not counts:
+            counts = {
+                "packages": 0, "files": 0, "types": 0, "members": 0, "phantoms": 0,
+                "extends": 0, "implements": 0, "injects": 0, "declares": 0, "overrides": 0,
+                "calls": 0, "routes": 0, "exposes": 0, "clients": 0, "declares_client": 0,
+                "producers": 0, "declares_producer": 0, "http_calls": 0, "async_calls": 0,
+            }
         routes_total = exposes_total = 0
         routes_resolved_pct = 0.0
         routes_by_framework: dict[str, Any] = {}
@@ -507,10 +531,7 @@ class KuzuGraph:
         cross_service_resolution: str | None = None
         if meta_mode != "legacy":
             rfw_raw = row.get("routes_by_framework") or "{}"
-            try:
-                routes_by_framework = json.loads(rfw_raw) if isinstance(rfw_raw, str) else (rfw_raw or {})
-            except Exception:
-                routes_by_framework = {}
+            routes_by_framework = _parse_ladybug_json(rfw_raw) if isinstance(rfw_raw, str) else (rfw_raw or {})
             if not isinstance(routes_by_framework, dict):
                 routes_by_framework = {}
             routes_total = int(row.get("routes_total") or 0)
@@ -519,26 +540,17 @@ class KuzuGraph:
         if meta_mode in ("pr_f1", "pr_e3", "pre_e3"):
             routes_from_brownfield_pct = float(row.get("routes_from_brownfield_pct") or 0.0)
             rbl_raw = row.get("routes_by_layer") or "{}"
-            try:
-                routes_by_layer = json.loads(rbl_raw) if isinstance(rbl_raw, str) else (rbl_raw or {})
-            except Exception:
-                routes_by_layer = {}
+            routes_by_layer = _parse_ladybug_json(rbl_raw) if isinstance(rbl_raw, str) else (rbl_raw or {})
             if not isinstance(routes_by_layer, dict):
                 routes_by_layer = {}
             http_calls_total = int(row.get("http_calls_total") or 0)
             async_calls_total = int(row.get("async_calls_total") or 0)
             hbs_raw = row.get("http_calls_by_strategy") or "{}"
             abs_raw = row.get("async_calls_by_strategy") or "{}"
-            try:
-                http_calls_by_strategy = json.loads(hbs_raw) if isinstance(hbs_raw, str) else (hbs_raw or {})
-            except Exception:
-                http_calls_by_strategy = {}
+            http_calls_by_strategy = _parse_ladybug_json(hbs_raw) if isinstance(hbs_raw, str) else (hbs_raw or {})
             if not isinstance(http_calls_by_strategy, dict):
                 http_calls_by_strategy = {}
-            try:
-                async_calls_by_strategy = json.loads(abs_raw) if isinstance(abs_raw, str) else (abs_raw or {})
-            except Exception:
-                async_calls_by_strategy = {}
+            async_calls_by_strategy = _parse_ladybug_json(abs_raw) if isinstance(abs_raw, str) else (abs_raw or {})
             if not isinstance(async_calls_by_strategy, dict):
                 async_calls_by_strategy = {}
             http_calls_resolved_pct = float(row.get("http_calls_resolved_pct") or 0.0)
@@ -547,16 +559,10 @@ class KuzuGraph:
             async_producers_from_brownfield_pct = float(row.get("async_producers_from_brownfield_pct") or 0.0)
             hmb_raw = row.get("http_calls_match_breakdown") or "{}"
             amb_raw = row.get("async_calls_match_breakdown") or "{}"
-            try:
-                http_calls_match_breakdown = json.loads(hmb_raw) if isinstance(hmb_raw, str) else (hmb_raw or {})
-            except Exception:
-                http_calls_match_breakdown = {}
+            http_calls_match_breakdown = _parse_ladybug_json(hmb_raw) if isinstance(hmb_raw, str) else (hmb_raw or {})
             if not isinstance(http_calls_match_breakdown, dict):
                 http_calls_match_breakdown = {}
-            try:
-                async_calls_match_breakdown = json.loads(amb_raw) if isinstance(amb_raw, str) else (amb_raw or {})
-            except Exception:
-                async_calls_match_breakdown = {}
+            async_calls_match_breakdown = _parse_ladybug_json(amb_raw) if isinstance(amb_raw, str) else (amb_raw or {})
             if not isinstance(async_calls_match_breakdown, dict):
                 async_calls_match_breakdown = {}
             cross_service_calls_total = int(row.get("cross_service_calls_total") or 0)
@@ -1013,7 +1019,7 @@ class KuzuGraph:
                            microservice: str | None = None,
                            capability: str | None = None,
                            limit: int = 100) -> list[SymbolHit]:
-        # Kuzu supports `list_contains` for STRING[].
+        # Ladybug supports `list_contains` for STRING[].
         filters = ["list_contains(s.annotations, $ann)"]
         params: dict[str, Any] = {"ann": annotation}
         if capability:
@@ -1454,7 +1460,7 @@ class KuzuGraph:
             ))
             if entry_roles:
                 params["entry_roles"] = list(entry_roles)
-                # Kuzu 0.11.x does not support parameterized lists inside ANY
+                # Ladybug 0.17.x does not support parameterized lists inside ANY
                 # comprehensions, so we expand the fixed capability set as
                 # individual list_contains predicates ORed together.
                 cap_predicates = " OR ".join(