gitnexus 1.5.3 → 1.6.1

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

@@ -0,0 +1,224 @@
+/**
+ * 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 `gitnexus-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.
+ */
+import { FREE_CALLABLE_TYPES } from './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 `gitnexus-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',
+};
+// ---------------------------------------------------------------------------
+// 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.
+ */
+export const ALL_NODE_LABELS = Object.keys(LABEL_BEHAVIOR);
+const labelsWithBehavior = (behavior) => 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.
+ */
+export const CALLABLE_ONLY_LABELS = FREE_CALLABLE_TYPES;
+/**
+ * NodeLabel values that touch only the file index — no specialized
+ * registry, no callable index.
+ */
+export const 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.
+ */
+export const 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.
+ */
+export 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));
+};

package/dist/core/ingestion/model/resolution-context.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Resolution Context
+ *
+ * Single implementation of tiered name resolution.
+ *
+ * Resolution tiers (highest confidence first):
+ * 1. Same file (lookupExactAll — authoritative)
+ * 2a-named. Named binding chain (walkBindingChain via NamedImportMap)
+ * 2a. Import-scoped (iterate importedFiles with lookupExactAll per file)
+ * 2b. Package-scoped (iterate indexed files matching package dir with lookupExactAll)
+ * 3. Global (lookupClassByName + lookupImplByName + lookupCallableByName — consumers must check count)
+ *
+ * Each tier queries the minimum necessary scope directly:
+ * - Tier 2a iterates the caller's import set (O(imports) × O(1) lookupExactAll).
+ * - Tier 2b iterates all indexed files filtered by package dir
+ *   (O(files) × O(1) lookupExactAll — avoids a global name scan).
+ * - Tier 3 combines lookupClassByName + lookupImplByName + lookupCallableByName
+ *   (three O(1) index lookups with a narrow, type-specific result set).
+ */
+import type { SymbolDefinition } from './symbol-table.js';
+import type { MutableSemanticModel } from './semantic-model.js';
+/**
+ * A single named binding in a source file (e.g. `import { User as U }`).
+ * Stores both the resolved source path and the original exported name so
+ * that aliased imports can resolve U → User in the source file.
+ */
+export interface NamedImportBinding {
+    sourcePath: string;
+    exportedName: string;
+}
+/**
+ * Map<ImportingFilePath, Map<LocalName, NamedImportBinding>>.
+ *
+ * Tracks which specific names a file imports from which sources (TS / Python
+ * / Rust / Java-static / ...). Used to tighten Tier 2a resolution:
+ * `import { User } from './models'` means only `User` (not `Repo`) is
+ * visible from models.ts via this import.
+ */
+export type NamedImportMap = Map<string, Map<string, NamedImportBinding>>;
+/**
+ * Check if a file path is directly inside a package directory identified by
+ * its suffix. Used by Tier 2b package-scoped resolution (Go / C#).
+ */
+export declare function isFileInPackageDir(filePath: string, dirSuffix: string): boolean;
+/** Resolution tier for tracking, logging, and test assertions. */
+export type ResolutionTier = 'same-file' | 'import-scoped' | 'global';
+/** Tier-selected candidates with metadata. */
+export interface TieredCandidates {
+    readonly candidates: readonly SymbolDefinition[];
+    readonly tier: ResolutionTier;
+}
+/** Confidence scores per resolution tier. */
+export declare const TIER_CONFIDENCE: Record<ResolutionTier, number>;
+export type ImportMap = Map<string, Set<string>>;
+export type PackageMap = Map<string, Set<string>>;
+/** Maps callerFile → (moduleAlias → sourceFilePath) for Python namespace imports.
+ *  e.g. `import models` in app.py → moduleAliasMap.get('app.py')?.get('models') === 'models.py' */
+export type ModuleAliasMap = Map<string, Map<string, string>>;
+export interface ResolutionContext {
+    /**
+     * The only resolution API. Returns all candidates at the winning tier.
+     *
+     * Tier 3 ('global') returns ALL candidates regardless of count —
+     * consumers must check candidates.length and refuse ambiguous matches.
+     */
+    resolve(name: string, fromFile: string): TieredCandidates | null;
+    /** Semantic model — the top-level container for types, methods, fields,
+     *  and the nested file/callable SymbolTable. Typed as
+     *  {@link MutableSemanticModel} because `ResolutionContext` is the
+     *  lifecycle owner — the pipeline registers symbols through it during
+     *  the fan-out phase. Resolvers that only query should annotate their
+     *  own fields as {@link SemanticModel} to drop write access. */
+    readonly model: MutableSemanticModel;
+    /** Raw maps — used by import-processor to populate import data. */
+    readonly importMap: ImportMap;
+    readonly packageMap: PackageMap;
+    readonly namedImportMap: NamedImportMap;
+    /** Module-alias map for Python namespace imports: callerFile → (alias → sourceFile). */
+    readonly moduleAliasMap: ModuleAliasMap;
+    enableCache(filePath: string): void;
+    clearCache(): void;
+    getStats(): {
+        fileCount: number;
+        cacheHits: number;
+        cacheMisses: number;
+        tierSameFile: number;
+        tierImportScoped: number;
+        tierGlobal: number;
+        tierMiss: number;
+    };
+    clear(): void;
+}
+export declare const createResolutionContext: () => ResolutionContext;

package/dist/core/ingestion/model/resolution-context.js

@@ -0,0 +1,337 @@
+/**
+ * Resolution Context
+ *
+ * Single implementation of tiered name resolution.
+ *
+ * Resolution tiers (highest confidence first):
+ * 1. Same file (lookupExactAll — authoritative)
+ * 2a-named. Named binding chain (walkBindingChain via NamedImportMap)
+ * 2a. Import-scoped (iterate importedFiles with lookupExactAll per file)
+ * 2b. Package-scoped (iterate indexed files matching package dir with lookupExactAll)
+ * 3. Global (lookupClassByName + lookupImplByName + lookupCallableByName — consumers must check count)
+ *
+ * Each tier queries the minimum necessary scope directly:
+ * - Tier 2a iterates the caller's import set (O(imports) × O(1) lookupExactAll).
+ * - Tier 2b iterates all indexed files filtered by package dir
+ *   (O(files) × O(1) lookupExactAll — avoids a global name scan).
+ * - Tier 3 combines lookupClassByName + lookupImplByName + lookupCallableByName
+ *   (three O(1) index lookups with a narrow, type-specific result set).
+ */
+import { createSemanticModel } from './semantic-model.js';
+/**
+ * Check if a file path is directly inside a package directory identified by
+ * its suffix. Used by Tier 2b package-scoped resolution (Go / C#).
+ */
+export function isFileInPackageDir(filePath, dirSuffix) {
+    // Prepend '/' so paths like "internal/auth/service.go" match suffix "/internal/auth/"
+    const normalized = '/' + filePath.replace(/\\/g, '/');
+    if (!normalized.includes(dirSuffix))
+        return false;
+    const afterDir = normalized.substring(normalized.indexOf(dirSuffix) + dirSuffix.length);
+    return !afterDir.includes('/');
+}
+/** Maximum re-export hops walkBindingChain will follow before giving up.
+ *  A hard cap is needed to defend against pathological cycles that slip
+ *  past the `visited` Set (e.g. a binding chain whose key is equal by
+ *  string value but visits distinct modules). Five hops covers the
+ *  common TypeScript monorepo pattern (component → pkg/index →
+ *  packages/index → root/index → types/index). Chains longer than this
+ *  fall through to Tier 2a-import / Tier 2b / Tier 3 resolution, which
+ *  is a silent false-negative that the caller may or may not recover
+ *  from. If a real repo hits this limit, raise it — there is no
+ *  correctness reason to keep it at exactly 5. */
+const MAX_BINDING_CHAIN_DEPTH = 5;
+/**
+ * Walk a named-binding re-export chain through NamedImportMap.
+ *
+ * When file A imports { User } from B, and B re-exports { User } from C,
+ * the NamedImportMap for A points to B, but B has no User definition.
+ * This function follows the chain: A → B → C until a definition is found.
+ *
+ * Returns the definitions found at the end of the chain, or null if the
+ * chain breaks (missing binding, circular reference, or
+ * {@link MAX_BINDING_CHAIN_DEPTH} exceeded). Internal to
+ * resolution-context — not exported from the model barrel.
+ */
+function walkBindingChain(name, currentFilePath, symbolTable, namedImportMap) {
+    // Fast exit: most files have no named imports at all. Skip the Set
+    // allocation + loop entry on the common empty-binding path so resolve()
+    // stays allocation-free for the typical call site.
+    const firstBindings = namedImportMap.get(currentFilePath);
+    if (!firstBindings)
+        return null;
+    const firstBinding = firstBindings.get(name);
+    if (!firstBinding)
+        return null;
+    let lookupFile = currentFilePath;
+    let lookupName = name;
+    const visited = new Set();
+    for (let depth = 0; depth < MAX_BINDING_CHAIN_DEPTH; depth++) {
+        const bindings = depth === 0 ? firstBindings : namedImportMap.get(lookupFile);
+        if (!bindings)
+            return null;
+        const binding = depth === 0 ? firstBinding : bindings.get(lookupName);
+        if (!binding)
+            return null;
+        const key = `${binding.sourcePath}:${binding.exportedName}`;
+        if (visited.has(key))
+            return null; // circular
+        visited.add(key);
+        const targetName = binding.exportedName;
+        const resolvedDefs = symbolTable.lookupExactAll(binding.sourcePath, targetName);
+        if (resolvedDefs.length > 0)
+            return resolvedDefs;
+        // No definition in source file → follow re-export chain
+        lookupFile = binding.sourcePath;
+        lookupName = targetName;
+    }
+    return null;
+}
+/** Confidence scores per resolution tier. */
+export const TIER_CONFIDENCE = {
+    'same-file': 0.95,
+    'import-scoped': 0.9,
+    global: 0.5,
+};
+export const createResolutionContext = () => {
+    const model = createSemanticModel();
+    const symbols = model.symbols;
+    const importMap = new Map();
+    const packageMap = new Map();
+    const namedImportMap = new Map();
+    const moduleAliasMap = new Map();
+    // Inverted index: packageDirSuffix → Set<filePath>.
+    // Built lazily on first Tier 2b hit — one-time cost of O(totalFiles ×
+    // allUniqueDirSuffixes) isFileInPackageDir calls across the entire
+    // packageMap, amortized over the pipeline run. Subsequent Tier 2b
+    // resolutions are O(callerPackages × filesInPackage × O(1)).
+    let packageDirIndex = null;
+    // Per-file cache state
+    let cacheFile = null;
+    let cache = null;
+    let cacheHits = 0;
+    let cacheMisses = 0;
+    // Tier hit counters — replaces the lost fuzzyCallCount diagnostic
+    let tierSameFile = 0;
+    let tierImportScoped = 0;
+    let tierGlobal = 0;
+    let tierMiss = 0;
+    // --- Core resolution (single implementation of tier logic) ---
+    const resolveUncached = (name, fromFile) => {
+        // Tier 1: Same file — authoritative match (returns all overloads)
+        const localDefs = symbols.lookupExactAll(fromFile, name);
+        if (localDefs.length > 0) {
+            tierSameFile++;
+            return { candidates: localDefs, tier: 'same-file' };
+        }
+        // Tier 2a-named: Named binding chain (aliased / re-exported imports)
+        // Checked before import-scoped so that `import { User as U }` resolves
+        // correctly even when lookupExactAll on the alias name returns nothing.
+        const chainResult = walkBindingChain(name, fromFile, symbols, namedImportMap);
+        if (chainResult && chainResult.length > 0) {
+            tierImportScoped++;
+            return { candidates: chainResult, tier: 'import-scoped' };
+        }
+        // Tier 2a: Import-scoped — iterate the caller's imported files directly.
+        // O(importedFiles) × O(1) lookupExactAll — no global name scan needed.
+        const importedFiles = importMap.get(fromFile);
+        if (importedFiles) {
+            const importedDefs = [];
+            for (const file of importedFiles) {
+                importedDefs.push(...symbols.lookupExactAll(file, name));
+            }
+            if (importedDefs.length > 0) {
+                tierImportScoped++;
+                return { candidates: importedDefs, tier: 'import-scoped' };
+            }
+        }
+        // Tier 2b: Package-scoped — look up files in the caller's imported package
+        // directories via an inverted index (packageDirSuffix → Set<filePath>),
+        // then do O(1) lookupExactAll per file. The inverted index is built lazily
+        // on first Tier 2b hit by scanning symbols.getFiles() once, making
+        // subsequent Tier 2b resolutions O(packages × filesInPackage) instead of
+        // O(allFiles × packages).
+        const importedPackages = packageMap.get(fromFile);
+        if (importedPackages) {
+            // Lazily build the inverted index on first use. For each indexed file,
+            // test it against isFileInPackageDir for all known dirSuffixes collected
+            // from packageMap. This scans all files once (instead of per-resolution)
+            // and produces a dirSuffix → Set<filePath> map.
+            if (!packageDirIndex) {
+                // Collect all unique dir suffixes across the entire packageMap
+                const allDirSuffixes = new Set();
+                for (const dirs of packageMap.values()) {
+                    for (const d of dirs)
+                        allDirSuffixes.add(d);
+                }
+                packageDirIndex = new Map();
+                for (const file of symbols.getFiles()) {
+                    for (const dirSuffix of allDirSuffixes) {
+                        if (isFileInPackageDir(file, dirSuffix)) {
+                            let files = packageDirIndex.get(dirSuffix);
+                            if (!files) {
+                                files = new Set();
+                                packageDirIndex.set(dirSuffix, files);
+                            }
+                            files.add(file);
+                        }
+                    }
+                }
+            }
+            const packageDefs = [];
+            for (const dirSuffix of importedPackages) {
+                const filesInDir = packageDirIndex.get(dirSuffix);
+                if (filesInDir) {
+                    for (const file of filesInDir) {
+                        packageDefs.push(...symbols.lookupExactAll(file, name));
+                    }
+                }
+            }
+            if (packageDefs.length > 0) {
+                tierImportScoped++;
+                return { candidates: packageDefs, tier: 'import-scoped' };
+            }
+        }
+        // Tier 3: Global — targeted O(1) index lookups for each symbol category.
+        // Class-like symbols (Class, Struct, Interface, Enum, Record, Trait) are
+        // covered by lookupClassByName; Rust impl blocks by lookupImplByName
+        // (separate to avoid polluting heritage resolution); free callables
+        // (Function, Macro, Delegate) by lookupCallableByName; owner-scoped
+        // methods and constructors by `model.methods.lookupMethodByName`.
+        //
+        // FREE_CALLABLE_TYPES excludes Method/Constructor, so strictly-labeled
+        // methods are disjoint between the two indexes.
+        //
+        // Partial-state caveat: Python/Rust/Kotlin class methods are emitted
+        // as Function + ownerId — `rawSymbols.add` routes them through both
+        // the Function callable index AND, via the dispatch-key normalization
+        // in `wrappedAdd`, the method registry. The same `SymbolDefinition`
+        // reference lands in both `callableDefs` and `methodDefs`, so the
+        // Set-based dedup below is required.
+        //
+        // Known exclusion: TypeAlias, Const, and Variable are NOT reachable at
+        // Tier 3 — they don't belong to any of the indexes. TypeAlias is not
+        // a call target; Const/Variable are resolved via import or same-file
+        // tiers. Macro (C/C++) and Delegate (C#) stay in the callable index
+        // since call-processor.ts treats them as callable targets.
+        const classDefs = model.types.lookupClassByName(name);
+        const implDefs = model.types.lookupImplByName(name);
+        const callableDefs = symbols.lookupCallableByName(name);
+        const methodDefs = model.methods.lookupMethodByName(name);
+        if (classDefs.length === 0 &&
+            implDefs.length === 0 &&
+            callableDefs.length === 0 &&
+            methodDefs.length === 0) {
+            tierMiss++;
+            return null;
+        }
+        // Fast path: if no `Function + ownerId` class method was ever
+        // registered into the method registry (the only source of
+        // cross-index duplication), the callable and method indexes are
+        // guaranteed disjoint and we can concat without dedup.
+        if (!model.methods.hasFunctionMethods) {
+            const globalDefs = [
+                ...classDefs,
+                ...implDefs,
+                ...callableDefs,
+                ...methodDefs,
+            ];
+            tierGlobal++;
+            return { candidates: globalDefs, tier: 'global' };
+        }
+        // Slow path: dedup by nodeId because the same SymbolDefinition
+        // reference can land in both `callableDefs` (via the Function
+        // callable-index gate) and `methodDefs` (via the dispatch-key
+        // normalization routing Function+ownerId into MethodRegistry).
+        // Dedup covers all four index reads so any nodeId overlap (even
+        // theoretical ones between classDefs/implDefs) is caught.
+        const globalDefs = [];
+        const seen = new Set();
+        const pushUnique = (pool) => {
+            for (const def of pool) {
+                if (seen.has(def.nodeId))
+                    continue;
+                seen.add(def.nodeId);
+                globalDefs.push(def);
+            }
+        };
+        pushUnique(classDefs);
+        pushUnique(implDefs);
+        pushUnique(callableDefs);
+        pushUnique(methodDefs);
+        tierGlobal++;
+        return { candidates: globalDefs, tier: 'global' };
+    };
+    const resolve = (name, fromFile) => {
+        // Check cache (only when enabled AND fromFile matches cached file)
+        if (cache && cacheFile === fromFile) {
+            if (cache.has(name)) {
+                cacheHits++;
+                return cache.get(name);
+            }
+            cacheMisses++;
+        }
+        const result = resolveUncached(name, fromFile);
+        // Store in cache if active and file matches
+        if (cache && cacheFile === fromFile) {
+            cache.set(name, result);
+        }
+        return result;
+    };
+    // --- Cache lifecycle ---
+    const enableCache = (filePath) => {
+        cacheFile = filePath;
+        if (!cache)
+            cache = new Map();
+        else
+            cache.clear();
+    };
+    const clearCache = () => {
+        cacheFile = null;
+        // Reuse the Map instance — just clear entries to reduce GC pressure at scale.
+        cache?.clear();
+        // Note: packageDirIndex is NOT invalidated here. It is built lazily on
+        // first Tier 2b hit and remains valid across file boundaries because
+        // packageMap and the symbol file set are append-only during the calls
+        // phase (all parsing/import processing completes before resolution).
+        // Invalidating per-file would destroy the amortization benefit — the
+        // O(files × dirs) rebuild would run per-file instead of once.
+        // Full invalidation happens in clear() (pipeline reset).
+    };
+    const getStats = () => ({
+        ...symbols.getStats(),
+        cacheHits,
+        cacheMisses,
+        tierSameFile,
+        tierImportScoped,
+        tierGlobal,
+        tierMiss,
+    });
+    const clear = () => {
+        model.clear();
+        importMap.clear();
+        packageMap.clear();
+        namedImportMap.clear();
+        moduleAliasMap.clear();
+        packageDirIndex = null; // invalidate — will rebuild on next Tier 2b hit
+        clearCache();
+        cacheHits = 0;
+        cacheMisses = 0;
+        tierSameFile = 0;
+        tierImportScoped = 0;
+        tierGlobal = 0;
+        tierMiss = 0;
+    };
+    return {
+        resolve,
+        model,
+        importMap,
+        packageMap,
+        namedImportMap,
+        moduleAliasMap,
+        enableCache,
+        clearCache,
+        getStats,
+        clear,
+    };
+};