gitnexus 1.6.3-rc.8 → 1.6.3

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

@@ -0,0 +1,79 @@
+/**
+ * Graph edge emission primitives.
+ *
+ * Two functions:
+ *   - `mapReferenceKindToEdgeType` — translate a scope-resolution
+ *     `Reference.kind` into the corresponding graph edge type.
+ *   - `tryEmitEdge` — given a reference site + target def, resolve
+ *     caller + target to graph ids and emit the edge with
+ *     language-provided reason text, dedup-keyed by
+ *     `(edgeType, callerId, targetId, line, col)`.
+ *
+ * Next-consumer contract: any language provider can call `tryEmitEdge`
+ * from its own post-pass to emit edges it resolves Python-specific
+ * (or TypeScript-specific, etc.) logic. The dedup key is
+ * language-agnostic — no language needs to change it.
+ */
+import { resolveCallerGraphId, resolveDefGraphId } from '../graph-bridge/ids.js';
+/**
+ * Map a `Reference.kind` to a graph edge type. `import-use` is dropped
+ * (no edge type today — provenance lives on the IMPORTS edge emitted
+ * by `emitImportEdges`).
+ */
+export function mapReferenceKindToEdgeType(kind) {
+    switch (kind) {
+        case 'call':
+            return 'CALLS';
+        case 'read':
+        case 'write':
+            return 'ACCESSES';
+        case 'inherits':
+            return 'EXTENDS';
+        case 'type-reference':
+            return 'USES';
+        case 'import-use':
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Resolve caller + target to graph ids and emit the edge. Returns true
+ * if the edge was emitted (not deduped, not skipped).
+ *
+ * `seen` is a language-shared dedup set keyed by
+ * `${edgeType}:${callerGraphId}->${targetGraphId}:${line}:${col}` so
+ * multiple language-specific post-passes can share it and never
+ * double-emit a resolution one of them already produced.
+ */
+export function tryEmitEdge(graph, scopes, nodeLookup, site, targetDef, reason, seen, confidence = 0.85, collapseByCallerTarget = false) {
+    const callerGraphId = resolveCallerGraphId(site.inScope, scopes, nodeLookup);
+    const targetGraphId = resolveDefGraphId(targetDef.filePath, targetDef, nodeLookup);
+    const edgeType = mapReferenceKindToEdgeType(site.kind);
+    if (callerGraphId === undefined)
+        return false;
+    if (targetGraphId === undefined)
+        return false;
+    if (edgeType === undefined)
+        return false;
+    // CALLS edges may collapse to `(caller, target)` granularity when
+    // the provider opts in (C# matches legacy DAG behavior this way).
+    // Write/read ACCESSES keep per-site dedup so multiple writes to the
+    // same field on different lines produce distinct edges.
+    const useCollapsed = collapseByCallerTarget && edgeType === 'CALLS';
+    const dedupKey = useCollapsed
+        ? `${edgeType}:${callerGraphId}->${targetGraphId}`
+        : `${edgeType}:${callerGraphId}->${targetGraphId}:${site.atRange.startLine}:${site.atRange.startCol}`;
+    if (seen.has(dedupKey))
+        return false;
+    seen.add(dedupKey);
+    graph.addRelationship({
+        id: `rel:${dedupKey}`,
+        sourceId: callerGraphId,
+        targetId: targetGraphId,
+        type: edgeType,
+        confidence,
+        reason,
+    });
+    return true;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Scope-resolution → legacy graph-node ID bridging.
+ *
+ * Two functions:
+ *   - `resolveDefGraphId` — turn a scope-resolution `SymbolDefinition`
+ *     into the graph's node id for the corresponding legacy node.
+ *   - `resolveCallerGraphId` — walk a scope chain from a reference
+ *     site upward to find the enclosing function/method/class and
+ *     return its graph-node id. Falls back to the File node for
+ *     module-level calls so those still get an edge source.
+ *
+ * Next-consumer contract: language-agnostic. Any OO language with
+ * file-level module semantics (TypeScript, Java, Go, Kotlin) can
+ * reuse `resolveCallerGraphId` as-is. Languages with different
+ * top-level semantics (COBOL programs, Rust crate modules) may want
+ * a different file-level fallback — cross that bridge when they
+ * migrate.
+ */
+import type { NodeLabel, ScopeId, SymbolDefinition } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import { type GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+/**
+ * Look up a `SymbolDefinition` in the graph node lookup.
+ *
+ * Tries the type-prefixed fully-qualified key FIRST. That's the only
+ * correct key when:
+ *   - Two classes in the same file define a method with the same
+ *     simple name (`class User: def save` + `class Document: def save`).
+ *   - A top-level function and a class method share a simple name
+ *     (`def save` + `class User: def save` — the Function's qualifier
+ *     is just `save`, which would alias the Method's simple-key slot
+ *     without the type prefix).
+ *
+ * Falls back to the simple name for definitions whose qualifier the
+ * lookup didn't capture (rare, but keeps cross-file simple-name
+ * resolution working for languages that don't yet synthesize
+ * qualifiers).
+ */
+export declare function resolveDefGraphId(filePath: string, def: {
+    qualifiedName?: string;
+    type?: NodeLabel;
+    parameterTypes?: readonly string[];
+}, nodeLookup: GraphNodeLookup): string | undefined;
+/** Derive the simple (unqualified) name of a def from its `qualifiedName`. */
+export declare function simpleQualifiedName(def: SymbolDefinition): string | undefined;
+/**
+ * Walk the scope chain from `startScope` upward looking for the first
+ * scope whose `ownedDefs` contains a Function/Method/Class — that's
+ * our caller anchor. Translate via `nodeLookup` to the graph-node ID.
+ *
+ * Module-level references (e.g. Python `u = models.User()` at top
+ * level) have no enclosing function/method/class. Fall back to the
+ * File node for the scope's filePath so those calls still get an
+ * edge source. Matches legacy DAG behavior where module-level CALLS
+ * edges originate from the file symbol.
+ */
+export declare function resolveCallerGraphId(startScope: ScopeId, scopes: ScopeResolutionIndexes, nodeLookup: GraphNodeLookup): string | undefined;

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

@@ -0,0 +1,112 @@
+/**
+ * Scope-resolution → legacy graph-node ID bridging.
+ *
+ * Two functions:
+ *   - `resolveDefGraphId` — turn a scope-resolution `SymbolDefinition`
+ *     into the graph's node id for the corresponding legacy node.
+ *   - `resolveCallerGraphId` — walk a scope chain from a reference
+ *     site upward to find the enclosing function/method/class and
+ *     return its graph-node id. Falls back to the File node for
+ *     module-level calls so those still get an edge source.
+ *
+ * Next-consumer contract: language-agnostic. Any OO language with
+ * file-level module semantics (TypeScript, Java, Go, Kotlin) can
+ * reuse `resolveCallerGraphId` as-is. Languages with different
+ * top-level semantics (COBOL programs, Rust crate modules) may want
+ * a different file-level fallback — cross that bridge when they
+ * migrate.
+ */
+import { generateId } from '../../../../lib/utils.js';
+import { isLinkableLabel, qualifiedKey, simpleKey, } from '../graph-bridge/node-lookup.js';
+/**
+ * Look up a `SymbolDefinition` in the graph node lookup.
+ *
+ * Tries the type-prefixed fully-qualified key FIRST. That's the only
+ * correct key when:
+ *   - Two classes in the same file define a method with the same
+ *     simple name (`class User: def save` + `class Document: def save`).
+ *   - A top-level function and a class method share a simple name
+ *     (`def save` + `class User: def save` — the Function's qualifier
+ *     is just `save`, which would alias the Method's simple-key slot
+ *     without the type prefix).
+ *
+ * Falls back to the simple name for definitions whose qualifier the
+ * lookup didn't capture (rare, but keeps cross-file simple-name
+ * resolution working for languages that don't yet synthesize
+ * qualifiers).
+ */
+export function resolveDefGraphId(filePath, def, nodeLookup) {
+    const qn = def.qualifiedName;
+    if (qn === undefined || qn.length === 0)
+        return undefined;
+    if (def.type !== undefined) {
+        // Overload disambiguation: when the def carries parameter types,
+        // try the parameter-typed key first so same-name same-arity
+        // overloads route to their distinct graph nodes.
+        if (def.type === 'Method' &&
+            def.parameterTypes !== undefined &&
+            def.parameterTypes.length > 0) {
+            const pKey = qualifiedKey(filePath, def.type, `${qn}~${def.parameterTypes.join(',')}`);
+            const pHit = nodeLookup.get(pKey);
+            if (pHit !== undefined)
+                return pHit;
+        }
+        const qualifiedHit = nodeLookup.get(qualifiedKey(filePath, def.type, qn));
+        if (qualifiedHit !== undefined)
+            return qualifiedHit;
+    }
+    const simpleName = qn.lastIndexOf('.') === -1 ? qn : qn.slice(qn.lastIndexOf('.') + 1);
+    return nodeLookup.get(simpleKey(filePath, simpleName));
+}
+/** Derive the simple (unqualified) name of a def from its `qualifiedName`. */
+export function simpleQualifiedName(def) {
+    const q = def.qualifiedName;
+    if (q === undefined || q.length === 0)
+        return undefined;
+    const dot = q.lastIndexOf('.');
+    return dot === -1 ? q : q.slice(dot + 1);
+}
+/**
+ * Walk the scope chain from `startScope` upward looking for the first
+ * scope whose `ownedDefs` contains a Function/Method/Class — that's
+ * our caller anchor. Translate via `nodeLookup` to the graph-node ID.
+ *
+ * Module-level references (e.g. Python `u = models.User()` at top
+ * level) have no enclosing function/method/class. Fall back to the
+ * File node for the scope's filePath so those calls still get an
+ * edge source. Matches legacy DAG behavior where module-level CALLS
+ * edges originate from the file symbol.
+ */
+export function resolveCallerGraphId(startScope, scopes, nodeLookup) {
+    let current = startScope;
+    const visited = new Set();
+    let lastFilePath;
+    while (current !== null) {
+        if (visited.has(current))
+            return undefined;
+        visited.add(current);
+        const scope = scopes.scopeTree.getScope(current);
+        if (scope === undefined)
+            break;
+        lastFilePath = scope.filePath;
+        // Prefer Function/Method anchors; fall back to Class.
+        const fnDef = scope.ownedDefs.find((d) => d.type === 'Function' || d.type === 'Method' || d.type === 'Constructor');
+        if (fnDef !== undefined) {
+            const id = resolveDefGraphId(scope.filePath, fnDef, nodeLookup);
+            if (id !== undefined)
+                return id;
+        }
+        const classDef = scope.ownedDefs.find((d) => isLinkableLabel(d.type));
+        if (classDef !== undefined) {
+            const id = resolveDefGraphId(scope.filePath, classDef, nodeLookup);
+            if (id !== undefined)
+                return id;
+        }
+        current = scope.parent;
+    }
+    // Module-level calls — fall back to the File node for the scope's filePath.
+    if (lastFilePath !== undefined) {
+        return generateId('File', lastFilePath);
+    }
+    return undefined;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * File→File IMPORTS edge emission from a finalized `ImportEdge` map.
+ *
+ * Deduplicates by `(sourceFile, targetFile)` so multi-symbol imports
+ * from the same module collapse to a single edge — matching the
+ * legacy schema.
+ *
+ * Next-consumer contract: language-agnostic. Any provider with a
+ * scope-resolution ImportEdge stream emits File→File edges via this
+ * single function. The `reason` defaults to
+ * `'scope-resolution: import'`; provider may override if downstream
+ * filters on reason.
+ */
+import type { ImportEdge, ScopeId } from '../../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../../graph/types.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+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

@@ -0,0 +1,46 @@
+/**
+ * File→File IMPORTS edge emission from a finalized `ImportEdge` map.
+ *
+ * Deduplicates by `(sourceFile, targetFile)` so multi-symbol imports
+ * from the same module collapse to a single edge — matching the
+ * legacy schema.
+ *
+ * Next-consumer contract: language-agnostic. Any provider with a
+ * scope-resolution ImportEdge stream emits File→File edges via this
+ * single function. The `reason` defaults to
+ * `'scope-resolution: import'`; provider may override if downstream
+ * filters on reason.
+ */
+import { generateId } from '../../../../lib/utils.js';
+export function emitImportEdges(graph, imports, scopeTree, reason = 'scope-resolution: import') {
+    const seen = new Set();
+    let emitted = 0;
+    for (const [scopeId, edges] of imports) {
+        const scope = scopeTree.getScope(scopeId);
+        if (scope === undefined)
+            continue;
+        const sourceFile = scope.filePath;
+        for (const edge of edges) {
+            if (edge.targetFile === null)
+                continue;
+            if (edge.targetFile === sourceFile)
+                continue;
+            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++;
+        }
+    }
+    return emitted;
+}

package/dist/core/ingestion/scope-resolution/graph-bridge/method-dispatch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Wrap a `DefId → ancestor DefId[]` MRO map in the shared
+ * `MethodDispatchIndex` shape so it slots into
+ * `ScopeResolutionIndexes.methodDispatch`.
+ *
+ * `finalizeScopeModel` builds an empty `MethodDispatchIndex` by design
+ * (per the comment in `finalize-orchestrator.ts`). Per-language
+ * providers compute MRO their own way (Python C3 walk, Java class
+ * hierarchy, Ruby mixin chains, etc.) and use this bridge to plug the
+ * result back into the shared index shape.
+ *
+ * Next-consumer contract: any language that computes its own MRO map
+ * calls `buildPopulatedMethodDispatch(mroByOwnerDefId)` and assigns the
+ * result to `indexes.methodDispatch`. Interface-implementer tracking
+ * (`implsByInterfaceDefId`) stays empty in V1 — providers that need it
+ * can extend the return shape without breaking existing consumers.
+ */
+import type { MethodDispatchIndex } from '../../../../_shared/index.js';
+export declare function buildPopulatedMethodDispatch(mroByDefId: ReadonlyMap<string, readonly string[]>): MethodDispatchIndex;

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

@@ -0,0 +1,30 @@
+/**
+ * Wrap a `DefId → ancestor DefId[]` MRO map in the shared
+ * `MethodDispatchIndex` shape so it slots into
+ * `ScopeResolutionIndexes.methodDispatch`.
+ *
+ * `finalizeScopeModel` builds an empty `MethodDispatchIndex` by design
+ * (per the comment in `finalize-orchestrator.ts`). Per-language
+ * providers compute MRO their own way (Python C3 walk, Java class
+ * hierarchy, Ruby mixin chains, etc.) and use this bridge to plug the
+ * result back into the shared index shape.
+ *
+ * Next-consumer contract: any language that computes its own MRO map
+ * calls `buildPopulatedMethodDispatch(mroByOwnerDefId)` and assigns the
+ * result to `indexes.methodDispatch`. Interface-implementer tracking
+ * (`implsByInterfaceDefId`) stays empty in V1 — providers that need it
+ * can extend the return shape without breaking existing consumers.
+ */
+const EMPTY_DEFS = Object.freeze([]);
+export function buildPopulatedMethodDispatch(mroByDefId) {
+    return {
+        mroByOwnerDefId: mroByDefId,
+        implsByInterfaceDefId: new Map(),
+        mroFor(ownerDefId) {
+            return mroByDefId.get(ownerDefId) ?? EMPTY_DEFS;
+        },
+        implementorsOf() {
+            return EMPTY_DEFS;
+        },
+    };
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Build a `(filePath, name) → graphNodeId` lookup over the graph's
+ * Function/Method/Class/Constructor nodes. Two keys per node:
+ *
+ *   - simple name (`User` / `save`) — legacy fallback
+ *   - qualified name when derivable from the node id (`User.save`)
+ *
+ * The qualified key is the authoritative one when two classes in the
+ * same file define a method with the same simple name
+ * (`class User: def save` + `class Document: def save`). Without it,
+ * the simple-name key collides and every `document.save()` CALLS edge
+ * would silently target `User.save`. Method node ids encode the
+ * qualifier (`Method:file.py:User.save#1`), so we parse it back out.
+ *
+ * Language-agnostic seam. Any language provider migrating to the
+ * registry-primary path can consume this to translate scope-resolution
+ * `SymbolDefinition.nodeId` values into the legacy graph-node ID
+ * format that downstream consumers (queries, edges, MCP) expect.
+ */
+import type { NodeLabel } from '../../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../../graph/types.js';
+export type GraphNodeLookup = ReadonlyMap<string, string>;
+/**
+ * Build a qualified-key string in a separate keyspace from simple-key
+ * strings. Prefix `<q>` can't appear in a valid filePath on any OS, so
+ * no collision between the two keyspaces is possible.
+ *
+ * Includes the node label so a top-level `def save` (Function,
+ * qualifier = `save`) doesn't alias a class method `User.save` (Method,
+ * simple name = `save`) whose Function-typed qualifier would collapse
+ * to the same simple-key slot in a single map.
+ */
+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;
+export declare function buildGraphNodeLookup(graph: KnowledgeGraph): GraphNodeLookup;
+export declare function isLinkableLabel(label: NodeLabel): boolean;

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

@@ -0,0 +1,113 @@
+/**
+ * Build a `(filePath, name) → graphNodeId` lookup over the graph's
+ * Function/Method/Class/Constructor nodes. Two keys per node:
+ *
+ *   - simple name (`User` / `save`) — legacy fallback
+ *   - qualified name when derivable from the node id (`User.save`)
+ *
+ * The qualified key is the authoritative one when two classes in the
+ * same file define a method with the same simple name
+ * (`class User: def save` + `class Document: def save`). Without it,
+ * the simple-name key collides and every `document.save()` CALLS edge
+ * would silently target `User.save`. Method node ids encode the
+ * qualifier (`Method:file.py:User.save#1`), so we parse it back out.
+ *
+ * Language-agnostic seam. Any language provider migrating to the
+ * registry-primary path can consume this to translate scope-resolution
+ * `SymbolDefinition.nodeId` values into the legacy graph-node ID
+ * format that downstream consumers (queries, edges, MCP) expect.
+ */
+/**
+ * Parse a qualified name out of a Function/Method node id.
+ *
+ * Node id format: `${label}:${filePath}:${qualifiedName}${arityTag}`,
+ * where `arityTag` is `#<n>` (or empty). Strips the known-length
+ * label + filePath prefix so colons inside `filePath` (Windows
+ * `C:\...`) don't break the parse. Returns `undefined` when the id
+ * doesn't match the expected shape.
+ */
+function parseQualifiedFromId(id, label, filePath) {
+    const prefix = `${label}:${filePath}:`;
+    if (!id.startsWith(prefix))
+        return undefined;
+    const suffix = id.slice(prefix.length);
+    if (suffix.length === 0)
+        return undefined;
+    const hash = suffix.indexOf('#');
+    return hash === -1 ? suffix : suffix.slice(0, hash);
+}
+/**
+ * Build a qualified-key string in a separate keyspace from simple-key
+ * strings. Prefix `<q>` can't appear in a valid filePath on any OS, so
+ * no collision between the two keyspaces is possible.
+ *
+ * Includes the node label so a top-level `def save` (Function,
+ * qualifier = `save`) doesn't alias a class method `User.save` (Method,
+ * simple name = `save`) whose Function-typed qualifier would collapse
+ * to the same simple-key slot in a single map.
+ */
+export function qualifiedKey(filePath, label, qualifiedName) {
+    return `<q>:${filePath}::${label}::${qualifiedName}`;
+}
+/** Simple-name key (legacy fallback keyspace — no `<q>` prefix). */
+export function simpleKey(filePath, name) {
+    return `${filePath}::${name}`;
+}
+export function buildGraphNodeLookup(graph) {
+    const lookup = new Map();
+    for (const node of graph.iterNodes()) {
+        const props = node.properties;
+        if (props.filePath === undefined || props.name === undefined)
+            continue;
+        if (!isLinkableLabel(node.label))
+            continue;
+        // 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).
+        // Method/Function nodes do not, so derive the qualifier from the
+        // node id — that's where the parse-phase encoded it. Including
+        // the label avoids a collision when a free Function's qualifier
+        // happens to equal a Method's simple name (e.g. top-level
+        // `def save` vs `class User: def save`).
+        const qualified = props.qualifiedName ?? parseQualifiedFromId(node.id, node.label, props.filePath);
+        if (qualified !== undefined && qualified.length > 0) {
+            const qKey = qualifiedKey(props.filePath, node.label, qualified);
+            if (!lookup.has(qKey))
+                lookup.set(qKey, node.id);
+            // Overload-disambiguating key: include parameter types so two
+            // same-arity overloads (e.g. `Lookup(int)` vs `Lookup(string)`)
+            // map to distinct graph nodes. Legacy parse-phase encodes the
+            // type tag into the node id; we register both that node id and
+            // a parameter-types-suffixed key so resolveDefGraphId can find
+            // the right overload by matching its def's parameterTypes.
+            const pTypes = props.parameterTypes;
+            if (pTypes !== undefined && pTypes.length > 0 && node.label === 'Method') {
+                const pKey = qualifiedKey(props.filePath, node.label, `${qualified}~${pTypes.join(',')}`);
+                // Each overload is unique — set unconditionally.
+                lookup.set(pKey, node.id);
+            }
+        }
+        // Fallback key: simple name. 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).
+        const sKey = simpleKey(props.filePath, props.name);
+        if (!lookup.has(sKey))
+            lookup.set(sKey, node.id);
+    }
+    return lookup;
+}
+export function isLinkableLabel(label) {
+    return (label === 'Function' ||
+        label === 'Method' ||
+        label === 'Constructor' ||
+        label === 'Class' ||
+        label === 'Interface' ||
+        label === 'Struct' ||
+        label === 'Enum' ||
+        // 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');
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Translate the resolved `ReferenceIndex` into legacy graph edges.
+ *
+ * Per reference:
+ *   1. Resolve `fromScope` → caller graph-node id by walking the scope
+ *      chain looking for an enclosing Function/Method/Class.
+ *   2. Resolve `toDef` → target graph-node id via `nodeLookup`.
+ *   3. Emit the edge (`CALLS` / `READS` / `WRITES` / `EXTENDS` / `USES`)
+ *      with the standard reason format.
+ *
+ * Skips (without throwing) when either side fails to map — either side
+ * may legitimately not exist as a graph node (e.g. a resolved target
+ * lives in an external file that wasn't ingested into the graph).
+ *
+ * Next-consumer contract: this function is the canonical bridge from
+ * a shared `ReferenceIndex` into per-language graph edges. Every
+ * registry-primary language provider calls this exactly once with its
+ * `referenceIndex` output and its own `nodeLookup`.
+ */
+import type { Reference, ScopeId } from '../../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../../graph/types.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+/**
+ * Optional opaque skip key — providers may pre-emit edges (e.g. via
+ * receiver-bound post-passes) and want this loop to skip references at
+ * the same source position so the shared resolver's potentially-wrong
+ * fallback resolution doesn't fight the precise emission. The key is
+ * `${filePath}:${startLine}:${startCol}`.
+ */
+type ReferenceSiteSkipSet = ReadonlySet<string>;
+export declare function emitReferencesViaLookup(graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, referenceIndex: {
+    readonly bySourceScope: ReadonlyMap<ScopeId, readonly Reference[]>;
+}, nodeLookup: GraphNodeLookup, skipSites?: ReferenceSiteSkipSet): {
+    emitted: number;
+    skipped: number;
+};
+export {};

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

@@ -0,0 +1,73 @@
+/**
+ * Translate the resolved `ReferenceIndex` into legacy graph edges.
+ *
+ * Per reference:
+ *   1. Resolve `fromScope` → caller graph-node id by walking the scope
+ *      chain looking for an enclosing Function/Method/Class.
+ *   2. Resolve `toDef` → target graph-node id via `nodeLookup`.
+ *   3. Emit the edge (`CALLS` / `READS` / `WRITES` / `EXTENDS` / `USES`)
+ *      with the standard reason format.
+ *
+ * Skips (without throwing) when either side fails to map — either side
+ * may legitimately not exist as a graph node (e.g. a resolved target
+ * lives in an external file that wasn't ingested into the graph).
+ *
+ * Next-consumer contract: this function is the canonical bridge from
+ * a shared `ReferenceIndex` into per-language graph edges. Every
+ * registry-primary language provider calls this exactly once with its
+ * `referenceIndex` output and its own `nodeLookup`.
+ */
+import { resolveCallerGraphId, resolveDefGraphId } from '../graph-bridge/ids.js';
+import { mapReferenceKindToEdgeType } from '../graph-bridge/edges.js';
+export function emitReferencesViaLookup(graph, scopes, referenceIndex, nodeLookup, skipSites) {
+    let emitted = 0;
+    let skipped = 0;
+    const seen = new Set();
+    for (const [fromScope, refs] of referenceIndex.bySourceScope) {
+        const callerGraphId = resolveCallerGraphId(fromScope, scopes, nodeLookup);
+        if (callerGraphId === undefined) {
+            skipped += refs.length;
+            continue;
+        }
+        const fromScopeMeta = scopes.scopeTree.getScope(fromScope);
+        const fromFilePath = fromScopeMeta?.filePath;
+        for (const ref of refs) {
+            if (skipSites !== undefined && fromFilePath !== undefined) {
+                const siteKey = `${fromFilePath}:${ref.atRange.startLine}:${ref.atRange.startCol}`;
+                if (skipSites.has(siteKey)) {
+                    skipped++;
+                    continue;
+                }
+            }
+            const targetDef = scopes.defs.get(ref.toDef);
+            if (targetDef === undefined) {
+                skipped++;
+                continue;
+            }
+            const targetGraphId = resolveDefGraphId(targetDef.filePath, targetDef, nodeLookup);
+            if (targetGraphId === undefined) {
+                skipped++;
+                continue;
+            }
+            const edgeType = mapReferenceKindToEdgeType(ref.kind);
+            if (edgeType === undefined) {
+                skipped++;
+                continue;
+            }
+            const dedupKey = `${edgeType}:${callerGraphId}->${targetGraphId}:${ref.atRange.startLine}:${ref.atRange.startCol}`;
+            if (seen.has(dedupKey))
+                continue;
+            seen.add(dedupKey);
+            graph.addRelationship({
+                id: `rel:${dedupKey}`,
+                sourceId: callerGraphId,
+                targetId: targetGraphId,
+                type: edgeType,
+                confidence: ref.confidence,
+                reason: `scope-resolution: ${ref.kind}`,
+            });
+            emitted++;
+        }
+    }
+    return { emitted, skipped };
+}