fix(storage): purge stale lbug/DuckDB refs after ADR 0019; fix 2 latent bugs (#247)

## Summary

The single-file SQLite migration (ADR 0019, #245) left stale references
to the removed `graph.lbug` + `temporal.duckdb` backends across source
comments, docs, agent-facing MCP tool descriptions, and user-facing
error strings. This sweeps and corrects them, and fixes **two real
bugs** the migration left behind that its own tests did not catch.

## Bugs fixed (behavioral)

**1. `describeArtifacts()` pointed at a file that no longer exists.**
`paths.ts` still returned `graphFile="graph.lbug"` /
`temporalFile="temporal.duckdb"`, but `openStore()` writes
`store.sqlite`. That value is not cosmetic: it feeds the `is-indexed`
existence probe (`cli/src/lib/is-indexed.ts`) and the user-facing path
in the MCP "store unreadable" error (`mcp/src/tools/shared.ts`). So the
error told users to check a `.codehub/graph.lbug` that is gone. Now
returns `store.sqlite` for both views. `paths.test.ts` had pinned the
wrong values, so it was green while asserting broken behavior — updated.

**2. `bm25CorpusHasSummaries()` queried `information_schema.tables`.**
That is a DuckDB/Postgres catalog `node:sqlite` does not expose. The
query threw, was swallowed by the surrounding `try/catch`, and the probe
was silently always-false in production. Switched to `sqlite_master`;
updated the test mock that pinned the old string.

## Also: the `sql` MCP tool contract

The `sql` tool now advertises `nodes`/`edges`/`embeddings` as directly
SQL-queryable (they are real tables in `store.sqlite`) instead of
claiming the graph is "NOT SQL-queryable, reachable only through
Cypher". The `cypher:` arg returns a clear "use `sql:` instead" envelope
against the default SQLite backend (`execCypher` is unimplemented per
ADR 0019, reserved for community forks). `sql.test.ts` updated to assert
the inverted contract.

## Scope

47 files. Most are comment/doc corrections; the 4 above are behavioral.
The DuckDB→SQLite comment pass was context-aware (historical-fact
mentions like "replaced the lbug + **DuckDB** pair" intentionally kept).

## Verification

- typecheck clean: core-types, storage, mcp, cli
- storage suite: 81 pass / 0 fail
- mcp suite: 234 pass / 0 fail
- cli suite: 346 pass / 0 fail
- banned-strings + commitlint pre-commit gates pass
- pre-push test hook passed on push

Author: theagenticguy

packages/analysis/src/group/cross-repo-links.ts

@@ -11,7 +11,7 @@
  * `traverseDescendants`, `traverse`, plus the ITemporalStore-compat noops.
  *
  * Per-test fixtures populate the store via `addNode` / `addEdge`; the test
- * then exercises the production code through the same finders the DuckDb
+ * then exercises the production code through the same finders the SQLite store
  * and GraphDb adapters expose. No raw SQL crosses the test boundary.
  */
 

packages/analysis/src/test-utils.ts

@@ -15,7 +15,7 @@
  *     Contributors) never crashes the verdict; it simply drops the missing
  *     signal.
  *   - **Zero `any`**: the only loose type surface is `Record<string,unknown>`
- *     for raw DuckDB rows, each of which we narrow with explicit casts.
+ *     for raw SQLite rows, each of which we narrow with explicit casts.
  */
 
 import { execFile } from "node:child_process";

packages/analysis/src/verdict.ts

@@ -56,7 +56,7 @@ export interface AnalyzeOptions {
   readonly force?: boolean;
   /**
    * When true, the embeddings phase embeds every callable/declaration symbol
-   * and the result is upserted into the DuckDB `embeddings` table. Requires
+   * and the result is upserted into the `embeddings` table. Requires
    * `codehub setup --embeddings` to have installed weights; if weights are
    * missing the phase logs a warning and skips — analyze never aborts.
    */
@@ -222,7 +222,7 @@ export async function runAnalyze(path: string, opts: AnalyzeOptions = {}): Promi
 
   // Load a prior graph projection for the incremental-scope phase when the
   // CLI was not invoked with --force. The projection is a thin wrapper
-  // around the prior DuckDB index (File nodes + IMPORTS / EXTENDS /
+  // around the prior SQLite index (File nodes + IMPORTS / EXTENDS /
   // IMPLEMENTS edges). `loadPreviousGraph` silently returns undefined if
   // the store does not exist or cannot be opened; incremental-scope then
   // reports mode="full" with reason="no-prior-graph".
@@ -333,10 +333,9 @@ export async function runAnalyze(path: string, opts: AnalyzeOptions = {}): Promi
     );
   }
 
-  // Persist to the composed graph + temporal store. Storage is always
-  // graph.lbug (graph-tier) + temporal.duckdb sidecar (cochanges, summary
-  // cache); the temporal-tier writes (`bulkLoadCochanges`,
-  // `bulkLoadSymbolSummaries`) route through `store.temporal`.
+  // Persist to the composed graph + temporal store. Post-ADR 0019 both views
+  // are one `store.sqlite`; the temporal-tier writes (`bulkLoadCochanges`,
+  // `bulkLoadSymbolSummaries`) still route through `store.temporal`.
   await mkdir(resolveRepoMetaDir(repoPath), { recursive: true });
   const dbPath = resolveGraphPath(repoPath);
   const store: Store = await openStore({ path: dbPath });
@@ -423,7 +422,7 @@ export async function runAnalyze(path: string, opts: AnalyzeOptions = {}): Promi
 
     // Persist the scan-state sidecar so the next analyze invocation can feed
     // the incremental-scope phase via loadPreviousGraph(). We write this
-    // alongside the DuckDB file under `<repo>/.codehub` so a clean of the
+    // alongside the store.sqlite file under `<repo>/.codehub` so a clean of the
     // meta dir invalidates both the index and the incremental state together.
     if (result.scan !== undefined) {
       await writeScanState(
@@ -434,7 +433,7 @@ export async function runAnalyze(path: string, opts: AnalyzeOptions = {}): Promi
 
     // Opt-in skill generation. Walk Community nodes just persisted above and
     // emit one SKILL.md per cluster under `<repo>/.codehub/skills/`. Runs
-    // against the still-open DuckDB handle so there's no re-open cost, and
+    // against the still-open SQLite handle so there's no re-open cost, and
     // any per-skill failure (read-only dir, permission denied, disk full)
     // logs-and-continues — analyze never aborts because of a skill write.
     if (opts.skills === true) {
@@ -579,7 +578,7 @@ export async function runAnalyze(path: string, opts: AnalyzeOptions = {}): Promi
 
 /**
  * Build the {@link pipeline.PreviousGraph} projection expected by the
- * incremental-scope phase from the prior DuckDB index + scan-state sidecar.
+ * incremental-scope phase from the prior SQLite index + scan-state sidecar.
  *
  * The projection carries:
  *   - file paths + scan-time content hashes, read from
@@ -827,7 +826,7 @@ export async function resolveCoverageEnabled(
  * compute that before the pipeline runs (LSP phases haven't yielded
  * yet), so we use the prior run's stored counts when available:
  *
- *   - If a DuckDB store is readable at the expected path, count nodes
+ *   - If a SQLite store is readable at the expected path, count nodes
  *     whose kind is Function/Method/Class. That count is the best proxy
  *     for "SCIP-confirmed callables" we can get before the parse phase.
  *   - If no prior store exists (fresh clone, first analyze), fall back
@@ -863,7 +862,7 @@ export async function resolveMaxSummariesCap(
 
 /**
  * Count callable symbols (Function / Method / Class) recorded by the
- * prior run. Returns `undefined` when no prior DuckDB index exists or
+ * prior run. Returns `undefined` when no prior SQLite index exists or
  * the count query fails — callers treat that as "no prior run" and fall
  * back to the first-run heuristic.
  */
@@ -893,7 +892,7 @@ async function countPriorCallableSymbols(repoPath: string): Promise<number | und
 }
 
 /**
- * Open a read-only DuckDB store scoped to the `symbol_summaries` cache
+ * Open a read-only SQLite store scoped to the `symbol_summaries` cache
  * probe. The returned object carries a cache adapter the `summarize`
  * phase uses to short-circuit candidates whose content hash already has
  * a row on disk, plus a `close()` the caller invokes to release the
@@ -927,7 +926,7 @@ async function openSummaryCacheAdapter(
 }
 
 /**
- * Open a read-only DuckDB store scoped to the `embeddings` content-hash
+ * Open a read-only SQLite store scoped to the `embeddings` content-hash
  * probe. The returned adapter's `list()` loads every prior
  * `(granularity, nodeId, chunkIndex) → content_hash` row in a single
  * round-trip so the embeddings phase can skip chunks whose source text is
@@ -992,7 +991,7 @@ function fileFromNodeId(id: string): string | undefined {
 // returns rehydrated `GraphNode` objects, so the constant is no longer
 // load-bearing here. The `rowToGraphNode` / `rowToCodeRelation` adapters
 // below remain exported for external consumers that hand-roll over the
-// DuckDB wide-column shape.
+// SQLite wide-column shape.
 
 const NODE_KIND_SET: ReadonlySet<string> = new Set<string>(NODE_KINDS);
 const RELATION_TYPE_SET: ReadonlySet<string> = new Set<string>(RELATION_TYPES);
@@ -1015,7 +1014,7 @@ function boolField(r: Record<string, unknown>, col: string): boolean | undefined
 }
 
 function stringArrayField(r: Record<string, unknown>, col: string): readonly string[] | undefined {
-  // Preserve `[]` distinct from absent. The DuckDB TEXT[] binder returns
+  // Preserve `[]` distinct from absent. The SQLite TEXT[] binder returns
   // a 0-length JS array for an empty SQL array literal and `null` for
   // SQL NULL; mirror the storage adapter's `setStringArrayField` and
   // return the array verbatim so a Community / Route node written as

packages/cli/src/commands/analyze.ts

@@ -61,7 +61,7 @@ export interface CodePackArgs {
   readonly engine?: "pack" | "repomix";
   /**
    * Test seam — inject a custom `generatePack` so unit tests don't need
-   * to load native DuckDB bindings. Production callers leave this
+   * to load native storage bindings. Production callers leave this
    * unset.
    */
   readonly _generatePack?: typeof generatePack;

packages/cli/src/commands/code-pack.ts

@@ -5,7 +5,7 @@
  * Flow:
  *   1. Read + parse + validate the SARIF file via `@opencodehub/sarif`.
  *   2. Resolve the target repo (either `--repo <name>` or CWD).
- *   3. Open the DuckDB store and pull a per-file, line-sorted symbol
+ *   3. Open the SQLite store and pull a per-file, line-sorted symbol
  *      index over the SARIF's referenced URIs (used to resolve Finding
  *      → Symbol edges).
  *   4. For every Result across every Run, build a Finding node keyed by
@@ -15,7 +15,7 @@
  *      enclosing symbol at `(uri, startLine)` when the graph contains
  *      one. A scanner-provided `opencodehub.symbolId` hint wins over the
  *      enclosing lookup when set.
- *   5. UPSERT into DuckDB via `store.bulkLoad({ mode: "upsert" })`.
+ *   5. UPSERT into the SQLite store via `store.bulkLoad({ mode: "upsert" })`.
  *
  * The command is idempotent — re-running with the same SARIF produces
  * the same nodes and edges. Results without a parsable location (no
@@ -140,7 +140,7 @@ interface BuildSummary {
 
 /**
  * Pure builder over SARIF runs. Exposed for unit tests so we can exercise
- * the node/edge emission logic without touching DuckDB.
+ * the node/edge emission logic without touching SQLite.
  *
  * `nodesByFile` is the per-file, line-sorted symbol index (produced by
  * {@link indexNodesByFile}) used to resolve each SARIF result back to the

packages/cli/src/commands/ingest-sarif.ts

@@ -34,8 +34,8 @@ type Health = "ok" | "path-missing" | "graph-missing";
 
 function classifyHealth(entry: RepoEntry): Health {
   if (!existsSync(entry.path)) return "path-missing";
-  // Indexed probe: presence of `meta.json` / `graph.lbug` under `.codehub/`
-  // counts as "indexed" (lbug is the only graph backend post-ADR 0016).
+  // Indexed probe: presence of `meta.json` / `store.sqlite` under `.codehub/`
+  // counts as "indexed" (the single-file store is the only backend, ADR 0019).
   if (!codehubIsIndexed(entry.path)) return "graph-missing";
   return "ok";
 }

packages/cli/src/commands/list.ts

@@ -6,9 +6,9 @@
  * Returns the canonical {@link Store} envelope from `@opencodehub/storage`
  * so callers can route graph-tier queries through `store.graph` and
  * temporal-tier queries (cochanges, summaries, `--sql` escape hatch)
- * through `store.temporal`. Storage is always graph.lbug + temporal.duckdb;
- * the legacy backend selector was removed when the DuckDB graph backend
- * was ripped out (see ADR 0016).
+ * through `store.temporal`. Post-ADR 0019 both views are one `SqliteStore`
+ * over a single `<repo>/.codehub/store.sqlite`; the legacy backend selector
+ * was removed when the lbug + DuckDB pair was replaced (see ADR 0019).
  */
 
 import { resolve } from "node:path";
@@ -33,7 +33,7 @@ export async function openStoreForCommand(opts: OpenStoreOptions): Promise<OpenS
     path: dbPath,
     readOnly: opts.readOnly ?? true,
   });
-  // The legacy CLI entry point opened the DuckDB connection eagerly and
+  // The legacy CLI entry point opened the store connection eagerly and
   // every command consumed an already-open store. The `openStore` factory
   // only constructs adapters; opening is the lifecycle owner's job. Keep
   // that contract by opening both views here so command handlers stay a

packages/cli/src/commands/open-store.ts

@@ -50,7 +50,7 @@ const INCLUDE_CONTENT_CHAR_CAP = 2000;
 const SUMMARY_COLUMN_CHAR_CAP = 120;
 
 /**
- * Hook for tests to inject a pre-built store without touching DuckDB. The
+ * Hook for tests to inject a pre-built store without touching SQLite. The
  * default implementation delegates to {@link openStoreForCommand}. Kept
  * separate from the public `QueryOptions` interface so end-user CLI callers
  * aren't tempted to pass an in-process store.

packages/cli/src/commands/query.ts

@@ -31,7 +31,7 @@ export interface StatusOptions {
   /**
    * Test seam: open a read-only store and return its retrieval state. Defaults
    * to opening the real composed store. Tests inject a stub so they don't need
-   * a live graph.lbug on disk.
+   * a live store.sqlite on disk.
    */
   readonly probeRetrieval?: (repoPath: string) => Promise<RetrievalState | undefined>;
 }