gitnexus 1.6.6-rc.150 → 1.6.6-rc.151

package/README.md

@@ -400,7 +400,7 @@ Values above **32768 KB (32 MB)** are clamped to the tree-sitter parser ceiling;
 
 ### Analyze reports a worker timeout
 
-Worker parse timeouts are recoverable. GitNexus retries stalled worker jobs with backoff, splits large jobs to isolate slow files, and falls back to the sequential parser when needed. If a large repository needs more time per worker job, use either:
+Worker parse timeouts are recoverable. GitNexus retries stalled worker jobs with backoff, splits large jobs to isolate slow files, and quarantines a file that repeatedly crashes its worker (respawning the slot so the pool keeps going). If a large repository needs more time per worker job, use either:
 
 ```bash
 # CLI flag, in seconds

package/dist/_shared/scope-resolution/parsed-file.d.ts

@@ -72,5 +72,29 @@ export interface ParsedFile {
      */
     readonly localDefs: readonly SymbolDefinition[];
     readonly referenceSites: readonly ReferenceSite[];
+    /**
+     * Opaque, language-private serialization of capture-time side-channel
+     * state that a provider's `emitScopeCaptures` populates into module-level
+     * maps as a SIDE EFFECT (not onto the scopes/defs of this `ParsedFile`).
+     *
+     * Such state is computed inside the parse worker (where `emitScopeCaptures`
+     * runs) and would otherwise be lost across the worker→main MessageChannel
+     * and the disk store, because scope-resolution reuses the serialized
+     * `ParsedFile` and SKIPS re-extraction on the main thread (#1983 — the
+     * whole point is to avoid a main-thread tree-sitter re-parse). Carrying the
+     * data here lets the main thread repopulate those maps WITHOUT re-parsing.
+     *
+     * Shared / ingestion code treats this as opaque (`unknown`) per AGENTS.md
+     * (no language names in shared code). The producing language fills it via
+     * the `LanguageProvider.collectCaptureSideChannel` hook (worker side) and
+     * consumes it via the `ScopeResolver.applyCaptureSideChannel` hook
+     * (main-thread resolution side). It MUST be plain JSON-serializable data
+     * (objects / arrays / primitives) so it round-trips through the disk-backed
+     * `parsedfile-store` (JSON.stringify + interning reviver).
+     *
+     * Optional: providers whose `emitScopeCaptures` is pure (no module-level
+     * side effects — the contract default) leave this undefined.
+     */
+    readonly captureSideChannel?: unknown;
 }
 //# sourceMappingURL=parsed-file.d.ts.map

package/dist/_shared/scope-resolution/parsed-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parsed-file.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/parsed-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;CACnD"}
+{"version":3,"file":"parsed-file.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/parsed-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC"}

package/dist/cli/analyze.d.ts

@@ -7,6 +7,15 @@
  * This CLI wrapper handles: heap management, progress bar, SIGINT,
  * skill generation (--skills), summary output, and process.exit().
  */
+/**
+ * RAM-aware re-exec heap cap (MB): `0.75 × effective RAM`, clamped to
+ * `>= DEFAULT_HEAP_MB`. Kept BELOW physical RAM on purpose — a cap `>=` RAM makes
+ * V8 collect lazily and inflate the heap into swap-thrash (observed analyzing the
+ * Linux kernel at a 30GB cap on a 31GB box). `constrainedBytes` is the cgroup
+ * limit or `null`; it is honored only as a real, smaller-than-physical cap, because
+ * `process.constrainedMemory()` returns a huge sentinel when UNCONSTRAINED.
+ */
+export declare function computeHeapCapMb(totalBytes: number, constrainedBytes: number | null): number;
 export interface AnalyzeOptions {
     force?: boolean;
     repairFts?: boolean;
@@ -78,7 +87,7 @@ export interface AnalyzeOptions {
     workerTimeout?: string;
     /** Control LadybugDB WAL auto-checkpoint threshold during analyze. */
     walCheckpointThreshold?: string;
-    /** Parse worker pool size; 0 disables workers (sequential fallback). */
+    /** Parse worker pool size (>=1); 0 is rejected (no sequential mode). */
     workers?: string;
     embeddingThreads?: string;
     embeddingBatchSize?: string;

package/dist/cli/analyze.js

@@ -8,6 +8,7 @@
  * skill generation (--skills), summary output, and process.exit().
  */
 import path from 'path';
+import os from 'os';
 import { spawn } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
@@ -63,12 +64,41 @@ const installFatalHandlers = () => {
         process.exit(1);
     });
 };
-const HEAP_MB = 16384;
+/** Historical floor for the re-exec heap cap — the auto-sizer never goes below
+ *  this, so small boxes / CI never regress. */
+const DEFAULT_HEAP_MB = 16384;
+/**
+ * RAM-aware re-exec heap cap (MB): `0.75 × effective RAM`, clamped to
+ * `>= DEFAULT_HEAP_MB`. Kept BELOW physical RAM on purpose — a cap `>=` RAM makes
+ * V8 collect lazily and inflate the heap into swap-thrash (observed analyzing the
+ * Linux kernel at a 30GB cap on a 31GB box). `constrainedBytes` is the cgroup
+ * limit or `null`; it is honored only as a real, smaller-than-physical cap, because
+ * `process.constrainedMemory()` returns a huge sentinel when UNCONSTRAINED.
+ */
+export function computeHeapCapMb(totalBytes, constrainedBytes) {
+    const effectiveBytes = constrainedBytes !== null && constrainedBytes > 0 && constrainedBytes < totalBytes
+        ? constrainedBytes
+        : totalBytes;
+    const effectiveMb = Math.floor(effectiveBytes / (1024 * 1024));
+    return Math.max(DEFAULT_HEAP_MB, Math.floor(0.75 * effectiveMb));
+}
+function readConstrainedBytes() {
+    if (typeof process.constrainedMemory !== 'function')
+        return null;
+    const c = process.constrainedMemory();
+    return typeof c === 'number' && c > 0 ? c : null;
+}
+const HEAP_MB = computeHeapCapMb(os.totalmem(), readConstrainedBytes());
 const TEST_RESPAWN_HEAP_MB = Number(process.env.GITNEXUS_TEST_RESPAWN_HEAP_MB);
 const RESPAWN_HEAP_MB = Number.isFinite(TEST_RESPAWN_HEAP_MB) && TEST_RESPAWN_HEAP_MB > 0
     ? Math.floor(TEST_RESPAWN_HEAP_MB)
     : HEAP_MB;
 const HEAP_FLAG = `--max-old-space-size=${RESPAWN_HEAP_MB}`;
+/** Larger semi-space (young-gen) cuts minor-GC frequency + promotion churn during
+ *  the multi-million-node graph build/emit. Allowed in NODE_OPTIONS (unlike
+ *  --stack-size), so it propagates to the re-exec env cleanly. */
+const SEMI_SPACE_MB = 128;
+const SEMI_FLAG = `--max-semi-space-size=${SEMI_SPACE_MB}`;
 /** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
 const STACK_KB = 4096;
 const STACK_FLAG = `--stack-size=${STACK_KB}`;
@@ -335,7 +365,8 @@ const forceHeapOOMForTestIfEnabled = () => {
 // the `DEFAULT_WAL_CHECKPOINT_THRESHOLD` constant in
 // `gitnexus/src/core/lbug/lbug-config.ts` in sync with this value.
 const RECOMMENDED_WAL_CHECKPOINT_THRESHOLD = 64 * 1024 * 1024;
-/** Re-exec the process with a 16GB heap and larger stack if we're currently below that. */
+/** Re-exec the process with the RAM-aware auto heap cap + larger semi-space/stack
+ *  if we're currently below that. A user-supplied NODE_OPTIONS heap wins (no re-exec). */
 async function ensureHeap() {
     const nodeOpts = process.env.NODE_OPTIONS || '';
     if (nodeOpts.includes('--max-old-space-size'))
@@ -343,32 +374,32 @@ async function ensureHeap() {
     const v8Heap = v8.getHeapStatistics().heap_size_limit;
     if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
         return false;
-    // --stack-size is a V8 flag not allowed in NODE_OPTIONS on Node 24+,
-    // so pass it only as a direct CLI argument, not via the environment.
-    const cliFlags = [HEAP_FLAG];
+    // --stack-size is a V8 flag not allowed in NODE_OPTIONS on Node 24+, so pass it
+    // only as a direct CLI argument. --max-semi-space-size IS allowed in NODE_OPTIONS.
+    const cliFlags = [HEAP_FLAG, SEMI_FLAG];
     if (!nodeOpts.includes('--stack-size'))
         cliFlags.push(STACK_FLAG);
     const childArgs = [...cliFlags, ...process.argv.slice(1)];
     const childEnv = {
         ...process.env,
-        NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim(),
+        NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG} ${SEMI_FLAG}`.trim(),
     };
     if (shouldBridgeRespawnProgressTty())
         childEnv[RESPAWN_PROGRESS_ENV] = '1';
     const childExit = await runRespawnedAnalyze(childArgs, childEnv);
     if (childExit.status !== 0 || childExit.signal) {
         if (childProcessLikelyOom(childExit)) {
-            cliError(`  Analysis likely ran out of memory.\n` +
-                `  Retry with a larger heap if your machine allows it:\n` +
-                `    NODE_OPTIONS="--max-old-space-size=24576" gitnexus analyze [your-args]\n` +
-                `    (Windows: set NODE_OPTIONS=--max-old-space-size=24576 && gitnexus analyze [your-args])\n` +
+            cliError(`  Analysis likely ran out of memory (heap cap auto-sized to ${RESPAWN_HEAP_MB}MB ≈ 0.75x RAM).\n` +
+                `  This repository's working set exceeds available RAM. Use a machine with more RAM,\n` +
+                `  or override the cap (a cap above physical RAM causes swap-thrash — use with care):\n` +
+                `    NODE_OPTIONS="--max-old-space-size=<MB>" gitnexus analyze [your-args]\n` +
+                `    (Windows: set NODE_OPTIONS=--max-old-space-size=<MB> && gitnexus analyze [your-args])\n` +
                 `  If this persists, it may be a native crash unrelated to heap size.\n`, { recoveryHint: 'heap-oom-respawn' });
         }
         else if (childProcessLikelyNativeAbort(childExit)) {
             cliError(`  Analysis aborted in a native worker or native binding path.\n` +
                 `  Try one of these recovery paths:\n` +
-                `    gitnexus analyze --workers 0\n` +
-                `    npm uninstall -g gitnexus && npm install -g gitnexus@latest\n` +
+                `    npm uninstall -g gitnexus && npm install -g gitnexus@latest (rebuilds native bindings)\n` +
                 `    Use Node 22 LTS if you are on a newer non-LTS runtime.\n`, { recoveryHint: 'native-worker-abort' });
         }
         const status = typeof childExit.status === 'number' && childExit.status !== 0 ? childExit.status : 1;
@@ -389,6 +420,7 @@ const ANALYZE_CLI_ENV_KEYS = [
     'GITNEXUS_VERBOSE',
     'GITNEXUS_PROFILE_DEFERRED',
     'GITNEXUS_PROFILE_DEFERRED_SLOW_MS',
+    'GITNEXUS_DEBUG_HEAP',
     'GITNEXUS_MAX_FILE_SIZE',
     'GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS',
     'GITNEXUS_WAL_CHECKPOINT_THRESHOLD',
@@ -576,9 +608,10 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
     let workerPoolSize;
     if (options.workers !== undefined) {
         const parsedWorkers = Number(options.workers);
-        if (!Number.isInteger(parsedWorkers) || parsedWorkers < 0) {
-            cliError('  --workers must be a non-negative integer. ' +
-                'Pass 0 to disable the worker pool (sequential fallback).\n');
+        if (!Number.isInteger(parsedWorkers) || parsedWorkers < 1) {
+            cliError('  --workers must be a positive integer (>= 1). ' +
+                'GitNexus parses through a worker pool only — there is no sequential ' +
+                'mode, so 0 is not allowed. Omit --workers for an auto-sized pool.\n');
             process.exitCode = 1;
             return;
         }

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

@@ -143,7 +143,7 @@ export declare const en: {
     readonly 'help.option.analyze.maxFileSize': "Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).";
     readonly 'help.option.analyze.workerTimeout': "Worker sub-batch idle timeout before retry/fallback. Default: 30.";
     readonly 'help.option.analyze.walCheckpointThreshold': "LadybugDB WAL auto-checkpoint threshold in bytes during analyze (integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).";
-    readonly 'help.option.analyze.workers': "Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).";
+    readonly 'help.option.analyze.workers': "Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.";
     readonly 'help.option.analyze.embeddingThreads': "Limit local ONNX embedding CPU threads";
     readonly 'help.option.analyze.embeddingBatchSize': "Number of nodes per embedding batch";
     readonly 'help.option.analyze.embeddingSubBatchSize': "Number of chunks per embedding model call";

package/dist/cli/i18n/en.js

@@ -143,7 +143,7 @@ export const en = {
     'help.option.analyze.maxFileSize': 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).',
     'help.option.analyze.workerTimeout': 'Worker sub-batch idle timeout before retry/fallback. Default: 30.',
     'help.option.analyze.walCheckpointThreshold': 'LadybugDB WAL auto-checkpoint threshold in bytes during analyze (integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).',
-    'help.option.analyze.workers': 'Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).',
+    'help.option.analyze.workers': 'Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.',
     'help.option.analyze.embeddingThreads': 'Limit local ONNX embedding CPU threads',
     'help.option.analyze.embeddingBatchSize': 'Number of nodes per embedding batch',
     'help.option.analyze.embeddingSubBatchSize': 'Number of chunks per embedding model call',

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

@@ -144,7 +144,7 @@ export declare const cliResources: {
         readonly 'help.option.analyze.maxFileSize': "Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).";
         readonly 'help.option.analyze.workerTimeout': "Worker sub-batch idle timeout before retry/fallback. Default: 30.";
         readonly 'help.option.analyze.walCheckpointThreshold': "LadybugDB WAL auto-checkpoint threshold in bytes during analyze (integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).";
-        readonly 'help.option.analyze.workers': "Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).";
+        readonly 'help.option.analyze.workers': "Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.";
         readonly 'help.option.analyze.embeddingThreads': "Limit local ONNX embedding CPU threads";
         readonly 'help.option.analyze.embeddingBatchSize': "Number of nodes per embedding batch";
         readonly 'help.option.analyze.embeddingSubBatchSize': "Number of chunks per embedding model call";

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

@@ -143,7 +143,7 @@ export const zhCN = {
     'help.option.analyze.maxFileSize': '跳过大于该值的文件（KB）。默认：512。硬上限：32768（tree-sitter 限制）。',
     'help.option.analyze.workerTimeout': 'Worker 子批次空闲超时，超时后重试/回退。默认：30。',
     'help.option.analyze.walCheckpointThreshold': 'analyze 期间 LadybugDB WAL 自动 checkpoint 阈值（字节，整数 >= -1；默认：67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。',
-    'help.option.analyze.workers': '解析 worker 池大小。默认：cores-1，最多 16。传 0 禁用 worker（顺序执行）。',
+    'help.option.analyze.workers': '解析 worker 池大小（>=1）。默认：cores-1，最多 16，按仓库规模自适应。',
     'help.option.analyze.embeddingThreads': '限制本地 ONNX 嵌入 CPU 线程数',
     'help.option.analyze.embeddingBatchSize': '每个嵌入批次的节点数',
     'help.option.analyze.embeddingSubBatchSize': '每次嵌入模型调用的分块数',

package/dist/cli/index.js

@@ -44,7 +44,7 @@ program
     .option('--worker-timeout <seconds>', 'Worker sub-batch idle timeout before retry/fallback. Default: 30.')
     .option('--wal-checkpoint-threshold <bytes>', 'LadybugDB WAL auto-checkpoint threshold in bytes during analyze ' +
     '(integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).')
-    .option('--workers <n>', 'Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).')
+    .option('--workers <n>', 'Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.')
     .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
     .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
     .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')

package/dist/core/ingestion/call-processor.d.ts

@@ -22,6 +22,11 @@ import type { ExtractedRoute, ExtractedFetchCall } from './workers/parse-worker.
 /** Per-file resolved type bindings for exported symbols.
  *  Consumed by the cross-file re-resolution / enrichment pass. */
 export type ExportedTypeMap = Map<string, Map<string, string>>;
+/** Record one exported graph node into the incremental ExportedTypeMap. */
+export declare const accumulateExportedTypesFromParsedNode: (result: ExportedTypeMap, node: {
+    id: string;
+    properties?: Record<string, unknown>;
+}, symbolTable: SymbolTableReader) => void;
 /** Build ExportedTypeMap from graph nodes — used for the worker path where the
  *  sequential TypeEnv is not available in the main thread. Collects
  *  returnType/declaredType from exported symbols with known types. */

package/dist/core/ingestion/call-processor.js

@@ -27,41 +27,42 @@ import { normalizeFetchURL, routeMatches } from './route-extractors/nextjs.js';
 import { extractReturnTypeName } from './type-extractors/shared.js';
 const MAX_EXPORTS_PER_FILE = 500;
 const MAX_TYPE_NAME_LENGTH = 256;
+/** Record one exported graph node into the incremental ExportedTypeMap. */
+export const accumulateExportedTypesFromParsedNode = (result, node, symbolTable) => {
+    if (!node.properties?.isExported)
+        return;
+    if (!node.properties?.filePath || !node.properties?.name)
+        return;
+    const filePath = node.properties.filePath;
+    const name = node.properties.name;
+    if (!name || name.length > MAX_TYPE_NAME_LENGTH)
+        return;
+    const defs = symbolTable.lookupExactAll(filePath, name);
+    const def = defs.find((d) => d.nodeId === node.id) ?? defs[0];
+    if (!def)
+        return;
+    const typeName = def.returnType ?? def.declaredType;
+    if (!typeName || typeName.length > MAX_TYPE_NAME_LENGTH)
+        return;
+    const simpleType = extractReturnTypeName(typeName) ?? typeName;
+    if (!simpleType)
+        return;
+    let fileExports = result.get(filePath);
+    if (!fileExports) {
+        fileExports = new Map();
+        result.set(filePath, fileExports);
+    }
+    if (fileExports.size < MAX_EXPORTS_PER_FILE) {
+        fileExports.set(name, simpleType);
+    }
+};
 /** Build ExportedTypeMap from graph nodes — used for the worker path where the
  *  sequential TypeEnv is not available in the main thread. Collects
  *  returnType/declaredType from exported symbols with known types. */
 export function buildExportedTypeMapFromGraph(graph, symbolTable) {
     const result = new Map();
     graph.forEachNode((node) => {
-        if (!node.properties?.isExported)
-            return;
-        if (!node.properties?.filePath || !node.properties?.name)
-            return;
-        const filePath = node.properties.filePath;
-        const name = node.properties.name;
-        if (!name || name.length > MAX_TYPE_NAME_LENGTH)
-            return;
-        // For callable symbols, use returnType; for properties/variables, use declaredType.
-        // Use lookupExactAll + nodeId match to handle same-name methods in different classes.
-        const defs = symbolTable.lookupExactAll(filePath, name);
-        const def = defs.find((d) => d.nodeId === node.id) ?? defs[0];
-        if (!def)
-            return;
-        const typeName = def.returnType ?? def.declaredType;
-        if (!typeName || typeName.length > MAX_TYPE_NAME_LENGTH)
-            return;
-        // Extract simple type name (strip Promise<>, etc.) — reuse shared utility
-        const simpleType = extractReturnTypeName(typeName) ?? typeName;
-        if (!simpleType)
-            return;
-        let fileExports = result.get(filePath);
-        if (!fileExports) {
-            fileExports = new Map();
-            result.set(filePath, fileExports);
-        }
-        if (fileExports.size < MAX_EXPORTS_PER_FILE) {
-            fileExports.set(name, simpleType);
-        }
+        accumulateExportedTypesFromParsedNode(result, node, symbolTable);
     });
     return result;
 }

package/dist/core/ingestion/finalize-orchestrator.js

@@ -32,6 +32,8 @@
  * safely consult `model.scopes` without branching on presence.
  */
 import { buildDefIndex, buildMethodDispatchIndex, buildModuleScopeIndex, buildQualifiedNameIndex, buildScopeTree, finalize, } from '../../_shared/index.js';
+import { parseTruthyEnv } from './utils/env.js';
+import { TransitionalScopeTree } from '../../storage/scope-index-store.js';
 /**
  * Produce a fully materialized `ScopeResolutionIndexes` from the
  * workspace's per-file artifacts.
@@ -66,7 +68,13 @@ export function finalizeScopeModel(parsedFiles, options = {}) {
             allDefs.push(d);
         moduleEntries.push({ filePath: file.filePath, moduleScopeId: file.moduleScope });
     }
-    const scopeTree = buildScopeTree(allScopes);
+    // Out-of-core scope index: when enabled, build a TransitionalScopeTree
+    // (validated + fully resident now; sealed to disk by run.ts just before emit so
+    // the heavy Scope.bindings payload is reclaimed). Default off → the in-heap
+    // buildScopeTree result exactly, byte-identical.
+    const scopeTree = parseTruthyEnv(process.env.GITNEXUS_DISK_SCOPE_INDEX)
+        ? new TransitionalScopeTree(allScopes)
+        : buildScopeTree(allScopes);
     const defs = buildDefIndex(allDefs);
     const qualifiedNames = buildQualifiedNameIndex(allDefs);
     const moduleScopes = buildModuleScopeIndex(moduleEntries);

package/dist/core/ingestion/language-provider.d.ts

@@ -241,6 +241,26 @@ interface LanguageProviderConfig {
     sourceMeta?: {
         readonly sourceKind?: 'full-file' | 'pre-extracted-script';
     }) => readonly CaptureMatch[];
+    /**
+     * Snapshot the capture-time side-channel state that this provider's
+     * `emitScopeCaptures` just populated for `filePath` into module-level maps,
+     * returning a plain JSON-serializable value (or `undefined` when there is
+     * nothing to carry).
+     *
+     * Called in the parse worker IMMEDIATELY after `emitScopeCaptures` runs for
+     * a file (see `parse-worker.ts`), and the result is stored on the produced
+     * `ParsedFile.captureSideChannel`. Scope-resolution on the main thread reuses
+     * that serialized `ParsedFile` and skips re-extraction (#1983), so this hook
+     * is how the worker-computed marks survive the worker→main boundary and the
+     * disk store WITHOUT a main-thread re-parse. The main thread restores them
+     * via the matching `ScopeResolver.applyCaptureSideChannel` hook.
+     *
+     * MUST return plain data (objects / arrays / primitives) so it round-trips
+     * through `JSON.stringify` + the parsedfile-store interning reviver.
+     *
+     * Default: undefined (provider has no capture-time module-level side effects).
+     */
+    readonly collectCaptureSideChannel?: (filePath: string) => unknown;
     /**
      * Interpret a raw `@import.statement` capture group into a `ParsedImport`.
      * The central finalize algorithm resolves `ParsedImport.targetRaw` to a

package/dist/core/ingestion/languages/c/capture-side-channel.d.ts

@@ -0,0 +1,62 @@
+/**
+ * C capture-time side-channel serialization (#1983).
+ *
+ * `emitCScopeCaptures` populates one MODULE-LEVEL, per-file map as a side
+ * effect that is NOT part of the returned `ParsedFile`'s scopes/defs:
+ *
+ *   - `staticNames`  (static-linkage.ts) — the simple names of functions
+ *     declared with `static` storage class (file-local / translation-unit
+ *     linkage in C), recorded via `markStaticName` from the
+ *     `@declaration.name` capture when the function node has a `static`
+ *     storage-class specifier.
+ *
+ * On the worker path that map is filled in the WORKER process and lost across
+ * the worker→main MessageChannel (and the disk-backed parsedfile-store),
+ * because scope-resolution reuses the serialized `ParsedFile` and SKIPS the
+ * main-thread re-extraction (the #1983 fix that avoids a main-thread
+ * tree-sitter re-parse / OOM on huge repos — e.g. the Linux kernel). The main
+ * thread then reads the map empty in `isStaticName` (consulted by
+ * `isFileLocalDef` in `c/scope-resolver.ts` and by `expandCWildcardNames` in
+ * static-linkage.ts) — so file-local `static` functions become eligible for
+ * cross-file global free-call resolution (false CALLS edges) and `#include`
+ * wildcard imports over-expose them.
+ *
+ * This module snapshots the per-file slice of that map into a plain,
+ * JSON-serializable object (carried on `ParsedFile.captureSideChannel`) and
+ * restores it on the main thread WITHOUT any parse. It mirrors the C++ pattern
+ * in `cpp/capture-side-channel.ts` and the Kotlin pattern in
+ * `kotlin/capture-side-channel.ts`.
+ *
+ * The single generic `ParsedFile.captureSideChannel` field is shared with C++
+ * and Kotlin, which is safe because each file is one language (a `.c` file uses
+ * the C provider). The payload is self-describing (`{ kind: 'c', staticNames }`)
+ * so `applyCStaticLinkageSideChannel` only restores C state and ignores a
+ * foreign-shaped snapshot.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+/**
+ * Plain JSON-serializable snapshot of the per-file C capture-time
+ * side-channel. Carried opaquely on `ParsedFile.captureSideChannel`. The
+ * `kind` tag makes the payload self-describing so `apply` can distinguish a C
+ * snapshot from another language's (C++ and Kotlin share the same field).
+ */
+export interface CCaptureSideChannel {
+    readonly kind: 'c';
+    /** Simple names of `static` (file-local linkage) functions in this file. */
+    readonly staticNames: readonly string[];
+}
+/**
+ * `LanguageProvider.collectCaptureSideChannel` implementation for C.
+ * Returns `undefined` when this file recorded no static names at all, so the
+ * produced `ParsedFile` carries the field only when there's data to ship.
+ */
+export declare function collectCStaticLinkageSideChannel(filePath: string): CCaptureSideChannel | undefined;
+/**
+ * `ScopeResolver.applyCaptureSideChannel` implementation for C. Reads the
+ * worker-serialized snapshot from `parsed.captureSideChannel` and re-populates
+ * the module-level static-linkage map via `markStaticName`. Tolerant of
+ * `undefined` (file carried no data) and of an unexpected / foreign shape
+ * (defensive — the `kind` tag guards against restoring a non-C payload).
+ * Does NO tree-sitter parse.
+ */
+export declare function applyCStaticLinkageSideChannel(parsed: ParsedFile): void;

package/dist/core/ingestion/languages/c/capture-side-channel.js

@@ -0,0 +1,65 @@
+/**
+ * C capture-time side-channel serialization (#1983).
+ *
+ * `emitCScopeCaptures` populates one MODULE-LEVEL, per-file map as a side
+ * effect that is NOT part of the returned `ParsedFile`'s scopes/defs:
+ *
+ *   - `staticNames`  (static-linkage.ts) — the simple names of functions
+ *     declared with `static` storage class (file-local / translation-unit
+ *     linkage in C), recorded via `markStaticName` from the
+ *     `@declaration.name` capture when the function node has a `static`
+ *     storage-class specifier.
+ *
+ * On the worker path that map is filled in the WORKER process and lost across
+ * the worker→main MessageChannel (and the disk-backed parsedfile-store),
+ * because scope-resolution reuses the serialized `ParsedFile` and SKIPS the
+ * main-thread re-extraction (the #1983 fix that avoids a main-thread
+ * tree-sitter re-parse / OOM on huge repos — e.g. the Linux kernel). The main
+ * thread then reads the map empty in `isStaticName` (consulted by
+ * `isFileLocalDef` in `c/scope-resolver.ts` and by `expandCWildcardNames` in
+ * static-linkage.ts) — so file-local `static` functions become eligible for
+ * cross-file global free-call resolution (false CALLS edges) and `#include`
+ * wildcard imports over-expose them.
+ *
+ * This module snapshots the per-file slice of that map into a plain,
+ * JSON-serializable object (carried on `ParsedFile.captureSideChannel`) and
+ * restores it on the main thread WITHOUT any parse. It mirrors the C++ pattern
+ * in `cpp/capture-side-channel.ts` and the Kotlin pattern in
+ * `kotlin/capture-side-channel.ts`.
+ *
+ * The single generic `ParsedFile.captureSideChannel` field is shared with C++
+ * and Kotlin, which is safe because each file is one language (a `.c` file uses
+ * the C provider). The payload is self-describing (`{ kind: 'c', staticNames }`)
+ * so `applyCStaticLinkageSideChannel` only restores C state and ignores a
+ * foreign-shaped snapshot.
+ */
+import { getStaticNamesForFile, markStaticName } from './static-linkage.js';
+/**
+ * `LanguageProvider.collectCaptureSideChannel` implementation for C.
+ * Returns `undefined` when this file recorded no static names at all, so the
+ * produced `ParsedFile` carries the field only when there's data to ship.
+ */
+export function collectCStaticLinkageSideChannel(filePath) {
+    const staticNames = getStaticNamesForFile(filePath);
+    if (staticNames.length === 0)
+        return undefined;
+    return { kind: 'c', staticNames };
+}
+/**
+ * `ScopeResolver.applyCaptureSideChannel` implementation for C. Reads the
+ * worker-serialized snapshot from `parsed.captureSideChannel` and re-populates
+ * the module-level static-linkage map via `markStaticName`. Tolerant of
+ * `undefined` (file carried no data) and of an unexpected / foreign shape
+ * (defensive — the `kind` tag guards against restoring a non-C payload).
+ * Does NO tree-sitter parse.
+ */
+export function applyCStaticLinkageSideChannel(parsed) {
+    const data = parsed.captureSideChannel;
+    if (data === undefined || data === null || typeof data !== 'object')
+        return;
+    if (data.kind !== 'c' || !Array.isArray(data.staticNames))
+        return;
+    for (const name of data.staticNames) {
+        markStaticName(parsed.filePath, name);
+    }
+}

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

@@ -1,4 +1,39 @@
 import { dirname, join } from 'path';
+/**
+ * Per-pass memo: workspace paths bucketed by basename (last path segment),
+ * keyed on the `allFilePaths` set identity.
+ *
+ * `resolveCImportTarget` is called once per (quoted) C/C++ `#include` with the
+ * same `allFilePaths` set per pass (the augmented set is itself memoized in
+ * the C resolver). The old suffix-match fallback scanned ALL workspace paths
+ * per include — with a per-element `.replace`/`.split` and no early exit
+ * (the fewest-path-components tie-break forces a full scan) — i.e.
+ * O(R_suffix × (F+H)). A path can satisfy `endsWith('/'+target)` (or equal
+ * the target) ONLY IF its basename equals the target's last segment, so we
+ * pre-bucket by basename once (O(F+H), `normalized`/`depth` precomputed) and
+ * the fallback inspects a single small bucket → O(F+H) build + ~O(1)/include.
+ * `WeakMap`-keyed so it is reclaimed with the pass (no cross-pass staleness).
+ * Shared by C and C++ (`resolveCppImportTarget` delegates here).
+ */
+const suffixIndexByPaths = new WeakMap();
+function suffixIndex(allFilePaths) {
+    let index = suffixIndexByPaths.get(allFilePaths);
+    if (index === undefined) {
+        index = new Map();
+        for (const original of allFilePaths) {
+            const normalized = original.replace(/\\/g, '/');
+            const basename = normalized.slice(normalized.lastIndexOf('/') + 1);
+            let bucket = index.get(basename);
+            if (bucket === undefined) {
+                bucket = [];
+                index.set(basename, bucket);
+            }
+            bucket.push({ original, normalized, depth: normalized.split('/').length });
+        }
+        suffixIndexByPaths.set(allFilePaths, index);
+    }
+    return index;
+}
 /**
  * Resolve a C #include path to a file in the workspace.
  *
@@ -36,20 +71,28 @@ export function resolveCImportTarget(targetRaw, fromFile, allFilePaths) {
     // Exact match (path as-is in the workspace)
     if (allFilePaths.has(normalizedTarget))
         return normalizedTarget;
-    // Suffix match: find files ending with /targetRaw or equal to targetRaw
+    // Suffix match: find files ending with /targetRaw or equal to targetRaw.
+    // A path can only match `=== normalizedTarget` or `endsWith('/'+target)` if
+    // its basename equals the target's last segment, so we inspect only that
+    // basename bucket (built once per pass) instead of scanning every workspace
+    // path. Match condition + tie-break (fewest path components, then
+    // lexicographic on the normalized path) are byte-identical to the prior scan.
     const suffix = '/' + normalizedTarget;
+    const targetBasename = normalizedTarget.slice(normalizedTarget.lastIndexOf('/') + 1);
+    const bucket = suffixIndex(allFilePaths).get(targetBasename);
+    if (bucket === undefined)
+        return null;
     let bestMatch = null;
     let bestDepth = Infinity;
     let bestNormalized = '';
-    for (const filePath of allFilePaths) {
-        const normalized = filePath.replace(/\\/g, '/');
-        if (normalized === normalizedTarget || normalized.endsWith(suffix)) {
+    for (const cand of bucket) {
+        if (cand.normalized === normalizedTarget || cand.normalized.endsWith(suffix)) {
             // Prefer shortest path (closest match)
-            const depth = normalized.split('/').length;
-            if (depth < bestDepth || (depth === bestDepth && normalized < bestNormalized)) {
-                bestDepth = depth;
-                bestMatch = filePath;
-                bestNormalized = normalized;
+            if (cand.depth < bestDepth ||
+                (cand.depth === bestDepth && cand.normalized < bestNormalized)) {
+                bestDepth = cand.depth;
+                bestMatch = cand.original;
+                bestNormalized = cand.normalized;
             }
         }
     }

package/dist/core/ingestion/languages/c/index.d.ts

@@ -8,4 +8,5 @@ export { cArityCompatibility } from './arity.js';
 export { cMergeBindings } from './merge-bindings.js';
 export { cBindingScopeFor, cImportOwningScope, cReceiverBinding } from './simple-hooks.js';
 export { resolveCImportTarget } from './import-target.js';
-export { markStaticName, isStaticName, clearStaticNames, expandCWildcardNames, } from './static-linkage.js';
+export { markStaticName, isStaticName, clearStaticNames, expandCWildcardNames, getStaticNamesForFile, } from './static-linkage.js';
+export { collectCStaticLinkageSideChannel, applyCStaticLinkageSideChannel, } from './capture-side-channel.js';

package/dist/core/ingestion/languages/c/index.js

@@ -8,4 +8,5 @@ export { cArityCompatibility } from './arity.js';
 export { cMergeBindings } from './merge-bindings.js';
 export { cBindingScopeFor, cImportOwningScope, cReceiverBinding } from './simple-hooks.js';
 export { resolveCImportTarget } from './import-target.js';
-export { markStaticName, isStaticName, clearStaticNames, expandCWildcardNames, } from './static-linkage.js';
+export { markStaticName, isStaticName, clearStaticNames, expandCWildcardNames, getStaticNamesForFile, } from './static-linkage.js';
+export { collectCStaticLinkageSideChannel, applyCStaticLinkageSideChannel, } from './capture-side-channel.js';