gitnexus 1.5.2 → 1.6.0

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

@@ -0,0 +1,86 @@
+/**
+ * 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
+ *
+ * ## DAG direction
+ *
+ *     gitnexus-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.
+ */
+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';
+/**
+ * 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;
+}
+/** 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;
+}
+export declare const createSemanticModel: () => MutableSemanticModel;

package/dist/core/ingestion/model/semantic-model.js

@@ -0,0 +1,120 @@
+/**
+ * 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
+ *
+ * ## DAG direction
+ *
+ *     gitnexus-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.
+ */
+import { createTypeRegistry } from './type-registry.js';
+import { createMethodRegistry } from './method-registry.js';
+import { createFieldRegistry } from './field-registry.js';
+import { createSymbolTable } from './symbol-table.js';
+import { createRegistrationTable } from './registration-table.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+//
+// NodeLabel taxonomy drift detection lives in `registration-table.ts` as a
+// pure compile-time check — the `LABEL_BEHAVIOR` map is
+// `Record<NodeLabel, LabelBehavior>` with `as const satisfies`, which proves
+// coverage, uniqueness, and no-extra-keys at build time. No runtime guard
+// is needed because drift is structurally impossible in the source.
+export const createSemanticModel = () => {
+    // 1. Create the pure, registry-unaware SymbolTable leaf.
+    // rawSymbols is the only handle in the codebase whose type (the
+    // internal createSymbolTable return) includes `.clear()`. cascadeClear
+    // below reaches it here; no external caller receives this variable.
+    const rawSymbols = createSymbolTable();
+    // 2. Create the three owner-scoped registries.
+    const types = createTypeRegistry();
+    const methods = createMethodRegistry();
+    const fields = createFieldRegistry();
+    // 3. Build the dispatch table, closed over THIS instance's registries.
+    const dispatchTable = createRegistrationTable({ types, methods, fields });
+    // 4. Wrap rawSymbols so `add()` fans out into the registries via the
+    //    dispatch table. See module JSDoc for the three-step contract.
+    const wrappedAdd = (filePath, name, nodeId, type, metadata) => {
+        const def = rawSymbols.add(filePath, name, nodeId, type, metadata);
+        // Function-with-ownerId (Python `def` in a class body, Rust trait
+        // method, Kotlin companion method) routes as Method. Keeps the
+        // dispatch table single-purpose.
+        const dispatchKey = type === 'Function' && metadata?.ownerId !== undefined ? 'Method' : type;
+        const hook = dispatchTable.get(dispatchKey);
+        if (hook) {
+            hook(name, def);
+        }
+        return def;
+    };
+    // Cascade clear: single source of truth for "reset the entire model".
+    // Wired into both `model.clear()` AND `model.symbols.clear()` so that a
+    // caller holding only a SymbolTable reference can't leave the
+    // owner-scoped registries populated while the file/callable indexes go
+    // empty (the phantom-resolution failure mode).
+    const cascadeClear = () => {
+        types.clear();
+        methods.clear();
+        fields.clear();
+        rawSymbols.clear();
+    };
+    // Writer-typed facade: exposes reads + add, but NO `clear` field.
+    // Callers holding a `SemanticModel.symbols` reference cannot desync
+    // the leaf indexes from the owner-scoped registries. Consumers that
+    // only query should widen their annotation to SymbolTableReader for
+    // least-authority clarity.
+    const symbols = {
+        add: wrappedAdd,
+        lookupExact: rawSymbols.lookupExact,
+        lookupExactFull: rawSymbols.lookupExactFull,
+        lookupExactAll: rawSymbols.lookupExactAll,
+        lookupCallableByName: rawSymbols.lookupCallableByName,
+        getFiles: rawSymbols.getFiles,
+        getStats: rawSymbols.getStats,
+    };
+    return {
+        types,
+        methods,
+        fields,
+        symbols,
+        clear: cascadeClear,
+    };
+};

package/dist/core/ingestion/model/symbol-table.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Symbol Table — file-indexed + callable-name symbol storage.
+ *
+ * This module is a PURE LEAF in the ingestion DAG. It owns two orthogonal
+ * O(1) indexes:
+ *
+ *   1. fileIndex      — Map<filePath, Map<name, SymbolDefinition[]>>
+ *                       for same-file lookups (Tier 1 resolution)
+ *   2. callableByName — Map<name, SymbolDefinition[]>
+ *                       for name-keyed callable lookups (Tier 3 widen)
+ *
+ * SymbolTable deliberately knows NOTHING about the owner-scoped registries
+ * (types, methods, fields) that sit above it in the DAG. Those registries
+ * live in `model/` and depend on SymbolTable, not the other way around.
+ * {@link createSemanticModel} composes this pure SymbolTable with the
+ * registries and wraps `add()` to fan out registrations into both layers.
+ *
+ * DAG direction (strictly enforced):
+ *
+ *     gitnexus-shared (NodeLabel)       — leaf type
+ *          ↑
+ *     symbol-table.ts                   — THIS FILE (pure storage)
+ *          ↑
+ *     model/type-registry.ts, method-registry.ts, field-registry.ts
+ *          ↑
+ *     model/registration-table.ts       — dispatch table factory
+ *          ↑
+ *     model/semantic-model.ts           — orchestrator, wraps add()
+ *          ↑
+ *     model/resolve.ts, call-processor.ts, resolution-context.ts, ...
+ *
+ * No arrow ever points downward from this file. If you are tempted to
+ * import from `./model/` here, you are going the wrong way — move the
+ * logic up the DAG instead.
+ */
+import type { NodeLabel } from '../../../_shared/index.js';
+/**
+ * Class-like NodeLabels — used for qualifiedName fallback inside
+ * `SymbolTable.add()` and (via import into `model/registration-table.ts`)
+ * as the single source of truth for which labels route to classHook
+ * in the dispatch table.
+ *
+ * Exported as a `readonly` tuple so that `typeof CLASS_TYPES_TUPLE[number]`
+ * yields a precise literal union (`ClassLikeLabel`). The model layer
+ * imports this tuple and uses `Record<ClassLikeLabel, 'dispatch'>` in a
+ * `satisfies` intersection to enforce at COMPILE TIME that every label
+ * listed here is also classified as dispatch in `LABEL_BEHAVIOR`. Adding
+ * a new class-like label to this tuple without updating `LABEL_BEHAVIOR`
+ * fails TypeScript.
+ *
+ * Traits are class-like for heritage resolution: PHP `use Trait;`, Rust
+ * `impl Trait for Struct`, and Scala traits all contribute methods to the
+ * hierarchy of their using/implementing type.
+ */
+export declare const CLASS_TYPES_TUPLE: readonly ["Class", "Struct", "Interface", "Enum", "Record", "Trait"];
+export type ClassLikeLabel = (typeof CLASS_TYPES_TUPLE)[number];
+export declare const CLASS_TYPES: ReadonlySet<NodeLabel>;
+/** Free-callable labels — single source of truth for "callables that have
+ *  NO owner scope". Methods and constructors are owner-scoped and live in
+ *  `MethodRegistry` — Tier 3 reaches them via
+ *  `model.methods.lookupMethodByName`. See `resolution-context.ts` Tier 3
+ *  for how both indexes are consulted together.
+ *
+ *  Exported as a `readonly` tuple so that `typeof FREE_CALLABLE_TUPLE[number]`
+ *  yields a precise literal union (`FreeCallableLabel`). `registration-table.ts`
+ *  imports this type and uses `Record<FreeCallableLabel, 'callable-only'>` in
+ *  a `satisfies` intersection to enforce at COMPILE TIME that every label
+ *  listed here is also classified as `callable-only` in `LABEL_BEHAVIOR`.
+ *  Adding a label to this tuple without updating `LABEL_BEHAVIOR` fails
+ *  TypeScript.
+ *
+ *  Partial-state caveat: Python/Rust/Kotlin class methods are emitted by
+ *  the worker as `Function` + `ownerId` (not `Method`), so they still land
+ *  here via the `Function` entry. Collapsing those three languages onto the
+ *  `Method` label is pending a `def.type` preservation decision.
+ */
+export declare const FREE_CALLABLE_TUPLE: readonly ["Function", "Macro", "Delegate"];
+export type FreeCallableLabel = (typeof FREE_CALLABLE_TUPLE)[number];
+export declare const FREE_CALLABLE_TYPES: ReadonlySet<NodeLabel>;
+/** Symbol types that can be the TARGET of a call in the resolver's kind
+ *  filter — superset of {@link FREE_CALLABLE_TYPES} that also admits
+ *  owner-scoped methods and constructors pulled in from `MethodRegistry`.
+ *
+ *  Why the split: `FREE_CALLABLE_TYPES` now has a narrow meaning (free
+ *  callables indexed in `callableByName`), but call resolution still
+ *  needs to accept Method and Constructor candidates once they have been
+ *  unioned in from `model.methods.lookupMethodByName`. The resolver uses
+ *  this constant for kind filtering in
+ *  `filterCallableCandidates` / `countCallableCandidates`.
+ */
+export declare const CALL_TARGET_TYPES: ReadonlySet<NodeLabel>;
+export interface SymbolDefinition {
+    nodeId: string;
+    filePath: string;
+    type: NodeLabel;
+    /** Canonical dot-separated qualified type name for class-like symbols
+     *  (e.g. `App.Models.User`). Falls back to the simple symbol name when no
+     *  package/namespace/module scope exists or no explicit qualified metadata is provided. */
+    qualifiedName?: string;
+    parameterCount?: number;
+    /** Number of required (non-optional, non-default) parameters.
+     *  Enables range-based arity filtering: argCount >= requiredParameterCount && argCount <= parameterCount. */
+    requiredParameterCount?: number;
+    /** Per-parameter type names for overload disambiguation (e.g. ['int', 'String']).
+     *  Populated when parameter types are resolvable from AST (any typed language). */
+    parameterTypes?: string[];
+    /** Raw return type text extracted from AST (e.g. 'User', 'Promise<User>') */
+    returnType?: string;
+    /** Declared type for non-callable symbols — fields/properties (e.g. 'Address', 'List<User>') */
+    declaredType?: string;
+    /** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */
+    ownerId?: string;
+}
+/**
+ * Optional metadata accepted by {@link SymbolTable.add}. Kept as a separate
+ * type alias so callers and wrappers can share the same shape.
+ */
+export interface AddMetadata {
+    parameterCount?: number;
+    requiredParameterCount?: number;
+    parameterTypes?: string[];
+    returnType?: string;
+    declaredType?: string;
+    ownerId?: string;
+    qualifiedName?: string;
+}
+/**
+ * Pure read-only view over the file and callable indexes. Does NOT
+ * include `add()` or `clear()`.
+ *
+ * Used by consumers that only query symbols (resolvers, type-env, field
+ * extractors). The interface is strictly observational — holding a
+ * `SymbolTableReader` cannot mutate the table in any way.
+ *
+ * For consumers that also need to register symbols, use
+ * {@link SymbolTableWriter}, which extends this interface with `add()`.
+ * Neither interface exposes `clear()` — that capability lives on the
+ * internal factory return type and is reachable only inside
+ * `SemanticModel` via `rawSymbols`.
+ *
+ * Segregating the observer contract from the mutation contract means
+ * callers holding only a Reader can never desync the model.
+ */
+export interface SymbolTableReader {
+    /**
+     * High Confidence: Look for a symbol specifically inside a file.
+     * Returns the Node ID if found.
+     */
+    lookupExact: (filePath: string, name: string) => string | undefined;
+    /**
+     * High Confidence: Look for a symbol in a specific file, returning full definition.
+     * Returns first matching definition — use lookupExactAll for overloaded methods.
+     */
+    lookupExactFull: (filePath: string, name: string) => SymbolDefinition | undefined;
+    /**
+     * High Confidence: Look for ALL symbols with this name in a specific file.
+     * Returns all definitions, including overloaded methods with the same name.
+     * The returned array is a view into the live internal index — callers
+     * MUST NOT mutate it. Use `readonly` to enforce this at the type level.
+     */
+    lookupExactAll: (filePath: string, name: string) => readonly SymbolDefinition[];
+    /**
+     * Look up callable symbols (Function, Macro, Delegate) by name.
+     * O(1) via dedicated eagerly-populated index keyed by symbol name.
+     * Returned array is a view into the live index — do not mutate.
+     */
+    lookupCallableByName: (name: string) => readonly SymbolDefinition[];
+    /**
+     * Iterate all indexed file paths.
+     * Used by Tier 2b (package-scoped) resolution to walk files matching a
+     * package directory suffix without a global name scan.
+     */
+    getFiles: () => IterableIterator<string>;
+    /**
+     * Debugging: See how many files are tracked.
+     */
+    getStats: () => {
+        fileCount: number;
+    };
+}
+/**
+ * Writer view — reads + symbol registration. Does NOT include `clear()`.
+ *
+ * `MutableSemanticModel.symbols` is typed as this interface, so the
+ * lifecycle owner can register symbols and query them. Full-model
+ * resets flow through `model.clear()`.
+ *
+ * The cascading `clear()` capability lives exclusively on the internal
+ * factory return type ({@link createSymbolTable}) — a private handle
+ * held only by `SemanticModel` via `rawSymbols`.
+ */
+export interface SymbolTableWriter extends SymbolTableReader {
+    /**
+     * Register a symbol in the file and (if callable) name-keyed indexes.
+     *
+     * Returns the constructed {@link SymbolDefinition} so higher-layer
+     * wrappers (e.g. `createSemanticModel`) can reuse it without rebuilding
+     * the def. This keeps the fan-out in one allocation.
+     */
+    add: (filePath: string, name: string, nodeId: string, type: NodeLabel, metadata?: AddMetadata) => SymbolDefinition;
+}
+/**
+ * Internal return type for {@link createSymbolTable} — extends the
+ * writer with `clear()`. This capability is intentionally NOT exported
+ * as a named interface; consumers should hold a `SymbolTableReader` or
+ * `SymbolTableWriter` instead.
+ *
+ * `SemanticModel`'s constructor is the only caller of `createSymbolTable`,
+ * and it retains the returned handle as the private `rawSymbols`
+ * reference so `cascadeClear` can reach `clear()`. Every other consumer
+ * receives the narrower `SymbolTableWriter` facade on `model.symbols`.
+ */
+interface InternalSymbolTable extends SymbolTableWriter {
+    /**
+     * Cleanup memory. Clears only the file and callable indexes owned here —
+     * owner-scoped registries are cleared by their respective owners via
+     * `model.clear()`.
+     */
+    clear: () => void;
+}
+export declare const createSymbolTable: () => InternalSymbolTable;
+export {};

package/dist/core/ingestion/model/symbol-table.js

@@ -0,0 +1,206 @@
+/**
+ * Symbol Table — file-indexed + callable-name symbol storage.
+ *
+ * This module is a PURE LEAF in the ingestion DAG. It owns two orthogonal
+ * O(1) indexes:
+ *
+ *   1. fileIndex      — Map<filePath, Map<name, SymbolDefinition[]>>
+ *                       for same-file lookups (Tier 1 resolution)
+ *   2. callableByName — Map<name, SymbolDefinition[]>
+ *                       for name-keyed callable lookups (Tier 3 widen)
+ *
+ * SymbolTable deliberately knows NOTHING about the owner-scoped registries
+ * (types, methods, fields) that sit above it in the DAG. Those registries
+ * live in `model/` and depend on SymbolTable, not the other way around.
+ * {@link createSemanticModel} composes this pure SymbolTable with the
+ * registries and wraps `add()` to fan out registrations into both layers.
+ *
+ * DAG direction (strictly enforced):
+ *
+ *     gitnexus-shared (NodeLabel)       — leaf type
+ *          ↑
+ *     symbol-table.ts                   — THIS FILE (pure storage)
+ *          ↑
+ *     model/type-registry.ts, method-registry.ts, field-registry.ts
+ *          ↑
+ *     model/registration-table.ts       — dispatch table factory
+ *          ↑
+ *     model/semantic-model.ts           — orchestrator, wraps add()
+ *          ↑
+ *     model/resolve.ts, call-processor.ts, resolution-context.ts, ...
+ *
+ * No arrow ever points downward from this file. If you are tempted to
+ * import from `./model/` here, you are going the wrong way — move the
+ * logic up the DAG instead.
+ */
+/**
+ * Class-like NodeLabels — used for qualifiedName fallback inside
+ * `SymbolTable.add()` and (via import into `model/registration-table.ts`)
+ * as the single source of truth for which labels route to classHook
+ * in the dispatch table.
+ *
+ * Exported as a `readonly` tuple so that `typeof CLASS_TYPES_TUPLE[number]`
+ * yields a precise literal union (`ClassLikeLabel`). The model layer
+ * imports this tuple and uses `Record<ClassLikeLabel, 'dispatch'>` in a
+ * `satisfies` intersection to enforce at COMPILE TIME that every label
+ * listed here is also classified as dispatch in `LABEL_BEHAVIOR`. Adding
+ * a new class-like label to this tuple without updating `LABEL_BEHAVIOR`
+ * fails TypeScript.
+ *
+ * Traits are class-like for heritage resolution: PHP `use Trait;`, Rust
+ * `impl Trait for Struct`, and Scala traits all contribute methods to the
+ * hierarchy of their using/implementing type.
+ */
+export const CLASS_TYPES_TUPLE = [
+    'Class',
+    'Struct',
+    'Interface',
+    'Enum',
+    'Record',
+    'Trait',
+];
+export const CLASS_TYPES = new Set(CLASS_TYPES_TUPLE);
+/** Free-callable labels — single source of truth for "callables that have
+ *  NO owner scope". Methods and constructors are owner-scoped and live in
+ *  `MethodRegistry` — Tier 3 reaches them via
+ *  `model.methods.lookupMethodByName`. See `resolution-context.ts` Tier 3
+ *  for how both indexes are consulted together.
+ *
+ *  Exported as a `readonly` tuple so that `typeof FREE_CALLABLE_TUPLE[number]`
+ *  yields a precise literal union (`FreeCallableLabel`). `registration-table.ts`
+ *  imports this type and uses `Record<FreeCallableLabel, 'callable-only'>` in
+ *  a `satisfies` intersection to enforce at COMPILE TIME that every label
+ *  listed here is also classified as `callable-only` in `LABEL_BEHAVIOR`.
+ *  Adding a label to this tuple without updating `LABEL_BEHAVIOR` fails
+ *  TypeScript.
+ *
+ *  Partial-state caveat: Python/Rust/Kotlin class methods are emitted by
+ *  the worker as `Function` + `ownerId` (not `Method`), so they still land
+ *  here via the `Function` entry. Collapsing those three languages onto the
+ *  `Method` label is pending a `def.type` preservation decision.
+ */
+export const FREE_CALLABLE_TUPLE = [
+    'Function',
+    'Macro', // C/C++
+    'Delegate', // C#
+];
+export const FREE_CALLABLE_TYPES = new Set(FREE_CALLABLE_TUPLE);
+/** Symbol types that can be the TARGET of a call in the resolver's kind
+ *  filter — superset of {@link FREE_CALLABLE_TYPES} that also admits
+ *  owner-scoped methods and constructors pulled in from `MethodRegistry`.
+ *
+ *  Why the split: `FREE_CALLABLE_TYPES` now has a narrow meaning (free
+ *  callables indexed in `callableByName`), but call resolution still
+ *  needs to accept Method and Constructor candidates once they have been
+ *  unioned in from `model.methods.lookupMethodByName`. The resolver uses
+ *  this constant for kind filtering in
+ *  `filterCallableCandidates` / `countCallableCandidates`.
+ */
+export const CALL_TARGET_TYPES = new Set([
+    ...FREE_CALLABLE_TYPES,
+    'Method',
+    'Constructor',
+]);
+export const createSymbolTable = () => {
+    // 1. File-Specific Index — stores full SymbolDefinition(s) for O(1) lookup.
+    // Structure: FilePath -> (SymbolName -> SymbolDefinition[])
+    // Array allows overloaded methods (same name, different signatures) to coexist.
+    const fileIndex = new Map();
+    // 2. Eagerly-populated Callable Index — maintained on add().
+    // Structure: SymbolName -> [Callable Definitions]
+    // Only Function, Method, Constructor, Macro, Delegate symbols are indexed.
+    const callableByName = new Map();
+    const add = (filePath, name, nodeId, type, metadata) => {
+        const qualifiedName = CLASS_TYPES.has(type)
+            ? (metadata?.qualifiedName ?? name)
+            : metadata?.qualifiedName;
+        const def = {
+            nodeId,
+            filePath,
+            type,
+            ...(qualifiedName !== undefined ? { qualifiedName } : {}),
+            ...(metadata?.parameterCount !== undefined
+                ? { parameterCount: metadata.parameterCount }
+                : {}),
+            ...(metadata?.requiredParameterCount !== undefined
+                ? { requiredParameterCount: metadata.requiredParameterCount }
+                : {}),
+            ...(metadata?.parameterTypes !== undefined
+                ? { parameterTypes: metadata.parameterTypes }
+                : {}),
+            ...(metadata?.returnType !== undefined ? { returnType: metadata.returnType } : {}),
+            ...(metadata?.declaredType !== undefined ? { declaredType: metadata.declaredType } : {}),
+            ...(metadata?.ownerId !== undefined ? { ownerId: metadata.ownerId } : {}),
+        };
+        // A. File Index — unconditional.
+        if (!fileIndex.has(filePath)) {
+            fileIndex.set(filePath, new Map());
+        }
+        const fileMap = fileIndex.get(filePath);
+        if (!fileMap.has(name)) {
+            fileMap.set(name, [def]);
+        }
+        else {
+            fileMap.get(name).push(def);
+        }
+        // B. Callable Index — gated by FREE_CALLABLE_TYPES.
+        //    Note: Property is NOT in FREE_CALLABLE_TYPES, so it never lands here.
+        //    This is the single source of truth for callable-index membership;
+        //    the higher-layer dispatch table only decides owner-scoped routing.
+        //
+        //    Fallback: `Method` or `Constructor` without an `ownerId` is an
+        //    extractor contract violation (AST-degraded parse, or a buggy
+        //    language extractor). The owner-scoped dispatch hook silently
+        //    skips such defs because it has no owner to key them under, so
+        //    without this fallback they would be invisible at Tier 3 global
+        //    resolution. Route them through `callableByName` so they remain
+        //    reachable by name — matching pre-dispatch-table behavior.
+        const isOrphanedOwnerScoped = (type === 'Method' || type === 'Constructor') && metadata?.ownerId === undefined;
+        if (FREE_CALLABLE_TYPES.has(type) || isOrphanedOwnerScoped) {
+            const existing = callableByName.get(name);
+            if (existing) {
+                existing.push(def);
+            }
+            else {
+                callableByName.set(name, [def]);
+            }
+        }
+        return def;
+    };
+    const lookupExact = (filePath, name) => {
+        const defs = fileIndex.get(filePath)?.get(name);
+        return defs?.[0]?.nodeId;
+    };
+    const lookupExactFull = (filePath, name) => {
+        const defs = fileIndex.get(filePath)?.get(name);
+        return defs?.[0];
+    };
+    const lookupExactAll = (filePath, name) => {
+        return fileIndex.get(filePath)?.get(name) ?? [];
+    };
+    const lookupCallableByName = (name) => {
+        return callableByName.get(name) ?? [];
+    };
+    /** Returns a live iterator over all indexed file paths (fileIndex.keys()).
+     *  The iterator is invalidated if add() changes fileIndex.size during
+     *  iteration (ES2015 Map spec). Safe in the current pipeline because all
+     *  symbols are added before resolution begins. */
+    const getFiles = () => fileIndex.keys();
+    const getStats = () => ({
+        fileCount: fileIndex.size,
+    });
+    const clear = () => {
+        fileIndex.clear();
+        callableByName.clear();
+    };
+    return {
+        add,
+        lookupExact,
+        lookupExactFull,
+        lookupExactAll,
+        lookupCallableByName,
+        getFiles,
+        getStats,
+        clear,
+    };
+};

package/dist/core/ingestion/model/type-registry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Type Registry
+ *
+ * Class/struct/interface index extracted from SymbolTable.
+ * Eagerly-populated indexes keyed by symbol name and qualified name.
+ * Also includes a separate index for Rust Impl blocks.
+ */
+import type { SymbolDefinition } from './symbol-table.js';
+export interface TypeRegistry {
+    /**
+     * Look up class-like definitions (Class, Struct, Interface, Enum, Record, Trait)
+     * by simple name. Returns all matching definitions across files
+     * (e.g. partial classes). Returned array is a view into the live
+     * internal index — do not mutate.
+     */
+    lookupClassByName(name: string): readonly SymbolDefinition[];
+    /**
+     * Look up class-like definitions by canonical qualified name.
+     * Qualified names are normalized to dot-separated scope segments across languages,
+     * e.g. `App.Models.User`, `com.example.User`, or `Admin.User`.
+     * Returned array is a view into the live index — do not mutate.
+     */
+    lookupClassByQualifiedName(qualifiedName: string): readonly SymbolDefinition[];
+    /**
+     * Look up Impl nodes by name. Used by Tier 3 resolution to include Rust
+     * impl blocks alongside class-like candidates.
+     * Returned array is a view into the live index — do not mutate.
+     */
+    lookupImplByName(name: string): readonly SymbolDefinition[];
+}
+export interface MutableTypeRegistry extends TypeRegistry {
+    /** Register a class-like type by name and qualified name. */
+    registerClass(name: string, qualifiedName: string, def: SymbolDefinition): void;
+    /** Register a Rust Impl block by name. */
+    registerImpl(name: string, def: SymbolDefinition): void;
+    /** Clear all entries. */
+    clear(): void;
+}
+export declare const createTypeRegistry: () => MutableTypeRegistry;