gitnexus 1.6.5 → 1.6.6-rc.2

package/dist/core/ingestion/parsing-processor.js

@@ -11,7 +11,7 @@ import { getDefinitionNodeFromCaptures, findEnclosingClassInfo, getLabelFromCapt
 import { detectFrameworkFromAST } from './framework-detection.js';
 import { buildTypeEnv } from './type-env.js';
 import { buildMethodProps, arityForIdFromInfo, typeTagForId, constTagForId, buildCollisionGroups, } from './utils/method-props.js';
-import { extractTemplateArguments, templateArgumentsIdTag } from './utils/template-arguments.js';
+import { extractTemplateArguments, templateArgumentsIdTag, templateConstraintsIdTag, } from './utils/template-arguments.js';
 import { logger } from '../logger.js';
 import { getTreeSitterBufferSize, getTreeSitterContentByteLength, TREE_SITTER_MAX_BUFFER, } from './constants.js';
 // ============================================================================
@@ -57,6 +57,7 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults) => {
                 parameterCount: sym.parameterCount,
                 requiredParameterCount: sym.requiredParameterCount,
                 parameterTypes: sym.parameterTypes,
+                parameterTypeClasses: sym.parameterTypeClasses,
                 returnType: sym.returnType,
                 declaredType: sym.declaredType,
                 templateArguments: sym.templateArguments,
@@ -499,7 +500,35 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
                 classTemplateArguments.length > 0
                 ? templateArgumentsIdTag(classTemplateArguments)
                 : '';
-            const nodeId = generateId(nodeLabel, `${file.path}:${qualifiedName}${classTemplateTag}${arityTag}`);
+            // SFINAE / `requires`-clause aware ID disambiguation (issue #1579).
+            // Function-template overloads with identical parameterTypes but
+            // mutually-exclusive constraints (e.g. `enable_if_t<is_integral_v<T>>`
+            // vs `enable_if_t<is_floating_point_v<T>>`) need distinct graph
+            // nodes so the constraint-filter step in `narrowOverloadCandidates`
+            // has two candidates to narrow between. Without this tag they
+            // collapse to a single Function node and the SFINAE call resolves
+            // to only one edge regardless of which overload's constraint holds.
+            // The provider hook is the right invocation point — parsing-processor
+            // sees raw tree-sitter matches without the `@`-prefixed synthetic
+            // captures `scope-extractor` consumes, so we delegate extraction to
+            // the language adapter (C++ implements this; other languages opt out).
+            let parsedTemplateConstraints = undefined;
+            let constraintsTag = '';
+            if ((nodeLabel === 'Function' || nodeLabel === 'Method') &&
+                provider.extractTemplateConstraints !== undefined &&
+                definitionNode !== null) {
+                try {
+                    parsedTemplateConstraints = provider.extractTemplateConstraints(definitionNode);
+                    if (parsedTemplateConstraints !== undefined) {
+                        constraintsTag = templateConstraintsIdTag(parsedTemplateConstraints);
+                    }
+                }
+                catch {
+                    parsedTemplateConstraints = undefined;
+                    constraintsTag = '';
+                }
+            }
+            const nodeId = generateId(nodeLabel, `${file.path}:${qualifiedName}${classTemplateTag}${arityTag}${constraintsTag}`);
             const classNodeForSymbol = definitionNodeForRange || definitionNode || nameNode;
             const qualifiedTypeName = extractedClassSymbol?.qualifiedName ??
                 (classNodeForSymbol && provider.classExtractor?.isTypeDeclaration(classNodeForSymbol)
@@ -528,6 +557,9 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
                     ...(classTemplateArguments !== undefined && classTemplateArguments.length > 0
                         ? { templateArguments: classTemplateArguments }
                         : {}),
+                    ...(parsedTemplateConstraints !== undefined
+                        ? { templateConstraints: parsedTemplateConstraints }
+                        : {}),
                     ...(frameworkHint
                         ? {
                             astFrameworkMultiplier: frameworkHint.entryPointMultiplier,
@@ -579,6 +611,7 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
                 parameterCount: methodProps.parameterCount,
                 requiredParameterCount: methodProps.requiredParameterCount,
                 parameterTypes: methodProps.parameterTypes,
+                parameterTypeClasses: methodProps.parameterTypeClasses,
                 returnType: methodProps.returnType,
                 declaredType,
                 templateArguments: classTemplateArguments,

package/dist/core/ingestion/scope-extractor.js

@@ -372,8 +372,10 @@ function buildDefFromDeclarationMatch(match, anchor, filePath) {
     const parameterCount = parseIntCapture(match['@declaration.parameter-count']);
     const requiredParameterCount = parseIntCapture(match['@declaration.required-parameter-count']);
     const parameterTypes = parseJsonStringArrayCapture(match['@declaration.parameter-types']);
+    const parameterTypeClasses = parseJsonParameterTypeClassesCapture(match['@declaration.parameter-type-classes']);
     const declaredType = match['@declaration.field-type']?.text;
     const returnType = match['@declaration.return-type']?.text;
+    const templateConstraints = parseJsonCapture(match['@declaration.template-constraints']);
     return {
         nodeId: makeDefId(filePath, anchor.range, type, nameCap.text),
         filePath,
@@ -382,17 +384,77 @@ function buildDefFromDeclarationMatch(match, anchor, filePath) {
         ...(parameterCount !== undefined ? { parameterCount } : {}),
         ...(requiredParameterCount !== undefined ? { requiredParameterCount } : {}),
         ...(parameterTypes !== undefined ? { parameterTypes } : {}),
+        ...(parameterTypeClasses !== undefined ? { parameterTypeClasses } : {}),
         ...(declaredType !== undefined ? { declaredType } : {}),
         ...(returnType !== undefined ? { returnType } : {}),
         ...(templateArguments !== undefined ? { templateArguments } : {}),
+        ...(templateConstraints !== undefined ? { templateConstraints } : {}),
     };
 }
+/** Parse an opaque JSON payload synthesized by per-language captures
+ *  (e.g. C++ `@declaration.template-constraints`). Producer owns the
+ *  shape; shared code threads it through as `unknown` per the
+ *  `SymbolDefinition.templateConstraints` contract. */
+function parseJsonCapture(cap) {
+    if (cap === undefined)
+        return undefined;
+    try {
+        return JSON.parse(cap.text);
+    }
+    catch {
+        return undefined;
+    }
+}
 function parseIntCapture(cap) {
     if (cap === undefined)
         return undefined;
     const n = Number.parseInt(cap.text, 10);
     return Number.isFinite(n) ? n : undefined;
 }
+function parseJsonParameterTypeClassesCapture(cap) {
+    if (cap === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(cap.text);
+        if (!Array.isArray(parsed))
+            return undefined;
+        const out = [];
+        for (const item of parsed) {
+            if (item === null || typeof item !== 'object')
+                return undefined;
+            const o = item;
+            if (typeof o.base !== 'string')
+                return undefined;
+            if (o.cv !== 'none' &&
+                o.cv !== 'const' &&
+                o.cv !== 'volatile' &&
+                o.cv !== 'const volatile' &&
+                o.cv !== 'unknown') {
+                return undefined;
+            }
+            if (o.indirection !== 'value' &&
+                o.indirection !== 'lvalue-ref' &&
+                o.indirection !== 'rvalue-ref' &&
+                o.indirection !== 'pointer' &&
+                o.indirection !== 'unknown') {
+                return undefined;
+            }
+            if (typeof o.pointerDepth !== 'number' || !Number.isFinite(o.pointerDepth)) {
+                return undefined;
+            }
+            out.push({
+                base: o.base,
+                cv: o.cv,
+                indirection: o.indirection,
+                pointerDepth: o.pointerDepth,
+            });
+        }
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
 function parseJsonStringArrayCapture(cap) {
     if (cap === undefined)
         return undefined;
@@ -747,6 +809,7 @@ const KNOWN_SUB_TAGS = new Set([
     '@declaration.parameter-count',
     '@declaration.required-parameter-count',
     '@declaration.parameter-types',
+    '@declaration.template-constraints',
 ]);
 /**
  * Return the anchor capture for a match — the one whose name begins with

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

@@ -250,7 +250,7 @@
  * Plan that introduced most of these invariants:
  * `docs/plans/2026-04-20-001-refactor-emit-pipeline-generalization-plan.md`.
  */
-import type { BindingRef, Callsite, ParsedFile, ScopeId, SupportedLanguages, SymbolDefinition } from '../../../../_shared/index.js';
+import type { BindingRef, Callsite, ConstraintContext, ParsedFile, ScopeId, SupportedLanguages, SymbolDefinition } from '../../../../_shared/index.js';
 import type { KnowledgeGraph } from '../../../graph/types.js';
 import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
 import { LanguageProvider } from '../../language-provider.js';
@@ -264,6 +264,9 @@ import type { ConversionRankFn } from '../passes/overload-narrowing.js';
 export type LinearizeStrategy = (classDefId: string, directParents: readonly string[], parentsByDefId: ReadonlyMap<string, readonly string[]>) => string[];
 /** Result of `ScopeResolver.arityCompatibility` — mirrors `RegistryProviders.arityCompatibility`. */
 export type ArityVerdict = 'compatible' | 'unknown' | 'incompatible';
+/** Re-exported for ScopeResolver consumers — same shape as
+ *  `RegistryProviders.constraintCompatibility`'s third parameter. */
+export type { ConstraintContext } from '../../../../_shared/index.js';
 export interface ScopeResolver {
     /** Identity for telemetry + per-language flag check. */
     readonly language: SupportedLanguages;
@@ -337,6 +340,23 @@ export interface ScopeResolver {
      * `(def, callsite)` and need an adapter at the wiring site.
      */
     arityCompatibility(callsite: Callsite, def: SymbolDefinition): ArityVerdict;
+    /**
+     * Per-language constraint compatibility between a callsite and a
+     * candidate `def` that carries `templateConstraints` metadata.
+     * Mirrors `arityCompatibility` semantics: the three-valued verdict
+     * MUST treat `'unknown'` as keep-candidate (monotonicity — adding
+     * a predicate can only narrow correctly, never produce a wrong
+     * edge). Consulted by `narrowOverloadCandidates` after the arity
+     * and parameter-type filters.
+     *
+     * Optional. Languages without constrained-overload semantics
+     * (SFINAE, `requires` clauses, trait bounds, conditional types)
+     * leave this undefined and the constraint filter is a pass-through.
+     *
+     * C++ is the first consumer; see `languages/cpp/constraint-filter.ts`
+     * for the Tier-A predicate registry and Kleene 3-valued evaluator.
+     */
+    readonly constraintCompatibility?: (callsite: Callsite, def: SymbolDefinition, ctx: ConstraintContext) => ArityVerdict;
     /**
      * Compute the method-dispatch order for every Class def in the
      * workspace. Python uses depth-first first-seen via

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

@@ -41,6 +41,7 @@ export declare function resolveDefGraphId(filePath: string, def: {
     type?: NodeLabel;
     parameterTypes?: readonly string[];
     templateArguments?: readonly string[];
+    templateConstraints?: unknown;
 }, 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

@@ -18,6 +18,7 @@
  */
 import { generateId } from '../../../../lib/utils.js';
 import { qualifiedKey, simpleKey } from '../graph-bridge/node-lookup.js';
+import { templateConstraintsIdTag } from '../../utils/template-arguments.js';
 /**
  * Labels that may legitimately ANCHOR a CALLS/ACCESSES edge as the
  * source ("caller"). A Variable / Property can be the TARGET of an
@@ -68,6 +69,19 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
     if (qn === undefined || qn.length === 0)
         return undefined;
     if (def.type !== undefined) {
+        // SFINAE / `requires`-clause disambiguation (issue #1579) — try the
+        // constraint-fingerprinted key FIRST. Two function-template overloads
+        // with identical `parameterTypes` but mutually-exclusive SFINAE
+        // constraints route to their distinct graph nodes via this key.
+        // Must run before the parameter-types key because both overloads
+        // share the latter.
+        if ((def.type === 'Function' || def.type === 'Method') &&
+            def.templateConstraints !== undefined) {
+            const cKey = qualifiedKey(filePath, def.type, `${qn}${templateConstraintsIdTag(def.templateConstraints)}`);
+            const cHit = nodeLookup.get(cKey);
+            if (cHit !== undefined)
+                return cHit;
+        }
         // Overload disambiguation: when the def carries parameter types,
         // try the parameter-typed key first so same-name same-arity
         // overloads route to their distinct graph nodes.

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

@@ -17,6 +17,7 @@
  * `SymbolDefinition.nodeId` values into the legacy graph-node ID
  * format that downstream consumers (queries, edges, MCP) expect.
  */
+import { templateConstraintsIdTag } from '../../utils/template-arguments.js';
 /**
  * Parse a qualified name out of a Function/Method node id.
  *
@@ -86,6 +87,17 @@ export function buildGraphNodeLookup(graph) {
                 // Each overload is unique — set unconditionally.
                 lookup.set(pKey, node.id);
             }
+            // SFINAE / `requires`-clause disambiguation (issue #1579) — register
+            // a constraint-fingerprinted key so resolveDefGraphId can locate the
+            // correct overload by hashing the def's `templateConstraints`. Mirrors
+            // the parameter-types key but keys on the opaque constraint payload
+            // instead, separating two `process<T>` overloads whose
+            // `parameterTypes=['T']` would otherwise collide.
+            const tConstraints = props.templateConstraints;
+            if (tConstraints !== undefined && (node.label === 'Function' || node.label === 'Method')) {
+                const cKey = qualifiedKey(props.filePath, node.label, `${qualified}${templateConstraintsIdTag(tConstraints)}`);
+                lookup.set(cKey, node.id);
+            }
             if ((node.label === 'Class' ||
                 node.label === 'Struct' ||
                 node.label === 'Interface' ||

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

@@ -22,6 +22,7 @@ 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 { ScopeResolver } from '../contract/scope-resolver.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[]>;
@@ -44,6 +45,12 @@ export declare function emitFreeCallFallback(graph: KnowledgeGraph, scopes: Scop
         };
     }, callerParsed: ParsedFile, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[]) => readonly SymbolDefinition[] | undefined;
     readonly conversionRankFn?: ConversionRankFn;
+    /** Optional per-language constraint hook threaded into
+     *  `narrowOverloadCandidates`. Drops candidates whose template
+     *  constraints (e.g. C++ `enable_if_t`, C++20 `requires`) provably
+     *  fail at the call site. Three-valued; `'unknown'` keeps the
+     *  candidate (monotonicity). */
+    readonly constraintCompatibility?: ScopeResolver['constraintCompatibility'];
 }): number;
 /** Walk up from the call-site scope to the enclosing class scope,
  *  pick a method member by name with overload narrowing on arity +
@@ -63,4 +70,7 @@ export declare function pickImplicitThisOverload(site: {
     readonly name: string;
     readonly arity?: number;
     readonly argumentTypes?: readonly string[];
-}, scopes: ScopeResolutionIndexes, workspaceIndex: WorkspaceResolutionIndex, model: SemanticModel, conversionRankFn?: ConversionRankFn): SymbolDefinition | undefined;
+}, scopes: ScopeResolutionIndexes, workspaceIndex: WorkspaceResolutionIndex, model: SemanticModel, hookCtx?: {
+    readonly conversionRankFn?: ConversionRankFn;
+    readonly constraintCompatibility?: ScopeResolver['constraintCompatibility'];
+}): SymbolDefinition | undefined;

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

@@ -45,7 +45,10 @@ 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, options.conversionRankFn);
+                fnDef = pickImplicitThisOverload(site, scopes, workspaceIndex, model, {
+                    conversionRankFn: options.conversionRankFn,
+                    constraintCompatibility: options.constraintCompatibility,
+                });
             }
             // Scope-chain callable lookup. First-match preserves scope-chain
             // precedence (local shadows import). When a conversion-rank function
@@ -63,7 +66,10 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
                     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);
+                            const narrowed = narrowOverloadCandidates(allCallables, site.arity, site.argumentTypes, {
+                                conversionRankFn: options.conversionRankFn,
+                                constraintCompatibility: options.constraintCompatibility,
+                            });
                             if (narrowed.length === 1) {
                                 fnDef = narrowed[0];
                             }
@@ -97,36 +103,49 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
                             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.
+                    const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`;
                     if (adl === undefined || adl.length === 0) {
-                        if (ordinary.length <= 1 || options.conversionRankFn === undefined) {
+                        // No ADL contribution. Default behavior: `ordinary[0]` —
+                        // scope-chain walk preserves local-shadows-import precedence.
+                        //
+                        // Narrowing kicks in when either disambiguation signal is
+                        // present: any candidate carries `templateConstraints`
+                        // (SFINAE / `requires`-clause guarded templates, #1579), OR
+                        // a conversion-rank function is provided (#1606 / #1578).
+                        // Both hooks are threaded into `narrowOverloadCandidates`
+                        // via the unified `OverloadNarrowingHookCtx`.
+                        const hasConstraints = ordinary.some((d) => d.templateConstraints !== undefined);
+                        const canNarrow = hasConstraints || options.conversionRankFn !== undefined;
+                        if (ordinary.length <= 1 || !canNarrow) {
                             fnDef = ordinary[0];
                         }
                         else {
-                            const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`;
-                            const narrowed = narrowOverloadCandidates(ordinary, site.arity, site.argumentTypes, options.conversionRankFn);
+                            const narrowed = narrowOverloadCandidates(ordinary, site.arity, site.argumentTypes, {
+                                conversionRankFn: options.conversionRankFn,
+                                constraintCompatibility: options.constraintCompatibility,
+                            });
                             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.
+                            else if (narrowed.length === 0) {
+                                handledSites.add(siteKey);
+                                continue;
+                            }
+                            else {
+                                // >1 survivors: same-file → suppress (true overloads,
+                                // "degrade not lie" — no edge beats a wrong one, and
+                                // SFINAE-ambiguous calls land here). Cross-file →
+                                // first-match (shadowing semantics).
                                 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
+                                fnDef = ordinary[0];
                             }
                         }
                     }
                     else {
-                        const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`;
                         const merged = [];
                         const seenMerge = new Set();
                         const push = (defs) => {
@@ -139,7 +158,10 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
                         };
                         push(ordinary);
                         push(adl);
-                        const narrowed = narrowOverloadCandidates(merged, site.arity, site.argumentTypes, options.conversionRankFn);
+                        const narrowed = narrowOverloadCandidates(merged, site.arity, site.argumentTypes, {
+                            conversionRankFn: options.conversionRankFn,
+                            constraintCompatibility: options.constraintCompatibility,
+                        });
                         if (narrowed.length === 1) {
                             fnDef = narrowed[0];
                         }
@@ -248,7 +270,9 @@ function pickUniqueGlobalCallable(name, model, scopes, callerFilePath, isFileLoc
     // 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);
+        const narrowed = narrowOverloadCandidates(scopeDefs, callArity, callArgTypes, {
+            conversionRankFn,
+        });
         if (narrowed.length === 1)
             return narrowed[0];
     }
@@ -286,7 +310,9 @@ function pickUniqueGlobalCallable(name, model, scopes, callerFilePath, isFileLoc
     }
     // Same argument-type + conversion-rank narrowing for the model pool.
     if (defs.length > 1) {
-        const narrowed = narrowOverloadCandidates(defs, callArity, callArgTypes, conversionRankFn);
+        const narrowed = narrowOverloadCandidates(defs, callArity, callArgTypes, {
+            conversionRankFn,
+        });
         if (narrowed.length === 1)
             return narrowed[0];
     }
@@ -345,7 +371,7 @@ function pickConstructorOrClass(classDef, workspaceIndex) {
  *  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) {
+export function pickImplicitThisOverload(site, scopes, workspaceIndex, model, hookCtx) {
     // Find the enclosing Class scope by walking parents.
     let curId = site.inScope;
     let classScopeId;
@@ -374,7 +400,10 @@ export function pickImplicitThisOverload(site, scopes, workspaceIndex, model, co
     // 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);
+    const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes, {
+        conversionRankFn: hookCtx?.conversionRankFn,
+        constraintCompatibility: hookCtx?.constraintCompatibility,
+    });
     if (candidates.length !== 1)
         return undefined;
     return candidates[0];

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

@@ -25,14 +25,19 @@
  *      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.
+ *       `conversionRankFn` is provided (via `hookCtx`), 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.
+ *   4c. Final per-candidate constraint filter (SFINAE / `requires`).
+ *       When `constraintCompatibility` is provided via `hookCtx`, drop
+ *       candidates whose template constraints provably fail at the
+ *       call site. Three-valued; `'unknown'` keeps the candidate
+ *       (monotonicity).
  *   5. Empty input returns empty output.
  */
-import type { SymbolDefinition } from '../../../../_shared/index.js';
+import type { ArityVerdict, Callsite, ConstraintContext, SymbolDefinition } from '../../../../_shared/index.js';
 /**
  * Per-slot conversion-rank function. Returns a numeric cost for
  * converting `argType` to `paramType`:
@@ -45,7 +50,25 @@ import type { SymbolDefinition } from '../../../../_shared/index.js';
  * 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[];
+/**
+ * Optional hook bundle for narrowing extension points. Threaded in
+ * from `pickOverload` / `pickImplicitThisOverload` so per-language
+ * narrowing can layer in conversion-rank scoring (#1606) and
+ * constraint filtering (#1579) without changing the call signature
+ * at every site. Each hook is independently optional — leaving both
+ * undefined preserves the legacy arity + exact-type behavior.
+ */
+export interface OverloadNarrowingHookCtx {
+    /** Conversion-rank scoring fallback (step 4b). Engages when the
+     *  exact-type filter rejects every candidate. */
+    readonly conversionRankFn?: ConversionRankFn;
+    /** Constraint filter (step 4c). Drops candidates whose template
+     *  guards (SFINAE `enable_if_t`, C++20 `requires`, future Rust
+     *  trait bounds, etc.) provably fail at the call site. Three-valued
+     *  — `'unknown'` keeps the candidate (monotonicity). */
+    readonly constraintCompatibility?: (callsite: Callsite, def: SymbolDefinition, ctx: ConstraintContext) => ArityVerdict;
+}
+export declare function narrowOverloadCandidates(overloads: readonly SymbolDefinition[], argCount: number | undefined, argTypes: readonly string[] | undefined, hookCtx?: OverloadNarrowingHookCtx): readonly SymbolDefinition[];
 /**
  * Detect when >1 candidate share identical `parameterTypes` after the
  * per-language normalizer has collapsed distinct underlying types. This

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

@@ -25,14 +25,19 @@
  *      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.
+ *       `conversionRankFn` is provided (via `hookCtx`), 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.
+ *   4c. Final per-candidate constraint filter (SFINAE / `requires`).
+ *       When `constraintCompatibility` is provided via `hookCtx`, drop
+ *       candidates whose template constraints provably fail at the
+ *       call site. Three-valued; `'unknown'` keeps the candidate
+ *       (monotonicity).
  *   5. Empty input returns empty output.
  */
-export function narrowOverloadCandidates(overloads, argCount, argTypes, conversionRankFn) {
+export function narrowOverloadCandidates(overloads, argCount, argTypes, hookCtx) {
     if (overloads.length === 0)
         return [];
     const arityMatches = argCount === undefined
@@ -67,6 +72,7 @@ export function narrowOverloadCandidates(overloads, argCount, argTypes, conversi
     // args).
     const anyUnknownBounds = overloads.some((d) => d.parameterCount === undefined && d.requiredParameterCount === undefined);
     const candidates = arityMatches.length > 0 ? arityMatches : anyUnknownBounds ? overloads : [];
+    let result = candidates;
     if (argTypes !== undefined && argTypes.length > 0) {
         const typed = candidates.filter((d) => {
             const params = d.parameterTypes;
@@ -80,21 +86,46 @@ export function narrowOverloadCandidates(overloads, argCount, argTypes, conversi
             }
             return true;
         });
-        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 (typed.length > 0) {
+            result = typed;
+        }
+        else if (hookCtx?.conversionRankFn !== undefined) {
+            // ── Conversion-rank scoring (step 4b) ──────────────────────────
+            // The exact-type filter rejected every candidate. 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. When
+            // ranking also yields empty, fall through to the arity-filtered
+            // `candidates` set — matches pre-#1606 behavior.
+            const ranked = rankByConversion(candidates, argTypes, hookCtx.conversionRankFn);
             if (ranked.length > 0)
-                return ranked;
+                result = ranked;
         }
     }
-    return candidates;
+    // Constraint filter (step 4c; Tier-A — SFINAE / `requires` clauses).
+    // Runs after arity, exact-type, and conversion-rank filters so the
+    // hook only sees candidates already viable on the other axes.
+    // Three-valued: `'compatible'` and `'unknown'` keep the candidate
+    // (monotonicity — adding a predicate must never cause a wrong edge);
+    // only `'incompatible'` drops it. Candidates without
+    // `templateConstraints` are always kept.
+    //
+    // No fallback to the unconstrained set when this filter empties the
+    // candidate list: a fully-`'incompatible'` verdict is authoritative.
+    // The downstream `OVERLOAD_AMBIGUOUS` sentinel still guards the empty
+    // case, so a buggy hook that wrongly returns `'incompatible'` for
+    // every candidate degrades to today's "suppress edge" behavior rather
+    // than emitting a wrong edge.
+    if (hookCtx?.constraintCompatibility !== undefined && argCount !== undefined) {
+        const callsite = { arity: argCount };
+        const ctx = argTypes !== undefined ? { argumentTypes: argTypes } : {};
+        result = result.filter((def) => {
+            if (def.templateConstraints === undefined)
+                return true;
+            return hookCtx.constraintCompatibility(callsite, def, ctx) !== 'incompatible';
+        });
+    }
+    return result;
 }
 /**
  * Pairwise dominance comparison (ISO C++ [over.ics.rank]).

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

@@ -41,7 +41,7 @@ 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' | 'isSuperReceiverInContext' | 'fieldFallbackOnMethodLookup' | 'collapseMemberCallsByCallerTarget' | 'unwrapCollectionAccessor' | 'hoistTypeBindingsToModule' | 'resolveQualifiedReceiverMember' | 'resolveThisViaEnclosingClass' | 'conversionRankFn'>;
+type ReceiverBoundProviderSubset = Pick<ScopeResolver, 'isSuperReceiver' | 'isSuperReceiverInContext' | 'fieldFallbackOnMethodLookup' | 'collapseMemberCallsByCallerTarget' | 'unwrapCollectionAccessor' | 'hoistTypeBindingsToModule' | 'resolveQualifiedReceiverMember' | 'resolveThisViaEnclosingClass' | 'conversionRankFn' | 'constraintCompatibility'>;
 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