gitnexus 1.6.3-rc.9 → 1.6.3

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

@@ -0,0 +1,130 @@
+/**
+ * Phase: scopeResolution
+ *
+ * Generic registry-primary resolution phase (RFC #909 Ring 3).
+ *
+ * For every language in `MIGRATED_LANGUAGES` (per-language flag set)
+ * whose provider is registered in `SCOPE_RESOLVERS`:
+ *   1. Filter scanned files by language extension.
+ *   2. Read file contents.
+ *   3. Drive the scope-based pipeline end-to-end via the generic
+ *      `runScopeResolution(input, provider)` orchestrator.
+ *   4. Emit IMPORTS / CALLS / ACCESSES / INHERITS / USES edges.
+ *
+ * Pairs with the per-language gates in `import-processor.ts` and
+ * `call-processor.ts` that skip files when their language is registry-
+ * primary, so we don't double-emit edges from both code paths.
+ *
+ * Adding a language is two changes:
+ *   - Implement `ScopeResolver` in `languages/<lang>/scope-resolver.ts`
+ *     and register it in `scope-resolution/pipeline/registry.ts`.
+ *   - Add the language to `MIGRATED_LANGUAGES` in
+ *     `registry-primary-flag.ts`.
+ *
+ * @deps    parse  (needs Symbol nodes already in the graph so emit-references
+ *                  can attach edges to existing Function/Method/Class nodes)
+ * @reads   scannedFiles
+ * @writes  graph (IMPORTS, CALLS, ACCESSES, INHERITS, USES)
+ */
+import { getPhaseOutput } from '../../pipeline-phases/types.js';
+import { isRegistryPrimary } from '../../registry-primary-flag.js';
+import { getLanguageFromFilename } from '../../../../_shared/index.js';
+import { readFileContents } from '../../filesystem-walker.js';
+import { runScopeResolution } from './run.js';
+import { SCOPE_RESOLVERS } from './registry.js';
+import { isDev } from '../../utils/env.js';
+const NOOP_OUTPUT = Object.freeze({
+    ran: false,
+    filesProcessed: 0,
+    importsEmitted: 0,
+    referenceEdgesEmitted: 0,
+    perLanguage: new Map(),
+});
+export const scopeResolutionPhase = {
+    name: 'scopeResolution',
+    // Depends on `parse` because emit-references attaches edges to
+    // already-existing Symbol nodes (Function/Method/Class). The legacy
+    // `parse` phase still creates those nodes; we only replace the
+    // import + call resolution layer.
+    //
+    // Also depends on `crossFile` — we don't read crossFile's output
+    // directly (we have our own cross-file resolution), but crossFile
+    // writes EXTENDS edges that `buildMro` consumes via
+    // `iterRelationshipsByType('EXTENDS')`. Declaring the dep pins the
+    // ordering explicitly: without it, Kahn's runner could schedule
+    // scopeResolution before crossFile (both unblock after parse), and
+    // the MRO walk would miss heritage edges crossFile later adds.
+    deps: ['parse', 'crossFile', 'structure'],
+    async execute(ctx, deps) {
+        const { scannedFiles } = getPhaseOutput(deps, 'structure');
+        // Reach into the parse phase's AST cache so per-file extract can
+        // skip a second tree-sitter parse. Cache miss is safe (re-parses).
+        // Worker-mode parses leave the cache empty for those files; they
+        // also fall back to a fresh parse — no correctness impact.
+        const parseOutput = getPhaseOutput(deps, 'parse');
+        const { scopeTreeCache, resolutionContext } = parseOutput;
+        // SemanticModel populated during `parse`: scope-resolution consumes
+        // TypeRegistry / MethodRegistry / SymbolTable lookups instead of
+        // rebuilding parallel indexes. See ARCHITECTURE.md § "Semantic-model
+        // source of truth".
+        const model = resolutionContext.model;
+        let totalFiles = 0;
+        let totalImports = 0;
+        let totalRefs = 0;
+        let anyRan = false;
+        const perLanguage = new Map();
+        for (const [lang, provider] of SCOPE_RESOLVERS) {
+            if (!isRegistryPrimary(lang))
+                continue;
+            const langFiles = scannedFiles.filter((f) => getLanguageFromFilename(f.path) === lang);
+            if (langFiles.length === 0)
+                continue;
+            const filePaths = langFiles.map((f) => f.path);
+            const contents = await readFileContents(ctx.repoPath, filePaths);
+            const files = [];
+            for (const fp of filePaths) {
+                const content = contents.get(fp);
+                if (content !== undefined)
+                    files.push({ path: fp, content });
+            }
+            const stats = runScopeResolution({
+                graph: ctx.graph,
+                model,
+                files,
+                treeCache: scopeTreeCache,
+                onWarn: (msg) => {
+                    if (isDev)
+                        console.warn(`[scope-resolution:${lang}] ${msg}`);
+                },
+            }, provider);
+            anyRan = true;
+            totalFiles += stats.filesProcessed;
+            totalImports += stats.importsEmitted;
+            totalRefs += stats.referenceEdgesEmitted;
+            perLanguage.set(lang, {
+                filesProcessed: stats.filesProcessed,
+                importsEmitted: stats.importsEmitted,
+                referenceEdgesEmitted: stats.referenceEdgesEmitted,
+            });
+            if (isDev) {
+                console.log(`[scope-resolution:${lang}] ${stats.filesProcessed} files → ${stats.importsEmitted} IMPORTS + ${stats.referenceEdgesEmitted} reference edges (${stats.resolve.unresolved} unresolved sites, ${stats.referenceSkipped} skipped)`);
+            }
+        }
+        // Dispose the cross-phase Tree cache — scope-resolution is the
+        // only consumer. Holding Trees past this point is pure memory
+        // pressure: downstream phases (mro, community, csv-generator)
+        // never read them, and tree-sitter Trees hold native-heap memory
+        // under WASM runtimes. ASTCache.clear() fires the LRU dispose
+        // handler which calls tree.delete?.() on each retained Tree.
+        scopeTreeCache.clear();
+        if (!anyRan)
+            return NOOP_OUTPUT;
+        return {
+            ran: true,
+            filesProcessed: totalFiles,
+            importsEmitted: totalImports,
+            referenceEdgesEmitted: totalRefs,
+            perLanguage,
+        };
+    },
+};

package/dist/core/ingestion/scope-resolution/pipeline/reconcile-ownership.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Reconcile scope-resolution's ownership view into the SemanticModel.
+ *
+ * For migrated languages (Python in particular) the legacy `parse` phase
+ * emits class-body callables without `ownerId` because
+ * `parsing-processor`'s `resolveEnclosingOwner` is language-dependent and
+ * not every extractor carries the enclosing-class info at parse time.
+ * Scope-resolution later calls `provider.populateOwners(parsed)`, which
+ * stamps the correct `ownerId` onto `parsed.localDefs[i]`. This pass
+ * mirrors those corrections into `model.methods` and `model.fields` so
+ * downstream passes can consult `SemanticModel` as the single
+ * authoritative owner-keyed index — no parallel scope-resolution
+ * registry is needed.
+ *
+ * ## Single-source-of-truth invariant (I9)
+ *
+ * After this pass runs, every `def in parsed.localDefs` with a non-
+ * undefined `ownerId` is reachable via either:
+ *   - `model.methods.lookupAllByOwner(ownerId, simpleName)` — if the
+ *     def is a Method / Function / Constructor, OR
+ *   - `model.fields.lookupFieldByOwner(ownerId, simpleName)` — if the
+ *     def is a Property / Variable.
+ *
+ * This invariant is the foundation of Contract Invariant I9
+ * (`contract/scope-resolver.ts`): scope-resolution passes MUST read
+ * symbol-keyed lookups exclusively from `SemanticModel`.
+ *
+ * ## Idempotency
+ *
+ * The pass skips registration when `(ownerId, simpleName)` already
+ * contains a def with matching `nodeId`. Safe to call multiple times
+ * or after a language whose legacy extractor does populate `ownerId`
+ * (C#) — no duplicates are introduced.
+ *
+ * ## Transitional shim
+ *
+ * This reconciliation pass is an explicit shim. The architectural end
+ * state is for the legacy extractor to emit the correct `ownerId` for
+ * every language at parse time, removing the need for a second pass.
+ * See ARCHITECTURE.md § "Semantic-model source of truth" for the
+ * follow-up plan.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { MutableSemanticModel, SemanticModel } from '../../model/semantic-model.js';
+export interface ReconcileStats {
+    /** Method/Function/Constructor defs registered into MethodRegistry. */
+    readonly methodsRegistered: number;
+    /** Property/Variable defs registered into FieldRegistry. */
+    readonly fieldsRegistered: number;
+    /** Defs already present (idempotent skip). */
+    readonly skippedAlreadyPresent: number;
+}
+export declare function reconcileOwnership(parsedFiles: readonly ParsedFile[], model: MutableSemanticModel): ReconcileStats;
+/**
+ * Debug-mode parity validator. Runs only when
+ * `VALIDATE_SEMANTIC_MODEL !== '0'` AND `NODE_ENV !== 'production'`.
+ *
+ * Iterates every def in `parsedFiles[i].localDefs` with an `ownerId`
+ * and asserts it is reachable via `model.methods.lookupAllByOwner` or
+ * `model.fields.lookupFieldByOwner`. On mismatch: emits a warning via
+ * `onWarn` — never throws, mirroring the pipeline's soft-fail posture.
+ *
+ * This is the enforcement of Contract Invariant I9 at runtime. In
+ * production it is a no-op; in development it surfaces drift between
+ * `parsed.localDefs` and `SemanticModel` that would otherwise silently
+ * produce wrong edges.
+ */
+export declare function validateOwnershipParity(parsedFiles: readonly ParsedFile[], model: SemanticModel, onWarn: (message: string) => void): number;

package/dist/core/ingestion/scope-resolution/pipeline/reconcile-ownership.js

@@ -0,0 +1,125 @@
+/**
+ * Reconcile scope-resolution's ownership view into the SemanticModel.
+ *
+ * For migrated languages (Python in particular) the legacy `parse` phase
+ * emits class-body callables without `ownerId` because
+ * `parsing-processor`'s `resolveEnclosingOwner` is language-dependent and
+ * not every extractor carries the enclosing-class info at parse time.
+ * Scope-resolution later calls `provider.populateOwners(parsed)`, which
+ * stamps the correct `ownerId` onto `parsed.localDefs[i]`. This pass
+ * mirrors those corrections into `model.methods` and `model.fields` so
+ * downstream passes can consult `SemanticModel` as the single
+ * authoritative owner-keyed index — no parallel scope-resolution
+ * registry is needed.
+ *
+ * ## Single-source-of-truth invariant (I9)
+ *
+ * After this pass runs, every `def in parsed.localDefs` with a non-
+ * undefined `ownerId` is reachable via either:
+ *   - `model.methods.lookupAllByOwner(ownerId, simpleName)` — if the
+ *     def is a Method / Function / Constructor, OR
+ *   - `model.fields.lookupFieldByOwner(ownerId, simpleName)` — if the
+ *     def is a Property / Variable.
+ *
+ * This invariant is the foundation of Contract Invariant I9
+ * (`contract/scope-resolver.ts`): scope-resolution passes MUST read
+ * symbol-keyed lookups exclusively from `SemanticModel`.
+ *
+ * ## Idempotency
+ *
+ * The pass skips registration when `(ownerId, simpleName)` already
+ * contains a def with matching `nodeId`. Safe to call multiple times
+ * or after a language whose legacy extractor does populate `ownerId`
+ * (C#) — no duplicates are introduced.
+ *
+ * ## Transitional shim
+ *
+ * This reconciliation pass is an explicit shim. The architectural end
+ * state is for the legacy extractor to emit the correct `ownerId` for
+ * every language at parse time, removing the need for a second pass.
+ * See ARCHITECTURE.md § "Semantic-model source of truth" for the
+ * follow-up plan.
+ */
+import { simpleQualifiedName } from '../graph-bridge/ids.js';
+export function reconcileOwnership(parsedFiles, model) {
+    let methodsRegistered = 0;
+    let fieldsRegistered = 0;
+    let skippedAlreadyPresent = 0;
+    for (const parsed of parsedFiles) {
+        for (const def of parsed.localDefs) {
+            const ownerId = def.ownerId;
+            if (ownerId === undefined)
+                continue;
+            const simple = simpleQualifiedName(def);
+            if (simple === undefined)
+                continue;
+            if (def.type === 'Method' || def.type === 'Function' || def.type === 'Constructor') {
+                const existing = model.methods.lookupAllByOwner(ownerId, simple);
+                if (existing.some((e) => e.nodeId === def.nodeId)) {
+                    skippedAlreadyPresent++;
+                    continue;
+                }
+                model.methods.register(ownerId, simple, def);
+                methodsRegistered++;
+            }
+            else if (def.type === 'Property' || def.type === 'Variable') {
+                const existing = model.fields.lookupFieldByOwner(ownerId, simple);
+                if (existing !== undefined && existing.nodeId === def.nodeId) {
+                    skippedAlreadyPresent++;
+                    continue;
+                }
+                model.fields.register(ownerId, simple, def);
+                fieldsRegistered++;
+            }
+        }
+    }
+    return { methodsRegistered, fieldsRegistered, skippedAlreadyPresent };
+}
+/**
+ * Debug-mode parity validator. Runs only when
+ * `VALIDATE_SEMANTIC_MODEL !== '0'` AND `NODE_ENV !== 'production'`.
+ *
+ * Iterates every def in `parsedFiles[i].localDefs` with an `ownerId`
+ * and asserts it is reachable via `model.methods.lookupAllByOwner` or
+ * `model.fields.lookupFieldByOwner`. On mismatch: emits a warning via
+ * `onWarn` — never throws, mirroring the pipeline's soft-fail posture.
+ *
+ * This is the enforcement of Contract Invariant I9 at runtime. In
+ * production it is a no-op; in development it surfaces drift between
+ * `parsed.localDefs` and `SemanticModel` that would otherwise silently
+ * produce wrong edges.
+ */
+export function validateOwnershipParity(parsedFiles, model, onWarn) {
+    if (process.env.NODE_ENV === 'production')
+        return 0;
+    if (process.env.VALIDATE_SEMANTIC_MODEL === '0')
+        return 0;
+    let mismatches = 0;
+    for (const parsed of parsedFiles) {
+        for (const def of parsed.localDefs) {
+            const ownerId = def.ownerId;
+            if (ownerId === undefined)
+                continue;
+            const simple = simpleQualifiedName(def);
+            if (simple === undefined)
+                continue;
+            if (def.type === 'Method' || def.type === 'Function' || def.type === 'Constructor') {
+                const found = model.methods.lookupAllByOwner(ownerId, simple);
+                if (!found.some((d) => d.nodeId === def.nodeId)) {
+                    onWarn(`semantic-model parity: ${def.type} ${def.nodeId} (${parsed.filePath}) ` +
+                        `owned by ${ownerId} as "${simple}" not in MethodRegistry`);
+                    mismatches++;
+                }
+            }
+            else if (def.type === 'Property' || def.type === 'Variable') {
+                const found = model.fields.lookupFieldByOwner(ownerId, simple);
+                if (found === undefined || found.nodeId !== def.nodeId) {
+                    onWarn(`semantic-model parity: ${def.type} ${def.nodeId} (${parsed.filePath}) ` +
+                        `owned by ${ownerId} as "${simple}" not in FieldRegistry`);
+                    mismatches++;
+                }
+            }
+        }
+    }
+    return mismatches;
+}

package/dist/core/ingestion/scope-resolution/pipeline/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-language `ScopeResolver` registry — the lookup the generic
+ * `scopeResolutionPhase` uses to pick the right resolver for each
+ * migrated language.
+ *
+ * Adding a language is two lines: implement a `ScopeResolver` in
+ * `languages/<lang>/scope-resolver.ts` and register it here. The
+ * phase picks it up automatically — no workflow changes, no
+ * per-language pipeline phase file.
+ */
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import type { ScopeResolver } from '../contract/scope-resolver.js';
+/** Map of `SupportedLanguages` → `ScopeResolver`. The phase iterates
+ *  this map intersected with `MIGRATED_LANGUAGES` (the per-language
+ *  flag set) so adding a resolver here without flipping the flag is
+ *  safe — the resolver sits idle until the language is migrated. */
+export declare const SCOPE_RESOLVERS: ReadonlyMap<SupportedLanguages, ScopeResolver>;

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

@@ -0,0 +1,21 @@
+/**
+ * Per-language `ScopeResolver` registry — the lookup the generic
+ * `scopeResolutionPhase` uses to pick the right resolver for each
+ * migrated language.
+ *
+ * Adding a language is two lines: implement a `ScopeResolver` in
+ * `languages/<lang>/scope-resolver.ts` and register it here. The
+ * phase picks it up automatically — no workflow changes, no
+ * per-language pipeline phase file.
+ */
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import { pythonScopeResolver } from '../../languages/python/scope-resolver.js';
+import { csharpScopeResolver } from '../../languages/csharp/scope-resolver.js';
+/** Map of `SupportedLanguages` → `ScopeResolver`. The phase iterates
+ *  this map intersected with `MIGRATED_LANGUAGES` (the per-language
+ *  flag set) so adding a resolver here without flipping the flag is
+ *  safe — the resolver sits idle until the language is migrated. */
+export const SCOPE_RESOLVERS = new Map([
+    [SupportedLanguages.Python, pythonScopeResolver],
+    [SupportedLanguages.CSharp, csharpScopeResolver],
+]);

package/dist/core/ingestion/scope-resolution/pipeline/run.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `runScopeResolution` — generic registry-primary resolution
+ * orchestrator.
+ *
+ *     ParsedFile[]  (one per file via `extractParsedFile`)
+ *        │  finalizeScopeModel(  + provider hooks adapted to FinalizeHooks)
+ *        ▼
+ *     ScopeResolutionIndexes
+ *        │  resolveReferenceSites
+ *        ▼
+ *     ReferenceIndex
+ *        │  emitReceiverBoundCalls (FIRST — see Contract Invariant I1)
+ *        │  emitFreeCallFallback   (THEN)
+ *        │  emitReferencesViaLookup (LAST — uses handledSites)
+ *        │  emitImportEdges
+ *        ▼
+ *     KnowledgeGraph
+ *
+ * Per-language entry points (e.g. `runPythonScopeResolution` in
+ * `languages/python/scope-resolver.ts`) construct an `ScopeResolver` and
+ * delegate here.
+ *
+ * Plan: `docs/plans/2026-04-20-001-refactor-emit-pipeline-generalization-plan.md`.
+ */
+import type { KnowledgeGraph } from '../../../graph/types.js';
+import type { MutableSemanticModel } from '../../model/semantic-model.js';
+import { type ResolveStats } from '../../resolve-references.js';
+import type { ScopeResolver } from '../contract/scope-resolver.js';
+interface RunScopeResolutionInput {
+    readonly graph: KnowledgeGraph;
+    /**
+     * Semantic model populated by the legacy `parse` phase. Scope-
+     * resolution consumes its `TypeRegistry` / `MethodRegistry` /
+     * `SymbolTable` lookups instead of rebuilding parallel indexes from
+     * `ParsedFile[]`. See ARCHITECTURE.md § "Semantic-model source of
+     * truth". Tests that invoke `runScopeResolution` in isolation pass a
+     * freshly-created `MutableSemanticModel` populated from the same
+     * `ParsedFile[]` to mirror the pipeline shape.
+     */
+    readonly model: MutableSemanticModel;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly onWarn?: (message: string) => void;
+    /**
+     * Optional pre-parsed-Tree lookup keyed by file path. When the
+     * pipeline's parse phase ran sequentially, it populated an
+     * `ASTCache`; passing that here lets the per-file extract step
+     * skip a second `tree-sitter parser.parse(...)` call. Cache miss
+     * is safe — falls back to a fresh parse inside the provider.
+     */
+    readonly treeCache?: {
+        get(filePath: string): unknown;
+    };
+}
+interface RunScopeResolutionStats {
+    readonly filesProcessed: number;
+    readonly filesSkipped: number;
+    readonly importsEmitted: number;
+    readonly resolve: ResolveStats;
+    readonly referenceEdgesEmitted: number;
+    readonly referenceSkipped: number;
+}
+export declare function runScopeResolution(input: RunScopeResolutionInput, provider: ScopeResolver): RunScopeResolutionStats;
+export {};

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

@@ -0,0 +1,157 @@
+/**
+ * `runScopeResolution` — generic registry-primary resolution
+ * orchestrator.
+ *
+ *     ParsedFile[]  (one per file via `extractParsedFile`)
+ *        │  finalizeScopeModel(  + provider hooks adapted to FinalizeHooks)
+ *        ▼
+ *     ScopeResolutionIndexes
+ *        │  resolveReferenceSites
+ *        ▼
+ *     ReferenceIndex
+ *        │  emitReceiverBoundCalls (FIRST — see Contract Invariant I1)
+ *        │  emitFreeCallFallback   (THEN)
+ *        │  emitReferencesViaLookup (LAST — uses handledSites)
+ *        │  emitImportEdges
+ *        ▼
+ *     KnowledgeGraph
+ *
+ * Per-language entry points (e.g. `runPythonScopeResolution` in
+ * `languages/python/scope-resolver.ts`) construct an `ScopeResolver` and
+ * delegate here.
+ *
+ * Plan: `docs/plans/2026-04-20-001-refactor-emit-pipeline-generalization-plan.md`.
+ */
+import { reconcileOwnership, validateOwnershipParity } from './reconcile-ownership.js';
+import { extractParsedFile } from '../../scope-extractor-bridge.js';
+import { finalizeScopeModel } from '../../finalize-orchestrator.js';
+import { resolveReferenceSites } from '../../resolve-references.js';
+import { buildGraphNodeLookup } from '../graph-bridge/node-lookup.js';
+import { buildPopulatedMethodDispatch } from '../graph-bridge/method-dispatch.js';
+import { propagateImportedReturnTypes } from '../passes/imported-return-types.js';
+import { emitReceiverBoundCalls } from '../passes/receiver-bound-calls.js';
+import { emitFreeCallFallback } from '../passes/free-call-fallback.js';
+import { emitReferencesViaLookup } from '../graph-bridge/references-to-edges.js';
+import { emitImportEdges } from '../graph-bridge/imports-to-edges.js';
+import { buildWorkspaceResolutionIndex } from '../workspace-index.js';
+export function runScopeResolution(input, provider) {
+    const { graph, files } = input;
+    const onWarn = input.onWarn ?? (() => { });
+    const PROF = process.env.PROF_SCOPE_RESOLUTION === '1';
+    const tStart = PROF ? process.hrtime.bigint() : 0n;
+    // ── Phase 1: extract each file → ParsedFile ────────────────────────────
+    const parsedFiles = [];
+    let filesSkipped = 0;
+    const treeCache = input.treeCache;
+    for (const file of files) {
+        const cachedTree = treeCache?.get(file.path);
+        const parsed = extractParsedFile(provider.languageProvider, file.content, file.path, onWarn, cachedTree);
+        if (parsed === undefined) {
+            filesSkipped++;
+            continue;
+        }
+        provider.populateOwners(parsed);
+        parsedFiles.push(parsed);
+    }
+    // Reconcile scope-resolution's ownership view into the SemanticModel.
+    // See `reconcile-ownership.ts` for the full rationale (Contract
+    // Invariant I9). Debug-mode validator runs immediately after to
+    // catch drift between `parsed.localDefs` and the registries.
+    //
+    // PHASE BOUNDARY: `input.model` is `MutableSemanticModel` up to this
+    // point (write phase: reconciliation). After this line no further
+    // writes are expected — downstream passes consume `readonlyModel`
+    // (narrowed to `SemanticModel`) so accidental writes would surface
+    // as type errors.
+    reconcileOwnership(parsedFiles, input.model);
+    validateOwnershipParity(parsedFiles, input.model, onWarn);
+    const readonlyModel = input.model;
+    if (parsedFiles.length === 0) {
+        return {
+            filesProcessed: 0,
+            filesSkipped,
+            importsEmitted: 0,
+            resolve: { sitesProcessed: 0, referencesEmitted: 0, unresolved: 0 },
+            referenceEdgesEmitted: 0,
+            referenceSkipped: 0,
+        };
+    }
+    const tExtract = PROF ? process.hrtime.bigint() : 0n;
+    // ── Phase 2: finalize → ScopeResolutionIndexes ─────────────────────────
+    const allFilePaths = new Set(parsedFiles.map((f) => f.filePath));
+    const nodeLookup = buildGraphNodeLookup(graph);
+    const mroByClassDefId = provider.buildMro(graph, parsedFiles, nodeLookup);
+    const finalized = finalizeScopeModel(parsedFiles, {
+        hooks: {
+            resolveImportTarget: (targetRaw, fromFile) => provider.resolveImportTarget(targetRaw, fromFile, allFilePaths),
+            mergeBindings: (existing, incoming, scopeId) => provider.mergeBindings(existing, incoming, scopeId),
+        },
+    });
+    // Replace the empty MethodDispatchIndex that finalizeScopeModel
+    // builds by design with the populated one derived from the
+    // language's MRO. Spread produces a fresh `ScopeResolutionIndexes`
+    // instead of mutating the finalized result through an `as` cast —
+    // downstream passes get an object whose readonly guarantees match
+    // the type system.
+    const indexes = {
+        ...finalized,
+        methodDispatch: buildPopulatedMethodDispatch(mroByClassDefId),
+    };
+    // Build the workspace resolution index ONCE — scope-valued lookups
+    // (`classScopeByDefId`, `moduleScopeByFile`) that `SemanticModel`
+    // cannot carry. Must run AFTER `populateOwners` (so owned defs are
+    // attributed correctly) and AFTER finalize (so module-scope
+    // bindings are available).
+    const workspaceIndex = buildWorkspaceResolutionIndex(parsedFiles);
+    // Cross-file implicit-namespace visibility (C#). Must run before
+    // propagateImportedReturnTypes so the latter pass sees siblings'
+    // class bindings when chasing return-type chains across files.
+    if (provider.populateNamespaceSiblings !== undefined) {
+        const fileContents = new Map();
+        for (const f of files)
+            fileContents.set(f.path, f.content);
+        provider.populateNamespaceSiblings(parsedFiles, indexes, {
+            fileContents,
+            treeCache,
+        });
+    }
+    // Cross-file return-type propagation (Contract Invariant I3 timing:
+    // after finalize, before resolve).
+    if (provider.propagatesReturnTypesAcrossImports !== false) {
+        propagateImportedReturnTypes(parsedFiles, indexes, workspaceIndex);
+    }
+    const tFinalize = PROF ? process.hrtime.bigint() : 0n;
+    // ── Phase 3: resolve references via Registry.lookup ────────────────────
+    const registryProviders = {
+        arityCompatibility: provider.arityCompatibility,
+    };
+    const { referenceIndex, stats: resolveStats } = resolveReferenceSites({
+        scopes: indexes,
+        providers: registryProviders,
+    });
+    const tResolve = PROF ? process.hrtime.bigint() : 0n;
+    // ── Phase 4: emit graph edges (LOAD-BEARING ORDER — see I1) ────────────
+    const handledSites = new Set();
+    const receiverExtras = emitReceiverBoundCalls(graph, indexes, parsedFiles, nodeLookup, handledSites, provider, workspaceIndex, readonlyModel);
+    const freeCallExtras = emitFreeCallFallback(graph, indexes, parsedFiles, nodeLookup, referenceIndex, handledSites, readonlyModel, workspaceIndex);
+    const { emitted, skipped } = emitReferencesViaLookup(graph, indexes, referenceIndex, nodeLookup, handledSites);
+    const importsEmitted = emitImportEdges(graph, indexes.imports, indexes.scopeTree, provider.importEdgeReason);
+    if (PROF) {
+        const tEnd = process.hrtime.bigint();
+        const ns = (a, b) => Number(b - a) / 1_000_000;
+        console.warn(`[scope-resolution prof] extract=${ns(tStart, tExtract).toFixed(0)}ms` +
+            ` finalize+propagate=${ns(tExtract, tFinalize).toFixed(0)}ms` +
+            ` resolve=${ns(tFinalize, tResolve).toFixed(0)}ms` +
+            ` emit=${ns(tResolve, tEnd).toFixed(0)}ms` +
+            ` total=${ns(tStart, tEnd).toFixed(0)}ms` +
+            ` (${parsedFiles.length} files)`);
+    }
+    return {
+        filesProcessed: parsedFiles.length,
+        filesSkipped,
+        importsEmitted,
+        resolve: resolveStats,
+        referenceEdgesEmitted: emitted + receiverExtras + freeCallExtras,
+        referenceSkipped: skipped,
+    };
+}

package/dist/core/ingestion/scope-resolution/scope/namespace-targets.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Build a per-file `localName → targetFilePath` map over the file's
+ * module-scope namespace-kind import edges.
+ *
+ * Namespace imports (`import X`, `import X as Y`) bind a name that can
+ * appear as a receiver in member calls (`X.foo()`, `Y.foo()`). Named
+ * imports (`from X import foo`) bind `foo` directly and are a different
+ * resolution path.
+ *
+ * Why not consult `scope.bindings` directly? For namespace imports
+ * where the target module has no self-named def,
+ * `finalize-algorithm.ts:540` skips binding creation entirely, so
+ * `scope.bindings.get('X')` returns undefined. We iterate
+ * `indexes.imports` to recover those targets.
+ *
+ * Next-consumer contract: any language with namespace-style imports
+ * (TypeScript `import * as X`, Java static import, Ruby `require`)
+ * uses this directly. `ParsedImport.kind === 'namespace'` is the
+ * cross-language hook.
+ *
+ * Scope-chain concern (verified 2026-04-21): `pythonImportOwningScope`
+ * documents that function-local and class-body imports bind to the
+ * inner scope, which would make a module-only read incomplete. In
+ * practice `finalize-algorithm` places ALL of a file's ImportEdges
+ * onto `indexes.imports[moduleScope]` regardless of where the
+ * `import` statement appears — the integration fixtures
+ * `python-function-local-namespace-import` and
+ * `python-class-body-namespace-import` both emit correct CALLS edges
+ * with reason "namespace-receiver", demonstrating that the module-
+ * scope read is sufficient today. If finalize routing ever changes to
+ * honor the hook's per-scope contract, this function must walk the
+ * reference-site scope chain (mirror `findExportedDefByName`).
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+export declare function collectNamespaceTargets(parsed: ParsedFile, scopes: ScopeResolutionIndexes): Map<string, string>;