<aside> 📌

This RFC is the scope-graph continuation of the Fuzzy Lookup Elimination RFC and implements the resolution-layer side of Ingestion Roadmap Phase 3 (Wire SemanticModel). It is triggered by PR #902 review feedback: "resolution must use the semantic model with O(1) lookups — that is the sole purpose of the semantic model."

</aside>

TL;DR

GitNexus already has a SemanticModel (SymbolTable + Type/Method/Field registries + HeritageMap) that resolves calls through a 5-stage DAG inside call-processor.ts. The DAG still reads AST fragments at resolution time and still uses a tiered TieredCandidates API where the caller has to reason about where a match was found. This RFC locks a design that:

1. Makes the scope tree the canonical visibility spine of the SemanticModel (containers + block + expression scopes, full granularity).
2. Replaces ResolutionContext.resolve(name, file) + TieredCandidates with three scope-aware per-kind entry points: ClassRegistry.lookup(name, scope), MethodRegistry.lookup(name, scope), FieldRegistry.lookup(name, scope) — all returning Resolution[] with { def, confidence, evidence }.
3. Collapses the call-resolution DAG into a single Registry.lookup(name, scope) call. TypeEnv becomes Scope.typeBindings; implicit-receiver inference becomes a strict resolveTypeRef path; dispatch-strategy selection becomes caller-side registry selection.
4. Keeps SymbolTable and TypeRegistry as internal contributors — the resolver never calls them directly.
5. Rolls out shadow-first: per-language PRs run both the legacy DAG and the new registries, diff results into a parity dashboard, and flip REGISTRY_PRIMARY_<LANG> when ≥99% fixture + ≥98% corpus parity is reached. DAG retirement only when all production-classified languages are flipped and stable for a release cycle.

The design preserves every public invariant of the knowledge graph: no changes to node/edge schema, no changes to MCP contracts, no changes to graph output. All delta lives inside the ingestion pipeline.

§1 — Architecture Overview

Two walls, one spine.

┌──────────────────────┐                          ┌──────────────────────┐
│  AST (tree-sitter    │                          │  Knowledge graph     │
│  + COBOL regex)      │                          │  (LadybugDB)         │
└──────────┬───────────┘                          └──────────▲───────────┘
           │                                                 │
           │ extraction                  resolution          │
           │ (AST-reading)               (model-only)        │
           ▼                                                 │
┌───────────────────────────────────────────────────────────┴──────────┐
│                      Semantic Model                                   │
│  ┌──────────────────────────────────────────────────────────────┐    │
│  │  ScopeTree (spine)                                           │    │
│  │    ─ Scope nodes: {bindings, ownedDefs, imports,             │    │
│  │                    typeBindings, range, parent}              │    │
│  │    ─ PositionIndex (O(log N) scope-at-position)              │    │
│  │    ─ Parent pointers (O(D) scope-chain walk)                 │    │
│  └──────────────────────────────────────────────────────────────┘    │
│  ┌──────────────────────────────────────────────────────────────┐    │
│  │  Public API (resolver calls these; nothing else)             │    │
│  │    ClassRegistry.lookup(name, scope)  → Resolution[]         │    │
│  │    MethodRegistry.lookup(name, scope) → Resolution[]         │    │
│  │    FieldRegistry.lookup(name, scope)  → Resolution[]         │    │
│  └──────────────────────────────────────────────────────────────┘    │
│  ┌──────────────────────────────────────────────────────────────┐    │
│  │  Internal contributors (feed into lookups; never called      │    │
│  │  directly by the resolver)                                   │    │
│  │    SymbolTable · TypeRegistry                                │    │
│  │    DefIndex · ModuleScopeIndex · QualifiedNameIndex          │    │
│  │    MethodDispatchIndex · ExportMap · ImportGraph             │    │
│  └──────────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────────┘

Wall 1 — Extraction → SemanticModel. Only extraction code reads the AST. It produces: scope tree, declarations attached to scopes, raw import edges on module-level scopes, type bindings, reference sites. No resolution happens here.

Wall 2 — SemanticModel → Resolver. Only the resolver calls Registry.lookup(name, scope). It never sees the AST. It emits one edge to the knowledge graph per call, tagged with confidence + evidence.

This matches the PR #902 review requirements verbatim: extraction is the sole AST-reader; resolution is the sole model-reader; the two phases talk through one well-typed spine and three well-typed queries.

§2 — Data Model (LOCKED — authoritative source)