gitnexus 1.6.2-rc.3 → 1.6.2-rc.5

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

@@ -8,7 +8,14 @@
  * 4. Update LadybugDB with embeddings
  * 5. Create vector index for semantic search
  */
-import { type EmbeddingProgress, type EmbeddingConfig, type SemanticSearchResult } from './types.js';
+import { type EmbeddingProgress, type EmbeddingConfig, type EmbeddableNode, type SemanticSearchResult } from './types.js';
+/**
+ * Compute a stable content fingerprint for an embeddable node.
+ * Used to detect when the underlying text has changed so stale vectors
+ * can be replaced (DELETE-then-INSERT, the Kuzu-sanctioned pattern for
+ * vector-indexed rows).
+ */
+export declare const contentHashForNode: (node: EmbeddableNode, config?: Partial<EmbeddingConfig>) => string;
 /**
  * Progress callback type
  */
@@ -20,9 +27,11 @@ export type EmbeddingProgressCallback = (progress: EmbeddingProgress) => void;
  * @param executeWithReusedStatement - Function to execute with reused prepared statement
  * @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 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>) => 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>, existingEmbeddings?: Map<string, string>) => Promise<void>;
 /**
  * Perform semantic search using the vector index
  *

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

@@ -8,10 +8,23 @@
  * 4. Update LadybugDB with embeddings
  * 5. Create vector index for semantic search
  */
+import { createHash } from 'crypto';
 import { initEmbedder, embedBatch, embedText, embeddingToArray, isEmbedderReady, } from './embedder.js';
-import { generateBatchEmbeddingTexts } from './text-generator.js';
+import { generateEmbeddingText, generateBatchEmbeddingTexts } from './text-generator.js';
 import { DEFAULT_EMBEDDING_CONFIG, EMBEDDABLE_LABELS, } from './types.js';
+import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, CREATE_VECTOR_INDEX_QUERY, } from '../lbug/schema.js';
+import { loadVectorExtension } from '../lbug/lbug-adapter.js';
 const isDev = process.env.NODE_ENV === 'development';
+/**
+ * Compute a stable content fingerprint for an embeddable node.
+ * Used to detect when the underlying text has changed so stale vectors
+ * can be replaced (DELETE-then-INSERT, the Kuzu-sanctioned pattern for
+ * vector-indexed rows).
+ */
+export const contentHashForNode = (node, config = {}) => {
+    const text = generateEmbeddingText(node, config);
+    return createHash('sha1').update(text).digest('hex');
+};
 /**
  * Query all embeddable nodes from LadybugDB
  * Uses table-specific queries (File has different schema than code elements)
@@ -68,33 +81,25 @@ const queryEmbeddableNodes = async (executeQuery) => {
  */
 const batchInsertEmbeddings = async (executeWithReusedStatement, updates) => {
     // MERGE instead of CREATE — idempotent, handles concurrent analyzes and partial prior runs
-    const cypher = `MERGE (e:CodeEmbedding {nodeId: $nodeId}) SET e.embedding = $embedding`;
-    const paramsList = updates.map((u) => ({ nodeId: u.id, embedding: u.embedding }));
+    const cypher = `MERGE (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) SET e.embedding = $embedding, e.contentHash = $contentHash`;
+    const paramsList = updates.map((u) => ({
+        nodeId: u.id,
+        embedding: u.embedding,
+        contentHash: u.contentHash,
+    }));
     await executeWithReusedStatement(cypher, paramsList);
 };
 /**
  * Create the vector index for semantic search
- * Now indexes the separate CodeEmbedding table
+ * Now indexes the separate CodeEmbedding table.
+ * Delegates extension loading to lbug-adapter's loadVectorExtension(),
+ * which owns the VECTOR extension lifecycle and state tracking.
  */
-let vectorExtensionLoaded = false;
 const createVectorIndex = async (executeQuery) => {
-    // LadybugDB v0.15+ requires explicit VECTOR extension loading (once per session)
-    if (!vectorExtensionLoaded) {
-        try {
-            await executeQuery('INSTALL VECTOR');
-            await executeQuery('LOAD EXTENSION VECTOR');
-            vectorExtensionLoaded = true;
-        }
-        catch {
-            // Extension may already be loaded — CREATE_VECTOR_INDEX will fail clearly if not
-            vectorExtensionLoaded = true;
-        }
-    }
-    const cypher = `
-    CALL CREATE_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 'embedding', metric := 'cosine')
-  `;
+    // Delegate to the adapter which tracks loaded state and handles DB reconnect resets
+    await loadVectorExtension();
     try {
-        await executeQuery(cypher);
+        await executeQuery(CREATE_VECTOR_INDEX_QUERY);
     }
     catch (error) {
         // Index might already exist
@@ -110,9 +115,11 @@ const createVectorIndex = async (executeQuery) => {
  * @param executeWithReusedStatement - Function to execute with reused prepared statement
  * @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 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) => {
+export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatement, onProgress, config = {}, existingEmbeddings) => {
     const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
     try {
         // Phase 1: Load embedding model
@@ -141,12 +148,50 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         }
         // Phase 2: Query embeddable nodes
         let nodes = await queryEmbeddableNodes(executeQuery);
-        // Incremental mode: filter out nodes that already have embeddings
-        if (skipNodeIds && skipNodeIds.size > 0) {
+        // 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();
+        if (existingEmbeddings && existingEmbeddings.size > 0) {
             const beforeCount = nodes.length;
-            nodes = nodes.filter((n) => !skipNodeIds.has(n.id));
+            const staleNodeIds = [];
+            nodes = nodes.filter((n) => {
+                const existingHash = existingEmbeddings.get(n.id);
+                if (existingHash === undefined) {
+                    // New node — needs embedding
+                    return true;
+                }
+                const currentHash = contentHashForNode(n, finalConfig);
+                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);
+                    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) {
+                    console.log(`🔄 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) {
-                console.log(`📦 Incremental embeddings: ${beforeCount} total, ${skipNodeIds.size} cached, ${nodes.length} to embed`);
+                console.log(`📦 Incremental embeddings: ${beforeCount} total, ${existingEmbeddings.size} cached, ${staleNodeIds.length} stale, ${nodes.length} to embed`);
             }
         }
         const totalNodes = nodes.length;
@@ -154,6 +199,10 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             console.log(`📊 Found ${totalNodes} embeddable nodes`);
         }
         if (totalNodes === 0) {
+            // 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);
             onProgress({
                 phase: 'ready',
                 percent: 100,
@@ -186,6 +235,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             const updates = batch.map((node, i) => ({
                 id: node.id,
                 embedding: embeddingToArray(embeddings[i]),
+                contentHash: computedStaleHashes.get(node.id) ?? contentHashForNode(node, finalConfig),
             }));
             await batchInsertEmbeddings(executeWithReusedStatement, updates);
             processedNodes += batch.length;
@@ -256,7 +306,7 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
     const queryVecStr = `[${queryVec.join(',')}]`;
     // Query the vector index on CodeEmbedding to get nodeIds and distances
     const vectorQuery = `
-    CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 
+    CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}', 
       CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${k})
     YIELD node AS emb, distance
     WITH emb, distance

package/dist/core/group/extractors/manifest-extractor.js

@@ -68,14 +68,29 @@ export function manifestSymbolUid(repo, contractId) {
 }
 export class ManifestExtractor {
     async extractFromManifest(links, dbExecutors) {
-        const contracts = [];
-        const crossLinks = [];
-        for (const link of links) {
+        const resolveCache = new Map();
+        const resolveOnce = (repo, link) => {
+            const key = `${repo}\u0000${link.type}\u0000${link.contract}`;
+            let pending = resolveCache.get(key);
+            if (!pending) {
+                pending = this.resolveSymbol(repo, link, dbExecutors);
+                resolveCache.set(key, pending);
+            }
+            return pending;
+        };
+        const perLink = await Promise.all(links.map(async (link) => {
             const contractId = this.buildContractId(link.type, link.contract);
             const providerRepo = link.role === 'provider' ? link.from : link.to;
             const consumerRepo = link.role === 'provider' ? link.to : link.from;
-            const providerSymbol = await this.resolveSymbol(providerRepo, link, dbExecutors);
-            const consumerSymbol = await this.resolveSymbol(consumerRepo, link, dbExecutors);
+            const [providerSymbol, consumerSymbol] = await Promise.all([
+                resolveOnce(providerRepo, link),
+                resolveOnce(consumerRepo, link),
+            ]);
+            return { link, contractId, providerRepo, consumerRepo, providerSymbol, consumerSymbol };
+        }));
+        const contracts = [];
+        const crossLinks = [];
+        for (const { link, contractId, providerRepo, consumerRepo, providerSymbol, consumerSymbol, } of perLink) {
             const providerRef = providerSymbol || { filePath: '', name: link.contract };
             const consumerRef = consumerSymbol || { filePath: '', name: link.contract };
             // When the resolver finds a real graph symbol we keep its uid, otherwise

package/dist/core/group/sync.js

@@ -6,6 +6,7 @@ import { readRegistry } from '../../storage/repo-manager.js';
 import { HttpRouteExtractor } from './extractors/http-route-extractor.js';
 import { GrpcExtractor } from './extractors/grpc-extractor.js';
 import { TopicExtractor } from './extractors/topic-extractor.js';
+import { ManifestExtractor } from './extractors/manifest-extractor.js';
 import { runExactMatch } from './matching.js';
 import { detectServiceBoundaries, assignService } from './service-boundary-detector.js';
 import { writeContractRegistry } from './storage.js';
@@ -34,10 +35,28 @@ function defaultResolveHandle(allEntries) {
         };
     };
 }
+/**
+ * Dedupe cross-links that point from the same consumer endpoint to the same
+ * provider endpoint for the same contract. Preserves first-seen order so the
+ * caller controls precedence (e.g., pass manifest links first).
+ */
+function dedupeCrossLinks(links) {
+    const seen = new Set();
+    const out = [];
+    for (const link of links) {
+        const key = `${link.from.repo}::${link.from.symbolUid}|${link.to.repo}::${link.to.symbolUid}|${link.type}|${link.contractId}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(link);
+    }
+    return out;
+}
 export async function syncGroup(config, opts) {
     const missingRepos = [];
     const repoSnapshots = {};
     let autoContracts = [];
+    let manifestCrossLinks = [];
     let dbExecutors;
     const eo = opts?.extractorOverride;
     if (eo && eo.length === 0) {
@@ -124,8 +143,37 @@ export async function syncGroup(config, opts) {
             }
         }
     }
+    // Process manifest links declared in group.yaml.
+    // ManifestExtractor is fully implemented but was never wired into this
+    // pipeline — config.links were parsed and validated but silently dropped.
+    // Placed after the DB try/finally: resolveSymbol falls back to synthetic
+    // UIDs when dbExecutors is undefined or a pool is closed, so cross-links
+    // are always generated regardless of whether real DB executors are available.
+    if (config.links.length > 0) {
+        // Warn about dangling links that reference repos not declared in config.repos.
+        // They still generate cross-links via synthetic UIDs (determinism is preserved),
+        // but the operator probably meant something that now silently does nothing useful.
+        const knownRepos = new Set(Object.keys(config.repos));
+        for (const link of config.links) {
+            const dangling = [link.from, link.to].filter((r) => !knownRepos.has(r));
+            if (dangling.length > 0) {
+                console.warn(`[group/sync] manifest link ${link.type}:${link.contract} references repos not in config.repos: ${dangling.join(', ')} — cross-links will use synthetic UIDs`);
+            }
+        }
+        const manifestEx = new ManifestExtractor();
+        const manifestResult = await manifestEx.extractFromManifest(config.links, dbExecutors);
+        autoContracts.push(...manifestResult.contracts);
+        manifestCrossLinks = manifestResult.crossLinks;
+        if (opts?.verbose) {
+            console.log(`  manifest: ${manifestCrossLinks.length} cross-links from ${config.links.length} declared links`);
+        }
+    }
     const { matched, unmatched } = runExactMatch(autoContracts);
-    const crossLinks = matched;
+    // Dedupe cross-links. Manifest contracts participate in runExactMatch, so a
+    // manifest-declared link can also emit a matchType:'exact' CrossLink with the
+    // same endpoints. Prefer the manifest version — it reflects operator intent
+    // and carries matchType:'manifest' which downstream consumers may rely on.
+    const crossLinks = dedupeCrossLinks([...manifestCrossLinks, ...matched]);
     const allContracts = autoContracts;
     const registry = {
         version: 1,

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

@@ -98,8 +98,18 @@ export declare const loadCachedEmbeddings: () => Promise<{
     embeddings: Array<{
         nodeId: string;
         embedding: number[];
+        contentHash?: string;
     }>;
 }>;
+/**
+ * Fetch existing embedding hashes from CodeEmbedding table for incremental embedding.
+ * Returns a Map<nodeId, contentHash> suitable for passing to `runEmbeddingPipeline`.
+ * Handles legacy DBs without the `contentHash` column (all rows treated as stale with empty hash).
+ * Returns undefined if the CodeEmbedding table does not exist.
+ *
+ * @param execQuery - Cypher query executor (typically pool-adapter's `executeQuery`)
+ */
+export declare const fetchExistingEmbeddingHashes: (execQuery: (cypher: string) => Promise<any[]>) => Promise<Map<string, string> | undefined>;
 export declare const closeLbug: () => Promise<void>;
 export declare const isLbugReady: () => boolean;
 /**

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

@@ -5,7 +5,7 @@ import { once } from 'events';
 import { finished } from 'stream/promises';
 import path from 'path';
 import lbug from '@ladybugdb/core';
-import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, } from './schema.js';
+import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 /**
  * Split a relationship CSV into per-label-pair files on disk.
@@ -110,6 +110,14 @@ let conn = null;
 let currentDbPath = null;
 let ftsLoaded = false;
 let vectorExtensionLoaded = false;
+/**
+ * Check if an error indicates a missing column or table (schema-level problem)
+ * rather than a transient/connection error. Used for legacy DB fallback logic.
+ */
+const isMissingColumnOrTableError = (msg) => msg.includes('does not exist') ||
+    // Kuzu-specific: "(table|column|property) ... not found" — narrow enough to avoid
+    // matching transient errors like "connection not found" or "key not found".
+    /(table|column|property).*not found/i.test(msg);
 /** Expose the current Database for pool adapter reuse in tests. */
 export const getDatabase = () => db;
 // Global session lock for operations that touch module-level lbug globals.
@@ -791,7 +799,24 @@ export const loadCachedEmbeddings = async () => {
     const embeddingNodeIds = new Set();
     const embeddings = [];
     try {
-        const rows = await conn.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.embedding AS embedding`);
+        // Try to read contentHash alongside the embedding
+        let rows;
+        let hasContentHash = true;
+        try {
+            rows = await conn.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.embedding AS embedding, e.contentHash AS contentHash`);
+        }
+        catch (err) {
+            // Only fall back for missing-column errors (legacy DBs without contentHash).
+            // Rethrow transient / connection errors so callers see them.
+            const msg = err?.message ?? '';
+            if (isMissingColumnOrTableError(msg)) {
+                hasContentHash = false;
+                rows = await conn.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.embedding AS embedding`);
+            }
+            else {
+                throw err;
+            }
+        }
         const result = Array.isArray(rows) ? rows[0] : rows;
         for (const row of await result.getAll()) {
             const nodeId = String(row.nodeId ?? row[0] ?? '');
@@ -805,6 +830,7 @@ export const loadCachedEmbeddings = async () => {
                     embedding: Array.isArray(embedding)
                         ? embedding.map(Number)
                         : Array.from(embedding).map(Number),
+                    contentHash: hasContentHash ? (row.contentHash ?? row[2] ?? undefined) : undefined,
                 });
             }
         }
@@ -814,6 +840,59 @@ export const loadCachedEmbeddings = async () => {
     }
     return { embeddingNodeIds, embeddings };
 };
+/**
+ * Fetch existing embedding hashes from CodeEmbedding table for incremental embedding.
+ * Returns a Map<nodeId, contentHash> suitable for passing to `runEmbeddingPipeline`.
+ * Handles legacy DBs without the `contentHash` column (all rows treated as stale with empty hash).
+ * Returns undefined if the CodeEmbedding table does not exist.
+ *
+ * @param execQuery - Cypher query executor (typically pool-adapter's `executeQuery`)
+ */
+export const fetchExistingEmbeddingHashes = async (execQuery) => {
+    try {
+        const rows = await execQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.contentHash AS contentHash`);
+        if (!rows || rows.length === 0)
+            return undefined;
+        const map = new Map();
+        for (const r of rows) {
+            const nodeId = r.nodeId ?? r[0];
+            const hash = r.contentHash ?? r[1] ?? STALE_HASH_SENTINEL;
+            if (nodeId) {
+                // Empty/null contentHash means legacy row — treat as stale so it gets re-embedded
+                map.set(nodeId, hash || STALE_HASH_SENTINEL);
+            }
+        }
+        return map;
+    }
+    catch (err) {
+        const msg = err?.message ?? '';
+        if (isMissingColumnOrTableError(msg)) {
+            // Column or table missing — try fallback without contentHash
+            try {
+                const rows = await execQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId`);
+                if (!rows || rows.length === 0)
+                    return undefined;
+                const map = new Map();
+                for (const r of rows) {
+                    const nodeId = r.nodeId ?? r[0];
+                    if (nodeId)
+                        map.set(nodeId, STALE_HASH_SENTINEL); // no contentHash — treat as stale
+                }
+                console.log(`[embed] ${map.size} nodes in legacy DB (no contentHash) — all treated as stale`);
+                return map;
+            }
+            catch (fallbackErr) {
+                const fallbackMsg = fallbackErr?.message ?? '';
+                if (isMissingColumnOrTableError(fallbackMsg)) {
+                    console.log(`[embed] CodeEmbedding table not yet present — full embedding run (${fallbackMsg})`);
+                    return undefined;
+                }
+                throw fallbackErr;
+            }
+        }
+        throw err;
+    }
+};
 export const closeLbug = async () => {
     if (conn) {
         try {

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

@@ -43,6 +43,13 @@ export declare const TOOL_SCHEMA = "\nCREATE NODE TABLE Tool (\n  id STRING,\n
 export declare const SECTION_SCHEMA = "\nCREATE NODE TABLE Section (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  level INT64,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const RELATION_SCHEMA = "\nCREATE REL TABLE CodeRelation (\n  FROM File TO File,\n  FROM File TO Folder,\n  FROM File TO Function,\n  FROM File TO Class,\n  FROM File TO Interface,\n  FROM File TO Method,\n  FROM File TO CodeElement,\n  FROM File TO `Struct`,\n  FROM File TO `Enum`,\n  FROM File TO `Macro`,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Trait`,\n  FROM File TO `Impl`,\n  FROM File TO `TypeAlias`,\n  FROM File TO `Const`,\n  FROM File TO `Static`,\n  FROM File TO `Property`,\n  FROM File TO `Record`,\n  FROM File TO `Delegate`,\n  FROM File TO `Annotation`,\n  FROM File TO `Constructor`,\n  FROM File TO `Template`,\n  FROM File TO `Module`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO Function,\n  FROM Function TO Method,\n  FROM Function TO Class,\n  FROM Function TO Community,\n  FROM Function TO `Macro`,\n  FROM Function TO `Struct`,\n  FROM Function TO `Template`,\n  FROM Function TO `Enum`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `TypeAlias`,\n  FROM Function TO `Module`,\n  FROM Function TO `Impl`,\n  FROM Function TO Interface,\n  FROM Function TO `Constructor`,\n  FROM Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\n  FROM Function TO CodeElement,\n  FROM Class TO Method,\n  FROM Class TO Function,\n  FROM Class TO Class,\n  FROM Class TO Interface,\n  FROM Class TO Community,\n  FROM Class TO `Template`,\n  FROM Class TO `TypeAlias`,\n  FROM Class TO `Struct`,\n  FROM Class TO `Enum`,\n  FROM Class TO `Annotation`,\n  FROM Class TO `Constructor`,\n  FROM Class TO `Trait`,\n  FROM Class TO `Macro`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO `Property`,\n  FROM Method TO Function,\n  FROM Method TO Method,\n  FROM Method TO Class,\n  FROM Method TO Community,\n  FROM Method TO `Template`,\n  FROM Method TO `Struct`,\n  FROM Method TO `TypeAlias`,\n  FROM Method TO `Enum`,\n  FROM Method TO `Macro`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Module`,\n  FROM Method TO `Impl`,\n  FROM Method TO Interface,\n  FROM Method TO `Constructor`,\n  FROM Method TO `Property`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO `Module`,\n  FROM Section TO Section,\n  FROM Section TO File,\n  FROM File TO Route,\n  FROM Function TO Route,\n  FROM Method TO Route,\n  FROM File TO Tool,\n  FROM Function TO Tool,\n  FROM Method TO Tool,\n  FROM CodeElement TO Community,\n  FROM Interface TO Community,\n  FROM Interface TO Function,\n  FROM Interface TO Method,\n  FROM Interface TO Class,\n  FROM Interface TO Interface,\n  FROM Interface TO `TypeAlias`,\n  FROM Interface TO `Struct`,\n  FROM Interface TO `Constructor`,\n  FROM Interface TO `Property`,\n  FROM `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO `Struct`,\n  FROM `Struct` TO Class,\n  FROM `Struct` TO `Enum`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Struct` TO Interface,\n  FROM `Struct` TO `Constructor`,\n  FROM `Struct` TO `Property`,\n  FROM `Enum` TO `Enum`,\n  FROM `Enum` TO Community,\n  FROM `Enum` TO Class,\n  FROM `Enum` TO Interface,\n  FROM `Macro` TO Community,\n  FROM `Macro` TO Function,\n  FROM `Macro` TO Method,\n  FROM `Module` TO Function,\n  FROM `Module` TO Method,\n  FROM `Typedef` TO Community,\n  FROM `Union` TO Community,\n  FROM `Namespace` TO Community,\n  FROM `Namespace` TO `Struct`,\n  FROM `Trait` TO Method,\n  FROM `Trait` TO `Constructor`,\n  FROM `Trait` TO `Property`,\n  FROM `Trait` TO Community,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `TypeAlias` TO Community,\n  FROM `TypeAlias` TO `Trait`,\n  FROM `TypeAlias` TO Class,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Property` TO Community,\n  FROM `Record` TO Method,\n  FROM `Record` TO `Constructor`,\n  FROM `Record` TO `Property`,\n  FROM `Record` TO Community,\n  FROM `Delegate` TO Community,\n  FROM `Annotation` TO Community,\n  FROM `Constructor` TO Community,\n  FROM `Constructor` TO Interface,\n  FROM `Constructor` TO Class,\n  FROM `Constructor` TO Method,\n  FROM `Constructor` TO Function,\n  FROM `Constructor` TO `Constructor`,\n  FROM `Constructor` TO `Struct`,\n  FROM `Constructor` TO `Macro`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `TypeAlias`,\n  FROM `Constructor` TO `Enum`,\n  FROM `Constructor` TO `Annotation`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Module`,\n  FROM `Constructor` TO `Property`,\n  FROM `Constructor` TO `Typedef`,\n  FROM `Template` TO Community,\n  FROM `Module` TO Community,\n  FROM Function TO Process,\n  FROM Method TO Process,\n  FROM Class TO Process,\n  FROM Interface TO Process,\n  FROM `Struct` TO Process,\n  FROM `Constructor` TO Process,\n  FROM `Module` TO Process,\n  FROM `Macro` TO Process,\n  FROM `Impl` TO Process,\n  FROM `Typedef` TO Process,\n  FROM `TypeAlias` TO Process,\n  FROM `Enum` TO Process,\n  FROM `Union` TO Process,\n  FROM `Namespace` TO Process,\n  FROM `Trait` TO Process,\n  FROM `Const` TO Process,\n  FROM `Static` TO Process,\n  FROM `Property` TO Process,\n  FROM `Record` TO Process,\n  FROM `Delegate` TO Process,\n  FROM `Annotation` TO Process,\n  FROM `Template` TO Process,\n  FROM CodeElement TO Process,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
 export declare const EMBEDDING_DIMS: number;
+/** HNSW vector index name for the CodeEmbedding table. */
+export declare const EMBEDDING_INDEX_NAME = "code_embedding_idx";
+/**
+ * Sentinel value for "no content hash available" — used in legacy DBs and null rows.
+ * Nodes with this hash are always treated as stale and re-embedded.
+ */
+export declare const STALE_HASH_SENTINEL = "";
 export declare const EMBEDDING_SCHEMA: string;
 /**
  * Create vector index for semantic search

package/dist/core/lbug/schema.js

@@ -410,10 +410,18 @@ if (Number.isNaN(_rawDims) || _rawDims <= 0) {
     throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${process.env.GITNEXUS_EMBEDDING_DIMS}"`);
 }
 export const EMBEDDING_DIMS = _rawDims;
+/** HNSW vector index name for the CodeEmbedding table. */
+export const EMBEDDING_INDEX_NAME = 'code_embedding_idx';
+/**
+ * Sentinel value for "no content hash available" — used in legacy DBs and null rows.
+ * Nodes with this hash are always treated as stale and re-embedded.
+ */
+export const STALE_HASH_SENTINEL = '';
 export const EMBEDDING_SCHEMA = `
 CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
   nodeId STRING,
   embedding FLOAT[${EMBEDDING_DIMS}],
+  contentHash STRING,
   PRIMARY KEY (nodeId)
 )`;
 /**
@@ -421,7 +429,7 @@ CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
  * Uses HNSW (Hierarchical Navigable Small World) algorithm with cosine similarity
  */
 export const CREATE_VECTOR_INDEX_QUERY = `
-CALL CREATE_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', 'code_embedding_idx', 'embedding', metric := 'cosine')
+CALL CREATE_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}', 'embedding', metric := 'cosine')
 `;
 // ============================================================================
 // ALL SCHEMA QUERIES IN ORDER

package/dist/core/run-analyze.js

@@ -15,6 +15,8 @@ import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReuse
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, } from '../storage/repo-manager.js';
 import { getCurrentCommit, hasGitDir } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
+import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
+import { STALE_HASH_SENTINEL } from './lbug/schema.js';
 /** Threshold: auto-skip embeddings for repos with more nodes than this */
 const EMBEDDING_NODE_LIMIT = 50_000;
 export const PHASE_LABELS = {
@@ -147,9 +149,13 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 const EMBED_BATCH = 200;
                 for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
                     const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
-                    const paramsList = batch.map((e) => ({ nodeId: e.nodeId, embedding: e.embedding }));
+                    const paramsList = batch.map((e) => ({
+                        nodeId: e.nodeId,
+                        embedding: e.embedding,
+                        contentHash: e.contentHash ?? STALE_HASH_SENTINEL,
+                    }));
                     try {
-                        await executeWithReusedStatement(`MERGE (e:CodeEmbedding {nodeId: $nodeId}) SET e.embedding = $embedding`, paramsList);
+                        await executeWithReusedStatement(`MERGE (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) SET e.embedding = $embedding, e.contentHash = $contentHash`, paramsList);
                     }
                     catch {
                         /* some may fail if node was removed, that's fine */
@@ -170,6 +176,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             const httpMode = isHttpMode();
             progress('embeddings', 90, httpMode ? 'Connecting to embedding endpoint...' : 'Loading embedding model...');
             const { runEmbeddingPipeline } = await import('./embeddings/embedding-pipeline.js');
+            // Build a Map<nodeId, contentHash> from cached embeddings for incremental mode
+            let existingEmbeddings;
+            if (cachedEmbeddingNodeIds.size > 0) {
+                existingEmbeddings = new Map();
+                for (const e of cachedEmbeddings) {
+                    existingEmbeddings.set(e.nodeId, e.contentHash ?? STALE_HASH_SENTINEL);
+                }
+            }
             await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
                 const scaled = 90 + Math.round((p.percent / 100) * 8);
                 const label = p.phase === 'loading-model'
@@ -178,14 +192,14 @@ 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);
+            }, {}, existingEmbeddings);
         }
         // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
         progress('done', 98, 'Saving metadata...');
         // Count embeddings in the index (cached + newly generated)
         let embeddingCount = 0;
         try {
-            const embResult = await executeQuery(`MATCH (e:CodeEmbedding) RETURN count(e) AS cnt`);
+            const embResult = await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`);
             embeddingCount = embResult?.[0]?.cnt ?? 0;
         }
         catch {

package/dist/server/api.js

@@ -1277,25 +1277,12 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     const lbugPath = path.join(entry.storagePath, 'lbug');
                     await withLbugDb(lbugPath, async () => {
                         const { runEmbeddingPipeline } = await import('../core/embeddings/embedding-pipeline.js');
-                        // Skip nodes that already have embeddings — Kuzu forbids SET on vector-indexed properties.
-                        let skipNodeIds;
-                        try {
-                            const rows = await executeQuery('MATCH (e:CodeEmbedding) RETURN e.nodeId AS nodeId');
-                            if (rows && rows.length > 0) {
-                                skipNodeIds = new Set(rows.map((r) => r.nodeId ?? r[0]).filter(Boolean));
-                                console.log(`[embed] ${skipNodeIds.size} nodes already embedded — skipping in incremental run`);
-                            }
-                        }
-                        catch (err) {
-                            // Swallow only "table does not exist" — let real connection errors propagate.
-                            // Log so ops can see this path fire if Kuzu ever changes error wording.
-                            const msg = err?.message ?? '';
-                            if (msg.includes('does not exist') || msg.includes('not found')) {
-                                console.log(`[embed] CodeEmbedding table not yet present — full embedding run (${msg})`);
-                            }
-                            else {
-                                throw err;
-                            }
+                        // Fetch existing content hashes for incremental embedding.
+                        // Delegated to lbug-adapter which owns the DB query logic and legacy-fallback handling.
+                        const { fetchExistingEmbeddingHashes } = await import('../core/lbug/lbug-adapter.js');
+                        const existingEmbeddings = await fetchExistingEmbeddingHashes(executeQuery);
+                        if (existingEmbeddings && existingEmbeddings.size > 0) {
+                            console.log(`[embed] ${existingEmbeddings.size} nodes already embedded — incremental run with content-hash comparison`);
                         }
                         await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
                             embedJobManager.updateJob(job.id, {
@@ -1313,8 +1300,8 @@ export const createServer = async (port, host = '127.0.0.1') => {
                                                     : `${p.phase} (${p.percent}%)`,
                                 },
                             });
-                        }, {}, // config: use defaults (runEmbeddingPipeline signature: executeQuery, executeWithReusedStatement, onProgress, config, skipNodeIds)
-                        skipNodeIds);
+                        }, {}, // config: use defaults
+                        existingEmbeddings);
                     });
                     clearTimeout(embedTimeout);
                     releaseRepoLock(repoLockPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.2-rc.3",
+  "version": "1.6.2-rc.5",
   "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",
@@ -71,7 +71,7 @@
     "pandemonium": "^2.4.0",
     "tree-sitter": "^0.21.1",
     "tree-sitter-c": "0.23.2",
-    "tree-sitter-c-sharp": "^0.23.1",
+    "tree-sitter-c-sharp": "0.23.1",
     "tree-sitter-cpp": "^0.23.4",
     "tree-sitter-go": "^0.23.0",
     "tree-sitter-java": "^0.23.5",