gitnexus 1.6.10-rc.98 → 1.6.10

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,7 +126,7 @@ 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 ─────────────────────────────────
@@ -230,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 ──────────────────────────────────────────────
@@ -283,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;
@@ -314,7 +337,7 @@ function resolveKindForScopeMatch(match, anchor, provider) {
             return null;
     }
 }
-function makeDraft(id, parent, kind, range, filePath) {
+function makeDraft(id, parent, kind, range, filePath, ownsReceivers, lexicalNames) {
     return {
         id,
         parent,
@@ -325,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)
@@ -339,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)
@@ -409,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,
@@ -423,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
@@ -522,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;
@@ -650,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)
@@ -660,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)
@@ -693,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
@@ -806,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;
@@ -819,6 +1012,25 @@ function pass5CollectReferences(matches, positionIndex, filePath, referenceSites
         // 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,
@@ -827,6 +1039,7 @@ 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 }
                 : {}),
@@ -835,10 +1048,59 @@ function pass5CollectReferences(matches, positionIndex, filePath, referenceSites
             ...(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`).
@@ -895,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)
@@ -1172,16 +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',
@@ -1193,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',
 ]);