gitnexus 1.6.9-rc.33 → 1.6.9-rc.34

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

@@ -8,7 +8,7 @@
  * 4. Update LadybugDB with chunk-aware embeddings
  * 5. Create vector index for semantic search
  */
-import { type EmbeddingProgress, type EmbeddingConfig, type EmbeddableNode, type SemanticSearchResult, type EmbeddingContext } from './types.js';
+import { type EmbeddingProgress, type EmbeddingConfig, type EmbeddableNode, type SemanticSearchResult } from './types.js';
 import type { ExtensionInstallPolicy } from '../lbug/extension-loader.js';
 /**
  * Resolve the extension-install policy for the embedding WRITE path (analyze).
@@ -28,7 +28,7 @@ export declare const resolveEmbeddingInstallPolicy: () => ExtensionInstallPolicy
  * invalidate existing vectors, such as metadata/header shape changes,
  * structural container context changes, or preceding-context formatting rules.
  */
-export declare const EMBEDDING_TEXT_VERSION = "v2";
+export declare const EMBEDDING_TEXT_VERSION = "v4";
 /**
  * Compute a stable content fingerprint for an embeddable node.
  * Used to detect when the underlying text has changed so stale vectors
@@ -65,13 +65,11 @@ export interface EmbeddingPipelineResult {
  * @param onProgress - Callback for progress updates
  * @param config - Optional configuration override
  * @param skipNodeIds - Optional set of node IDs that already have embeddings (incremental mode)
- * @param context - Optional repo/server context for metadata enrichment
  * @param existingEmbeddings - Optional map of nodeId → contentHash for incremental mode.
  *        Nodes whose hash matches are skipped; nodes with a changed hash are DELETE'd
  *        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<EmbeddingPipelineResult>;
+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>, existingEmbeddings?: Map<string, string>) => Promise<EmbeddingPipelineResult>;
 /**
  * Perform semantic search using the vector index with chunk deduplication
  */

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

@@ -51,7 +51,7 @@ const ensureVectorExtensionAvailable = async () => {
  * invalidate existing vectors, such as metadata/header shape changes,
  * structural container context changes, or preceding-context formatting rules.
  */
-export const EMBEDDING_TEXT_VERSION = 'v2';
+export const EMBEDDING_TEXT_VERSION = 'v4';
 /**
  * Compute a stable content fingerprint for an embeddable node.
  * Used to detect when the underlying text has changed so stale vectors
@@ -185,6 +185,32 @@ const buildVectorIndex = async () => {
         return false;
     }
 };
+/**
+ * DELETE stale embedding rows for the given nodeIds so they can be re-inserted.
+ *
+ * Kuzu forbids SET on vector-indexed properties; DELETE-then-INSERT is the
+ * sanctioned pattern. A `"does not exist"` error means the rows are already gone
+ * (safe to proceed); any other error risks vector-index corruption, so it
+ * propagates and aborts the pipeline.
+ *
+ * Called per-batch (just before each batch's INSERT), not once up front — see
+ * the caller comment / KTD7: an up-front bulk delete of every stale row leaves
+ * the whole index deleted-not-reinserted if the re-embed is interrupted. Per-batch
+ * interleaving bounds that window to a single batch.
+ */
+const deleteStaleEmbeddingRows = async (executeWithReusedStatement, nodeIds) => {
+    if (nodeIds.length === 0)
+        return;
+    try {
+        await executeWithReusedStatement(`MATCH (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) DELETE e`, nodeIds.map((nodeId) => ({ nodeId })));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (!msg.includes('does not exist')) {
+            throw new Error(`[embed] Failed to delete stale embedding rows — aborting to prevent vector-index corruption: ${msg}`);
+        }
+    }
+};
 /**
  * Run the embedding pipeline
  *
@@ -193,13 +219,11 @@ const buildVectorIndex = async () => {
  * @param onProgress - Callback for progress updates
  * @param config - Optional configuration override
  * @param skipNodeIds - Optional set of node IDs that already have embeddings (incremental mode)
- * @param context - Optional repo/server context for metadata enrichment
  * @param existingEmbeddings - Optional map of nodeId → contentHash for incremental mode.
  *        Nodes whose hash matches are skipped; nodes with a changed hash are DELETE'd
  *        and re-embedded; nodes not in the map are embedded fresh.
-
  */
-export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatement, onProgress, config = {}, skipNodeIds, context, existingEmbeddings) => {
+export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatement, onProgress, config = {}, skipNodeIds, existingEmbeddings) => {
     const finalConfig = resolveEmbeddingConfig(config);
     let totalChunks = 0;
     try {
@@ -233,20 +257,16 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         }
         // Phase 2: Query embeddable nodes
         let nodes = await queryEmbeddableNodes(executeQuery);
-        // Apply context metadata
-        if (context?.repoName) {
-            for (const node of nodes) {
-                node.repoName = context.repoName;
-                node.serverName = context.serverName;
-            }
-        }
         // Incremental mode: compare content hashes, delete stale rows, skip fresh ones.
         // Computed hashes for stale nodes are cached so batchInsertEmbeddings can reuse them
         // (avoids double computation).
         const computedStaleHashes = new Map();
+        // Stale rows are DELETE'd per-batch (just before each batch's INSERT) rather
+        // than all up front — see U6 / KTD7. `staleNodeIds` is consulted inside the
+        // batch loop; it stays empty in full (non-incremental) mode so no deletes fire.
+        const staleNodeIds = new Set();
         if (existingEmbeddings && existingEmbeddings.size > 0) {
             const beforeCount = nodes.length;
-            const staleNodeIds = [];
             nodes = nodes.filter((n) => {
                 const existingHash = existingEmbeddings.get(n.id);
                 if (existingHash === undefined) {
@@ -257,33 +277,14 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                 if (currentHash !== existingHash) {
                     // Content changed — cache hash for reuse during insert, mark for DELETE + re-embed
                     computedStaleHashes.set(n.id, currentHash);
-                    staleNodeIds.push(n.id);
+                    staleNodeIds.add(n.id);
                     return true;
                 }
                 // Hash matches — skip (fresh); no need to cache hash for skipped nodes
                 return false;
             });
-            // DELETE stale embedding rows so they can be re-inserted
-            // (Kuzu forbids SET on vector-indexed properties; DELETE-then-INSERT is the sanctioned pattern)
-            if (staleNodeIds.length > 0) {
-                if (isDev) {
-                    logger.info(`🔄 Deleting ${staleNodeIds.length} stale embedding rows for re-embed`);
-                }
-                try {
-                    await executeWithReusedStatement(`MATCH (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) DELETE e`, staleNodeIds.map((nodeId) => ({ nodeId })));
-                }
-                catch (err) {
-                    // "does not exist" = rows already gone — safe to proceed.
-                    // All other errors risk vector-index corruption (Kuzu requires DELETE-before-INSERT
-                    // for vector-indexed properties) — propagate so the pipeline aborts cleanly.
-                    const msg = err instanceof Error ? err.message : String(err);
-                    if (!msg.includes('does not exist')) {
-                        throw new Error(`[embed] Failed to delete stale embedding rows — aborting to prevent vector-index corruption: ${msg}`);
-                    }
-                }
-            }
             if (isDev) {
-                logger.info(`📦 Incremental embeddings: ${beforeCount} total, ${existingEmbeddings.size} cached, ${staleNodeIds.length} stale, ${nodes.length} to embed`);
+                logger.info(`📦 Incremental embeddings: ${beforeCount} total, ${existingEmbeddings.size} cached, ${staleNodeIds.size} stale, ${nodes.length} to embed`);
             }
         }
         const totalNodes = nodes.length;
@@ -373,6 +374,11 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                     prevTail = overlap > 0 ? chunk.text.slice(-overlap) : '';
                 }
             }
+            // U6 / KTD7: delete this batch's stale rows immediately before its inserts,
+            // so an interrupted re-embed loses at most one batch (not the whole index).
+            // Preserves Kuzu's required DELETE-before-INSERT for vector-indexed rows.
+            const batchStaleIds = batch.filter((n) => staleNodeIds.has(n.id)).map((n) => n.id);
+            await deleteStaleEmbeddingRows(executeWithReusedStatement, batchStaleIds);
             // Embed chunk texts in sub-batches to control memory
             const EMBED_SUB_BATCH = finalConfig.subBatchSize;
             for (let si = 0; si < allTexts.length; si += EMBED_SUB_BATCH) {

package/dist/core/embeddings/text-generator.d.ts

@@ -1,7 +1,7 @@
 /**
  * Text Generator Module
  *
- * Generates enriched embedding text from code nodes with metadata.
+ * Generates compact, description-forward embedding text from code nodes.
  * Supports chunkable labels (Function/Method with AST chunking),
  * Class-specific structural text, and short-node direct embed.
  *

package/dist/core/embeddings/text-generator.js

@@ -1,7 +1,7 @@
 /**
  * Text Generator Module
  *
- * Generates enriched embedding text from code nodes with metadata.
+ * Generates compact, description-forward embedding text from code nodes.
  * Supports chunkable labels (Function/Method with AST chunking),
  * Class-specific structural text, and short-node direct embed.
  *
@@ -41,27 +41,48 @@ const cleanContent = (content) => {
         .trim();
 };
 /**
- * Build metadata header for a node
+ * Compact location signal for the embedding header: the last 1-2 path segments
+ * (immediate parent dir + basename), never the full deep path.
+ *
+ * #2333 / PR #2334 tri-review: U1 dropped the location entirely, which regressed
+ * path/service-qualified semantic search (e.g. `billing/handler` vs
+ * `identity/handler` in a monorepo) — and FTS indexes only name/content/description,
+ * never `filePath`, so there is no keyword backfill. The bounded form restores the
+ * discriminating tokens (service dir + filename-concept) at a fraction of the
+ * dilution the full path caused.
  */
-const buildMetadataHeader = (node, config) => {
+const boundedLocation = (filePath) => {
+    const segments = filePath.replace(/\\/g, '/').split('/').filter(Boolean);
+    return segments.slice(-2).join('/');
+};
+/**
+ * Build a compact, description-forward header for embedding text.
+ *
+ * Issue #2333 (sub-issue of #2326), Option A: lead the embedding text with the
+ * symbol name + doc-comment description and drop the low-signal metadata lines
+ * (`Repo`/`Server`/`Export` and the verbose full `Path`). For short doc comments
+ * those lines used to be ~25-30% of the embedding text, diluting the description's
+ * semantic weight in the vector and weakening description-shaped search — worst
+ * for CJK, where a complete concept is often 4-20 characters.
+ *
+ * A *bounded* location signal (last 1-2 path segments) is kept after the
+ * description — see `boundedLocation` for why the full path drop was reversed.
+ *
+ * Full metadata is unaffected: it lives on the graph node properties, which is
+ * what display/context tools read. Only the embedding text changes here.
+ *
+ * Option B (reorder only, keep metadata) was rejected — mean-pooled embeddings
+ * weight by token proportion, not position, so reordering alone barely moves the
+ * signal. Option C (a separate description-only embedding + hybrid merge) is
+ * deferred to follow-up; build it only if Option A proves insufficient against
+ * real measurement. Any change to this template MUST bump EMBEDDING_TEXT_VERSION.
+ */
+const buildEmbeddingHeader = (node, config) => {
     const parts = [];
     // Label + name
     parts.push(`${node.label}: ${node.name}`);
-    // Repo name
-    if (node.repoName) {
-        parts.push(`Repo: ${node.repoName}`);
-    }
-    // Server name (optional)
-    if (node.serverName) {
-        parts.push(`Server: ${node.serverName}`);
-    }
-    // Full file path
-    parts.push(`Path: ${node.filePath}`);
-    // Export status
-    if (node.isExported !== undefined) {
-        parts.push(`Export: ${node.isExported}`);
-    }
-    // Description (truncated)
+    // Description hoisted above everything else so its semantic signal dominates
+    // the embedding vector and is never the part lost to token-limit truncation.
     if (node.description) {
         const maxLen = config.maxDescriptionLength ?? DEFAULT_EMBEDDING_CONFIG.maxDescriptionLength;
         const truncated = truncateDescription(node.description, maxLen);
@@ -69,10 +90,19 @@ const buildMetadataHeader = (node, config) => {
             parts.push(truncated);
         }
     }
+    // Bounded location signal — placed after the description so the description
+    // still leads the vector. Restores path/service disambiguation lost when the
+    // full Path line was dropped (FTS does not index filePath to backfill it).
+    if (node.filePath) {
+        const loc = boundedLocation(node.filePath);
+        if (loc) {
+            parts.push(`Loc: ${loc}`);
+        }
+    }
     return parts.join('\n');
 };
 const generateCodeBodyText = (node, codeBody, config, prevTail) => {
-    const header = buildMetadataHeader(node, config);
+    const header = buildEmbeddingHeader(node, config);
     const parts = [header];
     if (prevTail) {
         parts.push(`[preceding context]: ...${cleanContent(prevTail)}`);
@@ -87,7 +117,7 @@ const getCompactContainerContext = (cleanedContent, declarationOnly) => {
     return firstLine ? `Container: ${firstLine}` : undefined;
 };
 const generateStructuralTypeText = (node, codeBody, config, chunkIndex, prevTail) => {
-    const header = buildMetadataHeader(node, config);
+    const header = buildEmbeddingHeader(node, config);
     const parts = [header];
     const isFirstChunk = chunkIndex === undefined || chunkIndex === 0;
     const cleanedContent = cleanContent(node.content);
@@ -192,7 +222,7 @@ export const extractDeclarationOnly = (content) => {
  */
 export const generateEmbeddingText = (node, codeBody, config = {}, chunkIndex, prevTail) => {
     if (isShortLabel(node.label)) {
-        const header = buildMetadataHeader(node, config);
+        const header = buildEmbeddingHeader(node, config);
         const cleaned = cleanContent(node.content);
         return `${header}\n\n${cleaned}`;
     }

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

@@ -168,13 +168,6 @@ export interface CachedEmbedding {
     embedding: number[];
     contentHash?: string;
 }
-/**
- * Context info for embedding pipeline (repo/server metadata enrichment)
- */
-export interface EmbeddingContext {
-    repoName?: string;
-    serverName?: string;
-}
 /**
  * Model download progress from transformers.js
  */

package/dist/core/run-analyze.js

@@ -982,20 +982,6 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     existingEmbeddings.set(e.nodeId, e.contentHash ?? STALE_HASH_SENTINEL);
                 }
             }
-            const { readServerMapping } = await import('./embeddings/server-mapping.js');
-            // Mirror the registry's name-resolution chain so the server-mapping
-            // lookup key stays aligned with the final registry name (#1259):
-            //   --name → remote-derived → canonical-root basename
-            // (preserved-alias is intentionally NOT consulted here — server
-            // mappings are addressed by the operationally-meaningful name the
-            // user configures, not by a sticky registry-only alias they may not
-            // know about. The previous canonical-only logic ignored both --name
-            // and remote-derived names, silently breaking server-mapping for
-            // anyone with a `--name` alias or remote-named repo.)
-            const projectName = options.registryName ??
-                getInferredRepoName(repoPath) ??
-                path.basename(resolveRepoIdentityRoot(repoPath));
-            const serverName = await readServerMapping(projectName);
             const embeddingResult = await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
                 const scaled = 90 + Math.round((p.percent / 100) * 8);
                 const label = p.phase === 'loading-model'
@@ -1004,7 +990,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                         : 'Loading embedding model...'
                     : `Embedding ${p.nodesProcessed || 0}/${p.totalNodes || '?'}`;
                 progress('embeddings', scaled, label);
-            }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined, { repoName: projectName, serverName }, existingEmbeddings);
+            }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined, existingEmbeddings);
             if (embeddingResult.semanticMode === 'exact-scan') {
                 semanticMode = 'exact-scan';
                 log('Semantic embeddings were generated without a VECTOR index; ' +

package/dist/server/api.js

@@ -1520,7 +1520,6 @@ export const createServer = async (port, host = '127.0.0.1') => {
                             });
                         }, {}, // config: use defaults
                         undefined, // skipNodeIds
-                        undefined, // context
                         existingEmbeddings);
                         // Flush WAL so subsequent /api/search requests see the new
                         // embeddings immediately (#1149). In the CLI path closeLbug()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9-rc.33",
+  "version": "1.6.9-rc.34",
   "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",