gitnexus 1.4.6 → 1.4.8

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

@@ -9,9 +9,27 @@ let db = null;
 let conn = null;
 let currentDbPath = null;
 let ftsLoaded = false;
+/** Expose the current Database for pool adapter reuse in tests. */
+export const getDatabase = () => db;
 // Global session lock for operations that touch module-level lbug globals.
 // This guarantees no DB switch can happen while an operation is running.
 let sessionLock = Promise.resolve();
+/** Number of times to retry on a BUSY / lock-held error before giving up. */
+const DB_LOCK_RETRY_ATTEMPTS = 3;
+/** Base back-off in ms between BUSY retries (multiplied by attempt number). */
+const DB_LOCK_RETRY_DELAY_MS = 500;
+/**
+ * Return true when the error message indicates that another process holds
+ * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
+ * `gitnexus serve` running at the same time).
+ */
+export const isDbBusyError = (err) => {
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (msg.includes('busy')
+        || msg.includes('lock')
+        || msg.includes('already in use')
+        || msg.includes('could not set lock'));
+};
 const runWithSessionLock = async (operation) => {
     const previous = sessionLock;
     let release = null;
@@ -33,12 +51,50 @@ export const initLbug = async (dbPath) => {
 /**
  * Execute multiple queries against one repo DB atomically.
  * While the callback runs, no other request can switch the active DB.
+ *
+ * Automatically retries up to DB_LOCK_RETRY_ATTEMPTS times when the
+ * database is busy (e.g. `gitnexus analyze` holds the write lock).
+ * Each retry waits DB_LOCK_RETRY_DELAY_MS * attempt milliseconds.
  */
 export const withLbugDb = async (dbPath, operation) => {
-    return runWithSessionLock(async () => {
-        await ensureLbugInitialized(dbPath);
-        return operation();
-    });
+    let lastError;
+    for (let attempt = 1; attempt <= DB_LOCK_RETRY_ATTEMPTS; attempt++) {
+        try {
+            return await runWithSessionLock(async () => {
+                await ensureLbugInitialized(dbPath);
+                return operation();
+            });
+        }
+        catch (err) {
+            lastError = err;
+            if (!isDbBusyError(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
+                throw err;
+            }
+            // Close stale connection inside the session lock to prevent race conditions
+            // with concurrent operations that might acquire the lock between cleanup steps
+            await runWithSessionLock(async () => {
+                try {
+                    if (conn)
+                        await conn.close();
+                }
+                catch { /* best-effort */ }
+                try {
+                    if (db)
+                        await db.close();
+                }
+                catch { /* best-effort */ }
+                conn = null;
+                db = null;
+                currentDbPath = null;
+                ftsLoaded = false;
+            });
+            // Sleep outside the lock — no need to block others while waiting
+            await new Promise(resolve => setTimeout(resolve, DB_LOCK_RETRY_DELAY_MS * attempt));
+        }
+    }
+    // This line is unreachable — the loop either returns or throws inside,
+    // but TypeScript needs an explicit throw to satisfy the return type.
+    throw lastError;
 };
 const ensureLbugInitialized = async (dbPath) => {
     if (conn && currentDbPath === dbPath) {
@@ -321,6 +377,9 @@ const getCopyQuery = (table, filePath) => {
     if (table === 'Process') {
         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}`;
+    }
     if (table === 'Method') {
         return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description, parameterCount, returnType) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
@@ -361,6 +420,10 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
         else if (label === 'Folder') {
             query = `CREATE (n:Folder {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}})`;
         }
+        else if (label === 'Section') {
+            const descPart = properties.description ? `, description: ${escapeValue(properties.description)}` : '';
+            query = `CREATE (n:Section {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, level: ${properties.level || 1}, content: ${escapeValue(properties.content || '')}${descPart}})`;
+        }
         else if (TABLES_WITH_EXPORTED.has(label)) {
             const descPart = properties.description ? `, description: ${escapeValue(properties.description)}` : '';
             query = `CREATE (n:${t} {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, isExported: ${!!properties.isExported}, content: ${escapeValue(properties.content || '')}${descPart}})`;
@@ -436,6 +499,10 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
                 else if (label === 'Folder') {
                     query = `MERGE (n:Folder {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}`;
                 }
+                else if (label === 'Section') {
+                    const descPart = properties.description ? `, n.description = ${escapeValue(properties.description)}` : '';
+                    query = `MERGE (n:Section {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.level = ${properties.level || 1}, n.content = ${escapeValue(properties.content || '')}${descPart}`;
+                }
                 else if (TABLES_WITH_EXPORTED.has(label)) {
                     const descPart = properties.description ? `, n.description = ${escapeValue(properties.description)}` : '';
                     query = `MERGE (n:${t} {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.isExported = ${!!properties.isExported}, n.content = ${escapeValue(properties.content || '')}${descPart}`;

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

@@ -8,10 +8,10 @@
  * This allows LLMs to write natural Cypher queries like:
  *   MATCH (f:Function)-[r:CodeRelation {type: 'CALLS'}]->(g:Function) RETURN f, g
  */
-export declare const NODE_TABLES: readonly ["File", "Folder", "Function", "Class", "Interface", "Method", "CodeElement", "Community", "Process", "Struct", "Enum", "Macro", "Typedef", "Union", "Namespace", "Trait", "Impl", "TypeAlias", "Const", "Static", "Property", "Record", "Delegate", "Annotation", "Constructor", "Template", "Module"];
+export declare const NODE_TABLES: readonly ["File", "Folder", "Function", "Class", "Interface", "Method", "CodeElement", "Community", "Process", "Section", "Struct", "Enum", "Macro", "Typedef", "Union", "Namespace", "Trait", "Impl", "TypeAlias", "Const", "Static", "Property", "Record", "Delegate", "Annotation", "Constructor", "Template", "Module"];
 export type NodeTableName = typeof NODE_TABLES[number];
 export declare const REL_TABLE_NAME = "CodeRelation";
-export declare const REL_TYPES: readonly ["CONTAINS", "DEFINES", "IMPORTS", "CALLS", "EXTENDS", "IMPLEMENTS", "HAS_METHOD", "OVERRIDES", "MEMBER_OF", "STEP_IN_PROCESS"];
+export declare const REL_TYPES: readonly ["CONTAINS", "DEFINES", "IMPORTS", "CALLS", "EXTENDS", "IMPLEMENTS", "HAS_METHOD", "HAS_PROPERTY", "ACCESSES", "OVERRIDES", "MEMBER_OF", "STEP_IN_PROCESS"];
 export type RelType = typeof REL_TYPES[number];
 export declare const EMBEDDING_TABLE_NAME = "CodeEmbedding";
 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)";
@@ -41,8 +41,10 @@ export declare const ANNOTATION_SCHEMA: string;
 export declare const CONSTRUCTOR_SCHEMA: string;
 export declare const TEMPLATE_SCHEMA: string;
 export declare const MODULE_SCHEMA: string;
-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 `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 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 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 `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 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 `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 `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  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
-export declare const EMBEDDING_SCHEMA = "\nCREATE NODE TABLE CodeEmbedding (\n  nodeId STRING,\n  embedding FLOAT[384],\n  PRIMARY KEY (nodeId)\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 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 `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 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 `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 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 `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 `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  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
+export declare const EMBEDDING_DIMS: number;
+export declare const EMBEDDING_SCHEMA: string;
 /**
  * Create vector index for semantic search
  * Uses HNSW (Hierarchical Navigable Small World) algorithm with cosine similarity

package/dist/core/lbug/schema.js

@@ -12,7 +12,7 @@
 // NODE TABLE NAMES
 // ============================================================================
 export const NODE_TABLES = [
-    'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement', 'Community', 'Process',
+    'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement', 'Community', 'Process', 'Section',
     // Multi-language support
     'Struct', 'Enum', 'Macro', 'Typedef', 'Union', 'Namespace', 'Trait', 'Impl',
     'TypeAlias', 'Const', 'Static', 'Property', 'Record', 'Delegate', 'Annotation', 'Constructor', 'Template', 'Module'
@@ -22,7 +22,7 @@ export const NODE_TABLES = [
 // ============================================================================
 export const REL_TABLE_NAME = 'CodeRelation';
 // Valid relation types
-export const REL_TYPES = ['CONTAINS', 'DEFINES', 'IMPORTS', 'CALLS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'OVERRIDES', 'MEMBER_OF', 'STEP_IN_PROCESS'];
+export const REL_TYPES = ['CONTAINS', 'DEFINES', 'IMPORTS', 'CALLS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'ACCESSES', 'OVERRIDES', 'MEMBER_OF', 'STEP_IN_PROCESS'];
 // ============================================================================
 // EMBEDDING TABLE
 // ============================================================================
@@ -171,6 +171,19 @@ export const ANNOTATION_SCHEMA = CODE_ELEMENT_BASE('Annotation');
 export const CONSTRUCTOR_SCHEMA = CODE_ELEMENT_BASE('Constructor');
 export const TEMPLATE_SCHEMA = CODE_ELEMENT_BASE('Template');
 export const MODULE_SCHEMA = CODE_ELEMENT_BASE('Module');
+// Markdown heading sections
+export const SECTION_SCHEMA = `
+CREATE NODE TABLE Section (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  level INT64,
+  content STRING,
+  description STRING,
+  PRIMARY KEY (id)
+)`;
 // ============================================================================
 // RELATION TABLE SCHEMA
 // Single table with 'type' property - connects all node tables
@@ -202,6 +215,7 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM File TO \`Constructor\`,
   FROM File TO \`Template\`,
   FROM File TO \`Module\`,
+  FROM File TO Section,
   FROM Folder TO Folder,
   FROM Folder TO File,
   FROM Function TO Function,
@@ -266,6 +280,8 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM \`Template\` TO Interface,
   FROM \`Template\` TO \`Constructor\`,
   FROM \`Module\` TO \`Module\`,
+  FROM Section TO Section,
+  FROM Section TO File,
   FROM CodeElement TO Community,
   FROM Interface TO Community,
   FROM Interface TO Function,
@@ -373,10 +389,16 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
 // EMBEDDING TABLE SCHEMA
 // Separate table for vector storage to avoid copy-on-write overhead
 // ============================================================================
+/** Embedding vector dimensions. Default 384 (snowflake-arctic-embed-xs). */
+const _rawDims = parseInt(process.env.GITNEXUS_EMBEDDING_DIMS ?? '384', 10);
+if (Number.isNaN(_rawDims) || _rawDims <= 0) {
+    throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${process.env.GITNEXUS_EMBEDDING_DIMS}"`);
+}
+export const EMBEDDING_DIMS = _rawDims;
 export const EMBEDDING_SCHEMA = `
 CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
   nodeId STRING,
-  embedding FLOAT[384],
+  embedding FLOAT[${EMBEDDING_DIMS}],
   PRIMARY KEY (nodeId)
 )`;
 /**
@@ -419,6 +441,8 @@ export const NODE_SCHEMA_QUERIES = [
     CONSTRUCTOR_SCHEMA,
     TEMPLATE_SCHEMA,
     MODULE_SCHEMA,
+    // Markdown support
+    SECTION_SCHEMA,
 ];
 export const REL_SCHEMA_QUERIES = [
     RELATION_SCHEMA,

package/dist/mcp/core/embedder.js

@@ -5,9 +5,9 @@
  * For MCP, we only need to compute query embeddings, not batch embed.
  */
 import { pipeline, env } from '@huggingface/transformers';
+import { isHttpMode, getHttpDimensions, httpEmbedQuery } from '../../core/embeddings/http-client.js';
 // Model config
 const MODEL_ID = 'Snowflake/snowflake-arctic-embed-xs';
-const EMBEDDING_DIMS = 384;
 // Module-level state for singleton pattern
 let embedderInstance = null;
 let isInitializing = false;
@@ -16,6 +16,9 @@ let initPromise = null;
  * Initialize the embedding model (lazy, on first search)
  */
 export const initEmbedder = async () => {
+    if (isHttpMode()) {
+        throw new Error('initEmbedder() should not be called in HTTP mode.');
+    }
     if (embedderInstance) {
         return embedderInstance;
     }
@@ -75,11 +78,14 @@ export const initEmbedder = async () => {
 /**
  * Check if embedder is ready
  */
-export const isEmbedderReady = () => embedderInstance !== null;
+export const isEmbedderReady = () => isHttpMode() || embedderInstance !== null;
 /**
  * Embed a query text for semantic search
  */
 export const embedQuery = async (query) => {
+    if (isHttpMode()) {
+        return httpEmbedQuery(query);
+    }
     const embedder = await initEmbedder();
     const result = await embedder(query, {
         pooling: 'mean',
@@ -90,7 +96,9 @@ export const embedQuery = async (query) => {
 /**
  * Get embedding dimensions
  */
-export const getEmbeddingDims = () => EMBEDDING_DIMS;
+export const getEmbeddingDims = () => {
+    return getHttpDimensions() ?? 384;
+};
 /**
  * Cleanup embedder
  */

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

@@ -12,11 +12,29 @@
  * @see https://docs.ladybugdb.com/concurrency — multiple Connections
  * from the same Database is the officially supported concurrency pattern.
  */
+import lbug from '@ladybugdb/core';
+/** Saved real stdout.write — used to silence LadybugDB native output without race conditions */
+export declare const realStdoutWrite: any;
 /**
  * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).
+ *
+ * Concurrent calls for the same repoId are deduplicated — the second caller
+ * awaits the first's in-progress init rather than starting a redundant one.
  */
 export declare const initLbug: (repoId: string, dbPath: string) => Promise<void>;
+/**
+ * Initialize a pool entry from a pre-existing Database object.
+ *
+ * Used in tests to avoid the writable→close→read-only cycle that crashes
+ * on macOS due to N-API destructor segfaults.  The pool adapter reuses
+ * the core adapter's writable Database instead of opening a new read-only one.
+ *
+ * The Database is registered in the shared dbCache so closeOne() decrements
+ * the refCount correctly.  If the Database is already cached (e.g. another
+ * repoId already injected it), the existing entry is reused.
+ */
+export declare function initLbugWithDb(repoId: string, existingDb: lbug.Database, dbPath: string): Promise<void>;
 export declare const executeQuery: (repoId: string, cypher: string) => Promise<any[]>;
 /**
  * Execute a parameterized query on a specific repo's connection pool.
@@ -33,3 +51,7 @@ export declare const closeLbug: (repoId?: string) => Promise<void>;
  * Check if a specific repo's pool is active
  */
 export declare const isLbugReady: (repoId: string) => boolean;
+/** Regex to detect write operations in user-supplied Cypher queries */
+export declare const CYPHER_WRITE_RE: RegExp;
+/** Check if a Cypher query contains write operations */
+export declare function isWriteQuery(query: string): boolean;

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

@@ -22,12 +22,12 @@ const MAX_POOL_SIZE = 5;
 const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 /** Max connections per repo (caps concurrent queries per repo) */
 const MAX_CONNS_PER_REPO = 8;
-/** Connections created eagerly on init */
-const INITIAL_CONNS_PER_REPO = 2;
 let idleTimer = null;
 /** Saved real stdout.write — used to silence LadybugDB native output without race conditions */
-const realStdoutWrite = process.stdout.write.bind(process.stdout);
+export const realStdoutWrite = process.stdout.write.bind(process.stdout);
 let stdoutSilenceCount = 0;
+/** True while pre-warming connections — prevents watchdog from prematurely restoring stdout */
+let preWarmActive = false;
 /**
  * Start the idle cleanup timer (runs every 60s)
  */
@@ -65,19 +65,42 @@ function evictLRU() {
     }
 }
 /**
- * Remove a repo from the pool and release its shared Database ref.
- *
- * LadybugDB's native .closeSync() triggers N-API destructor hooks that
- * segfault on Linux/macOS.  Pool databases are opened read-only, so
- * there is no WAL to flush — just deleting the pool entry and letting
- * the GC (or process exit) reclaim native resources is safe.
+ * Remove a repo from the pool, close its connections, and release its
+ * shared Database ref.  Only closes the Database when no other repoIds
+ * reference it (refCount === 0).
  */
 function closeOne(repoId) {
     const entry = pool.get(repoId);
-    if (entry) {
-        const shared = dbCache.get(entry.dbPath);
-        if (shared && shared.refCount > 0) {
-            shared.refCount--;
+    if (!entry)
+        return;
+    entry.closed = true;
+    // Close available connections — fire-and-forget with .catch() to prevent
+    // unhandled rejections.  Native close() returns Promise<void> but can crash
+    // the N-API destructor on macOS/Windows; deferring to process exit lets
+    // dangerouslyIgnoreUnhandledErrors absorb the crash.
+    for (const conn of entry.available) {
+        conn.close().catch(() => { });
+    }
+    entry.available.length = 0;
+    // Checked-out connections can't be closed here — they're in-flight.
+    // The checkin() function detects entry.closed and closes them on return.
+    // Only close the Database when no other repoIds reference it.
+    // External databases (injected via initLbugWithDb) are never closed here —
+    // the core adapter owns them and handles their lifecycle.
+    const shared = dbCache.get(entry.dbPath);
+    if (shared) {
+        shared.refCount--;
+        if (shared.refCount === 0) {
+            if (shared.external) {
+                // External databases are owned by the core adapter — don't close
+                // or remove from cache.  Keep the entry so future initLbug() calls
+                // for the same dbPath reuse it instead of hitting a file lock.
+                shared.refCount = 0;
+            }
+            else {
+                shared.db.close().catch(() => { });
+                dbCache.delete(entry.dbPath);
+            }
         }
     }
     pool.delete(repoId);
@@ -86,6 +109,7 @@ function closeOne(repoId) {
  * Create a new Connection from a repo's Database.
  * Silences stdout to prevent native module output from corrupting MCP stdio.
  */
+let activeQueryCount = 0;
 function silenceStdout() {
     if (stdoutSilenceCount++ === 0) {
         process.stdout.write = (() => true);
@@ -97,6 +121,16 @@ function restoreStdout() {
         process.stdout.write = realStdoutWrite;
     }
 }
+// Safety watchdog: restore stdout if it gets stuck silenced (e.g. native crash
+// inside createConnection before restoreStdout runs).
+// Exempts active queries and pre-warm — these legitimately hold silence for
+// longer than 1 second (queries can take up to QUERY_TIMEOUT_MS = 30s).
+setInterval(() => {
+    if (stdoutSilenceCount > 0 && !preWarmActive && activeQueryCount === 0) {
+        stdoutSilenceCount = 0;
+        process.stdout.write = realStdoutWrite;
+    }
+}, 1000).unref();
 function createConnection(db) {
     silenceStdout();
     try {
@@ -112,9 +146,14 @@ const QUERY_TIMEOUT_MS = 30_000;
 const WAITER_TIMEOUT_MS = 15_000;
 const LOCK_RETRY_ATTEMPTS = 3;
 const LOCK_RETRY_DELAY_MS = 2000;
+/** Deduplicates concurrent initLbug calls for the same repoId */
+const initPromises = new Map();
 /**
  * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).
+ *
+ * Concurrent calls for the same repoId are deduplicated — the second caller
+ * awaits the first's in-progress init rather than starting a redundant one.
  */
 export const initLbug = async (repoId, dbPath) => {
     const existing = pool.get(repoId);
@@ -122,6 +161,27 @@ export const initLbug = async (repoId, dbPath) => {
         existing.lastUsed = Date.now();
         return;
     }
+    // Deduplicate concurrent init calls for the same repoId —
+    // prevents double-init race when multiple parallel tool calls
+    // trigger initialization for the same repo simultaneously.
+    const pending = initPromises.get(repoId);
+    if (pending)
+        return pending;
+    const promise = doInitLbug(repoId, dbPath);
+    initPromises.set(repoId, promise);
+    try {
+        await promise;
+    }
+    finally {
+        initPromises.delete(repoId);
+    }
+};
+/**
+ * Internal init — creates DB, pre-warms connections, loads FTS, then registers pool.
+ * Pool entry is registered LAST so concurrent executeQuery calls see either
+ * "not initialized" (and throw) or a fully ready pool — never a half-built one.
+ */
+async function doInitLbug(repoId, dbPath) {
     // Check if database exists
     try {
         await fs.stat(dbPath);
@@ -166,14 +226,22 @@ export const initLbug = async (repoId, dbPath) => {
     }
     shared.refCount++;
     const db = shared.db;
-    // Pre-create a small pool of connections
+    // Pre-create the full pool upfront so createConnection() (which silences
+    // stdout) is never called lazily during active query execution.
+    // Mark preWarmActive so the watchdog timer doesn't interfere.
+    preWarmActive = true;
     const available = [];
-    for (let i = 0; i < INITIAL_CONNS_PER_REPO; i++) {
-        available.push(createConnection(db));
+    try {
+        for (let i = 0; i < MAX_CONNS_PER_REPO; i++) {
+            available.push(createConnection(db));
+        }
     }
-    pool.set(repoId, { db, available, checkedOut: 0, waiters: [], lastUsed: Date.now(), dbPath });
-    ensureIdleTimer();
-    // Load FTS extension once per shared Database
+    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');
@@ -183,7 +251,67 @@ export const initLbug = async (repoId, dbPath) => {
             // Extension may not be installed — FTS queries will fail gracefully
         }
     }
-};
+    // 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.
+    pool.set(repoId, { db, available, checkedOut: 0, waiters: [], lastUsed: Date.now(), dbPath, closed: false });
+    ensureIdleTimer();
+}
+/**
+ * Initialize a pool entry from a pre-existing Database object.
+ *
+ * Used in tests to avoid the writable→close→read-only cycle that crashes
+ * on macOS due to N-API destructor segfaults.  The pool adapter reuses
+ * the core adapter's writable Database instead of opening a new read-only one.
+ *
+ * The Database is registered in the shared dbCache so closeOne() decrements
+ * the refCount correctly.  If the Database is already cached (e.g. another
+ * repoId already injected it), the existing entry is reused.
+ */
+export async function initLbugWithDb(repoId, existingDb, dbPath) {
+    const existing = pool.get(repoId);
+    if (existing) {
+        existing.lastUsed = Date.now();
+        return;
+    }
+    // Register in dbCache with external: true so other initLbug() calls
+    // for the same dbPath reuse this Database instead of trying to open
+    // a new one (which would fail with a file lock error).
+    // closeOne() respects the external flag and skips db.close().
+    let shared = dbCache.get(dbPath);
+    if (!shared) {
+        shared = { db: existingDb, refCount: 0, ftsLoaded: false, external: true };
+        dbCache.set(dbPath, shared);
+    }
+    shared.refCount++;
+    const available = [];
+    preWarmActive = true;
+    try {
+        for (let i = 0; i < MAX_CONNS_PER_REPO; i++) {
+            available.push(createConnection(existingDb));
+        }
+    }
+    finally {
+        preWarmActive = false;
+    }
+    // Load FTS extension if not already loaded on this Database
+    try {
+        await available[0].query('LOAD EXTENSION fts');
+    }
+    catch {
+        // Extension may already be loaded or not installed
+    }
+    pool.set(repoId, {
+        db: existingDb,
+        available,
+        checkedOut: 0,
+        waiters: [],
+        lastUsed: Date.now(),
+        dbPath,
+        closed: false
+    });
+    ensureIdleTimer();
+}
 /**
  * Checkout a connection from the pool.
  * Returns an available connection, or creates a new one if under the cap.
@@ -195,11 +323,14 @@ function checkout(entry) {
         entry.checkedOut++;
         return Promise.resolve(entry.available.pop());
     }
-    // Grow the pool if under the cap
+    // Pool was pre-warmed to MAX_CONNS_PER_REPO during init.  If we're here
+    // with fewer total connections, something leaked — surface the bug rather
+    // than silently creating a connection (which would silence stdout mid-query).
     const totalConns = entry.available.length + entry.checkedOut;
     if (totalConns < MAX_CONNS_PER_REPO) {
-        entry.checkedOut++;
-        return Promise.resolve(createConnection(entry.db));
+        throw new Error(`Connection pool integrity error: expected ${MAX_CONNS_PER_REPO} ` +
+            `connections but found ${totalConns} (${entry.available.length} available, ` +
+            `${entry.checkedOut} checked out)`);
     }
     // At capacity — queue the caller with a timeout.
     return new Promise((resolve, reject) => {
@@ -218,10 +349,17 @@ function checkout(entry) {
 }
 /**
  * Return a connection to the pool after use.
+ * If the pool entry was closed while the connection was checked out (e.g.
+ * LRU eviction), close the orphaned connection instead of returning it.
  * If there are queued waiters, hand the connection directly to the next one
  * instead of putting it back in the available array (avoids race conditions).
  */
 function checkin(entry, conn) {
+    if (entry.closed) {
+        // Pool entry was deleted during checkout — close the orphaned connection
+        conn.close().catch(() => { });
+        return;
+    }
     if (entry.waiters.length > 0) {
         // Hand directly to the next waiter — no intermediate available state
         const waiter = entry.waiters.shift();
@@ -249,8 +387,13 @@ export const executeQuery = async (repoId, cypher) => {
     if (!entry) {
         throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initLbug first.`);
     }
+    if (isWriteQuery(cypher)) {
+        throw new Error('Write operations are not allowed. The pool adapter is read-only.');
+    }
     entry.lastUsed = Date.now();
     const conn = await checkout(entry);
+    silenceStdout();
+    activeQueryCount++;
     try {
         const queryResult = await withTimeout(conn.query(cypher), QUERY_TIMEOUT_MS, 'Query');
         const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
@@ -258,6 +401,8 @@ export const executeQuery = async (repoId, cypher) => {
         return rows;
     }
     finally {
+        activeQueryCount--;
+        restoreStdout();
         checkin(entry, conn);
     }
 };
@@ -272,6 +417,8 @@ export const executeParameterized = async (repoId, cypher, params) => {
     }
     entry.lastUsed = Date.now();
     const conn = await checkout(entry);
+    silenceStdout();
+    activeQueryCount++;
     try {
         const stmt = await withTimeout(conn.prepare(cypher), QUERY_TIMEOUT_MS, 'Prepare');
         if (!stmt.isSuccess()) {
@@ -284,6 +431,8 @@ export const executeParameterized = async (repoId, cypher, params) => {
         return rows;
     }
     finally {
+        activeQueryCount--;
+        restoreStdout();
         checkin(entry, conn);
     }
 };
@@ -309,3 +458,9 @@ export const closeLbug = async (repoId) => {
  * Check if a specific repo's pool is active
  */
 export const isLbugReady = (repoId) => pool.has(repoId);
+/** Regex to detect write operations in user-supplied Cypher queries */
+export const CYPHER_WRITE_RE = /\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH)\b/i;
+/** Check if a Cypher query contains write operations */
+export function isWriteQuery(query) {
+    return CYPHER_WRITE_RE.test(query);
+}