@codragraph/cli 1.6.3 → 2.0.0

package/dist/core/lbug/lbug-adapter.d.ts

@@ -1,6 +1,7 @@
 import lbug from '@ladybugdb/core';
 import { KnowledgeGraph } from '../graph/types.js';
 import type { CachedEmbedding } from '../embeddings/types.js';
+import type { ContentEncoding } from '@codragraph/graphstore';
 /** Factory for creating WriteStreams — injectable for testing. */
 export type WriteStreamFactory = (filePath: string) => import('fs').WriteStream;
 /** Result of splitting the relationship CSV into per-label-pair files. */
@@ -51,7 +52,9 @@ export declare const initLbug: (dbPath: string) => Promise<{
  */
 export declare const withLbugDb: <T>(dbPath: string, operation: () => Promise<T>) => Promise<T>;
 export type LbugProgressCallback = (message: string) => void;
-export declare const loadGraphToLbug: (graph: KnowledgeGraph, repoPath: string, storagePath: string, onProgress?: LbugProgressCallback) => Promise<{
+export declare const loadGraphToLbug: (graph: KnowledgeGraph, repoPath: string, storagePath: string, onProgress?: LbugProgressCallback, options?: {
+    compress?: ContentEncoding;
+}) => Promise<{
     success: boolean;
     insertedRels: number;
     skippedRels: number;

package/dist/core/lbug/lbug-adapter.js

@@ -276,7 +276,7 @@ const doInitLbug = async (dbPath) => {
     const parentDir = path.dirname(dbPath);
     await fs.mkdir(parentDir, { recursive: true });
     db = new lbug.Database(dbPath);
-    conn = new lbug.Connection(db);
+    conn = trackConnection(new lbug.Connection(db));
     for (const schemaQuery of SCHEMA_QUERIES) {
         try {
             await conn.query(schemaQuery);
@@ -294,14 +294,14 @@ const doInitLbug = async (dbPath) => {
     currentDbPath = dbPath;
     return { db, conn };
 };
-export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress) => {
+export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress, options) => {
     if (!conn) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
     const log = onProgress || (() => { });
     const csvDir = path.join(storagePath, 'csv');
     log('Streaming CSVs to disk...');
-    const csvResult = await streamAllCSVsToDisk(graph, repoPath, csvDir);
+    const csvResult = await streamAllCSVsToDisk(graph, repoPath, csvDir, options?.compress);
     const validTables = new Set(NODE_TABLES);
     const getNodeLabel = (nodeId) => {
         if (nodeId.startsWith('comm_'))
@@ -322,7 +322,7 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
         try {
             await conn.query(copyQuery);
         }
-        catch (err) {
+        catch (_err) {
             try {
                 const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
                 await conn.query(retryQuery);
@@ -360,7 +360,7 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
             try {
                 await conn.query(copyQuery);
             }
-            catch (err) {
+            catch (_err) {
                 try {
                     const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
                     await conn.query(retryQuery);
@@ -504,8 +504,12 @@ const TABLES_WITH_EXPORTED = new Set([
 ]);
 const getCopyQuery = (table, filePath) => {
     const t = escapeTableName(table);
+    // RFC 0001 Phase 2: every content-bearing table also lists
+    // `contentEncoding` immediately after `content` to match the schema +
+    // CSV layout. Tables without a content column (Folder, Community,
+    // Process, Route, Tool) are unchanged.
     if (table === 'File') {
-        return `COPY ${t}(id, name, filePath, content) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+        return `COPY ${t}(id, name, filePath, content, contentEncoding) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'Folder') {
         return `COPY ${t}(id, name, filePath) FROM "${filePath}" ${COPY_CSV_OPTS}`;
@@ -517,7 +521,7 @@ const getCopyQuery = (table, filePath) => {
         return `COPY ${t}(id, label, heuristicLabel, processType, stepCount, communities, entryPointId, terminalId) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'Section') {
-        return `COPY ${t}(id, name, filePath, startLine, endLine, level, content, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+        return `COPY ${t}(id, name, filePath, startLine, endLine, level, content, contentEncoding, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'Route') {
         return `COPY ${t}(id, name, filePath, responseKeys, errorKeys, middleware) FROM "${filePath}" ${COPY_CSV_OPTS}`;
@@ -526,14 +530,14 @@ const getCopyQuery = (table, filePath) => {
         return `COPY ${t}(id, name, filePath, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'Method') {
-        return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description, parameterCount, returnType) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+        return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, contentEncoding, description, parameterCount, returnType) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     // TypeScript/JS code element tables have isExported; multi-language tables do not
     if (TABLES_WITH_EXPORTED.has(table)) {
-        return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+        return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, contentEncoding, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     // Multi-language tables (Struct, Impl, Trait, Macro, etc.)
-    return `COPY ${t}(id, name, filePath, startLine, endLine, content, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+    return `COPY ${t}(id, name, filePath, startLine, endLine, content, contentEncoding, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
 };
 /**
  * Insert a single node to LadybugDB
@@ -587,9 +591,10 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
         // Use per-query connection if dbPath provided (avoids lock conflicts)
         if (targetDbPath) {
             const tempDb = new lbug.Database(targetDbPath);
-            const tempConn = new lbug.Connection(tempDb);
+            const tempConn = trackConnection(new lbug.Connection(tempDb));
             try {
-                await tempConn.query(query);
+                const qr = await tempConn.query(query);
+                await closeQueryResult(qr);
                 return true;
             }
             finally {
@@ -635,7 +640,7 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
     };
     // Open a single connection for all inserts
     const tempDb = new lbug.Database(dbPath);
-    const tempConn = new lbug.Connection(tempDb);
+    const tempConn = trackConnection(new lbug.Connection(tempDb));
     let inserted = 0;
     let failed = 0;
     try {
@@ -671,7 +676,7 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
                 await tempConn.query(query);
                 inserted++;
             }
-            catch (e) {
+            catch (_e) {
                 // Don't console.error here - it corrupts MCP JSON-RPC on stderr
                 failed++;
             }
@@ -689,6 +694,83 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
     }
     return { inserted, failed };
 };
+/**
+ * Track every live QueryResult / PreparedStatement returned by the
+ * connection, and force-close them in `closeLbug()` BEFORE `conn.close()`
+ * runs.
+ *
+ * Why this exists: per upstream Kuzu issue #5316 the close-order is
+ *   QueryResult & PreparedStatement → Connection → Database
+ * Leaking any of these to GC means V8 finalizes the native handles AFTER
+ * `db.close()` has run, which corrupts memory and segfaults the process
+ * at exit (Windows: 0xC0000005, Linux: SIGSEGV). Kuzu was archived
+ * 2025-10-10 and LadybugDB inherits the same C++ core, so the
+ * close-discipline is on us — neither upstream is going to ship a fix.
+ *
+ * Per-call-site close (the `try/finally { closeQueryResult }` blocks
+ * below) handles the happy path. The tracking Set is a backstop for any
+ * call site that forgets, AND for the fire-and-forget DDL / COPY /
+ * extension-load queries that drop the QueryResult on the floor.
+ */
+const liveLbugHandles = new Set();
+const closeQueryResult = async (qr) => {
+    if (!qr)
+        return;
+    const candidates = Array.isArray(qr) ? qr : [qr];
+    for (const r of candidates) {
+        liveLbugHandles.delete(r);
+        try {
+            const close = r?.close;
+            if (typeof close === 'function')
+                await Promise.resolve(close.call(r));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+};
+const closeStmt = async (stmt) => {
+    if (!stmt)
+        return;
+    liveLbugHandles.delete(stmt);
+    try {
+        const close = stmt?.close;
+        if (typeof close === 'function')
+            await Promise.resolve(close.call(stmt));
+    }
+    catch {
+        /* best-effort */
+    }
+};
+/**
+ * Wrap `conn.query` and `conn.execute` to register every returned
+ * QueryResult in the live-handle tracker. PreparedStatements from
+ * `conn.prepare` are tracked the same way. Idempotent — safe to call
+ * twice on the same Connection.
+ */
+const trackConnection = (rawConn) => {
+    const c = rawConn;
+    if (c.__lbugTracked)
+        return rawConn;
+    c.__lbugTracked = true;
+    const wrap = (orig) => async function (...args) {
+        const qr = await orig.apply(this, args);
+        if (qr && typeof qr === 'object') {
+            if (Array.isArray(qr))
+                qr.forEach((r) => r && liveLbugHandles.add(r));
+            else
+                liveLbugHandles.add(qr);
+        }
+        return qr;
+    };
+    if (typeof c.query === 'function')
+        c.query = wrap(c.query);
+    if (typeof c.execute === 'function')
+        c.execute = wrap(c.execute);
+    if (typeof c.prepare === 'function')
+        c.prepare = wrap(c.prepare);
+    return rawConn;
+};
 export const executeQuery = async (cypher) => {
     if (!conn) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
@@ -697,8 +779,12 @@ export const executeQuery = async (cypher) => {
     // LadybugDB uses getAll() instead of hasNext()/getNext()
     // Query returns QueryResult for single queries, QueryResult[] for multi-statement
     const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-    const rows = await result.getAll();
-    return rows;
+    try {
+        return await result.getAll();
+    }
+    finally {
+        await closeQueryResult(queryResult);
+    }
 };
 export const streamQuery = async (cypher, onRow) => {
     if (!conn) {
@@ -735,11 +821,18 @@ export const executePrepared = async (cypher, params) => {
     const stmt = await conn.prepare(cypher);
     if (!stmt.isSuccess()) {
         const errMsg = await stmt.getErrorMessage();
+        await closeStmt(stmt);
         throw new Error(`Prepare failed: ${errMsg}`);
     }
     const queryResult = await conn.execute(stmt, params);
     const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-    return await result.getAll();
+    try {
+        return await result.getAll();
+    }
+    finally {
+        await closeQueryResult(queryResult);
+        await closeStmt(stmt);
+    }
 };
 export const executeWithReusedStatement = async (cypher, paramsList) => {
     if (!conn) {
@@ -753,18 +846,27 @@ export const executeWithReusedStatement = async (cypher, paramsList) => {
         const stmt = await conn.prepare(cypher);
         if (!stmt.isSuccess()) {
             const errMsg = await stmt.getErrorMessage();
+            await closeStmt(stmt);
             throw new Error(`Prepare failed: ${errMsg}`);
         }
         try {
             for (const params of subBatch) {
-                await conn.execute(stmt, params);
+                // `conn.execute` returns a QueryResult — close it as soon as
+                // we don't need its rows. Old code dropped the reference to GC,
+                // which is what segfaulted the process at exit on Windows
+                // (Kuzu issue #5316: QueryResult & PreparedStatement → Connection
+                // → Database close-order is required for native-binding safety).
+                const qr = await conn.execute(stmt, params);
+                await closeQueryResult(qr);
             }
         }
         catch (e) {
             // Log the error and continue with next batch
             console.warn('Batch execution error:', e);
         }
-        // Note: LadybugDB PreparedStatement doesn't require explicit close()
+        finally {
+            await closeStmt(stmt);
+        }
     }
 };
 export const getLbugStats = async () => {
@@ -772,8 +874,9 @@ export const getLbugStats = async () => {
         return { nodes: 0, edges: 0 };
     let totalNodes = 0;
     for (const tableName of NODE_TABLES) {
+        let queryResult;
         try {
-            const queryResult = await conn.query(`MATCH (n:${escapeTableName(tableName)}) RETURN count(n) AS cnt`);
+            queryResult = await conn.query(`MATCH (n:${escapeTableName(tableName)}) RETURN count(n) AS cnt`);
             const nodeResult = Array.isArray(queryResult) ? queryResult[0] : queryResult;
             const nodeRows = await nodeResult.getAll();
             if (nodeRows.length > 0) {
@@ -783,11 +886,15 @@ export const getLbugStats = async () => {
         catch {
             // ignore
         }
+        finally {
+            await closeQueryResult(queryResult);
+        }
     }
     let totalEdges = 0;
+    let edgeQueryResult;
     try {
-        const queryResult = await conn.query(`MATCH ()-[r:${REL_TABLE_NAME}]->() RETURN count(r) AS cnt`);
-        const edgeResult = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+        edgeQueryResult = await conn.query(`MATCH ()-[r:${REL_TABLE_NAME}]->() RETURN count(r) AS cnt`);
+        const edgeResult = Array.isArray(edgeQueryResult) ? edgeQueryResult[0] : edgeQueryResult;
         const edgeRows = await edgeResult.getAll();
         if (edgeRows.length > 0) {
             totalEdges = Number(edgeRows[0]?.cnt ?? edgeRows[0]?.[0] ?? 0);
@@ -796,6 +903,9 @@ export const getLbugStats = async () => {
     catch {
         // ignore
     }
+    finally {
+        await closeQueryResult(edgeQueryResult);
+    }
     return { nodes: totalNodes, edges: totalEdges };
 };
 /**
@@ -929,6 +1039,24 @@ export const fetchExistingEmbeddingHashes = async (execQuery) => {
     }
 };
 export const closeLbug = async () => {
+    // Drain every live QueryResult / PreparedStatement BEFORE closing the
+    // Connection or the Database. Required by upstream Kuzu (#5316) — the
+    // close-order is `QueryResult/PreparedStatement → Connection → Database`,
+    // and any outstanding handle held when `db.close()` runs corrupts memory
+    // and crashes the process at exit (Windows: 0xC0000005, POSIX: SIGSEGV).
+    // Snapshot the Set so concurrent close() calls don't deadlock the iteration.
+    const handles = Array.from(liveLbugHandles);
+    liveLbugHandles.clear();
+    for (const h of handles) {
+        try {
+            const close = h?.close;
+            if (typeof close === 'function')
+                await Promise.resolve(close.call(h));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
     if (conn) {
         try {
             await conn.close();
@@ -963,7 +1091,7 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
     let targetConn = conn;
     if (usePerQuery) {
         tempDb = new lbug.Database(dbPath);
-        tempConn = new lbug.Connection(tempDb);
+        tempConn = trackConnection(new lbug.Connection(tempDb));
         targetConn = tempConn;
     }
     else if (!conn) {
@@ -991,7 +1119,7 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
                     deletedNodes += count;
                 }
             }
-            catch (e) {
+            catch (_e) {
                 // Some tables may not support this query, skip
             }
         }
@@ -1148,8 +1276,9 @@ export const queryFTS = async (tableName, indexName, query, limit = 20, conjunct
     ORDER BY score DESC
     LIMIT ${limit}
   `;
+    let queryResult;
     try {
-        const queryResult = await conn.query(cypher);
+        queryResult = await conn.query(cypher);
         const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
         const rows = await result.getAll();
         return rows.map((row) => {
@@ -1171,6 +1300,9 @@ export const queryFTS = async (tableName, indexName, query, limit = 20, conjunct
         }
         throw e;
     }
+    finally {
+        await closeQueryResult(queryResult);
+    }
 };
 /**
  * Drop an FTS index

package/dist/core/lbug/pool-adapter.js

@@ -280,29 +280,18 @@ async function doInitLbug(repoId, dbPath) {
     finally {
         preWarmActive = false;
     }
-    // Load FTS extension once per shared Database.
-    // Done BEFORE pool registration so no concurrent checkout can grab
-    // the connection while the async FTS load is in progress.
-    if (!shared.ftsLoaded) {
-        try {
-            await available[0].query('LOAD EXTENSION fts');
-            shared.ftsLoaded = true;
-        }
-        catch {
-            // Extension may not be installed — FTS queries will fail gracefully
-        }
-    }
-    // Load VECTOR extension once per shared Database for semantic search support.
-    if (!shared.vectorLoaded) {
-        try {
-            await available[0].query('INSTALL VECTOR');
-            await available[0].query('LOAD EXTENSION VECTOR');
-            shared.vectorLoaded = true;
-        }
-        catch {
-            // VECTOR extension may not be available
-        }
-    }
+    // Load FTS + VECTOR extensions on EVERY connection in the pool.
+    //
+    // CRITICAL: LadybugDB's extension state is per-connection on macOS (and
+    // possibly other platforms) — loading on `available[0]` does NOT propagate
+    // to the other connections. Since checkout pops from the end of the array,
+    // queries would otherwise hit unloaded connections and `QUERY_FTS_INDEX`
+    // would silently return 0 rows (catch in queryFTSViaExecutor swallows the
+    // "extension not loaded" error). That broke every search on macOS.
+    //
+    // Load on all connections concurrently, but BEFORE the pool is registered
+    // so no checkout can race the load.
+    await loadExtensionsOnConnections(available, shared);
     // Register pool entry only after all connections are pre-warmed and FTS is
     // loaded.  Concurrent executeQuery calls see either "not initialized"
     // (and throw cleanly) or a fully ready pool — never a half-built one.
@@ -317,6 +306,42 @@ async function doInitLbug(repoId, dbPath) {
     });
     ensureIdleTimer();
 }
+/**
+ * Load FTS + VECTOR extensions on every connection in the pool.
+ * Per-connection load is required because LadybugDB's extension state is
+ * not always shared across connections of the same Database (observed on
+ * macOS native bindings — silent FTS failures otherwise).
+ */
+async function loadExtensionsOnConnections(conns, shared) {
+    // FTS: every connection needs `LOAD EXTENSION fts` independently.
+    await Promise.all(conns.map(async (c) => {
+        try {
+            await c.query('LOAD EXTENSION fts');
+        }
+        catch {
+            // already-loaded / not-installed — FTS queries fail gracefully if missing
+        }
+    }));
+    shared.ftsLoaded = true;
+    // VECTOR: install once on the Database (idempotent), then LOAD on every
+    // connection. INSTALL is a no-op after the first call but we run it on
+    // conn[0] to guarantee the package is present before fanning out LOADs.
+    try {
+        await conns[0].query('INSTALL VECTOR');
+    }
+    catch {
+        /* not available — semantic search will be a no-op */
+    }
+    await Promise.all(conns.map(async (c) => {
+        try {
+            await c.query('LOAD EXTENSION VECTOR');
+        }
+        catch {
+            /* not available — semantic search will be a no-op */
+        }
+    }));
+    shared.vectorLoaded = true;
+}
 /**
  * Initialize a pool entry from a pre-existing Database object.
  *
@@ -354,27 +379,9 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     finally {
         preWarmActive = false;
     }
-    // Load FTS extension if not already loaded on this Database
-    if (!shared.ftsLoaded) {
-        try {
-            await available[0].query('LOAD EXTENSION fts');
-            shared.ftsLoaded = true;
-        }
-        catch {
-            // Extension may already be loaded or not installed
-        }
-    }
-    // Load VECTOR extension for semantic search support
-    if (!shared.vectorLoaded) {
-        try {
-            await available[0].query('INSTALL VECTOR');
-            await available[0].query('LOAD EXTENSION VECTOR');
-            shared.vectorLoaded = true;
-        }
-        catch {
-            // VECTOR extension may not be available
-        }
-    }
+    // Load FTS + VECTOR on every connection (see loadExtensionsOnConnections
+    // for why per-connection load is required on macOS native bindings).
+    await loadExtensionsOnConnections(available, shared);
     pool.set(repoId, {
         db: existingDb,
         available,

package/dist/core/lbug/schema.d.ts

@@ -11,13 +11,13 @@
 import { NODE_TABLES, REL_TABLE_NAME, REL_TYPES, EMBEDDING_TABLE_NAME } from '../../_shared/index.js';
 export { NODE_TABLES, REL_TABLE_NAME, REL_TYPES, EMBEDDING_TABLE_NAME };
 export type { NodeTableName, RelType } from '../../_shared/index.js';
-export declare const FILE_SCHEMA = "\nCREATE NODE TABLE File (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  content STRING,\n  PRIMARY KEY (id)\n)";
+export declare const FILE_SCHEMA = "\nCREATE NODE TABLE File (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  content STRING,\n  contentEncoding STRING DEFAULT 'none',\n  PRIMARY KEY (id)\n)";
 export declare const FOLDER_SCHEMA = "\nCREATE NODE TABLE Folder (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  PRIMARY KEY (id)\n)";
-export declare const FUNCTION_SCHEMA = "\nCREATE NODE TABLE Function (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
-export declare const CLASS_SCHEMA = "\nCREATE NODE TABLE Class (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
-export declare const INTERFACE_SCHEMA = "\nCREATE NODE TABLE Interface (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
-export declare const METHOD_SCHEMA = "\nCREATE NODE TABLE Method (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  parameterCount INT32,\n  returnType STRING,\n  PRIMARY KEY (id)\n)";
-export declare const CODE_ELEMENT_SCHEMA = "\nCREATE NODE TABLE CodeElement (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
+export declare const FUNCTION_SCHEMA = "\nCREATE NODE TABLE Function (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  contentEncoding STRING DEFAULT 'none',\n  description STRING,\n  PRIMARY KEY (id)\n)";
+export declare const CLASS_SCHEMA = "\nCREATE NODE TABLE Class (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  contentEncoding STRING DEFAULT 'none',\n  description STRING,\n  PRIMARY KEY (id)\n)";
+export declare const INTERFACE_SCHEMA = "\nCREATE NODE TABLE Interface (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  contentEncoding STRING DEFAULT 'none',\n  description STRING,\n  PRIMARY KEY (id)\n)";
+export declare const METHOD_SCHEMA = "\nCREATE NODE TABLE Method (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  contentEncoding STRING DEFAULT 'none',\n  description STRING,\n  parameterCount INT32,\n  returnType STRING,\n  PRIMARY KEY (id)\n)";
+export declare const CODE_ELEMENT_SCHEMA = "\nCREATE NODE TABLE CodeElement (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  contentEncoding STRING DEFAULT 'none',\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const COMMUNITY_SCHEMA = "\nCREATE NODE TABLE Community (\n  id STRING,\n  label STRING,\n  heuristicLabel STRING,\n  keywords STRING[],\n  description STRING,\n  enrichedBy STRING,\n  cohesion DOUBLE,\n  symbolCount INT32,\n  PRIMARY KEY (id)\n)";
 export declare const PROCESS_SCHEMA = "\nCREATE NODE TABLE Process (\n  id STRING,\n  label STRING,\n  heuristicLabel STRING,\n  processType STRING,\n  stepCount INT32,\n  communities STRING[],\n  entryPointId STRING,\n  terminalId STRING,\n  PRIMARY KEY (id)\n)";
 export declare const STRUCT_SCHEMA: string;
@@ -41,7 +41,7 @@ export declare const TEMPLATE_SCHEMA: string;
 export declare const MODULE_SCHEMA: string;
 export declare const ROUTE_SCHEMA = "\nCREATE NODE TABLE Route (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  responseKeys STRING[],\n  errorKeys STRING[],\n  middleware STRING[],\n  PRIMARY KEY (id)\n)";
 export declare const TOOL_SCHEMA = "\nCREATE NODE TABLE Tool (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
-export declare const SECTION_SCHEMA = "\nCREATE NODE TABLE Section (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  level INT64,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
+export declare const SECTION_SCHEMA = "\nCREATE NODE TABLE Section (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  level INT64,\n  content STRING,\n  contentEncoding STRING DEFAULT 'none',\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const RELATION_SCHEMA = "\nCREATE REL TABLE CodeRelation (\n  FROM File TO File,\n  FROM File TO Folder,\n  FROM File TO Function,\n  FROM File TO Class,\n  FROM File TO Interface,\n  FROM File TO Method,\n  FROM File TO CodeElement,\n  FROM File TO `Struct`,\n  FROM File TO `Enum`,\n  FROM File TO `Macro`,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Trait`,\n  FROM File TO `Impl`,\n  FROM File TO `TypeAlias`,\n  FROM File TO `Const`,\n  FROM File TO `Static`,\n  FROM File TO `Variable`,\n  FROM File TO `Property`,\n  FROM File TO `Record`,\n  FROM File TO `Delegate`,\n  FROM File TO `Annotation`,\n  FROM File TO `Constructor`,\n  FROM File TO `Template`,\n  FROM File TO `Module`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO Function,\n  FROM Function TO Method,\n  FROM Function TO Class,\n  FROM Function TO Community,\n  FROM Function TO `Macro`,\n  FROM Function TO `Struct`,\n  FROM Function TO `Template`,\n  FROM Function TO `Enum`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `TypeAlias`,\n  FROM Function TO `Module`,\n  FROM Function TO `Impl`,\n  FROM Function TO Interface,\n  FROM Function TO `Constructor`,\n  FROM Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\n  FROM Function TO CodeElement,\n  FROM Class TO Method,\n  FROM Class TO Function,\n  FROM Class TO Class,\n  FROM Class TO Interface,\n  FROM Class TO Community,\n  FROM Class TO `Template`,\n  FROM Class TO `TypeAlias`,\n  FROM Class TO `Struct`,\n  FROM Class TO `Enum`,\n  FROM Class TO `Annotation`,\n  FROM Class TO `Constructor`,\n  FROM Class TO `Trait`,\n  FROM Class TO `Macro`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO `Property`,\n  FROM Method TO Function,\n  FROM Method TO Method,\n  FROM Method TO Class,\n  FROM Method TO Community,\n  FROM Method TO `Template`,\n  FROM Method TO `Struct`,\n  FROM Method TO `TypeAlias`,\n  FROM Method TO `Enum`,\n  FROM Method TO `Macro`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Module`,\n  FROM Method TO `Impl`,\n  FROM Method TO Interface,\n  FROM Method TO `Constructor`,\n  FROM Method TO `Property`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO `Module`,\n  FROM Section TO Section,\n  FROM Section TO File,\n  FROM File TO Route,\n  FROM Function TO Route,\n  FROM Method TO Route,\n  FROM File TO Tool,\n  FROM Function TO Tool,\n  FROM Method TO Tool,\n  FROM CodeElement TO Community,\n  FROM Interface TO Community,\n  FROM Interface TO Function,\n  FROM Interface TO Method,\n  FROM Interface TO Class,\n  FROM Interface TO Interface,\n  FROM Interface TO `TypeAlias`,\n  FROM Interface TO `Struct`,\n  FROM Interface TO `Constructor`,\n  FROM Interface TO `Property`,\n  FROM `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO `Struct`,\n  FROM `Struct` TO Class,\n  FROM `Struct` TO `Enum`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Struct` TO Interface,\n  FROM `Struct` TO `Constructor`,\n  FROM `Struct` TO `Property`,\n  FROM `Enum` TO `Enum`,\n  FROM `Enum` TO Community,\n  FROM `Enum` TO Class,\n  FROM `Enum` TO Interface,\n  FROM `Macro` TO Community,\n  FROM `Macro` TO Function,\n  FROM `Macro` TO Method,\n  FROM `Module` TO Function,\n  FROM `Module` TO Method,\n  FROM `Typedef` TO Community,\n  FROM `Union` TO Community,\n  FROM `Namespace` TO Community,\n  FROM `Namespace` TO `Struct`,\n  FROM `Trait` TO Method,\n  FROM `Trait` TO `Constructor`,\n  FROM `Trait` TO `Property`,\n  FROM `Trait` TO Community,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `TypeAlias` TO Community,\n  FROM `TypeAlias` TO `Trait`,\n  FROM `TypeAlias` TO Class,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Variable` TO Community,\n  FROM `Property` TO Community,\n  FROM `Record` TO Method,\n  FROM `Record` TO `Constructor`,\n  FROM `Record` TO `Property`,\n  FROM `Record` TO Community,\n  FROM `Delegate` TO Community,\n  FROM `Annotation` TO Community,\n  FROM `Constructor` TO Community,\n  FROM `Constructor` TO Interface,\n  FROM `Constructor` TO Class,\n  FROM `Constructor` TO Method,\n  FROM `Constructor` TO Function,\n  FROM `Constructor` TO `Constructor`,\n  FROM `Constructor` TO `Struct`,\n  FROM `Constructor` TO `Macro`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `TypeAlias`,\n  FROM `Constructor` TO `Enum`,\n  FROM `Constructor` TO `Annotation`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Module`,\n  FROM `Constructor` TO `Property`,\n  FROM `Constructor` TO `Typedef`,\n  FROM `Template` TO Community,\n  FROM `Module` TO Community,\n  FROM Function TO Process,\n  FROM Method TO Process,\n  FROM Class TO Process,\n  FROM Interface TO Process,\n  FROM `Struct` TO Process,\n  FROM `Constructor` TO Process,\n  FROM `Module` TO Process,\n  FROM `Macro` TO Process,\n  FROM `Impl` TO Process,\n  FROM `Typedef` TO Process,\n  FROM `TypeAlias` TO Process,\n  FROM `Enum` TO Process,\n  FROM `Union` TO Process,\n  FROM `Namespace` TO Process,\n  FROM `Trait` TO Process,\n  FROM `Const` TO Process,\n  FROM `Static` TO Process,\n  FROM `Variable` TO Process,\n  FROM `Property` TO Process,\n  FROM `Record` TO Process,\n  FROM `Delegate` TO Process,\n  FROM `Annotation` TO Process,\n  FROM `Template` TO Process,\n  FROM CodeElement TO Process,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
 export declare const EMBEDDING_DIMS: number;
 /** HNSW vector index name for the CodeEmbedding table. */

package/dist/core/lbug/schema.js

@@ -15,12 +15,23 @@ export { NODE_TABLES, REL_TABLE_NAME, REL_TYPES, EMBEDDING_TABLE_NAME };
 // ============================================================================
 // NODE TABLE SCHEMAS
 // ============================================================================
+// RFC 0001 Phase 2 — every node table that has `content STRING` also carries
+// `contentEncoding STRING DEFAULT 'none'`. Default keeps existing
+// uncompressed reads working (an empty/missing tag means "no decode
+// needed"); writers opt into compression by setting it to 'brotli' or
+// 'zstd' alongside the encoded bytes.
+//
+// Adding the column to every relevant table at once keeps the read path
+// simple — every `RETURN n.content` site can also `RETURN n.contentEncoding`
+// without per-table feature detection. Tables WITHOUT a content column
+// (Folder, Community, Process, Route, Tool) are intentionally not touched.
 export const FILE_SCHEMA = `
 CREATE NODE TABLE File (
   id STRING,
   name STRING,
   filePath STRING,
   content STRING,
+  contentEncoding STRING DEFAULT 'none',
   PRIMARY KEY (id)
 )`;
 export const FOLDER_SCHEMA = `
@@ -39,6 +50,7 @@ CREATE NODE TABLE Function (
   endLine INT64,
   isExported BOOLEAN,
   content STRING,
+  contentEncoding STRING DEFAULT 'none',
   description STRING,
   PRIMARY KEY (id)
 )`;
@@ -51,6 +63,7 @@ CREATE NODE TABLE Class (
   endLine INT64,
   isExported BOOLEAN,
   content STRING,
+  contentEncoding STRING DEFAULT 'none',
   description STRING,
   PRIMARY KEY (id)
 )`;
@@ -63,6 +76,7 @@ CREATE NODE TABLE Interface (
   endLine INT64,
   isExported BOOLEAN,
   content STRING,
+  contentEncoding STRING DEFAULT 'none',
   description STRING,
   PRIMARY KEY (id)
 )`;
@@ -75,6 +89,7 @@ CREATE NODE TABLE Method (
   endLine INT64,
   isExported BOOLEAN,
   content STRING,
+  contentEncoding STRING DEFAULT 'none',
   description STRING,
   parameterCount INT32,
   returnType STRING,
@@ -89,6 +104,7 @@ CREATE NODE TABLE CodeElement (
   endLine INT64,
   isExported BOOLEAN,
   content STRING,
+  contentEncoding STRING DEFAULT 'none',
   description STRING,
   PRIMARY KEY (id)
 )`;
@@ -135,6 +151,7 @@ CREATE NODE TABLE \`${name}\` (
   startLine INT64,
   endLine INT64,
   content STRING,
+  contentEncoding STRING DEFAULT 'none',
   description STRING,
   PRIMARY KEY (id)
 )`;
@@ -187,6 +204,7 @@ CREATE NODE TABLE Section (
   endLine INT64,
   level INT64,
   content STRING,
+  contentEncoding STRING DEFAULT 'none',
   description STRING,
   PRIMARY KEY (id)
 )`;

package/dist/core/run-analyze.d.ts

@@ -8,6 +8,7 @@
  * IMPORTANT: This module must NEVER call process.exit(). The caller (CLI
  * wrapper or server worker) is responsible for process lifecycle.
  */
+import type { ContentEncoding } from '@codragraph/graphstore';
 export interface AnalyzeCallbacks {
     onProgress: (phase: string, percent: number, message: string) => void;
     onLog?: (message: string) => void;
@@ -41,6 +42,18 @@ export interface AnalyzeOptions {
      * of a pipeline re-index.
      */
     allowDuplicateName?: boolean;
+    /**
+     * RFC 0001 Phase 2 — opt into per-row content compression. `'none'`
+     * (or undefined) writes plain text and the schema-default tag, exactly
+     * as pre-Phase-2 indexes do. `'brotli'` and `'zstd'` route every
+     * content field through `encodeContent` before it hits the CSV; the
+     * read path decodes via the per-row `contentEncoding` tag.
+     *
+     * Choosing `'zstd'` requires Node ≥ 22.15 on the indexer (the runtime
+     * that wrote the rows). Readers on older Node will get a clear
+     * forward-compat error rather than silently bad content.
+     */
+    compress?: ContentEncoding;
 }
 export interface AnalyzeResult {
     repoName: string;