gitnexus 1.6.12-rc.26 → 1.6.12-rc.28

package/dist/cli/embeddings-sync.d.ts

@@ -0,0 +1,2 @@
+/** Add missing embeddings directly to a healthy index, checkpointing periodically. */
+export declare const embeddingsSyncCommand: (inputPath?: string) => Promise<void>;

package/dist/cli/embeddings-sync.js

@@ -0,0 +1,127 @@
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { cliInfo } from './cli-message.js';
+import { getGitRoot } from '../storage/git.js';
+import { acquireIndexLock } from '../storage/index-lock.js';
+import { getStoragePaths, loadMeta, saveMeta } from '../storage/repo-manager.js';
+import { closeLbug, executeQuery, executeWithReusedStatement, fetchExistingEmbeddingHashes, initLbug, } from '../core/lbug/lbug-adapter.js';
+import { runEmbeddingPipeline } from '../core/embeddings/embedding-pipeline.js';
+import { resolveEmbeddingIdentity } from '../core/embeddings/embedding-identity.js';
+import { checkpointKind, decideEmbeddingResume, mintInterruptedCheckpoint, mintPartialCheckpoint, mintUnverifiedCountCheckpoint, } from '../core/embedding-checkpoint.js';
+import { measurePersistedEmbeddingCount, persistedEmbeddingCountOrUndefined, } from '../core/embedding-count.js';
+/** Add missing embeddings directly to a healthy index, checkpointing periodically. */
+export const embeddingsSyncCommand = async (inputPath) => {
+    const repoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());
+    if (!repoPath)
+        throw new Error('Not inside a git repository. Pass a repository path.');
+    const { lbugPath, metaPath } = getStoragePaths(repoPath);
+    const metaDir = path.dirname(metaPath);
+    const lock = await acquireIndexLock(metaDir);
+    try {
+        const meta = await loadMeta(metaDir);
+        if (!meta)
+            throw new Error(`No GitNexus index found for ${repoPath}. Run gitnexus analyze first.`);
+        if (meta.incrementalInProgress) {
+            throw new Error('The structural index is incomplete. Run gitnexus analyze --force first.');
+        }
+        let lbugStat;
+        try {
+            lbugStat = await lstat(lbugPath);
+        }
+        catch {
+            throw new Error(`The LadybugDB graph store at ${lbugPath} is missing. Run gitnexus analyze first.`);
+        }
+        if (!lbugStat.isFile()) {
+            throw new Error(`The LadybugDB graph store at ${lbugPath} is not a usable database file. Run gitnexus analyze first.`);
+        }
+        const identity = resolveEmbeddingIdentity();
+        let forceReembedNodeIds;
+        let resumedFrom;
+        if (meta.embeddingCheckpoint) {
+            const checkpoint = meta.embeddingCheckpoint;
+            const decision = decideEmbeddingResume(checkpoint, identity);
+            if (decision.action === 'abort')
+                throw new Error(decision.error);
+            const identityDiffers = checkpoint.provider !== identity.provider ||
+                checkpoint.model !== identity.model ||
+                checkpoint.dimensions !== identity.dimensions;
+            // `abandon` on a non-interrupted foreign identity drops the pending set
+            // only. Existing rows stay; sync would then embed the holes under the new
+            // identity and mix vector spaces. Fail closed — rebuild via analyze.
+            if (identityDiffers && checkpointKind(checkpoint) !== 'unverified-count') {
+                throw new Error(`Cannot sync embeddings: the index checkpoint was written by ${checkpoint.model} ` +
+                    `(${checkpoint.provider}) at ${checkpoint.dimensions} dimensions, but this run ` +
+                    `resolves ${identity.model} (${identity.provider}) at ${identity.dimensions}. ` +
+                    'Run `gitnexus analyze --embeddings --force` to rebuild under the new identity.');
+            }
+            cliInfo(decision.log);
+            if (decision.action === 'resume') {
+                forceReembedNodeIds = decision.pendingNodeIds;
+                resumedFrom = decision.resumedFrom;
+            }
+        }
+        await initLbug(lbugPath);
+        try {
+            const existing = await fetchExistingEmbeddingHashes(executeQuery);
+            let lastPercent = -1;
+            const countEmbeddings = async () => persistedEmbeddingCountOrUndefined(await measurePersistedEmbeddingCount(executeQuery));
+            const saveCheckpoint = async (checkpoint, pendingNodeIds, embeddings) => {
+                const latest = (await loadMeta(metaDir)) ?? meta;
+                await saveMeta(metaDir, {
+                    ...latest,
+                    ...(embeddings === undefined ? {} : { stats: { ...latest.stats, embeddings } }),
+                    embeddingCheckpoint: mintInterruptedCheckpoint(identity, checkpoint, pendingNodeIds),
+                });
+            };
+            cliInfo(`Embedding ${repoPath}`);
+            cliInfo(`Checkpointed nodes already present: ${existing?.size ?? 0}`);
+            const result = await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
+                const percent = Math.floor(progress.percent);
+                if (percent !== lastPercent && (percent % 5 === 0 || percent === 100)) {
+                    lastPercent = percent;
+                    cliInfo(`  ${percent}% — ${progress.nodesProcessed ?? 0}/${progress.totalNodes ?? '?'} nodes`);
+                }
+            }, {}, undefined, existing && existing.size ? existing : undefined, {
+                forceReembedNodeIds,
+                onCheckpointWindowStart: async ({ nodeIds, ...checkpoint }) => {
+                    await saveCheckpoint(checkpoint, nodeIds);
+                },
+                onCheckpoint: async (checkpoint) => {
+                    await saveCheckpoint(checkpoint, [], await countEmbeddings());
+                },
+            });
+            const embeddings = await countEmbeddings();
+            const latest = (await loadMeta(metaDir)) ?? meta;
+            if (embeddings === undefined) {
+                // Keep last-known stats.embeddings. An interrupted window marker would
+                // fail the identity gate on the next run even though this run finished;
+                // unverified-count is the recovery kind that forces a recount (#2790).
+                await saveMeta(metaDir, {
+                    ...latest,
+                    embeddingCheckpoint: result.failedNodeIds.length
+                        ? mintPartialCheckpoint(identity, result, resumedFrom)
+                        : mintUnverifiedCountCheckpoint(identity, {
+                            nodesProcessed: result.nodesProcessed,
+                            totalNodes: result.nodesProcessed,
+                            chunksProcessed: result.chunksProcessed,
+                        }),
+                });
+                throw new Error('Could not verify persisted embedding count.');
+            }
+            await saveMeta(metaDir, {
+                ...latest,
+                stats: { ...latest.stats, embeddings },
+                embeddingCheckpoint: result.failedNodeIds.length
+                    ? mintPartialCheckpoint(identity, result, resumedFrom)
+                    : undefined,
+            });
+            cliInfo(`Embeddings ready: ${embeddings}`);
+        }
+        finally {
+            await closeLbug().catch(() => { });
+        }
+    }
+    finally {
+        lock.release();
+    }
+};

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

@@ -140,6 +140,7 @@ export declare const en: {
     readonly 'help.watch.details': "\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
     readonly 'error.watch.ambiguous': "`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
     readonly 'help.command.analyze.description': "Index a repository (full analysis)";
+    readonly 'help.command.embeddings.sync.description': "Add missing embeddings to an existing index, checkpointing periodically for safe resume";
     readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
     readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
     readonly 'help.command.mcp.description': "Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).";
@@ -277,5 +278,5 @@ export declare const en: {
     readonly 'help.option.group.contracts.repo': "Filter by repo";
     readonly 'help.option.group.contracts.unmatched': "Show only unmatched contracts";
     readonly 'help.identityCache.environment': "\nAnalyzer identity cache:\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.";
-    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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\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 '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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\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

@@ -142,6 +142,7 @@ export const en = {
     'help.watch.details': '\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
     'error.watch.ambiguous': '`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
     'help.command.analyze.description': 'Index a repository (full analysis)',
+    'help.command.embeddings.sync.description': 'Add missing embeddings to an existing index, checkpointing periodically for safe resume',
     'help.command.index.description': 'Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)',
     'help.command.serve.description': 'Start local HTTP server for web UI connection',
     'help.command.mcp.description': 'Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).',
@@ -279,5 +280,5 @@ export const en = {
     'help.option.group.contracts.repo': 'Filter by repo',
     'help.option.group.contracts.unmatched': 'Show only unmatched contracts',
     'help.identityCache.environment': '\nAnalyzer identity cache:\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.',
-    '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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\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).',
+    '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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\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

@@ -141,6 +141,7 @@ export declare const cliResources: {
         readonly 'help.watch.details': "\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
         readonly 'error.watch.ambiguous': "`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
         readonly 'help.command.analyze.description': "Index a repository (full analysis)";
+        readonly 'help.command.embeddings.sync.description': "Add missing embeddings to an existing index, checkpointing periodically for safe resume";
         readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
         readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
         readonly 'help.command.mcp.description': "Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).";
@@ -278,7 +279,7 @@ export declare const cliResources: {
         readonly 'help.option.group.contracts.repo': "Filter by repo";
         readonly 'help.option.group.contracts.unmatched': "Show only unmatched contracts";
         readonly 'help.identityCache.environment': "\nAnalyzer identity cache:\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.";
-        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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\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 '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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\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;
@@ -422,6 +423,7 @@ export declare const cliResources: {
         'help.watch.details': string;
         'error.watch.ambiguous': string;
         'help.command.analyze.description': string;
+        'help.command.embeddings.sync.description': string;
         'help.command.index.description': string;
         'help.command.serve.description': string;
         'help.command.mcp.description': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -140,6 +140,7 @@ export declare const zhCN: {
     'help.watch.details': string;
     'error.watch.ambiguous': string;
     'help.command.analyze.description': string;
+    'help.command.embeddings.sync.description': string;
     'help.command.index.description': string;
     'help.command.serve.description': string;
     'help.command.mcp.description': string;

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

@@ -140,6 +140,7 @@ export const zhCN = {
     'help.watch.details': '\n`gitnexus watch` 不会启动监视器。\n  本地工作区增量索引：gitnexus analyze --watch\n  定时远程 clone/pull 并分析：gitnexus auto-sync start\n',
     'error.watch.ambiguous': '`gitnexus watch` 含义不明确。\n  本地工作区增量索引：gitnexus analyze --watch\n  定时远程 clone/pull 并分析：gitnexus auto-sync start\n',
     'help.command.analyze.description': '索引仓库（完整分析）',
+    'help.command.embeddings.sync.description': '向现有索引添加缺失的嵌入，并定期保存检查点以安全续跑',
     'help.command.index.description': '将现有 .gitnexus/ 文件夹注册到全局注册表（无需重新分析）',
     'help.command.serve.description': '启动供 Web UI 连接的本地 HTTP 服务器',
     'help.command.mcp.description': '启动 MCP 服务器。默认为 stdio。使用 --http 启动远程 HTTP 服务器（Streamable HTTP: POST /mcp + 遗留 SSE: GET /sse, POST /messages）。',
@@ -277,5 +278,5 @@ export const zhCN = {
     'help.option.group.contracts.repo': '按仓库过滤',
     'help.option.group.contracts.unmatched': '仅显示未匹配契约',
     'help.identityCache.environment': '\n分析器身份缓存：\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    由操作员明确信任的持久缓存，用于跨进程快速查询状态。目录必须预先存在、位于 GitNexus 包/构建根目录之外，且路径中不得包含符号链接或 junction。缺少 POSIX 所有权 API 的平台默认保持故障关闭。',
-    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  由操作员明确信任的持久分析器身份缓存；目录必须预先存在、位于包/构建根目录之外，且路径中不得包含符号链接或 junction。\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_WORKER_SHUTDOWN_DRAIN_MS=N  线程池关闭时等待仍在原生代码中的已退役 worker 的最长时间（到达安全点后再终止，避免进程级 abort）。默认 30000。\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  C++ 捕获提取的每文件墙钟预算；超出后该文件保留部分捕获并输出警告。默认 20000。\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）。',
+    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  由操作员明确信任的持久分析器身份缓存；目录必须预先存在、位于包/构建根目录之外，且路径中不得包含符号链接或 junction。\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_WORKER_SHUTDOWN_DRAIN_MS=N  线程池关闭时等待仍在原生代码中的已退役 worker 的最长时间（到达安全点后再终止，避免进程级 abort）。默认 30000。\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  C++ 捕获提取的每文件墙钟预算；超出后该文件保留部分捕获并输出警告。默认 20000。\n  GITNEXUS_EMBEDDING_THREADS=N  限制 --embeddings 的本地 ONNX CPU 线程数。\n  GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1  将单次 HTTP 嵌入超时纳入 GITNEXUS_EMBEDDING_MAX_ATTEMPTS 重试（默认关闭，超时仍为终止错误）。\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/cli/index.js

@@ -184,17 +184,21 @@ program
     .command('update')
     .description('Install the latest published GitNexus globally (`npm i -g gitnexus@<x.y.z>`).')
     .action(createLazyAction(() => import('./update.js'), 'updateCommand'));
-program
+const embeddings = program
     .command('embeddings')
-    .description('Manage the on-demand local embedding runtime')
+    .description(t('help.command.embeddings.description'));
+embeddings
     .command('install')
-    .description('Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. ' +
-    'Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). ' +
-    'Downloads only from your configured npm registry — mirrors and proxies apply.')
+    .description(t('help.command.embeddings.install.description'))
     .option('--cuda', "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; " +
     'set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)')
     .option('--force', 'Install into the runtime prefix even when the stack already resolves')
     .action(createLazyAction(() => import('./embeddings.js'), 'embeddingsInstallCommand'));
+embeddings
+    .command('sync [path]')
+    .description(t('help.command.embeddings.sync.description'))
+    .addHelpText('after', () => t('help.analyze.environment'))
+    .action(createLbugLazyAction(() => import('./embeddings-sync.js'), 'embeddingsSyncCommand'));
 program
     .command('clean')
     .description('Delete GitNexus index for current repo')

package/dist/core/embeddings/http-client.js

@@ -157,6 +157,7 @@ const readConfig = () => {
         retryCapMs: parsePositiveIntegerEnv('GITNEXUS_EMBEDDING_RETRY_CAP_MS', HTTP_RETRY_CAP_MS, 300_000),
         minIntervalMs: parseNonNegativeIntegerEnv('GITNEXUS_EMBEDDING_MIN_INTERVAL_MS', 0, 300_000),
         timeoutMs: parsePositiveIntegerEnv(HTTP_TIMEOUT_ENV, DEFAULT_HTTP_TIMEOUT_MS, MAX_HTTP_TIMEOUT_MS),
+        retryTimeouts: parseNonNegativeIntegerEnv('GITNEXUS_EMBEDDING_RETRY_TIMEOUTS', 0, 1) === 1,
         requestDimensions,
     };
 };
@@ -277,6 +278,23 @@ class RetryableEmbeddingBodyError extends Error {
         this.name = 'RetryableEmbeddingBodyError';
     }
 }
+class RetryableEmbeddingTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs, options) {
+        super(`Embedding request timed out after ${timeoutMs}ms`, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.timeoutMs = timeoutMs;
+        this.name = 'RetryableEmbeddingTimeoutError';
+    }
+}
+/** Re-wrap an opt-in TimeoutError so `resilientFetch` retries it. Abort stays terminal. */
+const throwIfRetryableTimeout = (err, retryTimeouts, callerAborted, timeoutMs) => {
+    if (retryTimeouts &&
+        !callerAborted &&
+        isTerminalNetworkError(err) &&
+        err.name === 'TimeoutError') {
+        throw new RetryableEmbeddingTimeoutError(timeoutMs, { cause: err });
+    }
+};
 /**
  * Build the message for a 2xx body carrying the wrong number of vectors.
  *
@@ -304,7 +322,7 @@ const countMismatchMessage = (received, expected, safeEndpoint, batchIndex) => `
  *   `GITNEXUS_EMBEDDING_REQUEST_DIMS=omit` for strict backends while keeping
  *   `GITNEXUS_EMBEDDING_DIMS` set to the returned vector size.
  */
-const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensions, requestOptions = {}, maxAttempts = HTTP_MAX_RETRIES + 1, retryCapMs = HTTP_RETRY_CAP_MS, minIntervalMs = 0, timeoutMs = DEFAULT_HTTP_TIMEOUT_MS) => {
+const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensions, requestOptions = {}, maxAttempts = HTTP_MAX_RETRIES + 1, retryCapMs = HTTP_RETRY_CAP_MS, minIntervalMs = 0, timeoutMs = DEFAULT_HTTP_TIMEOUT_MS, retryTimeouts = false) => {
     const requestBody = {
         input: batch,
         model,
@@ -341,7 +359,14 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
                 const signal = requestOptions.signal
                     ? AbortSignal.any([requestOptions.signal, timeoutSignal])
                     : timeoutSignal;
-                const attemptResp = await globalThis.fetch(input, { ...init, signal });
+                let attemptResp;
+                try {
+                    attemptResp = await globalThis.fetch(input, { ...init, signal });
+                }
+                catch (err) {
+                    throwIfRetryableTimeout(err, retryTimeouts, requestOptions.signal?.aborted, timeoutMs);
+                    throw err;
+                }
                 // Non-OK bodies are none of our business: hand the response straight
                 // back so `resilientFetch` keeps classifying 4xx/5xx/429 unchanged.
                 if (!attemptResp.ok)
@@ -361,15 +386,19 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
                     // Not every `.json()` rejection is a parse error: the per-attempt
                     // signal (`AbortSignal.any([caller, AbortSignal.timeout(...)])`) is
                     // wired to the body stream, so a stalled body rejects with the abort
-                    // reason. Re-raise those untouched — `isTerminalNetworkError` is
-                    // `resilientFetch`'s own predicate, so this test agrees with
-                    // `classifyOutcome` by construction. Wrapping one would flip its
-                    // verdict from `terminal-network` (returned without retry AND
-                    // without touching the breaker, via `recordNeutral()`) to
-                    // `retryable-network` (retried, then `breaker.recordFailure()`): the
-                    // same timeout would take 3 attempts instead of 1, count toward the
-                    // process-global `embeddings-http` breaker, and reach the operator as
-                    // "unparseable response" so they never reach for the timeout knob.
+                    // reason. Re-raise AbortError (and TimeoutError when retry is off)
+                    // untouched — `isTerminalNetworkError` is `resilientFetch`'s own
+                    // predicate, so this test agrees with `classifyOutcome` by
+                    // construction. Wrapping one would flip its verdict from
+                    // `terminal-network` (returned without retry AND without touching
+                    // the breaker, via `recordNeutral()`) to `retryable-network`
+                    // (retried, then `breaker.recordFailure()`): the same timeout would
+                    // take 3 attempts instead of 1, count toward the process-global
+                    // `embeddings-http` breaker, and reach the operator as "unparseable
+                    // response" so they never reach for the timeout knob.
+                    // Opt-in `GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1` is the exception:
+                    // TimeoutError is re-wrapped so the existing retry loop can retry it.
+                    throwIfRetryableTimeout(err, retryTimeouts, requestOptions.signal?.aborted, timeoutMs);
                     if (isTerminalNetworkError(err))
                         throw err;
                     throw new RetryableEmbeddingBodyError(unparseableMessage(), { cause: err });
@@ -411,6 +440,9 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
         if (err instanceof RetryableEmbeddingBodyError) {
             throw new HttpEmbeddingError(err.terminalMessage, { cause: err.cause });
         }
+        if (err instanceof RetryableEmbeddingTimeoutError) {
+            throw new HttpEmbeddingError(`${err.message} after ${maxAttempts} attempt(s) (${safeUrl(url)}, batch ${batchIndex})`, { cause: err.cause });
+        }
         if (err instanceof CircuitOpenError) {
             throw new HttpEmbeddingError(`Embedding endpoint circuit open (${safeUrl(url)}, batch ${batchIndex}): retry in ${Math.ceil(err.retryAfterMs / 1000)}s`, { cause: err });
         }
@@ -455,7 +487,7 @@ export const httpEmbed = async (texts, requestOptions = {}) => {
     const url = `${config.baseUrl}/embeddings`;
     const allVectors = [];
     for (const [batchIndex, batch] of chunk(texts, HTTP_BATCH_SIZE).entries()) {
-        const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs);
+        const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs, config.retryTimeouts);
         // Defensive backstop, deliberately kept: `httpEmbedBatch` now rejects a
         // short body from *inside* the retry loop (through the same
         // `countMismatchMessage`), so in practice this branch is unreachable. It
@@ -506,7 +538,7 @@ export const httpEmbedQuery = async (text, requestOptions = {}) => {
     if (!config)
         throw new Error('HTTP embedding not configured');
     const url = `${config.baseUrl}/embeddings`;
-    const items = await httpEmbedBatch(url, [text], config.model, config.apiKey, 0, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs);
+    const items = await httpEmbedBatch(url, [text], config.model, config.apiKey, 0, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs, config.retryTimeouts);
     // Defensive backstop like the `httpEmbed` one above: an empty `data` array is
     // now a cardinality mismatch (0 vectors for 1 text) rejected and retried
     // inside `httpEmbedBatch`, so this branch is unreachable in practice.

package/dist/core/ingestion/languages/ruby/import-target.d.ts

@@ -3,8 +3,9 @@
  *
  * Ruby import resolution rules:
  *   - `require_relative './foo'` → resolve relative to the importing file's dir
- *   - `require 'foo'`           → suffix-match via the existing Ruby import resolver
- *   - External gems             → null (unresolvable within the repo)
+ *   - `require 'foo'` → use scoped gem metadata before legacy suffix matching
+ *   - Known local gems → resolve only within their declared load roots
+ *   - Known external gems → null, even if an unrelated repo file suffix matches
  */
 export interface RubyResolveContext {
     readonly fromFile: string;
@@ -18,9 +19,10 @@ export interface RubyResolveContext {
  * against the importing file's directory, trying `.rb` and `/index.rb`
  * suffixes.
  *
- * For bare requires (gem-style like `'json'`, `'serializable'`), delegates
- * to the existing `resolveRubyImportInternal` which uses suffix matching.
- *
- * Returns `null` for external gems that have no matching file in the repo.
+ * For bare requires, scoped manifest metadata takes precedence: known local
+ * gems resolve only within their declared load roots (a miss returns `null`),
+ * and known external gem prefixes return `null` even if a repo suffix matches.
+ * Only requires without matching gem evidence delegate to the existing
+ * `resolveRubyImportInternal` suffix matcher.
  */
-export declare function resolveRubyImportTarget(targetRaw: string, fromFile: string, allFilePaths: ReadonlySet<string>, _resolutionConfig?: unknown): string | readonly string[] | null;
+export declare function resolveRubyImportTarget(targetRaw: string, fromFile: string, allFilePaths: ReadonlySet<string>, resolutionConfig?: unknown): string | readonly string[] | null;

package/dist/core/ingestion/languages/ruby/import-target.js

@@ -3,12 +3,14 @@
  *
  * Ruby import resolution rules:
  *   - `require_relative './foo'` → resolve relative to the importing file's dir
- *   - `require 'foo'`           → suffix-match via the existing Ruby import resolver
- *   - External gems             → null (unresolvable within the repo)
+ *   - `require 'foo'` → use scoped gem metadata before legacy suffix matching
+ *   - Known local gems → resolve only within their declared load roots
+ *   - Known external gems → null, even if an unrelated repo file suffix matches
  */
 import { resolveRubyImportInternal } from '../../import-resolvers/ruby.js';
 import { getWorkspaceFileIndex } from '../../import-resolvers/workspace-file-index.js';
 import { isHeritageMarker } from '../../utils/heritage-marker.js';
+import { findRubyResolutionScope, } from './resolution-config.js';
 // ─── resolveRubyImportTarget ──────────────────────────────────────────────
 /**
  * ScopeResolver-shaped adapter:
@@ -18,12 +20,13 @@ import { isHeritageMarker } from '../../utils/heritage-marker.js';
  * against the importing file's directory, trying `.rb` and `/index.rb`
  * suffixes.
  *
- * For bare requires (gem-style like `'json'`, `'serializable'`), delegates
- * to the existing `resolveRubyImportInternal` which uses suffix matching.
- *
- * Returns `null` for external gems that have no matching file in the repo.
+ * For bare requires, scoped manifest metadata takes precedence: known local
+ * gems resolve only within their declared load roots (a miss returns `null`),
+ * and known external gem prefixes return `null` even if a repo suffix matches.
+ * Only requires without matching gem evidence delegate to the existing
+ * `resolveRubyImportInternal` suffix matcher.
  */
-export function resolveRubyImportTarget(targetRaw, fromFile, allFilePaths, _resolutionConfig) {
+export function resolveRubyImportTarget(targetRaw, fromFile, allFilePaths, resolutionConfig) {
     if (!targetRaw)
         return null;
     if (isHeritageMarker(targetRaw))
@@ -37,7 +40,16 @@ export function resolveRubyImportTarget(targetRaw, fromFile, allFilePaths, _reso
         const resolved = resolveRelative(targetRaw, fromDir, allFilePaths);
         return resolved;
     }
-    // ── require: bare/gem-style suffix matching ─────────────────────────
+    // ── require: scoped gem evidence before repository-wide fallback ────
+    const config = resolutionConfig;
+    const scope = config === null || config === undefined ? undefined : findRubyResolutionScope(config, fromFile);
+    if (scope !== undefined) {
+        const localGemTarget = resolveLocalGemTarget(targetRaw, scope, allFilePaths);
+        if (localGemTarget !== undefined)
+            return localGemTarget;
+        if (matchesRequirePrefix(targetRaw, scope.externalRequirePrefixes))
+            return null;
+    }
     return resolveBare(targetRaw, allFilePaths);
 }
 // ─── internal helpers ─────────────────────────────────────────────────────
@@ -73,6 +85,55 @@ function resolveRelative(targetRaw, fromDir, allFilePaths) {
         return resolvedPath;
     return null;
 }
+/**
+ * Yield the require stem, then each slash-delimited ancestor. This makes both
+ * local-root and external-gem lookup O(require path depth), not O(gem count).
+ * A trailing `.rb` is stripped first so `require 'my_engine.rb'` matches the
+ * configured prefix `my_engine`, matching Ruby's optional-suffix require.
+ */
+function requirePrefixCandidates(targetRaw) {
+    const stem = targetRaw.endsWith('.rb') ? targetRaw.slice(0, -3) : targetRaw;
+    if (stem.length === 0)
+        return [];
+    const candidates = [stem];
+    let slash = stem.lastIndexOf('/');
+    while (slash !== -1) {
+        candidates.push(stem.slice(0, slash));
+        slash = stem.lastIndexOf('/', slash - 1);
+    }
+    return candidates;
+}
+function matchesRequirePrefix(targetRaw, prefixes) {
+    return requirePrefixCandidates(targetRaw).some((candidate) => prefixes.has(candidate));
+}
+/**
+ * Resolve a path/gemspec-backed gem against its declared Ruby load roots.
+ * `undefined` means no local-gem prefix matched; `null` means one matched but
+ * none of its declared load roots contained the target.
+ */
+function resolveLocalGemTarget(targetRaw, scope, allFilePaths) {
+    for (const prefix of requirePrefixCandidates(targetRaw)) {
+        const loadRoots = scope.localLoadRootsByPrefix.get(prefix);
+        if (loadRoots === undefined)
+            continue;
+        for (const loadRoot of loadRoots) {
+            const base = loadRoot ? `${loadRoot}/${targetRaw}` : targetRaw;
+            if (base.endsWith('.rb')) {
+                if (allFilePaths.has(base))
+                    return base;
+                continue;
+            }
+            const rbFile = `${base}.rb`;
+            if (allFilePaths.has(rbFile))
+                return rbFile;
+        }
+        // The prefix is owned by a known local gem. If its declared roots do not
+        // contain the target, repository-wide suffix matching would fabricate an
+        // edge to an unrelated file.
+        return null;
+    }
+    return undefined;
+}
 /**
  * Resolve a bare require path (`'serializable'`, `'json'`, `'net/http'`)
  * via suffix matching using the existing Ruby import resolver.

package/dist/core/ingestion/languages/ruby/resolution-config.d.ts

@@ -0,0 +1,28 @@
+export interface RubyResolutionScope {
+    /** Require prefixes provided by gems whose source is outside this repository. */
+    readonly externalRequirePrefixes: ReadonlySet<string>;
+    /** Require prefix -> repository-relative Ruby load roots for local gems. */
+    readonly localLoadRootsByPrefix: ReadonlyMap<string, readonly string[]>;
+}
+export interface RubyResolutionConfig {
+    /** Manifest directory (repository-relative POSIX path) -> dependency scope. */
+    readonly scopesByDirectory: ReadonlyMap<string, RubyResolutionScope>;
+}
+/**
+ * Select the nearest manifest directory that owns `fromFile`.
+ *
+ * Walking ancestors makes lookup O(path depth), independent of how many
+ * sibling Gemfiles a monorepo contains.
+ */
+export declare function findRubyResolutionScope(config: RubyResolutionConfig, fromFile: string): RubyResolutionScope | undefined;
+/**
+ * Statically collect Ruby dependency sources without evaluating Gemfile or
+ * gemspec code. Scopes stay separate by manifest directory so sibling projects
+ * in a monorepo cannot suppress one another's local imports. Lockfiles
+ * contribute remote GEM/GIT specs and local PATH/GEMSPEC load roots only when
+ * an adjacent Gemfile or gemspec establishes a Bundler/RubyGems project.
+ *
+ * No declarative manifest means no safe gate, so return null and preserve the
+ * resolver's existing fail-open behavior for loose script directories.
+ */
+export declare function loadRubyResolutionConfig(repoPath: string): RubyResolutionConfig | null;