gitnexus 1.6.10-rc.99 → 1.6.10

package/dist/core/ingestion/utils/line-base.js

@@ -18,3 +18,17 @@
  * must not shift. The clamp guards degenerate inputs (line 0 / empty files).
  */
 export const toZeroBasedLine = (oneBasedLine) => Math.max(0, oneBasedLine - 1);
+/**
+ * Convert a 0-based GraphNode `startLine`/`endLine` into the 1-based line space
+ * the CFG/PDG layer uses (`BasicBlock` ids and `functionStartLine` are built
+ * from `startPosition.row + 1`).
+ *
+ * This is the INTERNAL inverse of {@link toZeroBasedLine}, for joining graph
+ * rows against that layer. It is NOT the display converter: line numbers on
+ * their way out to a human or an LLM go through `mcp/local/line-display.ts`,
+ * which is documented as a response-boundary concern and passes `undefined`
+ * through. Here the arithmetic is the point, so the input must already be a
+ * number — a caller holding a possibly-absent value checks it first, exactly as
+ * the `typeof sym.startLine === 'number'` guards in `pdg-impact.ts` do.
+ */
+export const toOneBasedLine = (zeroBasedLine) => zeroBasedLine + 1;

package/dist/core/ingestion/utils/method-props.d.ts

@@ -6,16 +6,39 @@ import { SupportedLanguages, type ParameterTypeClass } from '../../../_shared/in
  */
 export declare function arityForIdFromInfo(info: MethodInfo): number | undefined;
 /**
- * Compute a type-based discriminator suffix for same-arity overloads.
- * Returns `~type1,type2` when the current method collides with another method
- * in the same class that has the same name and arity but different parameter types.
- * Returns `''` when there is no collision or types are unavailable.
+ * Key for the per-class method map built by `getMethodInfo` (parse-worker).
+ *
+ * `name:line` is NOT unique. Two callables can start on the same line with the
+ * same name whenever one of them is SYNTHESIZED at a position that is not its
+ * own declaration: a Java record's implicit component accessor is minted at the
+ * component (`record P(int x, int y) { int x(int s) {…} }`), and a C# 12 primary
+ * constructor at the owner's `parameter_list`
+ * (`class Point(int x, int y) { public Point(int x) : this(x, 0) {} }`). Both are
+ * appended LAST by their extractor, so under a `name:line` key the synthesized
+ * entry silently destroyed the source-written method's MethodInfo and the two
+ * ids collapsed onto one node (#2936).
+ *
+ * `line` is 1-based and `column` is 0-based — deliberately, because this is a
+ * join key rather than a displayed location and both sides derive it from the
+ * same node. Do not "normalize" one half; the join is the only contract.
+ *
+ * The KEY is never parsed by any consumer — `buildCollisionGroups`,
+ * `typeTagForId` and `constTagForId` all iterate `.values()`. Keep it that way,
+ * and never insert one MethodInfo under two keys: those consumers would then
+ * count it twice and turn every singleton into a false collision group.
  */
+export declare function methodInfoKey(name: string, line: number, column: number): string;
 /**
  * Build collision groups from a method map — groups methods by `name#arity`.
  * Call once per class, then pass to typeTagForId/constTagForId to avoid O(N²) scans.
  */
 export declare function buildCollisionGroups(methodMap: Map<string, MethodInfo>): Map<string, MethodInfo[]>;
+/**
+ * Compute a type-based discriminator suffix for same-arity overloads.
+ * Returns `~type1,type2` when the current method collides with another method
+ * in the same class that has the same name and arity but different parameter types.
+ * Returns `''` when there is no collision or types are unavailable.
+ */
 export declare function typeTagForId(methodMap: Map<string, MethodInfo>, methodName: string, arity: number | undefined, currentInfo: MethodInfo, language?: SupportedLanguages, 
 /** Pre-built collision groups from buildCollisionGroups(). Avoids O(N) scan per call. */
 collisionGroups?: Map<string, MethodInfo[]>): string;

package/dist/core/ingestion/utils/method-props.js

@@ -13,11 +13,30 @@ export function arityForIdFromInfo(info) {
     return info.parameters.some((p) => p.isVariadic) ? undefined : info.parameters.length;
 }
 /**
- * Compute a type-based discriminator suffix for same-arity overloads.
- * Returns `~type1,type2` when the current method collides with another method
- * in the same class that has the same name and arity but different parameter types.
- * Returns `''` when there is no collision or types are unavailable.
+ * Key for the per-class method map built by `getMethodInfo` (parse-worker).
+ *
+ * `name:line` is NOT unique. Two callables can start on the same line with the
+ * same name whenever one of them is SYNTHESIZED at a position that is not its
+ * own declaration: a Java record's implicit component accessor is minted at the
+ * component (`record P(int x, int y) { int x(int s) {…} }`), and a C# 12 primary
+ * constructor at the owner's `parameter_list`
+ * (`class Point(int x, int y) { public Point(int x) : this(x, 0) {} }`). Both are
+ * appended LAST by their extractor, so under a `name:line` key the synthesized
+ * entry silently destroyed the source-written method's MethodInfo and the two
+ * ids collapsed onto one node (#2936).
+ *
+ * `line` is 1-based and `column` is 0-based — deliberately, because this is a
+ * join key rather than a displayed location and both sides derive it from the
+ * same node. Do not "normalize" one half; the join is the only contract.
+ *
+ * The KEY is never parsed by any consumer — `buildCollisionGroups`,
+ * `typeTagForId` and `constTagForId` all iterate `.values()`. Keep it that way,
+ * and never insert one MethodInfo under two keys: those consumers would then
+ * count it twice and turn every singleton into a false collision group.
  */
+export function methodInfoKey(name, line, column) {
+    return `${name}:${line}:${column}`;
+}
 /**
  * Build collision groups from a method map — groups methods by `name#arity`.
  * Call once per class, then pass to typeTagForId/constTagForId to avoid O(N²) scans.
@@ -37,6 +56,12 @@ export function buildCollisionGroups(methodMap) {
     }
     return groups;
 }
+/**
+ * Compute a type-based discriminator suffix for same-arity overloads.
+ * Returns `~type1,type2` when the current method collides with another method
+ * in the same class that has the same name and arity but different parameter types.
+ * Returns `''` when there is no collision or types are unavailable.
+ */
 export function typeTagForId(methodMap, methodName, arity, currentInfo, language, 
 /** Pre-built collision groups from buildCollisionGroups(). Avoids O(N) scan per call. */
 collisionGroups) {

package/dist/core/ingestion/utils/receiver-chain-captures.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Synthesize `@reference.receiver-chain` for a call match whose receiver is
+ * itself an expression.
+ *
+ * Shared across every language emitter, and deliberately language-free (AGENTS.md
+ * R6): the call gate reads the `@reference.call.*` tag vocabulary, which is
+ * shared by every language's `.scm` query, rather than a per-language tag list.
+ *
+ * Lives in the emitter layer rather than the query because a `.scm` pattern
+ * cannot call `extractMixedChain`, and the receiver capture originates in
+ * several patterns per language.
+ */
+import type { Capture } from '../../../_shared/index.js';
+import type { SyntaxNode } from './ast-helpers.js';
+/**
+ * Add `@reference.receiver-chain` to `grouped` when the match is a call whose
+ * receiver decodes to a chain over a nameable base. Mutates `grouped` in place
+ * and returns nothing — mirroring how the other synthesized captures are added.
+ *
+ * Gated on the call tags: without that gate this fires on read, write and JSX
+ * receivers too, which pay the AST walk and the persisted bytes for a field no
+ * call-site resolver reads.
+ *
+ * A chain is minted ONLY when the walk reached a nameable base.
+ * `extractMixedChain` reports `baseReceiverName: undefined` whenever it stopped
+ * early — at `MAX_CHAIN_DEPTH`, or because a step could not be read — and what it
+ * collected then is a partial chain missing exactly the head that decides the
+ * final type. Encoding that would turn a receiver we cannot type into one we type
+ * WRONGLY, so those fall through to the resolver's existing text cascade.
+ */
+export declare function synthesizeReceiverChainCapture(grouped: Record<string, Capture>, receiverNode: SyntaxNode | undefined | null): void;

package/dist/core/ingestion/utils/receiver-chain-captures.js

@@ -0,0 +1,57 @@
+/**
+ * Synthesize `@reference.receiver-chain` for a call match whose receiver is
+ * itself an expression.
+ *
+ * Shared across every language emitter, and deliberately language-free (AGENTS.md
+ * R6): the call gate reads the `@reference.call.*` tag vocabulary, which is
+ * shared by every language's `.scm` query, rather than a per-language tag list.
+ *
+ * Lives in the emitter layer rather than the query because a `.scm` pattern
+ * cannot call `extractMixedChain`, and the receiver capture originates in
+ * several patterns per language.
+ */
+import { syntheticCapture } from './ast-helpers.js';
+import { extractMixedChain } from './call-analysis.js';
+import { encodeReceiverChain } from './receiver-chain-codec.js';
+/** Tag prefix marking a match as a CALL. `@reference.callable` is deliberately
+ *  excluded by the trailing dot — it marks a callable VALUE, not a call site. */
+const CALL_TAG_PREFIX = '@reference.call.';
+/** Does this match represent a call? */
+function isCallMatch(grouped) {
+    for (const tag of Object.keys(grouped)) {
+        if (tag.startsWith(CALL_TAG_PREFIX))
+            return true;
+    }
+    return false;
+}
+/**
+ * Add `@reference.receiver-chain` to `grouped` when the match is a call whose
+ * receiver decodes to a chain over a nameable base. Mutates `grouped` in place
+ * and returns nothing — mirroring how the other synthesized captures are added.
+ *
+ * Gated on the call tags: without that gate this fires on read, write and JSX
+ * receivers too, which pay the AST walk and the persisted bytes for a field no
+ * call-site resolver reads.
+ *
+ * A chain is minted ONLY when the walk reached a nameable base.
+ * `extractMixedChain` reports `baseReceiverName: undefined` whenever it stopped
+ * early — at `MAX_CHAIN_DEPTH`, or because a step could not be read — and what it
+ * collected then is a partial chain missing exactly the head that decides the
+ * final type. Encoding that would turn a receiver we cannot type into one we type
+ * WRONGLY, so those fall through to the resolver's existing text cascade.
+ */
+export function synthesizeReceiverChainCapture(grouped, receiverNode) {
+    if (receiverNode === undefined || receiverNode === null)
+        return;
+    if (grouped['@reference.receiver-chain'] !== undefined)
+        return;
+    if (!isCallMatch(grouped))
+        return;
+    const extracted = extractMixedChain(receiverNode);
+    if (extracted === undefined || extracted.baseReceiverName === undefined)
+        return;
+    const encoded = encodeReceiverChain(extracted.baseReceiverName, extracted.chain);
+    if (encoded === undefined)
+        return;
+    grouped['@reference.receiver-chain'] = syntheticCapture('@reference.receiver-chain', receiverNode, encoded);
+}

package/dist/core/ingestion/utils/receiver-chain-codec.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Receiver-chain codec.
+ *
+ * THE one encoder/decoder for the compact receiver chain carried on
+ * `ReferenceSite.receiverChain`: the capture emitters write it, the
+ * scope-resolution fold reads it, and the durable ParsedFile store validates
+ * it. Two hand-rolled copies of a wire format drift — every side MUST import
+ * from here. (`taint/path-codec.ts` is the in-repo precedent for both the
+ * discipline and the shape.)
+ *
+ * ## Why a string rather than `MixedChainStep[]`
+ *
+ * `makeInterningReviver` (parsedfile-store.ts) interns strings, but it
+ * re-shares OBJECTS only when they carry `nodeId` + `filePath`. A
+ * `MixedChainStep` has neither, so an object encoding leaves every step object
+ * and every chain array as a distinct allocation on every warm load, while a
+ * string collapses to one interned instance per distinct chain.
+ *
+ * ## Wire format (version `2`)
+ *
+ * ```
+ * 2|<base>|<step>|<step>…[|~]
+ * ```
+ *
+ * - One-character version prefix, then the BASE receiver name, then ordered
+ *   base-first steps.
+ * - Each step is a one-character kind sigil followed by the member name:
+ *   `c` = call (`getUser()`), `f` = field (`address`). The sigil is the first
+ *   character of the segment and the name follows immediately, so a member
+ *   whose name begins with `c` or `f` needs no escaping (`ccount` decodes as a
+ *   call to `count`).
+ * - `a` = await and `i` = index are NAME-FREE and encode as a BARE sigil: an
+ *   awaited call's name already lives on its `c` step, and a subscript's key is
+ *   a value rather than an identifier the resolver could look up. The decoder
+ *   rejects any trailing characters after `a` or `i`, which is what keeps an
+ *   accidentally empty-name `c` or `f` segment refusing instead of decoding as
+ *   one of these.
+ * - A trailing `|~` segment is the TRUNCATION MARKER. NOTE: no current producer
+ *   mints one. `extractMixedChain` signals "stopped early" by returning
+ *   `baseReceiverName: undefined`, and the encoder requires a base, so a
+ *   truncated chain is unrepresentable rather than merely unused. The marker and
+ *   the decoder/fold guards are kept as a forward-compatible contract: a future
+ *   producer that CAN report a partial chain must set it, and the fold already
+ *   refuses such chains. Read the `truncated` field as "reserved", not "live". the chain hit
+ *   `MAX_CHAIN_DEPTH` and what is encoded is a base-side PREFIX of the real
+ *   chain. A consumer MUST treat a truncated chain as unusable for typing —
+ *   the missing tail is exactly what determines the final type — but never as
+ *   an error.
+ *
+ * `|` and `~` cannot appear in an identifier in any supported language, so the
+ * format needs no escaping and a malformed payload cannot silently decode as a
+ * different valid chain.
+ *
+ * For `svc.getUser().address.save()`, the receiver of `save` encodes as
+ * `2|svc|cgetUser|faddress` — 23 bytes. For `(await svc.getUserAsync()).save()`
+ * it is `2|svc|cgetUserAsync|a`.
+ */
+import type { MixedChainStep } from '../../../_shared/index.js';
+/** Hard cap on the encoded payload. `MAX_CHAIN_DEPTH` already bounds the step
+ *  COUNT; this bounds the total bytes so a pathological identifier cannot grow
+ *  a shard without limit. Generous against real identifiers — the encoding for
+ *  a full-depth chain of 30-character names is still under 130 bytes. */
+export declare const MAX_RECEIVER_CHAIN_BYTES = 512;
+export interface DecodedReceiverChain {
+    readonly baseReceiverName: string;
+    readonly steps: readonly MixedChainStep[];
+    /** The encoded chain is a base-side prefix — the real chain was longer.
+     *  Typing off a truncated chain would type off the wrong member. */
+    readonly truncated: boolean;
+}
+/**
+ * Encode a chain, or `undefined` when it cannot be represented — an empty
+ * chain (nothing to fold), an unencodable name, or a payload over the byte
+ * cap. Refusing to mint is deliberate: a half-encoded chain would be decoded
+ * as a complete-but-different one.
+ */
+export declare function encodeReceiverChain(baseReceiverName: string, steps: readonly MixedChainStep[], options?: {
+    readonly truncated?: boolean;
+}): string | undefined;
+/**
+ * Decode a payload, or `undefined` when it is not a well-formed chain. Total
+ * function: every malformed input returns `undefined` rather than throwing,
+ * because the two callers that matter — the extractor and the untrusted store
+ * boundary — are both on paths where a throw would cost the whole file.
+ */
+export declare function decodeReceiverChain(value: unknown): DecodedReceiverChain | undefined;
+/** Whether a persisted value is a chain this build can use. The store boundary
+ *  wants the predicate, not the decoded value. */
+export declare function isValidReceiverChain(value: unknown): value is string;

package/dist/core/ingestion/utils/receiver-chain-codec.js

@@ -0,0 +1,182 @@
+/**
+ * Receiver-chain codec.
+ *
+ * THE one encoder/decoder for the compact receiver chain carried on
+ * `ReferenceSite.receiverChain`: the capture emitters write it, the
+ * scope-resolution fold reads it, and the durable ParsedFile store validates
+ * it. Two hand-rolled copies of a wire format drift — every side MUST import
+ * from here. (`taint/path-codec.ts` is the in-repo precedent for both the
+ * discipline and the shape.)
+ *
+ * ## Why a string rather than `MixedChainStep[]`
+ *
+ * `makeInterningReviver` (parsedfile-store.ts) interns strings, but it
+ * re-shares OBJECTS only when they carry `nodeId` + `filePath`. A
+ * `MixedChainStep` has neither, so an object encoding leaves every step object
+ * and every chain array as a distinct allocation on every warm load, while a
+ * string collapses to one interned instance per distinct chain.
+ *
+ * ## Wire format (version `2`)
+ *
+ * ```
+ * 2|<base>|<step>|<step>…[|~]
+ * ```
+ *
+ * - One-character version prefix, then the BASE receiver name, then ordered
+ *   base-first steps.
+ * - Each step is a one-character kind sigil followed by the member name:
+ *   `c` = call (`getUser()`), `f` = field (`address`). The sigil is the first
+ *   character of the segment and the name follows immediately, so a member
+ *   whose name begins with `c` or `f` needs no escaping (`ccount` decodes as a
+ *   call to `count`).
+ * - `a` = await and `i` = index are NAME-FREE and encode as a BARE sigil: an
+ *   awaited call's name already lives on its `c` step, and a subscript's key is
+ *   a value rather than an identifier the resolver could look up. The decoder
+ *   rejects any trailing characters after `a` or `i`, which is what keeps an
+ *   accidentally empty-name `c` or `f` segment refusing instead of decoding as
+ *   one of these.
+ * - A trailing `|~` segment is the TRUNCATION MARKER. NOTE: no current producer
+ *   mints one. `extractMixedChain` signals "stopped early" by returning
+ *   `baseReceiverName: undefined`, and the encoder requires a base, so a
+ *   truncated chain is unrepresentable rather than merely unused. The marker and
+ *   the decoder/fold guards are kept as a forward-compatible contract: a future
+ *   producer that CAN report a partial chain must set it, and the fold already
+ *   refuses such chains. Read the `truncated` field as "reserved", not "live". the chain hit
+ *   `MAX_CHAIN_DEPTH` and what is encoded is a base-side PREFIX of the real
+ *   chain. A consumer MUST treat a truncated chain as unusable for typing —
+ *   the missing tail is exactly what determines the final type — but never as
+ *   an error.
+ *
+ * `|` and `~` cannot appear in an identifier in any supported language, so the
+ * format needs no escaping and a malformed payload cannot silently decode as a
+ * different valid chain.
+ *
+ * For `svc.getUser().address.save()`, the receiver of `save` encodes as
+ * `2|svc|cgetUser|faddress` — 23 bytes. For `(await svc.getUserAsync()).save()`
+ * it is `2|svc|cgetUserAsync|a`.
+ */
+import { MAX_CHAIN_DEPTH } from './call-analysis.js';
+/** Wire version. Bumped 1 → 2 when the name-free `await` and `index` step kinds
+ *  were added: a v1 decoder reading a v2 payload must REFUSE, not decode the
+ *  prefix it happens to understand, because a chain missing its await or index
+ *  hop decodes cleanly as a different, shorter chain and would type the receiver
+ *  against the wrong member. */
+const VERSION = '2';
+const SEPARATOR = '|';
+const TRUNCATED = '~';
+/** Sigil per step kind. ONE table, and both directions derive from it — the
+ *  decoder used to hand-write `sigil === 'c' ? 'call' : 'field'` and its own
+ *  await/index comparison, which meant the decoder was exactly the side that
+ *  could drift from the table claiming to prevent drift. */
+const SIGIL_BY_KIND = {
+    call: 'c',
+    field: 'f',
+    await: 'a',
+    index: 'i',
+};
+/** Kinds that encode as a BARE sigil, because they have no member name to
+ *  carry. Derived from the step union rather than listed twice. */
+const NAME_FREE_KINDS = new Set(['await', 'index']);
+const KIND_BY_SIGIL = new Map(Object.entries(SIGIL_BY_KIND).map(([kind, sigil]) => [sigil, kind]));
+/** Hard cap on the encoded payload. `MAX_CHAIN_DEPTH` already bounds the step
+ *  COUNT; this bounds the total bytes so a pathological identifier cannot grow
+ *  a shard without limit. Generous against real identifiers — the encoding for
+ *  a full-depth chain of 30-character names is still under 130 bytes. */
+export const MAX_RECEIVER_CHAIN_BYTES = 512;
+/** A segment is safe when it contains no structural character. Identifiers in
+ *  every supported language satisfy this; anything that does not is a payload
+ *  we refuse to mint rather than escape. */
+function isEncodableSegment(value) {
+    // `\s` does NOT match zero-width characters (U+200B ZWS, U+200C/D ZWNJ/ZWJ,
+    // U+200E/F LRM/RLM, U+FEFF BOM). An identifier carrying one is a trojan-source
+    // vector: it would encode and persist cleanly, then match no binding at
+    // resolution time — a silent, unexplained miss. Refuse to mint instead.
+    return (value.length > 0 &&
+        !value.includes(SEPARATOR) &&
+        !value.includes(TRUNCATED) &&
+        !/[\s\u200B-\u200F\u2028\u2029\uFEFF]/.test(value));
+}
+/**
+ * Encode a chain, or `undefined` when it cannot be represented — an empty
+ * chain (nothing to fold), an unencodable name, or a payload over the byte
+ * cap. Refusing to mint is deliberate: a half-encoded chain would be decoded
+ * as a complete-but-different one.
+ */
+export function encodeReceiverChain(baseReceiverName, steps, options) {
+    if (steps.length === 0 || steps.length > MAX_CHAIN_DEPTH)
+        return undefined;
+    if (!isEncodableSegment(baseReceiverName))
+        return undefined;
+    const parts = [VERSION, baseReceiverName];
+    for (const step of steps) {
+        // Name-free kinds encode as a bare sigil. They are exempt from the
+        // non-empty-name guard because they HAVE no name to check — not because the
+        // guard is relaxed: an empty-name `call` or `field` is still refused below.
+        if (NAME_FREE_KINDS.has(step.kind)) {
+            parts.push(SIGIL_BY_KIND[step.kind]);
+            continue;
+        }
+        if (!isEncodableSegment(step.name))
+            return undefined;
+        parts.push(`${SIGIL_BY_KIND[step.kind]}${step.name}`);
+    }
+    if (options?.truncated === true)
+        parts.push(TRUNCATED);
+    const encoded = parts.join(SEPARATOR);
+    return encoded.length > MAX_RECEIVER_CHAIN_BYTES ? undefined : encoded;
+}
+/**
+ * Decode a payload, or `undefined` when it is not a well-formed chain. Total
+ * function: every malformed input returns `undefined` rather than throwing,
+ * because the two callers that matter — the extractor and the untrusted store
+ * boundary — are both on paths where a throw would cost the whole file.
+ */
+export function decodeReceiverChain(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    if (value.length === 0 || value.length > MAX_RECEIVER_CHAIN_BYTES)
+        return undefined;
+    const parts = value.split(SEPARATOR);
+    if (parts.length < 3)
+        return undefined; // version + base + at least one step
+    if (parts[0] !== VERSION)
+        return undefined;
+    // `parts.length < 3` above already proves this element exists.
+    const baseReceiverName = parts[1];
+    if (!isEncodableSegment(baseReceiverName))
+        return undefined;
+    let stepParts = parts.slice(2);
+    const truncated = stepParts[stepParts.length - 1] === TRUNCATED;
+    if (truncated)
+        stepParts = stepParts.slice(0, -1);
+    if (stepParts.length === 0 || stepParts.length > MAX_CHAIN_DEPTH)
+        return undefined;
+    const steps = [];
+    for (const part of stepParts) {
+        const sigil = part[0];
+        const name = part.slice(1);
+        // Name-free kinds must be EXACTLY their sigil. Rejecting a trailing tail is
+        // what keeps an accidentally empty-name call or field from decoding as one
+        // of these: `c` alone stays malformed, it does not become an await.
+        const kind = sigil === undefined ? undefined : KIND_BY_SIGIL.get(sigil);
+        if (kind === undefined)
+            return undefined;
+        if (NAME_FREE_KINDS.has(kind)) {
+            // Must be EXACTLY the sigil. Rejecting a trailing tail is what keeps an
+            // accidentally empty-name call or field from decoding as one of these.
+            if (name.length > 0)
+                return undefined;
+            steps.push({ kind: kind });
+            continue;
+        }
+        if (!isEncodableSegment(name))
+            return undefined;
+        steps.push({ kind: kind, name });
+    }
+    return { baseReceiverName, steps, truncated };
+}
+/** Whether a persisted value is a chain this build can use. The store boundary
+ *  wants the predicate, not the decoded value. */
+export function isValidReceiverChain(value) {
+    return decodeReceiverChain(value) !== undefined;
+}

package/dist/core/ingestion/utils/scope-tree-walk.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Scope-tree walking primitives shared by the providers' `bindingScopeFor`
+ * hooks.
+ *
+ * Language-neutral: parameterised over `ScopeKind` — the shared scope
+ * vocabulary — and names no language, so it belongs in the core pipeline
+ * rather than in any one provider (AGENTS.md § shared pipeline code).
+ */
+import type { Scope, ScopeId, ScopeTree } from '../../../_shared/index.js';
+/**
+ * Walk up the scope chain to find the first scope whose `kind` matches
+ * any of `kinds`. Returns the matching scope's id or `null` when no
+ * ancestor matches (e.g., a return type binding emitted outside any
+ * Module scope — shouldn't happen in well-formed input).
+ *
+ * Every provider that hoists a binding out of the scope it was captured in
+ * needs exactly this walk: a field typed from a constructor call in a method
+ * body belongs on the enclosing Class, a `var` on the enclosing Function or
+ * Module, a method return type on the Module. Which `kind` to stop at is the
+ * only per-language part, and that is the parameter.
+ */
+export declare function walkToScope(from: Scope, tree: ScopeTree, ...kinds: readonly Scope['kind'][]): ScopeId | null;

package/dist/core/ingestion/utils/scope-tree-walk.js

@@ -0,0 +1,33 @@
+/**
+ * Scope-tree walking primitives shared by the providers' `bindingScopeFor`
+ * hooks.
+ *
+ * Language-neutral: parameterised over `ScopeKind` — the shared scope
+ * vocabulary — and names no language, so it belongs in the core pipeline
+ * rather than in any one provider (AGENTS.md § shared pipeline code).
+ */
+/**
+ * Walk up the scope chain to find the first scope whose `kind` matches
+ * any of `kinds`. Returns the matching scope's id or `null` when no
+ * ancestor matches (e.g., a return type binding emitted outside any
+ * Module scope — shouldn't happen in well-formed input).
+ *
+ * Every provider that hoists a binding out of the scope it was captured in
+ * needs exactly this walk: a field typed from a constructor call in a method
+ * body belongs on the enclosing Class, a `var` on the enclosing Function or
+ * Module, a method return type on the Module. Which `kind` to stop at is the
+ * only per-language part, and that is the parameter.
+ */
+export function walkToScope(from, tree, ...kinds) {
+    let cur = from;
+    const kindSet = new Set(kinds);
+    while (cur !== undefined) {
+        if (kindSet.has(cur.kind))
+            return cur.id;
+        const parentId = cur.parent ?? null;
+        if (parentId === null)
+            break;
+        cur = tree.getScope(parentId);
+    }
+    return null;
+}

package/dist/core/ingestion/utils/template-arguments.d.ts

@@ -1,3 +1,4 @@
+import type { TypeRef } from '../../../_shared/index.js';
 /**
  * Parse top-level generic/template arguments from a type-like string.
  *
@@ -7,6 +8,43 @@
  * - `List<T*>` -> ['T*']
  */
 export declare function extractTemplateArguments(text: string): string[] | undefined;
+/**
+ * The type ARGUMENTS a reference applies to its base, read from the reference's
+ * own source spelling: `IValidator<string>` → `['string']`, `Base[User]` →
+ * `['User']`, `Repository` → `undefined`.
+ *
+ * The inverse direction of {@link erasedTypeApplication}, which rebuilds the
+ * `Base<Args>` SPELLING so a lookup can stay grounded; this returns the
+ * ARGUMENTS so a consumer that has already resolved the base can ask which
+ * instantiation it was (#2912).
+ *
+ * Both bracket families count, because both spell type application in a
+ * heritage position — `class C : IValidator<string>` and Go's `struct { Base[int] }`
+ * / Python's `class C(Base[User])`. What is NOT accepted is anything that fails
+ * to be exactly one balanced, non-empty list closing at the very end:
+ *
+ *   - `Base(args)`      — a C# primary-constructor base, not an application.
+ *   - `Foo[]`           — an empty list is an array spelling, not arguments.
+ *   - `(Int) -> Unit`   — a Kotlin function type, whose `>` closes nothing.
+ *
+ * Declining is the safe outcome for all of them: absence reads as "unknown"
+ * and every consumer of this fails open on it.
+ */
+export declare function typeApplicationArguments(spelling: string): string[] | undefined;
+/**
+ * Index of the `(` that matches the trailing `)` of `text`, or -1 when the text
+ * does not end in a balanced call suffix.
+ *
+ * Shared for the same reason as {@link balancedTailList}: this scan is fiddly
+ * enough that two copies would be free to disagree, and it has two unrelated
+ * readers — splitting a receiver chain at its call, and stripping a base's
+ * constructor invocation off a heritage spelling.
+ */
+export declare function matchingOpenParen(text: string): number;
+/** Drop a balanced `(...)` that ENDS the text — the argument list of a base's
+ *  constructor invocation, as in `record R : Base<int>(x)` or Kotlin
+ *  `class C : Bar<Int>()`. Anything else is returned unchanged. */
+export declare function stripTrailingCallSuffix(text: string): string;
 export declare function stripTemplateArguments(text: string): string;
 export declare function templateArgumentsIdTag(templateArguments?: readonly string[]): string;
 /**
@@ -28,3 +66,61 @@ export declare function constraintsHash(jsonText: string): string;
  *  Returns empty string when the payload is absent so callers can
  *  string-concatenate unconditionally. */
 export declare function templateConstraintsIdTag(payload: unknown): string;
+/**
+ * The type APPLICATION a type reference was reduced from — `Mapped[User]`,
+ * `Repo<User>` — restored to the `Base<Args>` spelling, or `undefined` when
+ * this reference is not that shape.
+ *
+ * ── WHY A LOOKUP MUST NOT BE HANDED THE REDUCED NAME ─────────────────────────
+ *
+ * `rawName` is post-normalization (see its docstring on `TypeRef`), and several
+ * providers reduce a type application to its BASE NAME at capture time —
+ * `Mapped[User]` → `Mapped`, `Repo<User>` → `Repo`. That erasure is what lets
+ * one declaration answer for every instantiation of it, and it is also the
+ * widest step any lookup in this pipeline takes: reaching a declaration by NAME
+ * ALONE binds whatever the workspace happens to declare under that name. A
+ * third-party `Mapped[User]` beside an unrelated workspace `class Mapped` is
+ * then a confident WRONG edge, which is strictly worse than the missing one it
+ * replaced.
+ *
+ * `resolveClassBindingForName` already owns the rule for this — it admits an
+ * erased base name only on grounds that connect the site to the declaration
+ * (the scope chain binds the name; the declaration is in the same file; the
+ * index proves the name is a template family; the file has no cross-file class
+ * channel to be absent from). But that route is entered on the SPELLING: a name
+ * carrying its arguments takes it, a name already reduced to its base cannot,
+ * because nothing distinguishes it from an ordinary class name. So a provider
+ * that reduces at capture time sends its receivers down the ungrounded route by
+ * construction, whatever the shared lookup does.
+ *
+ * Restoring the application from `declaredSpelling` — which keeps the
+ * annotation exactly as written whenever normalization changed it — puts those
+ * receivers back on the grounded route. Restoring rather than reimplementing
+ * the grounding here is deliberate: the rule is one rule, and a second copy of
+ * it in this file would be free to drift from the one in `scope/walkers.ts`
+ * that every other caller uses. (Its predicate is not exported; the exported
+ * entry point is the spelling.)
+ *
+ * ── WHAT COUNTS AS AN APPLICATION ────────────────────────────────────────────
+ *
+ * `rawName` must be the base the spelling APPLIES arguments to, and the
+ * argument list must be the whole of the rest of the spelling — one list,
+ * balanced, non-empty. Everything else is left exactly as it resolves today,
+ * because a transform that is not certain is a worse failure than no transform:
+ *
+ *   - `User[]` — an array whose ELEMENT the capture layer already reduced to
+ *     `User`. The position is the element, not an application of `User`, and
+ *     the empty list is what says so.
+ *   - `User[][]` — likewise, and it closes its first list before the end.
+ *   - `std::vector<Item>` reduced to `vector<Item>` — the spelling does not
+ *     start with the reduced name, so nothing was erased that this can restore.
+ *   - `Repo<User>?`, `Map<String, (Int) -> Unit>` — trailing decoration and an
+ *     argument list that does not close where it must. Declining leaves the
+ *     pre-existing behaviour, which is what "no transform" has to mean.
+ *
+ * The rebuilt spelling uses ANGLE brackets because that is the spelling
+ * `resolveClassBindingForName`'s contract is written against; the punctuation a
+ * language spells type application with is not otherwise meaningful here, and
+ * nothing downstream reads this string except that lookup.
+ */
+export declare function erasedTypeApplication(typeRef: TypeRef): string | undefined;