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

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

@@ -34,9 +34,24 @@
  *      as `ownedDefs` + a local `BindingRef { origin: 'local' }`.
  *   3. **Collect raw imports.** Walk `@import.*` matches. Call
  *      `provider.interpretImport` per match; attach the returned
- *      `ParsedImport` to the ParsedFile (not to any `Scope` — finalize
- *      reconstructs the owning scope via `provider.importOwningScope`
- *      during Phase 2).
+ *      `ParsedImport` to the ParsedFile — not to any `Scope`.
+ *      `provider.importOwningScope` is declared on `LanguageProvider` and
+ *      implemented by a dozen providers, but has no call site anywhere; this
+ *      step's output is a flat per-file list.
+ *
+ *      One scope fact is read before that list flattens it away:
+ *      `runsOnlyWhenCalled`, set when the statement sits anywhere inside a
+ *      `Function`. It is decided here because here is the last stage that can
+ *      — finalize receives the flat list, and its consumer receives a map
+ *      keyed by the file's Module scope only (see
+ *      `ParsedImport.runsOnlyWhenCalled`). This is a position fact, not a
+ *      syntax one, so it is decided centrally for every language rather than
+ *      per provider — with one capability a provider may declare to opt out
+ *      of it entirely, `importsExecuteWhereWritten: false`, because position
+ *      cannot defer an import that never executes (C/C++ `#include`, Rust
+ *      `use`, COBOL `COPY`). Providers still decide their own *syntactic* nesting
+ *      facts in their capture emitters, where the node is in hand (see
+ *      `languages/python/import-decomposer.ts`).
  *   4. **Collect type bindings.** Walk `@type-binding.*` matches. Call
  *      `provider.interpretTypeBinding` per match. Attach the resulting
  *      `TypeRef` to the innermost containing scope's `typeBindings`
@@ -59,7 +74,9 @@
  *   - `ParsedFile.referenceSites` — pre-resolution usage facts.
  */
 import { buildPositionIndex, buildScopeTree, canParentScope, makeScopeId } from '../../_shared/index.js';
-import { extractTemplateArguments } from './utils/template-arguments.js';
+import { isValidReceiverChain } from './utils/receiver-chain-codec.js';
+import { extractTemplateArguments, stripTrailingCallSuffix, typeApplicationArguments, } from './utils/template-arguments.js';
+import { parseTypeParameterList } from './utils/type-parameters.js';
 // ─── Public entry point ─────────────────────────────────────────────────────
 /**
  * Drive the five extraction passes and return a `ParsedFile`.
@@ -84,7 +101,11 @@ export function extract(matches, filePath, provider) {
     for (let i = 0; i < scopeDrafts.length; i++) {
         const d = scopeDrafts[i];
         if (d.parent === null && d.kind !== 'Module') {
-            scopeDrafts[i] = makeDraft(d.id, moduleScope.id, d.kind, d.range, d.filePath);
+            // `ownsReceivers` must be carried across: it is decided from the scope's
+            // own capture in pass 1 and re-parenting does not change what the scope
+            // binds. Dropping it here would silently un-mark every function scope in
+            // a file whose root parsed as ERROR (the only way a scope is orphaned).
+            scopeDrafts[i] = makeDraft(d.id, moduleScope.id, d.kind, d.range, d.filePath, d.ownsReceivers, d.lexicalNames);
         }
     }
     const scopes = scopeDrafts.map(draftToScope);
@@ -105,12 +126,17 @@ export function extract(matches, filePath, provider) {
     pass2AttachDeclarations(partitioned.declaration, scopeDrafts, positionIndex, localDefs, filePath, provider, scopeTree);
     // ── Pass 3: collect raw imports ─────────────────────────────────────
     const parsedImports = [];
-    pass3CollectImports(partitioned.import_, parsedImports, provider);
+    pass3CollectImports(partitioned.import_, positionIndex, filePath, parsedImports, provider, scopeTree);
     // ── Pass 4: collect type bindings ───────────────────────────────────
     pass4CollectTypeBindings(partitioned.typeBinding, scopeDrafts, positionIndex, filePath, provider, scopeTree);
     // ── Pass 5: collect reference sites ─────────────────────────────────
     const referenceSites = [];
     pass5CollectReferences(partitioned.reference, positionIndex, filePath, referenceSites, provider, scopeTree);
+    // ── Pass 6: collect normalized callable-value-flow facts ───────────
+    // Kept after (and independent from) Pass 5 so existing reference-site
+    // extraction remains byte-identical.
+    const callableFlowSites = [];
+    pass6CollectCallableFlows(partitioned.callableFlow, positionIndex, filePath, callableFlowSites);
     // Freeze Scope drafts into final shape and return.
     const frozenScopes = scopeDrafts.map(draftToScope);
     return Object.freeze({
@@ -120,12 +146,15 @@ export function extract(matches, filePath, provider) {
         parsedImports: Object.freeze(parsedImports.slice()),
         localDefs: Object.freeze(localDefs.slice()),
         referenceSites: Object.freeze(referenceSites.slice()),
+        ...(callableFlowSites.length > 0
+            ? { callableFlowSites: Object.freeze(callableFlowSites.slice()) }
+            : {}),
     });
 }
 /**
- * Bucket each match by the topic of its anchor capture. The anchor is the
- * capture whose name is prefixed with the match's topic (`@scope.*`,
- * `@declaration.*`, `@import.*`, `@type-binding.*`, `@reference.*`).
+ * Bucket each match by every topic represented by its anchor captures. An
+ * emitter may deliberately group a lexical scope and its declaration in one
+ * match so both passes observe the exact same source range.
  *
  * A match may contain additional captures (e.g., `@import.source`,
  * `@declaration.class.name`) that are used by the provider hooks to
@@ -138,49 +167,50 @@ function partitionByTopic(matches) {
     const import_ = [];
     const typeBinding = [];
     const reference = [];
+    const callableFlow = [];
     for (const match of matches) {
-        const topic = topicOf(match);
-        switch (topic) {
-            case 'scope':
-                scope.push(match);
-                break;
-            case 'declaration':
-                declaration.push(match);
-                break;
-            case 'import':
-                import_.push(match);
-                break;
-            case 'type-binding':
-                typeBinding.push(match);
-                break;
-            case 'reference':
-                reference.push(match);
-                break;
-            case 'unknown':
-                // Unrecognized anchor — silently skip. Providers may emit extra
-                // captures (e.g., `@comment`) that the extractor has no topic for.
-                break;
+        for (const topic of topicsOf(match)) {
+            switch (topic) {
+                case 'scope':
+                    scope.push(match);
+                    break;
+                case 'declaration':
+                    declaration.push(match);
+                    break;
+                case 'import':
+                    import_.push(match);
+                    break;
+                case 'type-binding':
+                    typeBinding.push(match);
+                    break;
+                case 'reference':
+                    reference.push(match);
+                    break;
+                case 'callable-flow':
+                    callableFlow.push(match);
+                    break;
+            }
         }
     }
-    return { scope, declaration, import_, typeBinding, reference };
+    return { scope, declaration, import_, typeBinding, reference, callableFlow };
 }
-function topicOf(match) {
-    // The anchor is the capture whose name uses one of the known topic
-    // prefixes. For multi-capture matches, ALL captures share the topic;
-    // we pick the first matching key for efficiency.
+function topicsOf(match) {
+    const topics = new Set();
     for (const name of Object.keys(match)) {
         if (name.startsWith('@scope.'))
-            return 'scope';
-        if (name.startsWith('@declaration.'))
-            return 'declaration';
-        if (name.startsWith('@import.'))
-            return 'import';
-        if (name.startsWith('@type-binding.'))
-            return 'type-binding';
-        if (name.startsWith('@reference.'))
-            return 'reference';
-    }
-    return 'unknown';
+            topics.add('scope');
+        else if (name.startsWith('@declaration.'))
+            topics.add('declaration');
+        else if (name.startsWith('@import.'))
+            topics.add('import');
+        else if (name.startsWith('@type-binding.'))
+            topics.add('type-binding');
+        else if (name.startsWith('@reference.'))
+            topics.add('reference');
+        else if (name.startsWith('@callable-flow.'))
+            topics.add('callable-flow');
+    }
+    return topics;
 }
 function ensureModuleScope(scopeDrafts, filePath, allMatches) {
     const moduleScope = scopeDrafts.find((s) => s.kind === 'Module');
@@ -221,6 +251,8 @@ function draftToScope(draft) {
         ownedDefs: Object.freeze(draft.ownedDefs.slice()),
         imports: Object.freeze(draft.imports.slice()),
         typeBindings: new Map(draft.typeBindings),
+        lexicalNames: draft.lexicalNames,
+        ownsReceivers: draft.ownsReceivers,
     };
 }
 // ─── Pass 1: build scope tree ──────────────────────────────────────────────
@@ -274,7 +306,7 @@ function pass1BuildScopes(matches, filePath, provider) {
             stack.pop();
         }
         const parent = stack.length > 0 ? stack[stack.length - 1].id : null;
-        drafts.push(makeDraft(cand.id, parent, cand.kind, cand.range, filePath));
+        drafts.push(makeDraft(cand.id, parent, cand.kind, cand.range, filePath, provider.scopeOwnsReceivers?.(cand.match), parseScopeLexicalNames(cand.match)));
         stack.push(cand);
     }
     return drafts;
@@ -299,11 +331,13 @@ function resolveKindForScopeMatch(match, anchor, provider) {
             return 'Block';
         case 'expression':
             return 'Expression';
+        case 'object':
+            return 'Object';
         default:
             return null;
     }
 }
-function makeDraft(id, parent, kind, range, filePath) {
+function makeDraft(id, parent, kind, range, filePath, ownsReceivers, lexicalNames) {
     return {
         id,
         parent,
@@ -314,13 +348,35 @@ function makeDraft(id, parent, kind, range, filePath) {
         ownedDefs: [],
         imports: [],
         typeBindings: new Map(),
+        lexicalNames,
+        ownsReceivers,
     };
 }
+function parseScopeLexicalNames(match) {
+    const raw = match['@scope.lexical-names']?.text;
+    if (raw === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return undefined;
+        const names = parsed.filter((name) => typeof name === 'string' && name.length > 0);
+        return names.length > 0 ? new Set(names) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 // ─── Pass 2: attach declarations + local bindings ──────────────────────────
 function pass2AttachDeclarations(matches, drafts, positionIndex, localDefs, filePath, provider, scopeTree) {
     const draftById = new Map();
     for (const d of drafts)
         draftById.set(d.id, d);
+    // First def seen per `nodeId`, for the duplicate backfill below. Two query
+    // patterns can legitimately match ONE declaration — a C++ templated struct
+    // matches both the standalone `struct_specifier` rule and the
+    // `template_declaration` rule that wraps it — and both mint the same def id.
+    const firstDefByNodeId = new Map();
     for (const match of matches) {
         const anchor = anchorCaptureFor(match, '@declaration.');
         if (anchor === undefined)
@@ -328,6 +384,32 @@ function pass2AttachDeclarations(matches, drafts, positionIndex, localDefs, file
         const def = buildDefFromDeclarationMatch(match, anchor, filePath);
         if (def === undefined)
             continue;
+        // ── Duplicate-declaration backfill ───────────────────────────────────────
+        // `buildDefIndex` is FIRST-WRITE-WINS, so when one declaration produces two
+        // defs under one id, whichever match tree-sitter reported first is the one
+        // resolution sees. That was harmless while the twins were byte-identical.
+        // It stops being harmless the moment one twin can carry a field the other
+        // structurally cannot: a C++ `template <class T> struct Vec` has its
+        // parameter list on the ENCLOSING `template_declaration`, so the standalone
+        // `struct_specifier` twin can never see it, and match order would silently
+        // decide whether `Vec` remembers `T`. Source order deciding a resolution
+        // fact is the failure mode this subsystem rejects everywhere else.
+        //
+        // Copying the field onto BOTH twins makes the outcome identical whichever
+        // one wins. Deliberately narrow — only `typeParameters`, the one field with
+        // an asymmetric twin today. Widening this to "merge all metadata" would
+        // change what every existing duplicate resolves to, which is a different
+        // change with a different blast radius and no evidence behind it yet.
+        const first = firstDefByNodeId.get(def.nodeId);
+        if (first === undefined) {
+            firstDefByNodeId.set(def.nodeId, def);
+        }
+        else if (first.typeParameters === undefined && def.typeParameters !== undefined) {
+            first.typeParameters = def.typeParameters;
+        }
+        else if (def.typeParameters === undefined && first.typeParameters !== undefined) {
+            def.typeParameters = first.typeParameters;
+        }
         // Find the innermost scope that contains the declaration's anchor range.
         const innermostId = positionIndex.atPosition(filePath, anchor.range.startLine, anchor.range.startCol);
         if (innermostId === undefined)
@@ -398,8 +480,15 @@ function buildDefFromDeclarationMatch(match, anchor, filePath) {
     const declaredType = match['@declaration.field-type']?.text;
     const returnType = match['@declaration.return-type']?.text;
     const templateConstraints = parseJsonCapture(match['@declaration.template-constraints']);
+    // The DECLARED parameters, a different axis from `templateArguments` above:
+    // that reads the arguments written on the name, this reads the list the
+    // declaration was written in terms of. A declaration can carry both, and for a
+    // C++ partial specialization the pairing is the only thing that tells it apart
+    // from a full specialization with the identical arguments.
+    const typeParameters = parseTypeParameterList(match['@declaration.type-parameters']?.text ?? '');
     const isExplicit = parseBooleanCapture(match['@declaration.is-explicit']);
     const isDeleted = parseBooleanCapture(match['@declaration.is-deleted']);
+    const isSynthetic = parseBooleanCapture(match['@declaration.is-synthetic']);
     return {
         nodeId: makeDefId(filePath, anchor.range, type, nameCap.text),
         filePath,
@@ -412,9 +501,11 @@ function buildDefFromDeclarationMatch(match, anchor, filePath) {
         ...(declaredType !== undefined ? { declaredType } : {}),
         ...(returnType !== undefined ? { returnType } : {}),
         ...(templateArguments !== undefined ? { templateArguments } : {}),
+        ...(typeParameters !== undefined ? { typeParameters } : {}),
         ...(templateConstraints !== undefined ? { templateConstraints } : {}),
         ...(isExplicit === true ? { isExplicit: true } : {}),
         ...(isDeleted === true ? { isDeleted: true } : {}),
+        ...(isSynthetic === true ? { isSynthetic: true } : {}),
     };
 }
 /** Parse an opaque JSON payload synthesized by per-language captures
@@ -511,7 +602,8 @@ function parseJsonStringArrayCapture(cap) {
     }
 }
 function deriveDeclarationName(match, def) {
-    const nameCap = match['@declaration.name'] ??
+    const nameCap = match['@declaration.binding-name'] ??
+        match['@declaration.name'] ??
         match[Object.keys(match).find((k) => k.startsWith('@declaration.') && k.endsWith('.name')) ?? ''];
     if (nameCap !== undefined)
         return nameCap.text;
@@ -574,6 +666,8 @@ function normalizeNodeLabel(kindStr) {
             return 'Annotation';
         case 'namespace':
             return 'Namespace';
+        case 'program':
+            return 'Module';
         case 'macro':
             return 'Macro';
         default:
@@ -637,9 +731,74 @@ function makeDefId(filePath, range, type, name) {
     return `def:${filePath}#${range.startLine}:${range.startCol}:${type}:${name}`;
 }
 // ─── Pass 3: collect raw imports ───────────────────────────────────────────
-function pass3CollectImports(matches, parsedImports, provider) {
+/**
+ * Does this import run only when something calls the function it sits in?
+ *
+ * Walks the scope chain to the file root rather than reading the immediate
+ * kind, because the immediate kind is not enough in either direction. A `Block`
+ * at the top of a module (`if (FLAG) { require('./x'); }`) runs during
+ * initialization; the same `Block` inside a function does not. `Class`,
+ * `Namespace`, `Expression` and `Object` bodies execute where they are defined,
+ * so they are initialization-time too. Only an enclosing `Function` — anywhere
+ * up the chain — defers execution.
+ *
+ * Language-agnostic on purpose: it is what catches Python's
+ * `def f(): from x import Y`, Ruby's `def f; require 'x'; end` and a CommonJS
+ * `require()` in a function body, none of which any `kind` marks as deferred —
+ * only their position says it.
+ *
+ * The rule is about EXECUTION, so it does not hold for a language whose
+ * imports are not executed statements at all — a C/C++ `#include` (spliced by
+ * the preprocessor before the program runs) or a Rust `use` (a compile-time
+ * path alias). Both are legal inside a function body and neither is deferred
+ * by sitting there, so a cycle they form is REAL. Marking one deferred would
+ * make `check --cycles` drop that cycle, and suppressing a true cycle is the
+ * failure direction that matters. Such a language opts out by declaring
+ * `LanguageProvider.importsExecuteWhereWritten: false`, checked by the caller
+ * — the capability is named on the provider rather than the language being
+ * named here, because shared ingestion code must not branch on language
+ * (AGENTS.md).
+ *
+ * Decided HERE and nowhere later because this is the last stage that knows the
+ * answer — see `ParsedImport.runsOnlyWhenCalled` for why finalize and the graph
+ * bridge cannot recover it.
+ */
+function runsOnlyWhenCalled(scopeTree, scopeId) {
+    // Inline rather than `utils/scope-tree-walk.ts`'s `walkToScope`, which is the
+    // shared primitive for exactly this climb and IS the right call everywhere it
+    // is used today — five `bindingScopeFor` hooks, all per-BINDING. This runs per
+    // IMPORT on every file of every analyze, and `walkToScope` takes `...kinds`
+    // and builds `new Set(kinds)` per call: measured on this host, 1.0 ns inline
+    // against 32.3 ns through the helper for the module-level case that is ~99% of
+    // imports, plus ~232 B of allocation each. Rewriting the helper's membership
+    // test as `kinds.includes` takes it to 8.8 ns — still 8x, because the rest
+    // array allocates regardless. Reuse loses to a two-field loop here; it would
+    // not on a colder path.
+    //
+    // No depth cap: the chain is acyclic by construction, since `buildScopeTree`
+    // only parents a scope to one that STRICTLY contains it.
+    let current = scopeId;
+    while (current !== null) {
+        const scope = scopeTree.getScope(current);
+        if (scope === undefined)
+            return false;
+        if (scope.kind === 'Function')
+            return true;
+        current = scope.parent;
+    }
+    return false;
+}
+function pass3CollectImports(matches, positionIndex, filePath, parsedImports, provider, scopeTree) {
     if (provider.interpretImport === undefined)
         return;
+    // Hoisted: the capability is a property of the language, identical for every
+    // match in the file. A provider that declares its imports do not execute
+    // where they are written (C/C++ `#include`, Rust `use`, COBOL `COPY`) skips
+    // the position walk entirely — position cannot defer something that never
+    // runs, and marking one deferred would hide a real cycle. Absent reads as
+    // `true`, so an undeclared provider is unchanged. See
+    // `LanguageProvider.importsExecuteWhereWritten`.
+    const positionCanDefer = provider.importsExecuteWhereWritten !== false;
     for (const match of matches) {
         const anchor = anchorCaptureFor(match, '@import.');
         if (anchor === undefined)
@@ -647,10 +806,24 @@ function pass3CollectImports(matches, parsedImports, provider) {
         const parsed = provider.interpretImport(match);
         if (parsed === null)
             continue;
-        parsedImports.push(parsed);
+        // The statement's own position, resolved to the innermost scope holding
+        // it. An unlocatable anchor leaves the import unmarked, which reads as
+        // "runs at initialization" — the fail-safe direction, since it can only
+        // make `check --cycles` over-report.
+        const inScopeId = positionCanDefer
+            ? positionIndex.atPosition(filePath, anchor.range.startLine, anchor.range.startCol)
+            : undefined;
+        const deferred = inScopeId !== undefined && runsOnlyWhenCalled(scopeTree, inScopeId);
+        parsedImports.push(deferred ? { ...parsed, runsOnlyWhenCalled: true } : parsed);
     }
 }
 // ─── Pass 4: collect type bindings ─────────────────────────────────────────
+/** Cap on the retained as-written annotation. Real container spellings are a
+ *  handful of characters; a multi-line mapped/conditional type is neither a
+ *  container any `elementTypeOf` parses nor worth keeping one copy of per
+ *  binding on a kernel-scale repo. Over the cap the spelling is dropped, which
+ *  makes an index step decline — the safe direction. */
+const MAX_DECLARED_SPELLING_LENGTH = 256;
 function pass4CollectTypeBindings(matches, drafts, positionIndex, filePath, provider, scopeTree) {
     const draftById = new Map();
     for (const d of drafts)
@@ -680,11 +853,39 @@ function pass4CollectTypeBindings(matches, drafts, positionIndex, filePath, prov
         // `bindingScopeFor` may hoist the type binding to an outer scope.
         const hostId = provider.bindingScopeFor?.(match, draftToScope(innermost), scopeTree) ?? autoHostedId;
         const host = draftById.get(hostId) ?? innermost;
-        const typeRef = {
-            rawName: parsed.rawTypeName,
-            declaredAtScope: host.id,
-            source: parsed.source,
-        };
+        // The annotation as the source wrote it, kept only when the provider's
+        // interpretation is not already it. `interpretTypeBinding` normalizes
+        // container spellings away (`User[]` → `User`, `List[User]` → `User`,
+        // `[]*User` → `User`), which makes a reduced container indistinguishable
+        // from a class of the same name — and an index step folding on that
+        // ambiguity typed `grid[0]` as `Grid`. Read at the one place the
+        // distinction matters; see `TypeRef.declaredSpelling`.
+        //
+        // Read from the capture rather than from `ParsedTypeBinding` deliberately:
+        // `@type-binding.type` is the shared anchor EVERY provider already reads to
+        // build `rawTypeName`, so nothing has to be threaded through fourteen
+        // interpreters (and none can forget to).
+        // A provider may override when its grammar keeps part of the written type
+        // outside `@type-binding.type` (C++ hangs `*` on the declarator).
+        const writtenType = (parsed.declaredSpelling ?? match['@type-binding.type']?.text)?.trim();
+        const declaredSpelling = writtenType !== undefined &&
+            writtenType.length > 0 &&
+            writtenType.length <= MAX_DECLARED_SPELLING_LENGTH &&
+            writtenType !== parsed.rawTypeName
+            ? writtenType
+            : undefined;
+        const typeRef = declaredSpelling === undefined
+            ? {
+                rawName: parsed.rawTypeName,
+                declaredAtScope: host.id,
+                source: parsed.source,
+            }
+            : {
+                rawName: parsed.rawTypeName,
+                declaredSpelling,
+                declaredAtScope: host.id,
+                source: parsed.source,
+            };
         // Prefer stronger sources when multiple matches fire for the same
         // bound name in the same scope. Example: `u: User = find()` matches
         // both the annotation and constructor-inferred patterns; the explicit
@@ -757,13 +958,15 @@ function followChainedRef(start, draftById) {
  * name in the same scope. Higher number wins; ties keep the later match
  * (last-write-wins preserves historical order within a tier).
  *
- * Rationale: explicit annotations always beat inferred ones because they
- * reflect user intent. `self`/`cls` are treated as strongly as annotations
- * because they are language-required receiver types.
+ * Rationale: explicit variable and field annotations always beat bindings
+ * derived from parameter annotations or inference because they reflect the
+ * most specific user intent. `self`/`cls` are treated as strongly as other
+ * declared types because they are language-required receiver types.
  */
 function typeBindingStrength(source) {
     switch (source) {
         case 'annotation':
+            return 3;
         case 'parameter-annotation':
         case 'return-annotation':
         case 'self':
@@ -791,6 +994,11 @@ function pass5CollectReferences(matches, positionIndex, filePath, referenceSites
         // sibling via the full-path QualifiedNameIndex before the simple-tail walk
         // (#1982). Absent for unqualified references — resolution stays unchanged.
         const qualifiedCap = match['@reference.qualified-name'];
+        // Generic ARGUMENTS written on a heritage reference (`: IValidator<string>`);
+        // `inherits` only, because a call/read/write anchor spans the whole call
+        // expression, whose `<…>` would be an argument list, a comparison, or
+        // nothing at all — widening the kind would mint confident nonsense (#2912).
+        const typeArguments = kind === 'inherits' ? heritageTypeArguments(match, anchor, nameCap) : undefined;
         const inScopeId = positionIndex.atPosition(filePath, anchor.range.startLine, anchor.range.startCol);
         if (inScopeId === undefined)
             continue;
@@ -801,6 +1009,28 @@ function pass5CollectReferences(matches, positionIndex, filePath, referenceSites
         const arity = extractArity(match);
         const argumentTypes = extractArgumentTypes(match);
         const argumentTypeClasses = parseJsonParameterTypeClassesCapture(match['@reference.parameter-type-classes']);
+        // Object-literal key for value-ref sites (`{ key: fn }` / shorthand);
+        // consumed by the property-dispatch pass (#2437).
+        const propertyKeyCap = match['@reference.property-key'];
+        // Compact receiver chain, when the emitter produced one. Validated HERE as
+        // well as at the store boundary: bounds applied only on load are a
+        // recurring defect in this codebase — the writer keeps minting payloads the
+        // reader keeps rejecting, which is a permanent warm-cache-miss reparse loop
+        // that logs nothing.
+        const receiverChain = extractReceiverChain(match);
+        // Callee-position marker: a member-read capture that is actually the callee
+        // of an enclosing call (`obj.f` in `obj.f()`). Recorded, not acted on —
+        // whether the read is a phantom or a genuine func-typed-field read depends
+        // on the resolved tail's kind, which only edge emission knows. Emitted by
+        // languages whose read pattern has no call-position exclusion; absent
+        // everywhere else, so the site stays byte-identical for them.
+        const inCalleePosition = match['@reference.callee-position'] !== undefined;
+        // Pointer-embedding marker: `struct S { *T }` rather than `struct S { T }`.
+        // Recorded, not acted on — Go's method-set rules make the two forms differ
+        // (see `ReferenceSite.embeddedAsPointer`), and only structural interface
+        // detection knows what to do with that. Absent for every language without
+        // pointer embedding, so their sites stay byte-identical.
+        const embeddedAsPointer = match['@reference.embedded-pointer'] !== undefined;
         const site = {
             name: nameCap.text,
             atRange: anchor.range,
@@ -809,15 +1039,68 @@ function pass5CollectReferences(matches, positionIndex, filePath, referenceSites
             ...(qualifiedCap?.text !== undefined && qualifiedCap.text.length > 0
                 ? { rawQualifiedName: qualifiedCap.text }
                 : {}),
+            ...(typeArguments !== undefined ? { typeArguments } : {}),
+            ...(propertyKeyCap?.text !== undefined && propertyKeyCap.text.length > 0
+                ? { propertyKey: propertyKeyCap.text }
+                : {}),
             ...(callForm !== undefined ? { callForm } : {}),
             ...(explicitReceiver !== undefined ? { explicitReceiver } : {}),
             ...(arity !== undefined ? { arity } : {}),
             ...(argumentTypes !== undefined ? { argumentTypes } : {}),
             ...(argumentTypeClasses !== undefined ? { argumentTypeClasses } : {}),
+            ...(receiverChain !== undefined ? { receiverChain } : {}),
+            ...(inCalleePosition ? { inCalleePosition: true } : {}),
+            ...(embeddedAsPointer ? { embeddedAsPointer: true } : {}),
         };
         referenceSites.push(site);
     }
 }
+/**
+ * The generic arguments a heritage reference was written with, by whichever of
+ * the two routes this emitter uses (#2912).
+ *
+ * `@reference.type-arguments` is the explicit route, for an emitter whose anchor
+ * is the bare NAME node (Rust's `impl Trait for S` anchors on the trait
+ * identifier inside a `generic_type`). It wins where present: moving such an
+ * anchor to cover the arguments would change the site's range, and that range is
+ * part of every inheritance EDGE ID — a spelling detail must not renumber the
+ * graph. Every other emitter already anchors on the whole base, so its spelling
+ * is read directly and no query changed.
+ */
+function heritageTypeArguments(match, anchor, nameCap) {
+    const explicit = match['@reference.type-arguments']?.text;
+    return explicit !== undefined
+        ? typeApplicationArguments(explicit)
+        : referenceTypeArguments(anchor.text, nameCap.text);
+}
+/**
+ * Type arguments written on a heritage reference, read from the anchor's own
+ * spelling — `IValidator<string>` → `['string']` (#2912).
+ *
+ * Two shapes are handled before the spelling is read as an application:
+ *
+ *   - A trailing CONSTRUCTOR INVOCATION is dropped. `record R : Base<int>(x)`
+ *     and Kotlin `class C : Bar<Int>()` write a call in the heritage position;
+ *     the call is not part of the type, and leaving it attached would make the
+ *     list fail to close at the end and lose the arguments entirely.
+ *   - The application's base must BE the referenced name (`Other::Inner<T>`
+ *     ends with `Inner`). An anchor that spans more than the base type is not
+ *     read at all rather than read wrongly.
+ *
+ * `undefined` for a non-generic base and for every spelling that is not exactly
+ * one balanced argument list — absence is the "unknown" value that consumers
+ * fail open on, so declining is always safe here.
+ */
+function referenceTypeArguments(anchorText, baseName) {
+    const text = stripTrailingCallSuffix(anchorText.trim());
+    const opener = text.search(OPENING_BRACKET);
+    if (opener === -1)
+        return undefined;
+    if (!text.slice(0, opener).trimEnd().endsWith(baseName))
+        return undefined;
+    return typeApplicationArguments(text);
+}
+const OPENING_BRACKET = /[<[]/;
 function referenceKindFromAnchor(name) {
     const suffix = name.slice('@reference.'.length);
     // Strip sub-tag after the kind (`@reference.call.member` → `call`).
@@ -840,6 +1123,8 @@ function referenceKindFromAnchor(name) {
             return 'import-use';
         case 'macro':
             return 'macro';
+        case 'value-ref':
+            return 'value-ref';
         default:
             return undefined;
     }
@@ -872,6 +1157,19 @@ function extractExplicitReceiver(match) {
         return undefined;
     return { name: cap.text };
 }
+/**
+ * The compact receiver chain, when the language emitter synthesized one.
+ *
+ * Returns `undefined` for anything that does not decode, so a malformed or
+ * over-bound payload degrades to the existing text cascade rather than
+ * poisoning the durable store. Never throws — this runs per reference site.
+ */
+function extractReceiverChain(match) {
+    const cap = match['@reference.receiver-chain'];
+    if (cap === undefined)
+        return undefined;
+    return isValidReceiverChain(cap.text) ? cap.text : undefined;
+}
 function extractArity(match) {
     const cap = match['@reference.arity'];
     if (cap === undefined)
@@ -893,6 +1191,245 @@ function extractArgumentTypes(match) {
     }
     return undefined;
 }
+// ─── Pass 6: collect callable-value-flow facts ─────────────────────────────
+const CALLABLE_FLOW_KINDS = [
+    'seed',
+    'copy',
+    'alias',
+    'address',
+    'store',
+    'load',
+    'formal',
+    'argument',
+    'invoke',
+];
+function pass6CollectCallableFlows(matches, positionIndex, filePath, out) {
+    for (const match of matches) {
+        const kind = callableFlowKind(match);
+        if (kind === undefined)
+            continue;
+        const anchor = match[`@callable-flow.${kind}`];
+        if (anchor === undefined)
+            continue;
+        switch (kind) {
+            case 'seed': {
+                const destination = callableFlowOperand(match, 'destination', positionIndex, filePath);
+                const target = match['@callable-flow.target'];
+                const targetName = match['@callable-flow.target-name']?.text ?? target?.text;
+                if (destination === undefined || target === undefined || !nonEmpty(targetName))
+                    continue;
+                const expectedSignature = callableFlowExpectedSignature(match);
+                out.push({
+                    kind,
+                    destination,
+                    targetName,
+                    targetRange: target.range,
+                    ...(nonEmpty(match['@callable-flow.target-qualified-name']?.text)
+                        ? { targetQualifiedName: match['@callable-flow.target-qualified-name'].text }
+                        : {}),
+                    ...(expectedSignature !== undefined ? { expectedSignature } : {}),
+                });
+                break;
+            }
+            case 'copy':
+            case 'alias': {
+                const source = callableFlowOperand(match, 'source', positionIndex, filePath);
+                const destination = callableFlowOperand(match, 'destination', positionIndex, filePath);
+                if (source === undefined || destination === undefined)
+                    continue;
+                out.push({ kind, source, destination });
+                break;
+            }
+            case 'address': {
+                const source = callableFlowOperand(match, 'source', positionIndex, filePath);
+                const destination = callableFlowOperand(match, 'destination', positionIndex, filePath);
+                if (source === undefined || destination === undefined)
+                    continue;
+                out.push({ kind, source, destination });
+                break;
+            }
+            case 'store': {
+                const source = callableFlowOperand(match, 'source', positionIndex, filePath);
+                const pointer = callableFlowOperand(match, 'pointer', positionIndex, filePath);
+                if (source === undefined || pointer === undefined)
+                    continue;
+                out.push({ kind, source, pointer });
+                break;
+            }
+            case 'load': {
+                const pointer = callableFlowOperand(match, 'pointer', positionIndex, filePath);
+                const destination = callableFlowOperand(match, 'destination', positionIndex, filePath);
+                if (pointer === undefined || destination === undefined)
+                    continue;
+                out.push({ kind, pointer, destination });
+                break;
+            }
+            case 'formal': {
+                const owner = match['@callable-flow.owner'];
+                const binding = callableFlowOperand(match, 'binding', positionIndex, filePath);
+                const parameterIndex = parseNonNegativeInt(match['@callable-flow.parameter-index']?.text);
+                const passingMode = parseCallablePassingMode(match['@callable-flow.passing-mode']?.text);
+                if (owner === undefined ||
+                    !nonEmpty(owner.text) ||
+                    binding === undefined ||
+                    parameterIndex === undefined ||
+                    passingMode === undefined) {
+                    continue;
+                }
+                const expectedSignature = callableFlowExpectedSignature(match);
+                out.push({
+                    kind,
+                    ownerName: owner.text,
+                    ownerRange: owner.range,
+                    parameterIndex,
+                    binding,
+                    passingMode,
+                    ...(expectedSignature !== undefined ? { expectedSignature } : {}),
+                });
+                break;
+            }
+            case 'argument': {
+                const source = callableFlowOperand(match, 'source', positionIndex, filePath);
+                const parameterIndex = parseNonNegativeInt(match['@callable-flow.parameter-index']?.text);
+                if (source === undefined || parameterIndex === undefined)
+                    continue;
+                out.push({
+                    kind,
+                    callSite: anchor.range,
+                    parameterIndex,
+                    source,
+                    ...(nonEmpty(match['@callable-flow.direct-callee-name']?.text)
+                        ? { directCalleeName: match['@callable-flow.direct-callee-name'].text }
+                        : {}),
+                });
+                break;
+            }
+            case 'invoke': {
+                const callee = callableFlowOperand(match, 'callee', positionIndex, filePath);
+                const inScope = positionIndex.atPosition(filePath, anchor.range.startLine, anchor.range.startCol);
+                const invocationKind = parseCallableInvocationKind(match['@callable-flow.invocation-kind']?.text);
+                if (callee === undefined || inScope === undefined || invocationKind === undefined)
+                    continue;
+                const receiver = callableFlowOperand(match, 'receiver', positionIndex, filePath);
+                const arity = parseNonNegativeInt(match['@callable-flow.arity']?.text);
+                out.push({
+                    kind,
+                    callSite: anchor.range,
+                    inScope,
+                    callee,
+                    invocationKind,
+                    ...(receiver !== undefined ? { receiver } : {}),
+                    ...(arity !== undefined ? { arity } : {}),
+                });
+                break;
+            }
+        }
+    }
+}
+function callableFlowKind(match) {
+    return CALLABLE_FLOW_KINDS.find((kind) => match[`@callable-flow.${kind}`] !== undefined);
+}
+function callableFlowOperand(match, role, positionIndex, filePath) {
+    const cap = match[`@callable-flow.${role}`];
+    if (cap === undefined || !nonEmpty(cap.text))
+        return undefined;
+    const inScope = positionIndex.atPosition(filePath, cap.range.startLine, cap.range.startCol);
+    if (inScope === undefined)
+        return undefined;
+    const expressionKind = parseCallableOperandKind(match[`@callable-flow.${role}-kind`]?.text);
+    const indirection = parseNonNegativeInt(match[`@callable-flow.${role}-indirection`]?.text);
+    if (indirection !== undefined && indirection > 16)
+        return undefined;
+    return {
+        name: cap.text,
+        inScope,
+        atRange: cap.range,
+        indirection: indirection ?? 0,
+        addressOf: match[`@callable-flow.${role}-address`]?.text === 'true',
+        ...(expressionKind !== undefined ? { expressionKind } : {}),
+        ...(nonEmpty(match[`@callable-flow.${role}-qualified-name`]?.text)
+            ? { qualifiedName: match[`@callable-flow.${role}-qualified-name`].text }
+            : {}),
+    };
+}
+function callableFlowExpectedSignature(match) {
+    const parameterCount = parseNonNegativeInt(match['@callable-flow.expected-arity']?.text);
+    const parameterTypes = parseJsonStringArray(match['@callable-flow.expected-types']?.text);
+    const parameterTypeClasses = parseJsonParameterTypeClassesCapture(match['@callable-flow.expected-type-classes']);
+    const isConst = parseBooleanText(match['@callable-flow.expected-const']?.text);
+    if (parameterCount === undefined &&
+        parameterTypes === undefined &&
+        parameterTypeClasses === undefined &&
+        isConst === undefined) {
+        return undefined;
+    }
+    return {
+        ...(parameterCount !== undefined ? { parameterCount } : {}),
+        ...(parameterTypes !== undefined ? { parameterTypes } : {}),
+        ...(parameterTypeClasses !== undefined ? { parameterTypeClasses } : {}),
+        ...(isConst !== undefined ? { isConst } : {}),
+    };
+}
+function parseCallableOperandKind(text) {
+    switch (text) {
+        case 'binding':
+        case 'callable-designator':
+        case 'bound-member':
+        case 'anonymous-callable':
+            return text;
+        default:
+            return undefined;
+    }
+}
+function parseBooleanText(text) {
+    if (text === 'true')
+        return true;
+    if (text === 'false')
+        return false;
+    return undefined;
+}
+function parseJsonStringArray(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return Array.isArray(parsed) && parsed.every((value) => typeof value === 'string')
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseNonNegativeInt(text) {
+    if (text === undefined || !/^\d+$/.test(text))
+        return undefined;
+    const value = Number.parseInt(text, 10);
+    return Number.isSafeInteger(value) ? value : undefined;
+}
+function parseCallablePassingMode(text) {
+    switch (text) {
+        case 'value':
+        case 'reference':
+        case 'pointer':
+            return text;
+        default:
+            return undefined;
+    }
+}
+function parseCallableInvocationKind(text) {
+    switch (text) {
+        case 'indirect':
+        case 'member-pointer':
+        case 'callable-object':
+            return text;
+        default:
+            return undefined;
+    }
+}
+function nonEmpty(value) {
+    return value !== undefined && value.length > 0;
+}
 // ─── Internal: range + capture utilities ───────────────────────────────────
 function rangesEqual(a, b) {
     return (a.startLine === b.startLine &&
@@ -910,15 +1447,27 @@ function rangesEqual(a, b) {
  * change.
  */
 const KNOWN_SUB_TAGS = new Set([
+    '@scope.lexical-names',
     '@declaration.name',
     '@declaration.qualified_name',
     '@import.name',
     '@import.source',
     '@import.alias',
+    // Provider-set marker, not a statement anchor. Listed for the same reason as
+    // its siblings: it is emitted on a sub-node of the import statement, and the
+    // anchor must stay `@import.statement` regardless of relative span.
+    '@import.publishes',
     '@type-binding.name',
     '@type-binding.type',
     '@reference.name',
     '@reference.qualified-name',
+    // The generic arguments a heritage base was written with, when the emitter's
+    // anchor is the bare name and cannot carry them (#2912). A sub-tag for the
+    // usual reason: it spans a sibling node of the anchor, never the site itself.
+    '@reference.type-arguments',
+    '@reference.property-key',
+    '@reference.callee-position',
+    '@reference.embedded-pointer',
     '@reference.receiver',
     '@reference.operator',
     '@reference.arity',
@@ -930,6 +1479,15 @@ const KNOWN_SUB_TAGS = new Set([
     '@declaration.parameter-type-classes',
     '@declaration.return-type',
     '@declaration.template-constraints',
+    // MUST be listed, and the failure it prevents is silent def LOSS rather than
+    // a missing field. `anchorCaptureFor` picks the broadest-span `@declaration.*`
+    // capture that is not a known sub-tag; a type-parameter list is normally
+    // narrower than the declaration that owns it, but a C++ `template <class A,
+    // class B, …>` or a multi-line Java `<T extends A & B>` written above a short
+    // declaration can out-span it. The anchor would then be `type-parameters`,
+    // `normalizeNodeLabel` would return undefined for it, and the whole class def
+    // would be dropped rather than merely losing its parameters.
+    '@declaration.type-parameters',
     '@declaration.is-explicit',
     '@declaration.is-deleted',
 ]);