gitnexus 1.5.2 → 1.6.0

package/dist/core/ingestion/model/resolution-context.js

@@ -0,0 +1,337 @@
+/**
+ * Resolution Context
+ *
+ * Single implementation of tiered name resolution.
+ *
+ * Resolution tiers (highest confidence first):
+ * 1. Same file (lookupExactAll — authoritative)
+ * 2a-named. Named binding chain (walkBindingChain via NamedImportMap)
+ * 2a. Import-scoped (iterate importedFiles with lookupExactAll per file)
+ * 2b. Package-scoped (iterate indexed files matching package dir with lookupExactAll)
+ * 3. Global (lookupClassByName + lookupImplByName + lookupCallableByName — consumers must check count)
+ *
+ * Each tier queries the minimum necessary scope directly:
+ * - Tier 2a iterates the caller's import set (O(imports) × O(1) lookupExactAll).
+ * - Tier 2b iterates all indexed files filtered by package dir
+ *   (O(files) × O(1) lookupExactAll — avoids a global name scan).
+ * - Tier 3 combines lookupClassByName + lookupImplByName + lookupCallableByName
+ *   (three O(1) index lookups with a narrow, type-specific result set).
+ */
+import { createSemanticModel } from './semantic-model.js';
+/**
+ * Check if a file path is directly inside a package directory identified by
+ * its suffix. Used by Tier 2b package-scoped resolution (Go / C#).
+ */
+export function isFileInPackageDir(filePath, dirSuffix) {
+    // Prepend '/' so paths like "internal/auth/service.go" match suffix "/internal/auth/"
+    const normalized = '/' + filePath.replace(/\\/g, '/');
+    if (!normalized.includes(dirSuffix))
+        return false;
+    const afterDir = normalized.substring(normalized.indexOf(dirSuffix) + dirSuffix.length);
+    return !afterDir.includes('/');
+}
+/** Maximum re-export hops walkBindingChain will follow before giving up.
+ *  A hard cap is needed to defend against pathological cycles that slip
+ *  past the `visited` Set (e.g. a binding chain whose key is equal by
+ *  string value but visits distinct modules). Five hops covers the
+ *  common TypeScript monorepo pattern (component → pkg/index →
+ *  packages/index → root/index → types/index). Chains longer than this
+ *  fall through to Tier 2a-import / Tier 2b / Tier 3 resolution, which
+ *  is a silent false-negative that the caller may or may not recover
+ *  from. If a real repo hits this limit, raise it — there is no
+ *  correctness reason to keep it at exactly 5. */
+const MAX_BINDING_CHAIN_DEPTH = 5;
+/**
+ * Walk a named-binding re-export chain through NamedImportMap.
+ *
+ * When file A imports { User } from B, and B re-exports { User } from C,
+ * the NamedImportMap for A points to B, but B has no User definition.
+ * This function follows the chain: A → B → C until a definition is found.
+ *
+ * Returns the definitions found at the end of the chain, or null if the
+ * chain breaks (missing binding, circular reference, or
+ * {@link MAX_BINDING_CHAIN_DEPTH} exceeded). Internal to
+ * resolution-context — not exported from the model barrel.
+ */
+function walkBindingChain(name, currentFilePath, symbolTable, namedImportMap) {
+    // Fast exit: most files have no named imports at all. Skip the Set
+    // allocation + loop entry on the common empty-binding path so resolve()
+    // stays allocation-free for the typical call site.
+    const firstBindings = namedImportMap.get(currentFilePath);
+    if (!firstBindings)
+        return null;
+    const firstBinding = firstBindings.get(name);
+    if (!firstBinding)
+        return null;
+    let lookupFile = currentFilePath;
+    let lookupName = name;
+    const visited = new Set();
+    for (let depth = 0; depth < MAX_BINDING_CHAIN_DEPTH; depth++) {
+        const bindings = depth === 0 ? firstBindings : namedImportMap.get(lookupFile);
+        if (!bindings)
+            return null;
+        const binding = depth === 0 ? firstBinding : bindings.get(lookupName);
+        if (!binding)
+            return null;
+        const key = `${binding.sourcePath}:${binding.exportedName}`;
+        if (visited.has(key))
+            return null; // circular
+        visited.add(key);
+        const targetName = binding.exportedName;
+        const resolvedDefs = symbolTable.lookupExactAll(binding.sourcePath, targetName);
+        if (resolvedDefs.length > 0)
+            return resolvedDefs;
+        // No definition in source file → follow re-export chain
+        lookupFile = binding.sourcePath;
+        lookupName = targetName;
+    }
+    return null;
+}
+/** Confidence scores per resolution tier. */
+export const TIER_CONFIDENCE = {
+    'same-file': 0.95,
+    'import-scoped': 0.9,
+    global: 0.5,
+};
+export const createResolutionContext = () => {
+    const model = createSemanticModel();
+    const symbols = model.symbols;
+    const importMap = new Map();
+    const packageMap = new Map();
+    const namedImportMap = new Map();
+    const moduleAliasMap = new Map();
+    // Inverted index: packageDirSuffix → Set<filePath>.
+    // Built lazily on first Tier 2b hit — one-time cost of O(totalFiles ×
+    // allUniqueDirSuffixes) isFileInPackageDir calls across the entire
+    // packageMap, amortized over the pipeline run. Subsequent Tier 2b
+    // resolutions are O(callerPackages × filesInPackage × O(1)).
+    let packageDirIndex = null;
+    // Per-file cache state
+    let cacheFile = null;
+    let cache = null;
+    let cacheHits = 0;
+    let cacheMisses = 0;
+    // Tier hit counters — replaces the lost fuzzyCallCount diagnostic
+    let tierSameFile = 0;
+    let tierImportScoped = 0;
+    let tierGlobal = 0;
+    let tierMiss = 0;
+    // --- Core resolution (single implementation of tier logic) ---
+    const resolveUncached = (name, fromFile) => {
+        // Tier 1: Same file — authoritative match (returns all overloads)
+        const localDefs = symbols.lookupExactAll(fromFile, name);
+        if (localDefs.length > 0) {
+            tierSameFile++;
+            return { candidates: localDefs, tier: 'same-file' };
+        }
+        // Tier 2a-named: Named binding chain (aliased / re-exported imports)
+        // Checked before import-scoped so that `import { User as U }` resolves
+        // correctly even when lookupExactAll on the alias name returns nothing.
+        const chainResult = walkBindingChain(name, fromFile, symbols, namedImportMap);
+        if (chainResult && chainResult.length > 0) {
+            tierImportScoped++;
+            return { candidates: chainResult, tier: 'import-scoped' };
+        }
+        // Tier 2a: Import-scoped — iterate the caller's imported files directly.
+        // O(importedFiles) × O(1) lookupExactAll — no global name scan needed.
+        const importedFiles = importMap.get(fromFile);
+        if (importedFiles) {
+            const importedDefs = [];
+            for (const file of importedFiles) {
+                importedDefs.push(...symbols.lookupExactAll(file, name));
+            }
+            if (importedDefs.length > 0) {
+                tierImportScoped++;
+                return { candidates: importedDefs, tier: 'import-scoped' };
+            }
+        }
+        // Tier 2b: Package-scoped — look up files in the caller's imported package
+        // directories via an inverted index (packageDirSuffix → Set<filePath>),
+        // then do O(1) lookupExactAll per file. The inverted index is built lazily
+        // on first Tier 2b hit by scanning symbols.getFiles() once, making
+        // subsequent Tier 2b resolutions O(packages × filesInPackage) instead of
+        // O(allFiles × packages).
+        const importedPackages = packageMap.get(fromFile);
+        if (importedPackages) {
+            // Lazily build the inverted index on first use. For each indexed file,
+            // test it against isFileInPackageDir for all known dirSuffixes collected
+            // from packageMap. This scans all files once (instead of per-resolution)
+            // and produces a dirSuffix → Set<filePath> map.
+            if (!packageDirIndex) {
+                // Collect all unique dir suffixes across the entire packageMap
+                const allDirSuffixes = new Set();
+                for (const dirs of packageMap.values()) {
+                    for (const d of dirs)
+                        allDirSuffixes.add(d);
+                }
+                packageDirIndex = new Map();
+                for (const file of symbols.getFiles()) {
+                    for (const dirSuffix of allDirSuffixes) {
+                        if (isFileInPackageDir(file, dirSuffix)) {
+                            let files = packageDirIndex.get(dirSuffix);
+                            if (!files) {
+                                files = new Set();
+                                packageDirIndex.set(dirSuffix, files);
+                            }
+                            files.add(file);
+                        }
+                    }
+                }
+            }
+            const packageDefs = [];
+            for (const dirSuffix of importedPackages) {
+                const filesInDir = packageDirIndex.get(dirSuffix);
+                if (filesInDir) {
+                    for (const file of filesInDir) {
+                        packageDefs.push(...symbols.lookupExactAll(file, name));
+                    }
+                }
+            }
+            if (packageDefs.length > 0) {
+                tierImportScoped++;
+                return { candidates: packageDefs, tier: 'import-scoped' };
+            }
+        }
+        // Tier 3: Global — targeted O(1) index lookups for each symbol category.
+        // Class-like symbols (Class, Struct, Interface, Enum, Record, Trait) are
+        // covered by lookupClassByName; Rust impl blocks by lookupImplByName
+        // (separate to avoid polluting heritage resolution); free callables
+        // (Function, Macro, Delegate) by lookupCallableByName; owner-scoped
+        // methods and constructors by `model.methods.lookupMethodByName`.
+        //
+        // FREE_CALLABLE_TYPES excludes Method/Constructor, so strictly-labeled
+        // methods are disjoint between the two indexes.
+        //
+        // Partial-state caveat: Python/Rust/Kotlin class methods are emitted
+        // as Function + ownerId — `rawSymbols.add` routes them through both
+        // the Function callable index AND, via the dispatch-key normalization
+        // in `wrappedAdd`, the method registry. The same `SymbolDefinition`
+        // reference lands in both `callableDefs` and `methodDefs`, so the
+        // Set-based dedup below is required.
+        //
+        // Known exclusion: TypeAlias, Const, and Variable are NOT reachable at
+        // Tier 3 — they don't belong to any of the indexes. TypeAlias is not
+        // a call target; Const/Variable are resolved via import or same-file
+        // tiers. Macro (C/C++) and Delegate (C#) stay in the callable index
+        // since call-processor.ts treats them as callable targets.
+        const classDefs = model.types.lookupClassByName(name);
+        const implDefs = model.types.lookupImplByName(name);
+        const callableDefs = symbols.lookupCallableByName(name);
+        const methodDefs = model.methods.lookupMethodByName(name);
+        if (classDefs.length === 0 &&
+            implDefs.length === 0 &&
+            callableDefs.length === 0 &&
+            methodDefs.length === 0) {
+            tierMiss++;
+            return null;
+        }
+        // Fast path: if no `Function + ownerId` class method was ever
+        // registered into the method registry (the only source of
+        // cross-index duplication), the callable and method indexes are
+        // guaranteed disjoint and we can concat without dedup.
+        if (!model.methods.hasFunctionMethods) {
+            const globalDefs = [
+                ...classDefs,
+                ...implDefs,
+                ...callableDefs,
+                ...methodDefs,
+            ];
+            tierGlobal++;
+            return { candidates: globalDefs, tier: 'global' };
+        }
+        // Slow path: dedup by nodeId because the same SymbolDefinition
+        // reference can land in both `callableDefs` (via the Function
+        // callable-index gate) and `methodDefs` (via the dispatch-key
+        // normalization routing Function+ownerId into MethodRegistry).
+        // Dedup covers all four index reads so any nodeId overlap (even
+        // theoretical ones between classDefs/implDefs) is caught.
+        const globalDefs = [];
+        const seen = new Set();
+        const pushUnique = (pool) => {
+            for (const def of pool) {
+                if (seen.has(def.nodeId))
+                    continue;
+                seen.add(def.nodeId);
+                globalDefs.push(def);
+            }
+        };
+        pushUnique(classDefs);
+        pushUnique(implDefs);
+        pushUnique(callableDefs);
+        pushUnique(methodDefs);
+        tierGlobal++;
+        return { candidates: globalDefs, tier: 'global' };
+    };
+    const resolve = (name, fromFile) => {
+        // Check cache (only when enabled AND fromFile matches cached file)
+        if (cache && cacheFile === fromFile) {
+            if (cache.has(name)) {
+                cacheHits++;
+                return cache.get(name);
+            }
+            cacheMisses++;
+        }
+        const result = resolveUncached(name, fromFile);
+        // Store in cache if active and file matches
+        if (cache && cacheFile === fromFile) {
+            cache.set(name, result);
+        }
+        return result;
+    };
+    // --- Cache lifecycle ---
+    const enableCache = (filePath) => {
+        cacheFile = filePath;
+        if (!cache)
+            cache = new Map();
+        else
+            cache.clear();
+    };
+    const clearCache = () => {
+        cacheFile = null;
+        // Reuse the Map instance — just clear entries to reduce GC pressure at scale.
+        cache?.clear();
+        // Note: packageDirIndex is NOT invalidated here. It is built lazily on
+        // first Tier 2b hit and remains valid across file boundaries because
+        // packageMap and the symbol file set are append-only during the calls
+        // phase (all parsing/import processing completes before resolution).
+        // Invalidating per-file would destroy the amortization benefit — the
+        // O(files × dirs) rebuild would run per-file instead of once.
+        // Full invalidation happens in clear() (pipeline reset).
+    };
+    const getStats = () => ({
+        ...symbols.getStats(),
+        cacheHits,
+        cacheMisses,
+        tierSameFile,
+        tierImportScoped,
+        tierGlobal,
+        tierMiss,
+    });
+    const clear = () => {
+        model.clear();
+        importMap.clear();
+        packageMap.clear();
+        namedImportMap.clear();
+        moduleAliasMap.clear();
+        packageDirIndex = null; // invalidate — will rebuild on next Tier 2b hit
+        clearCache();
+        cacheHits = 0;
+        cacheMisses = 0;
+        tierSameFile = 0;
+        tierImportScoped = 0;
+        tierGlobal = 0;
+        tierMiss = 0;
+    };
+    return {
+        resolve,
+        model,
+        importMap,
+        packageMap,
+        namedImportMap,
+        moduleAliasMap,
+        enableCache,
+        clearCache,
+        getStats,
+        clear,
+    };
+};

package/dist/core/ingestion/model/resolve.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Deterministic Resolution Functions
+ *
+ * Pure functions that resolve methods across the inheritance hierarchy
+ * using only the SemanticModel registries and HeritageMap — NO dependency
+ * on resolution-context.ts (circular dependency risk).
+ */
+import type { SymbolDefinition } from './symbol-table.js';
+import type { SemanticModel } from './semantic-model.js';
+import type { HeritageMap } from './heritage-map.js';
+import type { MroStrategy } from '../../../_shared/index.js';
+/**
+ * Gather all ancestor IDs in BFS / topological order.
+ * Returns the linearized list of ancestor IDs (excluding the class itself).
+ */
+declare function gatherAncestors(classId: string, parentMap: Map<string, string[]>): string[];
+/**
+ * Compute C3 linearization for a class given a parentMap.
+ * Returns an array of ancestor IDs in C3 order (excluding the class itself),
+ * or null if linearization fails (inconsistent or cyclic hierarchy).
+ *
+ * Used internally by `lookupMethodByOwnerWithMRO` for the Python MRO
+ * strategy and re-exported for mro-processor.ts (graph-level MRO emission).
+ */
+export declare function c3Linearize(classId: string, parentMap: Map<string, string[]>, cache: Map<string, string[] | null>, inProgress?: Set<string>): string[] | null;
+export { gatherAncestors };
+/**
+ * Look up a method on an owner class, walking the parent chain via HeritageMap
+ * when the method isn't found on the direct owner.
+ *
+ * Respects the 5 per-language MRO strategies:
+ * - `first-wins`:       BFS ancestor walk, first match wins (default)
+ * - `leftmost-base`:    BFS ancestor walk, leftmost base in declaration order wins (C++);
+ *                        HeritageMap preserves insertion order matching source declaration,
+ *                        so BFS order is equivalent to leftmost-base semantics
+ * - `c3`:               C3-linearized ancestor order, first match wins (Python)
+ * - `implements-split`: BFS ancestor walk, first match wins (Java/C#) —
+ *                        full ambiguity detection for multiple interface defaults
+ *                        is handled by computeMRO at graph level
+ * - `qualified-syntax`: No auto-resolution (Rust) — returns undefined
+ *
+ * Uses the `c3Linearize` defined in this file (also consumed by
+ * mro-processor.ts for graph-level MRO emission) for the `c3` strategy.
+ *
+ * Depends only on {@link SemanticModel} + {@link HeritageMap} + an
+ * {@link MroStrategy} literal — NO dependency on SymbolTable, the language
+ * registry, or resolution-context, which keeps the `model/` module free of
+ * cross-layer imports. Callers derive the strategy from their language
+ * provider before invoking this function.
+ *
+ * @internal This is the low-level MRO walker. Exported so call-processor's
+ * higher-level resolvers (and unit tests) can invoke it directly. Callers
+ * outside `core/ingestion/` should use the higher-level resolvers in
+ * call-processor.ts instead of depending on this function.
+ */
+export declare const lookupMethodByOwnerWithMRO: (ownerNodeId: string, methodName: string, heritageMap: HeritageMap, model: SemanticModel, strategy: MroStrategy, argCount?: number) => SymbolDefinition | undefined;

package/dist/core/ingestion/model/resolve.js

@@ -0,0 +1,242 @@
+/**
+ * Deterministic Resolution Functions
+ *
+ * Pure functions that resolve methods across the inheritance hierarchy
+ * using only the SemanticModel registries and HeritageMap — NO dependency
+ * on resolution-context.ts (circular dependency risk).
+ */
+// ---------------------------------------------------------------------------
+// MRO primitives.
+//
+// `c3Linearize` and its BFS helper `gatherAncestors` live here so the model
+// layer stays a pure leaf — mro-processor.ts (graph-level MRO emission)
+// imports `c3Linearize` from this file.
+// ---------------------------------------------------------------------------
+/**
+ * Gather all ancestor IDs in BFS / topological order.
+ * Returns the linearized list of ancestor IDs (excluding the class itself).
+ */
+function gatherAncestors(classId, parentMap) {
+    const visited = new Set();
+    const order = [];
+    const queue = [...(parentMap.get(classId) ?? [])];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        order.push(id);
+        const grandparents = parentMap.get(id);
+        if (grandparents) {
+            for (const gp of grandparents) {
+                if (!visited.has(gp))
+                    queue.push(gp);
+            }
+        }
+    }
+    return order;
+}
+/**
+ * Compute C3 linearization for a class given a parentMap.
+ * Returns an array of ancestor IDs in C3 order (excluding the class itself),
+ * or null if linearization fails (inconsistent or cyclic hierarchy).
+ *
+ * Used internally by `lookupMethodByOwnerWithMRO` for the Python MRO
+ * strategy and re-exported for mro-processor.ts (graph-level MRO emission).
+ */
+export function c3Linearize(classId, parentMap, cache, inProgress) {
+    if (cache.has(classId))
+        return cache.get(classId);
+    // Cycle detection: if we're already computing this class, the hierarchy is cyclic
+    const visiting = inProgress ?? new Set();
+    if (visiting.has(classId)) {
+        cache.set(classId, null);
+        return null;
+    }
+    visiting.add(classId);
+    const directParents = parentMap.get(classId);
+    if (!directParents || directParents.length === 0) {
+        visiting.delete(classId);
+        cache.set(classId, []);
+        return [];
+    }
+    // Compute linearization for each parent first
+    const parentLinearizations = [];
+    for (const pid of directParents) {
+        const pLin = c3Linearize(pid, parentMap, cache, visiting);
+        if (pLin === null) {
+            visiting.delete(classId);
+            cache.set(classId, null);
+            return null;
+        }
+        parentLinearizations.push([pid, ...pLin]);
+    }
+    // Add the direct parents list as the final sequence
+    const sequences = [...parentLinearizations, [...directParents]];
+    const result = [];
+    while (sequences.some((s) => s.length > 0)) {
+        // Find a good head: one that doesn't appear in the tail of any other sequence
+        let head = null;
+        for (const seq of sequences) {
+            if (seq.length === 0)
+                continue;
+            const candidate = seq[0];
+            const inTail = sequences.some((other) => other.length > 1 && other.indexOf(candidate, 1) !== -1);
+            if (!inTail) {
+                head = candidate;
+                break;
+            }
+        }
+        if (head === null) {
+            // Inconsistent hierarchy
+            visiting.delete(classId);
+            cache.set(classId, null);
+            return null;
+        }
+        result.push(head);
+        // Remove the chosen head from all sequences
+        for (const seq of sequences) {
+            if (seq.length > 0 && seq[0] === head) {
+                seq.shift();
+            }
+        }
+    }
+    visiting.delete(classId);
+    cache.set(classId, result);
+    return result;
+}
+// `gatherAncestors` is exported so mro-processor.ts can reuse the same
+// BFS traversal for graph-level MRO emission.
+export { gatherAncestors };
+// ---------------------------------------------------------------------------
+// C3 linearization cache (per HeritageMap, auto-drained via WeakMap)
+// ---------------------------------------------------------------------------
+/**
+ * Per-HeritageMap cache of C3 linearization results keyed by owner nodeId.
+ *
+ * HeritageMap instances are immutable after construction, so C3 output is
+ * stable for the lifetime of a HeritageMap. WeakMap lets the cache auto-drain
+ * when the HeritageMap is garbage collected (end of ingestion run), so we
+ * never need to manually invalidate it.
+ *
+ * `null` is a sentinel for "C3 failed for this owner" (cyclic or inconsistent
+ * hierarchy) so we don't re-run the expensive linearization repeatedly.
+ */
+const c3LinearizationCache = new WeakMap();
+const getCachedC3Linearization = (ownerNodeId, heritageMap) => {
+    let perHmCache = c3LinearizationCache.get(heritageMap);
+    if (!perHmCache) {
+        perHmCache = new Map();
+        c3LinearizationCache.set(heritageMap, perHmCache);
+    }
+    const cached = perHmCache.get(ownerNodeId);
+    if (cached !== undefined)
+        return cached;
+    const parentMap = buildParentMapFromHeritage(ownerNodeId, heritageMap);
+    const result = c3Linearize(ownerNodeId, parentMap, new Map()) ?? null;
+    perHmCache.set(ownerNodeId, result);
+    return result;
+};
+// ---------------------------------------------------------------------------
+// Heritage → parentMap conversion
+// ---------------------------------------------------------------------------
+/**
+ * Build a parentMap from HeritageMap for use with c3Linearize.
+ * Traverses the parent chain starting from startNodeId, collecting all
+ * parent→children relationships into a Map<string, string[]>.
+ *
+ * Uses a head-pointer BFS (queue[head++]) instead of Array.shift() to avoid
+ * O(n) per-dequeue re-indexing. For wide/shallow hierarchies common in
+ * large Java/C# codebases this keeps the walk linear in ancestor count.
+ */
+const buildParentMapFromHeritage = (startNodeId, heritageMap) => {
+    const parentMap = new Map();
+    const visited = new Set();
+    const queue = [startNodeId];
+    let head = 0;
+    while (head < queue.length) {
+        const nodeId = queue[head++];
+        if (visited.has(nodeId))
+            continue;
+        visited.add(nodeId);
+        const parents = heritageMap.getParents(nodeId);
+        if (parents.length > 0) {
+            parentMap.set(nodeId, parents);
+            for (const p of parents) {
+                if (!visited.has(p))
+                    queue.push(p);
+            }
+        }
+    }
+    return parentMap;
+};
+// ---------------------------------------------------------------------------
+// MRO-aware method lookup
+// ---------------------------------------------------------------------------
+/**
+ * Look up a method on an owner class, walking the parent chain via HeritageMap
+ * when the method isn't found on the direct owner.
+ *
+ * Respects the 5 per-language MRO strategies:
+ * - `first-wins`:       BFS ancestor walk, first match wins (default)
+ * - `leftmost-base`:    BFS ancestor walk, leftmost base in declaration order wins (C++);
+ *                        HeritageMap preserves insertion order matching source declaration,
+ *                        so BFS order is equivalent to leftmost-base semantics
+ * - `c3`:               C3-linearized ancestor order, first match wins (Python)
+ * - `implements-split`: BFS ancestor walk, first match wins (Java/C#) —
+ *                        full ambiguity detection for multiple interface defaults
+ *                        is handled by computeMRO at graph level
+ * - `qualified-syntax`: No auto-resolution (Rust) — returns undefined
+ *
+ * Uses the `c3Linearize` defined in this file (also consumed by
+ * mro-processor.ts for graph-level MRO emission) for the `c3` strategy.
+ *
+ * Depends only on {@link SemanticModel} + {@link HeritageMap} + an
+ * {@link MroStrategy} literal — NO dependency on SymbolTable, the language
+ * registry, or resolution-context, which keeps the `model/` module free of
+ * cross-layer imports. Callers derive the strategy from their language
+ * provider before invoking this function.
+ *
+ * @internal This is the low-level MRO walker. Exported so call-processor's
+ * higher-level resolvers (and unit tests) can invoke it directly. Callers
+ * outside `core/ingestion/` should use the higher-level resolvers in
+ * call-processor.ts instead of depending on this function.
+ */
+export const lookupMethodByOwnerWithMRO = (ownerNodeId, methodName, heritageMap, model, strategy, argCount) => {
+    // Direct lookup first (child override — no walk needed).
+    // argCount is threaded through so arity-differing overloads on the direct
+    // owner can be disambiguated before the MRO walk starts.
+    const direct = model.methods.lookupMethodByOwner(ownerNodeId, methodName, argCount);
+    if (direct)
+        return direct;
+    // Rust: requires qualified syntax (<Type as Trait>::method), no auto-resolution
+    if (strategy === 'qualified-syntax')
+        return undefined;
+    // Determine ancestor walk order based on MRO strategy.
+    // readonly to accept the cached (frozen) c3 linearization without copying.
+    let ancestors;
+    if (strategy === 'c3') {
+        // C3 linearization (memoized per HeritageMap
+        // so repeated calls for the same owner within an ingestion run reuse the
+        // linearization instead of rebuilding the parent map and re-running C3).
+        // c3Linearize returns ancestors only (excludes the owner itself),
+        // matching heritageMap.getAncestors() semantics.
+        const c3Result = getCachedC3Linearization(ownerNodeId, heritageMap);
+        // Fall back to BFS order if C3 fails (cyclic or inconsistent hierarchy).
+        // Note: BFS order may not preserve Python MRO semantics in these edge
+        // cases, but cyclic/inconsistent hierarchies are invalid in Python anyway.
+        ancestors = c3Result ?? heritageMap.getAncestors(ownerNodeId);
+    }
+    else {
+        // first-wins, leftmost-base, implements-split: BFS order via HeritageMap
+        ancestors = heritageMap.getAncestors(ownerNodeId);
+    }
+    // Walk ancestors in MRO order — first match wins.
+    // argCount narrows overloaded ancestors the same way as the direct lookup.
+    for (const ancestorId of ancestors) {
+        const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+        if (method)
+            return method;
+    }
+    return undefined;
+};