gitnexus 1.6.12-rc.4 → 1.6.12-rc.6

package/dist/core/ingestion/call-extractors/zig-static-gating.d.ts

@@ -11,17 +11,14 @@
  * Conservative by design: we only tag an edge when we can prove the
  * gating expression evaluates to `false`.  Anything ambiguous → live.
  *
- * Scope of v1:
+ * Supported scope:
  *
  *   (a) **File-local** consts (`pub const FOO = false;`, plus const-to-const
  *       aliases up to 5 hops), built once per file by `buildZigBoolConstMap`.
- *   (b) **Cross-file** (`const cfg = @import("./cfg.zig"); if (cfg.FOO)`) is
- *       NOT resolved yet. The evaluator keeps the seam for it (`importAliases`
- *       + `lookupBoolsForPath`, consumed by the `field_expression` case), but
- *       the only caller passes an empty alias map and a lookup that always
- *       returns `undefined`, because the capture emitter runs in the parse
- *       worker and sees only the current file. Tracked in #3162. Until then
- *       every `cfg.FOO` condition folds to unknown, i.e. live.
+ *   (b) **Cross-file** direct imports (`const cfg = @import("./cfg.zig");
+ *       if (cfg.FOO)`) are enriched after per-file extraction. The workspace
+ *       caller supplies `importAliases` and `lookupBoolsForPath`; the parse
+ *       worker still uses empty/undefined inputs and remains file-local.
  *
  * Also out of scope: multi-hop member access (`cfg.sub.FOO`), re-exported
  * consts, runtime-evaluated bools (`const FOO = computeIt();`), and

package/dist/core/ingestion/languages/zig/scope-resolver.js

@@ -16,6 +16,7 @@ import { resolveZigImportInternal } from '../../import-resolvers/zig.js';
 import { zigProvider } from '../zig.js';
 import { expandZigWildcardNames, zigArityCompatibility, zigMergeBindings } from './index.js';
 import { populateZigRangeBindings } from './range-binding.js';
+import { populateZigWorkspaceStaticGating } from './workspace-static-gating.js';
 export const zigScopeResolver = {
     language: SupportedLanguages.Zig,
     languageProvider: zigProvider,
@@ -48,6 +49,7 @@ export const zigScopeResolver = {
     arityCompatibility: zigArityCompatibility,
     buildMro: (graph, parsedFiles, nodeLookup) => buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
     populateOwners: (parsed) => populateClassOwnedMembers(parsed),
+    populateWorkspaceReferences: populateZigWorkspaceStaticGating,
     // Payload captures — `for (items) |it|`, `if (opt) |v|`, `while (it.next())
     // |x|` — typed from the subject's binding after finalize (F6).
     populateRangeBindings: populateZigRangeBindings,

package/dist/core/ingestion/languages/zig/workspace-static-gating.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedFile } from '../../../../_shared/index.js';
+export declare function populateZigWorkspaceStaticGating(parsedFiles: ParsedFile[], ctx: {
+    readonly fileContents: ReadonlyMap<string, string>;
+    readonly treeCache?: {
+        get(filePath: string): unknown;
+    };
+    readonly resolutionConfig?: unknown;
+}): void;

package/dist/core/ingestion/languages/zig/workspace-static-gating.js

@@ -0,0 +1,76 @@
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { resolveZigImportInternal } from '../../import-resolvers/zig.js';
+import { buildZigBoolConstMap, collectZigStaticGatedRanges, isPositionStaticGated, } from '../../call-extractors/zig-static-gating.js';
+import { parseSourceSafe, ParseTimeoutError } from '../../../tree-sitter/safe-parse.js';
+import { getZigParser } from './query.js';
+export function populateZigWorkspaceStaticGating(parsedFiles, ctx) {
+    const parser = getZigParser();
+    const trees = new Map();
+    const bools = new Map();
+    for (const parsed of parsedFiles) {
+        const source = ctx.fileContents.get(parsed.filePath);
+        if (source === undefined)
+            continue;
+        let tree = ctx.treeCache?.get(parsed.filePath);
+        if (tree === undefined) {
+            try {
+                tree = parseSourceSafe(parser, source, undefined, {
+                    bufferSize: getTreeSitterBufferSize(source),
+                });
+            }
+            catch (err) {
+                if (err instanceof ParseTimeoutError)
+                    continue;
+                throw err;
+            }
+        }
+        trees.set(parsed.filePath, tree);
+        bools.set(parsed.filePath, buildZigBoolConstMap(tree.rootNode));
+    }
+    const knownPaths = new Set(trees.keys());
+    for (const [index, parsed] of parsedFiles.entries()) {
+        const tree = trees.get(parsed.filePath);
+        if (tree === undefined)
+            continue;
+        const aliases = collectImportAliases(tree, parsed.filePath, knownPaths, ctx.resolutionConfig);
+        if (aliases.size === 0)
+            continue;
+        const ranges = collectZigStaticGatedRanges(tree.rootNode, bools.get(parsed.filePath) ?? new Map(), aliases, (filePath) => bools.get(filePath));
+        if (ranges.length === 0)
+            continue;
+        const next = parsed.referenceSites.map((site) => site.kind === 'call' &&
+            site.staticGated !== true &&
+            isPositionStaticGated(site.atRange.startLine, site.atRange.startCol, ranges)
+            ? { ...site, staticGated: true }
+            : site);
+        parsedFiles[index] = Object.freeze({ ...parsed, referenceSites: Object.freeze(next) });
+    }
+}
+function collectImportAliases(tree, fromFile, knownPaths, resolutionConfig) {
+    const candidates = new Map();
+    const declarationCounts = new Map();
+    for (const decl of tree.rootNode.descendantsOfType('variable_declaration')) {
+        const names = decl.namedChildren.filter((node) => node.type === 'identifier');
+        const binding = names[0]?.text;
+        if (binding === undefined)
+            continue;
+        declarationCounts.set(binding, (declarationCounts.get(binding) ?? 0) + 1);
+        const builtin = decl.namedChildren.find((node) => node.type === 'builtin_function' && node.text.startsWith('@import('));
+        const raw = builtin?.descendantsOfType('string').at(0)?.text;
+        if (raw === undefined)
+            continue;
+        const specifier = raw.replace(/^['"]|['"]$/g, '');
+        const target = resolveZigImportInternal(fromFile, specifier, knownPaths, resolutionConfig);
+        if (target !== null)
+            candidates.set(binding, target);
+    }
+    const aliases = new Map();
+    for (const [binding, target] of candidates) {
+        // Alias lookup below is name-based rather than position-aware. If a name
+        // is redeclared in another lexical scope, fail open instead of applying
+        // either module's constants to every use of that spelling.
+        if (declarationCounts.get(binding) === 1)
+            aliases.set(binding, target);
+    }
+    return aliases;
+}

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

@@ -3,6 +3,7 @@ import type { SymbolTableWriter } from './model/index.js';
 import { type ExportedTypeMap } from './call-processor.js';
 import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
+import type { DispatchGroup } from './workers/worker-pool.js';
 import type { ParseWorkerResult, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedModuleConstants, ExtractedToolDef, FileScopeBindings, ExtractedORMQuery, FetchWrapperDef } from './workers/parse-worker.js';
 import type { ExtractedRouterConstructorPrefix, ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './route-extractors/fastapi-router-bindings.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
@@ -78,13 +79,10 @@ chunkHash?: string) => Promise<ParseWorkerResult[]>;
  * boundaries, so every result stays attributable to the chunk whose cache key
  * owns it.
  */
-export declare const dispatchChunkParseRound: (groups: ReadonlyArray<{
-    items: {
-        path: string;
-        content: string;
-    }[];
-    chunkHash?: string;
-}>, workerPool: WorkerPool, onFileProgress?: FileProgressCallback) => Promise<ParseWorkerResult[][]>;
+export declare const dispatchChunkParseRound: (groups: ReadonlyArray<DispatchGroup<{
+    path: string;
+    content: string;
+}>>, workerPool: WorkerPool, onFileProgress?: FileProgressCallback) => Promise<ParseWorkerResult[][]>;
 export declare const processParsing: (graph: KnowledgeGraph, files: {
     path: string;
     content: string;

package/dist/core/ingestion/pipeline-phases/parse-impl.js

@@ -28,7 +28,7 @@ import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 import { getProvider, getProviderForFile, providers } from '../languages/index.js';
 import { SCOPE_RESOLVERS } from '../scope-resolution/pipeline/registry.js';
 import { DATA_ROUTE_TABLE_SOURCE } from '../route-extractors/data-route-table.js';
-import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
+import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, envWorkerPoolSize, resolveHostParallelism, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
 import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
 import { resolveOperands } from '../route-extractors/python-const-resolver.js';
 import { prepareRouteConstantsByProvider } from '../language-provider.js';
@@ -43,6 +43,8 @@ import { isVerboseIngestionEnabled } from '../utils/verbose.js';
 import { endTimer, isDeferredResolutionProfileEnabled, logDeferredProfile, startTimer, } from '../utils/deferred-resolution-profile.js';
 import { isDebugHeapEnabled, logHeapProbe } from '../utils/heap-probe.js';
 import { logger } from '../../logger.js';
+import { mapConcurrent } from '../../../lib/utils.js';
+import { createRoundBudget } from './parse-round-budget.js';
 // ── Constants ──────────────────────────────────────────────────────────────
 /**
  * Heap-scale guardrail constants (#2649). Measured on a Linux-kernel analyze:
@@ -130,10 +132,16 @@ const CHUNK_BYTES_PER_WORKER = DEFAULT_CHUNK_BYTE_BUDGET;
  * while the rest finish early). Drives the derived `subBatchMaxBytes`.
  */
 const TARGET_JOBS_PER_WORKER = 3;
+/**
+ * Concurrent durable ParsedFile directory resets per round. Matches the file
+ * reader's `READ_CONCURRENCY`, because both compete for the same descriptors.
+ */
+const DURABLE_RESET_CONCURRENCY = 32;
 /** Floor for a derived sub-batch so jobs don't shrink to per-file IPC churn. */
 const MIN_SUB_BATCH_BYTES = 256 * 1024;
 /**
- * Source bytes of cache-missing chunks allowed in flight in one pool round.
+ * Source bytes an open round may HOLD — cache hits and misses alike — before
+ * it is dispatched and drained.
  *
  * A `dispatch` is a barrier, so one round-trip per cache pack leaves most slots
  * idle: packs are keyed by `(language, hash(path) % 128)` and routinely land far
@@ -413,11 +421,38 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     // cores-based auto size is capped by source bytes / CHUNK_BYTES_PER_WORKER
     // so a tiny repo does not spawn a full idle pool. Cache pack membership
     // is independent of this number (#3088).
-    const explicitPoolSize = options?.workerPoolSize;
+    // `--workers <N>` and `GITNEXUS_WORKER_POOL_SIZE` are both deliberate
+    // operator input, so both bypass the work-proportional cap below. Only the
+    // env path used to be clamped by it, which made the documented escape hatch
+    // silently do nothing: on a 30MB repo the cap resolves to 16, so an operator
+    // asking for 24 still got 16 with no warning, while `--workers 24` got 24.
+    const explicitPoolSize = options?.workerPoolSize ?? envWorkerPoolSize();
+    // Cores-based auto size, bounded by source bytes so a tiny repo does not
+    // spawn a full idle pool.
     const workProportionalCap = Math.max(1, Math.ceil(totalBytes / CHUNK_BYTES_PER_WORKER));
+    // An operator's number is honored, but never exceeds the number of files
+    // there are to parse — `GITNEXUS_WORKER_POOL_SIZE=100000` on a five-file repo
+    // should not become the literal thread count. This bounds `--workers` and the
+    // env var identically, keeping the parity above intact. Note it does NOT
+    // shrink an incremental re-analyze: `totalParseable` counts every parseable
+    // file in the scan, not the changed ones, so a warm run of a large repo still
+    // spawns the full requested pool.
     const effectivePoolSize = explicitPoolSize && explicitPoolSize > 0
-        ? explicitPoolSize
+        ? Math.min(explicitPoolSize, Math.max(1, totalParseable))
         : Math.min(resolveAutoPoolSize(), workProportionalCap);
+    // Deliberate over-subscription is the operator's call, so this warns rather
+    // than caps — silently capping is what the override exists to stop. But an
+    // exported `GITNEXUS_WORKER_POOL_SIZE` applies to EVERY analyze in a
+    // long-lived caller (watch auto-sync, the MCP server), including small
+    // incremental ones, and that is easy to set once and forget.
+    if (explicitPoolSize && explicitPoolSize > 0) {
+        const hostParallelism = resolveHostParallelism();
+        if (effectivePoolSize > hostParallelism) {
+            logger.warn({ requested: explicitPoolSize, spawning: effectivePoolSize, hostParallelism }, `Worker pool size ${effectivePoolSize} exceeds this host's ${hostParallelism} usable core(s); ` +
+                `parsing is CPU-bound, so the extra workers add memory pressure without throughput. ` +
+                `This applies to every analyze while the override is set.`);
+        }
+    }
     // Cache packs: stable (language, hash(path) mod 128) buckets, then the
     // per-call byte budget inside each bucket (#3088). Pool size is used only
     // for worker count and sub-batch fan-out, not membership.
@@ -618,20 +653,30 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         // the env can't change mid-run.
         const verboseThroughputLog = isDev || isVerboseIngestionEnabled();
         const heapProbeEveryN = isDebugHeapEnabled() ? 25 : 0;
+        /**
+         * Chunk hashes whose durable ParsedFile directory could not be reset. The
+         * old generation's shards are still on disk, so a warm hit would union
+         * stale shards with the new ones. Treated exactly like a quarantined chunk:
+         * skip the parse-cache write so the next run re-dispatches into a clean
+         * directory rather than trusting a generation we could not clear.
+         */
+        const durablePrepareFailures = new Set();
         const roundByteBudget = resolveParseRoundByteBudget(options);
         let roundEntries = [];
-        let roundMissBytes = 0;
         /**
          * Bytes an open round is HOLDING, counting hits as well as misses.
          *
-         * `roundMissBytes` alone bounds only what the workers are asked to do, so a
-         * warm run — where nothing misses — would never reach the close condition
-         * and would buffer every chunk's cached output until the tail drain. That
-         * is the #2649 heap failure on a large repo. Closing on either cap keeps a
-         * hits-only run draining at the same cadence as a cold one; `startRound`
-         * already supports a round with no misses.
+         * Counting only the cache-MISSING bytes would bound just what the workers
+         * are asked to do, so a warm run — where nothing misses — would never reach
+         * the close condition and would buffer every chunk's cached output until
+         * the tail drain. That is the #2649 heap failure on a large repo. Counting
+         * both keeps a hits-only run draining at the same cadence as a cold one;
+         * `startRound` already supports a round with no misses.
+         *
+         * Measured in UTF-8 bytes, matching `estimateItemBytes` in the worker pool,
+         * so the cap means the same thing here as it does for a job's payload.
          */
-        let roundBufferedBytes = 0;
+        const roundBudget = createRoundBudget(roundByteBudget);
         /**
          * Files QUEUED into rounds so far. `filesParsedSoFar` only advances when a
          * round drains, so it is the right number for the throughput log but would
@@ -755,7 +800,12 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             if (parseCache && p.chunkHash && rawResults.length > 0) {
                 const quarantineSet = new Set(workerPool?.getQuarantinedPaths?.() ?? []);
                 const chunkHadQuarantine = p.chunkFiles.some((f) => quarantineSet.has(f.path));
-                if (chunkHadQuarantine) {
+                const durableGenerationStale = durablePrepareFailures.has(p.chunkHash);
+                if (durableGenerationStale) {
+                    logger.warn({ chunkHash: p.chunkHash.slice(0, 8) }, 'parse-cache SKIP: durable generation for this chunk could not be reset, ' +
+                        'so its shards may be stale; next run will re-dispatch it');
+                }
+                else if (chunkHadQuarantine) {
                     if (isDev) {
                         const quarantinedInChunk = p.chunkFiles.filter((f) => quarantineSet.has(f.path)).length;
                         logger.info(`📦 parse-cache SKIP: chunk ${p.chunkIdx + 1}/${numChunks} ` +
@@ -785,19 +835,34 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             if (misses.length === 0) {
                 return { entries, results: Promise.resolve([]) };
             }
-            for (const miss of misses) {
-                if (durableParsedFileDir !== undefined && miss.chunkHash !== null) {
-                    try {
-                        await prepareDurableParsedFileChunk(durableParsedFileDir, miss.chunkHash);
-                    }
-                    catch (err) {
-                        // The durable store is an optimization — degrade like the restore
-                        // path does instead of failing the analyze. Workers recreate the
-                        // directory on write, so at worst the old generation lingers.
-                        logger.warn({ err, chunkHash: miss.chunkHash.slice(0, 8) }, 'parsedfile-cache: could not reset durable chunk generation; continuing');
-                    }
+            // Each chunk resets its own directory, so these are independent and run
+            // concurrently: serially they would sit on the critical path this round
+            // exists to shorten, with the pool idle and the previous round's merge
+            // waiting, once per miss.
+            //
+            // BOUNDED, though. A round can hold hundreds of small packs, and each
+            // reset is a recursive rm + mkdir. Firing all of them at once competes
+            // for descriptors with the chunk prefetch this loop already has in
+            // flight, and `readFileContents` degrades a losing read SILENTLY by
+            // contract — a dropped file would vanish from the chunk, from the graph,
+            // and from the chunk hash, shipping a narrowed index with exit 0. Same
+            // helper and width the file reads use.
+            await mapConcurrent(misses, async (miss) => {
+                if (durableParsedFileDir === undefined || miss.chunkHash === null)
+                    return;
+                try {
+                    await prepareDurableParsedFileChunk(durableParsedFileDir, miss.chunkHash);
                 }
-            }
+                catch (err) {
+                    // The durable store is an optimization — degrade like the restore
+                    // path does instead of failing the analyze. Workers recreate the
+                    // directory on write, so at worst the old generation lingers.
+                    // Caught per chunk so one failure cannot abort the others.
+                    durablePrepareFailures.add(miss.chunkHash);
+                    logger.warn({ err, chunkHash: miss.chunkHash.slice(0, 8) }, 'parsedfile-cache: could not reset durable chunk generation; ' +
+                        'continuing without caching this chunk');
+                }
+            }, { concurrency: DURABLE_RESET_CONCURRENCY });
             const roundFiles = misses.reduce((sum, miss) => sum + miss.chunkFiles.length, 0);
             const firstIdx = misses[0].chunkIdx;
             const lastIdx = misses[misses.length - 1].chunkIdx;
@@ -844,7 +909,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
          */
         const drainRound = async (round) => {
             const missResults = round.missResults;
-            const missCount = round.entries.reduce((sum, entry) => sum + (entry.kind === 'miss' ? 1 : 0), 0);
+            const missCount = round.entries.filter((entry) => entry.kind === 'miss').length;
             // `dispatchGroups` returns one array per input group. If that contract
             // ever breaks, every later entry in this round would silently merge the
             // wrong chunk's results and skip its cache write, with a clean exit.
@@ -874,8 +939,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         const closeRound = async () => {
             const started = await startRound(roundEntries);
             roundEntries = [];
-            roundMissBytes = 0;
-            roundBufferedBytes = 0;
+            roundBudget.reset();
             const previous = pendingRound;
             pendingRound = null;
             if (previous) {
@@ -987,6 +1051,8 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 parsedFileStorePath !== undefined &&
                 durableExpectedPaths !== undefined &&
                 (await durableChunkHasShards(parsedFileStorePath, chunkHash, durableExpectedPaths));
+            // Set by whichever branch queues this chunk; drives the close below.
+            let roundIsFull = false;
             if (cachedRaw && cachedRaw.length > 0 && (durableHit || parsedFileStorePath === undefined)) {
                 // Cache hit: replay cached worker output. Finalize any parked worker
                 // chunk FIRST so deferred aggregation stays in chunk order, then merge
@@ -1022,8 +1088,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     chunkStartMs,
                     cachedRaw,
                 });
-                for (const file of chunkFiles)
-                    roundBufferedBytes += file.content.length;
+                roundIsFull = roundBudget.addChunk(chunkFiles.map((file) => file.content));
                 queuedFilesSoFar += chunkFiles.length;
             }
             else {
@@ -1032,18 +1097,14 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 chunkCacheMisses++;
                 reparsedFileCount += chunkFiles.length;
                 roundEntries.push({ kind: 'miss', chunkIdx, chunkHash, chunkFiles, chunkStartMs });
-                for (const file of chunkFiles) {
-                    roundMissBytes += file.content.length;
-                    roundBufferedBytes += file.content.length;
-                }
+                roundIsFull = roundBudget.addChunk(chunkFiles.map((file) => file.content));
                 queuedFilesSoFar += chunkFiles.length;
             }
-            // Close on EITHER cap. `roundMissBytes` sizes the worker round;
-            // `roundBufferedBytes` bounds what the main thread is holding, which is
-            // the only cap a warm run can ever reach.
-            if (roundMissBytes >= roundByteBudget || roundBufferedBytes >= roundByteBudget) {
+            // One cap, on what the main thread is holding. That bounds the worker
+            // round too, since a round's dispatched bytes are a subset of its
+            // buffered bytes.
+            if (roundIsFull)
                 await closeRound();
-            }
             // (Per-chunk aggregation + parse-cache write + throughput log now run in
             // `applyChunkResults` / `finalizeWorkerChunk` — see the merge-pipelining
             // block above. Route/import/inheritance edges are emitted later: route

package/dist/core/ingestion/pipeline-phases/parse-round-budget.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The fold that decides when an open dispatch round closes.
+ *
+ * Extracted so the decision is a shared, inspectable unit rather than four
+ * loose statements inside `runChunkedParseAndResolve`. The parse loop is
+ * STREAMING — it reads chunk contents lazily, so it cannot know every chunk's
+ * size up front and cannot "plan" rounds ahead. That makes an accumulator, not
+ * a planner, the honest shape: feed it each chunk as it is queued and it tells
+ * you whether the round is now full.
+ *
+ * Being a real unit is what makes round cadence observable. Round boundaries
+ * are otherwise invisible from outside the parse phase: they change no graph
+ * output (that is the point of batching) and surface only in a log line, which
+ * is why `bench/parse-dispatch-rounds` measures this directly rather than
+ * inferring cadence from a full analyze.
+ */
+/** Bytes a file contributes to the open round's retained total. */
+export declare const roundFileBytes: (content: string) => number;
+export interface RoundBudget {
+    /**
+     * Add one queued chunk's files. Returns true when the round is now full and
+     * the caller should close it. Closing resets the accumulator.
+     */
+    addChunk(contents: readonly string[]): boolean;
+    /** Bytes currently held by the open round. */
+    readonly bufferedBytes: number;
+    /** Reset without closing — used when the caller closes for another reason. */
+    reset(): void;
+}
+/**
+ * `budgetBytes` bounds what the main thread HOLDS, counting cache hits as well
+ * as misses. Counting only cache-missing bytes would bound just the work sent
+ * to workers, so a warm run — where nothing misses — would never reach the
+ * close condition and would buffer every chunk's cached output until the tail
+ * drain. That is the #2649 heap failure on a large repo.
+ *
+ * Measured in UTF-8 bytes, matching `estimateItemBytes` in the worker pool.
+ * `String.length` would return UTF-16 code units, undercounting non-ASCII
+ * source by up to 3x and letting a CJK-heavy repo hold well past its nominal
+ * budget before draining.
+ */
+export declare const createRoundBudget: (budgetBytes: number) => RoundBudget;

package/dist/core/ingestion/pipeline-phases/parse-round-budget.js

@@ -0,0 +1,50 @@
+/**
+ * The fold that decides when an open dispatch round closes.
+ *
+ * Extracted so the decision is a shared, inspectable unit rather than four
+ * loose statements inside `runChunkedParseAndResolve`. The parse loop is
+ * STREAMING — it reads chunk contents lazily, so it cannot know every chunk's
+ * size up front and cannot "plan" rounds ahead. That makes an accumulator, not
+ * a planner, the honest shape: feed it each chunk as it is queued and it tells
+ * you whether the round is now full.
+ *
+ * Being a real unit is what makes round cadence observable. Round boundaries
+ * are otherwise invisible from outside the parse phase: they change no graph
+ * output (that is the point of batching) and surface only in a log line, which
+ * is why `bench/parse-dispatch-rounds` measures this directly rather than
+ * inferring cadence from a full analyze.
+ */
+/** Bytes a file contributes to the open round's retained total. */
+export const roundFileBytes = (content) => Buffer.byteLength(content, 'utf8');
+/**
+ * `budgetBytes` bounds what the main thread HOLDS, counting cache hits as well
+ * as misses. Counting only cache-missing bytes would bound just the work sent
+ * to workers, so a warm run — where nothing misses — would never reach the
+ * close condition and would buffer every chunk's cached output until the tail
+ * drain. That is the #2649 heap failure on a large repo.
+ *
+ * Measured in UTF-8 bytes, matching `estimateItemBytes` in the worker pool.
+ * `String.length` would return UTF-16 code units, undercounting non-ASCII
+ * source by up to 3x and letting a CJK-heavy repo hold well past its nominal
+ * budget before draining.
+ */
+export const createRoundBudget = (budgetBytes) => {
+    let bufferedBytes = 0;
+    return {
+        addChunk(contents) {
+            for (const content of contents)
+                bufferedBytes += roundFileBytes(content);
+            if (bufferedBytes >= budgetBytes) {
+                bufferedBytes = 0;
+                return true;
+            }
+            return false;
+        },
+        get bufferedBytes() {
+            return bufferedBytes;
+        },
+        reset() {
+            bufferedBytes = 0;
+        },
+    };
+};

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.d.ts

@@ -615,6 +615,19 @@ export interface ScopeResolver {
     readonly populateWorkspaceOwners?: (parsedFiles: readonly ParsedFile[], ctx: {
         readonly fileContents: ReadonlyMap<string, string>;
     }) => void;
+    /**
+     * Optional workspace-wide enrichment of extracted reference sites. Runs
+     * after all files have been extracted and before reference finalization.
+     * Use this when a per-file capture needs conservative facts from an
+     * imported sibling (for example a compile-time branch constant).
+     */
+    readonly populateWorkspaceReferences?: (parsedFiles: ParsedFile[], ctx: {
+        readonly fileContents: ReadonlyMap<string, string>;
+        readonly treeCache?: {
+            get(filePath: string): unknown;
+        };
+        readonly resolutionConfig?: unknown;
+    }) => void;
     /**
      * Recognize a `super(...)`-style receiver text. Python returns
      * `/^super\s*\(/.test(t)`. Java returns `t === 'super'`. C++ may

package/dist/core/ingestion/scope-resolution/pipeline/phase.js

@@ -55,6 +55,7 @@ const NOOP_OUTPUT = Object.freeze({
 /** Select source files that must be materialized for one resolver pass. */
 export function selectScopeSourcePathsToRead(provider, primaryFilePaths, preExtractedByPath) {
     const hasPostExtractHooks = provider.populateWorkspaceOwners !== undefined ||
+        provider.populateWorkspaceReferences !== undefined ||
         provider.populateNamespaceSiblings !== undefined ||
         provider.populateRangeBindings !== undefined ||
         provider.emitPostResolutionEdges !== undefined;

package/dist/core/ingestion/scope-resolution/pipeline/run.js

@@ -312,6 +312,11 @@ export function runScopeResolution(input, provider) {
     }
     logHeapProbe('sr-extract-end', `lang=${provider.language} parsedFiles=${parsedFiles.length} preExtractedHits=${preExtractedHits} skipped=${filesSkipped}`);
     provider.populateWorkspaceOwners?.(parsedFiles, { fileContents: getFileContents() });
+    provider.populateWorkspaceReferences?.(parsedFiles, {
+        fileContents: getFileContents(),
+        treeCache,
+        resolutionConfig: input.resolutionConfig,
+    });
     // A callable-flow-only provider has no reason to build the whole-graph
     // lookup or finalize ordinary references when none of its files emitted a
     // callable fact. This keeps the opt-in path proportional to source scanning

package/dist/core/ingestion/workers/worker-pool.d.ts

@@ -27,6 +27,12 @@ export interface WorkerPool {
      *
      * Returns one result array per input group, in input order. A group whose
      * items were all quarantined yields an empty array.
+     *
+     * Required, not optional. `getQuarantinedPaths?` and `getStats?` below are
+     * marked optional as a compatibility accommodation for `WorkerPool` shapes
+     * that predate them — not as a convention for new members. Making this one
+     * optional would force a `?.` plus a fallback branch at its only production
+     * call site, and that branch could never run.
      */
     dispatchGroups<TInput, TResult>(groups: readonly DispatchGroup<TInput>[], onProgress?: (filesProcessed: number) => void): Promise<TResult[][]>;
     /**
@@ -260,6 +266,17 @@ interface ResolvedWorkerPoolOptions {
     workerReadyTimeoutMs: number;
 }
 export declare function resolveWorkerPoolOptions(options?: WorkerPoolOptions, poolSize?: number): ResolvedWorkerPoolOptions;
+/**
+ * The pool size requested via the `GITNEXUS_WORKER_POOL_SIZE` env var, or
+ * `undefined` when unset, empty/whitespace, or invalid. Module-internal sizing
+ * reader consumed by {@link resolveAutoPoolSize} (the env override) and
+ * {@link workerPoolDisabledByEnv} (the disabled-channel check). Reads only —
+ * never mutates `process.env`. Empty/whitespace is treated as *unset* (falls
+ * through to the auto formula), not as 0 — an empty assignment (`export
+ * GITNEXUS_WORKER_POOL_SIZE=`) is an accident, not a request for zero workers;
+ * only a literal `0` disables the pool.
+ */
+export declare function envWorkerPoolSize(): number | undefined;
 /**
  * True when the operator set `GITNEXUS_WORKER_POOL_SIZE=0` — the env-channel
  * equivalent of `--workers 0`. The parse phase consults this (only when no
@@ -285,6 +302,13 @@ export declare function workerPoolDisabledByEnv(): boolean;
  * on the env / default.
  */
 export declare function resolveAutoPoolSize(): number;
+/**
+ * Usable parallelism for this process. Prefers `os.availableParallelism` so
+ * cgroup CPU limits are honored, falling back to `os.cpus().length` on older
+ * Node. Exported so callers that size work against the host (rather than
+ * against the pool default) do not re-derive the fallback.
+ */
+export declare function resolveHostParallelism(): number;
 export declare function startHeartbeatStallTracker(): {
     read: () => number;
     stop: () => void;

package/dist/core/ingestion/workers/worker-pool.js

@@ -124,7 +124,9 @@ const DEFAULT_WORKER_READY_TIMEOUT_MS = 5_000;
  * extraction / structured-clone overhead, and the marginal worker adds
  * memory pressure (tree-sitter state + sub-batch buffer) without much
  * throughput gain. Operators on bigger machines override via
- * `GITNEXUS_WORKER_POOL_SIZE` or `--workers <N>`.
+ * `GITNEXUS_WORKER_POOL_SIZE` or `--workers <N>`; both are deliberate
+ * operator input and bypass the work-proportional sizing in `parse-impl`,
+ * which only bounds the AUTO default.
  */
 const DEFAULT_POOL_SIZE_CAP = 16;
 // ── Self-healing startup restart policy (#1741) ──────────────────────────────
@@ -263,7 +265,7 @@ export function resolveWorkerPoolOptions(options = {}, poolSize) {
  * GITNEXUS_WORKER_POOL_SIZE=`) is an accident, not a request for zero workers;
  * only a literal `0` disables the pool.
  */
-function envWorkerPoolSize() {
+export function envWorkerPoolSize() {
     const raw = process.env.GITNEXUS_WORKER_POOL_SIZE;
     if (raw === undefined || raw.trim() === '')
         return undefined;
@@ -307,8 +309,18 @@ export function resolveAutoPoolSize() {
     // pool cap exists to prevent. Falls back to os.cpus().length on
     // older Node versions. Mirrors `capabilities.ts:85`
     // (`defaultEmbeddingThreads`).
-    const cores = typeof os.availableParallelism === 'function' ? os.availableParallelism() : os.cpus().length;
-    return Math.min(DEFAULT_POOL_SIZE_CAP, Math.max(1, cores - 1));
+    return Math.min(DEFAULT_POOL_SIZE_CAP, Math.max(1, resolveHostParallelism() - 1));
+}
+/**
+ * Usable parallelism for this process. Prefers `os.availableParallelism` so
+ * cgroup CPU limits are honored, falling back to `os.cpus().length` on older
+ * Node. Exported so callers that size work against the host (rather than
+ * against the pool default) do not re-derive the fallback.
+ */
+export function resolveHostParallelism() {
+    return typeof os.availableParallelism === 'function'
+        ? os.availableParallelism()
+        : os.cpus().length;
 }
 /**
  * Max characters of a worker's stderr retained for crash diagnostics. A
@@ -889,16 +901,20 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
         // Layer 3: filter out quarantined paths so a known-bad file never reaches
         // a worker again this pool lifetime. The caller queries
         // `getQuarantinedPaths` after dispatch to route filtered items.
-        const dispatchableGroups = groups.map((group) => {
-            const items = [];
-            for (const item of group.items) {
-                const path = itemPath(item);
-                if (path !== undefined && quarantine.has(path))
-                    continue;
-                items.push(item);
-            }
-            return { items, chunkHash: group.chunkHash };
-        });
+        // Quarantine is empty on every run that has not had a worker die, so the
+        // filter below would be an identity copy of every group's items. Skip it.
+        const dispatchableGroups = quarantine.size === 0
+            ? groups
+            : groups.map((group) => {
+                const items = [];
+                for (const item of group.items) {
+                    const path = itemPath(item);
+                    if (path !== undefined && quarantine.has(path))
+                        continue;
+                    items.push(item);
+                }
+                return { items, chunkHash: group.chunkHash };
+            });
         const dispatchableCount = dispatchableGroups.reduce((sum, group) => sum + group.items.length, 0);
         if (dispatchableCount === 0)
             return emptyPerGroup();

package/package.json

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