@zuvia-software-solutions/code-mapper 2.4.0 → 2.5.0

package/dist/cli/analyze.js

@@ -347,86 +347,26 @@ export const analyzeCommand = async (inputPath, options) => {
             catch { /* some may fail if node was removed, that's fine */ }
         }
     }
-    // Phase 4: Embeddings (90-98%)
+    // Phase 4: Embeddings — bge-small NL embeddings (CPU, Node.js, no Python)
+    // Extracts natural language from code (comments, names, enums, patterns)
+    // and embeds with bge-small-en-v1.5 (33M params, 384-dim, ~6ms/doc).
     const stats = getStats(db);
     let embeddingFailed = false;
     if (options?.embeddings) {
         recordPhase('embeddings');
-        updateBar(90, 'Generating embeddings...');
-        // Close DB so Python can write to it
-        closeDb(dbPath);
-        // Run Python embedder in batch mode — reads from SQLite, embeds, writes back.
-        // Zero IPC overhead: ~3x faster than Node↔Python JSON streaming.
-        const { spawn: spawnChild } = await import('child_process');
-        const { fileURLToPath } = await import('url');
-        const mlxScript = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'models', 'mlx-embedder.py');
-        await new Promise((resolve) => {
-            // Use spawn (not execFile) — no internal buffer limit, streams only.
-            // execFile buffers all stdout in memory which causes OOM/kill on large codebases.
-            const proc = spawnChild('python3', [mlxScript, 'batch', dbPath, '--dims', '256', '--max-tokens', '2048'], {
-                stdio: ['ignore', 'pipe', 'pipe'],
-            });
-            let stderrBuf = '';
-            proc.stderr?.on('data', (chunk) => {
-                stderrBuf += chunk.toString();
-                if (stderrBuf.length > 10240)
-                    stderrBuf = stderrBuf.slice(-10240);
-            });
-            proc.on('close', (code) => {
-                if (code !== 0) {
-                    // Non-fatal: index is already saved, just embeddings failed
-                    console.error(`\n  Warning: Embedding failed (exit code ${code}). Index saved without embeddings.`);
-                    if (stderrBuf.trim())
-                        console.error(`  ${stderrBuf.trim().split('\n').slice(-3).join('\n  ')}`);
-                    embeddingFailed = true;
-                }
-                resolve();
-            });
-            proc.on('error', (err) => {
-                console.error(`\n  Warning: Embedding failed: ${err.message}. Index saved without embeddings.`);
-                embeddingFailed = true;
-                resolve();
-            });
-            // Stream progress from Python's JSON lines on stdout
-            let lineBuf = '';
-            proc.stdout?.on('data', (chunk) => {
-                lineBuf += chunk.toString();
-                const lines = lineBuf.split('\n');
-                lineBuf = lines.pop() || '';
-                for (const line of lines) {
-                    if (!line.trim())
-                        continue;
-                    try {
-                        const msg = JSON.parse(line);
-                        if (msg.phase === 'downloading' || msg.phase === 'converting') {
-                            updateBar(90, msg.message);
-                        }
-                        else if (msg.phase === 'loaded') {
-                            updateBar(91, `Model loaded (${msg.load_ms}ms)`);
-                        }
-                        else if (msg.phase === 'queried') {
-                            updateBar(92, `Found ${msg.nodes} embeddable nodes${msg.skipped_tests ? ` (${msg.skipped_tests} test files skipped)` : ''}`);
-                        }
-                        else if (msg.phase === 'prepared') {
-                            updateBar(93, `${msg.to_embed} to embed, ${msg.skipped} cached`);
-                        }
-                        else if (msg.phase === 'embedding') {
-                            const scaled = 93 + Math.round((msg.progress / 100) * 4);
-                            updateBar(scaled, `Embedding... ${msg.progress}% (${msg.embedded} written)`);
-                        }
-                        else if (msg.phase === 'embedded') {
-                            updateBar(97, `Embedded ${msg.count} nodes (${(msg.ms / 1000).toFixed(1)}s)`);
-                        }
-                        else if (msg.phase === 'done') {
-                            updateBar(98, `Embeddings complete (${msg.embedded} new, ${msg.skipped} cached)`);
-                        }
-                    }
-                    catch { }
-                }
+        updateBar(90, 'Generating embeddings (bge-small)...');
+        const { buildNlEmbeddings } = await import('../core/embeddings/nl-embedder.js');
+        try {
+            const result = await buildNlEmbeddings(db, (current, total) => {
+                const pct = 90 + Math.round((current / Math.max(total, 1)) * 8);
+                updateBar(pct, `Embeddings (${current}/${total})`, 'Embeddings');
             });
-        });
-        // Reopen DB after Python is done
-        db = openDb(dbPath);
+            updateBar(98, `Embeddings: ${result.embedded} embedded, ${result.skipped} cached (${(result.durationMs / 1000).toFixed(1)}s)`);
+        }
+        catch (err) {
+            console.error(`\n  Warning: Embedding failed: ${err instanceof Error ? err.message : err}`);
+            embeddingFailed = true;
+        }
     }
     // Phase 5: Finalize (98-100%)
     recordPhase('finalize');
@@ -519,7 +459,7 @@ export const analyzeCommand = async (inputPath, options) => {
         'search-text': 'Search text',
         fts: 'FTS indexing',
         'restore-embeddings': 'Restore embeddings',
-        embeddings: 'Embeddings (MLX)',
+        embeddings: 'Embeddings (bge-small)',
         finalize: 'Finalize & context',
         done: 'Done',
     };

package/dist/cli/index.js

@@ -22,7 +22,7 @@ program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
     .option('-f, --force', 'Force full re-index even if up to date')
-    .option('--embeddings', 'Enable embedding generation for semantic search (on by default)', true)
+    .option('--embeddings', 'Generate semantic embeddings (bge-small, CPU, fast)')
     .option('--no-embeddings', 'Skip embedding generation')
     .option('--no-tsgo', 'Skip tsgo LSP for call resolution (faster, less accurate)')
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')

package/dist/core/db/adapter.d.ts

@@ -138,6 +138,15 @@ export declare function searchFileWords(db: Database.Database, query: string, li
 }>;
 /** Clear all file words (used before full rebuild) */
 export declare function clearFileWords(db: Database.Database): void;
+/** Count NL embeddings in the index */
+export declare function countNlEmbeddings(db: Database.Database): number;
+/** Search NL embeddings via brute-force cosine similarity */
+export declare function searchNlVector(db: Database.Database, queryVec: number[], limit?: number, maxDistance?: number): Array<{
+    nodeId: string;
+    distance: number;
+    source: string;
+    text: string;
+}>;
 /** Escape a string for use in SQL single-quoted literals. */
 export declare function escapeSql(value: string): string;
 /** Execute a raw SQL query and return rows. */

package/dist/core/db/adapter.js

@@ -594,6 +594,46 @@ export function clearFileWords(db) {
     db.prepare('DELETE FROM file_words').run();
 }
 // ---------------------------------------------------------------------------
+// NL Embeddings
+// ---------------------------------------------------------------------------
+/** Count NL embeddings in the index */
+export function countNlEmbeddings(db) {
+    try {
+        const row = db.prepare('SELECT COUNT(*) as cnt FROM nl_embeddings').get();
+        return row?.cnt ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Search NL embeddings via brute-force cosine similarity */
+export function searchNlVector(db, queryVec, limit = 10, maxDistance = 0.5) {
+    let rows;
+    try {
+        rows = db.prepare('SELECT nodeId, embedding, source, text FROM nl_embeddings').all();
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const row of rows) {
+        const vec = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4);
+        let dot = 0, normA = 0, normB = 0;
+        for (let i = 0; i < queryVec.length && i < vec.length; i++) {
+            dot += queryVec[i] * vec[i];
+            normA += queryVec[i] * queryVec[i];
+            normB += vec[i] * vec[i];
+        }
+        const similarity = dot / (Math.sqrt(normA) * Math.sqrt(normB));
+        const distance = 1 - similarity;
+        if (distance < maxDistance) {
+            results.push({ nodeId: row.nodeId, distance, source: row.source, text: row.text });
+        }
+    }
+    results.sort((a, b) => a.distance - b.distance);
+    return results.slice(0, limit);
+}
+// ---------------------------------------------------------------------------
 // Raw SQL escape (for dynamic queries in local-backend.ts)
 // ---------------------------------------------------------------------------
 /** Escape a string for use in SQL single-quoted literals. */

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

@@ -68,6 +68,14 @@ export interface EmbeddingRow {
     readonly embedding: Buffer;
     readonly textHash: string | null;
 }
+/** A NL embedding row as stored in the `nl_embeddings` table */
+export interface NlEmbeddingRow {
+    readonly nodeId: NodeId;
+    readonly embedding: Buffer;
+    readonly textHash: string | null;
+    readonly source: string;
+    readonly text: string;
+}
 /** A reference occurrence as stored in the `refs` table */
 export interface RefsRow {
     readonly symbol: string;
@@ -118,4 +126,4 @@ export interface EdgeInsert {
 }
 /** Legacy edge table name constant (kept for compatibility) */
 export declare const REL_TABLE_NAME = "CodeRelation";
-export declare const SCHEMA_SQL = "\n-- Nodes: unified table for all code elements\nCREATE TABLE IF NOT EXISTS nodes (\n  id TEXT PRIMARY KEY,\n  label TEXT NOT NULL,\n  name TEXT NOT NULL DEFAULT '',\n  filePath TEXT NOT NULL DEFAULT '',\n  startLine INTEGER,\n  endLine INTEGER,\n  isExported INTEGER,\n  content TEXT NOT NULL DEFAULT '',\n  description TEXT NOT NULL DEFAULT '',\n  heuristicLabel TEXT,\n  cohesion REAL,\n  symbolCount INTEGER,\n  keywords TEXT,\n  enrichedBy TEXT,\n  processType TEXT,\n  stepCount INTEGER,\n  communities TEXT,\n  entryPointId TEXT,\n  terminalId TEXT,\n  parameterCount INTEGER,\n  returnType TEXT,\n  nameExpanded TEXT DEFAULT '',\n  searchText TEXT DEFAULT ''\n);\n\nCREATE INDEX IF NOT EXISTS idx_nodes_label ON nodes(label);\nCREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);\nCREATE INDEX IF NOT EXISTS idx_nodes_filePath ON nodes(filePath);\nCREATE INDEX IF NOT EXISTS idx_nodes_label_name ON nodes(label, name);\nCREATE INDEX IF NOT EXISTS idx_nodes_filePath_lines ON nodes(filePath, startLine, endLine);\n\n-- Edges: single table for all relationships\nCREATE TABLE IF NOT EXISTS edges (\n  id TEXT PRIMARY KEY,\n  sourceId TEXT NOT NULL,\n  targetId TEXT NOT NULL,\n  type TEXT NOT NULL,\n  confidence REAL NOT NULL DEFAULT 1.0,\n  reason TEXT NOT NULL DEFAULT '',\n  step INTEGER NOT NULL DEFAULT 0,\n  callLine INTEGER\n);\n\nCREATE INDEX IF NOT EXISTS idx_edges_sourceId ON edges(sourceId);\nCREATE INDEX IF NOT EXISTS idx_edges_targetId ON edges(targetId);\nCREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);\nCREATE INDEX IF NOT EXISTS idx_edges_source_type ON edges(sourceId, type);\nCREATE INDEX IF NOT EXISTS idx_edges_target_type ON edges(targetId, type);\n\n-- Embeddings: vector storage\nCREATE TABLE IF NOT EXISTS embeddings (\n  nodeId TEXT PRIMARY KEY,\n  embedding BLOB NOT NULL,\n  textHash TEXT\n);\n\n-- FTS5 virtual table (auto-updated via triggers)\nCREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(\n  name,\n  nameExpanded,\n  searchText,\n  filePath,\n  content,\n  content='nodes',\n  content_rowid='rowid'\n);\n\nCREATE TRIGGER IF NOT EXISTS nodes_fts_ai AFTER INSERT ON nodes BEGIN\n  INSERT INTO nodes_fts(rowid, name, nameExpanded, searchText, filePath, content) VALUES (new.rowid, new.name, new.nameExpanded, new.searchText, new.filePath, new.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS nodes_fts_ad AFTER DELETE ON nodes BEGIN\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES ('delete', old.rowid, old.name, old.nameExpanded, old.searchText, old.filePath, old.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS nodes_fts_au AFTER UPDATE ON nodes BEGIN\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES ('delete', old.rowid, old.name, old.nameExpanded, old.searchText, old.filePath, old.content);\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES (new.rowid, new.name, new.nameExpanded, new.searchText, new.filePath, new.content);\nEND;\n\n-- Refs: identifier occurrence index (pre-computed grep)\nCREATE TABLE IF NOT EXISTS refs (\n  symbol TEXT NOT NULL,\n  filePath TEXT NOT NULL,\n  line INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_refs_symbol ON refs(symbol);\nCREATE INDEX IF NOT EXISTS idx_refs_filePath ON refs(filePath);\nCREATE INDEX IF NOT EXISTS idx_refs_symbol_file ON refs(symbol, filePath);\n\n-- File-level word index for conceptual search\nCREATE TABLE IF NOT EXISTS file_words (\n  filePath TEXT PRIMARY KEY,\n  words TEXT NOT NULL DEFAULT ''\n);\n\nCREATE VIRTUAL TABLE IF NOT EXISTS file_words_fts USING fts5(\n  words,\n  content='file_words',\n  content_rowid='rowid'\n);\n\nCREATE TRIGGER IF NOT EXISTS file_words_fts_ai AFTER INSERT ON file_words BEGIN\n  INSERT INTO file_words_fts(rowid, words) VALUES (new.rowid, new.words);\nEND;\nCREATE TRIGGER IF NOT EXISTS file_words_fts_ad AFTER DELETE ON file_words BEGIN\n  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES ('delete', old.rowid, old.words);\nEND;\nCREATE TRIGGER IF NOT EXISTS file_words_fts_au AFTER UPDATE ON file_words BEGIN\n  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES ('delete', old.rowid, old.words);\n  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES (new.rowid, new.words);\nEND;\n";
+export declare const SCHEMA_SQL = "\n-- Nodes: unified table for all code elements\nCREATE TABLE IF NOT EXISTS nodes (\n  id TEXT PRIMARY KEY,\n  label TEXT NOT NULL,\n  name TEXT NOT NULL DEFAULT '',\n  filePath TEXT NOT NULL DEFAULT '',\n  startLine INTEGER,\n  endLine INTEGER,\n  isExported INTEGER,\n  content TEXT NOT NULL DEFAULT '',\n  description TEXT NOT NULL DEFAULT '',\n  heuristicLabel TEXT,\n  cohesion REAL,\n  symbolCount INTEGER,\n  keywords TEXT,\n  enrichedBy TEXT,\n  processType TEXT,\n  stepCount INTEGER,\n  communities TEXT,\n  entryPointId TEXT,\n  terminalId TEXT,\n  parameterCount INTEGER,\n  returnType TEXT,\n  nameExpanded TEXT DEFAULT '',\n  searchText TEXT DEFAULT ''\n);\n\nCREATE INDEX IF NOT EXISTS idx_nodes_label ON nodes(label);\nCREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);\nCREATE INDEX IF NOT EXISTS idx_nodes_filePath ON nodes(filePath);\nCREATE INDEX IF NOT EXISTS idx_nodes_label_name ON nodes(label, name);\nCREATE INDEX IF NOT EXISTS idx_nodes_filePath_lines ON nodes(filePath, startLine, endLine);\n\n-- Edges: single table for all relationships\nCREATE TABLE IF NOT EXISTS edges (\n  id TEXT PRIMARY KEY,\n  sourceId TEXT NOT NULL,\n  targetId TEXT NOT NULL,\n  type TEXT NOT NULL,\n  confidence REAL NOT NULL DEFAULT 1.0,\n  reason TEXT NOT NULL DEFAULT '',\n  step INTEGER NOT NULL DEFAULT 0,\n  callLine INTEGER\n);\n\nCREATE INDEX IF NOT EXISTS idx_edges_sourceId ON edges(sourceId);\nCREATE INDEX IF NOT EXISTS idx_edges_targetId ON edges(targetId);\nCREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);\nCREATE INDEX IF NOT EXISTS idx_edges_source_type ON edges(sourceId, type);\nCREATE INDEX IF NOT EXISTS idx_edges_target_type ON edges(targetId, type);\n\n-- Embeddings: vector storage\nCREATE TABLE IF NOT EXISTS embeddings (\n  nodeId TEXT PRIMARY KEY,\n  embedding BLOB NOT NULL,\n  textHash TEXT\n);\n\n-- NL Embeddings: natural language description vectors (bge-small, 384-dim)\nCREATE TABLE IF NOT EXISTS nl_embeddings (\n  nodeId TEXT NOT NULL,\n  embedding BLOB NOT NULL,\n  textHash TEXT,\n  source TEXT NOT NULL DEFAULT 'comment',\n  text TEXT NOT NULL DEFAULT ''\n);\n\nCREATE INDEX IF NOT EXISTS idx_nl_emb_nodeId ON nl_embeddings(nodeId);\n\n-- FTS5 virtual table (auto-updated via triggers)\nCREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(\n  name,\n  nameExpanded,\n  searchText,\n  filePath,\n  content,\n  content='nodes',\n  content_rowid='rowid'\n);\n\nCREATE TRIGGER IF NOT EXISTS nodes_fts_ai AFTER INSERT ON nodes BEGIN\n  INSERT INTO nodes_fts(rowid, name, nameExpanded, searchText, filePath, content) VALUES (new.rowid, new.name, new.nameExpanded, new.searchText, new.filePath, new.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS nodes_fts_ad AFTER DELETE ON nodes BEGIN\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES ('delete', old.rowid, old.name, old.nameExpanded, old.searchText, old.filePath, old.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS nodes_fts_au AFTER UPDATE ON nodes BEGIN\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES ('delete', old.rowid, old.name, old.nameExpanded, old.searchText, old.filePath, old.content);\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES (new.rowid, new.name, new.nameExpanded, new.searchText, new.filePath, new.content);\nEND;\n\n-- Refs: identifier occurrence index (pre-computed grep)\nCREATE TABLE IF NOT EXISTS refs (\n  symbol TEXT NOT NULL,\n  filePath TEXT NOT NULL,\n  line INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_refs_symbol ON refs(symbol);\nCREATE INDEX IF NOT EXISTS idx_refs_filePath ON refs(filePath);\nCREATE INDEX IF NOT EXISTS idx_refs_symbol_file ON refs(symbol, filePath);\n\n-- File-level word index for conceptual search\nCREATE TABLE IF NOT EXISTS file_words (\n  filePath TEXT PRIMARY KEY,\n  words TEXT NOT NULL DEFAULT ''\n);\n\nCREATE VIRTUAL TABLE IF NOT EXISTS file_words_fts USING fts5(\n  words,\n  content='file_words',\n  content_rowid='rowid'\n);\n\nCREATE TRIGGER IF NOT EXISTS file_words_fts_ai AFTER INSERT ON file_words BEGIN\n  INSERT INTO file_words_fts(rowid, words) VALUES (new.rowid, new.words);\nEND;\nCREATE TRIGGER IF NOT EXISTS file_words_fts_ad AFTER DELETE ON file_words BEGIN\n  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES ('delete', old.rowid, old.words);\nEND;\nCREATE TRIGGER IF NOT EXISTS file_words_fts_au AFTER UPDATE ON file_words BEGIN\n  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES ('delete', old.rowid, old.words);\n  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES (new.rowid, new.words);\nEND;\n";

package/dist/core/db/schema.js

@@ -114,6 +114,17 @@ CREATE TABLE IF NOT EXISTS embeddings (
   textHash TEXT
 );
 
+-- NL Embeddings: natural language description vectors (bge-small, 384-dim)
+CREATE TABLE IF NOT EXISTS nl_embeddings (
+  nodeId TEXT NOT NULL,
+  embedding BLOB NOT NULL,
+  textHash TEXT,
+  source TEXT NOT NULL DEFAULT 'comment',
+  text TEXT NOT NULL DEFAULT ''
+);
+
+CREATE INDEX IF NOT EXISTS idx_nl_emb_nodeId ON nl_embeddings(nodeId);
+
 -- FTS5 virtual table (auto-updated via triggers)
 CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
   name,

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

@@ -1,5 +1,4 @@
-/** @file index.ts @description Barrel re-exports for the embedding pipeline system */
+/** @file Barrel re-exports for the embedding system (bge-small NL embedder) */
 export * from './types.js';
-export * from './embedder.js';
 export * from './text-generator.js';
-export * from './embedding-pipeline.js';
+export * from './nl-embedder.js';

package/dist/core/embeddings/index.js

@@ -1,6 +1,5 @@
 // code-mapper/src/core/embeddings/index.ts
-/** @file index.ts @description Barrel re-exports for the embedding pipeline system */
+/** @file Barrel re-exports for the embedding system (bge-small NL embedder) */
 export * from './types.js';
-export * from './embedder.js';
 export * from './text-generator.js';
-export * from './embedding-pipeline.js';
+export * from './nl-embedder.js';

package/dist/core/embeddings/nl-embed-worker.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file Worker process for parallel NL embedding.
+ * Spawned by buildNlEmbeddings — loads bge-small independently,
+ * embeds texts received via IPC, sends vectors back.
+ *
+ * Same architecture as parallel tsgo: N processes, each with own model.
+ */
+export {};

package/dist/core/embeddings/nl-embed-worker.js

@@ -0,0 +1,38 @@
+// code-mapper/src/core/embeddings/nl-embed-worker.ts
+/**
+ * @file Worker process for parallel NL embedding.
+ * Spawned by buildNlEmbeddings — loads bge-small independently,
+ * embeds texts received via IPC, sends vectors back.
+ *
+ * Same architecture as parallel tsgo: N processes, each with own model.
+ */
+import { pipeline } from '@huggingface/transformers';
+const MODEL_ID = 'Xenova/bge-small-en-v1.5';
+async function main() {
+    // Load model
+    const extractor = await pipeline('feature-extraction', MODEL_ID, { quantized: true });
+    process.send({ type: 'ready' });
+    // Process messages from parent
+    process.on('message', async (msg) => {
+        if (msg.type === 'embed') {
+            const results = [];
+            for (const item of msg.items) {
+                try {
+                    const result = await extractor(item.text, { pooling: 'cls', normalize: true });
+                    results.push({ nodeId: item.nodeId, vec: Array.from(result.data) });
+                }
+                catch {
+                    // Skip failed embeddings
+                }
+            }
+            process.send({ type: 'results', results, batchId: msg.batchId });
+        }
+        else if (msg.type === 'exit') {
+            process.exit(0);
+        }
+    });
+}
+main().catch(err => {
+    console.error('NL embed worker failed:', err);
+    process.exit(1);
+});

package/dist/core/embeddings/nl-embedder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file Natural language embedder using bge-small-en-v1.5.
+ *
+ * Runs entirely in Node.js via @huggingface/transformers — no Python, no GPU.
+ * Embeds human-readable descriptions extracted from code (JSDoc comments,
+ * enum values, type patterns, file headers) for conceptual search.
+ *
+ * 33M params, q8 quantized, 384-dim embeddings, ~6ms/text on CPU.
+ */
+import type Database from 'better-sqlite3';
+/** Initialize the NL embedding model (lazy, idempotent) */
+export declare function initNlEmbedder(): Promise<void>;
+/** Check if the NL embedder is ready */
+export declare function isNlEmbedderReady(): boolean;
+/** Embed a single text, returns Float32Array */
+export declare function nlEmbed(text: string): Promise<number[]>;
+/** Embed a batch of texts (processes in sub-batches for memory efficiency) */
+export declare function nlEmbedBatch(texts: string[]): Promise<number[][]>;
+interface NodeForNl {
+    id: string;
+    name: string;
+    label: string;
+    filePath: string;
+    content: string;
+    startLine: number | null;
+    description: string;
+}
+interface NlDocument {
+    nodeId: string;
+    source: string;
+    text: string;
+}
+/** Build NL documents from a node */
+export declare function extractNlTexts(node: NodeForNl): NlDocument[];
+/**
+ * Build NL embeddings for all eligible nodes in the database.
+ * Reads nodes, extracts NL text, embeds with bge-small, writes to nl_embeddings.
+ */
+export declare function buildNlEmbeddings(db: Database.Database, onProgress?: (current: number, total: number) => void): Promise<{
+    embedded: number;
+    skipped: number;
+    durationMs: number;
+}>;
+export {};