arceus-s 1.6.4

package/dist/core/ingestion/model/resolve.js

@@ -0,0 +1,401 @@
+/**
+ * Deterministic Resolution Functions
+ *
+ * Pure functions that resolve methods across the inheritance hierarchy
+ * using only the SemanticModel registries and HeritageMap — NO dependency
+ * on resolution-context.ts (circular dependency risk).
+ */
+// ---------------------------------------------------------------------------
+// MRO primitives.
+//
+// `c3Linearize` and its BFS helper `gatherAncestors` live here so the model
+// layer stays a pure leaf — mro-processor.ts (graph-level MRO emission)
+// imports `c3Linearize` from this file.
+// ---------------------------------------------------------------------------
+/**
+ * Gather all ancestor IDs in BFS / topological order.
+ * Returns the linearized list of ancestor IDs (excluding the class itself).
+ *
+ * Uses a head-pointer BFS (`queue[head++]`) instead of `Array.shift()` to
+ * avoid O(n) per-dequeue re-indexing — matching `buildParentMapFromHeritage`.
+ */
+function gatherAncestors(classId, parentMap) {
+    const visited = new Set();
+    const order = [];
+    const queue = [...(parentMap.get(classId) ?? [])];
+    let head = 0;
+    while (head < queue.length) {
+        const id = queue[head++];
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        order.push(id);
+        const grandparents = parentMap.get(id);
+        if (grandparents) {
+            for (const gp of grandparents) {
+                if (!visited.has(gp))
+                    queue.push(gp);
+            }
+        }
+    }
+    return order;
+}
+/**
+ * Compute C3 linearization for a class given a parentMap.
+ * Returns an array of ancestor IDs in C3 order (excluding the class itself),
+ * or null if linearization fails (inconsistent or cyclic hierarchy).
+ *
+ * Used internally by `lookupMethodByOwnerWithMRO` for the Python MRO
+ * strategy and re-exported for mro-processor.ts (graph-level MRO emission).
+ */
+export function c3Linearize(classId, parentMap, cache, inProgress) {
+    if (cache.has(classId))
+        return cache.get(classId);
+    // Iterative C3 linearization using an explicit work stack. The recursive
+    // version overflows the call stack on deep class hierarchies (10K+
+    // levels in large Android/Java codebases).
+    //
+    // Strategy: maintain a stack of { classId, phase } frames. Each frame
+    // goes through two phases:
+    //   ENTER (0) – check cache / cycle, push parent frames to compute first
+    //   MERGE (1) – all parent linearizations are cached, merge them C3-style
+    const visiting = inProgress ?? new Set();
+    const ENTER = 0;
+    const MERGE = 1;
+    const stack = [{ id: classId, phase: ENTER }];
+    while (stack.length > 0) {
+        const frame = stack[stack.length - 1];
+        if (frame.phase === ENTER) {
+            // ── ENTER phase ─────────────────────────────────────────────
+            if (cache.has(frame.id)) {
+                stack.pop();
+                continue;
+            }
+            if (visiting.has(frame.id)) {
+                // Cycle detected
+                cache.set(frame.id, null);
+                stack.pop();
+                continue;
+            }
+            visiting.add(frame.id);
+            const directParents = parentMap.get(frame.id);
+            if (!directParents || directParents.length === 0) {
+                visiting.delete(frame.id);
+                cache.set(frame.id, []);
+                stack.pop();
+                continue;
+            }
+            // Switch to MERGE phase and push parents that still need computing
+            frame.phase = MERGE;
+            let allParentsCached = true;
+            for (let i = directParents.length - 1; i >= 0; i--) {
+                const pid = directParents[i];
+                if (!cache.has(pid)) {
+                    stack.push({ id: pid, phase: ENTER });
+                    allParentsCached = false;
+                }
+            }
+            // If all parents are already cached, proceed directly to the MERGE
+            // phase below (frame.phase is already MERGE, frame is at stack top).
+            // Otherwise, loop back to process the newly-pushed parent frames first.
+            if (!allParentsCached) {
+                continue;
+            }
+        }
+        // ── MERGE phase ───────────────────────────────────────────────
+        // directParents is guaranteed non-empty here — the ENTER phase already
+        // handles the empty-parents case and pops the frame before switching
+        // to MERGE.
+        stack.pop();
+        const directParents = parentMap.get(frame.id);
+        // Build parent linearizations from cache
+        const parentLinearizations = [];
+        let failed = false;
+        for (const pid of directParents) {
+            const pLin = cache.get(pid);
+            if (pLin === undefined) {
+                // Should not happen if phases are ordered correctly, but guard anyway
+                failed = true;
+                break;
+            }
+            if (pLin === null) {
+                // Parent linearization failed (cycle or inconsistent)
+                failed = true;
+                break;
+            }
+            parentLinearizations.push([pid, ...pLin]);
+        }
+        if (failed) {
+            visiting.delete(frame.id);
+            cache.set(frame.id, null);
+            continue;
+        }
+        // Add the direct parents list as the final sequence
+        const sequences = [...parentLinearizations, [...directParents]];
+        const heads = new Uint32Array(sequences.length); // head pointer per sequence
+        const result = [];
+        // Tail-count map: how many sequences contain this id at index > head.
+        // O(1) membership check replaces O(n) indexOf scans.
+        const tailCount = new Map();
+        for (const seq of sequences) {
+            for (let i = 1; i < seq.length; i++) {
+                tailCount.set(seq[i], (tailCount.get(seq[i]) ?? 0) + 1);
+            }
+        }
+        let remaining = sequences.reduce((n, s) => n + s.length, 0);
+        let inconsistent = false;
+        while (remaining > 0) {
+            let head = null;
+            for (let si = 0; si < sequences.length; si++) {
+                if (heads[si] >= sequences[si].length)
+                    continue;
+                const candidate = sequences[si][heads[si]];
+                if ((tailCount.get(candidate) ?? 0) === 0) {
+                    head = candidate;
+                    break;
+                }
+            }
+            if (head === null) {
+                inconsistent = true;
+                break;
+            }
+            result.push(head);
+            // Advance head pointers past the chosen head; update tail counts
+            for (let si = 0; si < sequences.length; si++) {
+                if (heads[si] >= sequences[si].length)
+                    continue;
+                if (sequences[si][heads[si]] === head) {
+                    heads[si]++;
+                    remaining--;
+                    // promoted was in this sequence's active tail; now it's the new head — remove from tailCount
+                    if (heads[si] < sequences[si].length) {
+                        const promoted = sequences[si][heads[si]];
+                        const prev = tailCount.get(promoted);
+                        if (prev <= 1)
+                            tailCount.delete(promoted);
+                        else
+                            tailCount.set(promoted, prev - 1);
+                    }
+                }
+            }
+        }
+        visiting.delete(frame.id);
+        cache.set(frame.id, inconsistent ? null : result);
+    }
+    return cache.get(classId) ?? null;
+}
+// `gatherAncestors` is exported so mro-processor.ts can reuse the same
+// BFS traversal for graph-level MRO emission.
+export { gatherAncestors };
+// ---------------------------------------------------------------------------
+// C3 linearization cache (per HeritageMap, auto-drained via WeakMap)
+// ---------------------------------------------------------------------------
+/**
+ * Per-HeritageMap cache of C3 linearization results keyed by owner nodeId.
+ *
+ * HeritageMap instances are immutable after construction, so C3 output is
+ * stable for the lifetime of a HeritageMap. WeakMap lets the cache auto-drain
+ * when the HeritageMap is garbage collected (end of ingestion run), so we
+ * never need to manually invalidate it.
+ *
+ * `null` is a sentinel for "C3 failed for this owner" (cyclic or inconsistent
+ * hierarchy) so we don't re-run the expensive linearization repeatedly.
+ */
+const c3LinearizationCache = new WeakMap();
+const getCachedC3Linearization = (ownerNodeId, heritageMap) => {
+    let perHmCache = c3LinearizationCache.get(heritageMap);
+    if (!perHmCache) {
+        perHmCache = new Map();
+        c3LinearizationCache.set(heritageMap, perHmCache);
+    }
+    const cached = perHmCache.get(ownerNodeId);
+    if (cached !== undefined)
+        return cached;
+    const parentMap = buildParentMapFromHeritage(ownerNodeId, heritageMap);
+    const result = c3Linearize(ownerNodeId, parentMap, new Map()) ?? null;
+    perHmCache.set(ownerNodeId, result);
+    return result;
+};
+// ---------------------------------------------------------------------------
+// Heritage → parentMap conversion
+// ---------------------------------------------------------------------------
+/**
+ * Build a parentMap from HeritageMap for use with c3Linearize.
+ * Traverses the parent chain starting from startNodeId, collecting all
+ * parent→children relationships into a Map<string, string[]>.
+ *
+ * Uses a head-pointer BFS (queue[head++]) instead of Array.shift() to avoid
+ * O(n) per-dequeue re-indexing. For wide/shallow hierarchies common in
+ * large Java/C# codebases this keeps the walk linear in ancestor count.
+ */
+const buildParentMapFromHeritage = (startNodeId, heritageMap) => {
+    const parentMap = new Map();
+    const visited = new Set();
+    const queue = [startNodeId];
+    let head = 0;
+    while (head < queue.length) {
+        const nodeId = queue[head++];
+        if (visited.has(nodeId))
+            continue;
+        visited.add(nodeId);
+        const parents = heritageMap.getParents(nodeId);
+        if (parents.length > 0) {
+            parentMap.set(nodeId, parents);
+            for (const p of parents) {
+                if (!visited.has(p))
+                    queue.push(p);
+            }
+        }
+    }
+    return parentMap;
+};
+// ---------------------------------------------------------------------------
+// MRO-aware method lookup
+// ---------------------------------------------------------------------------
+/**
+ * DAG stage 5 helper: look up a method on an owner class via MRO walk.
+ *
+ * Low-level resolver; no dependency on SymbolTable, language registry, or
+ * resolution-context (keeps model/ layer free of cross-layer imports).
+ * All strategies respect `argCount` for overload narrowing.
+ * `ancestryOverride` replaces the default walk; caller must compute it correctly.
+ *
+ * Strategy summary (full docs in arceus-shared/mro-strategy.ts):
+ * - `first-wins` / `leftmost-base` / `implements-split`: BFS, first match wins.
+ * - `c3`: C3-linearized order; falls back to BFS on cycle/inconsistency.
+ * - `qualified-syntax`: returns undefined immediately (Rust requires explicit syntax).
+ * - `ruby-mixin`: kind-aware walk — see inline comments below.
+ *
+ * Internal API: exported for call-processor resolvers and tests.
+ * External callers should use resolveMemberCall instead.
+ *
+ * @see arceus-shared/mro-strategy.ts § 'ruby-mixin'
+ * @see call-processor.ts § resolveMemberCall
+ */
+export const lookupMethodByOwnerWithMRO = (ownerNodeId, methodName, heritageMap, model, strategy, argCount, 
+/**
+ * Optional pre-computed ancestry list. When provided, overrides the default
+ * per-strategy ancestry source. Primarily used by Ruby singleton dispatch:
+ * the caller supplies `heritageMap.getSingletonAncestry(ownerNodeId)` as
+ * node-id array so this walker resolves against `extend` providers only.
+ *
+ * For `ruby-mixin` strategy, passing an override switches the walker into
+ * a no-prepend-no-direct linear scan (the caller has already decided the
+ * order), which is the correct semantics for singleton dispatch.
+ */
+ancestryOverride) => {
+    // ── Ruby mixin strategy ───────────────────────────────────────────
+    // Kind-aware walk — does NOT short-circuit on direct owner first (prepend beats direct).
+    // Instance dispatch: prepend (reverse) → direct → include (reverse) → transitive BFS.
+    // Singleton dispatch: caller supplies ancestryOverride (extend providers only);
+    //   simple left-to-right scan. Miss NEVER falls through to file-scoped fallback.
+    // See arceus-shared/mro-strategy.ts § 'ruby-mixin' for full strategy docs.
+    if (strategy === 'ruby-mixin') {
+        if (ancestryOverride) {
+            // Singleton dispatch: scan pre-computed ancestry only. Miss null-routes.
+            for (const ancestorId of ancestryOverride) {
+                const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+                if (method)
+                    return method;
+            }
+            return undefined;
+        }
+        // Instance dispatch — kind-aware walk per the pseudocode above.
+        const instanceEntries = heritageMap.getInstanceAncestry(ownerNodeId);
+        // Partition into prepend parents vs other parents (extends / include /
+        // implements / trait-impl), preserving declaration order within each.
+        const prependParents = [];
+        const otherParents = [];
+        for (const e of instanceEntries) {
+            if (e.kind === 'prepend')
+                prependParents.push(e.parentId);
+            else
+                otherParents.push(e.parentId);
+        }
+        // Step 1: Walk prepend parents in REVERSE declaration order (last-prepended wins).
+        for (let i = prependParents.length - 1; i >= 0; i--) {
+            const method = model.methods.lookupMethodByOwner(prependParents[i], methodName, argCount);
+            if (method)
+                return method;
+        }
+        // Step 2: Direct owner lookup (the class's own method).
+        // This is the only difference from other strategies — prepend beats direct.
+        const direct = model.methods.lookupMethodByOwner(ownerNodeId, methodName, argCount);
+        if (direct)
+            return direct;
+        // Step 3: Walk extends + include parents in REVERSE declaration order.
+        // (Ruby `include A; include B` puts B ahead of A in MRO.)
+        for (let i = otherParents.length - 1; i >= 0; i--) {
+            const method = model.methods.lookupMethodByOwner(otherParents[i], methodName, argCount);
+            if (method)
+                return method;
+        }
+        // Step 4: Transitive ancestors (a mixin that itself mixes in another module).
+        // Fall back to the BFS ancestor walk for depth > 1. Order is best-effort;
+        // Ruby's actual MRO for transitive mixins is rare and under-specified
+        // (documented in architecture docs as deferred work).
+        //
+        // O(1) skip-check via Sets:
+        //   - `walkedDirect` covers parents already visited in steps 1-3.
+        //   - `singletonOnly` covers direct `extend` providers: they belong to
+        //     the singleton MRO and must NEVER appear in instance dispatch.
+        // Building Sets once before the BFS loop avoids O(n²) `Array.includes`
+        // on large mixin hierarchies.
+        const walkedDirect = new Set(prependParents);
+        for (const id of otherParents)
+            walkedDirect.add(id);
+        const singletonOnly = new Set(heritageMap.getSingletonAncestry(ownerNodeId).map((e) => e.parentId));
+        for (const ancestorId of heritageMap.getAncestors(ownerNodeId)) {
+            if (ancestorId === ownerNodeId)
+                continue;
+            if (walkedDirect.has(ancestorId))
+                continue;
+            if (singletonOnly.has(ancestorId))
+                continue;
+            const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+            if (method)
+                return method;
+        }
+        return undefined;
+    }
+    // ── Non-Ruby strategies: direct-owner-first short-circuit ─────────
+    // Direct lookup first (child override — no walk needed).
+    // argCount is threaded through so arity-differing overloads on the direct
+    // owner can be disambiguated before the MRO walk starts.
+    const direct = model.methods.lookupMethodByOwner(ownerNodeId, methodName, argCount);
+    if (direct)
+        return direct;
+    // Rust: requires qualified syntax (<Type as Trait>::method), no auto-resolution
+    if (strategy === 'qualified-syntax')
+        return undefined;
+    // Determine ancestor walk order based on MRO strategy.
+    // readonly to accept the cached (frozen) c3 linearization without copying.
+    let ancestors;
+    if (ancestryOverride) {
+        ancestors = ancestryOverride;
+    }
+    else if (strategy === 'c3') {
+        // C3 linearization (memoized per HeritageMap
+        // so repeated calls for the same owner within an ingestion run reuse the
+        // linearization instead of rebuilding the parent map and re-running C3).
+        // c3Linearize returns ancestors only (excludes the owner itself),
+        // matching heritageMap.getAncestors() semantics.
+        const c3Result = getCachedC3Linearization(ownerNodeId, heritageMap);
+        // Fall back to BFS order if C3 fails (cyclic or inconsistent hierarchy).
+        // Note: BFS order may not preserve Python MRO semantics in these edge
+        // cases, but cyclic/inconsistent hierarchies are invalid in Python anyway.
+        ancestors = c3Result ?? heritageMap.getAncestors(ownerNodeId);
+    }
+    else {
+        // first-wins, leftmost-base, implements-split: BFS order via HeritageMap
+        ancestors = heritageMap.getAncestors(ownerNodeId);
+    }
+    // Walk ancestors in MRO order — first match wins.
+    // argCount narrows overloaded ancestors the same way as the direct lookup.
+    for (const ancestorId of ancestors) {
+        const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+        if (method)
+            return method;
+    }
+    return undefined;
+};

package/dist/core/ingestion/model/scope-resolution-indexes.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `ScopeResolutionIndexes` — the bundle of materialized indexes produced
+ * by the finalize-orchestrator (RFC #909 Ring 2 PKG #921) and attached
+ * to `MutableSemanticModel`.
+ *
+ * Produced by `finalizeScopeModel(parsedFiles, hooks)` in
+ * `finalize-orchestrator.ts`. Consumed by the resolution phase (future
+ * tickets) where `Registry.lookup` / `resolveTypeRef` query this bundle
+ * to answer call-resolution questions without re-walking any AST.
+ *
+ * ## Lifecycle
+ *
+ *   1. Pipeline collects `ParsedFile[]` from the parsing-processor (#920).
+ *   2. Pipeline invokes `finalizeScopeModel(parsedFiles, hooks)` →
+ *      returns a `ScopeResolutionIndexes` (this interface).
+ *   3. Pipeline calls `model.attachScopeIndexes(indexes)` to stamp them
+ *      onto the `MutableSemanticModel`. This is a **one-shot write**;
+ *      subsequent calls throw. After attachment, the indexes are frozen
+ *      at the type level (everything is `readonly`) and at runtime via
+ *      `Object.freeze` on the bundle.
+ *   4. Resolution callers hold a `SemanticModel` reference and read
+ *      `model.scopes` to query.
+ *
+ * ## Content
+ *
+ *   - `scopeTree` / `moduleScopes` / `defs` / `qualifiedNames` — the
+ *     four Ring 2 SHARED indexes built over per-file artifacts.
+ *   - `methodDispatch` — MRO + implements materialized view (#914).
+ *   - `imports` — finalized `ImportEdge[]` per module scope (`parsedImports`
+ *     resolved through cross-file link + wildcard expansion).
+ *   - `bindings` — merged bindings per module scope (local + import +
+ *     wildcard + re-export), with the provider's precedence applied.
+ *   - `referenceSites` — union of every file's pre-resolution usage
+ *     facts. Consumed by the resolution phase (future) to emit
+ *     `Reference` records into `ReferenceIndex`.
+ *   - `stats` — coarse-grained counts from the shared finalize algorithm
+ *     (total files/edges, linked vs unresolved, SCC topology).
+ *
+ * `ReferenceIndex` is deliberately NOT here — it is populated in a later
+ * phase (RFC §3.2 Phase 4 / Ring 2 PKG #925) and owned separately.
+ */
+import type { BindingRef, DefIndex, FinalizedScc, FinalizeStats, ImportEdge, MethodDispatchIndex, ModuleScopeIndex, QualifiedNameIndex, ReferenceSite, ScopeId, ScopeTree } from '../../../_shared/index.js';
+export interface ScopeResolutionIndexes {
+    readonly scopeTree: ScopeTree;
+    readonly defs: DefIndex;
+    readonly qualifiedNames: QualifiedNameIndex;
+    readonly moduleScopes: ModuleScopeIndex;
+    readonly methodDispatch: MethodDispatchIndex;
+    /** Finalized `ImportEdge[]` per module scope. */
+    readonly imports: ReadonlyMap<ScopeId, readonly ImportEdge[]>;
+    /** Finalize-output bindings (local + imports + wildcards) per module scope.
+     *  Inner `BindingRef[]` arrays are frozen by `materializeBindings`;
+     *  this channel is permanently immutable post-finalize. Consumers
+     *  MUST read via `lookupBindingsAt` so the augmentation channel is
+     *  consulted alongside. See I8 in `contract/scope-resolver.ts`. */
+    readonly bindings: ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>;
+    /** Append-only post-finalize augmentation channel. Populated by
+     *  language hooks such as `populateNamespaceSiblings` for cross-file
+     *  bindings synthesized after finalize (e.g. C# same-namespace
+     *  visibility, `using static` member exposure). Inner arrays are
+     *  NOT frozen — hooks `push()` directly. Walkers must consult both
+     *  this map and `bindings` via `lookupBindingsAt`; finalized refs
+     *  are returned first and win duplicate `def.nodeId` metadata, with
+     *  unique augmentations appended after. See I8. */
+    readonly bindingAugmentations: ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>;
+    /** Pre-resolution usage facts; consumed by the resolution phase. */
+    readonly referenceSites: readonly ReferenceSite[];
+    /** SCC condensation of the file-level import graph — callers that want
+     *  parallel per-SCC processing in the resolution phase read this. */
+    readonly sccs: readonly FinalizedScc[];
+    readonly stats: FinalizeStats;
+}

package/dist/core/ingestion/model/scope-resolution-indexes.js

@@ -0,0 +1,42 @@
+/**
+ * `ScopeResolutionIndexes` — the bundle of materialized indexes produced
+ * by the finalize-orchestrator (RFC #909 Ring 2 PKG #921) and attached
+ * to `MutableSemanticModel`.
+ *
+ * Produced by `finalizeScopeModel(parsedFiles, hooks)` in
+ * `finalize-orchestrator.ts`. Consumed by the resolution phase (future
+ * tickets) where `Registry.lookup` / `resolveTypeRef` query this bundle
+ * to answer call-resolution questions without re-walking any AST.
+ *
+ * ## Lifecycle
+ *
+ *   1. Pipeline collects `ParsedFile[]` from the parsing-processor (#920).
+ *   2. Pipeline invokes `finalizeScopeModel(parsedFiles, hooks)` →
+ *      returns a `ScopeResolutionIndexes` (this interface).
+ *   3. Pipeline calls `model.attachScopeIndexes(indexes)` to stamp them
+ *      onto the `MutableSemanticModel`. This is a **one-shot write**;
+ *      subsequent calls throw. After attachment, the indexes are frozen
+ *      at the type level (everything is `readonly`) and at runtime via
+ *      `Object.freeze` on the bundle.
+ *   4. Resolution callers hold a `SemanticModel` reference and read
+ *      `model.scopes` to query.
+ *
+ * ## Content
+ *
+ *   - `scopeTree` / `moduleScopes` / `defs` / `qualifiedNames` — the
+ *     four Ring 2 SHARED indexes built over per-file artifacts.
+ *   - `methodDispatch` — MRO + implements materialized view (#914).
+ *   - `imports` — finalized `ImportEdge[]` per module scope (`parsedImports`
+ *     resolved through cross-file link + wildcard expansion).
+ *   - `bindings` — merged bindings per module scope (local + import +
+ *     wildcard + re-export), with the provider's precedence applied.
+ *   - `referenceSites` — union of every file's pre-resolution usage
+ *     facts. Consumed by the resolution phase (future) to emit
+ *     `Reference` records into `ReferenceIndex`.
+ *   - `stats` — coarse-grained counts from the shared finalize algorithm
+ *     (total files/edges, linked vs unresolved, SCC topology).
+ *
+ * `ReferenceIndex` is deliberately NOT here — it is populated in a later
+ * phase (RFC §3.2 Phase 4 / Ring 2 PKG #925) and owned separately.
+ */
+export {};

package/dist/core/ingestion/model/semantic-model.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Semantic Model
+ *
+ * Top-level orchestrator for all resolution-time data. Owns:
+ *
+ *   - Three owner-scoped registries (types, methods, fields)
+ *   - A nested SymbolTable (file + callable name indexes) wrapped so
+ *     that `add()` fans out into the registries via the dispatch table
+ *
+ * ## Dependency direction
+ *
+ *     arceus-shared (NodeLabel)             — leaf
+ *          ↑
+ *     symbol-table.ts                         — pure file/callable index
+ *          ↑
+ *     model/type-registry / method-registry / field-registry
+ *          ↑
+ *     model/registration-table.ts             — dispatch table factory
+ *          ↑
+ *     model/semantic-model.ts                 — THIS FILE (orchestrator)
+ *          ↑
+ *     resolve.ts, call-processor.ts, resolution-context.ts, ...
+ *
+ * `symbol-table.ts` is a leaf — it never imports from `./model/`. This
+ * file (semantic-model.ts) is the ONLY place where SymbolTable and the
+ * owner-scoped registries are composed. Upstream consumers pass around
+ * the `SemanticModel` interface and reach into `.symbols` for file-scoped
+ * operations or `.types` / `.methods` / `.fields` for owner-scoped ones.
+ *
+ * ## Fan-out via wrapped add()
+ *
+ * `createSemanticModel()` creates a pure SymbolTable, creates the three
+ * registries, builds a dispatch table via `createRegistrationTable`, and
+ * exposes a SymbolTable-shaped façade whose `add()`:
+ *
+ *   1. Calls `rawSymbols.add()` — writes the fileIndex + callable index
+ *      and returns the fully-built `SymbolDefinition`.
+ *   2. Runs pre-dispatch normalization (`Function`-with-`ownerId` routes
+ *      as `Method`).
+ *   3. Looks up the dispatch table and invokes the hook, which writes to
+ *      the appropriate owner-scoped registry.
+ *
+ * The wrapper is the only place where the two layers are combined. A
+ * direct `createSymbolTable()` caller (e.g. an isolated unit test) gets
+ * the pure, registry-free behavior — no surprises, no hidden side
+ * effects.
+ *
+ * ## Single-source-of-truth invariant
+ *
+ * `SemanticModel` is the authoritative symbol store for the whole
+ * ingestion pipeline. Both the legacy Call-Resolution DAG and the
+ * new scope-resolution pipeline read symbol-keyed lookups from here
+ * exclusively — no parallel owner-keyed, name-keyed, or file-keyed
+ * symbol indexes exist outside this module. The scope-resolution
+ * pipeline does carry a small `WorkspaceResolutionIndex` for
+ * `Scope`-valued maps (`classScopeByDefId`, `moduleScopeByFile`) that
+ * `SemanticModel` structurally cannot hold, but nothing else.
+ *
+ * ## Write / read phase contract
+ *
+ * Writes to the model happen in three clearly-ordered phases during a
+ * single ingestion run:
+ *
+ *   1. **Legacy parse phase** (`parsing-processor`) calls
+ *      `symbols.add(...)` per extracted symbol, which fans out via
+ *      the dispatch table into `types` / `methods` / `fields`.
+ *   2. **Scope-resolution reconciliation** (`reconcileOwnership` in
+ *      `scope-resolution/pipeline/reconcile-ownership.ts`) registers
+ *      any `parsed.localDefs[i]` with a scope-resolution-corrected
+ *      `ownerId` that the legacy pass missed (Python class-body
+ *      methods are the canonical case). Idempotent.
+ *   3. **Finalize-orchestrator** calls `attachScopeIndexes(...)` to
+ *      stamp the materialized `ScopeResolutionIndexes` bundle onto
+ *      `model.scopes`. One-shot; throws on a second call.
+ *
+ * After these three phases, the model is effectively frozen:
+ *   - `attachScopeIndexes` applied `Object.freeze` to its bundle.
+ *   - Downstream passes receive the narrowed `SemanticModel` reader
+ *     handle (not `MutableSemanticModel`), so `.register()` /
+ *     `.clear()` / `attachScopeIndexes()` are structurally absent.
+ *
+ * See `scope-resolution/contract/scope-resolver.ts` Contract
+ * Invariant I9 for the scope-resolution-side rule and
+ * `ARCHITECTURE.md` § "Semantic-model source of truth" for the
+ * overall architecture.
+ */
+import type { TypeRegistry, MutableTypeRegistry } from './type-registry.js';
+import type { MethodRegistry, MutableMethodRegistry } from './method-registry.js';
+import type { FieldRegistry, MutableFieldRegistry } from './field-registry.js';
+import type { SymbolTableReader, SymbolTableWriter } from './symbol-table.js';
+import type { ScopeResolutionIndexes } from './scope-resolution-indexes.js';
+/**
+ * Aggregated read-only view of the semantic registries plus the nested
+ * file/callable SymbolTable.
+ *
+ * `symbols` is typed as {@link SymbolTableReader} — consumers can query
+ * symbols but cannot register new ones or trigger a reset. Callers that
+ * need to register symbols or reset state must hold a
+ * {@link MutableSemanticModel} reference instead, which widens
+ * `symbols` back to {@link SymbolTableWriter} and adds `clear()` on the
+ * model itself.
+ *
+ * This segregation is the runtime half of the principle of least
+ * authority: a resolver that receives `SemanticModel` physically cannot
+ * mutate the index, so it cannot desync the leaf from the owner-scoped
+ * registries even accidentally.
+ */
+export interface SemanticModel {
+    readonly types: TypeRegistry;
+    readonly methods: MethodRegistry;
+    readonly fields: FieldRegistry;
+    readonly symbols: SymbolTableReader;
+    /**
+     * Materialized scope-resolution indexes from RFC #909 Ring 2 PKG #921.
+     *
+     * `undefined` until the finalize-orchestrator attaches them. While
+     * `undefined`, the legacy DAG is the sole resolution surface; once set,
+     * resolvers whose language has `REGISTRY_PRIMARY_<LANG>=true` consult
+     * these indexes instead.
+     *
+     * The attach is a one-shot write (see `MutableSemanticModel`). Callers
+     * holding a read-only `SemanticModel` handle see either `undefined` or
+     * the final frozen bundle — never a half-populated view.
+     */
+    readonly scopes?: ScopeResolutionIndexes;
+}
+/** Mutable variant — exposes the MutableX registries, a Writer-typed
+ *  `symbols` facade, and a full-cascade reset. This is the interface
+ *  held by the lifecycle owner (pipeline, resolution-context); resolvers
+ *  that only query should hold the narrower {@link SemanticModel}. */
+export interface MutableSemanticModel extends SemanticModel {
+    readonly types: MutableTypeRegistry;
+    readonly methods: MutableMethodRegistry;
+    readonly fields: MutableFieldRegistry;
+    readonly symbols: SymbolTableWriter;
+    /** Clear all registries AND the nested SymbolTable. */
+    clear(): void;
+    /**
+     * Stamp the finalize-orchestrator's output onto this model.
+     *
+     * **One-shot write.** Throws when called a second time — the indexes are
+     * meant to be materialized once per ingestion run. `Object.freeze` is
+     * applied to the attached bundle so consumers cannot mutate after attach.
+     *
+     * `clear()` resets the attached bundle back to `undefined`, enabling a
+     * fresh re-ingestion to attach a new bundle.
+     */
+    attachScopeIndexes(indexes: ScopeResolutionIndexes): void;
+}
+export declare const createSemanticModel: () => MutableSemanticModel;