gitnexus 1.6.10-rc.99 → 1.6.10

package/dist/core/ingestion/utils/call-analysis.d.ts

@@ -1,9 +1,28 @@
+import type { MixedChainStep } from '../../../_shared/index.js';
 import type { SyntaxNode } from './ast-helpers.js';
 /** Node types representing call expressions across supported languages. */
 export declare const CALL_EXPRESSION_TYPES: Set<string>;
 /**
  * Hard limit on chain depth to prevent runaway recursion.
  * For `a.b().c().d()`, the chain has depth 2 (b and c before d).
+ *
+ * A chain deeper than this is DISCARDED WHOLE, not truncated:
+ * `extractMixedChain` returns an undefined base and the encoder refuses to mint
+ * a partial chain, because a base-side prefix decodes cleanly as a shorter,
+ * complete-looking chain and would type the receiver against the wrong member.
+ * Correct, but it means a builder chain one hop too long contributes nothing at
+ * all rather than degrading.
+ *
+ * DELIBERATELY NOT RAISED. Measured (see bench/receiver-resolution/BASELINE.md,
+ * `fourHopChain`): a 4-step chain mints NOTHING at this cap — confirmed by
+ * probing the emitter directly — and the site still RESOLVES, because the text
+ * cascade that owns the fallback path runs to `COMPOUND_RECEIVER_MAX_DEPTH` (8)
+ * and answers where the structural fold declined.
+ *
+ * So the cap bounds which chains are typed STRUCTURALLY, not which calls
+ * resolve. Raising it moves work from the cascade to the fold without changing
+ * any edge, and the fixture that proves it is committed so the next person to
+ * reach for this number has the measurement rather than the intuition.
  */
 export declare const MAX_CHAIN_DEPTH = 3;
 /**
@@ -31,11 +50,14 @@ export declare const extractReceiverName: (nameNode: SyntaxNode) => string | und
  * can be found (e.g. top-level free calls).
  */
 export declare const extractReceiverNode: (nameNode: SyntaxNode) => SyntaxNode | undefined;
-/** One step in a mixed receiver chain. */
-export type MixedChainStep = {
-    kind: 'field' | 'call';
-    name: string;
-};
+/**
+ * One step in a mixed receiver chain.
+ *
+ * Owned by `gitnexus-shared` — it is part of the ScopeExtractor output
+ * contract, and resolution consumes it. Re-exported here so the producer's
+ * existing importers keep a single import site.
+ */
+export type { MixedChainStep };
 /**
  * Walk a receiver AST node that is itself a call expression, accumulating the
  * chain of intermediate method names up to MAX_CHAIN_DEPTH.
@@ -50,26 +72,9 @@ export declare function extractCallChain(receiverCallNode: SyntaxNode): {
     chain: string[];
     baseReceiverName: string | undefined;
 } | undefined;
-/**
- * Walk a receiver AST node that may interleave field accesses and method calls,
- * building a unified chain of steps up to MAX_CHAIN_DEPTH.
- *
- * For `svc.getUser().address.save()`, called with the receiver of `save`
- * (`svc.getUser().address`, a field access node):
- *   returns { chain: [{ kind:'call', name:'getUser' }, { kind:'field', name:'address' }],
- *             baseReceiverName: 'svc' }
- *
- * For `user.getAddress().city.getName()`, called with receiver of `getName`
- * (`user.getAddress().city`):
- *   returns { chain: [{ kind:'call', name:'getAddress' }, { kind:'field', name:'city' }],
- *             baseReceiverName: 'user' }
- *
- * Pure field chains and pure call chains are special cases (all steps same kind).
- */
 export declare function extractMixedChain(receiverNode: SyntaxNode): {
     chain: MixedChainStep[];
     baseReceiverName: string | undefined;
 } | undefined;
 /** Arg types per call position (literals + optional TypeEnv for ids); undefined if unusable */
 export declare const extractCallArgTypes: (callNode: SyntaxNode, inferLiteralType: (node: SyntaxNode) => string | undefined, typeEnvLookup?: (varName: string, callNode: SyntaxNode) => string | undefined) => (string | undefined)[] | undefined;
-export {};

package/dist/core/ingestion/utils/call-analysis.js

@@ -1,4 +1,5 @@
 import { CALL_ARGUMENT_LIST_TYPES } from './ast-helpers.js';
+import { subscriptBase } from './callable-flow-captures.js';
 /** Node types representing call expressions across supported languages. */
 export const CALL_EXPRESSION_TYPES = new Set([
     'call_expression', // TS/JS/C/C++/Go/Rust
@@ -11,6 +12,24 @@ export const CALL_EXPRESSION_TYPES = new Set([
 /**
  * Hard limit on chain depth to prevent runaway recursion.
  * For `a.b().c().d()`, the chain has depth 2 (b and c before d).
+ *
+ * A chain deeper than this is DISCARDED WHOLE, not truncated:
+ * `extractMixedChain` returns an undefined base and the encoder refuses to mint
+ * a partial chain, because a base-side prefix decodes cleanly as a shorter,
+ * complete-looking chain and would type the receiver against the wrong member.
+ * Correct, but it means a builder chain one hop too long contributes nothing at
+ * all rather than degrading.
+ *
+ * DELIBERATELY NOT RAISED. Measured (see bench/receiver-resolution/BASELINE.md,
+ * `fourHopChain`): a 4-step chain mints NOTHING at this cap — confirmed by
+ * probing the emitter directly — and the site still RESOLVES, because the text
+ * cascade that owns the fallback path runs to `COMPOUND_RECEIVER_MAX_DEPTH` (8)
+ * and answers where the structural fold declined.
+ *
+ * So the cap bounds which chains are typed STRUCTURALLY, not which calls
+ * resolve. Raising it moves work from the cascade to the fold without changing
+ * any edge, and the fixture that proves it is committed so the next person to
+ * reach for this number has the measurement rather than the intuition.
  */
 export const MAX_CHAIN_DEPTH = 3;
 /**
@@ -296,6 +315,46 @@ export const extractReceiverNode = (nameNode) => {
 };
 // ── Chained-call extraction ───────────────────────────────────────────────
 /** Node types representing member/field access across languages. */
+/**
+ * Await expressions, per grammar. The walk previously stopped here — an await
+ * node is neither a call nor a field access — so `(await svc.getUserAsync()).save()`
+ * minted NO chain at all and the receiver fell to the text cascade.
+ */
+const AWAIT_EXPRESSION_NODE_TYPES = new Set([
+    'await_expression', // TS/JS/C#/Rust
+    'await', // Python
+]);
+/**
+ * Subscript / index expressions, per grammar. Same story as await: the walk
+ * stopped, so `repos[0].save()` minted no chain — which is why `indexElement`
+ * is an INVISIBLE-GAP (no edge AND no recorded drop) in all 14 languages, the
+ * most uniform cell in the matrix.
+ */
+const SUBSCRIPT_NODE_TYPES = new Set([
+    'subscript_expression', // TS/JS/PHP/C/C++
+    'subscript', // Python
+    'index_expression', // Go/Rust
+    'element_access_expression', // C#
+    'array_access', // Java
+    'indexing_expression', // Kotlin
+]);
+/**
+ * Can the chain walk descend into this node, or is it the base?
+ *
+ * ONE predicate for all four branches. The call and field branches previously
+ * tested only the call/field sets, so a receiver like `x[0].f().g()` stopped at
+ * the subscript and returned the literal text `x[0]` as the base — which
+ * `isEncodableSegment` accepts, minting a chain whose base binds to nothing. And
+ * `(await f()).g.h()` returned `await f()`, rejected on whitespace, minting no
+ * chain at all. Adding a fifth step kind must not require remembering four
+ * separate call sites.
+ */
+function isChainableReceiverNode(node) {
+    return (CALL_EXPRESSION_TYPES.has(node.type) ||
+        FIELD_ACCESS_NODE_TYPES.has(node.type) ||
+        AWAIT_EXPRESSION_NODE_TYPES.has(node.type) ||
+        SUBSCRIPT_NODE_TYPES.has(node.type));
+}
 const FIELD_ACCESS_NODE_TYPES = new Set([
     'member_expression', // TS/JS
     'member_access_expression', // C#
@@ -381,7 +440,10 @@ export function extractCallChain(receiverCallNode) {
         }
         else {
             // Reached a simple identifier — the base receiver
-            return { chain, baseReceiverName: innerReceiver.text || undefined };
+            return {
+                chain,
+                baseReceiverName: unwrapTransparentReceiver(innerReceiver).text || undefined,
+            };
         }
     }
     return chain.length > 0 ? { chain, baseReceiverName: undefined } : undefined;
@@ -402,10 +464,91 @@ export function extractCallChain(receiverCallNode) {
  *
  * Pure field chains and pure call chains are special cases (all steps same kind).
  */
+/**
+ * Node types that wrap an expression without changing what it denotes, so a
+ * receiver chain's BASE can be read through them.
+ *
+ * `svc!` (TS non-null assertion) and `(svc)` denote exactly `svc`; taking the
+ * wrapper's own text instead yields `svc!` / `(svc)`, which matches no binding
+ * and silently costs the chain its base.
+ *
+ * Deliberately EXCLUDES a cast (`x as T`, `(T)x`): a cast changes the type an
+ * expression denotes, so reading through one would type the receiver as the
+ * operand rather than as the cast target.
+ *
+ * Keyed by node type; the value is the operator text that has to TERMINATE the
+ * node for the peel to apply, or `null` for a node type that is transparent
+ * unconditionally.
+ *
+ * The gated entry exists because Swift force-unwrap (`self.a!`) is the exact
+ * semantic of TypeScript's `non_null_expression` — it yields the wrapped type —
+ * but Swift parses it as the general `postfix_expression`, which ALSO carries
+ * user-defined postfix operators. Those can return anything, so peeling that
+ * node type unconditionally would type the receiver as the operand and could
+ * produce a confidently wrong owner. Reading the operator keeps the peel to the
+ * case that is provably type-preserving.
+ */
+const TRANSPARENT_RECEIVER_WRAPPERS = new Map([
+    ['non_null_expression', null], // TypeScript `svc!`
+    ['parenthesized_expression', null], // `(svc)`
+    // NOT Swift-only: Kotlin's `!!` non-null assertion parses as the same node type
+    // and is equally type-preserving, so it is peeled too. Measured — the
+    // receiver-resolution bench moved `kotlin.nonNullAssert` VISIBLE-GAP ->
+    // RESOLVES when this landed, which is how the Kotlin effect was discovered
+    // rather than assumed. Any other grammar emitting `postfix_expression` is
+    // affected as well; the `!` gate, not the language, is what bounds this.
+    ['postfix_expression', '!'], // Swift `self.a!`, Kotlin `a!!`
+]);
+/** Is `node` a wrapper that denotes exactly what its operand denotes? */
+function isTransparentReceiverWrapper(node) {
+    // `node.type` is a native getter, and this predicate runs on every receiver
+    // node. Crossing it twice for two separate table lookups measured 376 ns/check
+    // against 188 ns for the single read below.
+    const operator = TRANSPARENT_RECEIVER_WRAPPERS.get(node.type);
+    // `undefined` is "not in the table"; `null` is "in the table, ungated". The
+    // two are distinguishable, so one `get` answers both questions — no separate
+    // `has` probe, and one crossing of the native `node.type` getter.
+    if (operator === undefined)
+        return false;
+    if (operator === null)
+        return true;
+    // The operator is an anonymous token, so it is not in `namedChildren`; the
+    // node's own text is the reliable place to read it. Deliberately NOT
+    // `node.lastChild` — measured 3x SLOWER (the child wrapper allocation
+    // dominates), and the token surfaces with type `bang`, not `!`.
+    return node.text.trimEnd().endsWith(operator);
+}
+/**
+ * Iteration bound for the wrapper peel. Its OWN constant, not `MAX_CHAIN_DEPTH`.
+ *
+ * The two answer unrelated questions — "how many chain hops do we type?" versus
+ * "how many redundant parens might someone write?" — and sharing one number
+ * meant raising the chain cap silently widened this loop as a side effect. That
+ * coupling is easy to miss precisely because the shared name reads as
+ * intentional. `((x))` nests twice; nothing real nests deeply.
+ */
+const MAX_TRANSPARENT_WRAPPER_DEPTH = 3;
+/** Peel transparent wrappers off a base receiver node. */
+function unwrapTransparentReceiver(node) {
+    let current = node;
+    for (let i = 0; i < MAX_TRANSPARENT_WRAPPER_DEPTH && isTransparentReceiverWrapper(current); i++) {
+        const inner = current.namedChildren?.find((c) => c !== null);
+        if (inner === undefined || inner === null)
+            break;
+        current = inner;
+    }
+    return current;
+}
 export function extractMixedChain(receiverNode) {
     const chain = [];
     let current = receiverNode;
     while (chain.length < MAX_CHAIN_DEPTH) {
+        // Peel transparent wrappers at LOOP ENTRY, not only where a base is
+        // returned. `(await svc.getUserAsync()).save()` hands this walk a
+        // `parenthesized_expression`, which matches no branch below, so the walk
+        // fell straight through to the base case with an empty chain and minted
+        // nothing — the await step could never be reached.
+        current = unwrapTransparentReceiver(current);
         if (CALL_EXPRESSION_TYPES.has(current.type)) {
             // ── Call expression: extract method name + inner receiver ────────────
             const funcNode = current.childForFieldName?.('function') ??
@@ -458,12 +601,14 @@ export function extractMixedChain(receiverNode) {
             }
             if (!innerReceiver)
                 break;
-            if (CALL_EXPRESSION_TYPES.has(innerReceiver.type) ||
-                FIELD_ACCESS_NODE_TYPES.has(innerReceiver.type)) {
+            if (isChainableReceiverNode(innerReceiver)) {
                 current = innerReceiver;
             }
             else {
-                return { chain, baseReceiverName: innerReceiver.text || undefined };
+                return {
+                    chain,
+                    baseReceiverName: unwrapTransparentReceiver(innerReceiver).text || undefined,
+                };
             }
         }
         else if (FIELD_ACCESS_NODE_TYPES.has(current.type)) {
@@ -506,12 +651,62 @@ export function extractMixedChain(receiverNode) {
             chain.unshift({ kind: 'field', name: propertyName });
             if (!innerObject)
                 break;
-            if (CALL_EXPRESSION_TYPES.has(innerObject.type) ||
-                FIELD_ACCESS_NODE_TYPES.has(innerObject.type)) {
+            if (isChainableReceiverNode(innerObject)) {
                 current = innerObject;
             }
             else {
-                return { chain, baseReceiverName: innerObject.text || undefined };
+                return {
+                    chain,
+                    baseReceiverName: unwrapTransparentReceiver(innerObject).text || undefined,
+                };
+            }
+        }
+        else if (AWAIT_EXPRESSION_NODE_TYPES.has(current.type)) {
+            // Name-free: the awaited call's method name already lives on its own
+            // `call` step, so this records only that an await happened.
+            chain.unshift({ kind: 'await' });
+            const inner = current.childForFieldName?.('argument') ??
+                current.childForFieldName?.('expression') ??
+                current.namedChildren?.find((c) => c !== null) ??
+                null;
+            if (!inner)
+                break;
+            if (isChainableReceiverNode(inner)) {
+                current = inner;
+            }
+            else {
+                return {
+                    chain,
+                    baseReceiverName: unwrapTransparentReceiver(inner).text || undefined,
+                };
+            }
+        }
+        else if (SUBSCRIPT_NODE_TYPES.has(current.type)) {
+            // Name-free: a subscript key is a VALUE, not an identifier the resolver
+            // could look up, so there is no member name to record.
+            chain.unshift({ kind: 'index' });
+            // Shared per-grammar table — it knows Python's `value` and Java's `array`,
+            // which a locally-written ladder omitted (they worked only because the
+            // container happened to be the first named child, an ordering coincidence
+            // rather than a contract). Falls back for grammars whose subscript node
+            // carries no `index` field.
+            const obj = subscriptBase(current) ??
+                current.childForFieldName?.('object') ??
+                current.childForFieldName?.('argument') ??
+                current.childForFieldName?.('operand') ??
+                current.childForFieldName?.('expression') ??
+                current.namedChildren?.find((c) => c !== null) ??
+                null;
+            if (!obj)
+                break;
+            if (isChainableReceiverNode(obj)) {
+                current = obj;
+            }
+            else {
+                return {
+                    chain,
+                    baseReceiverName: unwrapTransparentReceiver(obj).text || undefined,
+                };
             }
         }
         else if (current.type === 'selector') {

package/dist/core/ingestion/utils/callable-flow-captures.d.ts

@@ -6,6 +6,53 @@
  * callable signatures, protocol invocation names). The central extractor
  * never sees a parser node and shared ingestion code never branches on a
  * language name.
+ *
+ * ## The cell/site model
+ *
+ * A *cell* is a named storage location that may hold a callable — a variable,
+ * parameter, field or pointer, canonicalized to a binding key by the scope
+ * tree. A *site* is one observed fact about cells, emitted here as a capture
+ * match and consumed by `passes/callable-value-flow.ts`, which runs them to a
+ * fixpoint. The site kinds (`CallableFlowSite`) are:
+ *
+ * - `seed` — a cell acquires a named callable: `f = target`. Carries
+ *   `@callable-flow.target-name`, the name the pass resolves against.
+ * - `copy` / `alias` — a cell takes another cell's contents, so targets flow
+ *   between them.
+ * - `address` / `store` / `load` — indirection through a pointer cell.
+ * - `formal` — a parameter cell of a known function, by index.
+ * - `argument` — a callable passed at a call site, binding to that `formal`.
+ * - `invoke` — a call THROUGH a cell (`f()`), the site that ultimately becomes
+ *   a `CALLS` edge once the cell's target set is known.
+ *
+ * ## The anonymous-callable convention
+ *
+ * A closure literal has no name to resolve against, so a `seed` whose source
+ * is an anonymous callable takes its **destination's** name as
+ * `@callable-flow.target-name` — `val f = { }` seeds "the cell `f` holds the
+ * callable named `f`". That is deliberately self-referential and only resolves
+ * because the binding itself is a callable target: `buildGraphTargetIndex`
+ * admits it on the label of the graph node it resolves to, which #2687 makes a
+ * `Function` for exactly this construct. Languages whose closure binding does
+ * NOT emit a callable graph node get no resolution from the convention alone
+ * (#2693).
+ *
+ * ## Adding a language
+ *
+ * Supply `CallableFlowCaptureOptions` from `<lang>/captures.ts` and call
+ * `synthesizeCallableFlowCaptures`. Two recurring traps:
+ *
+ * - A **fieldless** assignment/binding node decomposes to nothing under the
+ *   shared `left`/`name`/`value` fallback in `assignmentParts`. Supply
+ *   `extractAssignment` (Kotlin's `assignment`, Dart's
+ *   `initialized_identifier`). Returning `undefined` falls back to the shared
+ *   path, so one callback can handle the odd node and leave the rest alone.
+ * - A binding needs a `SymbolDefinition` for the pass to attach to. Captures
+ *   alone are not enough: without a `@declaration.*` for the bound name, the
+ *   seed has no cell to key on.
+ *
+ * `c/captures.ts` is the fullest worked example (pointers, signatures,
+ * overload selection); `dart/captures.ts` the smallest interesting one.
  */
 import type { CaptureMatch, ParameterTypeClass } from '../../../_shared/index.js';
 import { type SyntaxNode } from './ast-helpers.js';
@@ -92,3 +139,15 @@ export interface CallableFlowCaptureOptions {
  * linear in AST size (the scope-capture benchmark guards the scaling ratio).
  */
 export declare function synthesizeCallableFlowCaptures(root: SyntaxNode, options: CallableFlowCaptureOptions): readonly CaptureMatch[];
+/**
+ * For a subscript/index expression, the identifier of interest is always in
+ * the container operand, never the index: `tbl[i] = h` must bind the cell
+ * `tbl` (index-insensitive, Andersen-style), not the index variable `i` —
+ * seeding `i` both pollutes a same-named formal and misses the later
+ * `tbl[i]()` join (#2522 review). Field names cover the grammars that field
+ * their subscript nodes; others keep the generic traversal.
+ */
+/** The container operand of a subscript node, per grammar. Exported because the
+ *  receiver-chain walk needs the same per-grammar answer — two divergent field
+ *  tables for one question is how a new grammar gets half-supported. */
+export declare function subscriptBase(node: SyntaxNode): SyntaxNode | null;

package/dist/core/ingestion/utils/callable-flow-captures.js

@@ -6,6 +6,53 @@
  * callable signatures, protocol invocation names). The central extractor
  * never sees a parser node and shared ingestion code never branches on a
  * language name.
+ *
+ * ## The cell/site model
+ *
+ * A *cell* is a named storage location that may hold a callable — a variable,
+ * parameter, field or pointer, canonicalized to a binding key by the scope
+ * tree. A *site* is one observed fact about cells, emitted here as a capture
+ * match and consumed by `passes/callable-value-flow.ts`, which runs them to a
+ * fixpoint. The site kinds (`CallableFlowSite`) are:
+ *
+ * - `seed` — a cell acquires a named callable: `f = target`. Carries
+ *   `@callable-flow.target-name`, the name the pass resolves against.
+ * - `copy` / `alias` — a cell takes another cell's contents, so targets flow
+ *   between them.
+ * - `address` / `store` / `load` — indirection through a pointer cell.
+ * - `formal` — a parameter cell of a known function, by index.
+ * - `argument` — a callable passed at a call site, binding to that `formal`.
+ * - `invoke` — a call THROUGH a cell (`f()`), the site that ultimately becomes
+ *   a `CALLS` edge once the cell's target set is known.
+ *
+ * ## The anonymous-callable convention
+ *
+ * A closure literal has no name to resolve against, so a `seed` whose source
+ * is an anonymous callable takes its **destination's** name as
+ * `@callable-flow.target-name` — `val f = { }` seeds "the cell `f` holds the
+ * callable named `f`". That is deliberately self-referential and only resolves
+ * because the binding itself is a callable target: `buildGraphTargetIndex`
+ * admits it on the label of the graph node it resolves to, which #2687 makes a
+ * `Function` for exactly this construct. Languages whose closure binding does
+ * NOT emit a callable graph node get no resolution from the convention alone
+ * (#2693).
+ *
+ * ## Adding a language
+ *
+ * Supply `CallableFlowCaptureOptions` from `<lang>/captures.ts` and call
+ * `synthesizeCallableFlowCaptures`. Two recurring traps:
+ *
+ * - A **fieldless** assignment/binding node decomposes to nothing under the
+ *   shared `left`/`name`/`value` fallback in `assignmentParts`. Supply
+ *   `extractAssignment` (Kotlin's `assignment`, Dart's
+ *   `initialized_identifier`). Returning `undefined` falls back to the shared
+ *   path, so one callback can handle the odd node and leave the rest alone.
+ * - A binding needs a `SymbolDefinition` for the pass to attach to. Captures
+ *   alone are not enough: without a `@declaration.*` for the bound name, the
+ *   seed has no cell to key on.
+ *
+ * `c/captures.ts` is the fullest worked example (pointers, signatures,
+ * overload selection); `dart/captures.ts` the smallest interesting one.
  */
 import { nodeToCapture, syntheticCapture } from './ast-helpers.js';
 /**
@@ -733,7 +780,10 @@ function unaryOperator(node) {
  * `tbl[i]()` join (#2522 review). Field names cover the grammars that field
  * their subscript nodes; others keep the generic traversal.
  */
-function subscriptBase(node) {
+/** The container operand of a subscript node, per grammar. Exported because the
+ *  receiver-chain walk needs the same per-grammar answer — two divergent field
+ *  tables for one question is how a new grammar gets half-supported. */
+export function subscriptBase(node) {
     if (node.childForFieldName('index') === null)
         return null;
     return (node.childForFieldName('argument') ?? // C/C++ subscript_expression

package/dist/core/ingestion/utils/callable-labels.d.ts

@@ -11,3 +11,28 @@ import type { NodeLabel } from '../../../_shared/index.js';
  * qualified/simple key and a ctor chain becomes a self-loop (#1928 F38 / #2046).
  */
 export declare function isOverloadableCallable(label: NodeLabel | undefined): boolean;
+/**
+ * Labels whose FUNCTION-LOCAL declarations carry the enclosing-callable +
+ * position identity of #2699 (`Function:x.ts:run.save@3:2`).
+ *
+ * Wider than {@link isOverloadableCallable} on purpose. #2695 restricted the
+ * rule to callables because the collision that produced wrong CALLS edges was
+ * between callables, and widening churned ids for symbols the local-symbol
+ * pruner mostly deletes. But the issue's ORIGINAL complaint was about values:
+ * a top-level `const handler` and a function-local `const handler` collapsed
+ * onto one `Const:v.ts:handler`, and no callable gate ever reaches that. The
+ * limitation is closed here rather than carried.
+ *
+ * Only LOCALS are affected either way: the prefix comes from
+ * `enclosingCallablePrefix`, which returns `undefined` when nothing encloses
+ * the declaration, so top-level and class-member ids are untouched — that is
+ * what keeps this off the symbols other files and stored references address.
+ * A class field stays unqualified even inside a function, because the prefix
+ * walk boundaries on class-likes.
+ *
+ * ONE definition, deliberately: the id-building phase and the resolution phase
+ * must agree on this set or the caller attaches to a node that does not exist
+ * and the edge is silently dropped — the failure mode #2714 fixed, invisible
+ * from outside because "zero dangling edges" is what it looks like.
+ */
+export declare function isPositionQualifiedLocalLabel(label: NodeLabel | undefined): boolean;

package/dist/core/ingestion/utils/callable-labels.js

@@ -12,3 +12,34 @@
 export function isOverloadableCallable(label) {
     return label === 'Function' || label === 'Method' || label === 'Constructor';
 }
+/**
+ * Labels whose FUNCTION-LOCAL declarations carry the enclosing-callable +
+ * position identity of #2699 (`Function:x.ts:run.save@3:2`).
+ *
+ * Wider than {@link isOverloadableCallable} on purpose. #2695 restricted the
+ * rule to callables because the collision that produced wrong CALLS edges was
+ * between callables, and widening churned ids for symbols the local-symbol
+ * pruner mostly deletes. But the issue's ORIGINAL complaint was about values:
+ * a top-level `const handler` and a function-local `const handler` collapsed
+ * onto one `Const:v.ts:handler`, and no callable gate ever reaches that. The
+ * limitation is closed here rather than carried.
+ *
+ * Only LOCALS are affected either way: the prefix comes from
+ * `enclosingCallablePrefix`, which returns `undefined` when nothing encloses
+ * the declaration, so top-level and class-member ids are untouched — that is
+ * what keeps this off the symbols other files and stored references address.
+ * A class field stays unqualified even inside a function, because the prefix
+ * walk boundaries on class-likes.
+ *
+ * ONE definition, deliberately: the id-building phase and the resolution phase
+ * must agree on this set or the caller attaches to a node that does not exist
+ * and the edge is silently dropped — the failure mode #2714 fixed, invisible
+ * from outside because "zero dangling edges" is what it looks like.
+ */
+export function isPositionQualifiedLocalLabel(label) {
+    return (isOverloadableCallable(label) ||
+        label === 'Variable' ||
+        label === 'Const' ||
+        label === 'Property' ||
+        label === 'Static');
+}

package/dist/core/ingestion/utils/effective-ram.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Effective RAM in bytes: physical total, or a REAL smaller cgroup limit
+ * (#2649). `process.constrainedMemory()` returns a huge sentinel when
+ * unconstrained, and only the leaf cgroup's limit is visible (parent-slice
+ * caps are not) — so a smaller-than-physical value is trusted and anything
+ * else falls back to `os.totalmem()`. Mirrors `computeHeapCapMb`'s
+ * constrained handling in `cli/analyze.ts`; container-blind sizing told
+ * users "this machine has more memory" inside an 8GB-limited container on
+ * a 64GB host, and sized worker heap caps past the whole container.
+ */
+export declare function effectiveRamBytes(): number;
+/**
+ * The RAM-aware heap cap formula (#2649), single-sourced here so the CLI
+ * respawn (`computeHeapCapMb` in `cli/analyze.ts`), and the server's
+ * analyze fork size from the same rule: `0.75 × effective RAM`, raised to
+ * the floor when RAM allows, never above `0.80 × effective RAM`.
+ */
+export declare function heapCapMbFor(effectiveBytes: number): number;
+/**
+ * True when the operator has turned GitNexus's memory autopilot off
+ * (`GITNEXUS_MEMORY=off`).
+ *
+ * One switch for one concern. Memory management has two automatic behaviours —
+ * re-running analyze with a RAM-aware heap cap, and aborting the parse before
+ * V8's ineffective-mark-compact death spiral — and an operator who wants to
+ * drive manually wants both off, not one. They were previously two separate
+ * variables (`GITNEXUS_AUTO_HEAP`, `GITNEXUS_HEAP_GUARD`), which is three knobs
+ * for one intent once the worker-heap override is counted; neither had shipped,
+ * so this consolidates them rather than deprecating anything.
+ *
+ * Note the ordinary way to pin the heap is Node's own `--max-old-space-size`,
+ * which `ensureHeap` already honours as the operator's decision. This switch is
+ * for declining the autopilot WITHOUT naming a size.
+ *
+ * Lives here beside the cap formula so policy and its escape hatch are
+ * single-sourced. Read every call (not memoized) so tests can stub the env.
+ */
+export declare function memoryAutopilotDisabled(): boolean;
+/** The cap for THIS machine/container: `heapCapMbFor(effectiveRamBytes())`. */
+export declare function autoHeapCapMb(): number;

package/dist/core/ingestion/utils/effective-ram.js

@@ -0,0 +1,58 @@
+import os from 'node:os';
+/**
+ * Effective RAM in bytes: physical total, or a REAL smaller cgroup limit
+ * (#2649). `process.constrainedMemory()` returns a huge sentinel when
+ * unconstrained, and only the leaf cgroup's limit is visible (parent-slice
+ * caps are not) — so a smaller-than-physical value is trusted and anything
+ * else falls back to `os.totalmem()`. Mirrors `computeHeapCapMb`'s
+ * constrained handling in `cli/analyze.ts`; container-blind sizing told
+ * users "this machine has more memory" inside an 8GB-limited container on
+ * a 64GB host, and sized worker heap caps past the whole container.
+ */
+export function effectiveRamBytes() {
+    const total = os.totalmem();
+    const constrained = typeof process.constrainedMemory === 'function' ? process.constrainedMemory() : undefined;
+    return typeof constrained === 'number' && constrained > 0 && constrained < total
+        ? constrained
+        : total;
+}
+/** Historical floor for the auto heap cap — applied only up to 0.80 × RAM
+ *  (a floor at or above physical memory swap-thrashes instead of OOMing,
+ *  #2649). */
+const HEAP_FLOOR_MB = 16384;
+/**
+ * The RAM-aware heap cap formula (#2649), single-sourced here so the CLI
+ * respawn (`computeHeapCapMb` in `cli/analyze.ts`), and the server's
+ * analyze fork size from the same rule: `0.75 × effective RAM`, raised to
+ * the floor when RAM allows, never above `0.80 × effective RAM`.
+ */
+export function heapCapMbFor(effectiveBytes) {
+    const effectiveMb = Math.floor(effectiveBytes / (1024 * 1024));
+    return Math.min(Math.max(HEAP_FLOOR_MB, Math.floor(0.75 * effectiveMb)), Math.floor(0.8 * effectiveMb));
+}
+/**
+ * True when the operator has turned GitNexus's memory autopilot off
+ * (`GITNEXUS_MEMORY=off`).
+ *
+ * One switch for one concern. Memory management has two automatic behaviours —
+ * re-running analyze with a RAM-aware heap cap, and aborting the parse before
+ * V8's ineffective-mark-compact death spiral — and an operator who wants to
+ * drive manually wants both off, not one. They were previously two separate
+ * variables (`GITNEXUS_AUTO_HEAP`, `GITNEXUS_HEAP_GUARD`), which is three knobs
+ * for one intent once the worker-heap override is counted; neither had shipped,
+ * so this consolidates them rather than deprecating anything.
+ *
+ * Note the ordinary way to pin the heap is Node's own `--max-old-space-size`,
+ * which `ensureHeap` already honours as the operator's decision. This switch is
+ * for declining the autopilot WITHOUT naming a size.
+ *
+ * Lives here beside the cap formula so policy and its escape hatch are
+ * single-sourced. Read every call (not memoized) so tests can stub the env.
+ */
+export function memoryAutopilotDisabled() {
+    return process.env.GITNEXUS_MEMORY === 'off';
+}
+/** The cap for THIS machine/container: `heapCapMbFor(effectiveRamBytes())`. */
+export function autoHeapCapMb() {
+    return heapCapMbFor(effectiveRamBytes());
+}

package/dist/core/ingestion/utils/line-base.d.ts

@@ -18,3 +18,17 @@
  * must not shift. The clamp guards degenerate inputs (line 0 / empty files).
  */
 export declare const toZeroBasedLine: (oneBasedLine: number) => number;
+/**
+ * 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 declare const toOneBasedLine: (zeroBasedLine: number) => number;