@codragraph/cli 1.6.4 → 2.1.0

package/dist/mcp/local/local-backend.js

@@ -7,7 +7,7 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
-import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, isWriteQuery, } from '../../core/lbug/pool-adapter.js';
+import { initCgdb, executeQuery, executeParameterized, closeCgdb, isCgdbReady, isWriteQuery, } from '../../core/cgdb/pool-adapter.js';
 export { isWriteQuery };
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
@@ -18,7 +18,8 @@ import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-ma
 import { GroupService } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
-import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
+import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/cgdb/schema.js';
+import { decodeContentField } from '../../core/cgdb/content-read.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { checkStaleness, checkCwdMatch } from '../../core/git-staleness.js';
 // AI context generation is CLI-only (codragraph analyze)
@@ -188,7 +189,7 @@ export class LocalBackend {
     }
     /** Close all pooled LadybugDB connections (CLI one-shot; optional for long-lived MCP). */
     async dispose() {
-        await closeLbug();
+        await closeCgdb();
     }
     // ─── Initialization ──────────────────────────────────────────────
     /**
@@ -211,9 +212,9 @@ export class LocalBackend {
             const id = this.repoId(entry.name, entry.path);
             freshIds.add(id);
             const storagePath = entry.storagePath;
-            const lbugPath = path.join(storagePath, 'lbug');
+            const cgdbPath = path.join(storagePath, 'cgdb');
             // Clean up any leftover KuzuDB files from before the LadybugDB migration.
-            // If kuzu exists but lbug doesn't, warn so the user knows to re-analyze.
+            // If kuzu exists but cgdb doesn't, warn so the user knows to re-analyze.
             const kuzu = await cleanupOldKuzuFiles(storagePath);
             if (kuzu.found && kuzu.needsReindex) {
                 console.error(`CodraGraph: "${entry.name}" has a stale KuzuDB index. Run: codragraph analyze ${entry.path}`);
@@ -223,7 +224,7 @@ export class LocalBackend {
                 name: entry.name,
                 repoPath: entry.path,
                 storagePath,
-                lbugPath,
+                cgdbPath,
                 indexedAt: entry.indexedAt,
                 lastCommit: entry.lastCommit,
                 remoteUrl: entry.remoteUrl,
@@ -363,7 +364,7 @@ export class LocalBackend {
         // Check if the index was rebuilt since we opened the connection (#297).
         // Throttle staleness checks to at most once per 5 seconds per repo to
         // avoid an fs.readFile round-trip on every tool invocation.
-        if (this.initializedRepos.has(repoId) && isLbugReady(repoId)) {
+        if (this.initializedRepos.has(repoId) && isCgdbReady(repoId)) {
             const now = Date.now();
             const lastCheck = this.lastStalenessCheck.get(repoId) ?? 0;
             if (now - lastCheck < 5000)
@@ -379,10 +380,10 @@ export class LocalBackend {
                     // callers both detect staleness and double-close the pool.
                     const reinit = (async () => {
                         try {
-                            await closeLbug(repoId);
+                            await closeCgdb(repoId);
                             this.initializedRepos.delete(repoId);
                             handle.indexedAt = meta.indexedAt;
-                            await initLbug(repoId, handle.lbugPath);
+                            await initCgdb(repoId, handle.cgdbPath);
                             this.initializedRepos.add(repoId);
                         }
                         finally {
@@ -401,7 +402,7 @@ export class LocalBackend {
             }
         }
         try {
-            await initLbug(repoId, handle.lbugPath);
+            await initCgdb(repoId, handle.cgdbPath);
             this.initializedRepos.add(repoId);
         }
         catch (err) {
@@ -835,10 +836,12 @@ export class LocalBackend {
                 try {
                     const contentRows = await executeParameterized(repo.id, `
             MATCH (n {id: $nodeId})
-            RETURN n.content AS content
+            RETURN n.content AS content, n.contentEncoding AS contentEncoding
           `, { nodeId: sym.nodeId });
                     if (contentRows.length > 0) {
-                        content = contentRows[0].content ?? contentRows[0][0];
+                        const raw = contentRows[0].content ?? contentRows[0][0];
+                        const enc = contentRows[0].contentEncoding ?? contentRows[0][1];
+                        content = decodeContentField(raw, enc);
                     }
                 }
                 catch (e) {
@@ -945,10 +948,10 @@ export class LocalBackend {
      * BM25 keyword search helper - uses LadybugDB FTS for always-fresh results
      */
     async bm25Search(repo, query, limit) {
-        const { searchFTSFromLbug } = await import('../../core/search/bm25-index.js');
+        const { searchFTSFromCgdb } = await import('../../core/search/bm25-index.js');
         let bm25Results;
         try {
-            bm25Results = await searchFTSFromLbug(query, limit, repo.id);
+            bm25Results = await searchFTSFromCgdb(query, limit, repo.id);
         }
         catch (err) {
             console.error('CodraGraph: BM25/FTS search failed (FTS indexes may not exist) -', err.message);
@@ -1085,7 +1088,7 @@ export class LocalBackend {
     }
     async cypher(repo, params) {
         await this.ensureInitialized(repo.id);
-        if (!isLbugReady(repo.id)) {
+        if (!isCgdbReady(repo.id)) {
             return { error: 'LadybugDB not ready. Index may be corrupted.' };
         }
         // Block write operations (defense-in-depth — DB is already read-only)
@@ -1330,7 +1333,13 @@ export class LocalBackend {
      */
     async resolveSymbolCandidates(repo, query, hints) {
         const { uid, name, include_content } = query;
-        const selectClause = `n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}`;
+        // RFC 0001 Phase 2: when fetching content, also fetch the per-row
+        // encoding tag so `decodeContentField` can pass it through unchanged
+        // (default 'none') or run brotli/zstd decode. Adding contentEncoding
+        // to the SELECT shifts the numeric-index fallback for content from
+        // r[6] to (still) r[6] — encoding lands at r[7] — but we read by name
+        // first which is the documented preferred path on LadybugDB.
+        const selectClause = `n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content, n.contentEncoding AS contentEncoding' : ''}`;
         // Direct UID — zero-ambiguity path.
         if (uid) {
             const rows = await executeParameterized(repo.id, `MATCH (n {id: $uid}) RETURN ${selectClause} LIMIT 1`, { uid });
@@ -1344,7 +1353,11 @@ export class LocalBackend {
                 filePath: (r.filePath ?? r[3]),
                 startLine: (r.startLine ?? r[4]),
                 endLine: (r.endLine ?? r[5]),
-                ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+                ...(include_content
+                    ? {
+                        content: decodeContentField(r.content ?? r[6], r.contentEncoding ?? r[7]),
+                    }
+                    : {}),
             };
             // Same LadybugDB label-enrichment as the name-based path: a UID
             // pointing at a Class must still surface `type: 'Class'` so impact's
@@ -1380,7 +1393,11 @@ export class LocalBackend {
             filePath: (r.filePath ?? r[3]),
             startLine: (r.startLine ?? r[4]),
             endLine: (r.endLine ?? r[5]),
-            ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+            ...(include_content
+                ? {
+                    content: decodeContentField(r.content ?? r[6], r.contentEncoding ?? r[7]),
+                }
+                : {}),
         }));
         // Enrich labels for any candidates where `labels(n)[0]` came back empty.
         // LadybugDB returns an empty string for that projection on certain node
@@ -3205,7 +3222,7 @@ export class LocalBackend {
         };
     }
     async disconnect() {
-        await closeLbug(); // close all connections
+        await closeCgdb(); // close all connections
         // Note: we intentionally do NOT call disposeEmbedder() here.
         // ONNX Runtime's native cleanup segfaults on macOS and some Linux configs,
         // and importing the embedder module on Node v24+ crashes if onnxruntime

package/dist/mcp/server.js

@@ -15,7 +15,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CompatibleStdioServerTransport } from './compatible-stdio-transport.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { CODRAGRAPH_TOOLS } from './tools.js';
-import { realStdoutWrite } from './core/lbug-adapter.js';
+import { realStdoutWrite } from './core/cgdb-adapter.js';
 import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
 /**
  * Next-step hints appended to tool responses.
@@ -208,7 +208,7 @@ export function createMCPServer(backend) {
                     { name: 'repo', description: 'Repository (omit if only one indexed)', required: false },
                     {
                         name: 'symbolId',
-                        description: 'Stable symbol id (PK in the lbug node table)',
+                        description: 'Stable symbol id (PK in the cgdb node table)',
                         required: true,
                     },
                     {
@@ -484,7 +484,7 @@ Follow these steps:
 export async function startMCPServer(backend) {
     const server = createMCPServer(backend);
     // Use the shared stdout reference captured at module-load time by the
-    // lbug-adapter.  Avoids divergence if anything patches stdout between
+    // cgdb-adapter.  Avoids divergence if anything patches stdout between
     // module load and server start.
     const _safeStdout = new Proxy(process.stdout, {
         get(target, prop, receiver) {

package/dist/mcp/tools.js

@@ -806,7 +806,7 @@ Pair with codragraph_context first to get the symbol's stable id (e.g. \`fn:src/
             type: 'object',
             properties: {
                 repo: { type: 'string', description: 'Indexed repo (omit if only one).' },
-                symbolId: { type: 'string', description: 'Stable symbol id (PK in the lbug node table).' },
+                symbolId: { type: 'string', description: 'Stable symbol id (PK in the cgdb node table).' },
                 table: {
                     type: 'string',
                     description: 'Optional table hint to narrow the search (Function, Class, Method, Interface, …).',

package/dist/server/analyze-worker.js

@@ -11,7 +11,7 @@
  *   Child -> Parent: { type: 'error', message: string }
  */
 import { runFullAnalysis } from '../core/run-analyze.js';
-import { closeLbug } from '../core/lbug/lbug-adapter.js';
+import { closeCgdb } from '../core/cgdb/cgdb-adapter.js';
 function send(msg) {
     process.send?.(msg);
 }
@@ -28,7 +28,7 @@ process.on('unhandledRejection', (reason) => {
 process.on('SIGTERM', async () => {
     send({ type: 'error', message: 'Analysis cancelled (worker received SIGTERM)' });
     try {
-        await closeLbug();
+        await closeCgdb();
     }
     catch { }
     process.exit(0);

package/dist/server/api.js

@@ -13,10 +13,11 @@ import path from 'path';
 import fs from 'fs/promises';
 import { createRequire } from 'node:module';
 import { loadMeta, listRegisteredRepos, getStoragePath } from '../storage/repo-manager.js';
-import { executeQuery, executePrepared, executeWithReusedStatement, streamQuery, closeLbug, withLbugDb, } from '../core/lbug/lbug-adapter.js';
-import { isWriteQuery } from '../core/lbug/pool-adapter.js';
+import { executeQuery, executePrepared, executeWithReusedStatement, streamQuery, closeCgdb, withCgdbDb, } from '../core/cgdb/cgdb-adapter.js';
+import { isWriteQuery } from '../core/cgdb/pool-adapter.js';
+import { decodeContentField } from '../core/cgdb/content-read.js';
 import { NODE_TABLES } from '../_shared/index.js';
-import { searchFTSFromLbug } from '../core/search/bm25-index.js';
+import { searchFTSFromCgdb } from '../core/search/bm25-index.js';
 import { hybridSearch } from '../core/search/hybrid-search.js';
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at server startup — crashes on unsupported Node ABI versions (#89)
@@ -189,7 +190,7 @@ const getNodeQuery = (table, includeContent) => {
     const tableLabel = quoteNodeTable(table);
     if (table === 'File') {
         return includeContent
-            ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content`
+            ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content, n.contentEncoding AS contentEncoding`
             : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
     }
     if (table === 'Folder') {
@@ -208,7 +209,7 @@ const getNodeQuery = (table, includeContent) => {
         return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.description AS description`;
     }
     return includeContent
-        ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content`
+        ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content, n.contentEncoding AS contentEncoding`
         : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine`;
 };
 const mapGraphNodeRow = (table, row, includeContent) => ({
@@ -219,7 +220,7 @@ const mapGraphNodeRow = (table, row, includeContent) => ({
         filePath: row.filePath ?? row[2],
         startLine: row.startLine,
         endLine: row.endLine,
-        content: includeContent ? row.content : undefined,
+        content: includeContent ? decodeContentField(row.content, row.contentEncoding) : undefined,
         responseKeys: row.responseKeys,
         errorKeys: row.errorKeys,
         middleware: row.middleware,
@@ -387,7 +388,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
     const cleanupMcp = mountMCPEndpoints(app, backend);
     const jobManager = new JobManager();
     // Shared repo lock — prevents concurrent analyze + embed on the same repo path,
-    // which would corrupt LadybugDB (analyze calls closeLbug + initLbug while embed has queries in flight).
+    // which would corrupt LadybugDB (analyze calls closeCgdb + initCgdb while embed has queries in flight).
     const activeRepoPaths = new Set();
     const acquireRepoLock = (repoPath) => {
         if (activeRepoPaths.has(repoPath)) {
@@ -570,7 +571,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
             try {
                 // Close any open LadybugDB handle before deleting files
                 try {
-                    await closeLbug();
+                    await closeCgdb();
                 }
                 catch { }
                 // 1. Delete the .codragraph index/storage directory
@@ -894,21 +895,21 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(404).json({ error: 'Repository not found' });
                 return;
             }
-            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const cgdbPath = path.join(entry.storagePath, 'cgdb');
             const includeContent = req.query.includeContent === 'true';
             const stream = req.query.stream === 'true';
-            // Guard: when a repo has no materialized lbug schema (fixture-
-            // seeded CAS-only repos), or the lbug WAL is corrupt/stale from
+            // Guard: when a repo has no materialized cgdb schema (fixture-
+            // seeded CAS-only repos), or the cgdb WAL is corrupt/stale from
             // a prior failed analyze, LadybugDB native will abort with
             // UNREACHABLE_CODE or an ANY-vector exception. Detect both
             // shapes — missing file (cheap fs.access) AND empty/4096-byte
             // schema-only file (fs.stat) — and return an empty graph so
             // the dashboard doesn't blow up. The Graph tab keeps working
-            // for repos that actually have a real lbug.
-            const isLbugMaterialized = await (async () => {
+            // for repos that actually have a real cgdb.
+            const isCgdbMaterialized = await (async () => {
                 try {
-                    const stat = await fs.stat(lbugPath);
-                    // Schema-only lbug is exactly 4096 bytes (one page, no real
+                    const stat = await fs.stat(cgdbPath);
+                    // Schema-only cgdb is exactly 4096 bytes (one page, no real
                     // data). Real graphs are larger.
                     return stat.isFile() && stat.size > 4096;
                 }
@@ -916,14 +917,14 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     return false;
                 }
             })();
-            if (!isLbugMaterialized) {
+            if (!isCgdbMaterialized) {
                 if (stream) {
                     res.setHeader('Content-Type', 'application/x-ndjson; charset=utf-8');
                     res.flushHeaders();
                     res.write(JSON.stringify({
                         type: 'meta',
                         repoName: entry.name,
-                        note: 'no lbug file — graph not yet materialized',
+                        note: 'no cgdb file — graph not yet materialized',
                         nodeCount: 0,
                         relationshipCount: 0,
                     }) + '\n');
@@ -936,7 +937,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     nodes: [],
                     relationships: [],
                     stats: { nodes: 0, edges: 0 },
-                    note: 'no lbug file — graph not yet materialized',
+                    note: 'no cgdb file — graph not yet materialized',
                 });
                 return;
             }
@@ -958,7 +959,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.once('finish', markFinished);
                 res.once('close', abortStreaming);
                 try {
-                    await withLbugDb(lbugPath, async () => streamGraphNdjson(res, includeContent, abortController.signal));
+                    await withCgdbDb(cgdbPath, async () => streamGraphNdjson(res, includeContent, abortController.signal));
                     if (!abortController.signal.aborted && !res.writableEnded) {
                         res.end();
                     }
@@ -970,7 +971,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 }
                 return;
             }
-            const graph = await withLbugDb(lbugPath, async () => buildGraph(includeContent));
+            const graph = await withCgdbDb(cgdbPath, async () => buildGraph(includeContent));
             res.json(graph);
         }
         catch (err) {
@@ -1008,8 +1009,8 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(404).json({ error: 'Repository not found' });
                 return;
             }
-            const lbugPath = path.join(entry.storagePath, 'lbug');
-            const result = await withLbugDb(lbugPath, () => executeQuery(cypher));
+            const cgdbPath = path.join(entry.storagePath, 'cgdb');
+            const result = await withCgdbDb(cgdbPath, () => executeQuery(cypher));
             res.json({ result });
         }
         catch (err) {
@@ -1029,14 +1030,14 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(404).json({ error: 'Repository not found' });
                 return;
             }
-            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const cgdbPath = path.join(entry.storagePath, 'cgdb');
             const parsedLimit = Number(req.body.limit ?? 10);
             const limit = Number.isFinite(parsedLimit)
                 ? Math.max(1, Math.min(100, Math.trunc(parsedLimit)))
                 : 10;
             const mode = req.body.mode ?? 'hybrid';
             const enrich = req.body.enrich !== false; // default true
-            const results = await withLbugDb(lbugPath, async () => {
+            const results = await withCgdbDb(cgdbPath, async () => {
                 let searchResults;
                 if (mode === 'semantic') {
                     const { isEmbedderReady } = await import('../core/embeddings/embedder.js');
@@ -1054,7 +1055,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     }));
                 }
                 else if (mode === 'bm25') {
-                    searchResults = await searchFTSFromLbug(query, limit);
+                    searchResults = await searchFTSFromCgdb(query, limit);
                     searchResults = searchResults.map((r, i) => ({
                         ...r,
                         rank: i + 1,
@@ -1069,7 +1070,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         searchResults = await hybridSearch(query, limit, executeQuery, semSearch);
                     }
                     else {
-                        searchResults = await searchFTSFromLbug(query, limit);
+                        searchResults = await searchFTSFromCgdb(query, limit);
                     }
                 }
                 if (!enrich)
@@ -1229,8 +1230,8 @@ export const createServer = async (port, host = '127.0.0.1') => {
             const results = [];
             const repoRoot = path.resolve(entry.path);
             // Get file paths from the graph (lightweight — no content loaded)
-            const lbugPath = path.join(entry.storagePath, 'lbug');
-            const fileRows = await withLbugDb(lbugPath, () => executeQuery(`MATCH (n:File) WHERE n.content IS NOT NULL RETURN n.filePath AS filePath`));
+            const cgdbPath = path.join(entry.storagePath, 'cgdb');
+            const fileRows = await withCgdbDb(cgdbPath, () => executeQuery(`MATCH (n:File) WHERE n.content IS NOT NULL RETURN n.filePath AS filePath`));
             // Search files on disk one at a time (constant memory)
             for (const row of fileRows) {
                 if (results.length >= limit)
@@ -1601,12 +1602,12 @@ export const createServer = async (port, host = '127.0.0.1') => {
             // Run embedding pipeline asynchronously
             (async () => {
                 try {
-                    const lbugPath = path.join(entry.storagePath, 'lbug');
-                    await withLbugDb(lbugPath, async () => {
+                    const cgdbPath = path.join(entry.storagePath, 'cgdb');
+                    await withCgdbDb(cgdbPath, async () => {
                         const { runEmbeddingPipeline } = await import('../core/embeddings/embedding-pipeline.js');
                         // Fetch existing content hashes for incremental embedding.
-                        // Delegated to lbug-adapter which owns the DB query logic and legacy-fallback handling.
-                        const { fetchExistingEmbeddingHashes } = await import('../core/lbug/lbug-adapter.js');
+                        // Delegated to cgdb-adapter which owns the DB query logic and legacy-fallback handling.
+                        const { fetchExistingEmbeddingHashes } = await import('../core/cgdb/cgdb-adapter.js');
                         const existingEmbeddings = await fetchExistingEmbeddingHashes(executeQuery);
                         if (existingEmbeddings && existingEmbeddings.size > 0) {
                             console.log(`[embed] ${existingEmbeddings.size} nodes already embedded — incremental run with content-hash comparison`);
@@ -1717,7 +1718,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
             jobManager.dispose();
             embedJobManager.dispose();
             await cleanupMcp();
-            await closeLbug();
+            await closeCgdb();
             await backend.disconnect();
             process.exit(0);
         };

package/dist/storage/repo-manager.d.ts

@@ -36,10 +36,49 @@
  * so the registry stabilises over analyze/re-analyze cycles.
  */
 export declare const canonicalizePath: (p: string) => string;
+/**
+ * On-disk schema version for `.codragraph/cgdb` and `.codragraph/meta.json`.
+ *
+ *   1  — pre-RFC-0001-Phase-2 layout. Node tables have `content STRING`
+ *        but no `contentEncoding` column. Implicit/missing on existing
+ *        1.6.x and 1.7.x indexes (RepoMeta.schemaVersion was undefined).
+ *   2  — RFC 0001 Phase 2: every node table that has `content` also has
+ *        a `contentEncoding STRING DEFAULT 'none'` column. Writers may
+ *        opt into compression via `--compress brotli|zstd` (compression
+ *        is OFF by default, so existing readers keep working). Readers
+ *        decode based on the per-row encoding tag.
+ *
+ * Bumping this is the migration trigger: `runFullAnalysis` forces a
+ * full re-analyze when an existing index has a missing or older
+ * `schemaVersion` field, because adding a column to an existing
+ * LadybugDB table via ALTER is not validated end-to-end yet — fresh
+ * `CREATE NODE TABLE` is the supported path.
+ */
+export declare const INDEX_SCHEMA_VERSION: 2;
 export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
     indexedAt: string;
+    /**
+     * On-disk schema version (see {@link INDEX_SCHEMA_VERSION}). Absent on
+     * indexes written by 1.7.x or earlier; `runFullAnalysis` treats those
+     * as needing a full re-analyze when they're loaded by a 1.8+ CLI.
+     */
+    schemaVersion?: number;
+    /**
+     * RFC 0001 Phase 2 — the per-row content encoding chosen at the last
+     * `analyze --compress` invocation. `'none'` (or absent) means rows
+     * carry plain text; `'brotli'` / `'zstd'` means rows are compressed
+     * and consumers must decode. Persisted so query-time tooling can
+     * detect the compressed mode without sampling rows.
+     *
+     * Phase 2.5 hooks: `core/search/bm25-index.ts` reads this field at
+     * FTS-create time and drops `content` from the FTS property list
+     * when set to a non-`'none'` value (full-text search falls back to
+     * symbol-name matches). Embeddings and graph queries are unaffected
+     * — they decode at the read boundary.
+     */
+    compress?: 'none' | 'brotli' | 'zstd';
     /**
      * Canonical `origin` remote URL captured at index time. Used to
      * fingerprint the same logical repo across multiple on-disk clones
@@ -71,7 +110,7 @@ export interface RepoMeta {
 export interface IndexedRepo {
     repoPath: string;
     storagePath: string;
-    lbugPath: string;
+    cgdbPath: string;
     metaPath: string;
     meta: RepoMeta;
 }
@@ -101,7 +140,7 @@ export declare const getStoragePath: (repoPath: string) => string;
  */
 export declare const getStoragePaths: (repoPath: string) => {
     storagePath: string;
-    lbugPath: string;
+    cgdbPath: string;
     metaPath: string;
 };
 /**
@@ -114,7 +153,7 @@ export declare const hasKuzuIndex: (storagePath: string) => Promise<boolean>;
  *
  * Returns:
  *   found        — true if .codragraph/kuzu existed and was deleted
- *   needsReindex — true if kuzu existed but lbug does not (re-analyze required)
+ *   needsReindex — true if kuzu existed but cgdb does not (re-analyze required)
  *
  * Callers own the user-facing messaging; this function only deletes files.
  */

package/dist/storage/repo-manager.js

@@ -49,6 +49,25 @@ export const canonicalizePath = (p) => {
         return resolved;
     }
 };
+/**
+ * On-disk schema version for `.codragraph/cgdb` and `.codragraph/meta.json`.
+ *
+ *   1  — pre-RFC-0001-Phase-2 layout. Node tables have `content STRING`
+ *        but no `contentEncoding` column. Implicit/missing on existing
+ *        1.6.x and 1.7.x indexes (RepoMeta.schemaVersion was undefined).
+ *   2  — RFC 0001 Phase 2: every node table that has `content` also has
+ *        a `contentEncoding STRING DEFAULT 'none'` column. Writers may
+ *        opt into compression via `--compress brotli|zstd` (compression
+ *        is OFF by default, so existing readers keep working). Readers
+ *        decode based on the per-row encoding tag.
+ *
+ * Bumping this is the migration trigger: `runFullAnalysis` forces a
+ * full re-analyze when an existing index has a missing or older
+ * `schemaVersion` field, because adding a column to an existing
+ * LadybugDB table via ALTER is not validated end-to-end yet — fresh
+ * `CREATE NODE TABLE` is the supported path.
+ */
+export const INDEX_SCHEMA_VERSION = 2;
 const CODRAGRAPH_DIR = '.codragraph';
 // ─── Local Storage Helpers ─────────────────────────────────────────────
 /**
@@ -64,7 +83,7 @@ export const getStoragePaths = (repoPath) => {
     const storagePath = getStoragePath(repoPath);
     return {
         storagePath,
-        lbugPath: path.join(storagePath, 'lbug'),
+        cgdbPath: path.join(storagePath, 'cgdb'),
         metaPath: path.join(storagePath, 'meta.json'),
     };
 };
@@ -86,16 +105,16 @@ export const hasKuzuIndex = async (storagePath) => {
  *
  * Returns:
  *   found        — true if .codragraph/kuzu existed and was deleted
- *   needsReindex — true if kuzu existed but lbug does not (re-analyze required)
+ *   needsReindex — true if kuzu existed but cgdb does not (re-analyze required)
  *
  * Callers own the user-facing messaging; this function only deletes files.
  */
 export const cleanupOldKuzuFiles = async (storagePath) => {
     const oldPath = path.join(storagePath, 'kuzu');
-    const newPath = path.join(storagePath, 'lbug');
+    const newPath = path.join(storagePath, 'cgdb');
     try {
         await fs.stat(oldPath);
-        // Old kuzu file/dir exists — determine if lbug is already present
+        // Old kuzu file/dir exists — determine if cgdb is already present
         let needsReindex = false;
         try {
             await fs.stat(newPath);