arceus-s 1.6.4

package/dist/core/ingestion/model/field-registry.js

@@ -0,0 +1,22 @@
+/**
+ * Field Registry
+ *
+ * Owner-scoped field/property index extracted from SymbolTable.
+ * Stores Property symbols keyed by `ownerNodeId\0fieldName` for O(1) lookup.
+ */
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export const createFieldRegistry = () => {
+    const fieldByOwner = new Map();
+    const lookupFieldByOwner = (ownerNodeId, fieldName) => {
+        return fieldByOwner.get(`${ownerNodeId}\0${fieldName}`);
+    };
+    const register = (ownerNodeId, fieldName, def) => {
+        fieldByOwner.set(`${ownerNodeId}\0${fieldName}`, def);
+    };
+    const clear = () => {
+        fieldByOwner.clear();
+    };
+    return { lookupFieldByOwner, register, clear };
+};

package/dist/core/ingestion/model/heritage-map.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Heritage Map
+ *
+ * Unified inheritance data structure built from accumulated
+ * {@link ExtractedHeritage} records **after all chunks complete** (between
+ * chunk processing and call resolution). Consumes `ExtractedHeritage[]` and
+ * resolves type names to nodeIds via `lookupClassByName`, NOT graph-edge
+ * queries.
+ *
+ * Combines two concerns:
+ * 1. **Parent/ancestor lookup** (MRO-aware method resolution)
+ * 2. **Implementor lookup** (interface dispatch — which files contain
+ *    classes implementing a given interface)
+ */
+import type { ResolutionContext } from './resolution-context.js';
+import { type SupportedLanguages } from '../../../_shared/index.js';
+export interface ExtractedHeritage {
+    filePath: string;
+    className: string;
+    parentName: string;
+    /** 'extends' | 'implements' | 'trait-impl' | 'include' | 'extend' | 'prepend' */
+    kind: string;
+}
+export interface HeritageResolutionStrategy {
+    /** If set and the parent name matches, force IMPLEMENTS even when the
+     *  symbol is unresolved (e.g. `/^I[A-Z]/` for C# / Java). */
+    readonly interfaceNamePattern?: RegExp;
+    /** Fallback edge for unresolved parents when the name pattern doesn't
+     *  match (Swift uses 'IMPLEMENTS' for protocol conformance). */
+    readonly defaultEdge: 'EXTENDS' | 'IMPLEMENTS';
+}
+/** Callback used by `buildHeritageMap` to look up the resolution strategy
+ *  for a given language. Injected by callers so the model module doesn't
+ *  depend on `../languages/index.js`. */
+export type HeritageStrategyLookup = (lang: SupportedLanguages) => HeritageResolutionStrategy;
+/**
+ * Determine whether a heritage.extends capture is actually an IMPLEMENTS
+ * relationship. Consults the symbol table first (authoritative — Tier 1 /
+ * Tier 2 resolution); falls back to the injected {@link HeritageResolutionStrategy}
+ * heuristics for external symbols not present in the graph.
+ */
+export declare const resolveExtendsType: (parentName: string, currentFilePath: string, ctx: ResolutionContext, strategy: HeritageResolutionStrategy) => {
+    type: "EXTENDS" | "IMPLEMENTS";
+    idPrefix: string;
+};
+/**
+ * Direct parent entry with the heritage kind that produced it. Preserved
+ * so kind-aware consumers (Ruby MRO, see `lookupMethodByOwnerWithMRO`) can
+ * walk prepend/include providers in the correct order. Flat-string consumers
+ * use `getParents` / `getAncestors` and see only the parent nodeIds.
+ */
+export interface ParentEntry {
+    readonly parentId: string;
+    /** 'extends' | 'implements' | 'trait-impl' | 'include' | 'extend' | 'prepend' */
+    readonly kind: string;
+}
+export interface HeritageMap {
+    /** Direct parents of `childNodeId` (extends + implements + trait-impl). */
+    getParents(childNodeId: string): string[];
+    /** Full ancestor chain (BFS, bounded depth, cycle-safe). */
+    getAncestors(childNodeId: string): string[];
+    /**
+     * Direct parents with heritage kind preserved, insertion-ordered. Used by
+     * kind-aware consumers (Ruby MRO) that need to distinguish prepend /
+     * include / extend / extends for walk-order decisions.
+     *
+     * Insertion order mirrors the order `ExtractedHeritage` records were fed
+     * into `buildHeritageMap`, which in turn mirrors tree-sitter match order.
+     * For Ruby, this matches source declaration order for `prepend` / `include`
+     * statements — the MRO walk reverses this (last-declared-first) at the
+     * consumer side.
+     */
+    getParentEntries(childNodeId: string): readonly ParentEntry[];
+    /**
+     * Ordered ancestry for instance method dispatch (Ruby-aware): includes
+     * `extends`, `implements`, `trait-impl`, `include`, `prepend` kinds.
+     * Excludes `extend` (singleton-only). Order is caller-determined in Unit 3.
+     * For non-Ruby callers (first-wins, c3, etc.), this matches `getAncestors`.
+     */
+    getInstanceAncestry(childNodeId: string): readonly ParentEntry[];
+    /**
+     * Ordered ancestry for singleton / class-method dispatch (Ruby-aware):
+     * only `extend` kind parents. For non-Ruby languages this is always empty.
+     */
+    getSingletonAncestry(childNodeId: string): readonly ParentEntry[];
+    /**
+     * File paths of classes that directly implement or extend-as-interface the
+     * given interface/abstract-class **name**. Replaces the standalone
+     * `ImplementorMap` — used by interface-dispatch in call resolution.
+     */
+    getImplementorFiles(interfaceName: string): ReadonlySet<string>;
+}
+/**
+ * Build a HeritageMap from accumulated ExtractedHeritage records.
+ *
+ * Resolves class/interface/struct/trait names to nodeIds via
+ * `ctx.model.types.lookupClassByName`. When a name resolves to multiple
+ * candidates, all are recorded (partial-class / cross-file scenario).
+ * Unresolvable names are silently skipped — a missing parent is better
+ * than a wrong edge.
+ *
+ * Also builds the implementor index (interface name → implementing file
+ * paths) used by interface-dispatch in call resolution.
+ */
+export declare const buildHeritageMap: (heritage: readonly ExtractedHeritage[], ctx: ResolutionContext, getHeritageStrategy?: HeritageStrategyLookup) => HeritageMap;

package/dist/core/ingestion/model/heritage-map.js

@@ -0,0 +1,260 @@
+/**
+ * Heritage Map
+ *
+ * Unified inheritance data structure built from accumulated
+ * {@link ExtractedHeritage} records **after all chunks complete** (between
+ * chunk processing and call resolution). Consumes `ExtractedHeritage[]` and
+ * resolves type names to nodeIds via `lookupClassByName`, NOT graph-edge
+ * queries.
+ *
+ * Combines two concerns:
+ * 1. **Parent/ancestor lookup** (MRO-aware method resolution)
+ * 2. **Implementor lookup** (interface dispatch — which files contain
+ *    classes implementing a given interface)
+ */
+import { getLanguageFromFilename } from '../../../_shared/index.js';
+/**
+ * Determine whether a heritage.extends capture is actually an IMPLEMENTS
+ * relationship. Consults the symbol table first (authoritative — Tier 1 /
+ * Tier 2 resolution); falls back to the injected {@link HeritageResolutionStrategy}
+ * heuristics for external symbols not present in the graph.
+ */
+export const resolveExtendsType = (parentName, currentFilePath, ctx, strategy) => {
+    const resolved = ctx.resolve(parentName, currentFilePath);
+    if (resolved && resolved.candidates.length > 0) {
+        const isInterface = resolved.candidates[0].type === 'Interface';
+        return isInterface
+            ? { type: 'IMPLEMENTS', idPrefix: 'Interface' }
+            : { type: 'EXTENDS', idPrefix: 'Class' };
+    }
+    // Unresolved symbol — fall back to strategy heuristics.
+    if (strategy.interfaceNamePattern?.test(parentName)) {
+        return { type: 'IMPLEMENTS', idPrefix: 'Interface' };
+    }
+    if (strategy.defaultEdge === 'IMPLEMENTS') {
+        return { type: 'IMPLEMENTS', idPrefix: 'Interface' };
+    }
+    return { type: 'EXTENDS', idPrefix: 'Class' };
+};
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+/** Maximum ancestor chain depth to prevent runaway traversal. */
+const MAX_ANCESTOR_DEPTH = 32;
+/** Shared empty set returned when no implementors are found. */
+const EMPTY_SET = new Set();
+/** Default strategy used when `buildHeritageMap` is called without an
+ *  explicit `getHeritageStrategy` callback — the fallback for a language
+ *  whose provider sets no interface-name pattern and no non-default
+ *  `heritageDefaultEdge`. */
+const DEFAULT_HERITAGE_STRATEGY = { defaultEdge: 'EXTENDS' };
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a HeritageMap from accumulated ExtractedHeritage records.
+ *
+ * Resolves class/interface/struct/trait names to nodeIds via
+ * `ctx.model.types.lookupClassByName`. When a name resolves to multiple
+ * candidates, all are recorded (partial-class / cross-file scenario).
+ * Unresolvable names are silently skipped — a missing parent is better
+ * than a wrong edge.
+ *
+ * Also builds the implementor index (interface name → implementing file
+ * paths) used by interface-dispatch in call resolution.
+ */
+export const buildHeritageMap = (heritage, ctx, getHeritageStrategy) => {
+    // childNodeId → insertion-ordered array of { parentId, kind }.
+    // Ordered array (not Set) because Ruby MRO walk depends on declaration
+    // order. A parallel `seen` map dedupes `(parentId, kind)` pairs without
+    // losing order.
+    const directParents = new Map();
+    const seenParents = new Map();
+    // interfaceName → Set<filePath>  (implementor lookup for interface dispatch)
+    const implementorFiles = new Map();
+    for (const h of heritage) {
+        // ── Parent lookup (nodeId-based) ────────────────────────────────
+        const childDefs = ctx.model.types.lookupClassByName(h.className);
+        const parentDefs = ctx.model.types.lookupClassByName(h.parentName);
+        if (childDefs.length > 0 && parentDefs.length > 0) {
+            for (const child of childDefs) {
+                for (const parent of parentDefs) {
+                    // Skip self-references
+                    if (child.nodeId === parent.nodeId)
+                        continue;
+                    let parents = directParents.get(child.nodeId);
+                    if (!parents) {
+                        parents = [];
+                        directParents.set(child.nodeId, parents);
+                    }
+                    let seen = seenParents.get(child.nodeId);
+                    if (!seen) {
+                        seen = new Set();
+                        seenParents.set(child.nodeId, seen);
+                    }
+                    // Dedup by `parentId + kind` so the same parent under two different
+                    // kinds (e.g. a module that is both included and prepended — legal
+                    // Ruby though unusual) is recorded twice; the consumer needs both
+                    // kinds in the walk. A single (parent, kind) pair is deduped.
+                    const key = `${parent.nodeId}|${h.kind}`;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        parents.push({ parentId: parent.nodeId, kind: h.kind });
+                    }
+                }
+            }
+        }
+        // ── Implementor index (name-based) ──────────────────────────────
+        //
+        // Known limitation: Rust `kind: 'trait-impl'` entries are intentionally NOT
+        // added to the implementor index. Interface dispatch resolution currently
+        // does not traverse Rust trait objects, so recording them here would
+        // inflate the index without a consumer. Revisit if/when trait-object
+        // dispatch is added.
+        //
+        // Known limitation: `getImplementorFiles` is keyed by interface **name**
+        // (string), so two interfaces with the same unqualified name in different
+        // packages (e.g. `pkgA.IRepository` vs `pkgB.IRepository`) collide.
+        let isImpl = false;
+        if (h.kind === 'implements') {
+            isImpl = true;
+        }
+        else if (h.kind === 'extends') {
+            const lang = getLanguageFromFilename(h.filePath);
+            if (lang) {
+                const strategy = getHeritageStrategy?.(lang) ?? DEFAULT_HERITAGE_STRATEGY;
+                const { type } = resolveExtendsType(h.parentName, h.filePath, ctx, strategy);
+                isImpl = type === 'IMPLEMENTS';
+            }
+        }
+        if (isImpl) {
+            let files = implementorFiles.get(h.parentName);
+            if (!files) {
+                files = new Set();
+                implementorFiles.set(h.parentName, files);
+            }
+            files.add(h.filePath);
+        }
+    }
+    // --- Public API ---------------------------------------------------
+    /** Internal helper: return the entries array (may be undefined). */
+    const entriesFor = (nodeId) => directParents.get(nodeId);
+    const getParentEntries = (childNodeId) => {
+        const entries = entriesFor(childNodeId);
+        return entries ?? [];
+    };
+    const getParents = (childNodeId) => {
+        const entries = entriesFor(childNodeId);
+        if (!entries)
+            return [];
+        // Deduplicate parent ids across kinds so the flat-string contract
+        // (used by non-Ruby MRO strategies and by the C3 linearizer) stays
+        // identical to its pre-kind-awareness behavior.
+        const out = [];
+        const seen = new Set();
+        for (const e of entries) {
+            if (!seen.has(e.parentId)) {
+                seen.add(e.parentId);
+                out.push(e.parentId);
+            }
+        }
+        return out;
+    };
+    const getAncestors = (childNodeId) => {
+        const result = [];
+        const visited = new Set();
+        visited.add(childNodeId); // prevent cycles through the start node
+        // BFS with bounded depth
+        let frontier = getParents(childNodeId);
+        let depth = 0;
+        while (frontier.length > 0 && depth < MAX_ANCESTOR_DEPTH) {
+            const nextFrontier = [];
+            for (const parentId of frontier) {
+                if (visited.has(parentId))
+                    continue;
+                visited.add(parentId);
+                result.push(parentId);
+                // Expand parent's own parents for next level
+                const grandparents = entriesFor(parentId);
+                if (grandparents) {
+                    const gpSeen = new Set();
+                    for (const gp of grandparents) {
+                        if (gpSeen.has(gp.parentId))
+                            continue;
+                        gpSeen.add(gp.parentId);
+                        if (!visited.has(gp.parentId))
+                            nextFrontier.push(gp.parentId);
+                    }
+                }
+            }
+            frontier = nextFrontier;
+            depth++;
+        }
+        return result;
+    };
+    /**
+     * Lazy-computed per-owner split of direct parents into instance-dispatch
+     * (non-`extend`) and singleton-dispatch (`extend`-only) views. Memoized on
+     * first request so the `.filter()` pass happens at most once per owner per
+     * HeritageMap lifetime, not per call-site dispatch.
+     *
+     * Shared empty-array sentinels for owners with no entries in a given view
+     * avoid per-call allocation when the split is asymmetric (common Ruby case:
+     * a class has `include` but no `extend`, so its singleton view is empty).
+     */
+    const EMPTY_PARENT_ENTRIES = [];
+    const splitCache = new Map();
+    const splitForOwner = (childNodeId) => {
+        let cached = splitCache.get(childNodeId);
+        if (cached)
+            return cached;
+        const entries = entriesFor(childNodeId);
+        if (!entries || entries.length === 0) {
+            cached = { instance: EMPTY_PARENT_ENTRIES, singleton: EMPTY_PARENT_ENTRIES };
+        }
+        else {
+            const instance = [];
+            const singleton = [];
+            for (const e of entries) {
+                if (e.kind === 'extend')
+                    singleton.push(e);
+                else
+                    instance.push(e);
+            }
+            cached = {
+                instance: instance.length === 0 ? EMPTY_PARENT_ENTRIES : instance,
+                singleton: singleton.length === 0 ? EMPTY_PARENT_ENTRIES : singleton,
+            };
+        }
+        splitCache.set(childNodeId, cached);
+        return cached;
+    };
+    /**
+     * Instance-dispatch ancestry walk. Excludes `extend` (singleton-only).
+     * For kind-aware consumers (Ruby MRO): walks parents in source-insertion
+     * order. The consumer is responsible for interleaving self / reversing
+     * prepend order / etc. This method preserves raw declaration order.
+     *
+     * Result is cached per owner; repeat calls return the same array.
+     */
+    const getInstanceAncestry = (childNodeId) => splitForOwner(childNodeId).instance;
+    /**
+     * Singleton-dispatch ancestry walk. Only `extend` parents. For non-Ruby
+     * languages this is always empty (no language currently produces `extend`
+     * heritage records outside Ruby).
+     *
+     * Result is cached per owner; repeat calls return the same array.
+     */
+    const getSingletonAncestry = (childNodeId) => splitForOwner(childNodeId).singleton;
+    const getImplementorFiles = (interfaceName) => {
+        return implementorFiles.get(interfaceName) ?? EMPTY_SET;
+    };
+    return {
+        getParents,
+        getAncestors,
+        getParentEntries,
+        getInstanceAncestry,
+        getSingletonAncestry,
+        getImplementorFiles,
+    };
+};

package/dist/core/ingestion/model/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Semantic Model — public module surface.
+ *
+ * Barrel re-export for the `model/` module. Consumers outside `model/`
+ * should import from this file rather than reaching into individual
+ * registry files.
+ *
+ * The model is owner-scoped type/method/field knowledge layered above
+ * `SymbolTable`. File-indexed and name-keyed callable lookups stay in
+ * `SymbolTable` by design.
+ */
+export { type SemanticModel, type MutableSemanticModel, createSemanticModel, } from './semantic-model.js';
+export { type SymbolTableReader, type SymbolTableWriter, createSymbolTable, type AddMetadata, CLASS_TYPES, CLASS_TYPES_TUPLE, type ClassLikeLabel, FREE_CALLABLE_TYPES, FREE_CALLABLE_TUPLE, type FreeCallableLabel, CALL_TARGET_TYPES, } from './symbol-table.js';
+export { type TypeRegistry, type MutableTypeRegistry, createTypeRegistry, } from './type-registry.js';
+export { type MethodRegistry, type MutableMethodRegistry, createMethodRegistry, } from './method-registry.js';
+export { type FieldRegistry, type MutableFieldRegistry, createFieldRegistry, } from './field-registry.js';
+export { lookupMethodByOwnerWithMRO } from './resolve.js';
+export { type NamedImportBinding, type NamedImportMap, isFileInPackageDir, } from './resolution-context.js';
+export { type ExtractedHeritage, type HeritageMap, type HeritageResolutionStrategy, type HeritageStrategyLookup, } from './heritage-map.js';
+export { CALLABLE_ONLY_LABELS, INERT_LABELS, DISPATCH_LABELS, ALL_NODE_LABELS, type LabelBehavior, } from './registration-table.js';

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

@@ -0,0 +1,43 @@
+/**
+ * Semantic Model — public module surface.
+ *
+ * Barrel re-export for the `model/` module. Consumers outside `model/`
+ * should import from this file rather than reaching into individual
+ * registry files.
+ *
+ * The model is owner-scoped type/method/field knowledge layered above
+ * `SymbolTable`. File-indexed and name-keyed callable lookups stay in
+ * `SymbolTable` by design.
+ */
+// Unified semantic model (factory + interfaces). SemanticModel is the
+// top-level container and owns the file/callable SymbolTable as a
+// nested `symbols` field.
+export { createSemanticModel, } from './semantic-model.js';
+// SymbolTable is exclusively owned by SemanticModel. Re-exported here
+// for the rare caller that needs the file/callable interface in
+// isolation (e.g. tests).
+export { createSymbolTable, CLASS_TYPES, CLASS_TYPES_TUPLE, FREE_CALLABLE_TYPES, FREE_CALLABLE_TUPLE, CALL_TARGET_TYPES, } from './symbol-table.js';
+// `SymbolDefinition` moved to `arceus-shared` (RFC #909 Ring 1 #910).
+// Consumers should import it directly from `arceus-shared`, not via this barrel.
+// Type registry (classes, structs, interfaces, enums, records, impls)
+export { createTypeRegistry, } from './type-registry.js';
+// Method registry (owner-scoped methods with arity-aware overload lookup)
+export { createMethodRegistry, } from './method-registry.js';
+// Field registry (owner-scoped fields/properties)
+export { createFieldRegistry, } from './field-registry.js';
+// MRO-aware method resolution (C3, first-wins, leftmost-base, implements-split,
+// qualified-syntax). Pure function that depends only on the model + HeritageMap.
+// `MroStrategy` itself lives in `arceus-shared`; re-exported here for
+// consumers that reach model behavior through the barrel.
+export { lookupMethodByOwnerWithMRO } from './resolve.js';
+// Named-import types and package-dir helper. Re-exported so barrel
+// consumers don't need to reach into a specific model file.
+export { isFileInPackageDir, } from './resolution-context.js';
+// Behavior-grouped dispatch table for SymbolTable.add() routing.
+// See registration-table.ts module JSDoc for the behavior group taxonomy
+// and "how to add a new NodeLabel" checklist.
+// NOTE: createRegistrationTable, RegistrationHook, and RegistrationTableDeps
+// are deliberately NOT re-exported here — they are factory internals of
+// SemanticModel and should only be imported directly from registration-table.js
+// by semantic-model.ts and the registration-table.test.ts file.
+export { CALLABLE_ONLY_LABELS, INERT_LABELS, DISPATCH_LABELS, ALL_NODE_LABELS, } from './registration-table.js';

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

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+import type { SymbolDefinition } from '../../../_shared/index.js';
+export interface MethodRegistry {
+    /**
+     * Look up a method by owner class + name, optionally filtered by arity.
+     *
+     * When `argCount` is provided, overloads whose parameter count doesn't
+     * accommodate the call's argument count are filtered out before the
+     * returnType dedup runs. This lets D0 (`resolveMemberCall`) disambiguate
+     * arity-differing overloads (e.g. C++ `greet()` vs `greet(string)`) that
+     * would otherwise collide on the shared `ownerId + methodName` key.
+     *
+     * Same-arity, same-returnType overloads (e.g. `save(int)` vs `save(String)`,
+     * both returning `void`) still collapse to the first match — callers must
+     * gate D0 on overload concern before invoking this function for that case.
+     */
+    lookupMethodByOwner(ownerNodeId: string, methodName: string, argCount?: number): SymbolDefinition | undefined;
+    /**
+     * Flat-by-name lookup across all owners. Returns every method registered
+     * with the given unqualified name, in registration order, accumulated
+     * across owners and overloads.
+     *
+     * Required by Tier 3 global resolution: Method and Constructor do not
+     * land in `SymbolTable.callableByName`, so Tier 3 reaches them through
+     * this flat index instead. Returns `[]` on miss — never `undefined` —
+     * so callers can concatenate without null checks.
+     *
+     * Reference identity: each returned def is the same object reference
+     * stored under `lookupMethodByOwner`, so a method symbol occupies one
+     * allocation reachable from two indexes.
+     */
+    lookupMethodByName(name: string): readonly SymbolDefinition[];
+    /**
+     * Return every overload registered under `(ownerNodeId, methodName)`,
+     * unfiltered by arity or return type. This is the raw owner-scoped
+     * view — callers that need arity narrowing or unambiguous single-
+     * result semantics should use `lookupMethodByOwner` instead.
+     *
+     * Returns `[]` on miss so callers can iterate without null checks.
+     */
+    lookupAllByOwner(ownerNodeId: string, methodName: string): readonly SymbolDefinition[];
+    /**
+     * True iff at least one registered def has `type === 'Function'` — i.e.,
+     * a Python/Rust/Kotlin class method emitted by the worker as
+     * `Function + ownerId` rather than as a strict `Method` label. Such defs
+     * are double-indexed: they land in `SymbolTable.callableByName` (via the
+     * Function callable-index gate) AND in this registry (via the
+     * dispatch-key normalization in `wrappedAdd`). Tier 3 resolution must
+     * then dedup the two indexes by nodeId.
+     *
+     * When this flag is false, the callable and method indexes are
+     * guaranteed disjoint and Tier 3 can skip the dedup pass entirely.
+     * The flag is monotonic (false→true once, never back) for the lifetime
+     * of the MethodRegistry.
+     */
+    readonly hasFunctionMethods: boolean;
+}
+export interface MutableMethodRegistry extends MethodRegistry {
+    /** Register a method under its owner. Supports multiple overloads. */
+    register(ownerNodeId: string, methodName: string, def: SymbolDefinition): void;
+    /** Clear all entries. */
+    clear(): void;
+}
+export declare const createMethodRegistry: () => MutableMethodRegistry;

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

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export 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;
+        },
+    };
+};