gitnexus 1.6.3-rc.8 → 1.6.3

package/dist/core/ingestion/model/scope-resolution-indexes.js

@@ -0,0 +1,42 @@
+/**
+ * `ScopeResolutionIndexes` — the bundle of materialized indexes produced
+ * by the finalize-orchestrator (RFC #909 Ring 2 PKG #921) and attached
+ * to `MutableSemanticModel`.
+ *
+ * Produced by `finalizeScopeModel(parsedFiles, hooks)` in
+ * `finalize-orchestrator.ts`. Consumed by the resolution phase (future
+ * tickets) where `Registry.lookup` / `resolveTypeRef` query this bundle
+ * to answer call-resolution questions without re-walking any AST.
+ *
+ * ## Lifecycle
+ *
+ *   1. Pipeline collects `ParsedFile[]` from the parsing-processor (#920).
+ *   2. Pipeline invokes `finalizeScopeModel(parsedFiles, hooks)` →
+ *      returns a `ScopeResolutionIndexes` (this interface).
+ *   3. Pipeline calls `model.attachScopeIndexes(indexes)` to stamp them
+ *      onto the `MutableSemanticModel`. This is a **one-shot write**;
+ *      subsequent calls throw. After attachment, the indexes are frozen
+ *      at the type level (everything is `readonly`) and at runtime via
+ *      `Object.freeze` on the bundle.
+ *   4. Resolution callers hold a `SemanticModel` reference and read
+ *      `model.scopes` to query.
+ *
+ * ## Content
+ *
+ *   - `scopeTree` / `moduleScopes` / `defs` / `qualifiedNames` — the
+ *     four Ring 2 SHARED indexes built over per-file artifacts.
+ *   - `methodDispatch` — MRO + implements materialized view (#914).
+ *   - `imports` — finalized `ImportEdge[]` per module scope (`parsedImports`
+ *     resolved through cross-file link + wildcard expansion).
+ *   - `bindings` — merged bindings per module scope (local + import +
+ *     wildcard + re-export), with the provider's precedence applied.
+ *   - `referenceSites` — union of every file's pre-resolution usage
+ *     facts. Consumed by the resolution phase (future) to emit
+ *     `Reference` records into `ReferenceIndex`.
+ *   - `stats` — coarse-grained counts from the shared finalize algorithm
+ *     (total files/edges, linked vs unresolved, SCC topology).
+ *
+ * `ReferenceIndex` is deliberately NOT here — it is populated in a later
+ * phase (RFC §3.2 Phase 4 / Ring 2 PKG #925) and owned separately.
+ */
+export {};

package/dist/core/ingestion/model/semantic-model.d.ts

@@ -44,11 +44,51 @@
  * direct `createSymbolTable()` caller (e.g. an isolated unit test) gets
  * the pure, registry-free behavior — no surprises, no hidden side
  * effects.
+ *
+ * ## Single-source-of-truth invariant
+ *
+ * `SemanticModel` is the authoritative symbol store for the whole
+ * ingestion pipeline. Both the legacy Call-Resolution DAG and the
+ * new scope-resolution pipeline read symbol-keyed lookups from here
+ * exclusively — no parallel owner-keyed, name-keyed, or file-keyed
+ * symbol indexes exist outside this module. The scope-resolution
+ * pipeline does carry a small `WorkspaceResolutionIndex` for
+ * `Scope`-valued maps (`classScopeByDefId`, `moduleScopeByFile`) that
+ * `SemanticModel` structurally cannot hold, but nothing else.
+ *
+ * ## Write / read phase contract
+ *
+ * Writes to the model happen in three clearly-ordered phases during a
+ * single ingestion run:
+ *
+ *   1. **Legacy parse phase** (`parsing-processor`) calls
+ *      `symbols.add(...)` per extracted symbol, which fans out via
+ *      the dispatch table into `types` / `methods` / `fields`.
+ *   2. **Scope-resolution reconciliation** (`reconcileOwnership` in
+ *      `scope-resolution/pipeline/reconcile-ownership.ts`) registers
+ *      any `parsed.localDefs[i]` with a scope-resolution-corrected
+ *      `ownerId` that the legacy pass missed (Python class-body
+ *      methods are the canonical case). Idempotent.
+ *   3. **Finalize-orchestrator** calls `attachScopeIndexes(...)` to
+ *      stamp the materialized `ScopeResolutionIndexes` bundle onto
+ *      `model.scopes`. One-shot; throws on a second call.
+ *
+ * After these three phases, the model is effectively frozen:
+ *   - `attachScopeIndexes` applied `Object.freeze` to its bundle.
+ *   - Downstream passes receive the narrowed `SemanticModel` reader
+ *     handle (not `MutableSemanticModel`), so `.register()` /
+ *     `.clear()` / `attachScopeIndexes()` are structurally absent.
+ *
+ * See `scope-resolution/contract/scope-resolver.ts` Contract
+ * Invariant I9 for the scope-resolution-side rule and
+ * `ARCHITECTURE.md` § "Semantic-model source of truth" for the
+ * overall architecture.
  */
 import type { TypeRegistry, MutableTypeRegistry } from './type-registry.js';
 import type { MethodRegistry, MutableMethodRegistry } from './method-registry.js';
 import type { FieldRegistry, MutableFieldRegistry } from './field-registry.js';
 import type { SymbolTableReader, SymbolTableWriter } from './symbol-table.js';
+import type { ScopeResolutionIndexes } from './scope-resolution-indexes.js';
 /**
  * Aggregated read-only view of the semantic registries plus the nested
  * file/callable SymbolTable.
@@ -70,6 +110,19 @@ export interface SemanticModel {
     readonly methods: MethodRegistry;
     readonly fields: FieldRegistry;
     readonly symbols: SymbolTableReader;
+    /**
+     * Materialized scope-resolution indexes from RFC #909 Ring 2 PKG #921.
+     *
+     * `undefined` until the finalize-orchestrator attaches them. While
+     * `undefined`, the legacy DAG is the sole resolution surface; once set,
+     * resolvers whose language has `REGISTRY_PRIMARY_<LANG>=true` consult
+     * these indexes instead.
+     *
+     * The attach is a one-shot write (see `MutableSemanticModel`). Callers
+     * holding a read-only `SemanticModel` handle see either `undefined` or
+     * the final frozen bundle — never a half-populated view.
+     */
+    readonly scopes?: ScopeResolutionIndexes;
 }
 /** Mutable variant — exposes the MutableX registries, a Writer-typed
  *  `symbols` facade, and a full-cascade reset. This is the interface
@@ -82,5 +135,16 @@ export interface MutableSemanticModel extends SemanticModel {
     readonly symbols: SymbolTableWriter;
     /** Clear all registries AND the nested SymbolTable. */
     clear(): void;
+    /**
+     * Stamp the finalize-orchestrator's output onto this model.
+     *
+     * **One-shot write.** Throws when called a second time — the indexes are
+     * meant to be materialized once per ingestion run. `Object.freeze` is
+     * applied to the attached bundle so consumers cannot mutate after attach.
+     *
+     * `clear()` resets the attached bundle back to `undefined`, enabling a
+     * fresh re-ingestion to attach a new bundle.
+     */
+    attachScopeIndexes(indexes: ScopeResolutionIndexes): void;
 }
 export declare const createSemanticModel: () => MutableSemanticModel;

package/dist/core/ingestion/model/semantic-model.js

@@ -44,6 +44,45 @@
  * direct `createSymbolTable()` caller (e.g. an isolated unit test) gets
  * the pure, registry-free behavior — no surprises, no hidden side
  * effects.
+ *
+ * ## Single-source-of-truth invariant
+ *
+ * `SemanticModel` is the authoritative symbol store for the whole
+ * ingestion pipeline. Both the legacy Call-Resolution DAG and the
+ * new scope-resolution pipeline read symbol-keyed lookups from here
+ * exclusively — no parallel owner-keyed, name-keyed, or file-keyed
+ * symbol indexes exist outside this module. The scope-resolution
+ * pipeline does carry a small `WorkspaceResolutionIndex` for
+ * `Scope`-valued maps (`classScopeByDefId`, `moduleScopeByFile`) that
+ * `SemanticModel` structurally cannot hold, but nothing else.
+ *
+ * ## Write / read phase contract
+ *
+ * Writes to the model happen in three clearly-ordered phases during a
+ * single ingestion run:
+ *
+ *   1. **Legacy parse phase** (`parsing-processor`) calls
+ *      `symbols.add(...)` per extracted symbol, which fans out via
+ *      the dispatch table into `types` / `methods` / `fields`.
+ *   2. **Scope-resolution reconciliation** (`reconcileOwnership` in
+ *      `scope-resolution/pipeline/reconcile-ownership.ts`) registers
+ *      any `parsed.localDefs[i]` with a scope-resolution-corrected
+ *      `ownerId` that the legacy pass missed (Python class-body
+ *      methods are the canonical case). Idempotent.
+ *   3. **Finalize-orchestrator** calls `attachScopeIndexes(...)` to
+ *      stamp the materialized `ScopeResolutionIndexes` bundle onto
+ *      `model.scopes`. One-shot; throws on a second call.
+ *
+ * After these three phases, the model is effectively frozen:
+ *   - `attachScopeIndexes` applied `Object.freeze` to its bundle.
+ *   - Downstream passes receive the narrowed `SemanticModel` reader
+ *     handle (not `MutableSemanticModel`), so `.register()` /
+ *     `.clear()` / `attachScopeIndexes()` are structurally absent.
+ *
+ * See `scope-resolution/contract/scope-resolver.ts` Contract
+ * Invariant I9 for the scope-resolution-side rule and
+ * `ARCHITECTURE.md` § "Semantic-model source of truth" for the
+ * overall architecture.
  */
 import { createTypeRegistry } from './type-registry.js';
 import { createMethodRegistry } from './method-registry.js';
@@ -85,6 +124,17 @@ export const createSemanticModel = () => {
         }
         return def;
     };
+    // Scope-resolution bundle slot. Starts `undefined`; populated by a
+    // one-shot `attachScopeIndexes(...)` from the finalize-orchestrator.
+    // Held inside the factory closure so the returned `SemanticModel`
+    // surface exposes it as a plain `readonly` property without a setter.
+    let attachedScopes;
+    const attachScopeIndexes = (indexes) => {
+        if (attachedScopes !== undefined) {
+            throw new Error('SemanticModel: scope indexes already attached. ' + 'Call `clear()` before re-attaching.');
+        }
+        attachedScopes = Object.freeze(indexes);
+    };
     // Cascade clear: single source of truth for "reset the entire model".
     // Wired into both `model.clear()` AND `model.symbols.clear()` so that a
     // caller holding only a SymbolTable reference can't leave the
@@ -95,6 +145,7 @@ export const createSemanticModel = () => {
         methods.clear();
         fields.clear();
         rawSymbols.clear();
+        attachedScopes = undefined;
     };
     // Writer-typed facade: exposes reads + add, but NO `clear` field.
     // Callers holding a `SemanticModel.symbols` reference cannot desync
@@ -115,6 +166,10 @@ export const createSemanticModel = () => {
         methods,
         fields,
         symbols,
+        get scopes() {
+            return attachedScopes;
+        },
         clear: cascadeClear,
+        attachScopeIndexes,
     };
 };

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

@@ -32,30 +32,46 @@ function buildAdjacency(graph) {
     const methodMap = new Map();
     // Track which edge type each parent link came from
     const parentEdgeType = new Map();
-    graph.forEachRelationship((rel) => {
-        if (rel.type === 'EXTENDS' || rel.type === 'IMPLEMENTS') {
-            let parents = parentMap.get(rel.sourceId);
-            if (!parents) {
-                parents = [];
-                parentMap.set(rel.sourceId, parents);
-            }
-            parents.push(rel.targetId);
-            let edgeTypes = parentEdgeType.get(rel.sourceId);
-            if (!edgeTypes) {
-                edgeTypes = new Map();
-                parentEdgeType.set(rel.sourceId, edgeTypes);
-            }
-            edgeTypes.set(rel.targetId, rel.type);
+    // Three typed iterations replace one full-relationship-map scan
+    // with per-edge type checks. Each consumes only the edges of the
+    // type it cares about — see plan
+    // docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 2).
+    for (const rel of graph.iterRelationshipsByType('EXTENDS')) {
+        let parents = parentMap.get(rel.sourceId);
+        if (!parents) {
+            parents = [];
+            parentMap.set(rel.sourceId, parents);
         }
-        if (rel.type === 'HAS_METHOD') {
-            let methods = methodMap.get(rel.sourceId);
-            if (!methods) {
-                methods = [];
-                methodMap.set(rel.sourceId, methods);
-            }
-            methods.push(rel.targetId);
+        parents.push(rel.targetId);
+        let edgeTypes = parentEdgeType.get(rel.sourceId);
+        if (!edgeTypes) {
+            edgeTypes = new Map();
+            parentEdgeType.set(rel.sourceId, edgeTypes);
+        }
+        edgeTypes.set(rel.targetId, 'EXTENDS');
+    }
+    for (const rel of graph.iterRelationshipsByType('IMPLEMENTS')) {
+        let parents = parentMap.get(rel.sourceId);
+        if (!parents) {
+            parents = [];
+            parentMap.set(rel.sourceId, parents);
         }
-    });
+        parents.push(rel.targetId);
+        let edgeTypes = parentEdgeType.get(rel.sourceId);
+        if (!edgeTypes) {
+            edgeTypes = new Map();
+            parentEdgeType.set(rel.sourceId, edgeTypes);
+        }
+        edgeTypes.set(rel.targetId, 'IMPLEMENTS');
+    }
+    for (const rel of graph.iterRelationshipsByType('HAS_METHOD')) {
+        let methods = methodMap.get(rel.sourceId);
+        if (!methods) {
+            methods = [];
+            methodMap.set(rel.sourceId, methods);
+        }
+        methods.push(rel.targetId);
+    }
     return { parentMap, methodMap, parentEdgeType };
 }
 /** Resolve by MRO order — first ancestor in linearized order wins. */

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

@@ -1,6 +1,7 @@
 import { KnowledgeGraph } from '../graph/types.js';
 import type { SymbolTableWriter, ExtractedHeritage } from './model/index.js';
 import { ASTCache } from './ast-cache.js';
+import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
 import type { ExtractedImport, ExtractedCall, ExtractedAssignment, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedToolDef, FileConstructorBindings, FileScopeBindings, ExtractedORMQuery } from './workers/parse-worker.js';
 export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
@@ -16,8 +17,24 @@ export interface WorkerExtractedData {
     ormQueries: ExtractedORMQuery[];
     constructorBindings: FileConstructorBindings[];
     fileScopeBindings: FileScopeBindings[];
+    /**
+     * Per-file `ParsedFile` artifacts from the new scope-based resolution
+     * pipeline (RFC #909 Ring 2). Empty until a provider implements
+     * `emitScopeCaptures` — additive to the legacy DAG path. Aggregated
+     * from every worker chunk; consumed downstream by #921's
+     * finalize-orchestrator.
+     */
+    parsedFiles: ParsedFile[];
 }
 export declare const processParsing: (graph: KnowledgeGraph, files: {
     path: string;
     content: string;
-}[], symbolTable: SymbolTableWriter, astCache: ASTCache, onFileProgress?: FileProgressCallback, workerPool?: WorkerPool) => Promise<WorkerExtractedData | null>;
+}[], symbolTable: SymbolTableWriter, astCache: ASTCache, 
+/**
+ * Persistent tree cache (separate from `astCache`, which the caller
+ * clears between chunks). Sequential parses additionally write the
+ * Tree here so cross-phase consumers (scope-resolution) can read it.
+ * Worker-mode parses skip — Trees can't cross MessageChannels.
+ * Pass `undefined` if no consumer needs cross-phase access.
+ */
+scopeTreeCache: ASTCache | undefined, onFileProgress?: FileProgressCallback, workerPool?: WorkerPool) => Promise<WorkerExtractedData | null>;

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

@@ -5,6 +5,7 @@ import { generateId } from '../../lib/utils.js';
 import { getLanguageFromFilename, SupportedLanguages } from '../../_shared/index.js';
 import { extractVueScript, isVueSetupTopLevel } from './vue-sfc-extractor.js';
 import { yieldToEventLoop } from './utils/event-loop.js';
+import { isVerboseIngestionEnabled } from './utils/verbose.js';
 import { getDefinitionNodeFromCaptures, findEnclosingClassInfo, getLabelFromCaptures, CLASS_CONTAINER_TYPES, } from './utils/ast-helpers.js';
 import { detectFrameworkFromAST } from './framework-detection.js';
 import { buildTypeEnv } from './type-env.js';
@@ -34,6 +35,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
             ormQueries: [],
             constructorBindings: [],
             fileScopeBindings: [],
+            parsedFiles: [],
         };
     const total = files.length;
     // Dispatch to worker pool — pool handles splitting into chunks and sub-batching
@@ -52,6 +54,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
     const allORMQueries = [];
     const allConstructorBindings = [];
     const fileScopeBindingsByFile = [];
+    const allParsedFiles = [];
     for (const result of chunkResults) {
         for (const node of result.nodes) {
             graph.addNode({
@@ -98,6 +101,13 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
         if (result.fileScopeBindings)
             for (const item of result.fileScopeBindings)
                 fileScopeBindingsByFile.push(item);
+        // RFC #909 Ring 2: aggregate per-file scope artifacts. Tolerant of
+        // workers that don't emit the field yet (older worker builds or
+        // partial rollouts), since the additive contract means undefined =
+        // "this worker produced no ParsedFiles for this chunk".
+        if (result.parsedFiles)
+            for (const item of result.parsedFiles)
+                allParsedFiles.push(item);
     }
     // Merge and log skipped languages from workers
     const skippedLanguages = new Map();
@@ -126,6 +136,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
         ormQueries: allORMQueries,
         constructorBindings: allConstructorBindings,
         fileScopeBindings: fileScopeBindingsByFile,
+        parsedFiles: allParsedFiles,
     };
 };
 // ============================================================================
@@ -210,10 +221,11 @@ function seqGetFieldInfo(classNode, provider, context) {
     seqFieldInfoCache.set(cacheKey, cached);
     return cached;
 }
-const processParsingSequential = async (graph, files, symbolTable, astCache, onFileProgress) => {
+const processParsingSequential = async (graph, files, symbolTable, astCache, scopeTreeCache, onFileProgress) => {
     const parser = await loadParser();
     const total = files.length;
-    const skippedLanguages = new Map();
+    const logSkipped = isVerboseIngestionEnabled();
+    const skippedByLang = logSkipped ? new Map() : null;
     for (let i = 0; i < files.length; i++) {
         const file = files[i];
         // Reset memoization before each new file (node refs are per-tree)
@@ -228,9 +240,10 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, onF
         const language = getLanguageFromFilename(file.path);
         if (!language)
             continue;
-        // Skip unsupported languages (e.g. Swift when tree-sitter-swift not installed)
         if (!isLanguageAvailable(language)) {
-            skippedLanguages.set(language, (skippedLanguages.get(language) || 0) + 1);
+            if (skippedByLang) {
+                skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);
+            }
             continue;
         }
         // Skip files larger than the max tree-sitter buffer (32 MB)
@@ -266,6 +279,13 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, onF
         }
         astCache.set(file.path, tree);
         const provider = getProvider(language);
+        // Mirror into the cross-phase cache only when the language has a
+        // scope-resolution consumer — otherwise we retain Trees no one
+        // reads. parse-impl clears `astCache` between chunks;
+        // `scopeTreeCache` survives until scope-resolution disposes it.
+        if (provider.emitScopeCaptures !== undefined) {
+            scopeTreeCache?.set(file.path, tree);
+        }
         const queryString = provider.treeSitterQueries;
         if (!queryString) {
             continue;
@@ -517,18 +537,32 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, onF
             }
         });
     }
-    if (skippedLanguages.size > 0) {
-        const summary = Array.from(skippedLanguages.entries())
-            .map(([lang, count]) => `${lang}: ${count}`)
-            .join(', ');
-        console.warn(`  Skipped unsupported languages: ${summary}`);
+    if (skippedByLang && skippedByLang.size > 0) {
+        for (const [lang, count] of skippedByLang.entries()) {
+            console.warn(`[ingestion] Skipped ${count} ${lang} file(s) in parsing processing — ${lang} parser not available.`);
+        }
     }
 };
 // ============================================================================
 // Public API
 // ============================================================================
-export const processParsing = async (graph, files, symbolTable, astCache, onFileProgress, workerPool) => {
+export const processParsing = async (graph, files, symbolTable, astCache, 
+/**
+ * Persistent tree cache (separate from `astCache`, which the caller
+ * clears between chunks). Sequential parses additionally write the
+ * Tree here so cross-phase consumers (scope-resolution) can read it.
+ * Worker-mode parses skip — Trees can't cross MessageChannels.
+ * Pass `undefined` if no consumer needs cross-phase access.
+ */
+scopeTreeCache, onFileProgress, workerPool) => {
     if (workerPool) {
+        if (scopeTreeCache !== undefined && process.env.PROF_SCOPE_RESOLUTION === '1') {
+            // Trees can't cross MessageChannels, so worker-parsed files land
+            // in scope-resolution with an empty cache and get re-parsed.
+            // Surfacing this in PROF mode prevents silent perf cliffs when
+            // a repo crosses the worker-pool threshold.
+            console.warn(`[scope-resolution prof] worker pool engaged for ${files.length} files — cross-phase tree cache will be empty; scope-resolution re-parses.`);
+        }
         try {
             return await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, onFileProgress);
         }
@@ -537,6 +571,6 @@ export const processParsing = async (graph, files, symbolTable, astCache, onFile
         }
     }
     // Fallback: sequential parsing (no pre-extracted data)
-    await processParsingSequential(graph, files, symbolTable, astCache, onFileProgress);
+    await processParsingSequential(graph, files, symbolTable, astCache, scopeTreeCache, onFileProgress);
     return null;
 };

package/dist/core/ingestion/pipeline-phases/index.d.ts

@@ -13,6 +13,7 @@ export { routesPhase, type RoutesOutput, type RouteEntry } from './routes.js';
 export { toolsPhase, type ToolsOutput, type ToolDef } from './tools.js';
 export { ormPhase, type ORMOutput } from './orm.js';
 export { crossFilePhase, type CrossFileOutput } from './cross-file.js';
+export { scopeResolutionPhase, type ScopeResolutionOutput, } from '../scope-resolution/pipeline/phase.js';
 export { mroPhase, type MROOutput } from './mro.js';
 export { communitiesPhase, type CommunitiesOutput } from './communities.js';
 export { processesPhase, type ProcessesOutput } from './processes.js';

package/dist/core/ingestion/pipeline-phases/index.js

@@ -14,6 +14,7 @@ export { routesPhase } from './routes.js';
 export { toolsPhase } from './tools.js';
 export { ormPhase } from './orm.js';
 export { crossFilePhase } from './cross-file.js';
+export { scopeResolutionPhase, } from '../scope-resolution/pipeline/phase.js';
 export { mroPhase } from './mro.js';
 export { communitiesPhase } from './communities.js';
 export { processesPhase } from './processes.js';

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

@@ -14,6 +14,7 @@
 import { BindingAccumulator } from '../binding-accumulator.js';
 import { type ExportedTypeMap } from '../call-processor.js';
 import { createResolutionContext } from '../model/resolution-context.js';
+import { ASTCache } from '../ast-cache.js';
 import { type PipelineProgress } from '../../../_shared/index.js';
 import type { ExtractedDecoratorRoute, ExtractedFetchCall, ExtractedORMQuery, ExtractedRoute, ExtractedToolDef } from '../workers/parse-worker.js';
 import type { KnowledgeGraph } from '../../graph/types.js';
@@ -44,5 +45,14 @@ export declare function runChunkedParseAndResolve(graph: KnowledgeGraph, scanned
     bindingAccumulator: BindingAccumulator;
     resolutionContext: ReturnType<typeof createResolutionContext>;
     usedWorkerPool: boolean;
+    /** Cross-phase tree-sitter Tree cache populated by the sequential
+     *  parse path. Distinct from the chunk-local `astCache` used inside
+     *  the parse loop (that one is cleared between chunks). Empty when
+     *  every chunk ran via the worker pool (workers can't return native
+     *  tree-sitter Trees across the MessageChannel). Downstream phases
+     *  (scope-resolution) read from this to skip re-parsing the same
+     *  source. See plan
+     *  docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 4). */
+    scopeTreeCache: ASTCache;
 }>;
 export {};

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

@@ -126,9 +126,18 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         }
     }
     let filesParsedSoFar = 0;
-    // AST cache sized for one chunk (sequential fallback uses it for import/call/heritage)
+    // Two caches with different lifetimes:
+    //   - `astCache` (chunk-local, cleared between chunks) — call /
+    //     heritage / import processors read it during parse to avoid
+    //     re-parsing within the same chunk.
+    //   - `scopeTreeCache` (total-parseable-sized, never cleared by
+    //     parse-impl) — exposed via ParseOutput so scope-resolution can
+    //     skip a second tree-sitter parse. Worker-mode parses don't
+    //     populate either; consumers fall back to a fresh parse.
+    // See plan docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 4).
     const maxChunkFiles = chunks.reduce((max, c) => Math.max(max, c.length), 0);
     let astCache = createASTCache(maxChunkFiles);
+    const scopeTreeCache = createASTCache(Math.max(parseableScanned.length, 1));
     // Build import resolution context once — suffix index, file lists, resolve cache.
     const importCtx = buildImportResolutionContext(allPaths);
     const allPathObjects = allPaths.map((p) => ({ path: p }));
@@ -161,7 +170,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             const chunkFiles = chunkPaths
                 .filter((p) => chunkContents.has(p))
                 .map((p) => ({ path: p, content: chunkContents.get(p) }));
-            const chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, (current, _total, filePath) => {
+            const chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, scopeTreeCache, (current, _total, filePath) => {
                 const globalCurrent = filesParsedSoFar + current;
                 const parsingProgress = 20 + (globalCurrent / totalParseable) * 62;
                 onProgress({
@@ -439,5 +448,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         // sequential fallback handled every chunk (either due to `skipWorkers`,
         // the file-count/byte thresholds, or a pool-creation failure).
         usedWorkerPool: workerPool !== undefined,
+        // Surface the persistent scope cache so downstream phases
+        // (scope-resolution) can skip re-parsing files that the
+        // sequential path already parsed. Survives chunk boundaries; the
+        // chunk-local `astCache` above is intentionally NOT exposed
+        // because parse-impl clears it between chunks.
+        scopeTreeCache,
     };
 }

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

@@ -19,6 +19,7 @@ import type { PipelinePhase } from './types.js';
 import type { BindingAccumulator } from '../binding-accumulator.js';
 import type { ExtractedFetchCall, ExtractedRoute, ExtractedDecoratorRoute, ExtractedToolDef, ExtractedORMQuery } from '../workers/parse-worker.js';
 import type { createResolutionContext } from '../model/resolution-context.js';
+import type { ASTCache } from '../ast-cache.js';
 export interface ParseOutput {
     /**
      * Read-only snapshot of exported type bindings keyed by file path.
@@ -52,5 +53,22 @@ export interface ParseOutput {
      * see `PipelineOptions.workerThresholdsForTest`.
      */
     readonly usedWorkerPool: boolean;
+    /**
+     * Cross-phase tree-sitter Tree cache populated by the sequential
+     * parse path. Separate from the chunk-local `astCache` used *inside*
+     * the parse phase (which is cleared between chunks) — this one
+     * survives the whole phase and hands Trees to scope-resolution so
+     * it can skip a second parse.
+     *
+     * Empty entries for files that ran through the worker pool
+     * (workers can't return native tree-sitter Trees across the
+     * MessageChannel). Cache miss is safe — consumers fall back to a
+     * fresh parse. See plan
+     * docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 4).
+     *
+     * Disposed by `scopeResolutionPhase` (the sole consumer) via
+     * `scopeTreeCache.clear()` after its extract loop finishes.
+     */
+    readonly scopeTreeCache: ASTCache;
 }
 export declare const parsePhase: PipelinePhase<ParseOutput>;

package/dist/core/ingestion/pipeline.js

@@ -15,7 +15,7 @@
  * See ARCHITECTURE.md for the full phase dependency diagram.
  */
 import { createKnowledgeGraph } from '../graph/graph.js';
-import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, mroPhase, communitiesPhase, processesPhase, } from './pipeline-phases/index.js';
+import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, mroPhase, communitiesPhase, processesPhase, } from './pipeline-phases/index.js';
 // ── Phase registry ─────────────────────────────────────────────────────────
 /**
  * All pipeline phases with their dependency relationships.
@@ -39,6 +39,7 @@ function buildPhaseList(options) {
         toolsPhase,
         ormPhase,
         crossFilePhase,
+        scopeResolutionPhase,
     ];
     if (!options?.skipGraphPhases) {
         phases.push(mroPhase, communitiesPhase, processesPhase);