gitnexus 1.5.3 → 1.6.1

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

@@ -0,0 +1,18 @@
+/**
+ * Field Registry
+ *
+ * Owner-scoped field/property index extracted from SymbolTable.
+ * Stores Property symbols keyed by `ownerNodeId\0fieldName` for O(1) lookup.
+ */
+import type { SymbolDefinition } from './symbol-table.js';
+export interface FieldRegistry {
+    /** Look up a field/property by its owning class nodeId and field name. */
+    lookupFieldByOwner(ownerNodeId: string, fieldName: string): SymbolDefinition | undefined;
+}
+export interface MutableFieldRegistry extends FieldRegistry {
+    /** Register a field/property under its owner. */
+    register(ownerNodeId: string, fieldName: string, def: SymbolDefinition): void;
+    /** Clear all entries. */
+    clear(): void;
+}
+export declare const createFieldRegistry: () => MutableFieldRegistry;

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,70 @@
+/**
+ * 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;
+};
+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[];
+    /**
+     * 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,159 @@
+/**
+ * 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 → Set<parentNodeId>  (Set to deduplicate cross-chunk duplicates)
+    const directParents = 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 = new Set();
+                        directParents.set(child.nodeId, parents);
+                    }
+                    parents.add(parent.nodeId);
+                }
+            }
+        }
+        // ── 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 ---------------------------------------------------
+    const getParents = (childNodeId) => {
+        const parents = directParents.get(childNodeId);
+        return parents ? [...parents] : [];
+    };
+    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 = directParents.get(parentId);
+                if (grandparents) {
+                    for (const gp of grandparents) {
+                        if (!visited.has(gp))
+                            nextFrontier.push(gp);
+                    }
+                }
+            }
+            frontier = nextFrontier;
+            depth++;
+        }
+        return result;
+    };
+    const getImplementorFiles = (interfaceName) => {
+        return implementorFiles.get(interfaceName) ?? EMPTY_SET;
+    };
+    return { getParents, getAncestors, 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, } 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 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,41 @@
+/**
+ * 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, } from './symbol-table.js';
+// 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 `gitnexus-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,62 @@
+/**
+ * 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 './symbol-table.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[];
+    /**
+     * 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,130 @@
+/**
+ * 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 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,
+        register,
+        clear,
+        get hasFunctionMethods() {
+            return hasFunctionMethodsFlag;
+        },
+    };
+};

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

@@ -0,0 +1,139 @@
+/**
+ * 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 type { NodeLabel } from '../../../_shared/index.js';
+import type { SymbolDefinition } from './symbol-table.js';
+import type { MutableTypeRegistry } from './type-registry.js';
+import type { MutableMethodRegistry } from './method-registry.js';
+import type { MutableFieldRegistry } from './field-registry.js';
+/**
+ * Registration hook — a pure side-effectful function closed over a
+ * specific registry. Performs the specialized registry write into the
+ * appropriate owner-scoped registry for one NodeLabel.
+ *
+ * Closure capture is the isolation mechanism: `propertyHook` literally
+ * cannot call `types.registerClass` because its closure does not hold
+ * a reference to `types`. This is the runtime half of the principle of
+ * least authority — the compile-time half is enforced by TypeScript.
+ *
+ * The callable-index gate lives inside `SymbolTable.add()` via the
+ * `FREE_CALLABLE_TYPES` allowlist — the dispatch table does not
+ * participate in that decision.
+ */
+export type RegistrationHook = (name: string, def: SymbolDefinition) => void;
+/**
+ * Dependencies required to build the dispatch table. Matches the shape
+ * that `createSemanticModel()` passes into `createRegistrationTable()`.
+ */
+export interface RegistrationTableDeps {
+    readonly types: MutableTypeRegistry;
+    readonly methods: MutableMethodRegistry;
+    readonly fields: MutableFieldRegistry;
+}
+/**
+ * Behavior category for a NodeLabel during ingestion. Determines which
+ * registry (if any) receives the symbol write during `SymbolTable.add()`:
+ *
+ *   - `dispatch`     — owner-scoped registry write via the dispatch table
+ *                      (Class/Struct/Interface/Enum/Record/Trait → types.registerClass,
+ *                       Method/Constructor → methods.register,
+ *                       Property → fields.register,
+ *                       Impl → types.registerImpl)
+ *   - `callable-only` — no specialized registry; symbol appears in
+ *                      `callableByName` via `SymbolTable.add()`'s
+ *                      FREE_CALLABLE_TYPES gate (Function/Macro/Delegate)
+ *   - `inert`        — no registry, no callable index; file-index only
+ *                      (metadata / structural nodes like Project, Module,
+ *                      Import, Decorator, etc.)
+ *
+ * `Function` has a twist: `Function`-with-`ownerId` (Python `def` in a
+ * class body, Rust trait method, Kotlin companion method) is pre-normalized
+ * to `Method` in `createSemanticModel`'s `wrappedAdd` before dispatch lookup,
+ * so only free functions actually flow through the callable-only path.
+ */
+export type LabelBehavior = 'dispatch' | 'callable-only' | 'inert';
+/**
+ * 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 declare const ALL_NODE_LABELS: readonly NodeLabel[];
+/**
+ * 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 declare const CALLABLE_ONLY_LABELS: ReadonlySet<NodeLabel>;
+/**
+ * NodeLabel values that touch only the file index — no specialized
+ * registry, no callable index.
+ */
+export declare const INERT_LABELS: ReadonlySet<NodeLabel>;
+/**
+ * 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 declare const DISPATCH_LABELS: ReadonlySet<NodeLabel>;
+/**
+ * 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 declare const createRegistrationTable: (deps: RegistrationTableDeps) => Map<NodeLabel, RegistrationHook>;