gitnexus 1.6.6-rc.98 → 1.6.6

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

@@ -25,17 +25,16 @@
  *      `runYourLangScopeResolution(input) = runScopeResolution(input, yourScopeResolver)`.
  *   3. Register the provider in
  *      `gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts`
- *      (the `SCOPE_RESOLVERS` map).
- *   4. Add `SupportedLanguages.YourLang` to `MIGRATED_LANGUAGES` in
- *      `registry-primary-flag.ts`.
- *   5. Verify the resolver integration test at
- *      `gitnexus/test/integration/resolvers/<lang>.test.ts` passes
- *      under both `REGISTRY_PRIMARY_<LANG>=0` (legacy) and `=1`
- *      (registry-primary). The CI parity gate enforces this.
+ *      (the `SCOPE_RESOLVERS` map). That registration is all it takes — the
+ *      `scopeResolutionPhase` runs every registered resolver.
+ *   4. Verify the resolver integration test at
+ *      `gitnexus/test/integration/resolvers/<lang>.test.ts` passes (it runs
+ *      in the standard test suite). Scope-resolution is the only resolution
+ *      path — the legacy call-resolution DAG was removed in RING4-1 #942.
  *
  * No new pipeline phase, no orchestrator copy-paste, no workflow
- * change. The generic `scopeResolutionPhase` and the CI parity
- * workflow auto-discover everything via `MIGRATED_LANGUAGES`.
+ * change. The generic `scopeResolutionPhase` auto-discovers everything via
+ * the `SCOPE_RESOLVERS` map.
  *
  * ## ScopeResolver vs LanguageProvider
  *
@@ -139,7 +138,19 @@
  *     once per workspace at resolve time), and merging would create a
  *     god-interface that complicates future migrations.
  *
- *   - **I8 — Two-channel binding lifecycle.**
+ *   - **I8 — Binding-channel lifecycle.** Post-finalize binding lookup
+ *     fans across several channels (`lookupBindingsAt` /
+ *     `findReceiverTypeBinding` consult them in precedence order):
+ *     `indexes.bindings` (frozen finalize output), `Scope.bindings`
+ *     (lexical local, first-tier shadowing), `indexes.bindingAugmentations`
+ *     (per-scope append-only), `indexes.workspaceFqnBindings` +
+ *     `indexes.workspaceTypeBindings` (scope-independent / global, consulted
+ *     unconditionally), and `indexes.namespaceFqnBindings` +
+ *     `indexes.namespaceTypeBindings` (per-namespace, consulted only for the
+ *     namespaces in `indexes.accessibleNamespacesByScope` for the caller's
+ *     module). All but `indexes.bindings` are mutable post-finalize and
+ *     populated by hooks; only `indexes.bindings` is frozen.
+ *
  *     `indexes.bindings` is the **finalize-output channel**. After
  *     `finalizeScopeModel` returns, its inner `BindingRef[]` arrays
  *     are deep-frozen by `materializeBindings` and MUST NOT be
@@ -391,13 +402,88 @@ export interface ScopeResolver {
      * `include`/`extend`/`prepend`) use this hook to emit IMPLEMENTS edges
      * from parsed import or reference data.
      *
-     * Receives the graph (writable), parsedFiles, and nodeLookup — same
-     * surface as `buildMro`. Must be idempotent (the orchestrator may call
-     * it more than once during re-resolution).
+     * Receives the graph (writable), parsedFiles, nodeLookup, and the finalized
+     * `ScopeResolutionIndexes` — the same scope/import/def model
+     * `preEmitInheritanceEdges` resolves against, and already a first-class part
+     * of this contract (the structure/binding hooks below take it too), so the
+     * trailing `scopes` parameter is not a new type dependency here. It is
+     * appended and optional so implementations that don't need scope-aware
+     * resolution keep their narrower signature.
+     *
+     * `scopes` has exactly ONE consumer: the Rust resolver — see
+     * `emitRustTraitImplEdges` in languages/rust/scope-resolver.ts — which
+     * resolves `impl T for S` trait/struct names through the scope chain +
+     * import-aware disambiguation (refusing ambiguous matches) instead of a
+     * global last-write-wins simple-name index (#1951). Other implementations
+     * (e.g. Ruby `include`/`extend`/`prepend`) ignore it and keep the 3-arg
+     * shape. Must be idempotent (the orchestrator may call it more than once
+     * during re-resolution).
      *
      * Default: undefined (no extra heritage edges needed).
      */
-    readonly emitHeritageEdges?: (graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup) => void;
+    readonly emitHeritageEdges?: (graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, scopes?: ScopeResolutionIndexes) => void;
+    /**
+     * Optional hook to emit IMPORTS edges that no syntactic import
+     * statement produces. Some languages grant files implicit visibility
+     * of one another within a compilation unit (e.g. every file in a
+     * build target sees its siblings' top-level declarations without an
+     * explicit import). The generic import pipeline only emits File→File
+     * IMPORTS edges from finalized `ImportEdge`s, so a language with this
+     * implicit-visibility rule has no edge to emit through that path.
+     *
+     * Runs immediately after `emitHeritageEdges` (so it shares the same
+     * pre-MRO surface: writable graph, parsedFiles, nodeLookup). Must be
+     * idempotent — the orchestrator may invoke it more than once during
+     * re-resolution. Implementations dedup their own emissions.
+     *
+     * `resolutionConfig` is the opaque per-workspace value returned by
+     * `loadResolutionConfig` (same channel threaded into `resolveImportTarget`).
+     * Swift uses it to group same-module files by the SPM target subtree;
+     * languages that don't need per-workspace config ignore the trailing
+     * parameter (it is optional so existing impls keep compiling).
+     *
+     * Default: undefined (cross-file visibility requires an explicit
+     * import; the finalized-ImportEdge pipeline covers it).
+     */
+    readonly emitImplicitImportEdges?: (graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, resolutionConfig?: unknown) => void;
+    /**
+     * Restore capture-time per-file side-channel state that `emitScopeCaptures`
+     * produces as a side effect into module-level maps, NOT onto the returned
+     * `ParsedFile`. Such state never crosses the worker boundary: in worker-mode
+     * parses `emitScopeCaptures` runs inside the worker, so its module-level
+     * marks are populated in the WORKER process. The main thread then reuses the
+     * serialized `ParsedFile` (see `RunScopeResolutionInput.preExtractedParsedFiles`)
+     * and skips `extractParsedFile`, so those marks would otherwise be missing in
+     * the main process where resolution consumes them.
+     *
+     * This hook reads the worker-serialized snapshot from
+     * `parsed.captureSideChannel` (produced by the matching
+     * `LanguageProvider.collectCaptureSideChannel` hook in the worker) and writes
+     * it back into the module maps. It does NO tree-sitter parse and needs no
+     * source `content` — that is the whole point of #1983 (the prior re-parse
+     * replay re-introduced the main-thread tree-sitter OOM on huge `.h`/`.cpp`
+     * repos and was replaced by this data-only restore).
+     *
+     * C++ is the only language with this pattern today: `emitCppScopeCaptures`
+     * records ADL call-site arg shapes, inline-/anonymous-namespace ranges,
+     * dependent-base names, and file-local linkage into module maps that
+     * `populateOwners` and the ADL / two-phase-lookup passes read on the main
+     * thread. Without this restore, all of that is empty on the worker path and
+     * advanced C++ resolution (ADL / SFINAE-adjacent / inline-namespace) silently
+     * produces zero edges.
+     *
+     * Called by `runScopeResolution` ONLY for pre-extracted files (the worker
+     * already populated the marks in-process for freshly extracted files, so the
+     * fresh-extract leg never calls this). Runs BEFORE `populateOwners(parsed)`
+     * so the resolved-range Sets it repopulates are visible to that hook.
+     *
+     * Languages whose `emitScopeCaptures` is pure (the contract default — see
+     * `scope-extractor.ts`) leave this undefined; the restore is a no-op for them.
+     *
+     * @param parsed   The pre-extracted ParsedFile being reused. Its
+     *                 `captureSideChannel` carries the worker-computed data.
+     */
+    readonly applyCaptureSideChannel?: (parsed: ParsedFile) => void;
     /**
      * Mutate `parsed.localDefs[i].ownerId` to point at the structural
      * owner. Python's rule: methods (Function defs whose parent scope
@@ -503,6 +589,15 @@ export interface ScopeResolver {
      * but is too loose as a default for strict module systems.
      */
     readonly allowGlobalFreeCallFallback?: boolean;
+    /**
+     * When true, a constructor-form call `Type(...)` links to the Class def
+     * itself rather than its explicit Constructor def. Default
+     * (undefined/false) targets the explicit Constructor when one exists,
+     * else falls back to the Class. Languages whose call graph models
+     * `Type(...)` as a reference to the type (not its initializer) — e.g.
+     * Swift — opt in.
+     */
+    readonly constructorCallTargetsClass?: boolean;
     /**
      * Optional per-slot conversion-rank function for overload resolution.
      * When provided, `narrowOverloadCandidates` uses ranked scoring as a
@@ -670,6 +765,12 @@ export interface ScopeResolver {
         readonly treeCache?: {
             get(filePath: string): unknown;
         };
+        /** Opaque per-workspace value from `loadResolutionConfig` (same
+         *  channel threaded into `resolveImportTarget`). Swift uses it to
+         *  group same-module siblings by the SPM target subtree; languages
+         *  that don't need per-workspace config ignore it. Optional so
+         *  existing impls keep compiling. */
+        readonly resolutionConfig?: unknown;
     }) => void;
     /**
      * Whether the compound-receiver resolver should walk up from a
@@ -705,9 +806,16 @@ export interface ScopeResolver {
      * `NewUser → User` mirrored from the target package). Runs after
      * `populateNamespaceSiblings` and before `propagateImportedReturnTypes`
      * so the SCC-ordered pass sees the mirrored bindings.
+     *
+     * `resolutionConfig` is the opaque per-workspace value returned by
+     * `loadResolutionConfig` (same channel threaded into `resolveImportTarget`).
+     * Swift uses it to group same-module sibling files by the SPM target
+     * subtree; languages that don't need per-workspace config ignore the
+     * trailing parameter (it is optional so existing impls keep compiling).
+     *
      * Default: undefined (no namespace typeBinding mirroring).
      */
-    readonly mirrorNamespaceTypeBindings?: (parsedFiles: readonly ParsedFile[], indexes: ScopeResolutionIndexes, workspaceIndex: import('../../scope-resolution/workspace-index.js').WorkspaceResolutionIndex) => void;
+    readonly mirrorNamespaceTypeBindings?: (parsedFiles: readonly ParsedFile[], indexes: ScopeResolutionIndexes, workspaceIndex: import('../../scope-resolution/workspace-index.js').WorkspaceResolutionIndex, resolutionConfig?: unknown) => void;
     /**
      * Optional: bind for-range loop variables to their element/value types.
      * Languages like Go need to resolve `for _, v := range m` where `m` is
@@ -722,6 +830,64 @@ export interface ScopeResolver {
             get(filePath: string): unknown;
         };
     }) => void;
+    /**
+     * Optional hook to expand the set of file paths handed to the scope-
+     * resolution run for this language.
+     *
+     * Called once per language with:
+     *   - `primaryFilePaths`      — files whose `getLanguageFromFilename` === this
+     *                               resolver's `language` (e.g. all `.vue` files).
+     *   - `preExtractedByPath`    — ParsedFile cache from the parse phase.
+     *   - `entryFileContents`     — raw source text of the primary files.
+     *   - `allScannedPaths`       — complete set of paths in the repository.
+     *   - `resolutionConfig`      — language-specific config (tsconfig paths, …).
+     *
+     * Return value: the full set of paths to include in the scope-resolution
+     * run.  May be a superset of `primaryFilePaths`.
+     *
+     * Vue uses this hook to collect the transitive TS/JS import closure of
+     * every `.vue` file so that cross-file imports (`import { fn } from './api'`)
+     * resolve correctly within a single Vue scope-resolution pass.
+     *
+     * This hook keeps language-specific scope-context policy inside the language
+     * module, preventing shared pipeline code (`phase.ts`) from naming individual
+     * languages.
+     *
+     * Default: undefined (use only `primaryFilePaths`).
+     */
+    readonly collectScopeContextPaths?: (options: {
+        readonly primaryFilePaths: readonly string[];
+        readonly preExtractedByPath: ReadonlyMap<string, import('../../../../_shared/index.js').ParsedFile>;
+        readonly entryFileContents: ReadonlyMap<string, string>;
+        readonly allScannedPaths: ReadonlySet<string>;
+        readonly resolutionConfig: unknown;
+    }) => Set<string>;
+    /**
+     * Optional post-resolution hook for emitting language-specific graph edges
+     * that cannot be derived from scope captures or import resolution alone.
+     *
+     * Runs AFTER all standard edge-emission passes (receiver-bound CALLS,
+     * free-call fallback, references-via-lookup, and import edges). Receives
+     * the fully-resolved graph, all ParsedFiles, the node lookup, the finalized
+     * scope indexes, and the raw file-content map.
+     *
+     * Vue uses this hook to emit:
+     *   - `CALLS` (`vue-template-component`) for PascalCase component elements
+     *   - `BINDS_EVENT_HANDLER` for `@event="handler"` on component elements
+     *   - `EMITS_EVENT` for `emit('eventName', …)` calls in script blocks
+     *   - `ACCESSES` (`vue-template-attribute`) for `:prop="var"` bindings
+     *
+     * Unlike `emitImplicitImportEdges` and `emitHeritageEdges` (which run
+     * before MRO construction), this hook runs last, after the full graph is
+     * populated, so it can safely query node existence and resolved import
+     * targets via `indexes.imports`.
+     *
+     * Default: undefined (no supplementary edges needed).
+     */
+    readonly emitPostResolutionEdges?: (graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, indexes: ScopeResolutionIndexes, ctx: {
+        readonly fileContents: ReadonlyMap<string, string>;
+        readonly resolutionConfig?: unknown;
+    }) => void;
     /**
      * Optional post-resolution pass: emit CALLS edges for member-call sites
      * whose receiver cannot be typed by the scope chain (no `TypeRef`).

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

@@ -25,17 +25,16 @@
  *      `runYourLangScopeResolution(input) = runScopeResolution(input, yourScopeResolver)`.
  *   3. Register the provider in
  *      `gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts`
- *      (the `SCOPE_RESOLVERS` map).
- *   4. Add `SupportedLanguages.YourLang` to `MIGRATED_LANGUAGES` in
- *      `registry-primary-flag.ts`.
- *   5. Verify the resolver integration test at
- *      `gitnexus/test/integration/resolvers/<lang>.test.ts` passes
- *      under both `REGISTRY_PRIMARY_<LANG>=0` (legacy) and `=1`
- *      (registry-primary). The CI parity gate enforces this.
+ *      (the `SCOPE_RESOLVERS` map). That registration is all it takes — the
+ *      `scopeResolutionPhase` runs every registered resolver.
+ *   4. Verify the resolver integration test at
+ *      `gitnexus/test/integration/resolvers/<lang>.test.ts` passes (it runs
+ *      in the standard test suite). Scope-resolution is the only resolution
+ *      path — the legacy call-resolution DAG was removed in RING4-1 #942.
  *
  * No new pipeline phase, no orchestrator copy-paste, no workflow
- * change. The generic `scopeResolutionPhase` and the CI parity
- * workflow auto-discover everything via `MIGRATED_LANGUAGES`.
+ * change. The generic `scopeResolutionPhase` auto-discovers everything via
+ * the `SCOPE_RESOLVERS` map.
  *
  * ## ScopeResolver vs LanguageProvider
  *
@@ -139,7 +138,19 @@
  *     once per workspace at resolve time), and merging would create a
  *     god-interface that complicates future migrations.
  *
- *   - **I8 — Two-channel binding lifecycle.**
+ *   - **I8 — Binding-channel lifecycle.** Post-finalize binding lookup
+ *     fans across several channels (`lookupBindingsAt` /
+ *     `findReceiverTypeBinding` consult them in precedence order):
+ *     `indexes.bindings` (frozen finalize output), `Scope.bindings`
+ *     (lexical local, first-tier shadowing), `indexes.bindingAugmentations`
+ *     (per-scope append-only), `indexes.workspaceFqnBindings` +
+ *     `indexes.workspaceTypeBindings` (scope-independent / global, consulted
+ *     unconditionally), and `indexes.namespaceFqnBindings` +
+ *     `indexes.namespaceTypeBindings` (per-namespace, consulted only for the
+ *     namespaces in `indexes.accessibleNamespacesByScope` for the caller's
+ *     module). All but `indexes.bindings` are mutable post-finalize and
+ *     populated by hooks; only `indexes.bindings` is frozen.
+ *
  *     `indexes.bindings` is the **finalize-output channel**. After
  *     `finalizeScopeModel` returns, its inner `BindingRef[]` arrays
  *     are deep-frozen by `materializeBindings` and MUST NOT be

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

@@ -31,6 +31,11 @@ export function mapReferenceKindToEdgeType(kind) {
             return 'EXTENDS';
         case 'type-reference':
             return 'USES';
+        // Macro invocations resolve to a `Macro` node (never a function), so
+        // they emit `USES` — kept out of the `CALLS` keyspace which denotes
+        // function/method dispatch (#1934 review).
+        case 'macro':
+            return 'USES';
         case 'import-use':
             return undefined;
         default:
@@ -47,7 +52,10 @@ export function mapReferenceKindToEdgeType(kind) {
  * double-emit a resolution one of them already produced.
  */
 export function tryEmitEdge(graph, scopes, nodeLookup, site, targetDef, reason, seen, confidence = 0.85, collapseByCallerTarget = false) {
-    const callerGraphId = resolveCallerGraphId(site.inScope, scopes, nodeLookup);
+    // Inheritance edges are emitted directly by `preEmitInheritanceEdges` (which
+    // owns the enclosing-class caller and the EXTENDS-vs-IMPLEMENTS type), so this
+    // generic bridge derives caller + edge type purely from the site.
+    const callerGraphId = resolveCallerGraphId(site.inScope, scopes, nodeLookup, site.atRange);
     const targetGraphId = resolveDefGraphId(targetDef.filePath, targetDef, nodeLookup);
     const edgeType = mapReferenceKindToEdgeType(site.kind);
     if (callerGraphId === undefined)
@@ -91,7 +99,7 @@ export function tryEmitEdge(graph, scopes, nodeLookup, site, targetDef, reason,
  * flag honoring, edge-type mapping, caller-id resolution.
  */
 export function tryEmitEdgeWithExplicitTargetId(graph, scopes, nodeLookup, site, targetGraphId, reason, seen, confidence = 0.85, collapseByCallerTarget = false) {
-    const callerGraphId = resolveCallerGraphId(site.inScope, scopes, nodeLookup);
+    const callerGraphId = resolveCallerGraphId(site.inScope, scopes, nodeLookup, site.atRange);
     const edgeType = mapReferenceKindToEdgeType(site.kind);
     if (callerGraphId === undefined)
         return false;

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

@@ -41,8 +41,11 @@ export declare function resolveDefGraphId(filePath: string, def: {
     type?: NodeLabel;
     parameterTypes?: readonly string[];
     parameterTypeClasses?: readonly ParameterTypeClass[];
+    parameterCount?: number;
     templateArguments?: readonly string[];
     templateConstraints?: unknown;
+    /** #1982 bridge-held namespace path; see `SymbolDefinition.namespacePrefix`. */
+    namespacePrefix?: string;
 }, nodeLookup: GraphNodeLookup): string | undefined;
 /** Derive the simple (unqualified) name of a def from its `qualifiedName`. */
 export declare function simpleQualifiedName(def: SymbolDefinition): string | undefined;
@@ -57,4 +60,7 @@ export declare function simpleQualifiedName(def: SymbolDefinition): string | und
  * edge source. Matches legacy DAG behavior where module-level CALLS
  * edges originate from the file symbol.
  */
-export declare function resolveCallerGraphId(startScope: ScopeId, scopes: ScopeResolutionIndexes, nodeLookup: GraphNodeLookup): string | undefined;
+export declare function resolveCallerGraphId(startScope: ScopeId, scopes: ScopeResolutionIndexes, nodeLookup: GraphNodeLookup, atRange?: {
+    startLine: number;
+    startCol: number;
+}): 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 { isOverloadableCallable } from '../../utils/callable-labels.js';
 import { templateConstraintsIdTag } from '../../utils/template-arguments.js';
 import { parameterShapeIdTag } from '../../utils/method-props.js';
 /**
@@ -48,6 +49,31 @@ function isCallerAnchorLabel(label) {
         label === 'Struct' ||
         label === 'Enum');
 }
+function rangeContainsPoint(range, at) {
+    if (at.startLine < range.startLine || at.startLine > range.endLine)
+        return false;
+    if (at.startLine === range.startLine && at.startCol < range.startCol)
+        return false;
+    if (at.startLine === range.endLine && at.startCol > range.endCol)
+        return false;
+    return true;
+}
+/** Pick the callable that owns `atRange` when multiple overloads share a class scope. */
+function pickCallerCallableDef(scope, scopes, atRange) {
+    if (atRange !== undefined) {
+        for (const childId of scopes.scopeTree.getChildren(scope.id)) {
+            const child = scopes.scopeTree.getScope(childId);
+            if (child === undefined || child.kind !== 'Function')
+                continue;
+            if (!rangeContainsPoint(child.range, atRange))
+                continue;
+            const childCallable = child.ownedDefs.find((d) => d.type === 'Function' || d.type === 'Method' || d.type === 'Constructor');
+            if (childCallable !== undefined)
+                return childCallable;
+        }
+    }
+    return scope.ownedDefs.find((d) => d.type === 'Function' || d.type === 'Method' || d.type === 'Constructor');
+}
 /**
  * Look up a `SymbolDefinition` in the graph node lookup.
  *
@@ -83,7 +109,7 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
             if (cHit !== undefined)
                 return cHit;
         }
-        if ((def.type === 'Function' || def.type === 'Method') &&
+        if (isOverloadableCallable(def.type) &&
             def.parameterTypes !== undefined &&
             def.parameterTypeClasses !== undefined) {
             const shapeTag = parameterShapeIdTag(def.parameterTypes, def.parameterTypeClasses);
@@ -96,8 +122,12 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
         }
         // 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.
-        if ((def.type === 'Function' || def.type === 'Method') &&
+        // overloads route to their distinct graph nodes. Constructors are
+        // included so a C# `: this(int)` / `: base(int)` chain, a Java
+        // `this(int)`/`super(int)` chain, or `new Foo(int)` resolves to the
+        // matching ctor overload instead of first-wins collapsing onto
+        // another `Foo` ctor (a self-loop) — #1928 F38 / #2046.
+        if (isOverloadableCallable(def.type) &&
             def.parameterTypes !== undefined &&
             def.parameterTypes.length > 0) {
             const pKey = qualifiedKey(filePath, def.type, `${qn}~${def.parameterTypes.join(',')}`);
@@ -105,6 +135,16 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
             if (pHit !== undefined)
                 return pHit;
         }
+        // Arity-disambiguating key (see node-lookup.ts): route a same-name overload
+        // to the structure node with the matching parameter count. Critical for a
+        // zero-arg overload (no parameterTypes) that would otherwise collapse onto a
+        // sibling overload via the source-order-dependent qualified key.
+        if (isOverloadableCallable(def.type) && def.parameterCount !== undefined) {
+            const aKey = qualifiedKey(filePath, def.type, `${qn}#${def.parameterCount}`);
+            const aHit = nodeLookup.get(aKey);
+            if (aHit !== undefined)
+                return aHit;
+        }
         if ((def.type === 'Class' ||
             def.type === 'Struct' ||
             def.type === 'Interface' ||
@@ -120,6 +160,18 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
         const qualifiedHit = nodeLookup.get(qualifiedKey(filePath, def.type, qn));
         if (qualifiedHit !== undefined)
             return qualifiedHit;
+        // #1982: some scope-extractors qualify a type by its enclosing CLASS chain
+        // (`A.Inner`) but drop the enclosing NAMESPACE, while the structure-phase
+        // node is keyed by the full path (`NS.A.Inner`). Retry with the
+        // namespace-prefixed key (tagged by `tagNamespacePrefixes`) BEFORE the
+        // simple-name fallback, so same-tail nested bases don't collapse across
+        // sibling namespace members via `simpleKey`.
+        const nsPrefix = def.namespacePrefix;
+        if (nsPrefix !== undefined && nsPrefix.length > 0) {
+            const nsHit = nodeLookup.get(qualifiedKey(filePath, def.type, `${nsPrefix}.${qn}`));
+            if (nsHit !== undefined)
+                return nsHit;
+        }
     }
     const simpleName = qn.lastIndexOf('.') === -1 ? qn : qn.slice(qn.lastIndexOf('.') + 1);
     return nodeLookup.get(simpleKey(filePath, simpleName));
@@ -143,7 +195,7 @@ export function simpleQualifiedName(def) {
  * edge source. Matches legacy DAG behavior where module-level CALLS
  * edges originate from the file symbol.
  */
-export function resolveCallerGraphId(startScope, scopes, nodeLookup) {
+export function resolveCallerGraphId(startScope, scopes, nodeLookup, atRange) {
     let current = startScope;
     const visited = new Set();
     let lastFilePath;
@@ -158,9 +210,9 @@ export function resolveCallerGraphId(startScope, scopes, nodeLookup) {
         // Prefer Function/Method/Constructor anchors; fall back to
         // Class/Interface/Struct/Enum. Variable/Property are NOT valid
         // caller anchors — see `isCallerAnchorLabel` for why.
-        const fnDef = scope.ownedDefs.find((d) => d.type === 'Function' || d.type === 'Method' || d.type === 'Constructor');
+        const fnDef = pickCallerCallableDef(scope, scopes, atRange);
         if (fnDef !== undefined) {
-            const id = resolveDefGraphId(scope.filePath, fnDef, nodeLookup);
+            const id = resolveDefGraphId(fnDef.filePath, fnDef, nodeLookup);
             if (id !== undefined)
                 return id;
         }

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 { isOverloadableCallable } from '../../utils/callable-labels.js';
 import { templateConstraintsIdTag } from '../../utils/template-arguments.js';
 import { parameterShapeIdTag } from '../../utils/method-props.js';
 /**
@@ -87,18 +88,31 @@ export function buildGraphNodeLookup(graph) {
             // a parameter-types-suffixed key so resolveDefGraphId can find
             // the right overload by matching its def's parameterTypes.
             const pTypes = props.parameterTypes;
-            if (pTypes !== undefined &&
-                pTypes.length > 0 &&
-                (node.label === 'Function' || node.label === 'Method')) {
+            if (pTypes !== undefined && pTypes.length > 0 && isOverloadableCallable(node.label)) {
                 const pKey = qualifiedKey(props.filePath, node.label, `${keyQualified}~${pTypes.join(',')}`);
                 // Each overload is unique — set unconditionally.
                 if (!lookup.has(pKey))
                     lookup.set(pKey, node.id);
             }
+            // Arity-disambiguating key: include the parameter count so two same-name
+            // overloads of DIFFERENT arity route to distinct graph nodes even when the
+            // shorter overload carries no parameter types (e.g. a Kotlin zero-arg
+            // secondary constructor vs a 2-arg one — both share the qualified key, whose
+            // first-write-wins assignment is source-order-dependent). The structure-phase
+            // node id encodes `#<arity>`; this mirrors it in the lookup keyspace so
+            // resolveDefGraphId can match by the def's own parameterCount. Same-arity
+            // overloads collapse onto one arity key (first-write-wins) — identical to the
+            // pre-existing qualified-key behavior, so no regression there.
+            const pCount = props.parameterCount;
+            if (pCount !== undefined && isOverloadableCallable(node.label)) {
+                const aKey = qualifiedKey(props.filePath, node.label, `${keyQualified}#${pCount}`);
+                if (!lookup.has(aKey))
+                    lookup.set(aKey, node.id);
+            }
             const pClasses = props
                 .parameterTypeClasses;
             const shapeTag = parameterShapeIdTag(pTypes, pClasses);
-            if (shapeTag !== '' && (node.label === 'Function' || node.label === 'Method')) {
+            if (shapeTag !== '' && isOverloadableCallable(node.label)) {
                 const shapeKey = qualifiedKey(props.filePath, node.label, `${keyQualified}${shapeTag}`);
                 if (!lookup.has(shapeKey))
                     lookup.set(shapeKey, node.id);
@@ -159,5 +173,10 @@ export function isLinkableLabel(label) {
         // `Variable` def for `export const fooService = {...}` to the canonical
         // `Const:filePath:name` graph node id, against which object-literal
         // method symbols register their `ownerId` (PR #1718 / issue #1358).
-        label === 'Const');
+        label === 'Const' ||
+        // Macro nodes are linkable so a macro invocation (`log!(…)`) resolved
+        // via `MacroRegistry` can bridge its scope-resolution `Macro` def to
+        // the legacy `@definition.macro` graph node and emit the `USES` edge
+        // (Rust #1934 F72; also covers C/C++ `#define` macro defs).
+        label === 'Macro');
 }

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

@@ -16,7 +16,7 @@
  * Generic; promoted from `languages/python/scope-resolver.ts` per the scope-resolution
  * generalization plan.
  */
-import type { ParsedFile, Reference, ScopeId, SymbolDefinition } from '../../../../_shared/index.js';
+import type { ParameterTypeClass, ParsedFile, Reference, ScopeId, SymbolDefinition } from '../../../../_shared/index.js';
 import type { KnowledgeGraph } from '../../../graph/types.js';
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import type { SemanticModel } from '../../model/semantic-model.js';
@@ -29,6 +29,9 @@ export declare function emitFreeCallFallback(graph: KnowledgeGraph, scopes: Scop
     readonly bySourceScope: ReadonlyMap<ScopeId, readonly Reference[]>;
 }, handledSites: Set<string>, model: SemanticModel, workspaceIndex: WorkspaceResolutionIndex, options?: {
     readonly allowGlobalFallback?: boolean;
+    /** When true, `Type(...)` constructor calls link to the Class def
+     *  itself rather than its explicit Constructor. Swift opts in. */
+    readonly constructorCallTargetsClass?: boolean;
     readonly isFileLocalDef?: (def: SymbolDefinition) => boolean;
     readonly isCallableVisibleFromCaller?: (ctx: {
         readonly callerParsed: ParsedFile;
@@ -54,6 +57,70 @@ export declare function emitFreeCallFallback(graph: KnowledgeGraph, scopes: Scop
     readonly constraintCompatibility?: ScopeResolver['constraintCompatibility'];
     readonly recordResolutionOutcome?: ResolutionOutcomeRecorder;
 }): number;
+/**
+ * Build a `simpleName -> callable defs` index from `scopes.defs` once per
+ * pass. Mirrors the filter the old per-site scan applied: Function /
+ * Method / Constructor, keyed by the last `.`-segment of `qualifiedName`
+ * (falling back to the qualifiedName itself when undotted). Used by
+ * `pickUniqueGlobalCallable` so every free-call fallback site is O(1)
+ * instead of O(|defs|).
+ *
+ * Exported for unit testing — language-agnostic logic, exercised via synthetic
+ * stubs in `pick-unique-global-callable.test.ts`.
+ */
+export declare function buildGlobalCallableIndex(scopes: ScopeResolutionIndexes): ReadonlyMap<string, readonly SymbolDefinition[]>;
+/**
+ * Build a `simpleName -> class-like defs` index from `scopes.defs` once per
+ * pass — the structural sibling of `buildGlobalCallableIndex`, consumed by
+ * `pickUniqueGlobalClass` so constructor-form fallback is O(1)-per-site
+ * instead of O(|defs|).
+ *
+ * **Kind filter (KTD5 — KEEP `'Interface'`):** the set is
+ * `Class | Struct | Interface`, matching the idiomatic class-like set used
+ * elsewhere in the scope-resolution bridge (`graph-bridge/ids.ts`,
+ * `node-lookup.ts`). This is a behavior-PRESERVING perf refactor for all 8
+ * `allowGlobalFreeCallFallback` languages — the previous per-site scan used
+ * exactly this filter. Excluding Swift `protocol` (`Interface`) defs because
+ * protocols aren't instantiable is a *separate* Swift-semantics question with
+ * its own test; dropping `Interface` here would be a deliberate
+ * behavior-changing edit, not part of U5.
+ *
+ * Bucket insertion order follows `defs.byId.values()` iteration order, so the
+ * downstream "keep first" / ambiguity ordering in `pickUniqueGlobalClass` is
+ * byte-identical to the old linear scan (equivalence verified).
+ *
+ * Exported for unit testing — language-agnostic logic, exercised via synthetic
+ * stubs in `pick-unique-global-class.test.ts`.
+ */
+export declare function buildGlobalClassIndex(scopes: ScopeResolutionIndexes): ReadonlyMap<string, readonly SymbolDefinition[]>;
+/**
+ * Resolve a free (unqualified, receiver-less) call to a globally-unique
+ * callable def by simple name. See the in-body comments for the narrowing
+ * order. Exported for unit testing — the `scopeDefsCache` equivalence is
+ * exercised via synthetic stubs in `pick-unique-global-callable.test.ts`.
+ */
+export declare function pickUniqueGlobalCallable(name: string, model: SemanticModel, globalCallablesBySimpleName: ReadonlyMap<string, readonly SymbolDefinition[]>, callerFilePath: string, isFileLocalDef?: (def: SymbolDefinition) => boolean, callArity?: number, isCallerVisible?: (candidate: SymbolDefinition) => boolean, callArgTypes?: readonly string[], callArgTypeClasses?: readonly ParameterTypeClass[], conversionRankFn?: ConversionRankFn, scopeDefsCache?: Map<string, readonly SymbolDefinition[]>): SymbolDefinition | undefined;
+/** Find a unique workspace-wide class-like def by simple name, for a
+ *  constructor-form call `Type(...)` whose type lives outside the call
+ *  site's lexical bindings (a sibling/imported file). Returns the def
+ *  only when all matches share ONE qualified name — i.e. they are
+ *  fragments of a single logical type (partial classes / extensions
+ *  that re-key onto the same type), which resolve to the same graph
+ *  node. Genuinely distinct types with the same simple name are
+ *  ambiguous and leave the call unresolved rather than guessing. Gated
+ *  by the caller on `allowGlobalFallback`, mirroring
+ *  `pickUniqueGlobalCallable`.
+ *
+ *  Consumes the once-built `buildGlobalClassIndex` (`simpleName ->
+ *  class-like defs`) so each call site is O(1) rather than O(|defs|).
+ *  The index's `Class | Struct | Interface` kind filter is intentionally
+ *  KEPT (KTD5) — see `buildGlobalClassIndex` for why dropping `Interface`
+ *  would be a separate, behavior-changing Swift-semantics edit.
+ *
+ *  Exported for unit testing — language-agnostic logic, exercised via
+ *  synthetic stubs in `pick-unique-global-class.test.ts`. The production
+ *  call site is the constructor-form fallback in `emitFreeCallFallback`. */
+export declare function pickUniqueGlobalClass(name: string, index: ReadonlyMap<string, readonly SymbolDefinition[]>): SymbolDefinition | undefined;
 /** 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,