gitnexus 1.4.5 → 1.4.7

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -1,5 +1,7 @@
 import { SupportedLanguages } from '../../../config/supported-languages.js';
+import { type MixedChainStep } from '../utils.js';
 import type { ConstructorBinding } from '../type-env.js';
+import type { NodeLabel } from '../../graph/types.js';
 interface ParsedNode {
     id: string;
     label: string;
@@ -21,7 +23,7 @@ interface ParsedRelationship {
     id: string;
     sourceId: string;
     targetId: string;
-    type: 'DEFINES' | 'HAS_METHOD';
+    type: 'DEFINES' | 'HAS_METHOD' | 'HAS_PROPERTY';
     confidence: number;
     reason: string;
 }
@@ -29,9 +31,10 @@ interface ParsedSymbol {
     filePath: string;
     name: string;
     nodeId: string;
-    type: string;
+    type: NodeLabel;
     parameterCount?: number;
     returnType?: string;
+    declaredType?: string;
     ownerId?: string;
 }
 export interface ExtractedImport {
@@ -57,13 +60,25 @@ export interface ExtractedCall {
     /** Resolved type name of the receiver (e.g., 'User' for user.save() when user: User) */
     receiverTypeName?: string;
     /**
-     * Chained call names when the receiver is itself a call expression.
-     * For `svc.getUser().save()`, the `save` ExtractedCall gets receiverCallChain = ['getUser']
-     * with receiverName = 'svc'.  The chain is ordered outermost-last, e.g.:
-     *   `a.b().c().d()` → calledName='d', receiverCallChain=['b','c'], receiverName='a'
+     * Unified mixed chain when the receiver is a chain of field accesses and/or method calls.
+     * Steps are ordered base-first (innermost to outermost). Examples:
+     *   `svc.getUser().save()`        → chain=[{kind:'call',name:'getUser'}], receiverName='svc'
+     *   `user.address.save()`         → chain=[{kind:'field',name:'address'}], receiverName='user'
+     *   `svc.getUser().address.save()` → chain=[{kind:'call',name:'getUser'},{kind:'field',name:'address'}]
      * Length is capped at MAX_CHAIN_DEPTH (3).
      */
-    receiverCallChain?: string[];
+    receiverMixedChain?: MixedChainStep[];
+}
+export interface ExtractedAssignment {
+    filePath: string;
+    /** generateId of enclosing function, or generateId('File', filePath) for top-level */
+    sourceId: string;
+    /** Receiver text (e.g., 'user' from user.address = value) */
+    receiverText: string;
+    /** Property name being written (e.g., 'address') */
+    propertyName: string;
+    /** Resolved type name of the receiver if available from TypeEnv */
+    receiverTypeName?: string;
 }
 export interface ExtractedHeritage {
     filePath: string;
@@ -93,6 +108,7 @@ export interface ParseWorkerResult {
     symbols: ParsedSymbol[];
     imports: ExtractedImport[];
     calls: ExtractedCall[];
+    assignments: ExtractedAssignment[];
     heritage: ExtractedHeritage[];
     routes: ExtractedRoute[];
     constructorBindings: FileConstructorBindings[];

package/dist/core/ingestion/workers/parse-worker.js

@@ -28,7 +28,7 @@ try {
     Kotlin = _require('tree-sitter-kotlin');
 }
 catch { }
-import { getLanguageFromFilename, FUNCTION_NODE_TYPES, extractFunctionName, isBuiltInOrNoise, getDefinitionNodeFromCaptures, findEnclosingClassId, extractMethodSignature, countCallArguments, inferCallForm, extractReceiverName, extractReceiverNode, CALL_EXPRESSION_TYPES, extractCallChain, } from '../utils.js';
+import { getLanguageFromFilename, FUNCTION_NODE_TYPES, extractFunctionName, isBuiltInOrNoise, getDefinitionNodeFromCaptures, findEnclosingClassId, extractMethodSignature, countCallArguments, inferCallForm, extractReceiverName, extractReceiverNode, extractMixedChain, } from '../utils.js';
 import { buildTypeEnv } from '../type-env.js';
 import { isNodeExported } from '../export-detection.js';
 import { detectFrameworkFromAST } from '../framework-detection.js';
@@ -37,6 +37,7 @@ import { generateId } from '../../../lib/utils.js';
 import { extractNamedBindings } from '../named-binding-extraction.js';
 import { appendKotlinWildcard } from '../resolvers/index.js';
 import { callRouters } from '../call-routing.js';
+import { extractPropertyDeclaredType } from '../type-extractors/shared.js';
 // ============================================================================
 // Worker-local parser + language map
 // ============================================================================
@@ -162,6 +163,7 @@ const processBatch = (files, onProgress) => {
         symbols: [],
         imports: [],
         calls: [],
+        assignments: [],
         heritage: [],
         routes: [],
         constructorBindings: [],
@@ -759,6 +761,28 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 });
                 continue;
             }
+            // Extract assignment sites (field write access)
+            if (captureMap['assignment'] && captureMap['assignment.receiver'] && captureMap['assignment.property']) {
+                const receiverText = captureMap['assignment.receiver'].text;
+                const propertyName = captureMap['assignment.property'].text;
+                if (receiverText && propertyName) {
+                    const srcId = findEnclosingFunctionId(captureMap['assignment'], file.path)
+                        || generateId('File', file.path);
+                    let receiverTypeName;
+                    if (typeEnv) {
+                        receiverTypeName = typeEnv.lookup(receiverText, captureMap['assignment']) ?? undefined;
+                    }
+                    result.assignments.push({
+                        filePath: file.path,
+                        sourceId: srcId,
+                        receiverText,
+                        propertyName,
+                        ...(receiverTypeName ? { receiverTypeName } : {}),
+                    });
+                }
+                if (!captureMap['call'])
+                    continue;
+            }
             // Extract call sites
             if (captureMap['call']) {
                 const callNameNode = captureMap['call.name'];
@@ -811,6 +835,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                                     nodeId,
                                     type: 'Property',
                                     ...(propEnclosingClassId ? { ownerId: propEnclosingClassId } : {}),
+                                    ...(item.declaredType ? { declaredType: item.declaredType } : {}),
                                 });
                                 const fileId = generateId('File', file.path);
                                 const relId = generateId('DEFINES', `${fileId}->${nodeId}`);
@@ -824,10 +849,10 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                                 });
                                 if (propEnclosingClassId) {
                                     result.relationships.push({
-                                        id: generateId('HAS_METHOD', `${propEnclosingClassId}->${nodeId}`),
+                                        id: generateId('HAS_PROPERTY', `${propEnclosingClassId}->${nodeId}`),
                                         sourceId: propEnclosingClassId,
                                         targetId: nodeId,
-                                        type: 'HAS_METHOD',
+                                        type: 'HAS_PROPERTY',
                                         confidence: 1.0,
                                         reason: '',
                                     });
@@ -844,26 +869,19 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                         const callForm = inferCallForm(callNode, callNameNode);
                         let receiverName = callForm === 'member' ? extractReceiverName(callNameNode) : undefined;
                         let receiverTypeName = receiverName ? typeEnv.lookup(receiverName, callNode) : undefined;
-                        let receiverCallChain;
-                        // When the receiver is a call_expression (e.g. svc.getUser().save()),
-                        // extractReceiverName returns undefined because it refuses complex expressions.
-                        // Instead, walk the receiver node to build a call chain for deferred resolution.
-                        // We capture the base receiver name so processCallsFromExtracted can look it up
-                        // from constructor bindings. receiverTypeName is intentionally left unset here —
-                        // the chain resolver in processCallsFromExtracted needs the base type as input and
-                        // produces the final receiver type as output.
+                        let receiverMixedChain;
+                        // When the receiver is a complex expression (call chain, field chain, or mixed),
+                        // extractReceiverName returns undefined. Walk the receiver node to build a unified
+                        // mixed chain for deferred resolution in processCallsFromExtracted.
                         if (callForm === 'member' && receiverName === undefined && !receiverTypeName) {
                             const receiverNode = extractReceiverNode(callNameNode);
-                            if (receiverNode && CALL_EXPRESSION_TYPES.has(receiverNode.type)) {
-                                const extracted = extractCallChain(receiverNode);
-                                if (extracted) {
-                                    receiverCallChain = extracted.chain;
-                                    // Set receiverName to the base object so Step 1 in processCallsFromExtracted
-                                    // can resolve it via constructor bindings to a base type for the chain.
+                            if (receiverNode) {
+                                const extracted = extractMixedChain(receiverNode);
+                                if (extracted && extracted.chain.length > 0) {
+                                    receiverMixedChain = extracted.chain;
                                     receiverName = extracted.baseReceiverName;
-                                    // Also try the type environment immediately (covers explicitly-typed locals
-                                    // and annotated parameters like `fn process(svc: &UserService)`).
-                                    // This sets a base type that chain resolution (Step 2) will use as input.
+                                    // Try the type environment immediately for the base receiver
+                                    // (covers explicitly-typed locals and annotated parameters).
                                     if (receiverName) {
                                         receiverTypeName = typeEnv.lookup(receiverName, callNode);
                                     }
@@ -878,7 +896,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                             ...(callForm !== undefined ? { callForm } : {}),
                             ...(receiverName !== undefined ? { receiverName } : {}),
                             ...(receiverTypeName !== undefined ? { receiverTypeName } : {}),
-                            ...(receiverCallChain !== undefined ? { receiverCallChain } : {}),
+                            ...(receiverMixedChain !== undefined ? { receiverMixedChain } : {}),
                         });
                     }
                 }
@@ -926,6 +944,21 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             const nodeLabel = getLabelFromCaptures(captureMap);
             if (!nodeLabel)
                 continue;
+            // C/C++: @definition.function is broad and also matches inline class methods (inside
+            // a class/struct body). Those are already captured by @definition.method, so skip
+            // the duplicate Function entry to prevent double-indexing in globalIndex.
+            if ((language === SupportedLanguages.CPlusPlus || language === SupportedLanguages.C) &&
+                nodeLabel === 'Function') {
+                let ancestor = captureMap['definition.function']?.parent;
+                while (ancestor) {
+                    if (ancestor.type === 'class_specifier' || ancestor.type === 'struct_specifier') {
+                        break; // inside a class body — duplicate of @definition.method
+                    }
+                    ancestor = ancestor.parent;
+                }
+                if (ancestor)
+                    continue; // found a class/struct ancestor → skip
+            }
             const nameNode = captureMap['name'];
             // Synthesize name for constructors without explicit @name capture (e.g. Swift init)
             if (!nameNode && nodeLabel !== 'Constructor')
@@ -948,18 +981,27 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 : null;
             let parameterCount;
             let returnType;
+            let declaredType;
             if (nodeLabel === 'Function' || nodeLabel === 'Method' || nodeLabel === 'Constructor') {
                 const sig = extractMethodSignature(definitionNode);
                 parameterCount = sig.parameterCount;
                 returnType = sig.returnType;
                 // Language-specific return type fallback (e.g. Ruby YARD @return [Type])
-                if (!returnType && definitionNode) {
+                // Also upgrades uninformative AST types like PHP `array` with PHPDoc `@return User[]`
+                if ((!returnType || returnType === 'array' || returnType === 'iterable') && definitionNode) {
                     const tc = typeConfigs[language];
                     if (tc?.extractReturnType) {
-                        returnType = tc.extractReturnType(definitionNode);
+                        const docReturn = tc.extractReturnType(definitionNode);
+                        if (docReturn)
+                            returnType = docReturn;
                     }
                 }
             }
+            else if (nodeLabel === 'Property' && definitionNode) {
+                // Extract the declared type for property/field nodes.
+                // Walk the definition node for type annotation children.
+                declaredType = extractPropertyDeclaredType(definitionNode);
+            }
             result.nodes.push({
                 id: nodeId,
                 label: nodeLabel,
@@ -990,6 +1032,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 type: nodeLabel,
                 ...(parameterCount !== undefined ? { parameterCount } : {}),
                 ...(returnType !== undefined ? { returnType } : {}),
+                ...(declaredType !== undefined ? { declaredType } : {}),
                 ...(enclosingClassId ? { ownerId: enclosingClassId } : {}),
             });
             const fileId = generateId('File', file.path);
@@ -1002,13 +1045,14 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 confidence: 1.0,
                 reason: '',
             });
-            // ── HAS_METHOD: link method/constructor/property to enclosing class ──
+            // ── HAS_METHOD / HAS_PROPERTY: link member to enclosing class ──
             if (enclosingClassId) {
+                const memberEdgeType = nodeLabel === 'Property' ? 'HAS_PROPERTY' : 'HAS_METHOD';
                 result.relationships.push({
-                    id: generateId('HAS_METHOD', `${enclosingClassId}->${nodeId}`),
+                    id: generateId(memberEdgeType, `${enclosingClassId}->${nodeId}`),
                     sourceId: enclosingClassId,
                     targetId: nodeId,
-                    type: 'HAS_METHOD',
+                    type: memberEdgeType,
                     confidence: 1.0,
                     reason: '',
                 });
@@ -1027,7 +1071,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
 /** Accumulated result across sub-batches */
 let accumulated = {
     nodes: [], relationships: [], symbols: [],
-    imports: [], calls: [], heritage: [], routes: [], constructorBindings: [], skippedLanguages: {}, fileCount: 0,
+    imports: [], calls: [], assignments: [], heritage: [], routes: [], constructorBindings: [], skippedLanguages: {}, fileCount: 0,
 };
 let cumulativeProcessed = 0;
 const mergeResult = (target, src) => {
@@ -1036,6 +1080,7 @@ const mergeResult = (target, src) => {
     target.symbols.push(...src.symbols);
     target.imports.push(...src.imports);
     target.calls.push(...src.calls);
+    target.assignments.push(...src.assignments);
     target.heritage.push(...src.heritage);
     target.routes.push(...src.routes);
     target.constructorBindings.push(...src.constructorBindings);
@@ -1061,7 +1106,7 @@ parentPort.on('message', (msg) => {
         if (msg && msg.type === 'flush') {
             parentPort.postMessage({ type: 'result', data: accumulated });
             // Reset for potential reuse
-            accumulated = { nodes: [], relationships: [], symbols: [], imports: [], calls: [], heritage: [], routes: [], constructorBindings: [], skippedLanguages: {}, fileCount: 0 };
+            accumulated = { nodes: [], relationships: [], symbols: [], imports: [], calls: [], assignments: [], heritage: [], routes: [], constructorBindings: [], skippedLanguages: {}, fileCount: 0 };
             cumulativeProcessed = 0;
             return;
         }

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

@@ -1,5 +1,7 @@
 import lbug from '@ladybugdb/core';
 import { KnowledgeGraph } from '../graph/types.js';
+/** Expose the current Database for pool adapter reuse in tests. */
+export declare const getDatabase: () => lbug.Database | null;
 export declare const initLbug: (dbPath: string) => Promise<{
     db: lbug.Database;
     conn: lbug.Connection;

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

@@ -9,6 +9,8 @@ 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();

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

@@ -11,7 +11,7 @@
 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 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)";

package/dist/core/lbug/schema.js

@@ -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
 // ============================================================================

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);
@@ -97,6 +120,14 @@ function restoreStdout() {
         process.stdout.write = realStdoutWrite;
     }
 }
+// Safety watchdog: restore stdout if it gets stuck silenced (e.g. native crash
+// inside createConnection before restoreStdout runs).
+setInterval(() => {
+    if (stdoutSilenceCount > 0 && !preWarmActive) {
+        stdoutSilenceCount = 0;
+        process.stdout.write = realStdoutWrite;
+    }
+}, 1000).unref();
 function createConnection(db) {
     silenceStdout();
     try {
@@ -112,9 +143,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 +158,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 +223,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 +248,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 +320,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 +346,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,6 +384,9 @@ 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);
     try {
@@ -309,3 +447,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);
+}

package/dist/mcp/local/local-backend.d.ts

@@ -144,6 +144,7 @@ export declare class LocalBackend {
      */
     private rename;
     private impact;
+    private _impactImpl;
     /**
      * Query clusters (communities) directly from graph.
      * Used by getClustersResource — avoids legacy overview() dispatch.