cgraphx 2.0.1 → 2.0.3

package/dist/core/code/engine/core/ingestion/model/method-registry.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * Method Registry
+ *
+ * Owner-scoped method index extracted from SymbolTable.
+ * Stores Method/Constructor/Function-with-ownerId symbols keyed by
+ * `ownerNodeId\0methodName` for O(1) lookup. Supports overloads
+ * (array values) and arity-based filtering.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMethodRegistry = void 0;
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+const createMethodRegistry = () => {
+    const methodByOwner = new Map();
+    // Secondary flat-by-name index. Values are the SAME SymbolDefinition
+    // references stored under `methodByOwner` — no copy, just a second key.
+    // Populated in lockstep by `register()` and emptied by `clear()`.
+    const methodsByName = new Map();
+    const EMPTY = Object.freeze([]);
+    // Set once when a Function+ownerId def lands here, powers the Tier 3
+    // dedup fast-path. Monotonic: never unset except on `clear()`.
+    let hasFunctionMethodsFlag = false;
+    const lookupMethodByOwner = (ownerNodeId, methodName, argCount) => {
+        const defs = methodByOwner.get(`${ownerNodeId}\0${methodName}`);
+        if (!defs || defs.length === 0)
+            return undefined;
+        // Arity narrowing: when an argCount is provided and there are multiple
+        // overloads, keep only those whose parameterCount can accommodate the
+        // call. This resolves arity-differing overloads (e.g. C++ `greet()` vs
+        // `greet(string)`) that share the same `ownerId + methodName` key.
+        //
+        // Candidates with `parameterCount === undefined` (extractor didn't
+        // populate the count — typically variadic or unknown) are retained
+        // conservatively so that legitimate variadic matches still resolve.
+        //
+        // Streaming loop avoids allocating a filtered array on the common
+        // "arity selects 0 or 1 match" path. We scan once, count arity
+        // matches, and only materialize a narrowed array if at least one
+        // match was found and at least one non-match exists. If arity rules
+        // out every candidate, fall back to the unfiltered set so the
+        // caller's fuzzy path still has something to work with.
+        let pool = defs;
+        if (argCount !== undefined && defs.length > 1) {
+            let matchedCount = 0;
+            let rejectedCount = 0;
+            for (const d of defs) {
+                if (d.parameterCount === undefined) {
+                    matchedCount++;
+                    continue;
+                }
+                const min = d.requiredParameterCount ?? d.parameterCount;
+                if (argCount >= min && argCount <= d.parameterCount)
+                    matchedCount++;
+                else
+                    rejectedCount++;
+            }
+            // Only narrow when the filter actually discriminates: at least one
+            // match AND at least one rejection. Pure-match and pure-reject
+            // paths both keep the unfiltered pool (the latter because fallback
+            // semantics demand it).
+            if (matchedCount > 0 && rejectedCount > 0) {
+                const arityMatched = [];
+                for (const d of defs) {
+                    if (d.parameterCount === undefined) {
+                        arityMatched.push(d);
+                        continue;
+                    }
+                    const min = d.requiredParameterCount ?? d.parameterCount;
+                    if (argCount >= min && argCount <= d.parameterCount)
+                        arityMatched.push(d);
+                }
+                pool = arityMatched;
+            }
+        }
+        if (pool.length === 1)
+            return pool[0];
+        // Multiple overloads after arity narrowing: return first if all share
+        // the same defined returnType (safe for chain resolution), undefined if
+        // return types differ (truly ambiguous — can't determine which overload).
+        const firstReturnType = pool[0].returnType;
+        if (firstReturnType === undefined)
+            return undefined;
+        for (let i = 1; i < pool.length; i++) {
+            if (pool[i].returnType !== firstReturnType)
+                return undefined;
+        }
+        return pool[0];
+    };
+    const lookupMethodByName = (name) => {
+        return methodsByName.get(name) ?? EMPTY;
+    };
+    const lookupAllByOwner = (ownerNodeId, methodName) => {
+        return methodByOwner.get(`${ownerNodeId}\0${methodName}`) ?? EMPTY;
+    };
+    const register = (ownerNodeId, methodName, def) => {
+        const key = `${ownerNodeId}\0${methodName}`;
+        const existing = methodByOwner.get(key);
+        if (existing) {
+            existing.push(def);
+        }
+        else {
+            methodByOwner.set(key, [def]);
+        }
+        const byName = methodsByName.get(methodName);
+        if (byName) {
+            byName.push(def);
+        }
+        else {
+            methodsByName.set(methodName, [def]);
+        }
+        // A `Function`-typed def reaching MethodRegistry means the worker
+        // emitted a Python/Rust/Kotlin class method as `Function + ownerId`.
+        // It was already written into `SymbolTable.callableByName` by the
+        // upstream Function callable-index gate, so the two indexes are no
+        // longer disjoint for this registry's lifetime — Tier 3 must dedup.
+        if (!hasFunctionMethodsFlag && def.type === 'Function') {
+            hasFunctionMethodsFlag = true;
+        }
+    };
+    const clear = () => {
+        methodByOwner.clear();
+        methodsByName.clear();
+        hasFunctionMethodsFlag = false;
+    };
+    return {
+        lookupMethodByOwner,
+        lookupMethodByName,
+        lookupAllByOwner,
+        register,
+        clear,
+        get hasFunctionMethods() {
+            return hasFunctionMethodsFlag;
+        },
+    };
+};
+exports.createMethodRegistry = createMethodRegistry;

package/dist/core/code/engine/core/ingestion/model/owned-members-lookup.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Owner-keyed member lookup for Step 2 (RFC #909 / PR #1656).
+ *
+ * Merges MethodRegistry + FieldRegistry hits for `(ownerDefId, memberName)`
+ * in O(1) map time per registry — no `defs.byId` scan. Callers that omit
+ * this helper and leave `ownedMembersByOwner` unset fall back to an O(|defs|)
+ * compatibility scan inside `lookupCore.collectOwnedMembers`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupOwnedMembersByOwner = lookupOwnedMembersByOwner;
+const EMPTY = Object.freeze([]);
+/**
+ * Production hook for `RegistryContext.ownedMembersByOwner`.
+ * Returns `[]` on miss (authoritative indexed empty) — never `undefined`.
+ *
+ * Merges hits from all three owner-keyed registries (methods, fields,
+ * nested types) under the same `(ownerDefId, memberName)` key. The
+ * caller's `acceptedKinds` filter in `lookupCore` picks the right subset.
+ */
+function lookupOwnedMembersByOwner(model, ownerDefId, memberName) {
+    const methods = model.methods.lookupAllByOwner(ownerDefId, memberName);
+    const fields = model.fields.lookupAllByOwner(ownerDefId, memberName);
+    const nestedTypes = model.types.lookupAllByOwner(ownerDefId, memberName);
+    const methodCount = methods.length;
+    const fieldCount = fields.length;
+    const typeCount = nestedTypes.length;
+    const total = methodCount + fieldCount + typeCount;
+    if (total === 0)
+        return EMPTY;
+    if (methodCount === total)
+        return methods;
+    if (fieldCount === total)
+        return fields;
+    if (typeCount === total)
+        return nestedTypes;
+    const merged = new Array(total);
+    let i = 0;
+    for (let j = 0; j < methodCount; j++)
+        merged[i++] = methods[j];
+    for (let j = 0; j < fieldCount; j++)
+        merged[i++] = fields[j];
+    for (let j = 0; j < typeCount; j++)
+        merged[i++] = nestedTypes[j];
+    return merged;
+}

package/dist/core/code/engine/core/ingestion/model/registration-table.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Registration Dispatch Table
+ *
+ * Behavior-grouped O(1) dispatch table for routing `SymbolTable.add()`
+ * registrations into the semantic registries. Replaces the cascading
+ * `if/else` ladder in `symbol-table.ts` with a `Map<NodeLabel, RoutingDecision>`
+ * whose entries point to closure-captured hooks.
+ *
+ * ## Ownership diagram
+ *
+ *     SemanticModel
+ *       ├── types   (TypeRegistry)    ← classLikeHook / implHook write here
+ *       ├── methods (MethodRegistry)  ← methodHook writes here
+ *       ├── fields  (FieldRegistry)   ← propertyHook writes here
+ *       └── symbols (SymbolTable)     ← owns fileIndex + callableByName,
+ *                                       calls dispatch() in add()
+ *
+ * ## Behavior groups (5 hooks, 13 table entries)
+ *
+ * | Group         | NodeLabel values                                  | Hook         | Skip callable? |
+ * |---------------|---------------------------------------------------|--------------|----------------|
+ * | class-like    | Class, Struct, Interface, Enum, Record, Trait     | classLikeHook    | no             |
+ * | method-like   | Method, Constructor                               | methodHook   | no             |
+ * | property      | Property                                          | propertyHook | YES            |
+ * | impl-block    | Impl                                              | implHook     | no             |
+ * | callable-only | Function, Macro, Delegate                         | (no entry)   | no             |
+ *
+ * Every other `NodeLabel` is "inert" — reached by `fileIndex` only. No
+ * specialized registry, no callable index append.
+ *
+ * ## How to add a new NodeLabel
+ *
+ * 1. Add the variant to the `NodeLabel` union in `cgraph-shared/src/graph/types.ts`.
+ * 2. Decide which behavior group it belongs to by asking "which lookups must
+ *    return this symbol?" (not "what language feature is it?"). A new Swift
+ *    `Extension` is class-like if you want owner-scoped method lookup on it;
+ *    a new Kotlin `Object` is class-like for the same reason.
+ * 3. Either:
+ *    - Add a table entry here pointing at one of the existing hooks, OR
+ *    - Add it to `CALLABLE_ONLY_LABELS` if it is a free callable, OR
+ *    - Add it to `INERT_LABELS` if it's metadata-only (File, Folder, Decorator,
+ *      etc.) — never queried via owner/class lookups.
+ * 4. If none of the above fit — the new kind needs a brand-new registry —
+ *    design the registry first in `model/`, then add a new hook closure
+ *    and table entries. Update `DISPATCH_LABELS` / the exhaustiveness guard
+ *    accordingly.
+ *
+ * The runtime exhaustiveness guard in `symbol-table.ts` will warn if a
+ * `NodeLabel` is missing from all three sets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRegistrationTable = exports.DISPATCH_LABELS = exports.INERT_LABELS = exports.CALLABLE_ONLY_LABELS = exports.ALL_NODE_LABELS = void 0;
+const symbol_table_js_1 = require("./symbol-table.js");
+/**
+ * **Single source of truth** for NodeLabel classification. Every NodeLabel
+ * has exactly one behavior category — enforced at compile time by the
+ * `as const satisfies Record<NodeLabel, LabelBehavior>` combo:
+ *
+ *   - **Completeness** — `Record<NodeLabel, LabelBehavior>` requires every
+ *     NodeLabel to be a key. Missing a label fails to compile with
+ *     "Property 'X' is missing in type ..." naming the drifted label.
+ *   - **No extras** — `satisfies` performs excess-property checking on
+ *     object literals, so a non-NodeLabel string key fails to compile.
+ *   - **No duplicates** — object keys are unique by construction. A label
+ *     cannot be classified into two categories by accident.
+ *   - **Valid values** — `LabelBehavior` is a narrow union, so a typo in
+ *     the category name fails to compile.
+ *
+ * Adding a new NodeLabel to `cgraph-shared`: TypeScript will flag this
+ * file as incomplete. Add the new label with its behavior category and
+ * the three `*_LABELS` Sets + `ALL_NODE_LABELS` array below are derived
+ * automatically — no separate list to update, no runtime drift detection
+ * needed.
+ *
+ * NOTE: `Type` and `CodeElement` are inert wrappers for language features
+ * that don't yet have a dedicated registry (typedefs, synthesized dynamic
+ * calls). If future work needs owner-scoped lookup for them, change their
+ * category to `'dispatch'` and add a hook in `createRegistrationTable`.
+ * Do not special-case them inside `SymbolTable.add()`.
+ */
+const LABEL_BEHAVIOR = {
+    // dispatch — owner-scoped registry writes
+    Class: 'dispatch',
+    Struct: 'dispatch',
+    Interface: 'dispatch',
+    Enum: 'dispatch',
+    Record: 'dispatch',
+    Trait: 'dispatch',
+    Method: 'dispatch',
+    Constructor: 'dispatch',
+    Property: 'dispatch',
+    Impl: 'dispatch',
+    // callable-only — file index + callableByName, no owner scope
+    Function: 'callable-only',
+    Macro: 'callable-only',
+    Delegate: 'callable-only',
+    // inert — file index only
+    Project: 'inert',
+    Package: 'inert',
+    Module: 'inert',
+    Folder: 'inert',
+    File: 'inert',
+    Variable: 'inert',
+    Decorator: 'inert',
+    Import: 'inert',
+    Type: 'inert',
+    CodeElement: 'inert',
+    Community: 'inert',
+    Process: 'inert',
+    Typedef: 'inert',
+    Union: 'inert',
+    Namespace: 'inert',
+    TypeAlias: 'inert',
+    Const: 'inert',
+    Static: 'inert',
+    Annotation: 'inert',
+    Template: 'inert',
+    Section: 'inert',
+    Route: 'inert',
+    Tool: 'inert',
+    // Taint/PDG substrate (issue #2080) — a control-flow node, never a
+    // symbol-resolution target. Inert: file index only, no owner scope.
+    BasicBlock: 'inert',
+    // Synthetic external-RPC-service node (spec §6.1). Never a symbol-resolution
+    // target — minted by rpc-edges / http-api-calls phases, not the bridge.
+    ExternalService: 'inert',
+};
+// ---------------------------------------------------------------------------
+// Derived runtime collections — all keyed off LABEL_BEHAVIOR
+// ---------------------------------------------------------------------------
+/**
+ * All known NodeLabels, derived from the keys of `LABEL_BEHAVIOR`. The
+ * `satisfies Record<NodeLabel, LabelBehavior>` bijection above proves
+ * that `Object.keys(LABEL_BEHAVIOR)` is exactly the NodeLabel set —
+ * the cast to `NodeLabel[]` is sound, not a type-system bypass.
+ *
+ * Consumers (e.g., the semantic-model barrel re-export for tests) can
+ * rely on this list being complete by construction. No runtime drift
+ * check is needed or possible — the type system is the proof.
+ */
+exports.ALL_NODE_LABELS = Object.keys(LABEL_BEHAVIOR);
+const labelsWithBehavior = (behavior) => exports.ALL_NODE_LABELS.filter((label) => LABEL_BEHAVIOR[label] === behavior);
+/**
+ * NodeLabel values that are free callables — appear in `callableByName`
+ * but have no owner-scoped specialized registry. Alias of
+ * {@link FREE_CALLABLE_TYPES} exported here for taxonomy-test use. The
+ * compile-time cross-invariant on `LABEL_BEHAVIOR` above guarantees the
+ * alias and the LABEL_BEHAVIOR `callable-only` classification cannot
+ * drift.
+ */
+exports.CALLABLE_ONLY_LABELS = symbol_table_js_1.FREE_CALLABLE_TYPES;
+/**
+ * NodeLabel values that touch only the file index — no specialized
+ * registry, no callable index.
+ */
+exports.INERT_LABELS = new Set(labelsWithBehavior('inert'));
+/**
+ * NodeLabel values that have a dispatch table entry. `createRegistrationTable`
+ * below must provide a hook for exactly this set — the test file's behavior-
+ * group tests and the integration tests pin the hook↔label correspondence.
+ */
+exports.DISPATCH_LABELS = new Set(labelsWithBehavior('dispatch'));
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Build the dispatch table. Must be called once per `createSymbolTable`
+ * invocation so each hook closes over that SymbolTable's injected
+ * registries. Reusing a single module-level instance would cause hooks
+ * to write into the wrong SemanticModel.
+ */
+const createRegistrationTable = (deps) => {
+    const { types, methods, fields } = deps;
+    // Hook 1: class-like — Class, Struct, Interface, Enum, Record, Trait.
+    // Shared reference — six table entries point at this one closure.
+    const classLikeHook = (name, def) => {
+        const qualifiedKey = def.qualifiedName ?? name;
+        types.registerClass(name, qualifiedKey, def);
+    };
+    // Hook 2: method-like — Method, Constructor. Silently skipped if the
+    // caller did not provide an ownerId (Property without ownerId is
+    // treated the same way).
+    const methodHook = (name, def) => {
+        if (def.ownerId) {
+            methods.register(def.ownerId, name, def);
+        }
+    };
+    // Hook 3: property — Property. Silently skipped without ownerId.
+    // Property is not in `FREE_CALLABLE_TYPES`, so `SymbolTable.add()` already
+    // excludes it from `callableByName`; common property names like
+    // `id` / `name` / `type` never pollute the callable index.
+    const propertyHook = (name, def) => {
+        if (def.ownerId) {
+            fields.register(def.ownerId, name, def);
+        }
+    };
+    // Hook 4: impl-block — Rust `impl` blocks. Kept separate from classLikeHook
+    // because heritage resolution must not treat Impls as class candidates
+    // (an Impl is not a parent type, it's an ancillary dispatch table).
+    const implHook = (name, def) => {
+        types.registerImpl(name, def);
+    };
+    // Single source of truth for the label → hook mapping. The
+    // `satisfies Record<DispatchLabel, RegistrationHook>` intersection
+    // fails at build time if (a) any label classified as 'dispatch' in
+    // `LABEL_BEHAVIOR` is missing here, or (b) any key here is not
+    // classified as 'dispatch'. This is the compile-time twin of the
+    // runtime taxonomy — no drift possible.
+    const dispatchByLabel = {
+        // class-like — six labels share the single `classLikeHook` closure,
+        // kept in lockstep with `CLASS_TYPES_TUPLE` via the
+        // `Record<ClassLikeLabel, 'dispatch'>` cross-invariant on
+        // `LABEL_BEHAVIOR`.
+        Class: classLikeHook,
+        Struct: classLikeHook,
+        Interface: classLikeHook,
+        Enum: classLikeHook,
+        Record: classLikeHook,
+        Trait: classLikeHook,
+        // method-like — routed via dispatch-key normalization in
+        // `wrappedAdd` so Function+ownerId also reaches `methodHook`.
+        Method: methodHook,
+        Constructor: methodHook,
+        // property — callable-index exclusion is enforced by
+        // `SymbolTable.add()` (Property is not in `FREE_CALLABLE_TYPES`).
+        Property: propertyHook,
+        // impl-block — Rust `impl` blocks. Separate from classLikeHook because
+        // heritage resolution must not treat Impls as class candidates.
+        Impl: implHook,
+    };
+    return new Map(Object.entries(dispatchByLabel));
+};
+exports.createRegistrationTable = createRegistrationTable;

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

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * MRO primitives.
+ *
+ * `c3Linearize` and its BFS helper `gatherAncestors` are pure functions over a
+ * `parentMap` (classId → parent ids). They carry no dependency on the semantic
+ * model or graph, so the model layer stays a pure leaf — `mro-processor.ts`
+ * (graph-level MRO emission) imports `c3Linearize` / `gatherAncestors` from here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.c3Linearize = c3Linearize;
+exports.gatherAncestors = gatherAncestors;
+/**
+ * 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.
+ */
+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).
+ *
+ * Re-exported for mro-processor.ts (graph-level MRO emission).
+ */
+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;
+}

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

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });