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

package/dist/core/ingestion/scope-resolution/graph-bridge/imports-to-edges.d.ts

@@ -10,8 +10,131 @@
  * single function. The `reason` defaults to
  * `'scope-resolution: import'`; provider may override if downstream
  * filters on reason.
+ *
+ * ## Non-initializing imports carry a distinct `reason`
+ *
+ * A pair reached ONLY by imports that cannot run at module-initialization time
+ * still gets an edge — it is a real dependency, and impact/trace must see it —
+ * but it cannot participate in the kind of cycle `check --cycles` exists to
+ * find. There are two such kinds, and they are NOT the same fact:
+ *
+ *  - **deferred** — the import exists at runtime, just later. `import('./m')`
+ *    and a function-local `import` both really load the module; what they do
+ *    not do is load it while the importing module is still initializing.
+ *    Deferring is in fact the standard idiom for BREAKING an init cycle, and
+ *    this repository uses it that way on purpose in both spellings:
+ *    `core/group/service.ts` does `await import('./cross-impact.js')`, and
+ *    `eval/workflow_bench/proposer_sandbox.py` puts a plain `import` inside a
+ *    function under the comment "Kept lazy to avoid a module cycle".
+ *  - **type-only** — the import does not exist at runtime AT ALL. `tsc` deletes
+ *    `import type { X } from './m'`; the emitted JavaScript contains no
+ *    reference to `./m`. Nothing was made later; the dependency is compile-time
+ *    only. Eight of the ten false cycles this repository reports are this.
+ *
+ * Reporting either as an init cycle flags the fix as the bug. They get separate
+ * suffixes rather than one shared "not really an import" tag because the two
+ * answers to "does this edge exist when the program runs?" are opposite, and a
+ * reader of the graph — or the next filter written against `reason` — needs to
+ * be able to tell them apart.
+ *
+ * Three signals, because no one of them covers the others. All three ride the
+ * EDGE — this function reads properties and never walks the scope tree for
+ * them, for the reason spelled out under "Why nothing here is derived from the
+ * scope tree" below:
+ *
+ *  - `ImportEdge.kind === 'dynamic-resolved'` — TS/JS `import()`.
+ *  - `ImportEdge.runsOnlyWhenCalled` — the import sits inside a function body
+ *    AND this language's imports execute where they are written: Python's
+ *    `def f(): from x import Y`, Ruby's `def f; require 'x'; end`, a CommonJS
+ *    `require()` in a body. Nothing marks those as dynamic, because
+ *    syntactically they are ordinary imports; what defers them is WHERE they
+ *    sit, so `scope-extractor.ts` decides it in Pass 3 and it is carried down
+ *    — `ParsedImport` → `finalize-algorithm.ts` → the edge. A language whose
+ *    imports do not execute never gets the tag no matter where one sits (Rust
+ *    `use`, C/C++ `#include`; see
+ *    `LanguageProvider.importsExecuteWhereWritten`).
+ *  - `ImportEdge.typeOnly` — TypeScript `import type` / `import { type X }`.
+ *    Neither of the other two sees it: the kind is the ordinary `named` /
+ *    `alias`, and the statement sits at module top level like any other. Only
+ *    the `type` keyword says it, so it is carried from the syntax down —
+ *    `typescript/import-decomposer.ts` → `interpret.ts` → `finalize-algorithm.ts`.
+ *
+ * ## Why nothing here is derived from the scope tree
+ *
+ * `scopeTree` is used for exactly one thing: turning the map's key into the
+ * source `filePath`. It is NOT a place to ask where an import was written.
+ * `finalize-algorithm.ts:295` publishes every file's finalized edges as
+ * `linkedByScope.set(file.moduleScope, …)`, so the `imports` map this function
+ * receives holds one bucket per FILE, keyed by that file's `Module` scope —
+ * never by the scope an import was actually written in. A walk from such a key
+ * looking for an enclosing `Function` starts at a `Module` and answers `false`
+ * every time, for every import in the tree.
+ *
+ * That walk was here, and it never fired once. It looked correct in unit tests
+ * only because they hand-built `new Map([['fn', …]])`, a shape the pipeline
+ * cannot produce. Position now arrives as `runsOnlyWhenCalled`, decided where
+ * the position is still known.
+ *
+ * Tagging the reason is enough for the check query, which already filters
+ * non-runtime edges that way (`markdown-link`, Swift implicit module
+ * visibility) — no change to the persisted RELATION schema, no new property on
+ * the emitted `CodeRelation`. (`typeOnly` and `runsOnlyWhenCalled` are fields
+ * on the in-memory `ImportEdge`, which is never persisted; they end here.)
+ *
+ * ponytail: reason-string tagging rather than a typed relation property,
+ * because the one consumer already filters on `reason` and a property would
+ * touch the relation schema. If a second consumer ever needs to branch on this,
+ * promote it to a real field then.
+ *
+ * ## Precedence: the strongest runtime presence in a pair wins
+ *
+ * Emission dedupes by `(sourceFile, targetFile)`, so one edge has to speak for
+ * every import that reaches the pair. Rank them by how much of the dependency
+ * survives to run time — initializing > deferred > erased — and let the
+ * strongest win: the ranks ascend as presence weakens, so the pair keeps the
+ * LOWEST rank it sees ({@link PRESENCE_INITIALIZES} is 0). Inverting that
+ * comparison is the one mutation here that hides a real cycle rather than
+ * inventing a false one, which is why the suite pins it directly.
+ *
+ *  - Any initializing import wins outright. One top-level `import { f }` beside
+ *    an `await import()` and a dozen `import type`s is a real init dependency;
+ *    reporting the pair as deferred or erased would HIDE a true cycle.
+ *  - Deferred beats type-only. A pair with a function-local import plus some
+ *    `import type`s does load the target at run time, so `(deferred)` is the
+ *    honest label; `(type-only)` would claim the module never loads.
+ *  - The two deferred signals rank the same. `import()` and a function-local
+ *    import are the same claim about the emitted program — it loads, later —
+ *    so a pair reached only by them is `(deferred)` either way.
+ *
+ * That also settles the mixed statement `import { type X, Y } from './m'`
+ * without the decomposer aggregating anything: `X` is erased, `Y` is not, and
+ * `Y` carries the pair. A statement is type-only exactly when every specifier
+ * it decomposes to is.
+ *
+ * Pairs are collected before anything is emitted so the ranking sees every
+ * contributing edge rather than whichever one arrived first. Insertion order
+ * into the map is first-seen order, so emission order is byte-identical to the
+ * single-pass form this replaced.
  */
 import type { ImportEdge, ScopeId } from '../../../../_shared/index.js';
 import type { KnowledgeGraph } from '../../../graph/types.js';
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+/**
+ * Reason suffix for a pair reachable only through imports that run later —
+ * `import()` and function-local imports.
+ *
+ * `check --cycles` matches this EXACTLY, so a provider that overrides the base
+ * reason keeps its deferred edges filterable — the suffix travels with it.
+ */
+export declare const DEFERRED_IMPORT_REASON_SUFFIX = " (deferred)";
+/**
+ * Reason suffix for a pair reachable only through imports the compiler erases —
+ * TypeScript `import type` / `import { type X }`.
+ *
+ * A second suffix rather than a reuse of {@link DEFERRED_IMPORT_REASON_SUFFIX}:
+ * both are excluded from the cycle query, but "runs later" and "never runs" are
+ * opposite answers about the emitted program, and the reason string is the only
+ * place the graph records which one this pair is.
+ */
+export declare const TYPE_ONLY_IMPORT_REASON_SUFFIX = " (type-only)";
 export declare function emitImportEdges(graph: KnowledgeGraph, imports: ReadonlyMap<ScopeId, readonly ImportEdge[]>, scopeTree: ScopeResolutionIndexes['scopeTree'], reason?: string): number;

package/dist/core/ingestion/scope-resolution/graph-bridge/imports-to-edges.js

@@ -10,12 +10,156 @@
  * single function. The `reason` defaults to
  * `'scope-resolution: import'`; provider may override if downstream
  * filters on reason.
+ *
+ * ## Non-initializing imports carry a distinct `reason`
+ *
+ * A pair reached ONLY by imports that cannot run at module-initialization time
+ * still gets an edge — it is a real dependency, and impact/trace must see it —
+ * but it cannot participate in the kind of cycle `check --cycles` exists to
+ * find. There are two such kinds, and they are NOT the same fact:
+ *
+ *  - **deferred** — the import exists at runtime, just later. `import('./m')`
+ *    and a function-local `import` both really load the module; what they do
+ *    not do is load it while the importing module is still initializing.
+ *    Deferring is in fact the standard idiom for BREAKING an init cycle, and
+ *    this repository uses it that way on purpose in both spellings:
+ *    `core/group/service.ts` does `await import('./cross-impact.js')`, and
+ *    `eval/workflow_bench/proposer_sandbox.py` puts a plain `import` inside a
+ *    function under the comment "Kept lazy to avoid a module cycle".
+ *  - **type-only** — the import does not exist at runtime AT ALL. `tsc` deletes
+ *    `import type { X } from './m'`; the emitted JavaScript contains no
+ *    reference to `./m`. Nothing was made later; the dependency is compile-time
+ *    only. Eight of the ten false cycles this repository reports are this.
+ *
+ * Reporting either as an init cycle flags the fix as the bug. They get separate
+ * suffixes rather than one shared "not really an import" tag because the two
+ * answers to "does this edge exist when the program runs?" are opposite, and a
+ * reader of the graph — or the next filter written against `reason` — needs to
+ * be able to tell them apart.
+ *
+ * Three signals, because no one of them covers the others. All three ride the
+ * EDGE — this function reads properties and never walks the scope tree for
+ * them, for the reason spelled out under "Why nothing here is derived from the
+ * scope tree" below:
+ *
+ *  - `ImportEdge.kind === 'dynamic-resolved'` — TS/JS `import()`.
+ *  - `ImportEdge.runsOnlyWhenCalled` — the import sits inside a function body
+ *    AND this language's imports execute where they are written: Python's
+ *    `def f(): from x import Y`, Ruby's `def f; require 'x'; end`, a CommonJS
+ *    `require()` in a body. Nothing marks those as dynamic, because
+ *    syntactically they are ordinary imports; what defers them is WHERE they
+ *    sit, so `scope-extractor.ts` decides it in Pass 3 and it is carried down
+ *    — `ParsedImport` → `finalize-algorithm.ts` → the edge. A language whose
+ *    imports do not execute never gets the tag no matter where one sits (Rust
+ *    `use`, C/C++ `#include`; see
+ *    `LanguageProvider.importsExecuteWhereWritten`).
+ *  - `ImportEdge.typeOnly` — TypeScript `import type` / `import { type X }`.
+ *    Neither of the other two sees it: the kind is the ordinary `named` /
+ *    `alias`, and the statement sits at module top level like any other. Only
+ *    the `type` keyword says it, so it is carried from the syntax down —
+ *    `typescript/import-decomposer.ts` → `interpret.ts` → `finalize-algorithm.ts`.
+ *
+ * ## Why nothing here is derived from the scope tree
+ *
+ * `scopeTree` is used for exactly one thing: turning the map's key into the
+ * source `filePath`. It is NOT a place to ask where an import was written.
+ * `finalize-algorithm.ts:295` publishes every file's finalized edges as
+ * `linkedByScope.set(file.moduleScope, …)`, so the `imports` map this function
+ * receives holds one bucket per FILE, keyed by that file's `Module` scope —
+ * never by the scope an import was actually written in. A walk from such a key
+ * looking for an enclosing `Function` starts at a `Module` and answers `false`
+ * every time, for every import in the tree.
+ *
+ * That walk was here, and it never fired once. It looked correct in unit tests
+ * only because they hand-built `new Map([['fn', …]])`, a shape the pipeline
+ * cannot produce. Position now arrives as `runsOnlyWhenCalled`, decided where
+ * the position is still known.
+ *
+ * Tagging the reason is enough for the check query, which already filters
+ * non-runtime edges that way (`markdown-link`, Swift implicit module
+ * visibility) — no change to the persisted RELATION schema, no new property on
+ * the emitted `CodeRelation`. (`typeOnly` and `runsOnlyWhenCalled` are fields
+ * on the in-memory `ImportEdge`, which is never persisted; they end here.)
+ *
+ * ponytail: reason-string tagging rather than a typed relation property,
+ * because the one consumer already filters on `reason` and a property would
+ * touch the relation schema. If a second consumer ever needs to branch on this,
+ * promote it to a real field then.
+ *
+ * ## Precedence: the strongest runtime presence in a pair wins
+ *
+ * Emission dedupes by `(sourceFile, targetFile)`, so one edge has to speak for
+ * every import that reaches the pair. Rank them by how much of the dependency
+ * survives to run time — initializing > deferred > erased — and let the
+ * strongest win: the ranks ascend as presence weakens, so the pair keeps the
+ * LOWEST rank it sees ({@link PRESENCE_INITIALIZES} is 0). Inverting that
+ * comparison is the one mutation here that hides a real cycle rather than
+ * inventing a false one, which is why the suite pins it directly.
+ *
+ *  - Any initializing import wins outright. One top-level `import { f }` beside
+ *    an `await import()` and a dozen `import type`s is a real init dependency;
+ *    reporting the pair as deferred or erased would HIDE a true cycle.
+ *  - Deferred beats type-only. A pair with a function-local import plus some
+ *    `import type`s does load the target at run time, so `(deferred)` is the
+ *    honest label; `(type-only)` would claim the module never loads.
+ *  - The two deferred signals rank the same. `import()` and a function-local
+ *    import are the same claim about the emitted program — it loads, later —
+ *    so a pair reached only by them is `(deferred)` either way.
+ *
+ * That also settles the mixed statement `import { type X, Y } from './m'`
+ * without the decomposer aggregating anything: `X` is erased, `Y` is not, and
+ * `Y` carries the pair. A statement is type-only exactly when every specifier
+ * it decomposes to is.
+ *
+ * Pairs are collected before anything is emitted so the ranking sees every
+ * contributing edge rather than whichever one arrived first. Insertion order
+ * into the map is first-seen order, so emission order is byte-identical to the
+ * single-pass form this replaced.
  */
 import { generateId } from '../../../../lib/utils.js';
+/**
+ * Reason suffix for a pair reachable only through imports that run later —
+ * `import()` and function-local imports.
+ *
+ * `check --cycles` matches this EXACTLY, so a provider that overrides the base
+ * reason keeps its deferred edges filterable — the suffix travels with it.
+ */
+export const DEFERRED_IMPORT_REASON_SUFFIX = ' (deferred)';
+/**
+ * Reason suffix for a pair reachable only through imports the compiler erases —
+ * TypeScript `import type` / `import { type X }`.
+ *
+ * A second suffix rather than a reuse of {@link DEFERRED_IMPORT_REASON_SUFFIX}:
+ * both are excluded from the cycle query, but "runs later" and "never runs" are
+ * opposite answers about the emitted program, and the reason string is the only
+ * place the graph records which one this pair is.
+ */
+export const TYPE_ONLY_IMPORT_REASON_SUFFIX = ' (type-only)';
+/**
+ * How much of an import survives to run time. Lower is stronger; a pair takes
+ * the minimum over every edge that reaches it. See the precedence section in
+ * the module header for why the order is this one.
+ */
+const PRESENCE_INITIALIZES = 0;
+const PRESENCE_DEFERRED = 1;
+const PRESENCE_ERASED = 2;
+/**
+ * Suffix per presence rank; the empty string is a real init dependency.
+ *
+ * Indexed rather than branched so the rank order lives in exactly one place —
+ * the constants above — instead of being restated by the order of an if-chain.
+ */
+const REASON_SUFFIX_BY_PRESENCE = {
+    [PRESENCE_INITIALIZES]: '',
+    [PRESENCE_DEFERRED]: DEFERRED_IMPORT_REASON_SUFFIX,
+    [PRESENCE_ERASED]: TYPE_ONLY_IMPORT_REASON_SUFFIX,
+};
 export function emitImportEdges(graph, imports, scopeTree, reason = 'scope-resolution: import') {
-    const seen = new Set();
-    let emitted = 0;
+    /** dedupKey -> the pair, plus the strongest runtime presence reaching it. */
+    const pairs = new Map();
     for (const [scopeId, edges] of imports) {
+        // The key's only job here is naming the source file — see the module
+        // header on why it says nothing about where an import was written.
         const scope = scopeTree.getScope(scopeId);
         if (scope === undefined)
             continue;
@@ -25,22 +169,32 @@ export function emitImportEdges(graph, imports, scopeTree, reason = 'scope-resol
                 continue;
             if (edge.targetFile === sourceFile)
                 continue;
+            // Erasure is checked first: an `import type` inside a function is still
+            // erased, not merely deferred, and the two are not mutually exclusive.
+            const presence = edge.typeOnly === true
+                ? PRESENCE_ERASED
+                : edge.runsOnlyWhenCalled === true || edge.kind === 'dynamic-resolved'
+                    ? PRESENCE_DEFERRED
+                    : PRESENCE_INITIALIZES;
             const dedupKey = `${sourceFile}->${edge.targetFile}`;
-            if (seen.has(dedupKey))
-                continue;
-            seen.add(dedupKey);
-            const sourceId = generateId('File', sourceFile);
-            const targetId = generateId('File', edge.targetFile);
-            graph.addRelationship({
-                id: generateId('IMPORTS', dedupKey),
-                sourceId,
-                targetId,
-                type: 'IMPORTS',
-                confidence: 1.0,
-                reason,
-            });
-            emitted++;
+            const existing = pairs.get(dedupKey);
+            if (existing === undefined) {
+                pairs.set(dedupKey, { sourceFile, targetFile: edge.targetFile, presence });
+            }
+            else if (presence < existing.presence) {
+                existing.presence = presence;
+            }
         }
     }
-    return emitted;
+    for (const [dedupKey, pair] of pairs) {
+        graph.addRelationship({
+            id: generateId('IMPORTS', dedupKey),
+            sourceId: generateId('File', pair.sourceFile),
+            targetId: generateId('File', pair.targetFile),
+            type: 'IMPORTS',
+            confidence: 1.0,
+            reason: reason + REASON_SUFFIX_BY_PRESENCE[pair.presence],
+        });
+    }
+    return pairs.size;
 }

package/dist/core/ingestion/scope-resolution/graph-bridge/node-lookup.d.ts

@@ -1,6 +1,6 @@
 /**
  * Build a `(filePath, name) → graphNodeId` lookup over the graph's
- * Function/Method/Class/Constructor nodes. Two keys per node:
+ * {@link LINKABLE_LABELS} definition nodes. Two keys per node:
  *
  *   - simple name (`User` / `save`) — legacy fallback
  *   - qualified name when derivable from the node id (`User.save`)
@@ -33,5 +33,60 @@ export type GraphNodeLookup = ReadonlyMap<string, string>;
 export declare function qualifiedKey(filePath: string, label: NodeLabel, qualifiedName: string): string;
 /** Simple-name key (legacy fallback keyspace — no `<q>` prefix). */
 export declare function simpleKey(filePath: string, name: string): string;
+/**
+ * Position key: `(filePath, label, 0-based startLine, simple name)` (#2699).
+ *
+ * The strongest evidence there is, and the only one that needs no name
+ * qualification at all — a definition and its graph node are the same
+ * construct, so they share a source position. That makes it correct for
+ * exactly the cases a name-based key cannot express: a function-local
+ * declaration shadowing a file-level one, a local inside an ANONYMOUS
+ * function (no name to qualify with), and two same-named declarations in
+ * sibling blocks. ECMAScript gives each of those its own environment record;
+ * position is what distinguishes them without having to model the chain.
+ *
+ * Registered only for callable labels, and only when the (line, name) pair is
+ * unique in the file — a genuine tie (overloads declared on one line) stores
+ * the `AMBIGUOUS_POSITION` tombstone so the caller falls through to the
+ * name-based keys rather than picking by source order.
+ */
+export declare function positionKey(filePath: string, label: NodeLabel, startLine: number, name: string): string;
+/**
+ * Key recording that a FUNCTION-LOCAL callable with this simple name exists in the
+ * file (#2699 follow-up).
+ *
+ * `resolveDefGraphId`'s last resort is a label-agnostic, first-write-wins
+ * `simpleKey(filePath, simpleName)`. That is safe while at most one callable in a file
+ * carries a given simple name — but #2699 deliberately creates function-locals that
+ * share a name with a file-level callable, and the local's graph node is keyed by
+ * position (`run.pick@1:2`) while the scope def is not. When the position join misses —
+ * the two id phases anchor on different nodes, so a multiline `const pick =` puts the
+ * declaration and its initializer on different lines — the simple-name fallback aliases
+ * the local onto whichever same-named callable was registered FIRST and mints a
+ * fabricated edge. That is the exact failure class #2693 already shipped once.
+ *
+ * This lets the resolver fail CLOSED for precisely that case and only that case: if a
+ * local of this name exists, a position miss is a genuine ambiguity rather than a lookup
+ * gap, so emitting no edge is correct. Files with no such local are untouched, which
+ * keeps legitimate anchor differences (e.g. a Vue SFC `lineOffset`) resolving through the
+ * name keys exactly as before.
+ */
+export declare function localNameKey(filePath: string, label: NodeLabel, name: string): string;
+/** Tombstone for a position claimed by two nodes — see `positionKey`. */
+export declare const AMBIGUOUS_POSITION = "";
 export declare function buildGraphNodeLookup(graph: KnowledgeGraph): GraphNodeLookup;
+/**
+ * Every label {@link buildGraphNodeLookup} registers — and therefore the ONLY
+ * labels `resolveDefGraphId` can ever return an id for. Both endpoints of every
+ * scope-resolution edge come from that lookup (the one exception is the File
+ * fallback in `resolveCallerGraphId`), so this set defines the whole FROM/TO
+ * surface those edges can produce.
+ *
+ * That makes it load-bearing for the LadybugDB relation DDL: a label added here
+ * without the matching `FROM x TO y` pairs in `RELATION_SCHEMA` crashes
+ * `analyze` at `assertDeclaredPair` on whichever codebase first emits the pair
+ * (#2792). `test/unit/schema-pair-coverage.test.ts` derives the required pairs
+ * from this set and fails in CI instead.
+ */
+export declare const LINKABLE_LABELS: ReadonlySet<NodeLabel>;
 export declare function isLinkableLabel(label: NodeLabel): boolean;

package/dist/core/ingestion/scope-resolution/graph-bridge/node-lookup.js

@@ -1,6 +1,6 @@
 /**
  * Build a `(filePath, name) → graphNodeId` lookup over the graph's
- * Function/Method/Class/Constructor nodes. Two keys per node:
+ * {@link LINKABLE_LABELS} definition nodes. Two keys per node:
  *
  *   - simple name (`User` / `save`) — legacy fallback
  *   - qualified name when derivable from the node id (`User.save`)
@@ -17,11 +17,11 @@
  * `SymbolDefinition.nodeId` values into the legacy graph-node ID
  * format that downstream consumers (queries, edges, MCP) expect.
  */
-import { isOverloadableCallable } from '../../utils/callable-labels.js';
+import { isOverloadableCallable, isPositionQualifiedLocalLabel, } from '../../utils/callable-labels.js';
 import { templateConstraintsIdTag } from '../../utils/template-arguments.js';
 import { parameterShapeIdTag } from '../../utils/method-props.js';
 /**
- * Parse a qualified name out of a Function/Method node id.
+ * Parse a qualified name out of a linkable graph-node id.
  *
  * Node id format: `${label}:${filePath}:${qualifiedName}${arityTag}`,
  * where `arityTag` is `#<n>` (or empty). Strips the known-length
@@ -59,6 +59,51 @@ export function qualifiedKey(filePath, label, qualifiedName) {
 export function simpleKey(filePath, name) {
     return `${filePath}::${name}`;
 }
+/**
+ * Position key: `(filePath, label, 0-based startLine, simple name)` (#2699).
+ *
+ * The strongest evidence there is, and the only one that needs no name
+ * qualification at all — a definition and its graph node are the same
+ * construct, so they share a source position. That makes it correct for
+ * exactly the cases a name-based key cannot express: a function-local
+ * declaration shadowing a file-level one, a local inside an ANONYMOUS
+ * function (no name to qualify with), and two same-named declarations in
+ * sibling blocks. ECMAScript gives each of those its own environment record;
+ * position is what distinguishes them without having to model the chain.
+ *
+ * Registered only for callable labels, and only when the (line, name) pair is
+ * unique in the file — a genuine tie (overloads declared on one line) stores
+ * the `AMBIGUOUS_POSITION` tombstone so the caller falls through to the
+ * name-based keys rather than picking by source order.
+ */
+export function positionKey(filePath, label, startLine, name) {
+    return `<p>:${filePath}::${label}::${startLine}::${name}`;
+}
+/**
+ * Key recording that a FUNCTION-LOCAL callable with this simple name exists in the
+ * file (#2699 follow-up).
+ *
+ * `resolveDefGraphId`'s last resort is a label-agnostic, first-write-wins
+ * `simpleKey(filePath, simpleName)`. That is safe while at most one callable in a file
+ * carries a given simple name — but #2699 deliberately creates function-locals that
+ * share a name with a file-level callable, and the local's graph node is keyed by
+ * position (`run.pick@1:2`) while the scope def is not. When the position join misses —
+ * the two id phases anchor on different nodes, so a multiline `const pick =` puts the
+ * declaration and its initializer on different lines — the simple-name fallback aliases
+ * the local onto whichever same-named callable was registered FIRST and mints a
+ * fabricated edge. That is the exact failure class #2693 already shipped once.
+ *
+ * This lets the resolver fail CLOSED for precisely that case and only that case: if a
+ * local of this name exists, a position miss is a genuine ambiguity rather than a lookup
+ * gap, so emitting no edge is correct. Files with no such local are untouched, which
+ * keeps legitimate anchor differences (e.g. a Vue SFC `lineOffset`) resolving through the
+ * name keys exactly as before.
+ */
+export function localNameKey(filePath, label, name) {
+    return `<l>:${filePath}::${label}::${name}`;
+}
+/** Tombstone for a position claimed by two nodes — see `positionKey`. */
+export const AMBIGUOUS_POSITION = '';
 export function buildGraphNodeLookup(graph) {
     const lookup = new Map();
     for (const node of graph.iterNodes()) {
@@ -67,6 +112,20 @@ export function buildGraphNodeLookup(graph) {
             continue;
         if (!isLinkableLabel(node.label))
             continue;
+        // Position key (#2699) — see `positionKey`. Second write on a key marks it
+        // ambiguous rather than letting source order decide.
+        const startLine = props.startLine;
+        if (startLine !== undefined && isPositionQualifiedLocalLabel(node.label)) {
+            const posK = positionKey(props.filePath, node.label, startLine, props.name);
+            lookup.set(posK, lookup.has(posK) ? AMBIGUOUS_POSITION : node.id);
+            // A local-identity node carries `@<row>:<col>` on its last name segment. Record
+            // that a local of this simple name exists, so the resolver can fail closed on a
+            // position miss instead of aliasing through the simple-name fallback.
+            const qualForLocal = parseQualifiedFromId(node.id, node.label, props.filePath);
+            if (qualForLocal !== undefined && /@\d+:\d+$/.test(qualForLocal)) {
+                lookup.set(localNameKey(props.filePath, node.label, props.name), node.id);
+            }
+        }
         // Primary key: fully-qualified name + label, in a separate
         // keyspace from simple names. Class nodes carry `qualifiedName`
         // in their properties (set by the parsing processor).
@@ -140,7 +199,7 @@ export function buildGraphNodeLookup(graph) {
                     lookup.set(tKey, node.id);
             }
         }
-        // Fallback key: simple name. First-wins within a file — used when
+        // Fallback key: simple name. Source-order first-wins within a file — used when
         // the caller doesn't know the qualifier (unqualified free-call
         // fallback, cross-file resolution where MethodRegistry already
         // disambiguated the owner).
@@ -150,33 +209,72 @@ export function buildGraphNodeLookup(graph) {
     }
     return lookup;
 }
+/**
+ * Every label {@link buildGraphNodeLookup} registers — and therefore the ONLY
+ * labels `resolveDefGraphId` can ever return an id for. Both endpoints of every
+ * scope-resolution edge come from that lookup (the one exception is the File
+ * fallback in `resolveCallerGraphId`), so this set defines the whole FROM/TO
+ * surface those edges can produce.
+ *
+ * That makes it load-bearing for the LadybugDB relation DDL: a label added here
+ * without the matching `FROM x TO y` pairs in `RELATION_SCHEMA` crashes
+ * `analyze` at `assertDeclaredPair` on whichever codebase first emits the pair
+ * (#2792). `test/unit/schema-pair-coverage.test.ts` derives the required pairs
+ * from this set and fails in CI instead.
+ */
+export const LINKABLE_LABELS = new Set([
+    'Function',
+    'Method',
+    'Constructor',
+    // Program-like module declarations are provider-gated callable-value
+    // targets and need the same def→graph bridge.
+    'Module',
+    'Class',
+    'Interface',
+    'Struct',
+    'Enum',
+    // Record participates in the same def→graph bridge as other class-like
+    // declarations. Without this entry, its qualified/template lookup branches
+    // are unreachable and label-agnostic fallback can alias it to a same-named
+    // Constructor or Method (#2801).
+    'Record',
+    // Trait nodes are linkable so MRO builders can bridge PHP/Rust trait
+    // defs between scope-resolution DefIds and the graph's node ids.
+    // IMPLEMENTS edges from classes to traits are otherwise invisible to
+    // the scope-resolution MRO pass.
+    'Trait',
+    // TypeAlias is linkable for the same reason Trait is (R2-2). The alias
+    // resolves fine — `CLASS_KINDS` has always listed it, and the ClassRegistry
+    // returns the def — but without an entry here `resolveDefGraphId` cannot
+    // bridge that def to its graph node, so the edge is dropped after a
+    // SUCCESSFUL lookup. That is why an exported contract type owned its members
+    // and still reported `incoming: {}`: the failure was one table away from
+    // everything that appeared to be responsible.
+    //
+    // Covers every language that spells an alias this way — TypeScript, Kotlin,
+    // Dart and Rust all emit `@declaration.type_alias`. The remaining
+    // `CLASS_KINDS` entries (Typedef, Record, Union, Delegate, Annotation,
+    // Template) plausibly have the same gap, but nothing exercises them today
+    // and adding labels no test covers is how this list drifts out of sync with
+    // what it claims.
+    'TypeAlias',
+    // Variable / Property are linkable too — receiver-bound write/read
+    // ACCESSES edges target field nodes (e.g. `user.name = "x"` →
+    // ACCESSES edge to User's `name` Variable/Property node).
+    'Variable',
+    'Property',
+    // Const is linkable so the value-receiver-owner bridge in
+    // `receiver-bound-calls.ts` Case 5 can translate the scope-resolution
+    // `Variable` def for `export const fooService = {...}` to the canonical
+    // `Const:filePath:name` graph node id, against which object-literal
+    // method symbols register their `ownerId` (PR #1718 / issue #1358).
+    'Const',
+    // Macro nodes are linkable so a macro invocation (`log!(…)`) resolved
+    // via `MacroRegistry` can bridge its scope-resolution `Macro` def to
+    // the legacy `@definition.macro` graph node and emit the `USES` edge
+    // (Rust #1934 F72; also covers C/C++ `#define` macro defs).
+    'Macro',
+]);
 export function isLinkableLabel(label) {
-    return (label === 'Function' ||
-        label === 'Method' ||
-        label === 'Constructor' ||
-        label === 'Class' ||
-        label === 'Interface' ||
-        label === 'Struct' ||
-        label === 'Enum' ||
-        // Trait nodes are linkable so MRO builders can bridge PHP/Rust trait
-        // defs between scope-resolution DefIds and the graph's node ids.
-        // IMPLEMENTS edges from classes to traits are otherwise invisible to
-        // the scope-resolution MRO pass.
-        label === 'Trait' ||
-        // Variable / Property are linkable too — receiver-bound write/read
-        // ACCESSES edges target field nodes (e.g. `user.name = "x"` →
-        // ACCESSES edge to User's `name` Variable/Property node).
-        label === 'Variable' ||
-        label === 'Property' ||
-        // Const is linkable so the value-receiver-owner bridge in
-        // `receiver-bound-calls.ts` Case 5 can translate the scope-resolution
-        // `Variable` def for `export const fooService = {...}` to the canonical
-        // `Const:filePath:name` graph node id, against which object-literal
-        // method symbols register their `ownerId` (PR #1718 / issue #1358).
-        label === 'Const' ||
-        // Macro nodes are linkable so a macro invocation (`log!(…)`) resolved
-        // via `MacroRegistry` can bridge its scope-resolution `Macro` def to
-        // the legacy `@definition.macro` graph node and emit the `USES` edge
-        // (Rust #1934 F72; also covers C/C++ `#define` macro defs).
-        label === 'Macro');
+    return LINKABLE_LABELS.has(label);
 }

package/dist/core/ingestion/scope-resolution/graph-bridge/references-to-edges.d.ts

@@ -30,13 +30,42 @@ import type { CalleeIdSink } from '../graph-bridge/callee-id-sink.js';
  * `${filePath}:${startLine}:${startCol}`.
  */
 type ReferenceSiteSkipSet = ReadonlySet<string>;
+/**
+ * Value labels whose defs MAY be function-local. A reference to one of these is
+ * dropped only when the def is positively identified as living inside a function
+ * body — see `functionLocalValueDefIds`. Everything else, including a class
+ * member in a language that keeps no values at module scope, is emitted.
+ */
 export declare function emitReferencesViaLookup(graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, referenceIndex: {
     readonly bySourceScope: ReadonlyMap<ScopeId, readonly Reference[]>;
 }, nodeLookup: GraphNodeLookup, skipSites?: ReferenceSiteSkipSet, 
 /** Resolved-callee-id capture sink (#2227 U2). Threaded in only under
  *  `--pdg`; `undefined` ⇒ zero overhead, byte-identity (R4). Captured at the
  *  CALLS emit below BEFORE this loop's `seen` dedup (KTD6/R8). */
-calleeIdSink?: CalleeIdSink): {
+calleeIdSink?: CalleeIdSink, 
+/**
+ * Def ids of value symbols bound inside a FUNCTION body. When supplied, a
+ * read/write whose target is a `Const`/`Variable`/`Static` in this set emits
+ * no edge.
+ *
+ * Bare-identifier reads (A2) made module-scope constants answerable, but the
+ * same capture also matches a read of a BLOCK-LOCAL `const`. An edge to one
+ * of those keeps alive precisely the inert local symbols `pruneLocalSymbols`
+ * exists to drop — turning a pruned node into a retained node plus an edge,
+ * in every function of every indexed repo. "Who uses this constant?" is a
+ * question about a module's surface; a local's uses are the three lines
+ * around it.
+ *
+ * A BLOCKLIST, not an allowlist, and the direction is the point. Asking
+ * "is this def module-level?" silently excludes class members — Java/C#
+ * fields, Python class attributes — which are neither module-level nor local.
+ * Asking "is this def function-local?" excludes only what it can positively
+ * identify, so an unrecognised or uninspected def is emitted. A stray inert
+ * local is recoverable; a deleted edge class reads as "nothing uses this".
+ *
+ * Optional so callers that never capture bare identifiers are unchanged.
+ */
+functionLocalValueDefIds?: ReadonlySet<string>): {
     emitted: number;
     skipped: number;
 };