gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

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

@@ -49,6 +49,9 @@ export declare function emitFreeCallFallback(graph: KnowledgeGraph, scopes: Scop
             readonly startCol: number;
         };
     }, callerParsed: ParsedFile, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[]) => readonly SymbolDefinition[] | undefined;
+    /** Module-qualified free-call resolver (#2730) — see
+     *  `ScopeResolver.resolveQualifiedFreeCall`. */
+    readonly resolveQualifiedFreeCall?: ScopeResolver['resolveQualifiedFreeCall'];
     readonly conversionRankFn?: ConversionRankFn;
     readonly conversionOnlyArgTypePrefixes?: readonly string[];
     /** Optional per-language constraint hook threaded into
@@ -57,11 +60,23 @@ export declare function emitFreeCallFallback(graph: KnowledgeGraph, scopes: Scop
      *  fail at the call site. Three-valued; `'unknown'` keeps the
      *  candidate (monotonicity). */
     readonly constraintCompatibility?: ScopeResolver['constraintCompatibility'];
+    /** Platform/language built-in names (e.g. `fetch`, `setTimeout`) that
+     *  are never real repository declarations. Gates the finalize-bucket
+     *  guard below (#2545) -- see `hasGenuineLexicalBinding`. */
+    readonly isBuiltInName?: (name: string) => boolean;
+    /** Instance-ownership gate (#2550): a free call may resolve to a
+     *  `Method` only when the caller's enclosing class chain (self + MRO)
+     *  contains the method's owner. See
+     *  `ScopeResolver.freeCallsRequireInstanceOwnership`. */
+    readonly freeCallsRequireInstanceOwnership?: boolean;
     readonly recordResolutionOutcome?: ResolutionOutcomeRecorder;
-    /** Resolved-callee-id capture sink (#2227 U2). Threaded in only under
-     *  `--pdg`; `undefined` ⇒ zero overhead, byte-identity (R4). Captured at
-     *  the CALLS emit below BEFORE the collapsed `seen` dedup (KTD6) so
-     *  same-target multi-line calls are still recorded per site. */
+    /** Call sites owned by a later precise pass (for example callable-value-flow). */
+    readonly skipSites?: ReadonlySet<string>;
+    /** Resolved-callee-id capture sink (#2227 U2). Threaded in under `--pdg`
+     *  OR for callable-flow's direct-target index (#2437, position-filtered);
+     *  `undefined` ⇒ zero overhead, byte-identity (R4). Captured at the CALLS
+     *  emit below BEFORE the collapsed `seen` dedup (KTD6) so same-target
+     *  multi-line calls are still recorded per site. */
     readonly calleeIdSink?: CalleeIdSink;
 }): number;
 /**

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

@@ -17,7 +17,7 @@
  * generalization plan.
  */
 import { resolveCallerGraphId, resolveDefGraphId } from '../graph-bridge/ids.js';
-import { findAllCallableBindingsInScope, findCallableBindingInScope, findCallableBindingsAndAdlBlocker, resolveInheritanceBaseInScope, } from '../scope/walkers.js';
+import { findAllCallableBindingCandidatesInScope, findAllCallableBindingsInScope, findCallableBindingInScope, findCallableBindingsAndAdlBlocker, findEnclosingClassDef, resolveInheritanceBaseInScope, } from '../scope/walkers.js';
 import { isOverloadAmbiguousAfterNormalization, narrowOverloadCandidates, } from './overload-narrowing.js';
 export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _referenceIndex, handledSites, model, workspaceIndex, options = {}) {
     let emitted = 0;
@@ -32,6 +32,11 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
     // defs.byId.values() at every constructor call. Same simple-name keying
     // and class-like kind filter the previous per-site scan applied.
     const globalClassesBySimpleName = buildGlobalClassIndex(scopes);
+    // Workspace file-path set for `resolveQualifiedFreeCall` (a module path maps
+    // to a file by language convention). Built lazily and once: languages without
+    // the hook never pay for it.
+    let allFilePathsMemo;
+    const allFilePaths = () => (allFilePathsMemo ??= new Set(parsedFiles.map((p) => p.filePath)));
     // Per-pass memo of pickUniqueGlobalCallable's post-filter candidate list,
     // keyed (simpleName, callerFilePath). Only created when no per-caller
     // visibility filter applies (the list is then a pure function of name+file —
@@ -40,12 +45,50 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
     const scopeDefsCache = options.isCallableVisibleFromCaller === undefined
         ? new Map()
         : undefined;
+    const enclosingInstanceOwnerByScope = options.freeCallsRequireInstanceOwnership === true
+        ? new Map()
+        : undefined;
+    const reachableInstanceOwnersByOwner = options.freeCallsRequireInstanceOwnership === true
+        ? new Map()
+        : undefined;
+    const instanceOwnerKey = (ownerId) => {
+        const owner = scopes.defs.get(ownerId);
+        const qualifiedName = owner?.qualifiedName;
+        if (qualifiedName === undefined || qualifiedName === '')
+            return ownerId;
+        const namespacePrefix = owner.namespacePrefix ?? '';
+        return `${namespacePrefix.length}:${namespacePrefix}:${qualifiedName}`;
+    };
+    const isReachableInstanceOwner = (scopeId, ownerId) => {
+        let enclosing = enclosingInstanceOwnerByScope?.get(scopeId);
+        if (enclosing === undefined) {
+            enclosing = findEnclosingClassDef(scopeId, scopes) ?? null;
+            enclosingInstanceOwnerByScope?.set(scopeId, enclosing);
+        }
+        if (enclosing === null)
+            return false;
+        let owners = reachableInstanceOwnersByOwner?.get(enclosing.nodeId);
+        if (owners === undefined) {
+            const mutableOwners = new Set([instanceOwnerKey(enclosing.nodeId)]);
+            for (const inheritedOwnerId of scopes.methodDispatch.mroFor(enclosing.nodeId)) {
+                mutableOwners.add(instanceOwnerKey(inheritedOwnerId));
+            }
+            owners = mutableOwners;
+            reachableInstanceOwnersByOwner?.set(enclosing.nodeId, owners);
+        }
+        return owners.has(instanceOwnerKey(ownerId));
+    };
     for (const parsed of parsedFiles) {
+        const bindingCandidatesByScope = options.freeCallsRequireInstanceOwnership === true
+            ? new Map()
+            : undefined;
         for (const site of parsed.referenceSites) {
             if (site.kind !== 'call')
                 continue;
             if (site.explicitReceiver !== undefined)
                 continue;
+            if (options.skipSites?.has(siteKey(parsed.filePath, site)) === true)
+                continue;
             // Constructor form (`new User(...)`): resolve the class, then
             // emit CALLS to its explicit Constructor def (when present) or
             // to the Class node itself (implicit constructor). Legacy emits
@@ -80,6 +123,18 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
                     }
                 }
             }
+            // Module-qualified free call (`mod::fn()`): the source named the module
+            // explicitly, so that path outranks every lexical tier below — otherwise
+            // the scope-chain walk binds the bare tail to a same-named definition in
+            // the caller's own file and emits a self-loop instead of the real
+            // cross-module edge (#2730). Only fires when the language populated
+            // `rawQualifiedName` AND provides the hook; `undefined` falls through to
+            // the unchanged chain, so this tier is strictly additive.
+            if (fnDef === undefined &&
+                options.resolveQualifiedFreeCall !== undefined &&
+                site.rawQualifiedName !== undefined) {
+                fnDef = options.resolveQualifiedFreeCall(site, parsed, scopes, workspaceIndex, allFilePaths());
+            }
             // Implicit-this overload narrowing: an unqualified call inside
             // a method body might be calling a sibling overload on the
             // enclosing class. When the workspace has multiple methods of
@@ -106,9 +161,82 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
                     // (local shadows import). When a conversion-rank function is
                     // available AND the binding scope contains multiple overloads,
                     // refine with narrowOverloadCandidates (#1578).
-                    fnDef = findCallableBindingInScope(site.inScope, site.name, scopes);
-                    if (fnDef !== undefined && options.conversionRankFn !== undefined) {
-                        const allCallables = findAllCallableBindingsInScope(site.inScope, site.name, scopes);
+                    let bindingCandidates;
+                    if (bindingCandidatesByScope !== undefined) {
+                        let byName = bindingCandidatesByScope.get(site.inScope);
+                        if (byName === undefined) {
+                            byName = new Map();
+                            bindingCandidatesByScope.set(site.inScope, byName);
+                        }
+                        bindingCandidates = byName.get(site.name);
+                        if (bindingCandidates === undefined) {
+                            bindingCandidates = findAllCallableBindingCandidatesInScope(site.inScope, site.name, scopes);
+                            byName.set(site.name, bindingCandidates);
+                        }
+                    }
+                    let eligibleBindingCandidates;
+                    if (bindingCandidates === undefined) {
+                        fnDef = findCallableBindingInScope(site.inScope, site.name, scopes);
+                    }
+                    else {
+                        eligibleBindingCandidates = bindingCandidates.filter((candidate) => {
+                            const def = candidate.def;
+                            if (def.type !== 'Method' ||
+                                def.ownerId === undefined ||
+                                def.filePath !== parsed.filePath) {
+                                return true;
+                            }
+                            const ownerReachable = isReachableInstanceOwner(site.inScope, def.ownerId);
+                            const staticallyImported = candidate.bindings.some((binding) => binding.visibility === 'static-member-import');
+                            return ownerReachable || staticallyImported;
+                        });
+                        fnDef = eligibleBindingCandidates[0]?.def;
+                        if (fnDef === undefined && bindingCandidates.length > 0) {
+                            recordSuppressedOutcome(options.recordResolutionOutcome, {
+                                phase: 'free-call-fallback',
+                                filePath: parsed.filePath,
+                                name: site.name,
+                                range: site.atRange,
+                                reason: 'free-call-instance-ownership',
+                                candidates: bindingCandidates.map((candidate) => candidate.def),
+                            });
+                        }
+                    }
+                    if (fnDef !== undefined &&
+                        options.isBuiltInName?.(site.name) === true &&
+                        fnDef.filePath === parsed.filePath &&
+                        eligibleBindingCandidates?.some((candidate) => candidate.bindings.some((binding) => binding.visibility === 'static-member-import')) !== true &&
+                        !hasGenuineLexicalBinding(site.inScope, site.name, scopes)) {
+                        // A platform/language built-in (e.g. `fetch`, `setTimeout`)
+                        // with no binding reachable via the TRUE lexical scope chain
+                        // (Scope.bindings only) -- the match came solely from
+                        // finalize's per-file "local + imports + wildcards" bucket,
+                        // which flattens every declaration in the file onto the
+                        // module scope regardless of true nesting depth
+                        // (gitnexus-shared's `materializeBindings`). That flattening
+                        // is correct for its purpose (cross-file import targets) but
+                        // over-matches same-file built-in-shadowing declarations that
+                        // were never really module-scope-visible -- e.g. a Cloudflare
+                        // Worker's `export default { fetch(req) {} }` handler (#2545).
+                        // Leave the call unresolved rather than emit a false edge.
+                        //
+                        // `fnDef.filePath === parsed.filePath` is the load-bearing
+                        // guard against a real regression: `materializeBindings`'s
+                        // flat bucket is per-file, so the leak this guard targets is
+                        // ALWAYS same-file. A cross-file match at this point can only
+                        // come from a genuine import/namespace/workspace-FQN channel
+                        // (the separate, gated `pickUniqueGlobalCallable` global
+                        // fallback runs later and isn't what populated `fnDef` here)
+                        // -- e.g. `import { fetch } from './fetch-polyfill'` must
+                        // keep resolving. Without this check, that import silently
+                        // stopped resolving (verified via a scratch probe fixture).
+                        fnDef = undefined;
+                    }
+                    if (fnDef !== undefined &&
+                        (options.conversionRankFn !== undefined || bindingCandidates !== undefined)) {
+                        const allCallables = eligibleBindingCandidates === undefined
+                            ? findAllCallableBindingsInScope(site.inScope, site.name, scopes)
+                            : eligibleBindingCandidates.map((candidate) => candidate.def);
                         if (allCallables.length > 1) {
                             const narrowed = narrowOverloadCandidates(allCallables, site.arity, site.argumentTypes, {
                                 argumentTypeClasses: site.argumentTypeClasses,
@@ -707,3 +835,31 @@ export function pickImplicitThisOverload(site, scopes, workspaceIndex, model, ho
         return undefined;
     return candidates[0];
 }
+/**
+ * True when `name` is bound somewhere along the TRUE lexical scope
+ * chain from `startScope` -- i.e. via `Scope.bindings` (the raw,
+ * nesting-aware per-scope map built during extraction), NOT via
+ * finalize's `indexes.bindings` module-scope bucket (which flattens
+ * every declaration in the file onto the module scope regardless of
+ * true nesting -- see `hasGenuineLexicalBinding`'s caller for why that
+ * distinction matters, #2545).
+ */
+function hasGenuineLexicalBinding(startScope, name, scopes) {
+    let currentId = startScope;
+    const visited = new Set();
+    while (currentId !== null) {
+        if (visited.has(currentId))
+            return false;
+        visited.add(currentId);
+        const scope = scopes.scopeTree.getScope(currentId);
+        if (scope === undefined)
+            return false;
+        // `Object` scopes (object/record literal bodies) are a hoist
+        // boundary only -- never a genuine lexical binding, not even to
+        // their own nested children (#2551, mirrors scope/walkers.ts).
+        if (scope.kind !== 'Object' && scope.bindings.get(name) !== undefined)
+            return true;
+        currentId = scope.parent;
+    }
+    return false;
+}

package/dist/core/ingestion/scope-resolution/passes/imported-value-refs.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cross-file value references, resolved post-finalize (A2).
+ *
+ * `resolveReferenceSites` runs against the registries, and — as its own
+ * comment says — "imports live in finalized bindings the registries can't
+ * see". That is why free CALLS need `emitFreeCallFallback`. Reads had no
+ * equivalent, so a module-scope `const` read from another file resolved to
+ * nothing: `import { DEFAULT_FETCH_LIMIT } from './config.js'` followed by a
+ * bare use produced no edge, while a CALL through the very same import
+ * statement resolved fine. "Who imports this constant?" — the question behind
+ * every constants refactor and dead-code trim — was unanswerable across files.
+ *
+ * This is the read/write counterpart to that call fallback, and it reuses the
+ * walker built for finalized bindings rather than inventing a lookup.
+ *
+ * DELIBERATELY CROSS-FILE ONLY. Same-file reads already resolve through the
+ * registries, so re-resolving them here would add nothing — and would add
+ * something unwanted: `findValueBindingInScope` accepts `Const`/`Variable`,
+ * which includes BLOCK-LOCAL values. Emitting an edge to one of those keeps
+ * alive exactly the inert local symbols `pruneLocalSymbols` exists to drop,
+ * inflating every indexed repo. A def in another file cannot be a block-local
+ * of this one, so the file guard is what keeps this pass proportional.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../../graph/types.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+export interface ImportedValueRefStats {
+    /** Cross-file value references resolved through finalized bindings. */
+    readonly emitted: number;
+}
+export declare function emitImportedValueReferences(graph: KnowledgeGraph, indexes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, 
+/** Sites an earlier pass already owns — never re-resolved here. */
+skipSites: ReadonlySet<string>): ImportedValueRefStats;

package/dist/core/ingestion/scope-resolution/passes/imported-value-refs.js

@@ -0,0 +1,62 @@
+/**
+ * Cross-file value references, resolved post-finalize (A2).
+ *
+ * `resolveReferenceSites` runs against the registries, and — as its own
+ * comment says — "imports live in finalized bindings the registries can't
+ * see". That is why free CALLS need `emitFreeCallFallback`. Reads had no
+ * equivalent, so a module-scope `const` read from another file resolved to
+ * nothing: `import { DEFAULT_FETCH_LIMIT } from './config.js'` followed by a
+ * bare use produced no edge, while a CALL through the very same import
+ * statement resolved fine. "Who imports this constant?" — the question behind
+ * every constants refactor and dead-code trim — was unanswerable across files.
+ *
+ * This is the read/write counterpart to that call fallback, and it reuses the
+ * walker built for finalized bindings rather than inventing a lookup.
+ *
+ * DELIBERATELY CROSS-FILE ONLY. Same-file reads already resolve through the
+ * registries, so re-resolving them here would add nothing — and would add
+ * something unwanted: `findValueBindingInScope` accepts `Const`/`Variable`,
+ * which includes BLOCK-LOCAL values. Emitting an edge to one of those keeps
+ * alive exactly the inert local symbols `pruneLocalSymbols` exists to drop,
+ * inflating every indexed repo. A def in another file cannot be a block-local
+ * of this one, so the file guard is what keeps this pass proportional.
+ */
+import { tryEmitEdge } from '../graph-bridge/edges.js';
+import { findValueBindingInScope } from '../scope/walkers.js';
+import { callableFlowSiteKey } from './callable-value-flow.js';
+/**
+ * Confidence for a reference resolved through a finalized import binding.
+ * This is a PRECISE resolution — the import names the def — so it carries the
+ * ordinary emission confidence, not the reduced tier used for name inference.
+ */
+const IMPORTED_VALUE_CONFIDENCE = 0.9;
+export function emitImportedValueReferences(graph, indexes, parsedFiles, nodeLookup, 
+/** Sites an earlier pass already owns — never re-resolved here. */
+skipSites) {
+    let emitted = 0;
+    const seen = new Set();
+    for (const parsed of parsedFiles) {
+        for (const site of parsed.referenceSites) {
+            if (site.kind !== 'read' && site.kind !== 'write')
+                continue;
+            // A member read (`obj.field`) is the receiver-bound passes' business;
+            // this pass exists for the BARE identifier an import binds.
+            if (site.explicitReceiver !== undefined)
+                continue;
+            const siteKey = callableFlowSiteKey(parsed.filePath, site.atRange);
+            if (skipSites.has(siteKey))
+                continue;
+            const def = findValueBindingInScope(site.inScope, site.name, indexes);
+            if (def === undefined)
+                continue;
+            // See the header: same-file hits are already resolved, and accepting
+            // them here would start emitting edges to block-local values.
+            if (def.filePath === parsed.filePath)
+                continue;
+            if (tryEmitEdge(graph, indexes, nodeLookup, site, def, 'import-resolved', seen, IMPORTED_VALUE_CONFIDENCE)) {
+                emitted++;
+            }
+        }
+    }
+    return { emitted };
+}

package/dist/core/ingestion/scope-resolution/passes/property-dispatch.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `emitPropertyDispatchCalls` — value-ref registration edges + field-based
+ * dispatch for functions registered as object-literal property values
+ * (#2437).
+ *
+ * A provider-hook registration (`{ emitScopeCaptures: emitCppScopeCaptures }`)
+ * emits a USES reference edge — a registration is not an invocation (Kythe
+ * `ref` vs `ref/call`; Joern `METHOD_REF`). The invocation happens later
+ * through the property (`provider.emitScopeCaptures(...)`) — a dispatch the
+ * receiver-bound pass cannot resolve because object literals are not
+ * IMPLEMENTS-linked implementors. This pass closes that soundness gap the
+ * field-based way (Feldthaus et al., ICSE'13; CodeQL `impliedReceiverStep`):
+ * key registrations by property name and connect every member-call site
+ * `x.<key>(...)` to every function registered under `<key>`.
+ *
+ * This pass is the SINGLE owner of `value-ref` resolution. The shared
+ * registries only consult pre-finalize local bindings — imported names live
+ * in finalized bindings (the same reason free calls need
+ * `emitFreeCallFallback`) — so `resolveReferenceSites` skips `value-ref`
+ * sites and this pass resolves them post-finalize via
+ * `findCallableBindingInScope` (Function/Method/Constructor only — the
+ * callable gate that keeps `{ port: DEFAULT_PORT }` from emitting anything).
+ *
+ * Precision posture (mirrors `emitInterfaceDispatchFor`):
+ *   - reason `'property-dispatch'` keeps synthesized CALLS auditable;
+ *   - dispatch confidence 0.7 sits below the 0.85 resolved baseline;
+ *   - a per-key fan-out cap drops promiscuous names (`handler`, `callback`)
+ *     entirely rather than truncating silently — property-name collisions
+ *     across unrelated objects are the documented field-based failure mode.
+ *
+ * Ordering: runs AFTER the precise emit passes. `graph.addRelationship` is
+ * first-write-wins on the position-keyed edge id, so a site that already
+ * resolved precisely to the same target keeps its precise edge.
+ *
+ * Language-neutral: consumes only `value-ref` sites (any language that
+ * emits the capture participates) and generic member-call sites.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../../graph/types.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+import type { CalleeIdSink } from '../graph-bridge/callee-id-sink.js';
+/**
+ * Keys registered by more than this many distinct functions are skipped —
+ * dispatch through such a name says nothing about which function runs.
+ * Calibrated on this repo's own provider tables: `emitScopeCaptures` has 16
+ * legitimate registrations (one per language provider), so the cap sits at
+ * 2× that — dropping the motivating key was the failure the first value (8)
+ * had. ponytail: flat cap; revisit with per-receiver narrowing if real
+ * repos show useful keys being dropped (§12 of the #2437 plan).
+ *
+ * Override via `GITNEXUS_MAX_PROPERTY_DISPATCH_FANOUT` env var for repos with
+ * legitimate high-fanout property keys (e.g. large Vue codebases where
+ * `validator` exceeds the default).
+ */
+export declare const MAX_PROPERTY_DISPATCH_FANOUT: number;
+/** Below the 0.85 resolved baseline; same discount idea as interface-dispatch. */
+export declare const PROPERTY_DISPATCH_CONFIDENCE = 0.7;
+export declare function emitPropertyDispatchCalls(graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, calleeIdSink?: CalleeIdSink): {
+    usesEmitted: number;
+    callsEmitted: number;
+    skippedKeys: number;
+    skippedKeyNames: readonly string[];
+};

package/dist/core/ingestion/scope-resolution/passes/property-dispatch.js

@@ -0,0 +1,118 @@
+/**
+ * `emitPropertyDispatchCalls` — value-ref registration edges + field-based
+ * dispatch for functions registered as object-literal property values
+ * (#2437).
+ *
+ * A provider-hook registration (`{ emitScopeCaptures: emitCppScopeCaptures }`)
+ * emits a USES reference edge — a registration is not an invocation (Kythe
+ * `ref` vs `ref/call`; Joern `METHOD_REF`). The invocation happens later
+ * through the property (`provider.emitScopeCaptures(...)`) — a dispatch the
+ * receiver-bound pass cannot resolve because object literals are not
+ * IMPLEMENTS-linked implementors. This pass closes that soundness gap the
+ * field-based way (Feldthaus et al., ICSE'13; CodeQL `impliedReceiverStep`):
+ * key registrations by property name and connect every member-call site
+ * `x.<key>(...)` to every function registered under `<key>`.
+ *
+ * This pass is the SINGLE owner of `value-ref` resolution. The shared
+ * registries only consult pre-finalize local bindings — imported names live
+ * in finalized bindings (the same reason free calls need
+ * `emitFreeCallFallback`) — so `resolveReferenceSites` skips `value-ref`
+ * sites and this pass resolves them post-finalize via
+ * `findCallableBindingInScope` (Function/Method/Constructor only — the
+ * callable gate that keeps `{ port: DEFAULT_PORT }` from emitting anything).
+ *
+ * Precision posture (mirrors `emitInterfaceDispatchFor`):
+ *   - reason `'property-dispatch'` keeps synthesized CALLS auditable;
+ *   - dispatch confidence 0.7 sits below the 0.85 resolved baseline;
+ *   - a per-key fan-out cap drops promiscuous names (`handler`, `callback`)
+ *     entirely rather than truncating silently — property-name collisions
+ *     across unrelated objects are the documented field-based failure mode.
+ *
+ * Ordering: runs AFTER the precise emit passes. `graph.addRelationship` is
+ * first-write-wins on the position-keyed edge id, so a site that already
+ * resolved precisely to the same target keeps its precise edge.
+ *
+ * Language-neutral: consumes only `value-ref` sites (any language that
+ * emits the capture participates) and generic member-call sites.
+ */
+import { tryEmitEdge } from '../graph-bridge/edges.js';
+import { findCallableBindingInScope } from '../scope/walkers.js';
+/**
+ * Keys registered by more than this many distinct functions are skipped —
+ * dispatch through such a name says nothing about which function runs.
+ * Calibrated on this repo's own provider tables: `emitScopeCaptures` has 16
+ * legitimate registrations (one per language provider), so the cap sits at
+ * 2× that — dropping the motivating key was the failure the first value (8)
+ * had. ponytail: flat cap; revisit with per-receiver narrowing if real
+ * repos show useful keys being dropped (§12 of the #2437 plan).
+ *
+ * Override via `GITNEXUS_MAX_PROPERTY_DISPATCH_FANOUT` env var for repos with
+ * legitimate high-fanout property keys (e.g. large Vue codebases where
+ * `validator` exceeds the default).
+ */
+export const MAX_PROPERTY_DISPATCH_FANOUT = (() => {
+    const env = Number(process.env.GITNEXUS_MAX_PROPERTY_DISPATCH_FANOUT);
+    return Number.isInteger(env) && env >= 1 ? env : 32;
+})();
+/** Below the 0.85 resolved baseline; same discount idea as interface-dispatch. */
+export const PROPERTY_DISPATCH_CONFIDENCE = 0.7;
+export function emitPropertyDispatchCalls(graph, scopes, parsedFiles, nodeLookup, calleeIdSink) {
+    const seen = new Set();
+    let usesEmitted = 0;
+    // Sweep 1 — resolve every value-ref site: emit the USES registration edge
+    // and index dispatchable registrations by property key.
+    const registrations = new Map();
+    for (const parsed of parsedFiles) {
+        for (const site of parsed.referenceSites) {
+            if (site.kind !== 'value-ref')
+                continue;
+            const def = findCallableBindingInScope(site.inScope, site.name, scopes);
+            if (def === undefined)
+                continue;
+            const ok = tryEmitEdge(graph, scopes, nodeLookup, site, def, 'scope-resolution: value-ref', seen);
+            if (ok)
+                usesEmitted++;
+            if (site.propertyKey === undefined)
+                continue;
+            let byDef = registrations.get(site.propertyKey);
+            if (byDef === undefined) {
+                byDef = new Map();
+                registrations.set(site.propertyKey, byDef);
+            }
+            byDef.set(def.nodeId, def);
+        }
+    }
+    // Keep the dropped key NAMES (bounded) — an over-cap key means no CALLS
+    // are synthesized through it, and a count alone leaves the operator unable
+    // to tell WHICH hook table lost coverage (#2522 review).
+    let skippedKeys = 0;
+    const skippedKeyNames = [];
+    for (const [key, defs] of registrations) {
+        if (defs.size > MAX_PROPERTY_DISPATCH_FANOUT) {
+            registrations.delete(key);
+            skippedKeys++;
+            if (skippedKeyNames.length < 20)
+                skippedKeyNames.push(key);
+        }
+    }
+    // Sweep 2 — synthesize CALLS from member-call sites through registered keys.
+    let callsEmitted = 0;
+    if (registrations.size > 0) {
+        for (const parsed of parsedFiles) {
+            const calleeCapture = calleeIdSink !== undefined ? { sink: calleeIdSink, filePath: parsed.filePath } : undefined;
+            for (const site of parsed.referenceSites) {
+                if (site.kind !== 'call' || site.callForm !== 'member')
+                    continue;
+                const defs = registrations.get(site.name);
+                if (defs === undefined)
+                    continue;
+                for (const def of defs.values()) {
+                    const ok = tryEmitEdge(graph, scopes, nodeLookup, site, def, 'property-dispatch', seen, PROPERTY_DISPATCH_CONFIDENCE, false, calleeCapture);
+                    if (ok)
+                        callsEmitted++;
+                }
+            }
+        }
+    }
+    return { usesEmitted, callsEmitted, skippedKeys, skippedKeyNames };
+}