arceus-s 1.6.4

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

@@ -0,0 +1,251 @@
+/**
+ * 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, options = {}) {
+    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);
+            }
+            // V1: pickUniqueGlobalCallable ignores import context — resolves to any
+            // globally-unique callable. False cross-package edges are possible when
+            // the caller does not import the target package. Same-package calls are
+            // caught by findCallableBindingInScope above before reaching here.
+            if (fnDef === undefined && options.allowGlobalFallback === true) {
+                fnDef = pickUniqueGlobalCallable(site.name, model, scopes, parsed.filePath, options.isFileLocalDef, site.arity, options.isCallableVisibleFromCaller !== undefined
+                    ? (candidate) => options.isCallableVisibleFromCaller({ callerParsed: parsed, candidate })
+                    : undefined);
+            }
+            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;
+}
+function pickUniqueGlobalCallable(name, model, scopes, callerFilePath, isFileLocalDef, callArity, isCallerVisible) {
+    const scopeDefs = [];
+    const scopeSeen = new Set();
+    for (const def of scopes.defs.byId.values()) {
+        const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName;
+        if (simple !== name)
+            continue;
+        if (def.type !== 'Function' && def.type !== 'Method' && def.type !== 'Constructor')
+            continue;
+        // Skip file-local defs (e.g. C `static` functions) that live in a
+        // different file from the caller — they are logically invisible.
+        if (isFileLocalDef !== undefined && def.filePath !== callerFilePath && isFileLocalDef(def)) {
+            continue;
+        }
+        // Caller-side visibility filter (e.g., PHP namespace + use-function
+        // import gating). When defined, blocks candidates the caller cannot
+        // legally reach. Languages without namespace-scoped function resolution
+        // leave this undefined → no filtering.
+        if (isCallerVisible !== undefined && !isCallerVisible(def)) {
+            continue;
+        }
+        const key = logicalCallableKey(def);
+        if (scopeSeen.has(key))
+            continue;
+        scopeSeen.add(key);
+        scopeDefs.push(def);
+    }
+    if (scopeDefs.length === 1)
+        return scopeDefs[0];
+    // When multiple scope-index candidates exist, attempt arity narrowing
+    // before falling back to the semantic-model lookup. This handles
+    // registry-primary languages where the model is not populated for the
+    // migrated language's files (call-processor skips them).
+    if (scopeDefs.length > 1 && callArity !== undefined) {
+        const arityMatch = narrowByArity(scopeDefs, callArity);
+        if (arityMatch !== undefined)
+            return arityMatch;
+    }
+    const defs = [];
+    const seen = new Set();
+    const push = (pool) => {
+        for (const def of pool) {
+            // Apply the same file-local linkage filter as Phase 1 —
+            // cross-file static defs must never leak through the
+            // SemanticModel fallback path.
+            if (isFileLocalDef !== undefined && def.filePath !== callerFilePath && isFileLocalDef(def)) {
+                continue;
+            }
+            // Same caller-visibility filter applied to the model-side pool.
+            if (isCallerVisible !== undefined && !isCallerVisible(def)) {
+                continue;
+            }
+            const key = logicalCallableKey(def);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            defs.push(def);
+        }
+    };
+    push(model.symbols.lookupCallableByName(name));
+    push(model.methods.lookupMethodByName(name));
+    if (defs.length === 1)
+        return defs[0];
+    // When multiple candidates exist and the call site has a known arity,
+    // narrow by parameter count.
+    if (defs.length > 1 && callArity !== undefined) {
+        const arityMatch = narrowByArity(defs, callArity);
+        if (arityMatch !== undefined)
+            return arityMatch;
+    }
+    return undefined;
+}
+/**
+ * Narrow a list of callable candidates by call-site arity.
+ * A def is compatible when `requiredParameterCount <= arity <= parameterCount`.
+ * Defs with `parameterCount === undefined` (variadic/unknown) are always kept.
+ * Returns the single compatible def, or `undefined` when zero or multiple match.
+ */
+function narrowByArity(defs, callArity) {
+    const compatible = defs.filter((d) => {
+        const total = d.parameterCount;
+        if (total === undefined)
+            return true; // unknown arity — keep
+        const required = d.requiredParameterCount ?? total;
+        return required <= callArity && callArity <= total;
+    });
+    return compatible.length === 1 ? compatible[0] : undefined;
+}
+function logicalCallableKey(def) {
+    return [
+        def.filePath,
+        def.qualifiedName ?? '',
+        def.type,
+        def.parameterCount ?? '',
+        def.parameterTypes?.join(',') ?? '',
+    ].join('\0');
+}
+/** 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,
+ *  no matching method, OR narrowing leaves multiple compatible
+ *  candidates — in the multi-candidate case, picking
+ *  `candidates[0]` would emit a high-confidence CALLS edge whose
+ *  target depends on registration order rather than a defensible
+ *  resolution. Mirrors `pickUniqueGlobalCallable`'s uniqueness check
+ *  in the same file (Codex PR #1497 review, finding 2).
+ *
+ *  Exported for unit testing — language-agnostic logic, exercised
+ *  via synthetic stubs in `pick-implicit-this-overload.test.ts`. The
+ *  production call site is `applyFreeCallFallback` immediately above. */
+export 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];
+    // Narrow on arity + argument types. Require a UNIQUE survivor —
+    // ambiguous narrowing (multiple compatible candidates with no
+    // disambiguating signal) leaves the call unresolved rather than
+    // routing to an arbitrary first overload by registration order.
+    const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes);
+    if (candidates.length !== 1)
+        return undefined;
+    return candidates[0];
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 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).
+ *
+ * **Ordering invariant (added 2026-04-24, RFC #909 Ring 3 / PR #1050):**
+ * The pass walks files in `indexes.sccs` reverse-topological order
+ * (leaves first per `tarjanSccs`). For each importer we chain-follow
+ * the source module's typeBindings BEFORE mirroring, so a multi-hop
+ * alias chain like
+ *
+ *   models.ts: function getUser(): User
+ *   service.ts: export const user = getUser()        // user → getUser
+ *   app.ts: import { user } from './service'         // user → ?
+ *
+ * collapses to `app.user → User` in a single pass instead of stopping
+ * at the intermediate `getUser` ref. The motivating regression is the
+ * `ts-simple` integration fixture (`arc/test/fixtures/scope-
+ * resolution/cross-file-binding/ts-simple/`), where `user.save()` and
+ * `user.getName()` only resolve when the chain collapse happens
+ * topologically.
+ *
+ * Cyclic SCCs reach a partial fixpoint via the same mirror step but
+ * are not guaranteed to fully resolve — see the `ts-circular`
+ * fixture, which only asserts pipeline-no-throw.
+ *
+ * Generic; promoted from `languages/python/scope-resolver.ts` per the
+ * scope-resolution generalization plan.
+ */
+import type { ParsedFile, ScopeId, TypeRef } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import type { WorkspaceResolutionIndex } from '../workspace-index.js';
+/** 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`. */
+export declare function followChainPostFinalize(start: TypeRef, fromScopeId: ScopeId, scopes: ScopeResolutionIndexes): TypeRef;
+/**
+ * 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,202 @@
+/**
+ * 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).
+ *
+ * **Ordering invariant (added 2026-04-24, RFC #909 Ring 3 / PR #1050):**
+ * The pass walks files in `indexes.sccs` reverse-topological order
+ * (leaves first per `tarjanSccs`). For each importer we chain-follow
+ * the source module's typeBindings BEFORE mirroring, so a multi-hop
+ * alias chain like
+ *
+ *   models.ts: function getUser(): User
+ *   service.ts: export const user = getUser()        // user → getUser
+ *   app.ts: import { user } from './service'         // user → ?
+ *
+ * collapses to `app.user → User` in a single pass instead of stopping
+ * at the intermediate `getUser` ref. The motivating regression is the
+ * `ts-simple` integration fixture (`arc/test/fixtures/scope-
+ * resolution/cross-file-binding/ts-simple/`), where `user.save()` and
+ * `user.getName()` only resolve when the chain collapse happens
+ * topologically.
+ *
+ * Cyclic SCCs reach a partial fixpoint via the same mirror step but
+ * are not guaranteed to fully resolve — see the `ts-circular`
+ * fixture, which only asserts pipeline-no-throw.
+ *
+ * Generic; promoted from `languages/python/scope-resolver.ts` per the
+ * scope-resolution generalization plan.
+ */
+import { lookupBindingsAt, namesAtScope } from '../scope/walkers.js';
+/**
+ * Max chain depth for the post-finalize re-follow. Effective end-to-end
+ * depth is roughly 2× this number, because chain-following runs once
+ * inside each importer's source module before mirroring AND once on
+ * the importer's own typeBindings after mirroring; deeply nested
+ * intra-module aliases can compose with cross-file aliases of the same
+ * depth. 8 covers all production fixtures with headroom.
+ */
+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`. */
+export 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;
+    // Walk SCCs in reverse-topological order (`indexes.sccs` is leaves-
+    // first per `tarjanSccs`). For each file we mirror import bindings
+    // AFTER chain-following the source module's typeBindings, so a
+    // multi-hop alias chain like
+    //   models.ts: function getUser(): User
+    //   service.ts: export const user = getUser()        // user → getUser
+    //   app.ts: import { user } from './service'         // user → ?
+    // collapses to `app.user → User` instead of stopping at the
+    // intermediate `getUser` ref. Without topological ordering, app.ts
+    // could be processed before service.ts had its own typeBindings
+    // chain-followed, leaving the importer with an unresolvable interim
+    // ref. Cyclic SCCs reach a partial fixpoint via the same mirror
+    // step but are not guaranteed to fully resolve — see the
+    // ts-circular cross-file-binding fixture which only asserts that
+    // the pipeline does not throw.
+    for (const scc of indexes.sccs) {
+        for (const filePath of scc.files) {
+            const importerModule = moduleScopeByFile.get(filePath);
+            if (importerModule === undefined)
+                continue;
+            // Iterate finalized + augmented binding names at this scope so
+            // post-finalize hooks (e.g. `using static` augmentations from
+            // `populateCsharpNamespaceSiblings`) are visible to the
+            // import-derived typeBinding mirror. Both helpers fast-path when
+            // no augmentations exist for the scope, so the common case is
+            // allocation-free. See I8.
+            for (const localName of namesAtScope(importerModule.id, indexes)) {
+                // Skip if importer already has a typeBinding for this name —
+                // an explicit local annotation must win over import-derived.
+                if (importerModule.typeBindings.has(localName))
+                    continue;
+                const refs = lookupBindingsAt(importerModule.id, localName, indexes);
+                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.
+                    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;
+                    // Chain-follow inside the source module so we mirror the
+                    // terminal type, not an intermediate intra-source reference.
+                    const terminal = followChainPostFinalize(sourceTypeRef, sourceModule.id, indexes);
+                    // Mutating typeBindings is safe because draftToScope
+                    // produced a non-frozen Map (Contract Invariant I3/I8).
+                    importerModule.typeBindings.set(localName, terminal);
+                    // First-write-wins for the local alias: if the same
+                    // `localName` was registered multiple times via
+                    // `mergeBindings` (rare; happens with conflicting
+                    // re-exports), only the first ref with a usable
+                    // typeBinding source is mirrored. Conflict resolution
+                    // among multiple sources is the merger's job, not ours.
+                    break;
+                }
+            }
+            // Chain-follow this importer's own module typeBindings now —
+            // any local `const x = importedFn()` resolves while we have
+            // freshly-mirrored bindings, and downstream importers in a
+            // later (closer-to-root) SCC will see x's terminal type rather
+            // than an intra-module call ref.
+            for (const [name, ref] of importerModule.typeBindings) {
+                const resolved = followChainPostFinalize(ref, importerModule.id, indexes);
+                if (resolved !== ref) {
+                    importerModule.typeBindings.set(name, resolved);
+                }
+            }
+        }
+    }
+    // Final pass: chain-follow non-module scopes (function-local
+    // typeBindings). Module scopes were already followed inside the
+    // SCC loop above.
+    for (const parsed of parsedFiles) {
+        const moduleScopeId = moduleScopeByFile.get(parsed.filePath)?.id;
+        for (const scope of parsed.scopes) {
+            if (scope.id === moduleScopeId)
+                continue;
+            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;

package/dist/core/ingestion/scope-resolution/passes/mro.js

@@ -0,0 +1,102 @@
+/**
+ * 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 { resolveDefGraphId } from '../graph-bridge/ids.js';
+import { isClassLike } from '../scope/walkers.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 function buildMro(graph, parsedFiles, nodeLookup, linearize) {
+    // Step 1: parentsByGraphId — typed iterator skips the per-edge type
+    // check and the millions of CALLS/ACCESSES/IMPORTS/DEFINES edges
+    // that aren't relevant to MRO.
+    const parentsByGraphId = new Map();
+    for (const rel of graph.iterRelationshipsByType('EXTENDS')) {
+        let list = parentsByGraphId.get(rel.sourceId);
+        if (list === undefined) {
+            list = [];
+            parentsByGraphId.set(rel.sourceId, list);
+        }
+        list.push(rel.targetId);
+    }
+    // Step 2: defIdByGraphId — translate graph ids to scope-resolution DefIds.
+    const defIdByGraphId = new Map();
+    for (const parsed of parsedFiles) {
+        for (const def of parsed.localDefs) {
+            if (!isClassLike(def.type))
+                continue;
+            const graphId = resolveDefGraphId(parsed.filePath, def, nodeLookup);
+            if (graphId !== undefined)
+                defIdByGraphId.set(graphId, def.nodeId);
+        }
+    }
+    // Step 2b: invert parentsByGraphId into parentsByDefId — the
+    // strategy works in DefId space.
+    const parentsByDefId = new Map();
+    for (const [childGraphId, parents] of parentsByGraphId) {
+        const childDefId = defIdByGraphId.get(childGraphId);
+        if (childDefId === undefined)
+            continue;
+        const parentDefIds = [];
+        for (const p of parents) {
+            const pd = defIdByGraphId.get(p);
+            if (pd !== undefined)
+                parentDefIds.push(pd);
+        }
+        parentsByDefId.set(childDefId, parentDefIds);
+    }
+    // Step 3: linearize per class.
+    const mroByDefId = new Map();
+    for (const defId of defIdByGraphId.values()) {
+        const directParents = parentsByDefId.get(defId) ?? [];
+        mroByDefId.set(defId, linearize(defId, directParents, parentsByDefId));
+    }
+    return mroByDefId;
+}
+/**
+ * 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 const defaultLinearize = (_classDefId, directParents, parentsByDefId) => {
+    const ancestors = [];
+    const visited = new Set();
+    const queue = [...directParents];
+    for (;;) {
+        const cur = queue.shift();
+        if (cur === undefined)
+            break;
+        if (visited.has(cur))
+            continue;
+        visited.add(cur);
+        ancestors.push(cur);
+        for (const p of parentsByDefId.get(cur) ?? [])
+            queue.push(p);
+    }
+    return ancestors;
+};