gitnexus 1.6.10-rc.221 → 1.6.10-rc.222

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

@@ -122,6 +122,15 @@ export declare const initLbug: (repoId: string, dbPath: string) => Promise<boole
  * repoId already injected it), the existing entry is reused.
  */
 export declare function initLbugWithDb(repoId: string, existingDb: lbug.Database, dbPath: string): Promise<void>;
+/**
+ * Lazily load VECTOR for a semantic query.
+ *
+ * Exact graph reads never call this function, so opening their read pool does
+ * not probe or warn about an optional extension they do not use. The promise
+ * lives on SharedDB because extension scope is per Database, and also joins
+ * concurrent first semantic requests onto one LOAD attempt.
+ */
+export declare function ensureVectorExtension(repoId: string): Promise<boolean>;
 export declare const executeQuery: (repoId: string, cypher: string) => Promise<any[]>;
 /**
  * Execute a parameterized query on a specific repo's connection pool.

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

@@ -265,6 +265,7 @@ function closeOne(repoId) {
                 shared.refCount = 0;
                 shared.ftsLoaded = false;
                 shared.vectorLoaded = false;
+                shared.vectorLoadPromise = undefined;
             }
             else {
                 shared.db.close().catch(() => { });
@@ -692,13 +693,6 @@ async function doInitLbug(repoId, dbPath) {
     if (!shared.ftsLoaded) {
         shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
     }
-    // VECTOR too — extension load scope is per-Database, so this one load
-    // makes QUERY_VECTOR_INDEX legal on every pooled connection. Same
-    // load-only contract as FTS above; on failure the semantic-query lane
-    // falls back to the exact scan with its own diagnostic (#2623 follow-up).
-    if (!shared.vectorLoaded) {
-        shared.vectorLoaded = await loadVectorExtension(available[0], { policy: 'load-only' });
-    }
     // 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.
@@ -761,11 +755,6 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     if (!shared.ftsLoaded) {
         shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
     }
-    // VECTOR too — same per-Database scope and load-only contract as the
-    // doInitLbug site above (#2623 follow-up).
-    if (!shared.vectorLoaded) {
-        shared.vectorLoaded = await loadVectorExtension(available[0], { policy: 'load-only' });
-    }
     pool.set(repoId, {
         db: existingDb,
         available,
@@ -780,6 +769,143 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     ensureIdleTimer();
     traceRss('init', repoId);
 }
+/**
+ * Lazily load VECTOR for a semantic query.
+ *
+ * Exact graph reads never call this function, so opening their read pool does
+ * not probe or warn about an optional extension they do not use. The promise
+ * lives on SharedDB because extension scope is per Database, and also joins
+ * concurrent first semantic requests onto one LOAD attempt.
+ */
+export async function ensureVectorExtension(repoId) {
+    const entry = pool.get(repoId);
+    if (!entry) {
+        throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initLbug first.`);
+    }
+    const shared = dbCache.get(entry.dbPath);
+    if (!shared) {
+        throw new Error(`LadybugDB shared handle is unavailable for repo "${repoId}".`);
+    }
+    if (shared.vectorLoaded)
+        return true;
+    if (shared.vectorLoadPromise)
+        return shared.vectorLoadPromise;
+    const loadAttempt = (async () => {
+        const conn = await checkout(entry);
+        try {
+            const loaded = await loadVectorExtension(conn, { policy: 'load-only' });
+            shared.vectorLoaded = loaded;
+            return loaded;
+        }
+        finally {
+            checkin(entry, conn);
+        }
+    })();
+    const cachedAttempt = loadAttempt.catch((err) => {
+        // A transient checkout/load failure must not poison this Database for the
+        // rest of its lifetime. Keep resolved false cached, but let a later
+        // semantic request retry a rejected attempt.
+        if (shared.vectorLoadPromise === cachedAttempt) {
+            shared.vectorLoadPromise = undefined;
+        }
+        throw err;
+    });
+    shared.vectorLoadPromise = cachedAttempt;
+    return shared.vectorLoadPromise;
+}
+/**
+ * Detect an actual VECTOR procedure call without treating source text stored in
+ * Cypher literals or comments as executable syntax.
+ */
+function callsVectorIndex(cypher) {
+    if (!/QUERY_VECTOR_INDEX/i.test(cypher))
+        return false;
+    let code = '';
+    let state = 'code';
+    let backtickIdentifier = '';
+    for (let i = 0; i < cypher.length; i++) {
+        const ch = cypher[i];
+        const next = cypher[i + 1];
+        if (state === 'code') {
+            if (ch === "'" || ch === '"' || ch === '`') {
+                state = ch === "'" ? 'single' : ch === '"' ? 'double' : 'backtick';
+                if (state === 'backtick')
+                    backtickIdentifier = '';
+                code += ' ';
+            }
+            else if (ch === '/' && next === '/') {
+                state = 'line-comment';
+                code += '  ';
+                i++;
+            }
+            else if (ch === '/' && next === '*') {
+                state = 'block-comment';
+                code += '  ';
+                i++;
+            }
+            else {
+                code += ch;
+            }
+            continue;
+        }
+        if (state === 'line-comment') {
+            if (ch === '\n' || ch === '\r') {
+                state = 'code';
+                code += ch;
+            }
+            else {
+                code += ' ';
+            }
+            continue;
+        }
+        if (state === 'block-comment') {
+            if (ch === '*' && next === '/') {
+                state = 'code';
+                code += '  ';
+                i++;
+            }
+            else {
+                code += ch === '\n' || ch === '\r' ? ch : ' ';
+            }
+            continue;
+        }
+        if (state === 'backtick') {
+            if (ch === '`' && next === '`') {
+                backtickIdentifier += '`';
+                code += '  ';
+                i++;
+            }
+            else if (ch === '`') {
+                state = 'code';
+                code +=
+                    backtickIdentifier.toUpperCase() === 'QUERY_VECTOR_INDEX' ? 'QUERY_VECTOR_INDEX' : ' ';
+            }
+            else if (ch === '\\' && next !== undefined) {
+                backtickIdentifier += next;
+                code += '  ';
+                i++;
+            }
+            else {
+                backtickIdentifier += ch;
+                code += ch === '\n' || ch === '\r' ? ch : ' ';
+            }
+            continue;
+        }
+        if (ch === '\\') {
+            code += ' ';
+            if (next !== undefined) {
+                code += next === '\n' || next === '\r' ? next : ' ';
+                i++;
+            }
+            continue;
+        }
+        const closesLiteral = (state === 'single' && ch === "'") || (state === 'double' && ch === '"');
+        if (closesLiteral)
+            state = 'code';
+        code += ch === '\n' || ch === '\r' ? ch : ' ';
+    }
+    return /\bCALL\s+QUERY_VECTOR_INDEX\s*\(/i.test(code);
+}
 /**
  * Checkout a connection from the pool.
  * Returns an available connection, or creates a new one if under the cap.
@@ -870,12 +996,26 @@ export const executeParameterized = async (repoId, cypher, params) => {
     // a query built by splicing a caller-sized list names itself even when the
     // repo is not initialized. Never throws (#2915).
     warnIfQueryTextUnbounded(cypher, `pool executeParameterized (repo "${repoId}")`, (message) => poolSidecarLogger.warn(message));
-    const entry = pool.get(repoId);
+    let entry = pool.get(repoId);
     if (!entry) {
         throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initLbug first.`);
     }
-    entry.lastUsed = Date.now();
+    // Exact reads must not pay for VECTOR, but an explicit raw vector procedure
+    // call is a semantic read. Preflight before taking the query connection:
+    // ensureVectorExtension performs its own checkout, so holding one here could
+    // make a saturated pool wait for a connection that every caller is holding.
+    // A load rejection must not replace the query's own diagnostic.
+    if (callsVectorIndex(cypher)) {
+        await ensureVectorExtension(repoId).catch(() => false);
+        // The preflight suspends, so close/re-init may replace the pool entry.
+        // Re-read it before checkout to avoid querying through a stale handle.
+        entry = pool.get(repoId);
+        if (!entry) {
+            throw new Error(`LadybugDB connection pool closed for repo "${repoId}" (re-init/teardown); retry the query.`);
+        }
+    }
     const conn = await checkout(entry);
+    entry.lastUsed = Date.now();
     silenceStdout();
     activeQueryCount++;
     let queryResult;

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

@@ -256,12 +256,12 @@ export declare class LocalBackend {
      */
     private warnedSiblingDrift;
     /**
-     * One-shot stderr warning for the VECTOR-extension fallback. Without this
-     * guard the diagnostic would fire on every `semanticSearch()` call on
-     * platforms where the extension is unsupported (e.g. Windows), making MCP
-     * stderr noisy per DoD §2.8.
+     * One-shot stderr guards for distinct VECTOR load and index-query failures.
+     * Keeping them separate preserves both diagnostics across semanticSearch calls
+     * without repeating either on hot paths.
      */
-    private warnedVectorUnsupported;
+    private warnedVectorLoadFailed;
+    private warnedVectorQueryFailed;
     /**
      * One-shot warning when a pruned or Node-unloadable optional embedding stack
      * (#2370/#2372) forces semantic search to fall back to BM25 — so the

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

@@ -8,7 +8,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { createHash } from 'crypto';
-import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, statDbIdentity, dbIdentityChanged, } from '../../core/lbug/pool-adapter.js';
+import { initLbug, executeQuery, executeParameterized, ensureVectorExtension, closeLbug, isLbugReady, statDbIdentity, dbIdentityChanged, } from '../../core/lbug/pool-adapter.js';
 import { queryClassBeanMetadata } from './bean-metadata.js';
 import { querySpringAopMetadata } from './aop-metadata.js';
 import { queryConvexDispatchMetadata } from './convex-metadata.js';
@@ -783,12 +783,12 @@ export class LocalBackend {
      */
     warnedSiblingDrift = new Set();
     /**
-     * One-shot stderr warning for the VECTOR-extension fallback. Without this
-     * guard the diagnostic would fire on every `semanticSearch()` call on
-     * platforms where the extension is unsupported (e.g. Windows), making MCP
-     * stderr noisy per DoD §2.8.
+     * One-shot stderr guards for distinct VECTOR load and index-query failures.
+     * Keeping them separate preserves both diagnostics across semanticSearch calls
+     * without repeating either on hot paths.
      */
-    warnedVectorUnsupported = false;
+    warnedVectorLoadFailed = false;
+    warnedVectorQueryFailed = false;
     /**
      * One-shot warning when a pruned or Node-unloadable optional embedding stack
      * (#2370/#2372) forces semantic search to fall back to BM25 — so the
@@ -2518,17 +2518,25 @@ export class LocalBackend {
             this.lastQueryEmbeddingDims.set(repo.lbugPath, dims);
             const queryVecStr = `[${queryVec.join(',')}]`;
             const maxDistance = getVectorMaxDistance(DEFAULT_MCP_VECTOR_MAX_DISTANCE);
-            let bestChunks = new Map();
-            // Always TRY the vector lane — no platform gate. LadybugDB ships the
-            // VECTOR extension for every supported platform, Windows included
-            // (#2623 follow-up; the old `platform !== 'win32'` gate was stale), so
-            // whether the index is queryable is a per-machine runtime fact. The
-            // catch below is the fallback: any failure (extension unloadable, index
-            // absent, older DB) degrades to the exact scan with a once-per-backend
-            // diagnostic instead of being silently swallowed.
+            let vectorReady = false;
             try {
-                bestChunks = await collectBestChunks(limit, async (fetchLimit) => {
-                    const vectorQuery = `
+                vectorReady = await ensureVectorExtension(repo.lbugPath);
+            }
+            catch (err) {
+                if (!this.warnedVectorLoadFailed) {
+                    this.warnedVectorLoadFailed = true;
+                    logger.warn({ err }, 'GitNexus [query:vector]: vector extension load failed; using exact scan fallback');
+                }
+            }
+            let bestChunks = new Map();
+            // Try the vector lane only after its lazy load succeeds. An unavailable
+            // extension is already reported by ExtensionManager; an index/query
+            // failure below gets its own once-per-backend diagnostic before the exact
+            // scan fallback.
+            if (vectorReady) {
+                try {
+                    bestChunks = await collectBestChunks(limit, async (fetchLimit) => {
+                        const vectorQuery = `
             CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
               CAST(${queryVecStr} AS FLOAT[${dims}]), ${fetchLimit})
             YIELD node AS emb, distance
@@ -2538,24 +2546,25 @@ export class LocalBackend {
                    emb.startLine AS startLine, emb.endLine AS endLine, distance
             ORDER BY distance
           `;
-                    const embResults = await executeQuery(repo.lbugPath, vectorQuery);
-                    return embResults.map((row) => ({
-                        nodeId: row.nodeId ?? row[0],
-                        chunkIndex: row.chunkIndex ?? row[1] ?? 0,
-                        startLine: row.startLine ?? row[2] ?? 0,
-                        endLine: row.endLine ?? row[3] ?? 0,
-                        distance: row.distance ?? row[4],
-                    }));
-                });
-            }
-            catch (err) {
-                bestChunks = new Map();
-                if (!this.warnedVectorUnsupported) {
-                    // Rare diagnostic: surface why semantic search fell back to the
-                    // exact scan. Emitted once per `LocalBackend` instance lifetime to
-                    // avoid noisy stderr on hot semantic-search paths (DoD §2.8).
-                    this.warnedVectorUnsupported = true;
-                    logger.warn({ err }, 'GitNexus [query:vector]: vector index query failed; using exact scan fallback');
+                        const embResults = await executeQuery(repo.lbugPath, vectorQuery);
+                        return embResults.map((row) => ({
+                            nodeId: row.nodeId ?? row[0],
+                            chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+                            startLine: row.startLine ?? row[2] ?? 0,
+                            endLine: row.endLine ?? row[3] ?? 0,
+                            distance: row.distance ?? row[4],
+                        }));
+                    });
+                }
+                catch (err) {
+                    bestChunks = new Map();
+                    if (!this.warnedVectorQueryFailed) {
+                        // Rare diagnostic: surface why semantic search fell back to the
+                        // exact scan. Emitted once per `LocalBackend` instance lifetime to
+                        // avoid noisy stderr on hot semantic-search paths (DoD §2.8).
+                        this.warnedVectorQueryFailed = true;
+                        logger.warn({ err }, 'GitNexus [query:vector]: vector index query failed; using exact scan fallback');
+                    }
                 }
             }
             if (bestChunks.size === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.221",
+  "version": "1.6.10-rc.222",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",