arceus-s 1.6.4

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.js

@@ -0,0 +1,250 @@
+/**
+ * `ScopeResolver` — the per-language contract consumed by the generic
+ * scope-resolution orchestrator (`runScopeResolution`).
+ *
+ * ## Migration cookbook (next language)
+ *
+ * To add a language to the registry-primary path:
+ *
+ *   1. Implement `ScopeResolver` in
+ *      `arc/src/core/ingestion/languages/<lang>/scope-resolver.ts`.
+ *      Nine required fields (language, languageProvider,
+ *      importEdgeReason, resolveImportTarget, mergeBindings,
+ *      arityCompatibility, buildMro, populateOwners, isSuperReceiver)
+ *      plus optional toggles / hooks:
+ *        - propagatesReturnTypesAcrossImports (default true)
+ *        - fieldFallbackOnMethodLookup (default true — turn OFF for
+ *          statically-typed languages; the heuristic over-connects)
+ *        - unwrapCollectionAccessor — property-style collection views
+ *        - collapseMemberCallsByCallerTarget — one edge per caller/target
+ *        - populateNamespaceSiblings — cross-file implicit visibility
+ *        - hoistTypeBindingsToModule — enable ONLY when method return
+ *          types are stored on the enclosing Module scope; most
+ *          languages attach them to the class scope and leave this off
+ *   2. Export a thin entry point:
+ *      `runYourLangScopeResolution(input) = runScopeResolution(input, yourScopeResolver)`.
+ *   3. Register the provider in
+ *      `arc/src/core/ingestion/scope-resolution/pipeline/registry.ts`
+ *      (the `SCOPE_RESOLVERS` map).
+ *   4. Add `SupportedLanguages.YourLang` to `MIGRATED_LANGUAGES` in
+ *      `registry-primary-flag.ts`.
+ *   5. Verify the resolver integration test at
+ *      `arc/test/integration/resolvers/<lang>.test.ts` passes
+ *      under both `REGISTRY_PRIMARY_<LANG>=0` (legacy) and `=1`
+ *      (registry-primary). The CI parity gate enforces this.
+ *
+ * No new pipeline phase, no orchestrator copy-paste, no workflow
+ * change. The generic `scopeResolutionPhase` and the CI parity
+ * workflow auto-discover everything via `MIGRATED_LANGUAGES`.
+ *
+ * ## ScopeResolver vs LanguageProvider
+ *
+ * The codebase has two provider contracts. Their lifecycles differ:
+ *
+ *   - `LanguageProvider` (`language-provider.ts`) is the
+ *     **parsing-side** contract — how to emit captures, classify
+ *     scopes, interpret imports / typeBindings. ~40 fields covering
+ *     both legacy and new pipelines. Consumed by `ScopeExtractor`,
+ *     once per file at extract time.
+ *   - `ScopeResolver` (this file) is the **emit-side** contract — how
+ *     the resolution pipeline dispatches references to graph edges.
+ *     8 fields total. Consumed by `runScopeResolution`, once per
+ *     workspace at resolve time.
+ *
+ * They share three concept names (`arityCompatibility`, `mergeBindings`,
+ * `resolveImportTarget`) because the emit pipeline reuses a few
+ * finalize hooks. Per-language wiring passes the SAME function
+ * reference through both interfaces — no second copy of the logic.
+ * Rationale for not collapsing: lifecycle separation, and merging
+ * would create a god-interface complicating future migrations.
+ *
+ * ## Reference implementation
+ *
+ * `arc/src/core/ingestion/languages/python/scope-resolver.ts` —
+ * `pythonScopeResolver` is the canonical example. Read that file when
+ * migrating a new language; this interface lists the fields that
+ * implementation populates.
+ *
+ * ## Contract Invariants the orchestrator depends on
+ *
+ * These are non-obvious behaviors that the orchestrator and the
+ * existing Python + C# resolvers depend on. Future implementers will
+ * break them silently if not documented.
+ *
+ *   - **I1 — Phase 4 emission order is load-bearing.** `emitReceiverBoundCalls`
+ *     runs FIRST (populates `handledSites`), then `emitFreeCallFallback`,
+ *     then `emitReferencesViaLookup` (consumes `handledSites` as a skip
+ *     set), then `emitImportEdges`. Reordering breaks same-name collision
+ *     resolution: the shared lookup can mis-resolve `app_metrics.get_metrics()`
+ *     to a same-named local function, and only the precise per-receiver
+ *     pass running first prevents the wrong edge.
+ *
+ *   - **I2 — `handledSites` semantics.** A site is added to
+ *     `handledSites` IFF a `tryEmitEdge` call returned `true` for it.
+ *     Sites a pass touched but couldn't resolve do NOT get marked —
+ *     they still get a chance from the shared resolver. Exception:
+ *     the free-call fallback marks the site unconditionally after
+ *     attempting emission (even on dedup-collapse), because the
+ *     per-(caller, target) collapse semantics require multiple call
+ *     sites in the same caller body not produce multiple edges.
+ *
+ *   - **I3 — `propagateImportedReturnTypes` mutation timing + ordering.**
+ *     The pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
+ *     `draftToScope`, NOT frozen). It MUST run AFTER `finalizeScopeModel`
+ *     (so `indexes.bindings` is populated) and BEFORE
+ *     `resolveReferenceSites` (so resolution sees the propagated types).
+ *     The pass also re-runs `followChainPostFinalize` on every scope's
+ *     typeBindings because scope-extractor's pass-4 already ran and
+ *     missed any chain whose terminal lives in a foreign file.
+ *     Within the pass, files are walked in `indexes.sccs` reverse-
+ *     topological order (leaves first) so multi-hop alias chains
+ *     (e.g. `models.User → service.user → app.user`) collapse to the
+ *     terminal class in a single pass — every importer sees its
+ *     source's already-chain-followed typeBindings. Cyclic SCCs reach
+ *     a partial fixpoint within a single pass without iterating to
+ *     convergence; `ts-circular` only asserts pipeline-no-throw.
+ *
+ *   - **I4 — `emitReceiverBoundCalls` case order.** Cases are evaluated
+ *     in this order; the FIRST that emits an edge wins:
+ *       1. super branch (`provider.isSuperReceiver(receiverName)`)
+ *       2. Case 0 compound (`receiverName` has `.` or `(`)
+ *       3. Case 1 namespace-receiver
+ *       4. Case 2 class-name receiver
+ *       5. Case 3 dotted typeBinding for namespace prefix
+ *       6. Case 3b chain-typebinding (compound resolver)
+ *       7. Case 4 simple typeBinding (MRO walk + findOwnedMember)
+ *     Reordering or merging cases changes resolution semantics. The
+ *     numbering is part of the contract — keep the comments.
+ *
+ *   - **I5 — Pre-seeding `seen` from `referenceIndex` is forbidden.**
+ *     Earlier versions of the receiver-bound pass pre-populated `seen`
+ *     to avoid double-emit. After Phase 4 was reordered, pre-seeding
+ *     became actively harmful: it suppresses correct emissions for
+ *     sites the shared resolver happened to resolve to a wrong target.
+ *     The orchestrator MUST NOT pre-seed.
+ *
+ *   - **I6 — `Scope.typeBindings` is mutable post-finalize.** `draftToScope`
+ *     (in `scope-extractor.ts`) builds `typeBindings` as a plain
+ *     `new Map(...)` — not frozen, intentionally. Passes below rely on
+ *     this. Do NOT freeze `typeBindings` in any downstream refactor.
+ *
+ *   - **I7 — `ScopeResolver` and `LanguageProvider` are distinct contracts.**
+ *     Python and C# pass the SAME function reference through both
+ *     interfaces where they share a hook name — no second copy of the
+ *     logic. Rationale for not collapsing them: lifecycles differ
+ *     (parsing-side runs once per file at extract time, emit-side runs
+ *     once per workspace at resolve time), and merging would create a
+ *     god-interface that complicates future migrations.
+ *
+ *   - **I8 — Two-channel binding lifecycle.**
+ *     `indexes.bindings` is the **finalize-output channel**. After
+ *     `finalizeScopeModel` returns, its inner `BindingRef[]` arrays
+ *     are deep-frozen by `materializeBindings` and MUST NOT be
+ *     mutated by any post-finalize hook. Treat `indexes.bindings` as
+ *     immutable from the moment `finalizeScopeModel` returns.
+ *
+ *     `indexes.bindingAugmentations` is the **post-finalize
+ *     append-only channel**. Hooks like `populateNamespaceSiblings`
+ *     append cross-file bindings synthesized after finalize (C#
+ *     same-namespace visibility, `using static` member exposure)
+ *     into this channel, NOT into `indexes.bindings`. Inner arrays
+ *     here are NEVER frozen — hooks `push()` directly. Any consumer
+ *     that reads post-finalize workspace bindings MUST query both
+ *     index channels via `lookupBindingsAt`
+ *     (`scope-resolution/scope/walkers.ts`); the helper returns
+ *     finalized refs first, appends unique augmentation refs after,
+ *     and dedupes by `def.nodeId` so finalized metadata wins on
+ *     duplicate defs. Per-`Scope.bindings` local declarations are the
+ *     lexical extraction channel and remain a separate first-tier
+ *     lookup for local shadowing.
+ *
+ *     `Scope.typeBindings` remains mutable post-finalize per I6 (it
+ *     is intentionally not frozen at any point).
+ *
+ *     The `ReadonlyMap<...>` types on `ScopeResolutionIndexes` are
+ *     compile-time read-guidance for consumers; structural mutation
+ *     of `bindingAugmentations` is performed via a deliberate
+ *     `as Map<...>` cast inside the hook implementations and is the
+ *     ONLY sanctioned channel for post-finalize binding fanout.
+ *
+ *     The dev-mode runtime validator
+ *     (`validateBindingsImmutability` in
+ *     `scope-resolution/validate-bindings-immutability.ts`) surfaces
+ *     any drift — i.e. a hook writing to `indexes.bindings` instead
+ *     of `bindingAugmentations`, or producing a non-frozen finalized
+ *     bucket — via `onWarn` when explicitly enabled by
+ *     `NODE_ENV === 'development' || VALIDATE_SEMANTIC_MODEL === '1'`
+ *     (`VALIDATE_SEMANTIC_MODEL=0` is an explicit off switch).
+ *
+ *   - **I9 — `SemanticModel` is the single authoritative symbol store.**
+ *     Every symbol-indexed lookup (key = `nodeId | simpleName |
+ *     qualifiedName | filePath`) resolves through
+ *     `SemanticModel.{symbols,types,methods,fields}`. Scope-resolution
+ *     passes MUST NOT maintain parallel owner-keyed or name-keyed
+ *     symbol indexes — `WorkspaceResolutionIndex` is reserved for
+ *     `Scope`-valued lookups that `SemanticModel` structurally cannot
+ *     carry.
+ *
+ *     The `runScopeResolution` orchestrator guarantees this invariant
+ *     in two steps:
+ *       1. The legacy `parse` phase populates `SemanticModel` via
+ *          `symbolTable.add(...)`. For languages whose extractor
+ *          resolves `enclosingClassId` at parse time, class-body defs
+ *          are correctly owner-keyed there.
+ *       2. The `reconcileOwnership` pass runs after
+ *          `provider.populateOwners(parsed)` and registers any def in
+ *          `parsed.localDefs[i]` with a corrected `ownerId` that the
+ *          legacy pass missed (primarily Python class-body methods).
+ *          Idempotent — duplicates are skipped by `nodeId`.
+ *
+ *     Contract for consumers: `model` is `MutableSemanticModel` only
+ *     during those two write phases. Downstream passes receive a
+ *     narrowed `SemanticModel` (read-only) handle. This is enforced by
+ *     `runScopeResolution`'s type-level narrowing at the phase
+ *     boundary.
+ *
+ *     The dev-mode runtime validator (`validateOwnershipParity`)
+ *     surfaces any drift between `parsed.localDefs` ownership and the
+ *     registries via `onWarn` when
+ *     `NODE_ENV !== 'production' && VALIDATE_SEMANTIC_MODEL !== '0'`.
+ *
+ *     This invariant is a **transitional shim**: the architectural
+ *     end state is for every language's parse-time extractor to emit
+ *     the correct `ownerId` directly, removing the need for
+ *     reconciliation. Tracked as a follow-up; see ARCHITECTURE.md §
+ *     "Semantic-model source of truth".
+ *
+ * ## Semantic-model source of truth
+ *
+ * `ParsedFile` (from `arceus-shared/src/scope-resolution/parsed-file.ts`)
+ * is the single semantic model consumed by both the legacy DAG and the
+ * scope-resolution pipeline. Scope-resolution passes MUST NOT build a
+ * parallel parse representation; if a pass needs AST-level facts that
+ * `ParsedFile` doesn't expose, it should reuse the orchestrator's
+ * `treeCache` (see `RunScopeResolutionInput.treeCache`) rather than
+ * re-invoke `parser.parse(...)` on its own.
+ *
+ * ## Same-graph guarantee
+ *
+ * Edges emitted by `runScopeResolution` and edges emitted by the legacy
+ * DAG are indistinguishable to downstream consumers:
+ *   - Node identity: same `generateId(...)` helper, same qualified-name
+ *     keyspace, same File/Folder/Method/Class node labels.
+ *   - Edge vocabulary: `'import-resolved' | 'global' | 'local-call' |
+ *     'same-file' | 'interface-dispatch' | 'read' | 'write'` — both
+ *     paths emit the same reasons (see
+ *     `arc/src/core/ingestion/call-processor.ts` for the legacy
+ *     emitter and `passes/receiver-bound-calls.ts` /
+ *     `passes/free-call-fallback.ts` for the scope-resolution emitters).
+ *   - Overload disambiguation: both paths use
+ *     `generateId('Method', ...)` suffixed with `parameterTypes` when a
+ *     method has overloads — see `graph-bridge/ids.ts`.
+ *
+ * The CI parity workflow (`.github/workflows/ci-scope-parity.yml`)
+ * runs both paths on every migrated language's fixture corpus and
+ * fails if the graph outputs diverge.
+ *
+ * Plan that introduced most of these invariants:
+ * `docs/plans/2026-04-20-001-refactor-emit-pipeline-generalization-plan.md`.
+ */
+export {};

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

@@ -0,0 +1,43 @@
+/**
+ * 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 type { Reference, ScopeId, SymbolDefinition } 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';
+/**
+ * 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 declare function mapReferenceKindToEdgeType(kind: Reference['kind']): 'CALLS' | 'ACCESSES' | 'EXTENDS' | 'USES' | 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 declare function tryEmitEdge(graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, nodeLookup: GraphNodeLookup, site: {
+    readonly inScope: ScopeId;
+    readonly atRange: {
+        startLine: number;
+        startCol: number;
+    };
+    readonly kind: string;
+}, targetDef: SymbolDefinition, reason: string, seen: Set<string>, confidence?: number, collapseByCallerTarget?: boolean): boolean;

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,142 @@
+/**
+ * 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 { qualifiedKey, simpleKey } from '../graph-bridge/node-lookup.js';
+/**
+ * Labels that may legitimately ANCHOR a CALLS/ACCESSES edge as the
+ * source ("caller"). A Variable / Property can be the TARGET of an
+ * edge (e.g., a write-access to `user.name`), but it cannot be a
+ * caller — variables don't execute code, so attributing a call to a
+ * sibling Variable in the same scope produces nonsense edges like
+ * `Variable:create → Function:create` (which the simpleKey fallback
+ * in `resolveDefGraphId` then silently rewrites to
+ * `Function:create → Function:create`, a self-loop that doesn't exist
+ * in the source).
+ *
+ * Module-level call expressions inside a `const X = expr(args)`
+ * declaration are the canonical case where this used to fail: the
+ * walk-up over module scope's ownedDefs (only Variables) would land
+ * on the FIRST Variable, get name-aliased to its sibling Function
+ * with the same simple name, and emit a self-CALLS. With this label
+ * restricted to function/class-likes, those calls correctly fall
+ * through to the File-node fallback at the bottom of the walk.
+ */
+function isCallerAnchorLabel(label) {
+    return (label === 'Function' ||
+        label === 'Method' ||
+        label === 'Constructor' ||
+        label === 'Class' ||
+        label === 'Interface' ||
+        label === 'Struct' ||
+        label === 'Enum');
+}
+/**
+ * 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/Constructor anchors; fall back to
+        // Class/Interface/Struct/Enum. Variable/Property are NOT valid
+        // caller anchors — see `isCallerAnchorLabel` for why.
+        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) => isCallerAnchorLabel(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[]>, extendsOnlyMroByDefId?: ReadonlyMap<string, readonly string[]>): MethodDispatchIndex;