gitnexus 1.6.4-rc.20 → 1.6.4-rc.22

package/dist/cli/analyze.d.ts

@@ -47,5 +47,9 @@ export interface AnalyzeOptions {
     maxFileSize?: string;
     /** Override worker sub-batch idle timeout in seconds. */
     workerTimeout?: string;
+    embeddingThreads?: string;
+    embeddingBatchSize?: string;
+    embeddingSubBatchSize?: string;
+    embeddingDevice?: string;
 }
 export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -64,6 +64,32 @@ export const analyzeCommand = async (inputPath, options) => {
         }
         process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(Math.round(workerTimeoutSeconds * 1000));
     }
+    const setPositiveEnv = (optionName, envName, value) => {
+        if (value === undefined)
+            return true;
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed <= 0) {
+            console.error(`  ${optionName} must be a positive integer.\n`);
+            process.exitCode = 1;
+            return false;
+        }
+        process.env[envName] = String(parsed);
+        return true;
+    };
+    if (!setPositiveEnv('--embedding-threads', 'GITNEXUS_EMBEDDING_THREADS', options?.embeddingThreads) ||
+        !setPositiveEnv('--embedding-batch-size', 'GITNEXUS_EMBEDDING_BATCH_SIZE', options?.embeddingBatchSize) ||
+        !setPositiveEnv('--embedding-sub-batch-size', 'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE', options?.embeddingSubBatchSize)) {
+        return;
+    }
+    if (options?.embeddingDevice) {
+        const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
+        if (!allowed.has(options.embeddingDevice)) {
+            console.error('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
+            process.exitCode = 1;
+            return;
+        }
+        process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
+    }
     console.log('\n  GitNexus Analyzer\n');
     let repoPath;
     if (inputPath) {

package/dist/cli/doctor.d.ts

@@ -0,0 +1 @@
+export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -0,0 +1,31 @@
+import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
+import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
+import { isHttpMode } from '../core/embeddings/http-client.js';
+export const doctorCommand = async () => {
+    const fingerprint = getRuntimeFingerprint();
+    const capabilities = getRuntimeCapabilities();
+    const embeddingConfig = resolveEmbeddingConfig();
+    console.log('GitNexus Doctor\n');
+    console.log('Runtime');
+    console.log(`  OS:        ${fingerprint.platform}/${fingerprint.arch}`);
+    console.log(`  Node:      ${fingerprint.node}`);
+    console.log(`  GitNexus:  ${fingerprint.gitnexus}`);
+    console.log(`  LadybugDB: ${fingerprint.ladybugdb ?? 'unknown'}`);
+    console.log(`  ONNX:      ${fingerprint.onnxruntime ?? 'unknown'}`);
+    console.log('');
+    console.log('Capabilities');
+    console.log(`  Graph store:     ${capabilities.graph}`);
+    console.log(`  Full-text search:${capabilities.fts.padStart(10)}`);
+    console.log(`  VECTOR index:    ${capabilities.vector}`);
+    console.log(`  Semantic mode:   ${capabilities.semanticMode}`);
+    console.log(`  Exact scan limit:${String(capabilities.exactScanLimit).padStart(9)} chunks`);
+    if (capabilities.reason)
+        console.log(`  Note:            ${capabilities.reason}`);
+    console.log('');
+    console.log('Embeddings');
+    console.log(`  Backend:   ${isHttpMode() ? 'http' : 'local'}`);
+    console.log(`  Device:    ${embeddingConfig.device}`);
+    console.log(`  Threads:   ${embeddingConfig.threads}`);
+    console.log(`  Batch:     ${embeddingConfig.batchSize} nodes`);
+    console.log(`  Sub-batch: ${embeddingConfig.subBatchSize} chunks`);
+};

package/dist/cli/index.js

@@ -31,11 +31,17 @@ program
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .option('--max-file-size <kb>', 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).')
     .option('--worker-timeout <seconds>', 'Worker sub-batch idle timeout before retry/fallback. Default: 30.')
+    .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
+    .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
+    .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
+    .option('--embedding-device <device>', 'Embedding device: auto, cpu, dml, cuda, or wasm')
     .addHelpText('after', '\nEnvironment variables:\n' +
     '  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n' +
     '  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
     '  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n' +
     '  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n' +
+    '  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n' +
+    '  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n' +
     '\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n' +
     '     `!__tests__/` to index a directory that is auto-filtered by default (#771).')
     .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
@@ -63,6 +69,10 @@ program
     .command('status')
     .description('Show index status for current repo')
     .action(createLazyAction(() => import('./status.js'), 'statusCommand'));
+program
+    .command('doctor')
+    .description('Show runtime platform capabilities and embedding configuration')
+    .action(createLazyAction(() => import('./doctor.js'), 'doctorCommand'));
 program
     .command('clean')
     .description('Delete GitNexus index for current repo')

package/dist/core/embeddings/config.d.ts

@@ -0,0 +1,2 @@
+import { type EmbeddingConfig } from './types.js';
+export declare const resolveEmbeddingConfig: (overrides?: Partial<EmbeddingConfig>) => EmbeddingConfig;

package/dist/core/embeddings/config.js

@@ -0,0 +1,36 @@
+import { defaultEmbeddingThreads } from '../platform/capabilities.js';
+import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
+const parsePositiveInt = (name, value, fallback) => {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a positive integer, got "${value}"`);
+    }
+    return parsed;
+};
+const parseDevice = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (value === 'auto' ||
+        value === 'dml' ||
+        value === 'cuda' ||
+        value === 'cpu' ||
+        value === 'wasm') {
+        return value;
+    }
+    throw new Error(`embedding device must be one of auto, dml, cuda, cpu, wasm; got "${value}"`);
+};
+export const resolveEmbeddingConfig = (overrides = {}) => {
+    const env = process.env;
+    return {
+        ...DEFAULT_EMBEDDING_CONFIG,
+        ...overrides,
+        batchSize: parsePositiveInt('GITNEXUS_EMBEDDING_BATCH_SIZE', env.GITNEXUS_EMBEDDING_BATCH_SIZE, overrides.batchSize ?? DEFAULT_EMBEDDING_CONFIG.batchSize),
+        subBatchSize: parsePositiveInt('GITNEXUS_EMBEDDING_SUB_BATCH_SIZE', env.GITNEXUS_EMBEDDING_SUB_BATCH_SIZE, overrides.subBatchSize ?? DEFAULT_EMBEDDING_CONFIG.subBatchSize),
+        threads: parsePositiveInt('GITNEXUS_EMBEDDING_THREADS', env.GITNEXUS_EMBEDDING_THREADS, overrides.threads ?? defaultEmbeddingThreads()),
+        device: parseDevice(env.GITNEXUS_EMBEDDING_DEVICE) ??
+            overrides.device ??
+            DEFAULT_EMBEDDING_CONFIG.device,
+    };
+};

package/dist/core/embeddings/embedder.js

@@ -20,6 +20,7 @@ import { join, dirname } from 'path';
 import { createRequire } from 'module';
 import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
 import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
+import { resolveEmbeddingConfig } from './config.js';
 /**
  * Check whether the onnxruntime-node package that @huggingface/transformers
  * will actually load at runtime ships the CUDA execution provider.
@@ -120,13 +121,12 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
         return initPromise;
     }
     isInitializing = true;
-    const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
-    // On Windows, use DirectML for GPU acceleration (via DirectX12)
-    // CUDA is only available on Linux x64 with onnxruntime-node
+    const finalConfig = resolveEmbeddingConfig(config);
+    // CUDA is probe-gated because ONNX Runtime can crash in native code when
+    // provider libraries are missing. DirectML stays opt-in for the same reason.
     // Probe for CUDA first — ONNX Runtime crashes (uncatchable native error)
     // if we attempt CUDA without the required shared libraries
-    const isWindows = process.platform === 'win32';
-    const gpuDevice = isWindows ? 'dml' : isCudaAvailable() ? 'cuda' : 'cpu';
+    const gpuDevice = isCudaAvailable() ? 'cuda' : 'cpu';
     const requestedDevice = forceDevice || (finalConfig.device === 'auto' ? gpuDevice : finalConfig.device);
     initPromise = (async () => {
         try {
@@ -176,7 +176,12 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
                         device: device,
                         dtype: 'fp32',
                         progress_callback: progressCallback,
-                        session_options: { logSeverityLevel: 3 },
+                        session_options: {
+                            logSeverityLevel: 3,
+                            intraOpNumThreads: finalConfig.threads,
+                            interOpNumThreads: 1,
+                            executionMode: 'sequential',
+                        },
                     });
                     currentDevice = device;
                     if (isDev) {

package/dist/core/embeddings/embedding-pipeline.d.ts

@@ -37,6 +37,12 @@ export declare const batchInsertEmbeddings: (executeWithReusedStatement: (cypher
     embedding: number[];
     contentHash?: string;
 }>) => Promise<void>;
+export interface EmbeddingPipelineResult {
+    nodesProcessed: number;
+    chunksProcessed: number;
+    vectorIndexReady: boolean;
+    semanticMode: 'vector-index' | 'exact-scan';
+}
 /**
  * Run the embedding pipeline
  *
@@ -51,7 +57,7 @@ export declare const batchInsertEmbeddings: (executeWithReusedStatement: (cypher
  *        and re-embedded; nodes not in the map are embedded fresh.
 
  */
-export declare const runEmbeddingPipeline: (executeQuery: (cypher: string) => Promise<any[]>, executeWithReusedStatement: (cypher: string, paramsList: Array<Record<string, any>>) => Promise<void>, onProgress: EmbeddingProgressCallback, config?: Partial<EmbeddingConfig>, skipNodeIds?: Set<string>, context?: EmbeddingContext, existingEmbeddings?: Map<string, string>) => Promise<void>;
+export declare const runEmbeddingPipeline: (executeQuery: (cypher: string) => Promise<any[]>, executeWithReusedStatement: (cypher: string, paramsList: Array<Record<string, any>>) => Promise<void>, onProgress: EmbeddingProgressCallback, config?: Partial<EmbeddingConfig>, skipNodeIds?: Set<string>, context?: EmbeddingContext, existingEmbeddings?: Map<string, string>) => Promise<EmbeddingPipelineResult>;
 /**
  * Perform semantic search using the vector index with chunk deduplication
  */

package/dist/core/embeddings/embedding-pipeline.js

@@ -13,10 +13,21 @@ import { initEmbedder, embedBatch, embedText, embeddingToArray, isEmbedderReady,
 import { generateEmbeddingText } from './text-generator.js';
 import { chunkNode, characterChunk } from './chunker.js';
 import { extractStructuralNames } from './structural-extractor.js';
-import { DEFAULT_EMBEDDING_CONFIG, EMBEDDABLE_LABELS, isShortLabel, LABEL_METHOD, LABELS_WITH_EXPORTED, STRUCTURAL_LABELS, collectBestChunks, } from './types.js';
+import { EMBEDDABLE_LABELS, isShortLabel, LABEL_METHOD, LABELS_WITH_EXPORTED, STRUCTURAL_LABELS, collectBestChunks, } from './types.js';
+import { resolveEmbeddingConfig } from './config.js';
+import { rankExactEmbeddingRows } from './exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from '../lbug/schema.js';
 import { loadVectorExtension } from '../lbug/lbug-adapter.js';
+import { getExactScanLimit } from '../platform/capabilities.js';
 const isDev = process.env.NODE_ENV === 'development';
+const vectorUnavailableMessage = 'VECTOR extension is unavailable for this LadybugDB runtime; semantic search will use exact scan when embeddings exist.';
+const ensureVectorExtensionAvailable = async () => {
+    const vectorReady = await loadVectorExtension();
+    if (!vectorReady) {
+        return false;
+    }
+    return true;
+};
 /**
  * Bump this when the embedding text template changes in a way that should
  * invalidate existing vectors, such as metadata/header shape changes,
@@ -132,18 +143,17 @@ export const batchInsertEmbeddings = async (executeWithReusedStatement, updates)
 
  */
 const createVectorIndex = async (executeQuery) => {
-    // Delegate to the adapter which tracks loaded state and handles DB reconnect resets.
-    // If the optional VECTOR extension cannot be loaded, semantic search degrades gracefully.
-    if (!(await loadVectorExtension())) {
-        return;
-    }
+    if (!(await ensureVectorExtensionAvailable()))
+        return false;
     try {
         await executeQuery(CREATE_VECTOR_INDEX_QUERY);
+        return true;
     }
     catch (error) {
         if (isDev) {
             console.warn('Vector index creation warning:', error);
         }
+        return false;
     }
 };
 /**
@@ -161,8 +171,12 @@ const createVectorIndex = async (executeQuery) => {
 
  */
 export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatement, onProgress, config = {}, skipNodeIds, context, existingEmbeddings) => {
-    const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
+    const finalConfig = resolveEmbeddingConfig(config);
+    let totalChunks = 0;
     try {
+        const vectorAvailable = await ensureVectorExtensionAvailable();
+        if (!vectorAvailable && isDev)
+            console.warn(vectorUnavailableMessage);
         // Phase 1: Load embedding model
         onProgress({
             phase: 'loading-model',
@@ -250,21 +264,25 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             // Ensure the vector index exists even when no new nodes need embedding.
             // A prior crash or first-time incremental run may have left CodeEmbedding
             // rows without ever reaching index creation.
-            await createVectorIndex(executeQuery);
+            const vectorIndexReady = await createVectorIndex(executeQuery);
             onProgress({
                 phase: 'ready',
                 percent: 100,
                 nodesProcessed: 0,
                 totalNodes: 0,
             });
-            return;
+            return {
+                nodesProcessed: 0,
+                chunksProcessed: 0,
+                vectorIndexReady,
+                semanticMode: vectorIndexReady ? 'vector-index' : 'exact-scan',
+            };
         }
         // Phase 3: Chunk + embed nodes
         const batchSize = finalConfig.batchSize;
         const chunkSize = finalConfig.chunkSize;
         const overlap = finalConfig.overlap;
         let processedNodes = 0;
-        let totalChunks = 0;
         onProgress({
             phase: 'embedding',
             percent: 20,
@@ -326,7 +344,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                 }
             }
             // Embed chunk texts in sub-batches to control memory
-            const EMBED_SUB_BATCH = 8;
+            const EMBED_SUB_BATCH = finalConfig.subBatchSize;
             for (let si = 0; si < allTexts.length; si += EMBED_SUB_BATCH) {
                 const subTexts = allTexts.slice(si, si + EMBED_SUB_BATCH);
                 const subUpdates = allUpdates.slice(si, si + EMBED_SUB_BATCH);
@@ -366,7 +384,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         if (isDev) {
             console.log('📇 Creating vector index...');
         }
-        await createVectorIndex(executeQuery);
+        const vectorIndexReady = await createVectorIndex(executeQuery);
         onProgress({
             phase: 'ready',
             percent: 100,
@@ -376,6 +394,12 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         if (isDev) {
             console.log(`✅ Embedding pipeline complete! (${totalChunks} chunks from ${totalNodes} nodes)`);
         }
+        return {
+            nodesProcessed: totalNodes,
+            chunksProcessed: totalChunks,
+            vectorIndexReady,
+            semanticMode: vectorIndexReady ? 'vector-index' : 'exact-scan',
+        };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
@@ -400,26 +424,63 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
     const queryEmbedding = await embedText(query);
     const queryVec = embeddingToArray(queryEmbedding);
     const queryVecStr = `[${queryVec.join(',')}]`;
-    const bestChunks = await collectBestChunks(k, async (fetchLimit) => {
-        const vectorQuery = `
-      CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
-        CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${fetchLimit})
-      YIELD node AS emb, distance
-      WITH emb, distance
-      WHERE distance < ${maxDistance}
-      RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
-             emb.startLine AS startLine, emb.endLine AS endLine, distance
-      ORDER BY distance
-    `;
-        const embResults = await executeQuery(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],
-        }));
-    });
+    let bestChunks = new Map();
+    if (await loadVectorExtension()) {
+        try {
+            bestChunks = await collectBestChunks(k, async (fetchLimit) => {
+                const vectorQuery = `
+          CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
+            CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${fetchLimit})
+          YIELD node AS emb, distance
+          WITH emb, distance
+          WHERE distance < ${maxDistance}
+          RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
+                 emb.startLine AS startLine, emb.endLine AS endLine, distance
+          ORDER BY distance
+        `;
+                const embResults = await executeQuery(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 {
+            bestChunks = new Map();
+        }
+    }
+    if (bestChunks.size === 0) {
+        const countRows = await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`);
+        const countRow = countRows[0];
+        const embeddingCount = Number(countRow?.cnt ?? countRow?.[0] ?? 0);
+        const exactLimit = getExactScanLimit();
+        if (embeddingCount > 0 && embeddingCount <= exactLimit) {
+            const rows = await executeQuery(`
+        MATCH (e:${EMBEDDING_TABLE_NAME})
+        RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex,
+               e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding
+      `);
+            const exactRows = rows.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,
+                embedding: row.embedding ?? row[4] ?? [],
+            }));
+            bestChunks = new Map(rankExactEmbeddingRows(exactRows, queryVec, k, maxDistance).map((row) => [
+                row.nodeId,
+                {
+                    distance: row.distance,
+                    chunkIndex: row.chunkIndex,
+                    startLine: row.startLine,
+                    endLine: row.endLine,
+                },
+            ]));
+        }
+    }
     if (bestChunks.size === 0) {
         return [];
     }

package/dist/core/embeddings/exact-search.d.ts

@@ -0,0 +1,15 @@
+export interface ExactEmbeddingRow {
+    nodeId: string;
+    chunkIndex: number;
+    startLine: number;
+    endLine: number;
+    embedding: readonly number[];
+}
+export interface ExactSearchChunk {
+    nodeId: string;
+    chunkIndex: number;
+    startLine: number;
+    endLine: number;
+    distance: number;
+}
+export declare const rankExactEmbeddingRows: (rows: readonly ExactEmbeddingRow[], queryEmbedding: readonly number[], limit: number, maxDistance: number) => ExactSearchChunk[];

package/dist/core/embeddings/exact-search.js

@@ -0,0 +1,27 @@
+const cosineDistance = (a, b) => {
+    let dot = 0;
+    let aNorm = 0;
+    let bNorm = 0;
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        dot += av * bv;
+        aNorm += av * av;
+        bNorm += bv * bv;
+    }
+    if (aNorm === 0 || bNorm === 0)
+        return 1;
+    return 1 - dot / (Math.sqrt(aNorm) * Math.sqrt(bNorm));
+};
+export const rankExactEmbeddingRows = (rows, queryEmbedding, limit, maxDistance) => rows
+    .map((row) => ({
+    nodeId: row.nodeId,
+    chunkIndex: row.chunkIndex,
+    startLine: row.startLine,
+    endLine: row.endLine,
+    distance: cosineDistance(row.embedding, queryEmbedding),
+}))
+    .filter((row) => row.distance < maxDistance)
+    .sort((a, b) => a.distance - b.distance)
+    .slice(0, limit);

package/dist/core/embeddings/types.d.ts

@@ -102,6 +102,10 @@ export interface EmbeddingConfig {
     modelId: string;
     /** Number of nodes to embed in each batch */
     batchSize: number;
+    /** Number of chunks passed to one local/HTTP embedding call */
+    subBatchSize: number;
+    /** Maximum ONNX Runtime CPU threads for local inference */
+    threads: number;
     /** Embedding vector dimensions */
     dimensions: number;
     /** Device to use for inference: 'auto' tries GPU first (DirectML on Windows, CUDA on Linux), falls back to CPU */

package/dist/core/embeddings/types.js

@@ -147,6 +147,8 @@ export const CHUNKING_RULES = {
 export const DEFAULT_EMBEDDING_CONFIG = {
     modelId: 'Snowflake/snowflake-arctic-embed-xs',
     batchSize: 16,
+    subBatchSize: 8,
+    threads: 2,
     dimensions: 384,
     device: 'auto',
     maxSnippetLength: 500,

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

@@ -1051,7 +1051,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 parentPort.postMessage({ type: 'warning', message });
             else
                 console.warn(message);
-        });
+        }, tree);
         if (parsedFile !== undefined)
             result.parsedFiles.push(parsedFile);
         // Pre-pass: extract heritage from query matches to build parentMap for buildTypeEnv.

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

@@ -137,8 +137,8 @@ export declare const getEmbeddingTableName: () => string;
 export declare const loadFTSExtension: (targetConn?: lbug.Connection, opts?: ExtensionEnsureOptions) => Promise<boolean>;
 /**
  * Load the VECTOR extension on the supplied connection (or the singleton
- * writable connection when none is given). See `loadFTSExtension` for the
- * policy / capability contract — the same `ExtensionManager` owns both.
+ * writable connection when none is given). Returns false when VECTOR is
+ * unavailable so semantic search can fall back to exact scan.
  */
 export declare const loadVectorExtension: (targetConn?: lbug.Connection, opts?: ExtensionEnsureOptions) => Promise<boolean>;
 /**

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

@@ -8,6 +8,7 @@ import lbug from '@ladybugdb/core';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { extensionManager } from './extension-loader.js';
+import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
 /**
  * Split a relationship CSV into per-label-pair files on disk.
  *
@@ -288,10 +289,9 @@ const doInitLbug = async (dbPath) => {
             }
         }
     }
-    // Load query extensions once per core adapter session. Missing optional
-    // extensions degrade search features but must not block analyze completion.
+    // FTS powers baseline search, so initialize it with the core DB. VECTOR is
+    // only required for semantic embeddings and is probed lazily there.
     await loadFTSExtension();
-    await loadVectorExtension();
     currentDbPath = dbPath;
     return { db, conn };
 };
@@ -762,8 +762,9 @@ export const executeWithReusedStatement = async (cypher, paramsList) => {
             }
         }
         catch (e) {
-            // Log the error and continue with next batch
-            console.warn('Batch execution error:', e);
+            const msg = e instanceof Error ? e.message : String(e);
+            const queryPreview = cypher.replace(/\s+/g, ' ').slice(0, 120);
+            throw new Error(`Batch execution failed for rows ${i + 1}-${i + subBatch.length}: ${msg} (${queryPreview})`);
         }
         // Note: LadybugDB PreparedStatement doesn't require explicit close()
     }
@@ -1052,13 +1053,15 @@ export const loadFTSExtension = async (targetConn, opts = {}) => {
 };
 /**
  * Load the VECTOR extension on the supplied connection (or the singleton
- * writable connection when none is given). See `loadFTSExtension` for the
- * policy / capability contract — the same `ExtensionManager` owns both.
+ * writable connection when none is given). Returns false when VECTOR is
+ * unavailable so semantic search can fall back to exact scan.
  */
 export const loadVectorExtension = async (targetConn, opts = {}) => {
     const useModuleState = targetConn === undefined;
     if (useModuleState && vectorExtensionLoaded)
         return true;
+    if (!isVectorExtensionSupportedByPlatform())
+        return false;
     const c = targetConn ?? conn;
     if (!c) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');

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

@@ -16,7 +16,7 @@
  */
 import fs from 'fs/promises';
 import lbug from '@ladybugdb/core';
-import { loadFTSExtension, loadVectorExtension } from './lbug-adapter.js';
+import { loadFTSExtension } from './lbug-adapter.js';
 const pool = new Map();
 const poolCloseListeners = new Set();
 /**
@@ -122,7 +122,6 @@ function closeOne(repoId) {
                 // for the same dbPath reuse it instead of hitting a file lock.
                 shared.refCount = 0;
                 shared.ftsLoaded = false;
-                shared.vectorLoaded = false;
             }
             else {
                 shared.db.close().catch(() => { });
@@ -248,7 +247,7 @@ async function doInitLbug(repoId, dbPath) {
                 false, // enableCompression (default)
                 true);
                 restoreStdout();
-                shared = { db, refCount: 0, ftsLoaded: false, vectorLoaded: false };
+                shared = { db, refCount: 0, ftsLoaded: false };
                 dbCache.set(dbPath, shared);
                 break;
             }
@@ -290,9 +289,6 @@ async function doInitLbug(repoId, dbPath) {
     if (!shared.ftsLoaded) {
         shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
     }
-    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.
@@ -330,7 +326,7 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     // closeOne() respects the external flag and skips db.close().
     let shared = dbCache.get(dbPath);
     if (!shared) {
-        shared = { db: existingDb, refCount: 0, ftsLoaded: false, vectorLoaded: false, external: true };
+        shared = { db: existingDb, refCount: 0, ftsLoaded: false, external: true };
         dbCache.set(dbPath, shared);
     }
     shared.refCount++;
@@ -350,9 +346,6 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     if (!shared.ftsLoaded) {
         shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
     }
-    if (!shared.vectorLoaded) {
-        shared.vectorLoaded = await loadVectorExtension(available[0], { policy: 'load-only' });
-    }
     pool.set(repoId, {
         db: existingDb,
         available,

package/dist/core/platform/capabilities.d.ts

@@ -0,0 +1,24 @@
+export type CapabilityStatus = 'available' | 'degraded' | 'unavailable';
+export type SemanticSearchMode = 'vector-index' | 'exact-scan' | 'unavailable';
+export interface RuntimeFingerprint {
+    platform: NodeJS.Platform;
+    arch: string;
+    node: string;
+    gitnexus: string;
+    ladybugdb?: string;
+    onnxruntime?: string;
+}
+export interface RuntimeCapabilities {
+    graph: CapabilityStatus;
+    fts: CapabilityStatus;
+    vector: CapabilityStatus;
+    semanticMode: SemanticSearchMode;
+    exactScanLimit: number;
+    reason?: string;
+}
+export declare const DEFAULT_EXACT_SCAN_LIMIT = 10000;
+export declare const getExactScanLimit: () => number;
+export declare const getRuntimeFingerprint: () => RuntimeFingerprint;
+export declare const isVectorExtensionSupportedByPlatform: (platform?: NodeJS.Platform) => boolean;
+export declare const getRuntimeCapabilities: () => RuntimeCapabilities;
+export declare const defaultEmbeddingThreads: () => number;

package/dist/core/platform/capabilities.js

@@ -0,0 +1,54 @@
+import os from 'os';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const packageVersion = (name) => {
+    try {
+        return require(`${name}/package.json`).version;
+    }
+    catch {
+        return undefined;
+    }
+};
+const gitnexusVersion = () => {
+    try {
+        return require('../../../package.json').version;
+    }
+    catch {
+        return 'unknown';
+    }
+};
+const parsePositiveInt = (value, fallback) => {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+};
+export const DEFAULT_EXACT_SCAN_LIMIT = 10_000;
+export const getExactScanLimit = () => parsePositiveInt(process.env.GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT, DEFAULT_EXACT_SCAN_LIMIT);
+export const getRuntimeFingerprint = () => ({
+    platform: process.platform,
+    arch: process.arch,
+    node: process.version,
+    gitnexus: gitnexusVersion(),
+    ladybugdb: packageVersion('@ladybugdb/core'),
+    onnxruntime: packageVersion('onnxruntime-node'),
+});
+export const isVectorExtensionSupportedByPlatform = (platform = process.platform) => platform !== 'win32';
+export const getRuntimeCapabilities = () => {
+    const vector = isVectorExtensionSupportedByPlatform() ? 'available' : 'unavailable';
+    const exactScanLimit = getExactScanLimit();
+    return {
+        graph: 'available',
+        fts: 'available',
+        vector,
+        semanticMode: vector === 'available' ? 'vector-index' : 'exact-scan',
+        exactScanLimit,
+        reason: vector === 'unavailable'
+            ? 'LadybugDB VECTOR is disabled on this platform; semantic search uses exact scan when embeddings exist.'
+            : undefined,
+    };
+};
+export const defaultEmbeddingThreads = () => {
+    const available = typeof os.availableParallelism === 'function' ? os.availableParallelism() : os.cpus().length;
+    return Math.max(1, Math.min(4, Math.floor(available / 2) || 1));
+};

package/dist/core/run-analyze.js

@@ -198,6 +198,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
         const stats = await getLbugStats();
         let embeddingSkipped = true;
+        let semanticMode;
         if (shouldGenerateEmbeddings) {
             if (stats.nodes <= EMBEDDING_NODE_LIMIT) {
                 embeddingSkipped = false;
@@ -219,7 +220,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             const { readServerMapping } = await import('./embeddings/server-mapping.js');
             const projectName = path.basename(repoPath);
             const serverName = await readServerMapping(projectName);
-            await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
+            const embeddingResult = await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
                 const scaled = 90 + Math.round((p.percent / 100) * 8);
                 const label = p.phase === 'loading-model'
                     ? httpMode
@@ -228,6 +229,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     : `Embedding ${p.nodesProcessed || 0}/${p.totalNodes || '?'}`;
                 progress('embeddings', scaled, label);
             }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined, { repoName: projectName, serverName }, existingEmbeddings);
+            if (embeddingResult.semanticMode === 'exact-scan') {
+                semanticMode = 'exact-scan';
+                log('Semantic embeddings were generated without a VECTOR index; ' +
+                    'queries will use exact-scan fallback within the configured limit.');
+            }
+            else {
+                semanticMode = 'vector-index';
+            }
         }
         // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
         progress('done', 98, 'Saving metadata...');
@@ -235,11 +244,20 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         let embeddingCount = 0;
         try {
             const embResult = await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`);
-            embeddingCount = embResult?.[0]?.cnt ?? 0;
+            const row = embResult?.[0];
+            embeddingCount = Number(row?.cnt ?? row?.[0] ?? 0);
         }
         catch {
             /* table may not exist if embeddings never ran */
         }
+        if (!embeddingSkipped && stats.nodes > 0 && embeddingCount === 0) {
+            throw new Error('Embedding generation completed without persisted embeddings. ' +
+                'The index was not registered to avoid silently reporting embeddings: 0.');
+        }
+        const { getRuntimeCapabilities } = await import('./platform/capabilities.js');
+        const runtimeCapabilities = getRuntimeCapabilities();
+        const effectiveSemanticMode = semanticMode ??
+            (runtimeCapabilities.semanticMode === 'vector-index' ? 'vector-index' : 'exact-scan');
         const meta = {
             repoPath,
             lastCommit: currentCommit,
@@ -259,6 +277,16 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 processes: pipelineResult.processResult?.stats.totalProcesses,
                 embeddings: embeddingCount,
             },
+            capabilities: {
+                graph: { provider: 'ladybugdb', status: runtimeCapabilities.graph },
+                fts: { provider: 'ladybugdb-fts', status: runtimeCapabilities.fts },
+                vectorSearch: {
+                    provider: effectiveSemanticMode === 'vector-index' ? 'ladybugdb-vector' : 'exact-scan',
+                    status: embeddingCount > 0 ? effectiveSemanticMode : 'unavailable',
+                    exactScanLimit: runtimeCapabilities.exactScanLimit,
+                    reason: runtimeCapabilities.reason,
+                },
+            },
         };
         await saveMeta(storagePath, meta);
         // Forward the --name alias and the registry-collision bypass bit.

package/dist/mcp/core/embedder.js

@@ -8,6 +8,7 @@ import { pipeline, env } from '@huggingface/transformers';
 import os from 'os';
 import { join } from 'path';
 import { isHttpMode, getHttpDimensions, httpEmbedQuery, } from '../../core/embeddings/http-client.js';
+import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
 // Model config
 const MODEL_ID = 'Snowflake/snowflake-arctic-embed-xs';
@@ -37,11 +38,11 @@ export const initEmbedder = async () => {
             // when gitnexus is installed globally (e.g. /usr/lib/node_modules/).
             // Respect HF_HOME if set, otherwise fall back to ~/.cache/huggingface.
             env.cacheDir = process.env.HF_HOME ?? join(os.homedir(), '.cache', 'huggingface');
+            const embeddingConfig = resolveEmbeddingConfig();
             console.error('GitNexus: Loading embedding model (first search may take a moment)...');
-            // Try GPU first (DirectML on Windows, CUDA on Linux), fall back to CPU
-            const isWindows = process.platform === 'win32';
-            const gpuDevice = isWindows ? 'dml' : 'cuda';
-            const devicesToTry = [gpuDevice, 'cpu'];
+            const devicesToTry = embeddingConfig.device === 'dml' || embeddingConfig.device === 'cuda'
+                ? [embeddingConfig.device, 'cpu']
+                : ['cpu'];
             for (const device of devicesToTry) {
                 try {
                     // Silence stdout and stderr during model load — ONNX Runtime and transformers.js
@@ -55,6 +56,12 @@ export const initEmbedder = async () => {
                         embedderInstance = await pipeline('feature-extraction', MODEL_ID, {
                             device: device,
                             dtype: 'fp32',
+                            session_options: {
+                                logSeverityLevel: 3,
+                                intraOpNumThreads: embeddingConfig.threads,
+                                interOpNumThreads: 1,
+                                executionMode: 'sequential',
+                            },
                         });
                     }
                     finally {

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

@@ -18,7 +18,9 @@ import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-ma
 import { GroupService } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
+import { rankExactEmbeddingRows, } from '../../core/embeddings/exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
+import { getExactScanLimit } from '../../core/platform/capabilities.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { checkStaleness, checkCwdMatch } from '../../core/git-staleness.js';
 // AI context generation is CLI-only (gitnexus analyze)
@@ -889,26 +891,59 @@ export class LocalBackend {
             const queryVec = await embedQuery(query);
             const dims = getEmbeddingDims();
             const queryVecStr = `[${queryVec.join(',')}]`;
-            const 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
-          WITH emb, distance
-          WHERE distance < 0.6
-          RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
-                 emb.startLine AS startLine, emb.endLine AS endLine, distance
-          ORDER BY distance
-        `;
-                const embResults = await executeQuery(repo.id, vectorQuery);
-                return embResults.map((row) => ({
+            let bestChunks = new Map();
+            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
+            WITH emb, distance
+            WHERE distance < 0.6
+            RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
+                   emb.startLine AS startLine, emb.endLine AS endLine, distance
+            ORDER BY distance
+          `;
+                    const embResults = await executeQuery(repo.id, 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 {
+                bestChunks = new Map();
+            }
+            if (bestChunks.size === 0) {
+                const embeddingCount = Number(tableCheck[0].cnt ?? tableCheck[0][0] ?? 0);
+                const exactLimit = getExactScanLimit();
+                if (embeddingCount > exactLimit)
+                    return [];
+                const rows = await executeQuery(repo.id, `
+          MATCH (e:${EMBEDDING_TABLE_NAME})
+          RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex,
+                 e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding
+        `);
+                const exactRows = rows.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],
+                    embedding: row.embedding ?? row[4] ?? [],
                 }));
-            });
+                bestChunks = new Map(rankExactEmbeddingRows(exactRows, queryVec, limit, 0.6).map((row) => [
+                    row.nodeId,
+                    {
+                        distance: row.distance,
+                        chunkIndex: row.chunkIndex,
+                        startLine: row.startLine,
+                        endLine: row.endLine,
+                    },
+                ]));
+            }
             if (bestChunks.size === 0)
                 return [];
             const results = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.4-rc.20",
+  "version": "1.6.4-rc.22",
   "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",