gitnexus 1.6.9-rc.32 → 1.6.9-rc.34

package/dist/cli/i18n/en.d.ts

@@ -234,5 +234,5 @@ export declare const en: {
     readonly 'help.option.group.contracts.type': "Filter by contract type";
     readonly 'help.option.group.contracts.repo': "Filter by repo";
     readonly 'help.option.group.contracts.unmatched': "Show only unmatched contracts";
-    readonly 'help.analyze.environment': "\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_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\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\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).";
+    readonly 'help.analyze.environment': "\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_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\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  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).";
 };

package/dist/cli/i18n/en.js

@@ -234,5 +234,5 @@ export const en = {
     'help.option.group.contracts.type': 'Filter by contract type',
     'help.option.group.contracts.repo': 'Filter by repo',
     'help.option.group.contracts.unmatched': 'Show only unmatched contracts',
-    'help.analyze.environment': '\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_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\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\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).',
+    'help.analyze.environment': '\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_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\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  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).',
 };

package/dist/cli/i18n/resources.d.ts

@@ -235,7 +235,7 @@ export declare const cliResources: {
         readonly 'help.option.group.contracts.type': "Filter by contract type";
         readonly 'help.option.group.contracts.repo': "Filter by repo";
         readonly 'help.option.group.contracts.unmatched': "Show only unmatched contracts";
-        readonly 'help.analyze.environment': "\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_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\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\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).";
+        readonly 'help.analyze.environment': "\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_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\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  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).";
     };
     readonly 'zh-CN': {
         'common.notIndexed': string;

package/dist/cli/i18n/zh-CN.js

@@ -234,5 +234,5 @@ export const zhCN = {
     'help.option.group.contracts.type': '按契约类型过滤',
     'help.option.group.contracts.repo': '按仓库过滤',
     'help.option.group.contracts.unmatched': '仅显示未匹配契约',
-    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker 空闲超时（毫秒）。默认 30000。\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL 自动 checkpoint 阈值（字节，默认 67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker 作业字节预算。默认 8388608。\n  GITNEXUS_WORKER_POOL_SIZE=N  解析 worker 数量覆盖值。默认 cores-1，最多 16。\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  并发进行中的解析分块数。默认 2。\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  每个 slot 丢弃前允许的最大替换进程数。默认 3。\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  每个作业的总重试墙钟时间。默认 5 倍子批次超时。\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  每个 slot 触发熔断的死亡次数。默认 max(3, poolSize)。\n  GITNEXUS_EMBEDDING_THREADS=N  限制 --embeddings 的本地 ONNX CPU 线程数。\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  exact-scan 回退的最大嵌入分块数。默认 10000。\n\n当参数和对应环境变量同时提供时，参数优先。\n\n提示：`.gitnexusignore` 支持 `.gitignore` 风格的取反。比如添加\n     `!__tests__/` 可以索引默认自动过滤的目录（#771）。',
+    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker 空闲超时（毫秒）。默认 30000。\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL 自动 checkpoint 阈值（字节，默认 67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker 作业字节预算。默认 8388608。\n  GITNEXUS_WORKER_POOL_SIZE=N  解析 worker 数量覆盖值。默认 cores-1，最多 16。\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  并发进行中的解析分块数。默认 2。\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  每个 slot 丢弃前允许的最大替换进程数。默认 3。\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  每个作业的总重试墙钟时间。默认 5 倍子批次超时。\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  每个 slot 触发熔断的死亡次数。默认 max(3, poolSize)。\n  GITNEXUS_EMBEDDING_THREADS=N  限制 --embeddings 的本地 ONNX CPU 线程数。\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  exact-scan 回退的最大嵌入分块数。默认 10000。\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  语义/向量搜索接受的最大余弦距离（0 < N <= 2；超出则钳制为 2）。MCP 默认 0.6，其他路径默认 0.5。\n\n当参数和对应环境变量同时提供时，参数优先。\n\n提示：`.gitnexusignore` 支持 `.gitignore` 风格的取反。比如添加\n     `!__tests__/` 可以索引默认自动过滤的目录（#771）。',
 };

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

@@ -1,2 +1,17 @@
 import { type EmbeddingConfig } from './types.js';
+export declare const DEFAULT_VECTOR_MAX_DISTANCE = 0.5;
+export declare const DEFAULT_MCP_VECTOR_MAX_DISTANCE = 0.6;
+/**
+ * Cosine distance over normalized embeddings is bounded to [0, 2], so any threshold
+ * above this accepts every row and silently disables the relevance filter. Values
+ * over the ceiling are clamped to it rather than passed through.
+ */
+export declare const VECTOR_MAX_DISTANCE_CEILING = 2;
+/**
+ * Resolve the effective max accepted vector/semantic cosine distance.
+ * Reads `GITNEXUS_VECTOR_MAX_DISTANCE`. Unset/empty/whitespace → silent fallback.
+ * Invalid (non-numeric, <= 0, non-finite) → fallback plus a one-time warning.
+ * Values above the cosine ceiling (2) are clamped to it with a one-time warning.
+ */
+export declare const getVectorMaxDistance: (fallback?: number) => number;
 export declare const resolveEmbeddingConfig: (overrides?: Partial<EmbeddingConfig>) => EmbeddingConfig;

package/dist/core/embeddings/config.js

@@ -1,5 +1,42 @@
 import { defaultEmbeddingThreads } from '../platform/capabilities.js';
+import { logger } from '../logger.js';
 import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
+export const DEFAULT_VECTOR_MAX_DISTANCE = 0.5;
+export const DEFAULT_MCP_VECTOR_MAX_DISTANCE = 0.6;
+/**
+ * Cosine distance over normalized embeddings is bounded to [0, 2], so any threshold
+ * above this accepts every row and silently disables the relevance filter. Values
+ * over the ceiling are clamped to it rather than passed through.
+ */
+export const VECTOR_MAX_DISTANCE_CEILING = 2;
+const warned = new Set();
+const warnOnce = (key, message) => {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    logger.warn(message);
+};
+/**
+ * Resolve the effective max accepted vector/semantic cosine distance.
+ * Reads `GITNEXUS_VECTOR_MAX_DISTANCE`. Unset/empty/whitespace → silent fallback.
+ * Invalid (non-numeric, <= 0, non-finite) → fallback plus a one-time warning.
+ * Values above the cosine ceiling (2) are clamped to it with a one-time warning.
+ */
+export const getVectorMaxDistance = (fallback = DEFAULT_VECTOR_MAX_DISTANCE) => {
+    const raw = process.env.GITNEXUS_VECTOR_MAX_DISTANCE;
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        warnOnce(`invalid:${raw}`, `  GITNEXUS_VECTOR_MAX_DISTANCE must be a positive number in (0, ${VECTOR_MAX_DISTANCE_CEILING}], got "${raw}" — using default ${fallback}`);
+        return fallback;
+    }
+    if (parsed > VECTOR_MAX_DISTANCE_CEILING) {
+        warnOnce(`clamp:${raw}`, `  GITNEXUS_VECTOR_MAX_DISTANCE=${parsed} exceeds the cosine-distance ceiling (${VECTOR_MAX_DISTANCE_CEILING}) — clamping`);
+        return VECTOR_MAX_DISTANCE_CEILING;
+    }
+    return parsed;
+};
 const parsePositiveInt = (name, value, fallback) => {
     if (value === undefined)
         return fallback;

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

@@ -14,7 +14,7 @@ import { generateEmbeddingText } from './text-generator.js';
 import { chunkNode, characterChunk } from './chunker.js';
 import { extractStructuralNames } from './structural-extractor.js';
 import { EMBEDDABLE_LABELS, isShortLabel, LABEL_METHOD, LABELS_WITH_EXPORTED, STRUCTURAL_LABELS, collectBestChunks, } from './types.js';
-import { resolveEmbeddingConfig } from './config.js';
+import { DEFAULT_VECTOR_MAX_DISTANCE, getVectorMaxDistance, resolveEmbeddingConfig, } from './config.js';
 import { rankExactEmbeddingRows } from './exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, STALE_HASH_SENTINEL } from '../lbug/schema.js';
 import { loadVectorExtension, createVectorIndex } from '../lbug/lbug-adapter.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) {
@@ -447,7 +453,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
 /**
  * Perform semantic search using the vector index with chunk deduplication
  */
-export const semanticSearch = async (executeQuery, query, k = 10, maxDistance = 0.5) => {
+export const semanticSearch = async (executeQuery, query, k = 10, maxDistance = getVectorMaxDistance(DEFAULT_VECTOR_MAX_DISTANCE)) => {
     if (!isEmbedderReady()) {
         throw new Error('Embedding model not initialized. Run embedding pipeline first.');
     }
@@ -569,7 +575,7 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
  * Semantic search with graph expansion (flattened results)
  */
 export const semanticSearchWithContext = async (executeQuery, query, k = 5, _hops = 1) => {
-    const results = await semanticSearch(executeQuery, query, k, 0.5);
+    const results = await semanticSearch(executeQuery, query, k);
     return results.map((r) => ({
         matchId: r.nodeId,
         matchName: r.name,

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/mcp/local/local-backend.js

@@ -21,6 +21,7 @@ import { listRegisteredRepos, cleanupOldKuzuFiles, canonicalizePath, getStorageP
 import { GroupService, } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
+import { DEFAULT_MCP_VECTOR_MAX_DISTANCE, getVectorMaxDistance, } from '../../core/embeddings/config.js';
 import { rankExactEmbeddingRows, } from '../../core/embeddings/exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
 import { getExactScanLimit, isVectorExtensionSupportedByPlatform, } from '../../core/platform/capabilities.js';
@@ -1694,6 +1695,7 @@ export class LocalBackend {
             const queryVec = await embedQuery(query);
             const dims = getEmbeddingDims();
             const queryVecStr = `[${queryVec.join(',')}]`;
+            const maxDistance = getVectorMaxDistance(DEFAULT_MCP_VECTOR_MAX_DISTANCE);
             let bestChunks = new Map();
             if (isVectorExtensionSupportedByPlatform()) {
                 try {
@@ -1703,7 +1705,7 @@ export class LocalBackend {
               CAST(${queryVecStr} AS FLOAT[${dims}]), ${fetchLimit})
             YIELD node AS emb, distance
             WITH emb, distance
-            WHERE distance < 0.6
+            WHERE distance < ${maxDistance}
             RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
                    emb.startLine AS startLine, emb.endLine AS endLine, distance
             ORDER BY distance
@@ -1747,7 +1749,7 @@ export class LocalBackend {
                     endLine: row.endLine ?? row[3] ?? 0,
                     embedding: row.embedding ?? row[4] ?? [],
                 }));
-                bestChunks = new Map(rankExactEmbeddingRows(exactRows, queryVec, limit, 0.6).map((row) => [
+                bestChunks = new Map(rankExactEmbeddingRows(exactRows, queryVec, limit, maxDistance).map((row) => [
                     row.nodeId,
                     {
                         distance: row.distance,

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.32",
+  "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",