gitnexus 1.5.2 → 1.6.0

package/dist/core/ingestion/pipeline.js

@@ -1,22 +1,24 @@
 import { createKnowledgeGraph } from '../graph/graph.js';
+import { BindingAccumulator, enrichExportedTypeMap, } from './binding-accumulator.js';
 import { processStructure } from './structure-processor.js';
 import { processMarkdown } from './markdown-processor.js';
 import { processCobol, isCobolFile, isJclFile } from './cobol-processor.js';
 import { processParsing } from './parsing-processor.js';
 import { processImports, processImportsFromExtracted, buildImportResolutionContext, } from './import-processor.js';
 import { EMPTY_INDEX } from './import-resolvers/utils.js';
-import { processCalls, processCallsFromExtracted, processAssignmentsFromExtracted, processRoutesFromExtracted, processNextjsFetchRoutes, extractFetchCallsFromFiles, seedCrossFileReceiverTypes, buildImportedReturnTypes, buildImportedRawReturnTypes, buildExportedTypeMapFromGraph, buildImplementorMap, mergeImplementorMaps, } from './call-processor.js';
+import { processCalls, processCallsFromExtracted, processAssignmentsFromExtracted, processRoutesFromExtracted, processNextjsFetchRoutes, extractFetchCallsFromFiles, seedCrossFileReceiverTypes, buildImportedReturnTypes, buildImportedRawReturnTypes, buildExportedTypeMapFromGraph, } from './call-processor.js';
+import { buildHeritageMap } from './model/heritage-map.js';
 import { nextjsFileToRouteURL, normalizeFetchURL } from './route-extractors/nextjs.js';
 import { expoFileToRouteURL } from './route-extractors/expo.js';
 import { phpFileToRouteURL } from './route-extractors/php.js';
 import { extractResponseShapes, extractPHPResponseShapes, } from './route-extractors/response-shapes.js';
 import { extractMiddlewareChain, extractNextjsMiddlewareConfig, compileMatcher, compiledMatcherMatchesRoute, } from './route-extractors/middleware.js';
 import { generateId } from '../../lib/utils.js';
-import { processHeritage, processHeritageFromExtracted, extractExtractedHeritageFromFiles, } from './heritage-processor.js';
+import { processHeritage, processHeritageFromExtracted, extractExtractedHeritageFromFiles, getHeritageStrategyForLanguage, } from './heritage-processor.js';
 import { computeMRO } from './mro-processor.js';
 import { processCommunities } from './community-processor.js';
 import { processProcesses } from './process-processor.js';
-import { createResolutionContext } from './resolution-context.js';
+import { createResolutionContext } from './model/resolution-context.js';
 import { createASTCache } from './ast-cache.js';
 import { getLanguageFromFilename } from '../../_shared/index.js';
 import { walkRepositoryPaths, readFileContents } from './filesystem-walker.js';
@@ -252,7 +254,7 @@ async function runCrossFileBindingPropagation(graph, ctx, exportedTypeMap, allPa
     // For the worker path, buildTypeEnv runs inside workers without SymbolTable,
     // so exported bindings must be collected from graph + SymbolTable in main thread.
     if (exportedTypeMap.size === 0 && graph.nodeCount > 0) {
-        const graphExports = buildExportedTypeMapFromGraph(graph, ctx.symbols);
+        const graphExports = buildExportedTypeMapFromGraph(graph, ctx.model.symbols);
         for (const [fp, exports] of graphExports)
             exportedTypeMap.set(fp, exports);
     }
@@ -278,7 +280,7 @@ async function runCrossFileBindingPropagation(graph, ctx, exportedTypeMap, allPa
                     filesWithGaps++;
                     break;
                 }
-                const def = ctx.symbols.lookupExactFull(binding.sourcePath, binding.exportedName);
+                const def = ctx.model.symbols.lookupExactFull(binding.sourcePath, binding.exportedName);
                 if (def?.returnType) {
                     filesWithGaps++;
                     break;
@@ -321,8 +323,8 @@ async function runCrossFileBindingPropagation(graph, ctx, exportedTypeMap, allPa
                         seeded.set(localName, type);
                 }
             }
-            const importedReturns = buildImportedReturnTypes(filePath, ctx.namedImportMap, ctx.symbols);
-            const importedRawReturns = buildImportedRawReturnTypes(filePath, ctx.namedImportMap, ctx.symbols);
+            const importedReturns = buildImportedReturnTypes(filePath, ctx.namedImportMap, ctx.model.symbols);
+            const importedRawReturns = buildImportedRawReturnTypes(filePath, ctx.namedImportMap, ctx.model.symbols);
             if (seeded.size === 0 && importedReturns.size === 0)
                 continue;
             if (!allPathSet.has(filePath))
@@ -480,8 +482,8 @@ async function runScanAndStructure(repoPath, graph, onProgress) {
  * Follow-up from PR review: MethodExtractor (FieldExtractor parity) and optional
  * METHOD_IMPLEMENTS graph edges to make dispatch queryable without an in-memory map.
  */
-async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, totalFiles, repoPath, pipelineStart, onProgress) {
-    const symbolTable = ctx.symbols;
+async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, totalFiles, repoPath, pipelineStart, onProgress, options) {
+    const symbolTable = ctx.model.symbols;
     const parseableScanned = scannedFiles.filter((f) => {
         const lang = getLanguageFromFilename(f.path);
         return lang && isLanguageAvailable(lang);
@@ -538,7 +540,8 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
     const totalBytes = parseableScanned.reduce((s, f) => s + f.size, 0);
     // Create worker pool once, reuse across chunks
     let workerPool;
-    if (totalParseable >= MIN_FILES_FOR_WORKERS || totalBytes >= MIN_BYTES_FOR_WORKERS) {
+    if (!options?.skipWorkers &&
+        (totalParseable >= MIN_FILES_FOR_WORKERS || totalBytes >= MIN_BYTES_FOR_WORKERS)) {
         try {
             let workerUrl = new URL('./workers/parse-worker.js', import.meta.url);
             // When running under vitest, import.meta.url points to src/ where no .js exists.
@@ -578,7 +581,7 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
     // Phase 14: Collect exported type bindings for cross-file propagation
     const exportedTypeMap = new Map();
     // Accumulate file-scope TypeEnv bindings from workers (closes worker/sequential quality gap)
-    const workerTypeEnvBindings = [];
+    const bindingAccumulator = new BindingAccumulator();
     // Accumulate fetch() calls from workers for Next.js route matching
     const allFetchCalls = [];
     // Accumulate framework-extracted routes (Laravel, etc.) for Route node creation
@@ -649,11 +652,15 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
                         console.log(`🔗 E1: Seeded ${enrichedCount} cross-file receiver types (chunk ${chunkIdx + 1})`);
                     }
                 }
-                deferredWorkerCalls.push(...chunkWorkerData.calls);
-                deferredWorkerHeritage.push(...chunkWorkerData.heritage);
-                deferredConstructorBindings.push(...chunkWorkerData.constructorBindings);
+                for (const _item of chunkWorkerData.calls)
+                    deferredWorkerCalls.push(_item);
+                for (const _item of chunkWorkerData.heritage)
+                    deferredWorkerHeritage.push(_item);
+                for (const _item of chunkWorkerData.constructorBindings)
+                    deferredConstructorBindings.push(_item);
                 if (chunkWorkerData.assignments?.length) {
-                    deferredAssignments.push(...chunkWorkerData.assignments);
+                    for (const _item of chunkWorkerData.assignments)
+                        deferredAssignments.push(_item);
                 }
                 // Heritage + Routes — calls deferred until all chunks have contributed heritage
                 // (complete implementor map for interface dispatch).
@@ -685,25 +692,56 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
                         });
                     }),
                 ]);
-                // Collect TypeEnv file-scope bindings for exported type enrichment
-                if (chunkWorkerData.typeEnvBindings?.length) {
-                    workerTypeEnvBindings.push(...chunkWorkerData.typeEnvBindings);
+                // Collect file-scope bindings into BindingAccumulator. The worker
+                // IPC payload carries only file-scope entries (`scope = ''`
+                // hardcoded here). See the FileScopeBindings JSDoc in
+                // parse-worker.ts for the rationale and Phase 9 reversion path.
+                //
+                // Defensive validation at the IPC boundary: silently skip entries
+                // with non-string varName/typeName. If a future worker regression
+                // (or a Phase 9 reversion mistake that emits 3-tuples into the
+                // 2-tuple consumer) produces malformed data, logging is better
+                // than silently writing `undefined` into the enrichment map.
+                if (chunkWorkerData.fileScopeBindings?.length) {
+                    for (const { filePath, bindings } of chunkWorkerData.fileScopeBindings) {
+                        if (typeof filePath !== 'string' || filePath.length === 0)
+                            continue;
+                        if (!Array.isArray(bindings))
+                            continue;
+                        const entries = [];
+                        for (const tuple of bindings) {
+                            if (!Array.isArray(tuple) || tuple.length !== 2)
+                                continue;
+                            const [varName, typeName] = tuple;
+                            if (typeof varName !== 'string' || typeof typeName !== 'string')
+                                continue;
+                            entries.push({ scope: '', varName, typeName });
+                        }
+                        if (entries.length > 0) {
+                            bindingAccumulator.appendFile(filePath, entries);
+                        }
+                    }
                 }
                 // Collect fetch() calls for Next.js route matching
                 if (chunkWorkerData.fetchCalls?.length) {
-                    allFetchCalls.push(...chunkWorkerData.fetchCalls);
+                    for (const _item of chunkWorkerData.fetchCalls)
+                        allFetchCalls.push(_item);
                 }
                 if (chunkWorkerData.routes?.length) {
-                    allExtractedRoutes.push(...chunkWorkerData.routes);
+                    for (const _item of chunkWorkerData.routes)
+                        allExtractedRoutes.push(_item);
                 }
                 if (chunkWorkerData.decoratorRoutes?.length) {
-                    allDecoratorRoutes.push(...chunkWorkerData.decoratorRoutes);
+                    for (const _item of chunkWorkerData.decoratorRoutes)
+                        allDecoratorRoutes.push(_item);
                 }
                 if (chunkWorkerData.toolDefs?.length) {
-                    allToolDefs.push(...chunkWorkerData.toolDefs);
+                    for (const _item of chunkWorkerData.toolDefs)
+                        allToolDefs.push(_item);
                 }
                 if (chunkWorkerData.ormQueries?.length) {
-                    allORMQueries.push(...chunkWorkerData.ormQueries);
+                    for (const _item of chunkWorkerData.ormQueries)
+                        allORMQueries.push(_item);
                 }
             }
             else {
@@ -715,10 +753,10 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
             astCache.clear();
             // chunkContents + chunkFiles + chunkWorkerData go out of scope → GC reclaims
         }
-        // Complete implementor map from all worker heritage, then resolve CALLS once (interface dispatch).
-        const fullWorkerImplementorMap = deferredWorkerHeritage.length > 0
-            ? buildImplementorMap(deferredWorkerHeritage, ctx)
-            : new Map();
+        // Build unified HeritageMap (parent lookup + implementor index) after all chunks.
+        const fullWorkerHeritageMap = deferredWorkerHeritage.length > 0
+            ? buildHeritageMap(deferredWorkerHeritage, ctx, getHeritageStrategyForLanguage)
+            : undefined;
         if (deferredWorkerCalls.length > 0) {
             await processCallsFromExtracted(graph, deferredWorkerCalls, ctx, (current, total) => {
                 onProgress({
@@ -732,10 +770,23 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
                         nodesCreated: graph.nodeCount,
                     },
                 });
-            }, deferredConstructorBindings.length > 0 ? deferredConstructorBindings : undefined, fullWorkerImplementorMap);
+            }, deferredConstructorBindings.length > 0 ? deferredConstructorBindings : undefined, fullWorkerHeritageMap, 
+            // Phase 9: pass the accumulator so processCallsFromExtracted can fall back
+            // to file-scope TypeEnv bindings when the SymbolTable lacks a return type
+            // for a cross-file callee (e.g. var x = getUser() → x: User).
+            //
+            // Lifecycle ordering: the accumulator is populated but NOT yet finalized
+            // at this seam. finalize() is called later (after the sequential-path
+            // processCalls which also appends via typeEnv.flush()). Moving finalize()
+            // before this call would break sequential-path repos. Pre-finalize reads
+            // are safe because finalize() is a write-lock-only operation with no side
+            // effects on stored data. All worker-path appendFile calls complete in the
+            // chunk loop above, so every worker-contributed binding is available via
+            // fileScopeGet().
+            bindingAccumulator);
         }
         if (deferredAssignments.length > 0) {
-            processAssignmentsFromExtracted(graph, deferredAssignments, ctx, deferredConstructorBindings.length > 0 ? deferredConstructorBindings : undefined);
+            processAssignmentsFromExtracted(graph, deferredAssignments, ctx, deferredConstructorBindings.length > 0 ? deferredConstructorBindings : undefined, bindingAccumulator);
         }
     }
     finally {
@@ -746,18 +797,40 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
     // before any call resolution — same rationale as the worker-path inline synthesis.
     if (sequentialChunkPaths.length > 0)
         synthesizeWildcardImportBindings(graph, ctx);
-    // Merge implementor-map deltas per chunk (O(heritage per chunk)), not O(|edges|) graph scans
-    // per chunk — mirrors worker-path deferred heritage without re-iterating all relationships.
-    const sequentialImplementorMap = new Map();
+    // Pass 1: Extract heritage from all sequential chunks.
+    // Heritage must be fully accumulated BEFORE call resolution so the HeritageMap
+    // has the complete ancestor chain and implementor index (same constraint as
+    // the worker path).
+    //
+    // File contents are read once here and cached for Pass 2 to avoid a 2× I/O
+    // cost on the sequential path (ASTs are intentionally NOT cached — rebuilding
+    // them in Pass 2 keeps peak memory bounded to one chunk at a time).
+    const allSequentialHeritage = [];
+    const cachedSequentialChunkFiles = [];
     for (const chunkPaths of sequentialChunkPaths) {
         const chunkContents = await readFileContents(repoPath, chunkPaths);
         const chunkFiles = chunkPaths
             .filter((p) => chunkContents.has(p))
             .map((p) => ({ path: p, content: chunkContents.get(p) }));
+        cachedSequentialChunkFiles.push(chunkFiles);
         astCache = createASTCache(chunkFiles.length);
         const sequentialHeritage = await extractExtractedHeritageFromFiles(chunkFiles, astCache);
-        mergeImplementorMaps(sequentialImplementorMap, buildImplementorMap(sequentialHeritage, ctx));
-        const rubyHeritage = await processCalls(graph, chunkFiles, astCache, ctx, undefined, exportedTypeMap, undefined, undefined, undefined, sequentialImplementorMap);
+        // Manual loop (not spread) — `push(...arr)` blows the stack on very large
+        // arrays, see #650. Pay the explicit iteration cost for safety.
+        for (const h of sequentialHeritage)
+            allSequentialHeritage.push(h);
+        astCache.clear();
+    }
+    // Build unified HeritageMap from all sequential heritage (parent lookup + implementor index).
+    const sequentialHeritageMap = allSequentialHeritage.length > 0
+        ? buildHeritageMap(allSequentialHeritage, ctx, getHeritageStrategyForLanguage)
+        : undefined;
+    // Pass 2: Process calls, heritage edges, fetch calls, and ORM queries per chunk.
+    // Reuse the file contents cached in Pass 1 instead of re-reading from disk.
+    for (let chunkIdx = 0; chunkIdx < sequentialChunkPaths.length; chunkIdx++) {
+        const chunkFiles = cachedSequentialChunkFiles[chunkIdx];
+        astCache = createASTCache(chunkFiles.length);
+        const rubyHeritage = await processCalls(graph, chunkFiles, astCache, ctx, undefined, exportedTypeMap, undefined, undefined, undefined, sequentialHeritageMap, bindingAccumulator);
         await processHeritage(graph, chunkFiles, astCache, ctx);
         if (rubyHeritage.length > 0) {
             await processHeritageFromExtracted(graph, rubyHeritage, ctx);
@@ -765,13 +838,18 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
         // Extract fetch() calls for Next.js route matching (sequential path)
         const chunkFetchCalls = await extractFetchCallsFromFiles(chunkFiles, astCache);
         if (chunkFetchCalls.length > 0) {
-            allFetchCalls.push(...chunkFetchCalls);
+            for (const _item of chunkFetchCalls)
+                allFetchCalls.push(_item);
         }
         // Extract ORM queries (sequential path)
         for (const f of chunkFiles) {
             extractORMQueriesInline(f.path, f.content, allORMQueries);
         }
         astCache.clear();
+        // Release cached chunk content as soon as Pass 2 finishes with it so the
+        // Pass-1 content map drains incrementally rather than being held for the
+        // full duration of Pass 2.
+        cachedSequentialChunkFiles[chunkIdx] = [];
     }
     // Log resolution cache stats
     if (isDev) {
@@ -780,36 +858,28 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
         const hitRate = total > 0 ? ((rcStats.cacheHits / total) * 100).toFixed(1) : '0';
         console.log(`🔍 Resolution cache: ${rcStats.cacheHits} hits, ${rcStats.cacheMisses} misses (${hitRate}% hit rate)`);
     }
-    // ── Worker path quality enrichment: merge TypeEnv file-scope bindings into ExportedTypeMap ──
-    // Workers return file-scope bindings from their TypeEnv fixpoint (includes inferred types
-    // like `const config = getConfig()` → Config). Filter by graph isExported to match
-    // the sequential path's collectExportedBindings behavior.
-    if (workerTypeEnvBindings.length > 0) {
-        let enriched = 0;
-        for (const { filePath, bindings } of workerTypeEnvBindings) {
-            for (const [name, type] of bindings) {
-                // Verify the symbol is exported via graph node
-                const nodeId = `Function:${filePath}:${name}`;
-                const varNodeId = `Variable:${filePath}:${name}`;
-                const constNodeId = `Const:${filePath}:${name}`;
-                const node = graph.getNode(nodeId) ?? graph.getNode(varNodeId) ?? graph.getNode(constNodeId);
-                if (!node?.properties?.isExported)
-                    continue;
-                let fileExports = exportedTypeMap.get(filePath);
-                if (!fileExports) {
-                    fileExports = new Map();
-                    exportedTypeMap.set(filePath, fileExports);
-                }
-                // Don't overwrite existing entries (Tier 0 from SymbolTable is authoritative)
-                if (!fileExports.has(name)) {
-                    fileExports.set(name, type);
-                    enriched++;
-                }
-            }
-        }
-        if (isDev && enriched > 0) {
-            console.log(`🔗 Worker TypeEnv enrichment: ${enriched} fixpoint-inferred exports added to ExportedTypeMap`);
-        }
+    // ── Finalize the accumulator before the read phase begins. All worker-path
+    //    appends (line ~934) and sequential-path flushes (via `processCalls` →
+    //    `typeEnv.flush()` earlier in this function) have completed by here,
+    //    so the finalize-write-lock is correct at this seam. Making the
+    //    lifecycle contract explicit — `append → finalize → consume → dispose`.
+    //    Previously `finalize()` was called much later in `runPipelineFromRepo`
+    //    after the enrichment loop had already read the mutable accumulator.
+    bindingAccumulator.finalize();
+    // ── Worker path quality enrichment: merge file-scope bindings into ExportedTypeMap ──
+    // Counterpart to `collectExportedBindings()` in call-processor.ts which
+    // handles the sequential path (main thread, full SymbolTable access).
+    // This call handles the worker path via the accumulator. Both sites
+    // populate the same `exportedTypeMap` with subtly different export-check
+    // semantics — sequential uses SymbolTable + graph lookup, `enrichExportedTypeMap`
+    // uses a three-candidate-ID graph lookup. They must stay in sync until
+    // Phase 9 unifies them. If you edit one, check the other.
+    //
+    // The enrichment loop itself lives in `binding-accumulator.ts` so tests
+    // can exercise the real production code instead of reimplementing it.
+    const enriched = enrichExportedTypeMap(bindingAccumulator, graph, exportedTypeMap);
+    if (isDev && enriched > 0) {
+        console.log(`🔗 Worker TypeEnv enrichment: ${enriched} fixpoint-inferred exports added to ExportedTypeMap`);
     }
     // ── Final synthesis pass for whole-module-import languages ──
     // Per-chunk synthesis (above) already ran incrementally. This final pass ensures
@@ -832,13 +902,14 @@ async function runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, tot
         allDecoratorRoutes,
         allToolDefs,
         allORMQueries,
+        bindingAccumulator,
     };
 }
 /**
  * Post-parse graph analysis: MRO, community detection, process extraction.
  *
  * @reads  graph (all nodes and relationships from parse + resolve phases)
- * @writes graph (Community nodes, Process nodes, MEMBER_OF edges, STEP_IN_PROCESS edges, OVERRIDES edges)
+ * @writes graph (Community nodes, Process nodes, MEMBER_OF edges, STEP_IN_PROCESS edges, METHOD_OVERRIDES edges)
  */
 async function runGraphAnalysisPhases(graph, totalFiles, onProgress, routeRegistry, toolDefs) {
     // ── Phase 4.5: Method Resolution Order ──────────────────────────────
@@ -850,7 +921,7 @@ async function runGraphAnalysisPhases(graph, totalFiles, onProgress, routeRegist
     });
     const mroResult = computeMRO(graph);
     if (isDev && mroResult.entries.length > 0) {
-        console.log(`🔀 MRO: ${mroResult.entries.length} classes analyzed, ${mroResult.ambiguityCount} ambiguities found, ${mroResult.overrideEdges} OVERRIDES edges`);
+        console.log(`🔀 MRO: ${mroResult.entries.length} classes analyzed, ${mroResult.ambiguityCount} ambiguities, ${mroResult.overrideEdges} METHOD_OVERRIDES, ${mroResult.methodImplementsEdges} METHOD_IMPLEMENTS`);
     }
     // ── Phase 5: Communities ───────────────────────────────────────────
     onProgress({
@@ -1023,11 +1094,24 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
     const graph = createKnowledgeGraph();
     const ctx = createResolutionContext();
     const pipelineStart = Date.now();
+    // Hoisted reference for error-path cleanup. The accumulator is normally
+    // disposed at the happy-path seam after the dev telemetry log, but if any
+    // step between the runChunkedParseAndResolve return and that seam throws
+    // (ORM processing, tool node creation, Phase 14, graph analysis), the
+    // catch handler disposes it here so the heap footprint does not leak
+    // through the rethrow. See binding-accumulator.ts dispose() JSDoc for the
+    // lifecycle contract.
+    let bindingAccumulatorForCleanup;
     try {
         // Phase 1+2: Scan paths, build structure, process markdown
         const { scannedFiles, allPaths, totalFiles } = await runScanAndStructure(repoPath, graph, onProgress);
         // Phase 3+4: Chunked parse + resolve (imports, calls, heritage, routes)
-        const { exportedTypeMap, allFetchCalls, allExtractedRoutes, allDecoratorRoutes, allToolDefs, allORMQueries, } = await runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, totalFiles, repoPath, pipelineStart, onProgress);
+        const { exportedTypeMap, allFetchCalls, allExtractedRoutes, allDecoratorRoutes, allToolDefs, allORMQueries, bindingAccumulator, } = await runChunkedParseAndResolve(graph, ctx, scannedFiles, allPaths, totalFiles, repoPath, pipelineStart, onProgress, options);
+        // Track the accumulator for error-path cleanup — the happy-path dispose
+        // is still at the post-telemetry seam below, this reference is only
+        // consulted by the catch handler if any step between here and there
+        // throws.
+        bindingAccumulatorForCleanup = bindingAccumulator;
         const routeRegistry = new Map();
         // Detect Expo Router app/ roots vs Next.js app/ roots (monorepo-safe).
         const expoAppRoots = new Set();
@@ -1303,6 +1387,40 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         if (allORMQueries.length > 0) {
             processORMQueries(graph, allORMQueries, isDev);
         }
+        // `bindingAccumulator.finalize()` was moved inside `runChunkedParseAndResolve`
+        // to immediately precede the enrichment loop — see the comment there for
+        // the ordering rationale. By the time execution
+        // reaches this point, the accumulator has already been finalized, consumed
+        // by the enrichment loop, and is ready for dispose() below after the dev
+        // telemetry log captures peak state.
+        if (isDev) {
+            if (bindingAccumulator.totalBindings > 0) {
+                const memKB = Math.round(bindingAccumulator.estimateMemoryBytes() / 1024);
+                console.log(`📦 BindingAccumulator: ${bindingAccumulator.totalBindings} bindings across ${bindingAccumulator.fileCount} files (~${memKB} KB)`);
+            }
+            else if (totalFiles > 0) {
+                // Zero-binding signal: if the pipeline parsed files but the
+                // accumulator is empty, something upstream dropped all bindings.
+                // Flag it so operators can spot a regression (e.g. a worker path
+                // that accidentally emits empty fileScopeBindings arrays for every
+                // file, or a TypeEnv build failure). Dev-mode only.
+                console.log(`📦 BindingAccumulator: EMPTY — 0 bindings across 0 files despite ${totalFiles} parsed files. If the codebase has typed bindings, this indicates an upstream regression.`);
+            }
+        }
+        // Release the accumulator's heap footprint now. Both consumers of the
+        // accumulator have completed:
+        //   1. ExportedTypeMap enrichment loop (enrichExportedTypeMap, above).
+        //   2. Phase 9: processCallsFromExtracted in runChunkedParseAndResolve,
+        //      which uses the accumulator as a BindingAccumulator fallback for
+        //      cross-file return types when the SymbolTable has no returnType.
+        // Phase 14 (runCrossFileBindingPropagation) and runGraphAnalysisPhases
+        // do not read the accumulator — keeping it alive through those long-
+        // running phases pins heap for no reason.
+        bindingAccumulator.dispose();
+        // Happy-path dispose completed — clear the cleanup ref so the catch
+        // handler doesn't attempt a second (harmless but noisy) dispose if a
+        // later phase throws.
+        bindingAccumulatorForCleanup = undefined;
         // ── Phase 14: Cross-file binding propagation (topological level sort) ──
         await runCrossFileBindingPropagation(graph, ctx, exportedTypeMap, allPaths, totalFiles, repoPath, pipelineStart, onProgress);
         // Post-parse graph analysis (MRO, communities, processes)
@@ -1328,6 +1446,12 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         return { graph, repoPath, totalFileCount: totalFiles, communityResult, processResult };
     }
     catch (error) {
+        // Error-path cleanup: dispose the accumulator if a step after the
+        // destructure from runChunkedParseAndResolve but before the happy-path
+        // dispose threw. The reference is cleared on the happy path, so this
+        // is a no-op when the pipeline completed successfully and then threw
+        // from an unrelated post-dispose step (e.g., future cleanup code).
+        bindingAccumulatorForCleanup?.dispose();
         ctx.clear();
         throw error;
     }