gitnexus 1.6.10-rc.99 → 1.6.10

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

@@ -17,10 +17,11 @@
  * migrate.
  */
 import { generateId } from '../../../../lib/utils.js';
-import { qualifiedKey, simpleKey } from '../graph-bridge/node-lookup.js';
-import { isOverloadableCallable } from '../../utils/callable-labels.js';
+import { AMBIGUOUS_POSITION, exactPositionKey, localNameKey, positionKey, qualifiedKey, simpleKey, } from '../graph-bridge/node-lookup.js';
+import { isOverloadableCallable, isPositionQualifiedLocalLabel, } from '../../utils/callable-labels.js';
 import { templateConstraintsIdTag } from '../../utils/template-arguments.js';
 import { parameterShapeIdTag } from '../../utils/method-props.js';
+import { definitionIdPosition } from '../utils/definition-id.js';
 /**
  * Labels that may legitimately ANCHOR a CALLS/ACCESSES edge as the
  * source ("caller"). A Variable / Property can be the TARGET of an
@@ -40,15 +41,22 @@ import { parameterShapeIdTag } from '../../utils/method-props.js';
  * restricted to function/class-likes, those calls correctly fall
  * through to the File-node fallback at the bottom of the walk.
  */
+export const CALLER_ANCHOR_LABELS = new Set([
+    'Function',
+    'Method',
+    'Constructor',
+    'Module',
+    'Class',
+    'Interface',
+    'Struct',
+    'Enum',
+    // Record is class-like executable context for declaration initializers.
+    // Without this anchor, calls from Java static-field / C# property initializers
+    // fall through to File even though the canonical Record node is linkable.
+    'Record',
+]);
 function isCallerAnchorLabel(label) {
-    return (label === 'Function' ||
-        label === 'Method' ||
-        label === 'Constructor' ||
-        label === 'Module' ||
-        label === 'Class' ||
-        label === 'Interface' ||
-        label === 'Struct' ||
-        label === 'Enum');
+    return CALLER_ANCHOR_LABELS.has(label);
 }
 function rangeContainsPoint(range, at) {
     if (at.startLine < range.startLine || at.startLine > range.endLine)
@@ -59,21 +67,64 @@ function rangeContainsPoint(range, at) {
         return false;
     return true;
 }
+/**
+ * Adapter over the canonical {@link isOverloadableCallable} — deliberately NOT a
+ * second spelling of the label set. An earlier revision of this file inlined
+ * `Function | Method | Constructor` here, which recreated the exact twin-list
+ * drift this PR adds a guard test for elsewhere.
+ */
+const isCallableDef = (d) => isOverloadableCallable(d.type);
+/**
+ * True when `range` is the body of `def` itself — the scope's start position
+ * equals the def's declaration position.
+ *
+ * Safe to compare directly: `scope-extractor.ts` builds a def id as
+ * `def:<filePath>#<startLine>:<startCol>:<type>:<name>` from the same `Range`
+ * a scope carries, so both sides share one coordinate base and need no
+ * conversion. (Do not "fix" this against the 1-based reading in
+ * `defStartLine`'s docblock — what matters here is that the two sides agree
+ * with each other, not which base they use.)
+ */
+function scopeIsCallableBody(range, def) {
+    const position = definitionIdPosition(def.nodeId, def.filePath);
+    if (position === undefined)
+        return false;
+    return position.line === range.startLine && position.column === range.startCol;
+}
 /** Pick the callable that owns `atRange` when multiple overloads share a class scope. */
 function pickCallerCallableDef(scope, scopes, atRange) {
     if (atRange !== undefined) {
         for (const childId of scopes.scopeTree.getChildren(scope.id)) {
             const child = scopes.scopeTree.getScope(childId);
-            if (child === undefined || child.kind !== 'Function')
+            if (child === undefined)
                 continue;
             if (!rangeContainsPoint(child.range, atRange))
                 continue;
-            const childCallable = child.ownedDefs.find((d) => d.type === 'Function' || d.type === 'Method' || d.type === 'Constructor');
-            if (childCallable !== undefined)
-                return childCallable;
+            const childCallable = child.ownedDefs.find(isCallableDef);
+            if (childCallable === undefined)
+                continue;
+            if (child.kind === 'Function')
+                return { def: childCallable, fromChildScope: true };
+            // A Block-kind scope is a callable boundary ONLY when the scope IS that
+            // callable's own body. Kotlin `lambda_literal` and Ruby `do_block`/`block`
+            // are @scope.block deliberately (#1757 smart casts), so the kind gate
+            // alone would never let a closure there become a call SOURCE (#2699).
+            //
+            // But relaxing the gate to accept ANY Block owning a callable is wrong:
+            // a nested `fun foo()` declared inside a block is owned by that block, so
+            // a call made at BLOCK level — outside foo — would be misattributed to
+            // foo. The alignment test discriminates them. For a closure the
+            // declaration and the scope sit on the SAME node (the anchor discipline
+            // documented in javascript/query.ts), so their start positions match; for
+            // a nested function the block starts at `{` and the def starts at the
+            // declaration, so they do not.
+            if (child.kind === 'Block' && scopeIsCallableBody(child.range, childCallable)) {
+                return { def: childCallable, fromChildScope: true };
+            }
         }
     }
-    return scope.ownedDefs.find((d) => d.type === 'Function' || d.type === 'Method' || d.type === 'Constructor');
+    const own = scope.ownedDefs.find(isCallableDef);
+    return own === undefined ? undefined : { def: own, fromChildScope: false };
 }
 /**
  * Look up a `SymbolDefinition` in the graph node lookup.
@@ -92,11 +143,191 @@ function pickCallerCallableDef(scope, scopes, atRange) {
  * resolution working for languages that don't yet synthesize
  * qualifiers).
  */
+/**
+ * Trailing segment of a dotted qualified name (`Outer.inner` -> `inner`),
+ * with any function-local `@line:col` identity suffix stripped
+ * (`run.pick@5:10` -> `pick`).
+ *
+ * The graph node's `name` property is the bare source name, so the position
+ * key must compare against that — the position it carries is already the
+ * disambiguator, and leaving the suffix on would make every local miss.
+ */
+function simpleNameOf(qualifiedName) {
+    const dot = qualifiedName.lastIndexOf('.');
+    const tail = dot === -1 ? qualifiedName : qualifiedName.slice(dot + 1);
+    return tail.replace(LOCAL_IDENTITY_SUFFIX, '');
+}
+/**
+ * The function-local identity marker appended by `localIdentity` (`name@row:col`).
+ * Shared so the stripper above and the fail-closed guard in
+ * `resolveCallerGraphId` cannot disagree about what counts as a local.
+ */
+const LOCAL_IDENTITY_SUFFIX = /@\d+:\d+$/;
+/**
+ * The OTHER callable label the same construct may be registered under.
+ *
+ * A def and its graph node describe one construct, but they do not always agree
+ * on its LABEL: some structure phases emit a type's methods as `Function` nodes
+ * while the scope extractor derives `Method` from the `@declaration.method`
+ * anchor. Every key `resolveDefGraphId` builds is label-scoped, so such a pair
+ * misses ALL of them and lands on the label-agnostic, first-write-wins
+ * `simpleKey` at the bottom (#2807 follow-up, measured in Swift).
+ *
+ * ONE definition, consulted by all three key families — position, local-name
+ * guard, qualified — because they are not independent: leaving it out of the
+ * position key makes the fail-closed guard beside it UNREACHABLE for exactly the
+ * split the qualified retry serves, so the retry inherits a case the guard was
+ * written to stop (a function-local aliased onto a same-named class method).
+ * What each family may do with it differs and is documented at each site.
+ */
+function siblingCallableLabel(label) {
+    if (label === 'Method')
+        return 'Function';
+    if (label === 'Function')
+        return 'Method';
+    return undefined;
+}
 export function resolveDefGraphId(filePath, def, nodeLookup) {
     const qn = def.qualifiedName;
     if (qn === undefined || qn.length === 0)
         return undefined;
     if (def.type !== undefined) {
+        // ONE binding for all three key families — see `siblingCallableLabel`, which
+        // documents why they cannot be given independent answers. What each family
+        // is allowed to DO with it still differs, and is documented at each site.
+        const siblingLabel = siblingCallableLabel(def.type);
+        // Position key FIRST (#2699). A def and its graph node are the same
+        // construct, so they share a source line — the only evidence that
+        // separates a function-local declaration from a same-named file-level one
+        // without either side having to model the scope chain. Node ids are
+        // 0-based, def ids 1-based. An `AMBIGUOUS_POSITION` tombstone (two
+        // callables on one line) falls through to the name-based keys below.
+        //
+        // For a closure binding the two query channels still anchor on different
+        // AST nodes (outer wrapper vs inner callable), but the graph node's
+        // `startLine` follows the initializer (#2735) so this join matches even
+        // when the binding is split across lines.
+        const definitionPosition = definitionIdPosition(def.nodeId, filePath);
+        const line = definitionPosition?.line;
+        if (line !== undefined && isPositionQualifiedLocalLabel(def.type)) {
+            const simple = simpleNameOf(qn);
+            if (definitionPosition !== undefined) {
+                const exactHit = nodeLookup.get(exactPositionKey(filePath, def.type, definitionPosition.line - 1, definitionPosition.column));
+                if (exactHit !== undefined && exactHit !== AMBIGUOUS_POSITION)
+                    return exactHit;
+                if (exactHit === undefined && siblingLabel !== undefined) {
+                    const siblingExactHit = nodeLookup.get(exactPositionKey(filePath, siblingLabel, definitionPosition.line - 1, definitionPosition.column));
+                    if (siblingExactHit !== undefined && siblingExactHit !== AMBIGUOUS_POSITION) {
+                        return siblingExactHit;
+                    }
+                }
+            }
+            const posHit = nodeLookup.get(positionKey(filePath, def.type, line - 1, simple));
+            if (posHit !== undefined && posHit !== AMBIGUOUS_POSITION)
+                return posHit;
+            // Retry under the sibling callable label when the def's OWN label
+            // registered NOTHING here — see `siblingCallableLabel`. Both keys in this
+            // block are label-scoped, so under a split the position join misses and
+            // the guard below cannot fire, and the def falls through to the qualified
+            // retry that ends on the class method of the same name: a function-local
+            // `func helper` inside `Host.run` was aliased onto `Host.helper`, taking
+            // its calls with it, even at a different arity.
+            //
+            // Deliberately NOT dot-gated the way the qualified retry is: this key is
+            // not a name. `(file, line, simple name)` identifies one declaration by
+            // itself — that is why `positionKey` needs no qualifier at all — so
+            // crossing the two callable labels here cannot alias a top-level `save`
+            // onto a class's `save` the way a bare NAME would.
+            //
+            // Gated on `posHit === undefined` so an `AMBIGUOUS_POSITION` tombstone
+            // keeps meaning ambiguous: two callables already claim this line under the
+            // def's own label, and relabelling must not resolve by picking a third.
+            if (posHit === undefined && siblingLabel !== undefined) {
+                const siblingPosHit = nodeLookup.get(positionKey(filePath, siblingLabel, line - 1, simple));
+                if (siblingPosHit !== undefined && siblingPosHit !== AMBIGUOUS_POSITION) {
+                    return siblingPosHit;
+                }
+            }
+            // FAIL CLOSED when a function-local of this name exists in the file (#2699
+            // follow-up). Falling through to the name keys would end at the label-agnostic,
+            // first-write-wins `simpleKey` below and alias this def onto whichever same-named
+            // callable was registered first — reproducibly minting a FALSE edge. A missing
+            // edge is the correct failure direction for a graph whose consumers include
+            // `impact`; a fabricated caller is not. Gated on `localNameKey` so this ONLY
+            // fires where the collision is real — a file with no such local keeps its
+            // previous fallback behaviour, which is what preserves legitimate anchor
+            // differences such as a Vue SFC's `lineOffset`.
+            //
+            // Multi-line closure bindings are NOT this case anymore (#2735): their graph
+            // `startLine` follows the initializer, so the position key above hits.
+            if (nodeLookup.get(localNameKey(filePath, def.type, simple)) !== undefined) {
+                return undefined;
+            }
+            // Same guard under the sibling label: a local the structure phase
+            // registered as `Function` must still stop a `Method`-labelled def of that
+            // name from reaching `simpleKey`, or the split re-opens the fabricated
+            // edge this guard exists to close. Unlike the position retry above this
+            // arm is NOT conditioned on the own-label lookup missing — it only ever
+            // returns `undefined`, and a missing edge is the correct failure
+            // direction; declining to check would be the risky choice, not this.
+            if (siblingLabel !== undefined &&
+                nodeLookup.get(localNameKey(filePath, siblingLabel, simple)) !== undefined) {
+                return undefined;
+            }
+        }
+        // Name forms to try for every keyed lookup below, most specific first.
+        //
+        // #1982/#2742: some scope-extractors qualify a def by its enclosing CLASS
+        // chain (`A.Inner`) or leave it a bare tail, while the structure-phase node is
+        // keyed by the full path (`NS.A.Inner`, or a Rust `mod` chain). The
+        // namespace-prefixed form is therefore the more specific one and must be tried
+        // first — the bare form happily matches a same-named item at a DIFFERENT
+        // namespace depth in the same file and returns it before any retry is reached
+        // (#2742: a call into `mod inner { fn dispatch }` bound to the crate-root
+        // `fn dispatch` and rendered as a self-loop).
+        //
+        // Applied to the TAGGED keys too, not just the plain one. Previously only the
+        // plain key had the prefixed retry, so for a namespace/mod-qualified def every
+        // tagged key — constraints, parameter types, parameter shape, arity, template
+        // arguments — composed from the bare tail and simply missed the node
+        // `node-lookup.ts` had registered under the qualified name. Those keys exist to
+        // separate overloads, so leaving them dead meant a mod-scoped overload set
+        // depended on whichever later key happened to catch it.
+        const defType = def.type;
+        const nsPrefix = def.namespacePrefix;
+        const nameForms = nsPrefix !== undefined && nsPrefix.length > 0 ? [`${nsPrefix}.${qn}`, qn] : [qn];
+        // The label split described on `siblingCallableLabel` also kills every key
+        // above: they are all label-scoped, so a split pair misses all of them and
+        // lands on the label-agnostic simple key at the bottom of this function —
+        // which is first-write-wins, so two same-named methods in ONE file both
+        // resolved to whichever was registered first. That silently misattributed
+        // every call in the second method's body to the first (#2807 follow-up;
+        // measured in Swift, where `class A { func run }` + `class B { func run }`
+        // gave A.run both bodies' edges and B.run none).
+        //
+        // Crossing the two callable labels is sound HERE only for a name that
+        // carries its owner: `A.run` names exactly one construct whatever the
+        // label, while a bare `run` is precisely the aliasing the label was added
+        // to prevent (a top-level `save` vs a class's `save`). Hence the dot gate —
+        // it keeps the original guarantee intact for unqualified names. The
+        // position key above needs no such gate because it is not a name.
+        const lookupTagged = (tag) => {
+            for (const form of nameForms) {
+                const hit = nodeLookup.get(qualifiedKey(filePath, defType, `${form}${tag}`));
+                if (hit !== undefined)
+                    return hit;
+            }
+            if (siblingLabel === undefined)
+                return undefined;
+            for (const form of nameForms) {
+                if (!form.includes('.'))
+                    continue;
+                const hit = nodeLookup.get(qualifiedKey(filePath, siblingLabel, `${form}${tag}`));
+                if (hit !== undefined)
+                    return hit;
+            }
+            return undefined;
+        };
         // SFINAE / `requires`-clause disambiguation (issue #1579) — try the
         // constraint-fingerprinted key FIRST. Two function-template overloads
         // with identical `parameterTypes` but mutually-exclusive SFINAE
@@ -105,8 +336,7 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
         // share the latter.
         if ((def.type === 'Function' || def.type === 'Method') &&
             def.templateConstraints !== undefined) {
-            const cKey = qualifiedKey(filePath, def.type, `${qn}${templateConstraintsIdTag(def.templateConstraints)}`);
-            const cHit = nodeLookup.get(cKey);
+            const cHit = lookupTagged(templateConstraintsIdTag(def.templateConstraints));
             if (cHit !== undefined)
                 return cHit;
         }
@@ -115,8 +345,7 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
             def.parameterTypeClasses !== undefined) {
             const shapeTag = parameterShapeIdTag(def.parameterTypes, def.parameterTypeClasses);
             if (shapeTag !== '') {
-                const shapeKey = qualifiedKey(filePath, def.type, `${qn}${shapeTag}`);
-                const shapeHit = nodeLookup.get(shapeKey);
+                const shapeHit = lookupTagged(shapeTag);
                 if (shapeHit !== undefined)
                     return shapeHit;
             }
@@ -131,8 +360,7 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
         if (isOverloadableCallable(def.type) &&
             def.parameterTypes !== undefined &&
             def.parameterTypes.length > 0) {
-            const pKey = qualifiedKey(filePath, def.type, `${qn}~${def.parameterTypes.join(',')}`);
-            const pHit = nodeLookup.get(pKey);
+            const pHit = lookupTagged(`~${def.parameterTypes.join(',')}`);
             if (pHit !== undefined)
                 return pHit;
         }
@@ -141,8 +369,7 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
         // zero-arg overload (no parameterTypes) that would otherwise collapse onto a
         // sibling overload via the source-order-dependent qualified key.
         if (isOverloadableCallable(def.type) && def.parameterCount !== undefined) {
-            const aKey = qualifiedKey(filePath, def.type, `${qn}#${def.parameterCount}`);
-            const aHit = nodeLookup.get(aKey);
+            const aHit = lookupTagged(`#${def.parameterCount}`);
             if (aHit !== undefined)
                 return aHit;
         }
@@ -153,26 +380,13 @@ export function resolveDefGraphId(filePath, def, nodeLookup) {
             def.type === 'Record') &&
             def.templateArguments !== undefined &&
             def.templateArguments.length > 0) {
-            const tKey = qualifiedKey(filePath, def.type, `${qn}~${def.templateArguments.join(',')}`);
-            const tHit = nodeLookup.get(tKey);
+            const tHit = lookupTagged(`~${def.templateArguments.join(',')}`);
             if (tHit !== undefined)
                 return tHit;
         }
-        const qualifiedHit = nodeLookup.get(qualifiedKey(filePath, def.type, qn));
+        const qualifiedHit = lookupTagged('');
         if (qualifiedHit !== undefined)
             return qualifiedHit;
-        // #1982: some scope-extractors qualify a type by its enclosing CLASS chain
-        // (`A.Inner`) but drop the enclosing NAMESPACE, while the structure-phase
-        // node is keyed by the full path (`NS.A.Inner`). Retry with the
-        // namespace-prefixed key (tagged by `tagNamespacePrefixes`) BEFORE the
-        // simple-name fallback, so same-tail nested bases don't collapse across
-        // sibling namespace members via `simpleKey`.
-        const nsPrefix = def.namespacePrefix;
-        if (nsPrefix !== undefined && nsPrefix.length > 0) {
-            const nsHit = nodeLookup.get(qualifiedKey(filePath, def.type, `${nsPrefix}.${qn}`));
-            if (nsHit !== undefined)
-                return nsHit;
-        }
     }
     const simpleName = qn.lastIndexOf('.') === -1 ? qn : qn.slice(qn.lastIndexOf('.') + 1);
     return nodeLookup.get(simpleKey(filePath, simpleName));
@@ -187,7 +401,7 @@ export function simpleQualifiedName(def) {
 }
 /**
  * Walk the scope chain from `startScope` upward looking for the first
- * scope whose `ownedDefs` contains a Function/Method/Class — that's
+ * scope whose `ownedDefs` contains a callable or class-like anchor — that's
  * our caller anchor. Translate via `nodeLookup` to the graph-node ID.
  *
  * Module-level references (e.g. Python `u = models.User()` at top
@@ -209,13 +423,37 @@ export function resolveCallerGraphId(startScope, scopes, nodeLookup, atRange) {
             break;
         lastFilePath = scope.filePath;
         // Prefer Function/Method/Constructor anchors; fall back to
-        // Class/Interface/Struct/Enum. Variable/Property are NOT valid
+        // Class/Interface/Struct/Enum/Record. Variable/Property are NOT valid
         // caller anchors — see `isCallerAnchorLabel` for why.
-        const fnDef = pickCallerCallableDef(scope, scopes, atRange);
-        if (fnDef !== undefined) {
+        const picked = pickCallerCallableDef(scope, scopes, atRange);
+        if (picked !== undefined) {
+            const fnDef = picked.def;
             const id = resolveDefGraphId(fnDef.filePath, fnDef, nodeLookup);
             if (id !== undefined)
                 return id;
+            // FAIL CLOSED at a FUNCTION-LOCAL boundary (#2699 review P1-1).
+            //
+            // `fnDef` is the callable that genuinely owns this call site. When its
+            // graph node cannot be named, climbing to the parent scope does not
+            // degrade gracefully — it ATTRIBUTES THE CALL TO A FUNCTION THAT DOES NOT
+            // MAKE IT. Measured before this guard, a closure whose literal starts on
+            // the line after its binding
+            //     $multi =
+            //         function ($x) { return target($x); };
+            // emitted `outer -> target` while the real `outer.$multi` node sat with no
+            // outgoing edges: a CALLS edge present nowhere in the source, which is the
+            // exact defect class #2699 exists to remove.
+            //
+            // Restricted to defs carrying the function-local `@line:col` identity,
+            // because that is precisely the set whose position join can miss (the two
+            // query channels anchor on different nodes by design). For every other
+            // callable the historical climb is preserved, so this cannot silently
+            // delete edges outside the local-identity path.
+            // The scope we are standing in OWNS this call site and we have identified
+            // its callable — we simply cannot name that callable's graph node. Climbing
+            // to an ancestor here does not degrade gracefully: it credits the call to a
+            // function that does not make it. Fail closed instead.
+            return undefined;
         }
         const classDef = scope.ownedDefs.find((d) => isCallerAnchorLabel(d.type));
         if (classDef !== undefined) {

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;