@codragraph/cli 1.6.4 → 2.1.0

package/dist/core/lbug/csv-generator.d.ts

@@ -13,6 +13,7 @@
  */
 import { KnowledgeGraph } from '../graph/types.js';
 import { NodeTableName } from './schema.js';
+import { type ContentEncoding } from '@codragraph/graphstore';
 export declare const sanitizeUTF8: (str: string) => string;
 export declare const escapeCSVField: (value: string | number | undefined | null) => string;
 export declare const escapeCSVNumber: (value: number | undefined | null, defaultValue?: number) => string;
@@ -25,9 +26,4 @@ export interface StreamedCSVResult {
     relCsvPath: string;
     relRows: number;
 }
-/**
- * Stream all CSV data directly to disk files.
- * Iterates graph nodes exactly ONCE — routes each node to the right writer.
- * File contents are lazy-read from disk with a generous LRU cache.
- */
-export declare const streamAllCSVsToDisk: (graph: KnowledgeGraph, repoPath: string, csvDir: string) => Promise<StreamedCSVResult>;
+export declare const streamAllCSVsToDisk: (graph: KnowledgeGraph, repoPath: string, csvDir: string, compress?: ContentEncoding) => Promise<StreamedCSVResult>;

package/dist/core/lbug/csv-generator.js

@@ -14,6 +14,7 @@
 import fs from 'fs/promises';
 import { createWriteStream } from 'fs';
 import path from 'path';
+import { encodeContent } from '@codragraph/graphstore';
 /** Flush buffered rows to disk every N rows */
 const FLUSH_EVERY = 500;
 // ============================================================================
@@ -184,7 +185,26 @@ class BufferedCSVWriter {
  * Iterates graph nodes exactly ONCE — routes each node to the right writer.
  * File contents are lazy-read from disk with a generous LRU cache.
  */
-export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
+/**
+ * Apply RFC 0001 Phase 2 content encoding. Returns the on-the-wire string
+ * + the encoding tag to write into the per-row `contentEncoding` column.
+ *
+ * `compress: undefined | 'none'` is the default — content goes through
+ * unchanged and the tag is `'none'` (matches the schema DEFAULT, so older
+ * readers and the schema-default behavior stay in agreement).
+ *
+ * Always writing the tag column (even as 'none') keeps the CSV / COPY /
+ * schema layouts uniform regardless of compression mode. The wasted bytes
+ * are negligible — a few characters per row vs the kilobytes of content
+ * the column is alongside.
+ */
+const applyEncoding = (content, compress) => {
+    if (!compress || compress === 'none') {
+        return { wireContent: content, tag: 'none' };
+    }
+    return { wireContent: encodeContent(content, compress), tag: compress };
+};
+export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, compress) => {
     // Remove stale CSVs from previous crashed runs, then recreate
     try {
         await fs.rm(csvDir, { recursive: true, force: true });
@@ -196,26 +216,29 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
     const prevMax = process.getMaxListeners();
     process.setMaxListeners(prevMax + 40);
     const contentCache = new FileContentCache(repoPath);
-    // Create writers for every node type up-front
-    const fileWriter = new BufferedCSVWriter(path.join(csvDir, 'file.csv'), 'id,name,filePath,content');
+    // Create writers for every node type up-front. Content-bearing tables
+    // carry an extra `contentEncoding` column right after `content` to
+    // match the Phase 2 schema layout. Tables without `content` (Folder,
+    // Community, Process, Route, Tool) are unchanged.
+    const fileWriter = new BufferedCSVWriter(path.join(csvDir, 'file.csv'), 'id,name,filePath,content,contentEncoding');
     const folderWriter = new BufferedCSVWriter(path.join(csvDir, 'folder.csv'), 'id,name,filePath');
-    const codeElementHeader = 'id,name,filePath,startLine,endLine,isExported,content,description';
+    const codeElementHeader = 'id,name,filePath,startLine,endLine,isExported,content,contentEncoding,description';
     const functionWriter = new BufferedCSVWriter(path.join(csvDir, 'function.csv'), codeElementHeader);
     const classWriter = new BufferedCSVWriter(path.join(csvDir, 'class.csv'), codeElementHeader);
     const interfaceWriter = new BufferedCSVWriter(path.join(csvDir, 'interface.csv'), codeElementHeader);
-    const methodHeader = 'id,name,filePath,startLine,endLine,isExported,content,description,parameterCount,returnType';
+    const methodHeader = 'id,name,filePath,startLine,endLine,isExported,content,contentEncoding,description,parameterCount,returnType';
     const methodWriter = new BufferedCSVWriter(path.join(csvDir, 'method.csv'), methodHeader);
     const codeElemWriter = new BufferedCSVWriter(path.join(csvDir, 'codeelement.csv'), codeElementHeader);
     const communityWriter = new BufferedCSVWriter(path.join(csvDir, 'community.csv'), 'id,label,heuristicLabel,keywords,description,enrichedBy,cohesion,symbolCount');
     const processWriter = new BufferedCSVWriter(path.join(csvDir, 'process.csv'), 'id,label,heuristicLabel,processType,stepCount,communities,entryPointId,terminalId');
     // Section nodes have an extra 'level' column
-    const sectionWriter = new BufferedCSVWriter(path.join(csvDir, 'section.csv'), 'id,name,filePath,startLine,endLine,level,content,description');
+    const sectionWriter = new BufferedCSVWriter(path.join(csvDir, 'section.csv'), 'id,name,filePath,startLine,endLine,level,content,contentEncoding,description');
     // Route nodes for API endpoint mapping
     const routeWriter = new BufferedCSVWriter(path.join(csvDir, 'route.csv'), 'id,name,filePath,responseKeys,errorKeys,middleware');
     // Tool nodes for MCP tool definitions
     const toolWriter = new BufferedCSVWriter(path.join(csvDir, 'tool.csv'), 'id,name,filePath,description');
     // Multi-language node types share the same CSV shape (no isExported column)
-    const multiLangHeader = 'id,name,filePath,startLine,endLine,content,description';
+    const multiLangHeader = 'id,name,filePath,startLine,endLine,content,contentEncoding,description';
     const MULTI_LANG_TYPES = [
         'Struct',
         'Enum',
@@ -259,11 +282,13 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
         switch (node.label) {
             case 'File': {
                 const content = await extractContent(node, contentCache);
+                const { wireContent, tag } = applyEncoding(content, compress);
                 await fileWriter.addRow([
                     escapeCSVField(node.id),
                     escapeCSVField(node.properties.name || ''),
                     escapeCSVField(node.properties.filePath || ''),
-                    escapeCSVField(content),
+                    escapeCSVField(wireContent),
+                    escapeCSVField(tag),
                 ].join(','));
                 break;
             }
@@ -306,6 +331,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
             }
             case 'Method': {
                 const content = await extractContent(node, contentCache);
+                const { wireContent, tag } = applyEncoding(content, compress);
                 await methodWriter.addRow([
                     escapeCSVField(node.id),
                     escapeCSVField(node.properties.name || ''),
@@ -313,7 +339,8 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
                     escapeCSVNumber(node.properties.startLine, -1),
                     escapeCSVNumber(node.properties.endLine, -1),
                     node.properties.isExported ? 'true' : 'false',
-                    escapeCSVField(content),
+                    escapeCSVField(wireContent),
+                    escapeCSVField(tag),
                     escapeCSVField(node.properties.description || ''),
                     escapeCSVNumber(node.properties.parameterCount, 0),
                     escapeCSVField(node.properties.returnType || ''),
@@ -322,6 +349,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
             }
             case 'Section': {
                 const content = await extractContent(node, contentCache);
+                const { wireContent, tag } = applyEncoding(content, compress);
                 await sectionWriter.addRow([
                     escapeCSVField(node.id),
                     escapeCSVField(node.properties.name || ''),
@@ -329,7 +357,8 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
                     escapeCSVNumber(node.properties.startLine, -1),
                     escapeCSVNumber(node.properties.endLine, -1),
                     escapeCSVNumber(node.properties.level, 1),
-                    escapeCSVField(content),
+                    escapeCSVField(wireContent),
+                    escapeCSVField(tag),
                     escapeCSVField(node.properties.description || ''),
                 ].join(','));
                 break;
@@ -366,6 +395,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
                 const writer = codeWriterMap[node.label];
                 if (writer) {
                     const content = await extractContent(node, contentCache);
+                    const { wireContent, tag } = applyEncoding(content, compress);
                     await writer.addRow([
                         escapeCSVField(node.id),
                         escapeCSVField(node.properties.name || ''),
@@ -373,7 +403,8 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
                         escapeCSVNumber(node.properties.startLine, -1),
                         escapeCSVNumber(node.properties.endLine, -1),
                         node.properties.isExported ? 'true' : 'false',
-                        escapeCSVField(content),
+                        escapeCSVField(wireContent),
+                        escapeCSVField(tag),
                         escapeCSVField(node.properties.description || ''),
                     ].join(','));
                 }
@@ -382,13 +413,15 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
                     const mlWriter = multiLangWriters.get(node.label);
                     if (mlWriter) {
                         const content = await extractContent(node, contentCache);
+                        const { wireContent, tag } = applyEncoding(content, compress);
                         await mlWriter.addRow([
                             escapeCSVField(node.id),
                             escapeCSVField(node.properties.name || ''),
                             escapeCSVField(node.properties.filePath || ''),
                             escapeCSVNumber(node.properties.startLine, -1),
                             escapeCSVNumber(node.properties.endLine, -1),
-                            escapeCSVField(content),
+                            escapeCSVField(wireContent),
+                            escapeCSVField(tag),
                             escapeCSVField(node.properties.description || ''),
                         ].join(','));
                     }

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_'))
@@ -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 {
@@ -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) {
@@ -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/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)
 )`;