gitnexus 1.6.5-rc.9 → 1.6.5

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

@@ -13,14 +13,65 @@
  *   2. Exact-required-match wins over variadic. Variadic is detected
  *      via a `parameterTypes` entry equal to `'params'` or starting
  *      with `'params '` (C# `params` / variadic marker).
- *   3. If the arity filter empties the set, fall back to the full
- *      overload list rather than returning nothing — the caller still
- *      needs a best-effort candidate.
+ *   3. If the arity filter empties the set AND any candidate had
+ *      unknown bounds (both `parameterCount` and `requiredParameterCount`
+ *      undefined), fall back to the full overload list — the empty
+ *      result may be due to missing metadata rather than a real mismatch.
+ *      If EVERY rejected candidate had definite arity bounds, trust the
+ *      filter and return empty — the call is genuinely arity-incompatible
+ *      (e.g., PHP `f(int $req, ...$rest)` called with zero args).
  *   4. If `argTypes` is present, filter further by per-slot type
  *      equality. An empty string in `argTypes[i]` means "unknown" and
  *      counts as a match. Mismatches disqualify. A non-empty typed
  *      result wins; otherwise return the arity-filtered candidates.
+ *   4b. When the exact-type filter from step 4 returns empty AND a
+ *       `conversionRankFn` is provided, rank candidates via pairwise
+ *       dominance comparison (ISO C++ [over.ics.rank]): F1 beats F2
+ *       only when F1 is not worse for every arg and better for at
+ *       least one. Non-dominated candidates are returned; multiple
+ *       survivors are genuinely ambiguous.
  *   5. Empty input returns empty output.
  */
 import type { SymbolDefinition } from '../../../../_shared/index.js';
-export declare function narrowOverloadCandidates(overloads: readonly SymbolDefinition[], argCount: number | undefined, argTypes: readonly string[] | undefined): readonly SymbolDefinition[];
+/**
+ * Per-slot conversion-rank function. Returns a numeric cost for
+ * converting `argType` to `paramType`:
+ *   - 0 = exact match (no conversion)
+ *   - 1 = promotion (e.g. char→int, bool→int in C++)
+ *   - 2 = standard conversion (e.g. int→double)
+ *   - Infinity = incompatible types
+ *
+ * Each language provides its own implementation. The function operates
+ * on normalized type strings (output of the language's type normalizer).
+ */
+export type ConversionRankFn = (argType: string, paramType: string) => number;
+export declare function narrowOverloadCandidates(overloads: readonly SymbolDefinition[], argCount: number | undefined, argTypes: readonly string[] | undefined, conversionRankFn?: ConversionRankFn): readonly SymbolDefinition[];
+/**
+ * Detect when >1 candidate share identical `parameterTypes` after the
+ * per-language normalizer has collapsed distinct underlying types. This
+ * signals "the resolver cannot pick the right overload — the
+ * normalization that helps single-candidate flows now hides a real
+ * ambiguity" and lets callers suppress the edge rather than pick
+ * arbitrarily.
+ *
+ * Concrete trigger (PR #1520 review follow-up plan U2, Claude review
+ * Finding 5): the C++ `arity-metadata.ts` normalizer collapses `int`,
+ * `long`, `short`, `unsigned`, and `size_t` to `'int'`. Without this
+ * check, `process(int)` and `process(long)` both end up with
+ * `parameterTypes === ['int']`, and `pickOverload` arbitrarily picks
+ * the first — emitting a false CALLS edge to the wrong overload.
+ *
+ * Returns false when:
+ *   - 0 or 1 candidates (no ambiguity to detect)
+ *   - any candidate has undefined `parameterTypes` (can't compare)
+ *   - candidates differ in arity or in any parameter-type slot
+ *
+ * Other languages: this check is a precondition gate, not a behavior
+ * change for normal narrowing. Languages whose normalizers do not
+ * collapse distinct types (verified by grep over `*-arity-metadata.ts`
+ * — no `int → int` collapse outside C++) will never produce >1
+ * candidate with identical `parameterTypes` from genuinely distinct
+ * declarations, so this returns false for them. The branch is
+ * effectively C++-only in practice.
+ */
+export declare function isOverloadAmbiguousAfterNormalization(candidates: readonly SymbolDefinition[], argCount?: number): boolean;

package/dist/core/ingestion/scope-resolution/passes/overload-narrowing.js

@@ -13,16 +13,26 @@
  *   2. Exact-required-match wins over variadic. Variadic is detected
  *      via a `parameterTypes` entry equal to `'params'` or starting
  *      with `'params '` (C# `params` / variadic marker).
- *   3. If the arity filter empties the set, fall back to the full
- *      overload list rather than returning nothing — the caller still
- *      needs a best-effort candidate.
+ *   3. If the arity filter empties the set AND any candidate had
+ *      unknown bounds (both `parameterCount` and `requiredParameterCount`
+ *      undefined), fall back to the full overload list — the empty
+ *      result may be due to missing metadata rather than a real mismatch.
+ *      If EVERY rejected candidate had definite arity bounds, trust the
+ *      filter and return empty — the call is genuinely arity-incompatible
+ *      (e.g., PHP `f(int $req, ...$rest)` called with zero args).
  *   4. If `argTypes` is present, filter further by per-slot type
  *      equality. An empty string in `argTypes[i]` means "unknown" and
  *      counts as a match. Mismatches disqualify. A non-empty typed
  *      result wins; otherwise return the arity-filtered candidates.
+ *   4b. When the exact-type filter from step 4 returns empty AND a
+ *       `conversionRankFn` is provided, rank candidates via pairwise
+ *       dominance comparison (ISO C++ [over.ics.rank]): F1 beats F2
+ *       only when F1 is not worse for every arg and better for at
+ *       least one. Non-dominated candidates are returned; multiple
+ *       survivors are genuinely ambiguous.
  *   5. Empty input returns empty output.
  */
-export function narrowOverloadCandidates(overloads, argCount, argTypes) {
+export function narrowOverloadCandidates(overloads, argCount, argTypes, conversionRankFn) {
     if (overloads.length === 0)
         return [];
     const arityMatches = argCount === undefined
@@ -31,6 +41,16 @@ export function narrowOverloadCandidates(overloads, argCount, argTypes) {
             const max = d.parameterCount;
             const min = d.requiredParameterCount;
             if (max !== undefined && argCount > max) {
+                // Variadic marker check is C#-specific (the 'params' keyword).
+                // Other languages use their own marker — PHP uses '...' (see
+                // `languages/php/arity-metadata.ts:46`), Python uses '*args'-
+                // shaped metadata that lives outside `parameterTypes` entirely.
+                // This branch is dead code for those languages because they
+                // set `parameterCount = undefined` for variadic functions,
+                // which keeps `max` undefined and skips this check entirely.
+                // Adding new variadic markers here changes behavior for those
+                // other languages too — don't extend without auditing each
+                // adapter's `arity-metadata.ts`. Finding 9 of PR #1497.
                 const variadic = d.parameterTypes !== undefined &&
                     d.parameterTypes.some((t) => t === 'params' || t.startsWith('params '));
                 if (!variadic)
@@ -40,7 +60,13 @@ export function narrowOverloadCandidates(overloads, argCount, argTypes) {
                 return false;
             return true;
         });
-    const candidates = arityMatches.length > 0 ? arityMatches : overloads;
+    // When the arity filter empties the set, only fall back to the full
+    // overload list if some candidate had unknown bounds — otherwise the
+    // empty result is authoritative (every candidate definitively failed
+    // arity, e.g., PHP variadic with required-prefix called with too few
+    // args).
+    const anyUnknownBounds = overloads.some((d) => d.parameterCount === undefined && d.requiredParameterCount === undefined);
+    const candidates = arityMatches.length > 0 ? arityMatches : anyUnknownBounds ? overloads : [];
     if (argTypes !== undefined && argTypes.length > 0) {
         const typed = candidates.filter((d) => {
             const params = d.parameterTypes;
@@ -56,6 +82,161 @@ export function narrowOverloadCandidates(overloads, argCount, argTypes) {
         });
         if (typed.length > 0)
             return typed;
+        // ── Conversion-rank scoring (step 4b) ──────────────────────────
+        // The exact-type filter above rejected every candidate. When a
+        // per-language conversion-rank function is available, rank via
+        // pairwise dominance: F1 beats F2 only when F1 is not worse for
+        // every arg and better for at least one. Non-dominated candidates
+        // are returned; multiple survivors are genuinely ambiguous.
+        if (conversionRankFn !== undefined) {
+            const ranked = rankByConversion(candidates, argTypes, conversionRankFn);
+            if (ranked.length > 0)
+                return ranked;
+        }
     }
     return candidates;
 }
+/**
+ * Pairwise dominance comparison (ISO C++ [over.ics.rank]).
+ *
+ * F1 is a better match than F2 when F1's conversion rank is **not
+ * worse** for every argument AND **strictly better** for at least one.
+ * Candidates dominated by any other viable candidate are removed.
+ * If more than one non-dominated candidate remains, they are genuinely
+ * ambiguous — callers suppress the edge rather than picking arbitrarily.
+ *
+ * Candidates with at least one `Infinity`-ranked slot (incompatible
+ * type) are excluded before pairwise comparison begins.
+ */
+function rankByConversion(candidates, argTypes, rankFn) {
+    // Step 1: compute per-slot ranks and exclude non-viable candidates.
+    const viable = [];
+    for (const d of candidates) {
+        const params = d.parameterTypes;
+        if (params === undefined)
+            continue;
+        const ranks = [];
+        let ok = true;
+        for (let i = 0; i < argTypes.length && i < params.length; i++) {
+            if (argTypes[i] === '') {
+                ranks.push(0); // unknown arg → any-match (rank 0)
+                continue;
+            }
+            const r = rankFn(argTypes[i], params[i]);
+            if (!isFinite(r)) {
+                ok = false;
+                break;
+            }
+            ranks.push(r);
+        }
+        if (!ok)
+            continue;
+        viable.push({ def: d, ranks });
+    }
+    if (viable.length <= 1)
+        return viable.map((v) => v.def);
+    // Step 2: pairwise dominance — remove candidates dominated by any other.
+    const dominated = new Set();
+    for (let i = 0; i < viable.length; i++) {
+        if (dominated.has(i))
+            continue;
+        for (let j = i + 1; j < viable.length; j++) {
+            if (dominated.has(j))
+                continue;
+            const cmp = pairwiseCompare(viable[i].ranks, viable[j].ranks);
+            if (cmp < 0)
+                dominated.add(j); // i dominates j
+            else if (cmp > 0)
+                dominated.add(i); // j dominates i
+        }
+    }
+    return viable.filter((_, idx) => !dominated.has(idx)).map((v) => v.def);
+}
+/**
+ * Compare two per-slot rank vectors.
+ * Returns  -1 if `a` dominates `b` (not worse everywhere, better somewhere),
+ *          +1 if `b` dominates `a`,
+ *           0 if neither dominates (incomparable or equal).
+ */
+function pairwiseCompare(a, b) {
+    let aBetter = false;
+    let bBetter = false;
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        if (a[i] < b[i])
+            aBetter = true;
+        else if (b[i] < a[i])
+            bBetter = true;
+        if (aBetter && bBetter)
+            return 0; // incomparable — early exit
+    }
+    if (aBetter && !bBetter)
+        return -1;
+    if (bBetter && !aBetter)
+        return 1;
+    return 0;
+}
+/**
+ * Detect when >1 candidate share identical `parameterTypes` after the
+ * per-language normalizer has collapsed distinct underlying types. This
+ * signals "the resolver cannot pick the right overload — the
+ * normalization that helps single-candidate flows now hides a real
+ * ambiguity" and lets callers suppress the edge rather than pick
+ * arbitrarily.
+ *
+ * Concrete trigger (PR #1520 review follow-up plan U2, Claude review
+ * Finding 5): the C++ `arity-metadata.ts` normalizer collapses `int`,
+ * `long`, `short`, `unsigned`, and `size_t` to `'int'`. Without this
+ * check, `process(int)` and `process(long)` both end up with
+ * `parameterTypes === ['int']`, and `pickOverload` arbitrarily picks
+ * the first — emitting a false CALLS edge to the wrong overload.
+ *
+ * Returns false when:
+ *   - 0 or 1 candidates (no ambiguity to detect)
+ *   - any candidate has undefined `parameterTypes` (can't compare)
+ *   - candidates differ in arity or in any parameter-type slot
+ *
+ * Other languages: this check is a precondition gate, not a behavior
+ * change for normal narrowing. Languages whose normalizers do not
+ * collapse distinct types (verified by grep over `*-arity-metadata.ts`
+ * — no `int → int` collapse outside C++) will never produce >1
+ * candidate with identical `parameterTypes` from genuinely distinct
+ * declarations, so this returns false for them. The branch is
+ * effectively C++-only in practice.
+ */
+export function isOverloadAmbiguousAfterNormalization(candidates, argCount) {
+    if (candidates.length < 2)
+        return false;
+    const first = candidates[0].parameterTypes;
+    if (first === undefined)
+        return false;
+    // When argCount is provided, compare only the first `argCount` slots —
+    // this catches default-argument ambiguity: `void f(int); void f(int, int = 0);`
+    // called with `f(1)` (argCount=1) leaves both candidates viable because
+    // default args make them arity-compatible, and their first slot is
+    // identical even though full parameterTypes lengths differ.
+    // Without argCount, fall back to full-sequence comparison (the original
+    // int/long normalization-collapse case).
+    const compareUpTo = argCount !== undefined ? argCount : first.length;
+    if (compareUpTo === 0)
+        return false;
+    if (first.length < compareUpTo)
+        return false;
+    for (let i = 1; i < candidates.length; i++) {
+        const p = candidates[i].parameterTypes;
+        if (p === undefined)
+            return false;
+        if (p.length < compareUpTo)
+            return false;
+        for (let j = 0; j < compareUpTo; j++) {
+            if (p[j] !== first[j])
+                return false;
+        }
+        // When argCount is NOT provided, also require length equality so
+        // distinct-arity candidates that happen to share a prefix don't
+        // collapse to ambiguous (preserves the original int/long contract).
+        if (argCount === undefined && p.length !== first.length)
+            return false;
+    }
+    return true;
+}

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

@@ -41,6 +41,15 @@ import type { WorkspaceResolutionIndex } from '../workspace-index.js';
 /** Subset of `ScopeResolver` consumed by this pass. Accepting the
  *  subset rather than the full provider keeps tests and partial
  *  refactors lighter — callers only need to populate what we read. */
-type ReceiverBoundProviderSubset = Pick<ScopeResolver, 'isSuperReceiver' | 'fieldFallbackOnMethodLookup' | 'collapseMemberCallsByCallerTarget' | 'unwrapCollectionAccessor' | 'hoistTypeBindingsToModule'>;
+type ReceiverBoundProviderSubset = Pick<ScopeResolver, 'isSuperReceiver' | 'isSuperReceiverInContext' | 'fieldFallbackOnMethodLookup' | 'collapseMemberCallsByCallerTarget' | 'unwrapCollectionAccessor' | 'hoistTypeBindingsToModule' | 'resolveQualifiedReceiverMember' | 'resolveThisViaEnclosingClass' | 'conversionRankFn'>;
 export declare function emitReceiverBoundCalls(graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, handledSites: Set<string>, provider: ReceiverBoundProviderSubset, index: WorkspaceResolutionIndex, model: SemanticModel): number;
+/**
+ * Sentinel returned by `pickOverload` when narrowing leaves >1 candidate
+ * sharing identical normalized parameter-types. Callers should suppress
+ * the CALLS edge AND mark the site as handled so `emitReferencesViaLookup`
+ * does not re-emit from the pre-resolved reference index. See
+ * `pickOverload` JSDoc for the upstream cause (per-language normalizer
+ * collapses distinct types in arity-metadata).
+ */
+export declare const OVERLOAD_AMBIGUOUS: unique symbol;
 export {};

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

@@ -36,7 +36,49 @@ import { findClassBindingInScope, findEnclosingClassDef, findExportedDef, findOw
 import { tryEmitEdge } from '../graph-bridge/edges.js';
 import { resolveCompoundReceiverClass } from '../passes/compound-receiver.js';
 import { resolveDefGraphId } from '../graph-bridge/ids.js';
-import { narrowOverloadCandidates } from './overload-narrowing.js';
+import { narrowOverloadCandidates, isOverloadAmbiguousAfterNormalization, } from './overload-narrowing.js';
+import { extractTemplateArguments, stripTemplateArguments, } from '../../utils/template-arguments.js';
+function normalizeTemplateArgToken(value) {
+    return value.replace(/\s+/g, '');
+}
+function resolveClassBindingForName(scopeId, rawClassName, scopes) {
+    const direct = findClassBindingInScope(scopeId, rawClassName, scopes);
+    if (direct !== undefined)
+        return direct;
+    if (!rawClassName.includes('<'))
+        return undefined;
+    const baseName = stripTemplateArguments(rawClassName).replace(/\s+/g, '');
+    if (baseName.length === 0)
+        return undefined;
+    const wantedArgs = extractTemplateArguments(rawClassName)?.map(normalizeTemplateArgToken);
+    if (wantedArgs !== undefined && wantedArgs.length > 0) {
+        // qualifiedNames is a Map and may not contain the stripped base name at all
+        // (e.g., unresolved type binding or only template-qualified entries), so
+        // default to [] before checking `.length`.
+        const qnameIds = scopes.qualifiedNames.get(baseName) ?? [];
+        if (qnameIds.length === 0) {
+            return findClassBindingInScope(scopeId, baseName, scopes);
+        }
+        const matches = [];
+        for (const id of qnameIds) {
+            const def = scopes.defs.get(id);
+            if (def === undefined || !isClassLike(def.type))
+                continue;
+            const defArgs = def.templateArguments?.map(normalizeTemplateArgToken);
+            if (defArgs !== undefined &&
+                defArgs.length === wantedArgs.length &&
+                defArgs.every((value, i) => value === wantedArgs[i])) {
+                matches.push(def);
+            }
+        }
+        if (matches.length === 1)
+            return matches[0];
+        // Scope extractor only records class definitions with bodies in C++, so
+        // forward declarations are not expected here. Keep fallback behavior for
+        // safety in non-ODR or mixed-language edge cases.
+    }
+    return findClassBindingInScope(scopeId, baseName, scopes);
+}
 export function emitReceiverBoundCalls(graph, scopes, parsedFiles, nodeLookup, handledSites, provider, index, model) {
     let emitted = 0;
     // Per-pass dedup so the multiple cases don't double-emit if two of
@@ -113,10 +155,24 @@ export function emitReceiverBoundCalls(graph, scopes, parsedFiles, nodeLookup, h
             const memberName = site.name;
             const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`;
             // ── super branch ─────────────────────────────────────────────
-            if (provider.isSuperReceiver(receiverName)) {
+            // Languages with caller-context-dependent super classification
+            // (C++) define `isSuperReceiverInContext`; we prefer it. Simple
+            // text-only languages (Python, Java, PHP) use the plain hook.
+            const isSuper = provider.isSuperReceiverInContext !== undefined
+                ? provider.isSuperReceiverInContext(receiverName, site.inScope, scopes)
+                : provider.isSuperReceiver(receiverName);
+            if (isSuper) {
                 const enclosingClass = findEnclosingClassDef(site.inScope, scopes);
                 if (enclosingClass !== undefined) {
-                    const ancestors = scopes.methodDispatch.mroFor(enclosingClass.nodeId);
+                    // For super-receiver dispatch (`parent::`, `base.`, `super()`),
+                    // walk the inheritance-only ancestor chain when the language
+                    // exposes it. PHP's `parent::` semantically bypasses composed
+                    // traits; other languages without mixin augmentation have no
+                    // `extendsOnlyMroFor` and fall back to `mroFor`.
+                    const extendsOnly = scopes.methodDispatch.extendsOnlyMroFor;
+                    const ancestors = extendsOnly !== undefined
+                        ? extendsOnly(enclosingClass.nodeId)
+                        : scopes.methodDispatch.mroFor(enclosingClass.nodeId);
                     let memberDef;
                     for (const ownerId of ancestors) {
                         memberDef = findOwnedMember(ownerId, memberName, model);
@@ -176,6 +232,78 @@ export function emitReceiverBoundCalls(graph, scopes, parsedFiles, nodeLookup, h
                     }
                 }
             }
+            // ── Case 0.5: implicit `this` receiver ───────────────────────
+            // C++ `this->member()` (and same-shape receivers in other OO
+            // languages) should resolve against the enclosing class + MRO
+            // even when there is no explicit `this` typeBinding in scope.
+            if (provider.resolveThisViaEnclosingClass === true && receiverName === 'this') {
+                const enclosingClass = findEnclosingClassDef(site.inScope, scopes);
+                if (enclosingClass !== undefined) {
+                    const chain = [
+                        enclosingClass.nodeId,
+                        ...scopes.methodDispatch.mroFor(enclosingClass.nodeId),
+                    ];
+                    let memberDef;
+                    let ambiguous = false;
+                    let hiddenByName = false;
+                    for (const ownerId of chain) {
+                        const methodOverloads = model.methods.lookupAllByOwner(ownerId, memberName);
+                        if (methodOverloads.length > 0) {
+                            const narrowed = narrowOverloadCandidates(methodOverloads, site.arity, site.argumentTypes, provider.conversionRankFn);
+                            if (isOverloadAmbiguousAfterNormalization(narrowed, site.arity)) {
+                                ambiguous = true;
+                                break;
+                            }
+                            if (narrowed.length === 0) {
+                                // C++ name hiding: if the derived class declares `f`, base-class
+                                // overloads named `f` are hidden for member lookup
+                                // ([basic.lookup.classref]). A non-viable derived overload set
+                                // therefore terminates lookup instead of falling through to base.
+                                hiddenByName = true;
+                                break;
+                            }
+                            // Multiple tied survivors with distinct param types (e.g.
+                            // h(int,double) vs h(double,int) both scoring 2) → ambiguous.
+                            if (narrowed.length > 1) {
+                                ambiguous = true;
+                                break;
+                            }
+                            memberDef = narrowed[0] ?? methodOverloads[0];
+                            break;
+                        }
+                        // Field/property lookup intentionally runs only after the method
+                        // lookup above: in C++ member-name lookup, functions with this
+                        // name hide same-named base members; we therefore prefer method
+                        // candidates first and only target a field when no methods with
+                        // this name exist on the current owner.
+                        memberDef = model.fields.lookupFieldByOwner(ownerId, memberName);
+                        if (memberDef !== undefined) {
+                            break;
+                        }
+                    }
+                    if (ambiguous) {
+                        handledSites.add(siteKey);
+                        continue;
+                    }
+                    if (hiddenByName) {
+                        handledSites.add(siteKey);
+                        continue;
+                    }
+                    if (memberDef !== undefined) {
+                        const reason = site.kind === 'write' || site.kind === 'read'
+                            ? site.kind
+                            : memberDef.filePath !== parsed.filePath
+                                ? 'import-resolved'
+                                : 'global';
+                        const confidence = site.kind === 'write' || site.kind === 'read' ? 1.0 : 0.85;
+                        const ok = tryEmitEdge(graph, scopes, nodeLookup, site, memberDef, reason, seen, confidence, collapse);
+                        if (ok)
+                            emitted++;
+                        handledSites.add(siteKey);
+                        continue;
+                    }
+                }
+            }
             // ── Case 1: namespace receiver ───────────────────────────────
             const targetFiles = namespaceTargets.get(receiverName);
             if (targetFiles !== undefined) {
@@ -194,6 +322,28 @@ export function emitReceiverBoundCalls(graph, scopes, parsedFiles, nodeLookup, h
                 if (found)
                     continue;
             }
+            // ── Case 1.5: qualified namespace-receiver (language-specific) ───
+            // Languages whose qualified-name semantics need workspace-wide
+            // namespace-scope walking (C++ `outer::foo()`, including inline-
+            // namespace transitive traversal) implement `resolveQualifiedReceiverMember`.
+            // Runs before Case 2 so namespace receivers don't accidentally match a
+            // class with the same simple name.
+            if (provider.resolveQualifiedReceiverMember !== undefined) {
+                const memberDef = provider.resolveQualifiedReceiverMember(receiverName, memberName, site.inScope, scopes, parsedFiles);
+                if (memberDef === 'ambiguous') {
+                    // Same-name ambiguity across inline-namespace children (#1564):
+                    // suppress edge emission, mark site handled.
+                    handledSites.add(siteKey);
+                    continue;
+                }
+                if (memberDef !== undefined) {
+                    const ok = tryEmitEdge(graph, scopes, nodeLookup, site, memberDef, memberDef.filePath !== parsed.filePath ? 'import-resolved' : 'global', seen, 0.85, collapse);
+                    if (ok)
+                        emitted++;
+                    handledSites.add(siteKey);
+                    continue;
+                }
+            }
             // ── Case 2: class-name receiver ──────────────────────────────
             const classDef = findClassBindingInScope(site.inScope, receiverName, scopes);
             if (classDef !== undefined) {
@@ -201,8 +351,19 @@ export function emitReceiverBoundCalls(graph, scopes, parsedFiles, nodeLookup, h
                 let memberDef;
                 for (const ownerId of chain) {
                     memberDef = findOwnedMember(ownerId, memberName, model);
-                    if (memberDef !== undefined)
+                    if (memberDef !== undefined) {
+                        // The MRO chain is most-derived-first ([classDef, ...ancestors]).
+                        // If the most-derived definition is arity-incompatible with the
+                        // call site, PHP throws ArgumentCountError at runtime — it does
+                        // NOT silently dispatch to an ancestor. Terminate the chain walk
+                        // so no edge is emitted, rather than falling through to an
+                        // arity-compatible ancestor (which would be a false positive).
+                        if (narrowOverloadCandidates([memberDef], site.arity, site.argumentTypes).length === 0) {
+                            memberDef = undefined;
+                            break;
+                        }
                         break;
+                    }
                 }
                 if (memberDef !== undefined) {
                     const reason = site.kind === 'write' || site.kind === 'read'
@@ -281,7 +442,7 @@ export function emitReceiverBoundCalls(graph, scopes, parsedFiles, nodeLookup, h
             }
             // ── Case 4: simple typeBinding (`u: U`) ──────────────────────
             if (typeRef !== undefined && !typeRef.rawName.includes('.')) {
-                let ownerDef = findClassBindingInScope(site.inScope, typeRef.rawName, scopes);
+                let ownerDef = resolveClassBindingForName(site.inScope, typeRef.rawName, scopes);
                 // `findClassBindingInScope(..., typeRef.rawName)` only works when
                 // rawName is itself a class symbol reachable through scope bindings.
                 // For languages with namespace-style imports (Go), imported types
@@ -304,10 +465,24 @@ export function emitReceiverBoundCalls(graph, scopes, parsedFiles, nodeLookup, h
                 if (ownerDef !== undefined) {
                     const chain = [ownerDef.nodeId, ...scopes.methodDispatch.mroFor(ownerDef.nodeId)];
                     let memberDef;
+                    let ambiguous = false;
                     for (const ownerId of chain) {
-                        memberDef = pickOverload(ownerId, memberName, site, model);
-                        if (memberDef !== undefined)
+                        const picked = pickOverload(ownerId, memberName, site, model, provider.conversionRankFn);
+                        if (picked === OVERLOAD_AMBIGUOUS) {
+                            ambiguous = true;
                             break;
+                        }
+                        if (picked !== undefined) {
+                            memberDef = picked;
+                            break;
+                        }
+                    }
+                    if (ambiguous) {
+                        // Suppress and mark handled so `emitReferencesViaLookup`
+                        // doesn't re-emit the pre-resolved reference. See
+                        // OVERLOAD_AMBIGUOUS docstring for the upstream cause.
+                        handledSites.add(siteKey);
+                        continue;
                     }
                     if (memberDef !== undefined) {
                         // For read/write ACCESSES, mirror the legacy DAG's reason
@@ -343,7 +518,7 @@ export function emitReceiverBoundCalls(graph, scopes, parsedFiles, nodeLookup, h
  *  types when multiple overloads share the name. Falls back to the
  *  first-seen def (legacy `findOwnedMember` semantics) when there's
  *  no narrowing signal or when `argumentTypes` is unavailable. */
-function pickOverload(ownerId, memberName, site, model) {
+function pickOverload(ownerId, memberName, site, model, conversionRankFn) {
     const overloads = model.methods.lookupAllByOwner(ownerId, memberName);
     if (overloads.length === 0) {
         // Non-callable member (field / property / variable) — ACCESSES
@@ -353,6 +528,29 @@ function pickOverload(ownerId, memberName, site, model) {
     }
     if (overloads.length === 1)
         return overloads[0];
-    const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes);
+    const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes, conversionRankFn);
+    // When narrowing leaves >1 candidate that share identical normalized
+    // parameter-types (e.g., C++ `f(int)` vs `f(long)` both collapsed to
+    // `['int']` by `normalizeCppParamType`), suppress the edge entirely.
+    // The graph schema has no ambiguous-target edge model, so emitting one
+    // would arbitrarily pick a candidate and lie about the call's target.
+    // PR #1520 review follow-up plan U2 / Claude review Finding 5.
+    if (isOverloadAmbiguousAfterNormalization(candidates, site.arity))
+        return OVERLOAD_AMBIGUOUS;
+    // When conversion-rank scoring leaves >1 tied candidate with distinct
+    // parameter types (e.g. h(int,double) vs h(double,int) both scoring 2),
+    // suppress rather than picking arbitrarily — C++ would call this
+    // ambiguous. Mirrors ADL merged-candidate suppression behavior.
+    if (candidates.length > 1)
+        return OVERLOAD_AMBIGUOUS;
     return candidates[0] ?? overloads[0];
 }
+/**
+ * Sentinel returned by `pickOverload` when narrowing leaves >1 candidate
+ * sharing identical normalized parameter-types. Callers should suppress
+ * the CALLS edge AND mark the site as handled so `emitReferencesViaLookup`
+ * does not re-emit from the pre-resolved reference index. See
+ * `pickOverload` JSDoc for the upstream cause (per-language normalizer
+ * collapses distinct types in arity-metadata).
+ */
+export const OVERLOAD_AMBIGUOUS = Symbol('overload-ambiguous');

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

@@ -63,12 +63,23 @@ export const scopeResolutionPhase = {
         // Worker-mode parses leave the cache empty for those files; they
         // also fall back to a fresh parse — no correctness impact.
         const parseOutput = getPhaseOutput(deps, 'parse');
-        const { scopeTreeCache, resolutionContext } = parseOutput;
+        const { scopeTreeCache, resolutionContext, parsedFiles: workerParsedFiles } = parseOutput;
         // SemanticModel populated during `parse`: scope-resolution consumes
         // TypeRegistry / MethodRegistry / SymbolTable lookups instead of
         // rebuilding parallel indexes. See ARCHITECTURE.md § "Semantic-model
         // source of truth".
         const model = resolutionContext.model;
+        // Build a per-file lookup of ParsedFile artifacts the workers (or
+        // sequential extracts) already produced. Threading this into
+        // `runScopeResolution` lets the per-language extract loop short-
+        // circuit `extractParsedFile` — the dominant cost on the warm-cache
+        // path, since workers can't return tree-sitter Trees across the
+        // MessageChannel and scope-resolution would otherwise re-parse
+        // every file from scratch on the main thread.
+        const preExtractedByPath = new Map();
+        for (const pf of workerParsedFiles) {
+            preExtractedByPath.set(pf.filePath, pf);
+        }
         let totalFiles = 0;
         let totalImports = 0;
         let totalRefs = 0;
@@ -101,6 +112,7 @@ export const scopeResolutionPhase = {
                 files,
                 treeCache: scopeTreeCache,
                 resolutionConfig,
+                preExtractedParsedFiles: preExtractedByPath,
                 onWarn: (msg) => {
                     if (isSemanticModelValidatorEnabled()) {
                         logger.warn(`[scope-resolution:${lang}] ${msg}`);

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

@@ -13,7 +13,10 @@ import { pythonScopeResolver } from '../../languages/python/scope-resolver.js';
 import { csharpScopeResolver } from '../../languages/csharp/scope-resolver.js';
 import { typescriptScopeResolver } from '../../languages/typescript/scope-resolver.js';
 import { goScopeResolver } from '../../languages/go/scope-resolver.js';
+import { javaScopeResolver } from '../../languages/java/scope-resolver.js';
 import { cScopeResolver } from '../../languages/c/scope-resolver.js';
+import { cppScopeResolver } from '../../languages/cpp/scope-resolver.js';
+import { phpScopeResolver } from '../../languages/php/scope-resolver.js';
 /** Map of `SupportedLanguages` → `ScopeResolver`. The phase iterates
  *  this map intersected with `MIGRATED_LANGUAGES` (the per-language
  *  flag set) so adding a resolver here without flipping the flag is
@@ -23,5 +26,8 @@ export const SCOPE_RESOLVERS = new Map([
     [SupportedLanguages.CSharp, csharpScopeResolver],
     [SupportedLanguages.TypeScript, typescriptScopeResolver],
     [SupportedLanguages.Go, goScopeResolver],
+    [SupportedLanguages.Java, javaScopeResolver],
     [SupportedLanguages.C, cScopeResolver],
+    [SupportedLanguages.CPlusPlus, cppScopeResolver],
+    [SupportedLanguages.PHP, phpScopeResolver],
 ]);