gitnexus 1.6.5-rc.8 → 1.6.5

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.d.ts

@@ -87,6 +87,9 @@
  *     attempting emission (even on dedup-collapse), because the
  *     per-(caller, target) collapse semantics require multiple call
  *     sites in the same caller body not produce multiple edges.
+ *     `preEmitInheritanceEdges` also pre-marks every `inherits` site so
+ *     the generic bridge cannot remap class heritage into method-owned
+ *     EXTENDS edges via `resolveCallerGraphId`.
  *
  *   - **I3 — `propagateImportedReturnTypes` mutation timing + ordering.**
  *     The pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
@@ -253,6 +256,7 @@ import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
 import { LanguageProvider } from '../../language-provider.js';
 import { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import type { SemanticModel } from '../../model/semantic-model.js';
+import type { ConversionRankFn } from '../passes/overload-narrowing.js';
 /** A LinearizeStrategy receives the full ancestor map so C3-style
  *  algorithms (which need to merge each parent's MRO) can implement
  *  themselves. Python's depth-first first-seen only consumes
@@ -342,6 +346,21 @@ export interface ScopeResolver {
      * inheritance).
      */
     buildMro(graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup): Map<string, string[]>;
+    /**
+     * Optional parallel MRO that EXCLUDES mixin-like augmentation (e.g., PHP
+     * traits). Returns the inheritance-only ancestor chain — the same kind
+     * of map as `buildMro` but built only from inheritance edges (EXTENDS).
+     *
+     * Used by the shared super-branch dispatch in `receiver-bound-calls`
+     * so that `parent::method()` walks the inheritance chain only, not the
+     * trait-augmented one. PHP semantics: `parent::` explicitly bypasses
+     * traits, even when a composed trait shadows a same-named parent method.
+     *
+     * Languages without mixin-like semantics leave this undefined — callers
+     * fall back to `buildMro`/`mroFor`, which for those languages is already
+     * the inheritance chain.
+     */
+    readonly buildExtendsOnlyMro?: (graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup) => Map<string, string[]>;
     /**
      * Mutate `parsed.localDefs[i].ownerId` to point at the structural
      * owner. Python's rule: methods (Function defs whose parent scope
@@ -365,8 +384,41 @@ export interface ScopeResolver {
      * `/^super\s*\(/.test(t)`. Java returns `t === 'super'`. C++ may
      * also need `this` capture. Languages without inheritance return
      * constant `false`.
+     *
+     * For languages where the answer depends on caller context (e.g.
+     * C++, where `Base::method()` is a super call ONLY when `Base` is
+     * actually a base of the caller's enclosing class, and namespace-
+     * qualified calls like `Singleton::getInstance()` must NOT be
+     * misclassified), implement the optional `isSuperReceiverInContext`
+     * variant below. The receiver-bound-calls pass prefers the context-
+     * aware variant when both are defined.
      */
     isSuperReceiver(receiverText: string): boolean;
+    /**
+     * Optional context-aware variant of `isSuperReceiver`. When defined,
+     * the receiver-bound-calls pass prefers this hook over the simple
+     * `isSuperReceiver(text)` form. Languages where super classification
+     * is purely text-driven (Python, Java, PHP) omit this hook and the
+     * simple form is used unchanged.
+     *
+     * C++ uses this to distinguish `Base::method()` (super call when
+     * `Base` is in the caller's MRO) from `Singleton::getInstance()`
+     * (ordinary namespace-qualified call). Without this, the regex
+     * heuristic `/^[A-Z]\w*::/` misclassifies any uppercase-qualified
+     * call as a super-receiver call and routes it through the wrong
+     * resolution branch.
+     *
+     * Returns `true` ONLY when:
+     *   - the receiver text parses as `<Name>::<...>` (or another super-
+     *     form the language recognizes), AND
+     *   - `<Name>` resolves (via scope chain) to a class-like def, AND
+     *   - that class is in the MRO of the caller's enclosing class.
+     *
+     * Returns `false` for namespace-qualified calls, unresolved names,
+     * class-qualified calls where the class is NOT in the caller's MRO,
+     * and any text the simple `isSuperReceiver` hook also rejects.
+     */
+    readonly isSuperReceiverInContext?: (receiverText: string, callerScope: ScopeId, scopes: ScopeResolutionIndexes) => boolean;
     /**
      * Whether the orchestrator should run `propagateImportedReturnTypes`
      * after finalize. Default `true`. TypeScript with explicit type
@@ -414,6 +466,19 @@ export interface ScopeResolver {
      * but is too loose as a default for strict module systems.
      */
     readonly allowGlobalFreeCallFallback?: boolean;
+    /**
+     * Optional per-slot conversion-rank function for overload resolution.
+     * When provided, `narrowOverloadCandidates` uses ranked scoring as a
+     * fallback when the exact-type filter produces no match. The function
+     * returns a numeric cost (0 = exact, 1 = promotion, 2 = standard
+     * conversion, Infinity = incompatible) for converting an argument
+     * type to a parameter type.
+     *
+     * The conversion-rank table is language-specific (issue #1578 pitfall:
+     * keep it out of shared overload-narrowing). C++ provides
+     * `cppConversionRank`; other languages define their own if needed.
+     */
+    readonly conversionRankFn?: ConversionRankFn;
     /**
      * Optional predicate to identify definitions with file-local linkage
      * (e.g. C `static` functions). When provided, `pickUniqueGlobalCallable`
@@ -425,6 +490,88 @@ export interface ScopeResolver {
      * Languages without file-local linkage semantics leave this undefined.
      */
     readonly isFileLocalDef?: (def: SymbolDefinition) => boolean;
+    /**
+     * Optional predicate to gate free-call fallback emission by caller-side
+     * visibility. When provided, `pickUniqueGlobalCallable` rejects candidates
+     * the caller cannot legally reach — e.g., a PHP function in a different
+     * namespace with no `use function` import, which PHP runtime would treat
+     * as `Call to undefined function`. Returning `false` blocks the candidate;
+     * returning `true` allows it; undefined-default keeps current behavior
+     * (no visibility filtering, equivalent to "all candidates visible").
+     *
+     * The hook receives the caller's `ParsedFile` (so it can consult
+     * `parsedImports`, `moduleScope`, etc.) and the candidate `SymbolDefinition`.
+     * The predicate must be pure: same inputs → same answer.
+     *
+     * Languages without namespace-scoped function resolution leave this undefined.
+     */
+    readonly isCallableVisibleFromCaller?: (ctx: {
+        readonly callerParsed: ParsedFile;
+        readonly candidate: SymbolDefinition;
+        /** Caller's enclosing scope id. Languages that gate visibility on
+         *  caller scope (e.g. C++ two-phase template lookup) consult it;
+         *  others ignore. Optional so existing implementations stay valid. */
+        readonly callerScope?: ScopeId;
+        /** ScopeResolutionIndexes for scope-tree walks. Optional for the
+         *  same reason as `callerScope`. */
+        readonly scopes?: ScopeResolutionIndexes;
+    }) => boolean;
+    /**
+     * Optional argument-dependent-lookup (ADL / Koenig lookup) hook for
+     * languages with C++-style associated-namespace candidate addition.
+     *
+     * Runs in the free-call fallback alongside ordinary unqualified lookup.
+     * The fallback merges ordinary candidates with ADL candidates and applies
+     * overload narrowing over the union.
+     *
+     * The hook inspects the call site's argument types, computes the
+     * associated namespace set, and returns either:
+     *   - an array of candidate `SymbolDefinition`s to add to the
+     *     ordinary-lookup candidate pool.
+     *   - `undefined` when ADL contributes no candidates.
+     *
+     * Languages without C++-style ADL leave this undefined. The
+     * cross-language contract is "additive tier" — defining the hook never
+     * removes candidates the prior tier would have produced.
+     */
+    readonly resolveAdlCandidates?: (site: {
+        readonly name: string;
+        readonly arity?: number;
+        readonly argumentTypes?: readonly string[];
+        readonly atRange: {
+            readonly startLine: number;
+            readonly startCol: number;
+        };
+    }, callerParsed: ParsedFile, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[]) => readonly SymbolDefinition[] | undefined;
+    /**
+     * Optional resolver for qualified-receiver member calls where the
+     * receiver is a namespace (not a class) and ordinary scope-chain /
+     * import resolution doesn't find the member. C++ uses this for
+     * `outer::foo()` style calls and to walk through inline-namespace
+     * children transitively (`outer::v1::foo` reachable as `outer::foo`).
+     *
+     * Languages whose qualified-name semantics are already covered by the
+     * receiver-bound-calls Case-1 namespace-targets path (e.g., Python's
+     * `import X; X.foo()`) leave this undefined.
+     *
+     * Receiver-bound-calls invokes this hook AFTER Case 1 (namespace
+     * imports) and AFTER Case 2 (class-name receiver) fail to resolve.
+     * Returns the target def, `'ambiguous'` when multiple inline-namespace
+     * children declare the same name (suppresses edge emission), or
+     * `undefined` to fall through to the remaining cases.
+     */
+    readonly resolveQualifiedReceiverMember?: (receiverName: string, memberName: string, callerScope: ScopeId, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[]) => SymbolDefinition | 'ambiguous' | undefined;
+    /**
+     * Enable the receiver-bound Case 0.5 fallback for explicit `this`
+     * receivers (`this->m()` / `this.m()`) that resolves against the
+     * enclosing class + MRO even when no explicit `this` typeBinding is
+     * present in scope.
+     *
+     * Keep disabled for languages where the existing type-binding path
+     * (Case 4) already handles `this` correctly and overload ambiguity
+     * suppression must remain unchanged.
+     */
+    readonly resolveThisViaEnclosingClass?: boolean;
     /**
      * Optional post-finalize hook to inject cross-file bindings that
      * aren't modeled via explicit imports. Runs after
@@ -501,4 +648,24 @@ export interface ScopeResolver {
             get(filePath: string): unknown;
         };
     }) => void;
+    /**
+     * Optional post-resolution pass: emit CALLS edges for member-call sites
+     * whose receiver cannot be typed by the scope chain (no `TypeRef`).
+     * Dynamically-typed languages with untyped/`mixed`/`Any` parameters use
+     * this hook to recover the call edge via workspace-wide method-name
+     * lookup, mirroring what their legacy resolvers did.
+     *
+     * Runs AFTER `emitReceiverBoundCalls` and BEFORE `emitFreeCallFallback`.
+     * Implementations MUST:
+     *   - Skip sites already in `handledSites` (Invariant I2).
+     *   - Add resolved site keys to `handledSites` before returning.
+     *   - Stay narrow: a unique workspace-wide match is the safe baseline.
+     *     Multi-candidate fallbacks should narrow by arity / argument types
+     *     before emitting to keep false-positive rate bounded.
+     *
+     * Returns the number of edges emitted (for telemetry).
+     *
+     * Default: undefined (no unresolved-receiver fallback).
+     */
+    readonly emitUnresolvedReceiverEdges?: (graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, handledSites: Set<string>, model: SemanticModel) => number;
 }

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.js

@@ -87,6 +87,9 @@
  *     attempting emission (even on dedup-collapse), because the
  *     per-(caller, target) collapse semantics require multiple call
  *     sites in the same caller body not produce multiple edges.
+ *     `preEmitInheritanceEdges` also pre-marks every `inherits` site so
+ *     the generic bridge cannot remap class heritage into method-owned
+ *     EXTENDS edges via `resolveCallerGraphId`.
  *
  *   - **I3 — `propagateImportedReturnTypes` mutation timing + ordering.**
  *     The pass mutates `Scope.typeBindings` (a plain `new Map(...)` from

package/dist/core/ingestion/scope-resolution/graph-bridge/ids.d.ts

@@ -40,6 +40,7 @@ export declare function resolveDefGraphId(filePath: string, def: {
     qualifiedName?: string;
     type?: NodeLabel;
     parameterTypes?: readonly string[];
+    templateArguments?: readonly string[];
 }, nodeLookup: GraphNodeLookup): string | undefined;
 /** Derive the simple (unqualified) name of a def from its `qualifiedName`. */
 export declare function simpleQualifiedName(def: SymbolDefinition): string | undefined;

package/dist/core/ingestion/scope-resolution/graph-bridge/ids.js

@@ -79,6 +79,18 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
             if (pHit !== undefined)
                 return pHit;
         }
+        if ((def.type === 'Class' ||
+            def.type === 'Struct' ||
+            def.type === 'Interface' ||
+            def.type === 'Enum' ||
+            def.type === 'Record') &&
+            def.templateArguments !== undefined &&
+            def.templateArguments.length > 0) {
+            const tKey = qualifiedKey(filePath, def.type, `${qn}~${def.templateArguments.join(',')}`);
+            const tHit = nodeLookup.get(tKey);
+            if (tHit !== undefined)
+                return tHit;
+        }
         const qualifiedHit = nodeLookup.get(qualifiedKey(filePath, def.type, qn));
         if (qualifiedHit !== undefined)
             return qualifiedHit;

package/dist/core/ingestion/scope-resolution/graph-bridge/method-dispatch.d.ts

@@ -16,4 +16,4 @@
  * can extend the return shape without breaking existing consumers.
  */
 import type { MethodDispatchIndex } from '../../../../_shared/index.js';
-export declare function buildPopulatedMethodDispatch(mroByDefId: ReadonlyMap<string, readonly string[]>): MethodDispatchIndex;
+export declare function buildPopulatedMethodDispatch(mroByDefId: ReadonlyMap<string, readonly string[]>, extendsOnlyMroByDefId?: ReadonlyMap<string, readonly string[]>): MethodDispatchIndex;

package/dist/core/ingestion/scope-resolution/graph-bridge/method-dispatch.js

@@ -16,8 +16,8 @@
  * can extend the return shape without breaking existing consumers.
  */
 const EMPTY_DEFS = Object.freeze([]);
-export function buildPopulatedMethodDispatch(mroByDefId) {
-    return {
+export function buildPopulatedMethodDispatch(mroByDefId, extendsOnlyMroByDefId) {
+    const base = {
         mroByOwnerDefId: mroByDefId,
         implsByInterfaceDefId: new Map(),
         mroFor(ownerDefId) {
@@ -27,4 +27,14 @@ export function buildPopulatedMethodDispatch(mroByDefId) {
             return EMPTY_DEFS;
         },
     };
+    if (extendsOnlyMroByDefId !== undefined) {
+        return {
+            ...base,
+            extendsOnlyMroByOwnerDefId: extendsOnlyMroByDefId,
+            extendsOnlyMroFor(ownerDefId) {
+                return extendsOnlyMroByDefId.get(ownerDefId) ?? EMPTY_DEFS;
+            },
+        };
+    }
+    return base;
 }

package/dist/core/ingestion/scope-resolution/graph-bridge/node-lookup.js

@@ -86,6 +86,17 @@ export function buildGraphNodeLookup(graph) {
                 // Each overload is unique — set unconditionally.
                 lookup.set(pKey, node.id);
             }
+            if ((node.label === 'Class' ||
+                node.label === 'Struct' ||
+                node.label === 'Interface' ||
+                node.label === 'Enum' ||
+                node.label === 'Record') &&
+                props.templateArguments !== undefined &&
+                props.templateArguments.length > 0) {
+                const tKey = qualifiedKey(props.filePath, node.label, `${qualified}~${props.templateArguments.join(',')}`);
+                if (!lookup.has(tKey))
+                    lookup.set(tKey, node.id);
+            }
         }
         // Fallback key: simple name. First-wins within a file — used when
         // the caller doesn't know the qualifier (unqualified free-call
@@ -105,6 +116,11 @@ export function isLinkableLabel(label) {
         label === 'Interface' ||
         label === 'Struct' ||
         label === 'Enum' ||
+        // Trait nodes are linkable so MRO builders can bridge PHP/Rust trait
+        // defs between scope-resolution DefIds and the graph's node ids.
+        // IMPLEMENTS edges from classes to traits are otherwise invisible to
+        // the scope-resolution MRO pass.
+        label === 'Trait' ||
         // Variable / Property are linkable too — receiver-bound write/read
         // ACCESSES edges target field nodes (e.g. `user.name = "x"` →
         // ACCESSES edge to User's `name` Variable/Property node).

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

@@ -22,9 +22,45 @@ import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexe
 import type { SemanticModel } from '../../model/semantic-model.js';
 import type { WorkspaceResolutionIndex } from '../workspace-index.js';
 import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+import { type ConversionRankFn } from './overload-narrowing.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, options?: {
     readonly allowGlobalFallback?: boolean;
     readonly isFileLocalDef?: (def: SymbolDefinition) => boolean;
+    readonly isCallableVisibleFromCaller?: (ctx: {
+        readonly callerParsed: ParsedFile;
+        readonly candidate: SymbolDefinition;
+        readonly callerScope?: ScopeId;
+        readonly scopes?: ScopeResolutionIndexes;
+    }) => boolean;
+    readonly resolveAdlCandidates?: (site: {
+        readonly name: string;
+        readonly arity?: number;
+        readonly argumentTypes?: readonly string[];
+        readonly atRange: {
+            readonly startLine: number;
+            readonly startCol: number;
+        };
+    }, callerParsed: ParsedFile, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[]) => readonly SymbolDefinition[] | undefined;
+    readonly conversionRankFn?: ConversionRankFn;
 }): number;
+/** 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 declare function pickImplicitThisOverload(site: {
+    readonly inScope: ScopeId;
+    readonly name: string;
+    readonly arity?: number;
+    readonly argumentTypes?: readonly string[];
+}, scopes: ScopeResolutionIndexes, workspaceIndex: WorkspaceResolutionIndex, model: SemanticModel, conversionRankFn?: ConversionRankFn): SymbolDefinition | undefined;

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

@@ -17,8 +17,8 @@
  * generalization plan.
  */
 import { resolveCallerGraphId, resolveDefGraphId } from '../graph-bridge/ids.js';
-import { findCallableBindingInScope, findClassBindingInScope } from '../scope/walkers.js';
-import { narrowOverloadCandidates } from './overload-narrowing.js';
+import { findAllCallableBindingsInScope, findCallableBindingInScope, findCallableBindingsAndAdlBlocker, findClassBindingInScope, } from '../scope/walkers.js';
+import { isOverloadAmbiguousAfterNormalization, narrowOverloadCandidates, } from './overload-narrowing.js';
 export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _referenceIndex, handledSites, model, workspaceIndex, options = {}) {
     let emitted = 0;
     const seen = new Set();
@@ -45,17 +45,134 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
             // the same name in a single class, choose the best match by
             // arity + argument types.
             if (fnDef === undefined) {
-                fnDef = pickImplicitThisOverload(site, scopes, workspaceIndex, model);
+                fnDef = pickImplicitThisOverload(site, scopes, workspaceIndex, model, options.conversionRankFn);
             }
+            // Scope-chain callable lookup. First-match preserves scope-chain
+            // precedence (local shadows import). When a conversion-rank function
+            // is available AND the binding scope contains multiple overloads,
+            // refine with `narrowOverloadCandidates` to pick the best overload
+            // by argument types (#1578). The first-match result is kept as a
+            // fallback when narrowing is indeterminate.
             if (fnDef === undefined) {
-                fnDef = findCallableBindingInScope(site.inScope, site.name, scopes);
+                if (options.resolveAdlCandidates === undefined) {
+                    // Non-ADL path: first-match preserves scope-chain precedence
+                    // (local shadows import). When a conversion-rank function is
+                    // available AND the binding scope contains multiple overloads,
+                    // refine with narrowOverloadCandidates (#1578).
+                    fnDef = findCallableBindingInScope(site.inScope, site.name, scopes);
+                    if (fnDef !== undefined && options.conversionRankFn !== undefined) {
+                        const allCallables = findAllCallableBindingsInScope(site.inScope, site.name, scopes);
+                        if (allCallables.length > 1) {
+                            const narrowed = narrowOverloadCandidates(allCallables, site.arity, site.argumentTypes, options.conversionRankFn);
+                            if (narrowed.length === 1) {
+                                fnDef = narrowed[0];
+                            }
+                            else if (narrowed.length > 1) {
+                                // Multiple survivors after conversion-rank scoring.
+                                // Suppress when all candidates share the same file (true
+                                // overloads) — mirrors ADL merged-candidate path behavior.
+                                // Cross-file candidates are shadowing; keep first-match.
+                                const sameFile = narrowed.every((d) => d.filePath === narrowed[0].filePath);
+                                if (sameFile) {
+                                    handledSites.add(`${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`);
+                                    continue;
+                                }
+                            }
+                            // narrowed.length === 0: keep the first-match fnDef —
+                            // preserves local-shadows-import.
+                        }
+                    }
+                }
+                else {
+                    // ADL path: ISO C++ `[basic.lookup.unqual]` §7 — ADL is suppressed
+                    // when ordinary lookup finds a non-function name or a block-scope
+                    // function declaration.
+                    const { callables: ordinary, nonCallableFound, blockScopeDeclFound, } = findCallableBindingsAndAdlBlocker(site.inScope, site.name, scopes);
+                    const adlSuppressed = nonCallableFound || blockScopeDeclFound;
+                    const adl = adlSuppressed
+                        ? undefined
+                        : options.resolveAdlCandidates({
+                            name: site.name,
+                            arity: site.arity,
+                            argumentTypes: site.argumentTypes,
+                            atRange: { startLine: site.atRange.startLine, startCol: site.atRange.startCol },
+                        }, parsed, scopes, parsedFiles);
+                    // When ADL contributed no candidates, narrow ordinary candidates
+                    // with conversion-rank scoring when multiple overloads exist.
+                    // Single candidate or empty falls through to first-match.
+                    if (adl === undefined || adl.length === 0) {
+                        if (ordinary.length <= 1 || options.conversionRankFn === undefined) {
+                            fnDef = ordinary[0];
+                        }
+                        else {
+                            const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`;
+                            const narrowed = narrowOverloadCandidates(ordinary, site.arity, site.argumentTypes, options.conversionRankFn);
+                            if (narrowed.length === 1) {
+                                fnDef = narrowed[0];
+                            }
+                            else if (narrowed.length > 1) {
+                                // Multiple survivors — suppress when same-file (true
+                                // overloads), mirrors ADL merged-candidate behavior.
+                                const sameFile = narrowed.every((d) => d.filePath === narrowed[0].filePath);
+                                if (sameFile) {
+                                    handledSites.add(siteKey);
+                                    continue;
+                                }
+                                fnDef = ordinary[0]; // cross-file shadowing → first-match
+                            }
+                            else {
+                                fnDef = ordinary[0]; // narrowed empty → first-match
+                            }
+                        }
+                    }
+                    else {
+                        const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`;
+                        const merged = [];
+                        const seenMerge = new Set();
+                        const push = (defs) => {
+                            for (const d of defs) {
+                                if (seenMerge.has(d.nodeId))
+                                    continue;
+                                seenMerge.add(d.nodeId);
+                                merged.push(d);
+                            }
+                        };
+                        push(ordinary);
+                        push(adl);
+                        const narrowed = narrowOverloadCandidates(merged, site.arity, site.argumentTypes, options.conversionRankFn);
+                        if (narrowed.length === 1) {
+                            fnDef = narrowed[0];
+                        }
+                        else if (narrowed.length === 0) {
+                            handledSites.add(siteKey);
+                            continue;
+                        }
+                        else if (narrowed.length > 1) {
+                            if (isOverloadAmbiguousAfterNormalization(narrowed, site.arity)) {
+                                handledSites.add(siteKey);
+                                continue;
+                            }
+                            // Multiple survivors remain after conversion-rank scoring;
+                            // suppress instead of picking arbitrarily.
+                            handledSites.add(siteKey);
+                            continue;
+                        }
+                    }
+                }
             }
             // 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.
+            // usually caught by nearest-scope lookup before reaching here.
             if (fnDef === undefined && options.allowGlobalFallback === true) {
-                fnDef = pickUniqueGlobalCallable(site.name, model, scopes, parsed.filePath, options.isFileLocalDef);
+                fnDef = pickUniqueGlobalCallable(site.name, model, scopes, parsed.filePath, options.isFileLocalDef, site.arity, options.isCallableVisibleFromCaller !== undefined
+                    ? (candidate) => options.isCallableVisibleFromCaller({
+                        callerParsed: parsed,
+                        candidate,
+                        callerScope: site.inScope,
+                        scopes,
+                    })
+                    : undefined, site.argumentTypes, options.conversionRankFn);
             }
             if (fnDef === undefined)
                 continue;
@@ -88,7 +205,7 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
     }
     return emitted;
 }
-function pickUniqueGlobalCallable(name, model, scopes, callerFilePath, isFileLocalDef) {
+function pickUniqueGlobalCallable(name, model, scopes, callerFilePath, isFileLocalDef, callArity, isCallerVisible, callArgTypes, conversionRankFn) {
     const scopeDefs = [];
     const scopeSeen = new Set();
     for (const def of scopes.defs.byId.values()) {
@@ -102,6 +219,13 @@ function pickUniqueGlobalCallable(name, model, scopes, callerFilePath, isFileLoc
         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;
@@ -110,6 +234,24 @@ function pickUniqueGlobalCallable(name, model, scopes, callerFilePath, isFileLoc
     }
     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;
+    }
+    // When arity narrowing left >1 candidate, try overload narrowing with
+    // argument types + conversion ranking (#1578). This picks the unique
+    // best-rank candidate when exact-type or conversion-rank scoring can
+    // disambiguate (e.g., `f(int)` vs `f(double)` called with `f(2.5)`).
+    if (scopeDefs.length > 1) {
+        const narrowed = narrowOverloadCandidates(scopeDefs, callArity, callArgTypes, conversionRankFn);
+        if (narrowed.length === 1)
+            return narrowed[0];
+    }
     const defs = [];
     const seen = new Set();
     const push = (pool) => {
@@ -120,6 +262,10 @@ function pickUniqueGlobalCallable(name, model, scopes, callerFilePath, isFileLoc
             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;
@@ -129,7 +275,38 @@ function pickUniqueGlobalCallable(name, model, scopes, callerFilePath, isFileLoc
     };
     push(model.symbols.lookupCallableByName(name));
     push(model.methods.lookupMethodByName(name));
-    return defs.length === 1 ? defs[0] : undefined;
+    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;
+    }
+    // Same argument-type + conversion-rank narrowing for the model pool.
+    if (defs.length > 1) {
+        const narrowed = narrowOverloadCandidates(defs, callArity, callArgTypes, conversionRankFn);
+        if (narrowed.length === 1)
+            return narrowed[0];
+    }
+    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 [
@@ -157,10 +334,18 @@ function pickConstructorOrClass(classDef, workspaceIndex) {
 }
 /** 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) {
+ *  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, conversionRankFn) {
     // Find the enclosing Class scope by walking parents.
     let curId = site.inScope;
     let classScopeId;
@@ -185,6 +370,12 @@ function pickImplicitThisOverload(site, scopes, workspaceIndex, model) {
         return undefined;
     if (overloads.length === 1)
         return overloads[0];
-    const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes);
+    // 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, conversionRankFn);
+    if (candidates.length !== 1)
+        return undefined;
     return candidates[0];
 }

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

@@ -140,7 +140,7 @@ export function propagateImportedReturnTypes(parsedFiles, indexes, index) {
                     continue;
                 const refs = lookupBindingsAt(importerModule.id, localName, indexes);
                 for (const ref of refs) {
-                    if (ref.origin !== 'import' && ref.origin !== 'reexport')
+                    if (ref.origin !== 'import' && ref.origin !== 'reexport' && ref.origin !== 'wildcard')
                         continue;
                     const sourceModule = moduleScopeByFile.get(ref.def.filePath);
                     if (sourceModule === undefined)