gitnexus 1.6.3-rc.8 → 1.6.3

package/dist/core/ingestion/scope-resolution/passes/compound-receiver.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolve a compound-receiver expression's TYPE — `user.address.save()`,
+ * `svc.get_user().save()`, `c.greet().save()` — to the class def of
+ * the value the receiver expression produces.
+ *
+ * Three shapes (parsed C-family-style):
+ *   - bare identifier `name` — look up via typeBinding chain
+ *   - dotted `obj.field[.field]…` — walk fields via class-scope typeBindings
+ *   - call `expr.method()` — recurse into expr, find method's return-type
+ *     typeBinding on its class, resolve to a class
+ *
+ * **Field-fallback heuristic** (Phase-9C "unified fixpoint"): when the
+ * receiver class has no `methodName`, walk its fields and try the
+ * lookup on each field's type. Useful for dynamically-typed languages
+ * (Python). Strictly-typed languages should pass
+ * `fieldFallbackOnMethodLookup: false` via `ScopeResolver`.
+ *
+ * Generic for any C-family language (`.` member access, `()` call
+ * syntax). Languages with non-C-family syntax (Ruby blocks, COBOL)
+ * either don't trigger the call branch or skip this pass entirely.
+ */
+import type { ScopeId, SymbolDefinition } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import type { WorkspaceResolutionIndex } from '../workspace-index.js';
+interface ResolveCompoundReceiverOptions {
+    /** When true (default), if method lookup fails on the receiver's
+     *  class, walk its fields and try the lookup on each field's class.
+     *  Phase-9C "unified fixpoint" — Python-shaped heuristic. */
+    readonly fieldFallback?: boolean;
+    /** Language-specific accessor unwrap — `data.Values` on a
+     *  Dictionary<K,V>-typed receiver yields V (C#), etc. Returns the
+     *  element type's simple name, or `undefined` to let the regular
+     *  field-walk handle the access. */
+    readonly unwrapCollectionAccessor?: (receiverType: string, accessor: string) => string | undefined;
+    /** Walk up from the class scope to ancestor (Module) scopes when
+     *  looking up a method's return-type typeBinding. Only enable for
+     *  languages that hoist return-type bindings to Module scope (C#);
+     *  otherwise we risk picking up unrelated module-level bindings. */
+    readonly hoistTypeBindingsToModule?: boolean;
+}
+export declare function resolveCompoundReceiverClass(receiverText: string, inScope: ScopeId, scopes: ScopeResolutionIndexes, index: WorkspaceResolutionIndex, options?: ResolveCompoundReceiverOptions, depth?: number): SymbolDefinition | undefined;
+export {};

package/dist/core/ingestion/scope-resolution/passes/compound-receiver.js

@@ -0,0 +1,198 @@
+/**
+ * Resolve a compound-receiver expression's TYPE — `user.address.save()`,
+ * `svc.get_user().save()`, `c.greet().save()` — to the class def of
+ * the value the receiver expression produces.
+ *
+ * Three shapes (parsed C-family-style):
+ *   - bare identifier `name` — look up via typeBinding chain
+ *   - dotted `obj.field[.field]…` — walk fields via class-scope typeBindings
+ *   - call `expr.method()` — recurse into expr, find method's return-type
+ *     typeBinding on its class, resolve to a class
+ *
+ * **Field-fallback heuristic** (Phase-9C "unified fixpoint"): when the
+ * receiver class has no `methodName`, walk its fields and try the
+ * lookup on each field's type. Useful for dynamically-typed languages
+ * (Python). Strictly-typed languages should pass
+ * `fieldFallbackOnMethodLookup: false` via `ScopeResolver`.
+ *
+ * Generic for any C-family language (`.` member access, `()` call
+ * syntax). Languages with non-C-family syntax (Ruby blocks, COBOL)
+ * either don't trigger the call branch or skip this pass entirely.
+ */
+import { findClassBindingInScope, findExportedDefByName, findReceiverTypeBinding, } from '../scope/walkers.js';
+/** Max depth for compound-receiver chain resolution (`a().b().c().d()`).
+ *  Practical code rarely exceeds 3-4 hops; the cap prevents
+ *  pathological recursion if the receiver text is malformed. */
+const COMPOUND_RECEIVER_MAX_DEPTH = 4;
+export function resolveCompoundReceiverClass(receiverText, inScope, scopes, index, options = {}, depth = 0) {
+    const classScopeByDefId = index.classScopeByDefId;
+    if (depth > COMPOUND_RECEIVER_MAX_DEPTH)
+        return undefined;
+    const text = receiverText.trim();
+    if (text.length === 0)
+        return undefined;
+    const fieldFallback = options.fieldFallback ?? true;
+    // Bare identifier — resolve via typeBinding then class lookup.
+    if (!text.includes('.') && !text.includes('(')) {
+        const tb = findReceiverTypeBinding(inScope, text, scopes);
+        if (tb === undefined)
+            return undefined;
+        return findClassBindingInScope(tb.declaredAtScope, tb.rawName, scopes);
+    }
+    // Trailing `()` — call expression. Strip it and resolve the function
+    // expression's return type. We only handle the canonical `f()` /
+    // `obj.method()` shape; nested-arg expressions like `f(g())` are
+    // out of scope for V1 (depth-capped recursion catches infinite loops).
+    if (text.endsWith(')')) {
+        const openIdx = matchingOpenParen(text);
+        if (openIdx === -1)
+            return undefined;
+        const fnExpr = text.slice(0, openIdx).trim();
+        if (fnExpr.length === 0)
+            return undefined;
+        const lastDot = fnExpr.lastIndexOf('.');
+        if (lastDot === -1) {
+            // Free call `name()`. Look up function in scope, then its
+            // return-type typeBinding (which lives in the function's
+            // enclosing scope per the language's return-type hoist rule).
+            const fnDef = findExportedDefByName(fnExpr, inScope, scopes, index);
+            if (fnDef === undefined)
+                return undefined;
+            const retType = findReceiverTypeBinding(inScope, fnExpr, scopes);
+            if (retType === undefined)
+                return undefined;
+            return findClassBindingInScope(retType.declaredAtScope, retType.rawName, scopes);
+        }
+        // `obj.method()` — resolve obj's class, look up method's return
+        // type on that class scope (or the MRO).
+        const objExpr = fnExpr.slice(0, lastDot);
+        const methodName = fnExpr.slice(lastDot + 1);
+        const objClass = resolveCompoundReceiverClass(objExpr, inScope, scopes, index, options, depth + 1);
+        if (objClass === undefined)
+            return undefined;
+        let retType;
+        const ownerChain = [objClass.nodeId, ...scopes.methodDispatch.mroFor(objClass.nodeId)];
+        for (const ownerId of ownerChain) {
+            const cs = classScopeByDefId.get(ownerId);
+            const candidate = cs?.typeBindings.get(methodName);
+            if (candidate !== undefined) {
+                retType = candidate;
+                break;
+            }
+            // Fallback: walk up from the class scope looking for a return-
+            // type binding on an ancestor (Module) scope. Gated on
+            // `hoistTypeBindingsToModule` because only languages that hoist
+            // method return-type bindings to Module scope need this path;
+            // enabling it unconditionally would let other languages pick up
+            // unrelated module-level bindings. See contract doc for the
+            // invariant and `propagateImportedReturnTypes` for how the
+            // hoisted bindings originate.
+            if (cs !== undefined && options.hoistTypeBindingsToModule === true) {
+                let curId = cs.parent;
+                while (curId !== null) {
+                    const curScope = scopes.scopeTree.getScope(curId);
+                    if (curScope === undefined)
+                        break;
+                    const cand = curScope.typeBindings.get(methodName);
+                    if (cand !== undefined) {
+                        retType = cand;
+                        break;
+                    }
+                    curId = curScope.parent;
+                }
+                if (retType !== undefined)
+                    break;
+            }
+        }
+        if (retType === undefined && fieldFallback) {
+            const objCs = classScopeByDefId.get(objClass.nodeId);
+            if (objCs !== undefined) {
+                for (const [, fieldType] of objCs.typeBindings) {
+                    const fieldClass = findClassBindingInScope(fieldType.declaredAtScope, fieldType.rawName, scopes);
+                    if (fieldClass === undefined)
+                        continue;
+                    const fcs = classScopeByDefId.get(fieldClass.nodeId);
+                    const candidate = fcs?.typeBindings.get(methodName);
+                    if (candidate !== undefined) {
+                        retType = candidate;
+                        break;
+                    }
+                }
+            }
+        }
+        if (retType === undefined)
+            return undefined;
+        return findClassBindingInScope(retType.declaredAtScope, retType.rawName, scopes);
+    }
+    // Pure dotted access `obj.field[.field]…` — walk fields.
+    const parts = text.split('.');
+    // Language-specific collection-accessor suffix (C#'s `data.Values`
+    // on Dictionary<K,V>, etc.). When the provider hook recognizes
+    // the final segment and unwraps the receiver's generic, return
+    // the element class directly. Resolved before the field-walk
+    // because Dictionary-family types aren't local class defs.
+    if (options.unwrapCollectionAccessor !== undefined && parts.length >= 2) {
+        const last = parts[parts.length - 1];
+        const prefix = parts.slice(0, -1).join('.');
+        let prefixType;
+        if (parts.length === 2) {
+            prefixType = findReceiverTypeBinding(inScope, prefix, scopes);
+        }
+        else {
+            // Recursive resolution: walk the prefix as a dotted class chain
+            // to find its typeRef. We need the TypeRef (not the class def)
+            // because the hook inspects the raw generic args (e.g.
+            // `Dictionary<string, User>`).
+            const headInner = parts[0];
+            let cur = findReceiverTypeBinding(inScope, headInner, scopes);
+            for (let i = 1; i < parts.length - 1 && cur !== undefined; i++) {
+                const cls = findClassBindingInScope(cur.declaredAtScope, cur.rawName, scopes);
+                if (cls === undefined) {
+                    cur = undefined;
+                    break;
+                }
+                const cs = classScopeByDefId.get(cls.nodeId);
+                cur = cs?.typeBindings.get(parts[i]);
+            }
+            prefixType = cur;
+        }
+        if (prefixType !== undefined) {
+            const elemName = options.unwrapCollectionAccessor(prefixType.rawName, last);
+            if (elemName !== undefined) {
+                return findClassBindingInScope(prefixType.declaredAtScope, elemName, scopes);
+            }
+        }
+    }
+    const head = parts[0];
+    const headType = findReceiverTypeBinding(inScope, head, scopes);
+    let currentClass = headType
+        ? findClassBindingInScope(headType.declaredAtScope, headType.rawName, scopes)
+        : undefined;
+    for (let i = 1; i < parts.length && currentClass !== undefined; i++) {
+        const fieldName = parts[i];
+        const cs = classScopeByDefId.get(currentClass.nodeId);
+        const fieldType = cs?.typeBindings.get(fieldName);
+        if (fieldType === undefined)
+            return undefined;
+        currentClass = findClassBindingInScope(fieldType.declaredAtScope, fieldType.rawName, scopes);
+    }
+    return currentClass;
+}
+/** Find the index of the `(` that matches the trailing `)` of a
+ *  call-expression text. Returns -1 if unbalanced. */
+function matchingOpenParen(text) {
+    if (!text.endsWith(')'))
+        return -1;
+    let depth = 0;
+    for (let i = text.length - 1; i >= 0; i--) {
+        const ch = text[i];
+        if (ch === ')')
+            depth++;
+        else if (ch === '(') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}

package/dist/core/ingestion/scope-resolution/passes/free-call-fallback.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Emit CALLS edges for free-call reference sites whose target is
+ * imported (or otherwise visible only via post-finalize scope.bindings).
+ *
+ * The shared `MethodRegistry.lookup` only consults `scope.bindings`
+ * (pre-finalize / local-only) for free calls. Cross-file imports land
+ * in `indexes.bindings` (post-finalize). Without this fallback, every
+ * `from x import f; f()` resolves to "unresolved".
+ *
+ * **Free-call dedup contract (Contract Invariant I2):** free calls
+ * collapse to one CALLS edge per (caller, target) pair regardless of
+ * how many call sites the caller contains. Mirrors the legacy DAG's
+ * dedup semantics (what the `default-params` / `variadic` / `overload`
+ * fixtures expect). Member calls keep position-based dedup elsewhere.
+ *
+ * Generic; promoted from `languages/python/scope-resolver.ts` per the scope-resolution
+ * generalization plan.
+ */
+import type { ParsedFile, Reference, ScopeId } from '../../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../../graph/types.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import type { SemanticModel } from '../../model/semantic-model.js';
+import type { WorkspaceResolutionIndex } from '../workspace-index.js';
+import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+export declare function emitFreeCallFallback(graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, _referenceIndex: {
+    readonly bySourceScope: ReadonlyMap<ScopeId, readonly Reference[]>;
+}, handledSites: Set<string>, model: SemanticModel, workspaceIndex: WorkspaceResolutionIndex): number;

package/dist/core/ingestion/scope-resolution/passes/free-call-fallback.js

@@ -0,0 +1,131 @@
+/**
+ * Emit CALLS edges for free-call reference sites whose target is
+ * imported (or otherwise visible only via post-finalize scope.bindings).
+ *
+ * The shared `MethodRegistry.lookup` only consults `scope.bindings`
+ * (pre-finalize / local-only) for free calls. Cross-file imports land
+ * in `indexes.bindings` (post-finalize). Without this fallback, every
+ * `from x import f; f()` resolves to "unresolved".
+ *
+ * **Free-call dedup contract (Contract Invariant I2):** free calls
+ * collapse to one CALLS edge per (caller, target) pair regardless of
+ * how many call sites the caller contains. Mirrors the legacy DAG's
+ * dedup semantics (what the `default-params` / `variadic` / `overload`
+ * fixtures expect). Member calls keep position-based dedup elsewhere.
+ *
+ * Generic; promoted from `languages/python/scope-resolver.ts` per the scope-resolution
+ * generalization plan.
+ */
+import { resolveCallerGraphId, resolveDefGraphId } from '../graph-bridge/ids.js';
+import { findCallableBindingInScope, findClassBindingInScope } from '../scope/walkers.js';
+import { narrowOverloadCandidates } from './overload-narrowing.js';
+export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _referenceIndex, handledSites, model, workspaceIndex) {
+    let emitted = 0;
+    const seen = new Set();
+    for (const parsed of parsedFiles) {
+        for (const site of parsed.referenceSites) {
+            if (site.kind !== 'call')
+                continue;
+            if (site.explicitReceiver !== undefined)
+                continue;
+            // Constructor form (`new User(...)`): resolve the class, then
+            // emit CALLS to its explicit Constructor def (when present) or
+            // to the Class node itself (implicit constructor). Legacy emits
+            // the same two targets; see test expectations.
+            let fnDef;
+            if (site.callForm === 'constructor') {
+                const classDef = findClassBindingInScope(site.inScope, site.name, scopes);
+                if (classDef !== undefined) {
+                    fnDef = pickConstructorOrClass(classDef, workspaceIndex);
+                }
+            }
+            // Implicit-this overload narrowing: an unqualified call inside
+            // a method body might be calling a sibling overload on the
+            // enclosing class. When the workspace has multiple methods of
+            // the same name in a single class, choose the best match by
+            // arity + argument types.
+            if (fnDef === undefined) {
+                fnDef = pickImplicitThisOverload(site, scopes, workspaceIndex, model);
+            }
+            if (fnDef === undefined) {
+                fnDef = findCallableBindingInScope(site.inScope, site.name, scopes);
+            }
+            if (fnDef === undefined)
+                continue;
+            const callerGraphId = resolveCallerGraphId(site.inScope, scopes, nodeLookup);
+            if (callerGraphId === undefined)
+                continue;
+            const tgtGraphId = resolveDefGraphId(fnDef.filePath, fnDef, nodeLookup);
+            if (tgtGraphId === undefined)
+                continue;
+            // Always mark the site as handled — even when the dedup-collapse
+            // means we don't add a new edge — so `emit-references` skips its
+            // potentially-wrong fallback for the same site.
+            handledSites.add(`${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`);
+            const relId = `rel:CALLS:${callerGraphId}->${tgtGraphId}`;
+            if (seen.has(relId))
+                continue;
+            seen.add(relId);
+            graph.addRelationship({
+                id: relId,
+                sourceId: callerGraphId,
+                targetId: tgtGraphId,
+                type: 'CALLS',
+                confidence: 0.85,
+                // Match legacy DAG's reason convention so consumers that
+                // assert `reason === 'import-resolved'` keep working.
+                reason: fnDef.filePath !== parsed.filePath ? 'import-resolved' : 'local-call',
+            });
+            emitted++;
+        }
+    }
+    return emitted;
+}
+/** For a constructor call `new X(...)`, return the X class's explicit
+ *  Constructor def (by walking the class scope's ownedDefs) or the
+ *  Class def itself when no explicit Constructor exists. Matches
+ *  legacy behavior — tests assert targetLabel === 'Class' for implicit
+ *  ctors and targetLabel === 'Constructor' for explicit ones. */
+function pickConstructorOrClass(classDef, workspaceIndex) {
+    const classScope = workspaceIndex.classScopeByDefId.get(classDef.nodeId);
+    if (classScope === undefined)
+        return classDef;
+    for (const def of classScope.ownedDefs) {
+        if (def.type === 'Constructor')
+            return def;
+    }
+    return classDef;
+}
+/** Walk up from the call-site scope to the enclosing class scope,
+ *  pick a method member by name with overload narrowing on arity +
+ *  argument types. Returns undefined if there's no enclosing class
+ *  or no matching method. Used for implicit-this calls inside a
+ *  class body where multiple overloads share the call name. */
+function pickImplicitThisOverload(site, scopes, workspaceIndex, model) {
+    // Find the enclosing Class scope by walking parents.
+    let curId = site.inScope;
+    let classScopeId;
+    while (curId !== null) {
+        const sc = scopes.scopeTree.getScope(curId);
+        if (sc === undefined)
+            break;
+        if (sc.kind === 'Class') {
+            classScopeId = sc.id;
+            break;
+        }
+        curId = sc.parent;
+    }
+    if (classScopeId === undefined)
+        return undefined;
+    // O(1) reverse-lookup via inverse map on WorkspaceResolutionIndex.
+    const classDefId = workspaceIndex.classScopeIdToDefId.get(classScopeId);
+    if (classDefId === undefined)
+        return undefined;
+    const overloads = model.methods.lookupAllByOwner(classDefId, site.name);
+    if (overloads.length === 0)
+        return undefined;
+    if (overloads.length === 1)
+        return overloads[0];
+    const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes);
+    return candidates[0];
+}

package/dist/core/ingestion/scope-resolution/passes/imported-return-types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cross-file return-type typeBinding propagation + post-finalize
+ * chain re-follow.
+ *
+ * **Why this lives in scope-resolution:** the algorithm is language-agnostic.
+ * Every language with cross-file callable imports needs the same
+ * mirror-binding step, otherwise `u = f(); u.save()` only resolves
+ * when `f` is in the same file as the call.
+ *
+ * **Mutation contract (Contract Invariant I3 + I6):**
+ *   - Mutates `Scope.typeBindings` (a plain `new Map(...)` from
+ *     `draftToScope`, NOT frozen — intentional, do not freeze).
+ *   - MUST run AFTER `finalizeScopeModel` (so `indexes.bindings` is
+ *     populated) but BEFORE `resolveReferenceSites` (so resolution
+ *     sees the propagated types).
+ *
+ * Generic; promoted from `languages/python/scope-resolver.ts` per the scope-resolution
+ * generalization plan.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import type { WorkspaceResolutionIndex } from '../workspace-index.js';
+/**
+ * Copy return-type typeBindings across module boundaries via import
+ * bindings. For each module-scope import like `from x import f`, look
+ * up `f` in the source file's module-scope typeBindings (which carries
+ * `f → ReturnType` from the language's return-type annotation
+ * capture) and mirror that binding into the importer's module scope.
+ *
+ * After propagation, re-runs the chain-follow on every scope's
+ * typeBindings — the in-extractor pass-4 ran before propagation and
+ * missed any chain whose terminal lived in a foreign file.
+ *
+ * Scope-chain concern (verified 2026-04-21): `pythonImportOwningScope`
+ * documents that function-local `from x import y` binds `y` to the
+ * inner function scope, which would make a module-only write miss
+ * non-module importers. In practice `finalize-algorithm` hoists those
+ * bindings into `indexes.bindings[moduleScope]` regardless of where
+ * the `import` statement appears — the integration fixture
+ * `python-function-local-import-chain` exercises a chained
+ * receiver-bound call `u = get_user(); u.save()` inside a function
+ * body and emits the expected `do_work → User.save` edge. The
+ * module-scope write is sufficient today. If finalize routing ever
+ * changes to honor the hook's per-scope contract, this pass must
+ * iterate `indexes.bindings` over every scope and mirror into the
+ * binding-owning scope's `typeBindings`, not just the module's.
+ */
+export declare function propagateImportedReturnTypes(parsedFiles: readonly ParsedFile[], indexes: ScopeResolutionIndexes, index: WorkspaceResolutionIndex): void;

package/dist/core/ingestion/scope-resolution/passes/imported-return-types.js

@@ -0,0 +1,130 @@
+/**
+ * Cross-file return-type typeBinding propagation + post-finalize
+ * chain re-follow.
+ *
+ * **Why this lives in scope-resolution:** the algorithm is language-agnostic.
+ * Every language with cross-file callable imports needs the same
+ * mirror-binding step, otherwise `u = f(); u.save()` only resolves
+ * when `f` is in the same file as the call.
+ *
+ * **Mutation contract (Contract Invariant I3 + I6):**
+ *   - Mutates `Scope.typeBindings` (a plain `new Map(...)` from
+ *     `draftToScope`, NOT frozen — intentional, do not freeze).
+ *   - MUST run AFTER `finalizeScopeModel` (so `indexes.bindings` is
+ *     populated) but BEFORE `resolveReferenceSites` (so resolution
+ *     sees the propagated types).
+ *
+ * Generic; promoted from `languages/python/scope-resolver.ts` per the scope-resolution
+ * generalization plan.
+ */
+/** Max chain depth for the post-finalize re-follow. */
+const RECHAIN_MAX_DEPTH = 8;
+/** Walk `ref.rawName` through the scope chain's typeBindings looking
+ *  for a terminal class-like rawName. Mirrors the in-extractor
+ *  `followChainedRef` but operates on post-finalize Scope objects so
+ *  it can see imported return-types propagated by
+ *  `propagateImportedReturnTypes`. */
+function followChainPostFinalize(start, fromScopeId, scopes) {
+    let current = start;
+    const visited = new Set();
+    for (let depth = 0; depth < RECHAIN_MAX_DEPTH; depth++) {
+        if (current.rawName.includes('.'))
+            return current;
+        let scopeId = fromScopeId;
+        let next;
+        while (scopeId !== null) {
+            const scope = scopes.scopeTree.getScope(scopeId);
+            if (scope === undefined)
+                break;
+            next = scope.typeBindings.get(current.rawName);
+            if (next !== undefined && next !== current)
+                break;
+            next = undefined;
+            scopeId = scope.parent;
+        }
+        if (next === undefined)
+            return current;
+        if (visited.has(next.rawName))
+            return current;
+        visited.add(next.rawName);
+        current = next;
+    }
+    return current;
+}
+/**
+ * Copy return-type typeBindings across module boundaries via import
+ * bindings. For each module-scope import like `from x import f`, look
+ * up `f` in the source file's module-scope typeBindings (which carries
+ * `f → ReturnType` from the language's return-type annotation
+ * capture) and mirror that binding into the importer's module scope.
+ *
+ * After propagation, re-runs the chain-follow on every scope's
+ * typeBindings — the in-extractor pass-4 ran before propagation and
+ * missed any chain whose terminal lived in a foreign file.
+ *
+ * Scope-chain concern (verified 2026-04-21): `pythonImportOwningScope`
+ * documents that function-local `from x import y` binds `y` to the
+ * inner function scope, which would make a module-only write miss
+ * non-module importers. In practice `finalize-algorithm` hoists those
+ * bindings into `indexes.bindings[moduleScope]` regardless of where
+ * the `import` statement appears — the integration fixture
+ * `python-function-local-import-chain` exercises a chained
+ * receiver-bound call `u = get_user(); u.save()` inside a function
+ * body and emits the expected `do_work → User.save` edge. The
+ * module-scope write is sufficient today. If finalize routing ever
+ * changes to honor the hook's per-scope contract, this pass must
+ * iterate `indexes.bindings` over every scope and mirror into the
+ * binding-owning scope's `typeBindings`, not just the module's.
+ */
+export function propagateImportedReturnTypes(parsedFiles, indexes, index) {
+    const moduleScopeByFile = index.moduleScopeByFile;
+    for (const parsed of parsedFiles) {
+        const importerModule = moduleScopeByFile.get(parsed.filePath);
+        if (importerModule === undefined)
+            continue;
+        const finalizedBindings = indexes.bindings.get(importerModule.id);
+        if (finalizedBindings === undefined)
+            continue;
+        for (const [localName, refs] of finalizedBindings) {
+            // Skip if importer already has a typeBinding for this name (e.g.
+            // an explicit local annotation should win over import-derived).
+            if (importerModule.typeBindings.has(localName))
+                continue;
+            for (const ref of refs) {
+                if (ref.origin !== 'import' && ref.origin !== 'reexport')
+                    continue;
+                const sourceModule = moduleScopeByFile.get(ref.def.filePath);
+                if (sourceModule === undefined)
+                    continue;
+                // The source file's typeBinding is keyed by the def's simple
+                // name (e.g. `get_user`), not the importer's local alias. Use
+                // the def's qualifiedName tail.
+                const qn = ref.def.qualifiedName;
+                if (qn === undefined)
+                    continue;
+                const dot = qn.lastIndexOf('.');
+                const sourceName = dot === -1 ? qn : qn.slice(dot + 1);
+                const sourceTypeRef = sourceModule.typeBindings.get(sourceName);
+                if (sourceTypeRef === undefined)
+                    continue;
+                // Mirror the binding under the importer's local alias —
+                // mutating typeBindings is safe because draftToScope produced
+                // a non-frozen Map.
+                importerModule.typeBindings.set(localName, sourceTypeRef);
+                break;
+            }
+        }
+    }
+    // Re-follow chains across every scope so chains terminating in a
+    // freshly-propagated import binding resolve to their terminal type.
+    for (const parsed of parsedFiles) {
+        for (const scope of parsed.scopes) {
+            for (const [name, ref] of scope.typeBindings) {
+                const resolved = followChainPostFinalize(ref, scope.id, indexes);
+                if (resolved !== ref) {
+                    scope.typeBindings.set(name, resolved);
+                }
+            }
+        }
+    }
+}

package/dist/core/ingestion/scope-resolution/passes/mro.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Generic MRO (method-resolution-order) builder.
+ *
+ * Walks the graph's `EXTENDS` edges to recover an inheritance map,
+ * then asks the per-language `LinearizeStrategy` to order each class's
+ * ancestors. Returns `Map<classDefId, ancestorDefId[]>` ready to plug
+ * into `MethodDispatchIndex` via `buildPopulatedMethodDispatch`.
+ *
+ * **Why a strategy hook:** linearization differs across languages.
+ *   - Python (depth-first first-seen, single inheritance): trivially
+ *     correct; multi-inheritance falls back to BFS dedup. Real C3
+ *     would handle diamond hierarchies — defer until we hit one.
+ *   - Java (single-inheritance only): walk one parent.
+ *   - C++ (multiple inheritance): C3-like or BFS depending on how
+ *     strict the consumer needs to be.
+ *   - Languages without inheritance (COBOL): return empty list.
+ *
+ * The strategy receives the FULL ancestry context (`directParents` +
+ * `parentsByDefId`) so C3 implementations have what they need.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../../graph/types.js';
+import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+import type { LinearizeStrategy } from '../contract/scope-resolver.js';
+/**
+ * Build an MRO map keyed by scope-resolution Class `DefId`.
+ *
+ * Steps:
+ *   1. Collect EXTENDS edges from the graph → `parentsByGraphId`.
+ *   2. Collect Class defs from `parsedFiles` and translate to graph
+ *      ids via `nodeLookup` → `defIdByGraphId` (the bridge between
+ *      scope-resolution DefId and the legacy graph node id).
+ *   3. For each Class def, ask `linearize` for its ancestor order.
+ */
+export declare function buildMro(graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, linearize: LinearizeStrategy): Map<string, string[]>;
+/**
+ * Default linearization: depth-first BFS-with-visited, first-seen
+ * wins. Correct for single-inheritance languages and for Python's
+ * simplified MRO. Multi-inheritance diamond hierarchies need a real
+ * C3 implementation; per-language overrides land here.
+ */
+export declare const defaultLinearize: LinearizeStrategy;