Evaluate replacing Kùzu with LadybugDB (Kùzu is archived; Ladybug is the maintained fork)

Bắt đầu với package.json và src/store/kuzu_store.ts để hiểu ranh giới phụ thuộc và cách sử dụng hiện tại của Database, Connection, QueryResult và KuzuValue. Sau đó kiểm tra src/query/graph_query.ts và chạy quá trình tải cùng toàn bộ bộ truy vấn trên một repository mẫu, so sánh kết quả với Kùzu. Được xem là hoàn tất khi dependency ổn định của LadybugDB hoạt động trên các nền tảng được hỗ trợ, các graph và query được dựng lại tạo ra kết quả tương đương, và yêu cầu dựng lại storage đã được ghi lại.

Summary

Kùzu — the embedded graph database codespine is built on — was archived in October 2025 after the company was acquired by Apple. The kuzu npm package has been frozen at 0.11.3 since 2025-10-10: no further bug fixes, security patches, or releases. We are sitting on an abandoned core dependency.

LadybugDB is the most prominent community fork of Kùzu, created by the post-archival fork wave. It is a direct fork of the same C++ codebase, keeps the same Cypher dialect and the same Node.js API, and is actively developed (stable 0.17.1 in June 2026, daily nightly builds). Because it shares Kùzu's lineage, migrating codespine to it is a near drop-in swap rather than a rewrite.

Recommendation: yes, we should plan this migration. It is low-urgency (the pinned kuzu build keeps working) but high-leverage (gets us off a dead dependency back onto a maintained one), and the cost is small thanks to the shared API. This issue is the evaluation; it does not change any code yet.

---

Background: what happened to Kùzu

• Kùzu Inc. was acquired by Apple; the upstream repo was archived in October 2025.
• Several community forks emerged afterward. Per Gábor Szárnyas' survey, the notable ones are:
  • LadybugDB (LadybugDB / Arun Sharma) — "embedded graph database built for query speed and scalability"; security fixes + Arrow/DuckDB/Parquet integration.
  • Ryu / Ryugraph (Predictable Labs) — embedded, vector + full-text search focus.
  • Bighorn (Kineviz) — visualization integration, embedded + standalone server modes.
  • Vela (Vela Partners) — AI-agent memory, concurrent multi-writer focus.
• LadybugDB is the most visible of the four (~1.4k GitHub stars, 77 contributors, 16 releases). It explicitly positions itself as the successor and tells Kùzu users to migrate.

Why LadybugDB specifically

	kuzu (current)	@ladybugdb/core
Status	Archived Oct 2025	Active (stable 0.17.1, June 2026; daily nightlies)
npm last publish	2025-10-10, frozen at 0.11.3	created 2026-03-01, ongoing
Lineage	original	fork of the same codebase
Cypher dialect	Kùzu	same (CREATE NODE/REL TABLE, var-length rels)
Node.js API	Database, Connection, QueryResult	identical class/method surface
Install	npm i kuzu	npm i @ladybugdb/core

The other forks would also be Cypher-compatible, but LadybugDB has the most momentum and the clearest "drop-in for Kùzu users" stance, so it is the lowest-risk target.

---

How much of codespine touches the database

The graph database is the heart of codespine: it stores the TypeScript code knowledge graph (GraphNode + Edge + GraphMeta tables) and answers all the analysis queries (blast radius, who-calls, dead exports, clustering input, hotspots, webview export).

Roughly ~3,500 lines across ~15 files import or call kuzu, but almost all of it goes through one abstraction:

• src/store/kuzu_store.ts — the central KuzuStore wrapper (new Database(dbPath) / new Connection(db), schema DDL, prepare/execute, getAll/close).
• src/query/graph_query.ts — ~25 Cypher queries (the actual analysis logic).
• src/cluster/graph_clusterer.ts, src/enrich/runtime_enricher.ts, src/report/report_data.ts, and the src/commands/* CLI commands.

The import surface is uniform:

import { Connection, Database, QueryResult } from 'kuzu';
import type { KuzuValue } from 'kuzu';

That KuzuStore boundary is exactly what makes this cheap — there is essentially one seam to cut.

Compatibility check (verified against the LadybugDB type definitions)

The published @ladybugdb/core .d.ts exposes the same API codespine already uses:

• class Database { constructor(...); close() }
• class Connection { constructor(database, numThreads?); query(); execute(); prepare(); close() }
• class PreparedStatement
• class QueryResult { hasNext(); getNext(); each(); getAll(); all(); close() }
• Value shapes NodeValue (_label, _id), RelValue (_src, _dst, _label), RecursiveRelValue — identical to Kùzu's. The only rename is the value union type: KuzuValue → LbugValue.

The Cypher we rely on is the Kùzu dialect and carries over unchanged, including the non-standard bits:

• CREATE NODE TABLE / CREATE REL TABLE (FROM … TO …) DDL.
• Variable-length relationships with an inline edge predicate — -[e:Edge*1..N (r, n | WHERE r.kind = 'CALLS')]- (the blast-radius query).
• Prepared statements + parameter records.

What actually needs to change

1. Dependency swap — "kuzu": "^0.11.3" → "@ladybugdb/core": "^0.17" in package.json.
2. Import path in the ~15 files: from 'kuzu' → from '@ladybugdb/core', and the KuzuValue → LbugValue type rename.
3. Rebuild the on-disk database. LadybugDB's storage format (v0.17) is newer than Kùzu 0.11, so existing graph.kuzu files are not guaranteed to open. This is a non-issue for us: codespine regenerates the graph from JSONL via load, so users just re-run extraction/load. Worth a note in docs/changelog.
4. Re-check KUZU_MAX_REL_BOUND = 30 in graph_query.ts — Kùzu's parser rejected N > 30 on variable-length edges. LadybugDB may have lifted this; verify and relax the clamp if so.
5. Cosmetic (optional, separate PR): rename kuzu_store.ts / KuzuStore / KUZU_* to neutral names (e.g. graph_store.ts / GraphStore) so we are not naming things after a dead project.

Effort

Because it is a same-API fork (not a port to a different database), this is roughly a day of work, not the ~2 weeks a true database swap (SQLite/Postgres) would take:

• Swap dependency + imports: ~1–2 hours (mechanical).
• Build native addon for our platforms / CI, smoke-test load → query: ~½ day.
• Run the existing query suite against a rebuilt graph and diff results vs. Kùzu: ~½ day.

Risks / open questions

• Fork is young. @ladybugdb/core only appeared on npm in March 2026; it is a 0.x project with daily dev builds. Pin to a stable tag (0.17.1), not nightlies.
• Ecosystem fragmentation. Four forks are competing for the Kùzu mantle (LadybugDB, Ryu, Bighorn, Vela). There is a small risk of backing the one that loses momentum. Mitigation: our KuzuStore seam keeps us portable — any Cypher-compatible fork is a similar swap later.
• Native addon / platform coverage. Confirm prebuilt binaries exist for the platforms codespine ships to (macOS arm64 at minimum); otherwise we depend on cmake-js building from source.
• Storage-format migration affects anyone with a cached graph.kuzu — needs a one-line "re-run load" note.

Proposed plan

1. Spike on a branch: swap to @ladybugdb/[email protected], run load + the full query suite on a sample repo, diff against current Kùzu output.
2. If clean, land the dependency/import swap as one PR; keep the KuzuStore name in that PR to minimize diff.
3. Follow-up PR: rename the kuzu-flavored identifiers and update docs (storage rebuild note, KUZU_MAX_REL_BOUND re-check).

---

Sources: LadybugDB repo · Kùzu forks survey (Szárnyas) · npm registry (kuzu frozen at 0.11.3 2025-10-10; @ladybugdb/core latest 0.17.1).