gitnexus 1.6.2 → 1.6.3-rc.10

package/dist/_shared/scope-resolution/types.d.ts

@@ -0,0 +1,356 @@
+/**
+ * Scope-resolution type definitions — RFC §2 data model (authoritative source).
+ *
+ * See: https://www.notion.so/346dc50b6ed281cfaacbe480bf231d50
+ *
+ * Anti-drift rule: every type, interface, and enum defined here is the single
+ * source of truth. Later code that references these names must import them
+ * from `gitnexus-shared`; it must not re-define them locally.
+ *
+ * Lifecycle contract (RFC §2.8): scopes are **constructed during extraction,
+ * linked during finalize, immutable after finalize**. All fields are
+ * `readonly` at the type level; `Object.freeze` is applied at runtime in dev
+ * builds. `ReferenceIndex` is the sole structure populated after freeze — by
+ * resolution, before emission.
+ */
+import type { NodeLabel } from '../graph/types.js';
+import type { SymbolDefinition } from './symbol-definition.js';
+/** Stable per-(file, range, kind) scope identifier; interned for identity-fast equality. */
+export type ScopeId = string;
+/** Stable symbol-definition identifier (graph nodeId). */
+export type DefId = string;
+/** Kinds of lexical scope a `Scope` node can represent. */
+export type ScopeKind = 'Module' | 'Namespace' | 'Class' | 'Function' | 'Block' | 'Expression';
+/** Source-text range. 1-based `startLine`/`endLine`; 0-based `startCol`/`endCol`. */
+export interface Range {
+    readonly startLine: number;
+    readonly startCol: number;
+    readonly endLine: number;
+    readonly endCol: number;
+}
+/**
+ * Tagged capture emitted by a LanguageProvider's `emitScopeCaptures` hook.
+ *
+ * Parser-agnostic: tree-sitter queries and COBOL's regex tagger both produce
+ * `Capture[]`. The central `ScopeExtractor` consumes captures without
+ * knowing which parser produced them.
+ */
+export interface Capture {
+    /** Capture name, including leading `@` (e.g., `'@scope.module'`, `'@declaration.class'`). */
+    readonly name: string;
+    readonly range: Range;
+    /** The captured source text. */
+    readonly text: string;
+}
+/**
+ * A grouping of `Capture`s that came from a single query match (e.g., one
+ * `@import.statement` match carries `@import.source`, `@import.name`,
+ * `@import.alias?` as child captures). Keyed by capture name for O(1)
+ * child access.
+ */
+export type CaptureMatch = Readonly<Record<string, Capture>>;
+/**
+ * Provider-interpreted raw import, consumed by finalize (Phase 2) to produce
+ * linked `ImportEdge[]`. The provider's `interpretImport` hook turns a
+ * `CaptureMatch` for an `@import.statement` into one of these; the central
+ * finalize algorithm resolves `targetRaw` to a concrete file via
+ * `resolveImportTarget` and materializes the final `ImportEdge`.
+ *
+ * Discriminated union — each variant carries only the fields that make sense
+ * for its kind. Invalid shapes (e.g., a `namespace` import with an alias-like
+ * `importedName` mismatch) are compile errors, not latent bugs. `'wildcard-
+ * expanded'` is deliberately NOT a variant: that kind is finalize output only,
+ * produced when `expandsWildcardTo` materializes a wildcard against target
+ * exports — a provider must never emit it at parse time.
+ */
+export type ParsedImport = 
+/**
+ * Per-name import without rename.
+ *
+ * Examples:
+ *   - Python `from foo import X`   → `{ kind: 'named', localName: 'X', importedName: 'X', targetRaw: 'foo' }`
+ *   - TS `import { X } from './foo'` → `{ kind: 'named', localName: 'X', importedName: 'X', targetRaw: './foo' }`
+ *   - Java `import foo.bar.X`       → `{ kind: 'named', localName: 'X', importedName: 'X', targetRaw: 'foo.bar' }`
+ */
+{
+    readonly kind: 'named';
+    readonly localName: string;
+    readonly importedName: string;
+    readonly targetRaw: string;
+}
+/**
+ * Per-name import with rename.
+ *
+ * Examples:
+ *   - Python `from foo import X as Y`   → `{ kind: 'alias', localName: 'Y', importedName: 'X', alias: 'Y', targetRaw: 'foo' }`
+ *   - TS `import { X as Y } from './foo'` → `{ kind: 'alias', localName: 'Y', importedName: 'X', alias: 'Y', targetRaw: './foo' }`
+ */
+ | {
+    readonly kind: 'alias';
+    readonly localName: string;
+    readonly importedName: string;
+    readonly alias: string;
+    readonly targetRaw: string;
+}
+/**
+ * Qualified module handle, with or without rename. `importedName` is the
+ * module being aliased; `localName` is the scope-visible handle (often the
+ * same unless renamed).
+ *
+ * Examples:
+ *   - Python `import numpy`            → `{ kind: 'namespace', localName: 'numpy', importedName: 'numpy', targetRaw: 'numpy' }`
+ *   - Python `import numpy as np`      → `{ kind: 'namespace', localName: 'np',    importedName: 'numpy', targetRaw: 'numpy' }`
+ *   - TS `import * as np from 'numpy'` → `{ kind: 'namespace', localName: 'np',    importedName: 'numpy', targetRaw: 'numpy' }`
+ *   - Go `import foo "pkg/bar"`        → `{ kind: 'namespace', localName: 'foo',   importedName: 'bar',   targetRaw: 'pkg/bar' }`
+ */
+ | {
+    readonly kind: 'namespace';
+    /** Scope-visible handle (e.g. `np` in `import numpy as np`; `numpy` when unaliased). */
+    readonly localName: string;
+    /** Module being aliased (e.g. `numpy` in `import numpy as np`). */
+    readonly importedName: string;
+    readonly targetRaw: string;
+}
+/**
+ * Syntactically-detectable parse-time re-export. Finalize may still produce
+ * `ImportEdge { kind: 'reexport', transitiveVia }` when flattening chains;
+ * this variant preserves the *parse-time* signal so finalize doesn't have
+ * to re-derive it from scratch.
+ *
+ * Examples:
+ *   - TS `export { X } from './y'`       → `{ kind: 'reexport', localName: 'X', importedName: 'X', targetRaw: './y' }`
+ *   - TS `export { X as Y } from './y'`  → `{ kind: 'reexport', localName: 'Y', importedName: 'X', alias: 'Y', targetRaw: './y' }`
+ *   - Rust `pub use foo::bar`            → `{ kind: 'reexport', localName: 'bar', importedName: 'bar', targetRaw: 'foo' }`
+ */
+ | {
+    readonly kind: 'reexport';
+    /** Name as re-exported in the current module. */
+    readonly localName: string;
+    /** Name in the source module. */
+    readonly importedName: string;
+    readonly targetRaw: string;
+    /** Set when the re-export renames the symbol (e.g. `export { X as Y } from './y'`). */
+    readonly alias?: string;
+}
+/**
+ * Wildcard import — brings every exported name from the target module into
+ * the importing scope. The finalize algorithm expands this into one
+ * `BindingRef` per exported name via the provider's `expandsWildcardTo`
+ * hook, producing the finalize-only `ImportEdge` kind `'wildcard-expanded'`.
+ *
+ * Examples:
+ *   - Python `from foo import *`   → `{ kind: 'wildcard', targetRaw: 'foo' }`
+ *   - JS `export * from './foo'`   → `{ kind: 'wildcard', targetRaw: './foo' }`
+ *   - Rust `pub use foo::*`         → `{ kind: 'wildcard', targetRaw: 'foo' }`
+ */
+ | {
+    readonly kind: 'wildcard';
+    readonly targetRaw: string;
+}
+/**
+ * Runtime-computed target — the import path is not a static literal at
+ * parse time. Providers SHOULD emit the unresolvable expression's source
+ * text as `targetRaw` to aid diagnostics; `null` only when no string form
+ * exists.
+ *
+ * Examples:
+ *   - JS `await import(expr)`                          → `{ kind: 'dynamic-unresolved', localName: '', targetRaw: 'expr' }`
+ *   - Python `importlib.import_module(f'pkg.{name}')`  → `{ kind: 'dynamic-unresolved', localName: '', targetRaw: "f'pkg.{name}'" }`
+ */
+ | {
+    readonly kind: 'dynamic-unresolved';
+    readonly localName: string;
+    /** Source text of the unresolved expression when available; `null` otherwise. */
+    readonly targetRaw: string | null;
+};
+/**
+ * Provider-interpreted type binding. The provider's `interpretTypeBinding`
+ * hook turns a `CaptureMatch` (e.g., `@type-binding.parameter`) into one of
+ * these; the central extractor attaches the resulting `TypeRef` to the
+ * appropriate scope's `typeBindings` map.
+ */
+export interface ParsedTypeBinding {
+    /** The name being bound (parameter name, `self`, assignment LHS, …). */
+    readonly boundName: string;
+    /** The raw type name as written in source (`'User'`, `'models.User'`, …). */
+    readonly rawTypeName: string;
+    readonly source: TypeRef['source'];
+}
+/**
+ * Cross-file workspace index consumed by finalize-phase hooks
+ * (`resolveImportTarget`, `expandsWildcardTo`). Opaque placeholder in Ring 1;
+ * concretely typed in Ring 2 SHARED (#915).
+ */
+export type WorkspaceIndex = unknown;
+/**
+ * Minimal scope-lookup contract: map a `ScopeId` back to its `Scope` record.
+ *
+ * Lives in the data-model layer so both `ScopeTree` (§3.1) and
+ * `resolveTypeRef` / `Registry.lookup` (§4) can depend on it without
+ * inverting each other. `ScopeTree` is the canonical implementation;
+ * tests and future alternative containers may supply their own.
+ */
+export interface ScopeLookup {
+    getScope(id: ScopeId): Scope | undefined;
+}
+/** Call-site description passed to `arityCompatibility`. */
+export interface Callsite {
+    /** Number of arguments at the call site. */
+    readonly arity: number;
+}
+/**
+ * A cross-file import edge attached to a module/namespace scope.
+ *
+ * Raw (unlinked) edges are emitted during parse (Phase 1); `targetModuleScope`
+ * and `targetDefId` are filled in during finalize (Phase 2) via SCC-aware
+ * bounded-fixpoint linking (RFC §3.2).
+ */
+export interface ImportEdge {
+    /** How this scope sees the imported name (after alias). */
+    readonly localName: string;
+    /** Exporting file; `null` only when `kind === 'dynamic-unresolved'`. */
+    readonly targetFile: string | null;
+    /** The name under which the target exports this symbol. */
+    readonly targetExportedName: string;
+    /** Pre-resolved at finalize: the module scope of the exporting file. */
+    readonly targetModuleScope?: ScopeId;
+    /** Pre-resolved at finalize: the exported symbol's `DefId`. */
+    readonly targetDefId?: DefId;
+    readonly kind: 'named' | 'alias' | 'namespace' | 'wildcard-expanded' | 'reexport' | 'dynamic-unresolved';
+    /** Re-export chain, for provenance (e.g., `['./y']` when re-exported via `./y`). */
+    readonly transitiveVia?: readonly string[];
+    /** Set to `'unresolved'` when the SCC fixpoint could not link this edge. */
+    readonly linkStatus?: 'unresolved';
+}
+/**
+ * A name binding visible at a scope, with provenance.
+ *
+ * Provenance stays at the visibility layer — a name being visible because it
+ * is local vs imported vs wildcard-expanded vs re-exported is a property of
+ * the binding itself. This keeps evidence emission and `import-use` reference
+ * stamping first-class instead of reconstructing provenance from a side table.
+ */
+export interface BindingRef {
+    readonly def: SymbolDefinition;
+    readonly origin: 'local' | 'import' | 'namespace' | 'wildcard' | 'reexport';
+    /** Non-null for non-local origins; carries the `ImportEdge` that brought the name into this scope. */
+    readonly via?: ImportEdge;
+}
+/**
+ * A reference to a named type, anchored at its declaration site.
+ *
+ * Design choice: raw name + declaration-site scope, resolved at lookup time.
+ * Pre-resolution would invert the extraction/resolution wall. Deferred thunks
+ * add no capability. Structured type systems are months of work per language.
+ * This shape keeps V1 tractable while preserving correctness for aliases,
+ * re-exports, and nested modules. Generics deferred to V2 via `typeArgs`.
+ */
+export interface TypeRef {
+    /** The name as written in source (e.g., `'User'`, `'models.User'`, `'List'`). */
+    readonly rawName: string;
+    /** Anchor for resolving `rawName` — the scope where the annotation/inference was written. */
+    readonly declaredAtScope: ScopeId;
+    readonly source: 'annotation' | 'parameter-annotation' | 'return-annotation' | 'self' | 'assignment-inferred' | 'constructor-inferred' | 'receiver-propagated';
+    /** Reserved for V2+: generic type arguments (`List<User>` → `[TypeRef('User')]`). V1 ignores. */
+    readonly typeArgs?: readonly TypeRef[];
+}
+/**
+ * The canonical lexical-scope node. Forms the spine of the SemanticModel.
+ *
+ * ScopeId shape (RFC §2.2): `scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}`
+ * — deterministic, stable across reparses of the same source, interned.
+ */
+export interface Scope {
+    readonly id: ScopeId;
+    readonly parent: ScopeId | null;
+    readonly kind: ScopeKind;
+    readonly range: Range;
+    readonly filePath: string;
+    /** Names visible from this scope. Provenance preserved via `BindingRef.origin`. */
+    readonly bindings: ReadonlyMap<string, readonly BindingRef[]>;
+    /** Defs structurally owned by this scope (e.g., methods owned by a class body scope). */
+    readonly ownedDefs: readonly SymbolDefinition[];
+    /** Import edges attached to this scope. Mostly module/namespace scopes, but some
+     *  languages allow local imports (Python `def f(): from x import Y`, Rust
+     *  fn-local `use`, TS dynamic `import()`). */
+    readonly imports: readonly ImportEdge[];
+    /** Local type facts visible from this scope (parameter annotations, `self` binding, etc.). */
+    readonly typeBindings: ReadonlyMap<string, TypeRef>;
+}
+/**
+ * One piece of evidence for a `Resolution`. Multiple signals corroborate a
+ * single match; their weights compose additively to produce `confidence`.
+ *
+ * Weights come from `EvidenceWeights` (see `./evidence-weights.ts`).
+ */
+export interface ResolutionEvidence {
+    readonly kind: 'local' | 'scope-chain' | 'import' | 'type-binding' | 'owner-match' | 'kind-match' | 'arity-match' | 'global-name' | 'global-qualified' | 'dynamic-import-unresolved';
+    /** Signal weight, sourced from `EvidenceWeights`. Additive; sum capped at 1.0. */
+    readonly weight: number;
+    /** Optional debug annotation (e.g., `'matched via self: User'`). */
+    readonly note?: string;
+}
+/**
+ * A ranked resolution candidate returned by `ClassRegistry.lookup` /
+ * `MethodRegistry.lookup` / `FieldRegistry.lookup`. Evidence composes
+ * additively; callers read `[0]` for the one-shot answer or inspect the
+ * evidence trace for debugging.
+ */
+export interface Resolution {
+    readonly def: SymbolDefinition;
+    /** Σ of `evidence[].weight`, capped at 1.0. */
+    readonly confidence: number;
+    readonly evidence: readonly ResolutionEvidence[];
+    /** Optional debug trace: scopes walked to reach `def`. */
+    readonly path?: readonly ScopeId[];
+}
+/**
+ * A post-resolution usage fact: some code at `atRange` inside `fromScope`
+ * references `toDef` with the given confidence/evidence. Materialized by the
+ * resolution phase; emitted as graph edges (`CALLS`/`READS`/`WRITES`/etc.)
+ * during the emit phase.
+ */
+export interface Reference {
+    /** Innermost lexical scope containing `atRange`. */
+    readonly fromScope: ScopeId;
+    readonly toDef: DefId;
+    /** Location of the reference in source. */
+    readonly atRange: Range;
+    readonly kind: 'call' | 'read' | 'write' | 'type-reference' | 'inherits' | 'import-use';
+    readonly confidence: number;
+    readonly evidence: readonly ResolutionEvidence[];
+}
+/**
+ * Two-way index over `Reference` records, populated during the resolution
+ * phase. Scopes stay immutable after finalize; references accumulate here.
+ */
+export interface ReferenceIndex {
+    readonly bySourceScope: ReadonlyMap<ScopeId, readonly Reference[]>;
+    readonly byTargetDef: ReadonlyMap<DefId, readonly Reference[]>;
+}
+/**
+ * Opaque placeholder for the per-kind registry passed as the owner-scoped
+ * contributor. Typed concretely in Ring 2 SHARED (#917); kept as `unknown`
+ * here so Ring 1 can ship without pulling in the registry implementation.
+ */
+export type RegistryContributor = unknown;
+/**
+ * Parameters accepted by `Registry.lookup`. Three registries (Class/Method/
+ * Field) run the same 7-step algorithm with different parameter tuples; see
+ * RFC §4.4 for per-registry specializations.
+ */
+export interface LookupParams {
+    readonly acceptedKinds: readonly NodeLabel[];
+    /** Class lookups: false. Method/Field lookups: true. */
+    readonly useReceiverTypeBinding: boolean;
+    readonly ownerScopedContributor: RegistryContributor | null;
+    /** Optional arity hint fed to `provider.arityCompatibility`. */
+    readonly arityHint?: number;
+    /** Explicit receiver name (e.g., `'user'` in `user.save()`). When present,
+     *  the receiver's type binding at the callsite scope is used; otherwise
+     *  the enclosing method's implicit `self`/`this` is consulted. See §4.1. */
+    readonly explicitReceiver?: {
+        readonly name: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/_shared/scope-resolution/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/types.ts"],"names":[],"mappings":"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"}

package/dist/_shared/scope-resolution/types.js

@@ -0,0 +1,17 @@
+/**
+ * Scope-resolution type definitions — RFC §2 data model (authoritative source).
+ *
+ * See: https://www.notion.so/346dc50b6ed281cfaacbe480bf231d50
+ *
+ * Anti-drift rule: every type, interface, and enum defined here is the single
+ * source of truth. Later code that references these names must import them
+ * from `gitnexus-shared`; it must not re-define them locally.
+ *
+ * Lifecycle contract (RFC §2.8): scopes are **constructed during extraction,
+ * linked during finalize, immutable after finalize**. All fields are
+ * `readonly` at the type level; `Object.freeze` is applied at runtime in dev
+ * builds. `ReferenceIndex` is the sole structure populated after freeze — by
+ * resolution, before emission.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/_shared/scope-resolution/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/scope-resolution/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/core/ingestion/call-processor.d.ts

@@ -1,6 +1,7 @@
 import { KnowledgeGraph } from '../graph/types.js';
 import { ASTCache } from './ast-cache.js';
-import type { SymbolDefinition, SymbolTableReader, HeritageMap, ExtractedHeritage } from './model/index.js';
+import type { SymbolDefinition } from '../../_shared/index.js';
+import type { SymbolTableReader, HeritageMap, ExtractedHeritage } from './model/index.js';
 import type { ResolutionContext } from './model/resolution-context.js';
 import type { TieredCandidates } from './model/resolution-context.js';
 import type { TypeEnvironment } from './type-env.js';

package/dist/core/ingestion/language-provider.d.ts

@@ -8,7 +8,7 @@
  * The providers table in `languages/index.ts` uses `satisfies Record<SupportedLanguages, LanguageProvider>`
  * so adding a language to the enum without creating a provider is a compiler error.
  */
-import type { SupportedLanguages, MroStrategy } from '../../_shared/index.js';
+import type { SupportedLanguages, MroStrategy, Capture, CaptureMatch, BindingRef, TypeRef, Scope, ScopeId, ScopeKind, ScopeTree, ParsedImport, ParsedTypeBinding, SymbolDefinition, Callsite, WorkspaceIndex } from '../../_shared/index.js';
 import type { LanguageTypeConfig } from './type-extractors/types.js';
 import type { CallRouter } from './call-routing.js';
 import type { CallExtractor, DispatchDecision, ImplicitReceiverOverride, ReceiverEnriched } from './call-types.js';
@@ -222,6 +222,177 @@ interface LanguageProviderConfig {
     /** Built-in/stdlib names that should be filtered from the call graph for this language.
      *  Default: undefined (no language-specific filtering). */
     readonly builtInNames?: ReadonlySet<string>;
+    /**
+     * Emit scope captures from raw source. Tree-sitter-based providers run a
+     * `scopes.scm` query; standalone providers (COBOL) emit captures from a
+     * regex tagger. The return shape is parser-agnostic: the central
+     * `ScopeExtractor` consumes `Capture[]` without knowing which parser
+     * produced them.
+     *
+     * Required for any provider participating in scope-based resolution.
+     * Providers that have not yet migrated continue to run through the legacy
+     * DAG path (feature-flagged per `REGISTRY_PRIMARY_<LANG>`).
+     *
+     * Default: undefined (language continues to use legacy DAG).
+     */
+    readonly emitScopeCaptures?: (sourceText: string, filePath: string) => Promise<readonly Capture[]>;
+    /**
+     * Interpret a raw `@import.statement` capture group into a `ParsedImport`.
+     * The central finalize algorithm resolves `ParsedImport.targetRaw` to a
+     * concrete file via `resolveImportTarget` and materializes the final
+     * `ImportEdge` with `targetModuleScope` / `targetDefId` filled in.
+     *
+     * Required when `emitScopeCaptures` is implemented.
+     */
+    readonly interpretImport?: (captures: CaptureMatch) => ParsedImport | null;
+    /**
+     * What is the implicit receiver on a Function scope? For instance methods
+     * this is `self`/`this`; for standalone functions it is `null`. Consulted
+     * by `Registry.lookup` Step 2 via the `resolveTypeRef` helper.
+     *
+     * Required for any language with method dispatch (OO semantics).
+     *
+     * Default: undefined (treated as `null` — no implicit receiver).
+     */
+    readonly receiverBinding?: (functionScope: Scope) => TypeRef | null;
+    /**
+     * Interpret a raw type-binding capture (parameter annotation, `self`,
+     * assignment with constructor RHS, …) into a `ParsedTypeBinding`. The
+     * central extractor attaches the resulting `TypeRef` to the appropriate
+     * scope's `typeBindings` map.
+     *
+     * Default: undefined (falls back to `{ boundName: captures.name, rawTypeName: captures.type, source: 'annotation' }`).
+     */
+    readonly interpretTypeBinding?: (captures: CaptureMatch) => ParsedTypeBinding | null;
+    /**
+     * Override the `ScopeKind` assigned to a scope capture. Use when the
+     * capture name alone can't resolve the kind (e.g., tree-sitter captures
+     * a `block` that is semantically an `Expression` in this language).
+     *
+     * Default: undefined (the central extractor uses the capture name's
+     * suffix — `@scope.function` → `'Function'`, etc.).
+     */
+    readonly resolveScopeKind?: (captures: CaptureMatch) => ScopeKind | null;
+    /**
+     * Should this scope capture materialize as a real `Scope` node? Return
+     * `false` to skip scope creation while still emitting declarations that
+     * would have gone inside (they attach to the enclosing real scope).
+     *
+     * Example: Python `if`/`for`/`while` bodies capture as `@scope.block` but
+     * Python has no block scope — hook returns `false` and child declarations
+     * lift to the enclosing function/module.
+     *
+     * Default: undefined (treated as `true` — always create).
+     */
+    readonly shouldCreateScope?: (captures: CaptureMatch) => boolean;
+    /**
+     * Override where a declaration's name becomes visible. By default the name
+     * is bound in the innermost enclosing scope; return a different `ScopeId`
+     * to hoist it (JS `var` → enclosing function scope; Ruby `def` inside
+     * `begin` → enclosing class scope).
+     *
+     * Return `null` to delegate to the central default (innermost enclosing
+     * scope). This matches the `X | null` convention used by the other optional
+     * hooks and supports partial overrides — e.g., a JS provider can return a
+     * hoisted scope for `var` declarations and `null` for `let`/`const`, without
+     * re-implementing the default lookup.
+     *
+     * **Purity:** must be a pure function of its inputs — same parameters must
+     * yield the same `ScopeId` (or `null`) across invocations. No closure over
+     * mutable state. Required so scope-tree construction stays deterministic
+     * across re-parses.
+     *
+     * Default: undefined (the central extractor uses `innermostScope.id`).
+     */
+    readonly bindingScopeFor?: (declCapture: CaptureMatch, innermostScope: Scope, scopeTree: ScopeTree) => ScopeId | null;
+    /**
+     * Resolve a `ParsedImport.targetRaw` expression to a concrete file path in
+     * the workspace. Language-specific resolution: Python relative imports,
+     * JS package.json + node_modules, Go module paths, Java classpath,
+     * COBOL COPY paths. Ports today's per-language import resolver.
+     *
+     * Required when `emitScopeCaptures` is implemented. Ring 2 PKG #922
+     * provides the adapter that bridges today's resolver shape to this hook.
+     */
+    readonly resolveImportTarget?: (parsedImport: ParsedImport, workspaceIndex: WorkspaceIndex) => string | null;
+    /**
+     * Enumerate the exported names of a file — used by the finalize algorithm
+     * to expand `import * from M` into individual `BindingRef`s with
+     * `origin: 'wildcard'`.
+     *
+     * Default: undefined (central finalize walks the target file's
+     * `ExportMap.keys()`).
+     */
+    readonly expandsWildcardTo?: (targetFile: string, workspaceIndex: WorkspaceIndex) => readonly string[];
+    /**
+     * Decide the scope to which a `ParsedImport` attaches. Most languages
+     * attach imports to the nearest enclosing `Module`/`Namespace` scope
+     * (the default); some languages allow local imports (Python function-local
+     * `from x import Y`, Rust fn-local `use`, TS dynamic `import()`) — return
+     * a `Function`/`Block` scope id instead.
+     *
+     * Return `null` to delegate to the central default (nearest enclosing
+     * `Module`/`Namespace`). This matches the `X | null` convention used by
+     * the other optional hooks and supports partial overrides — a provider
+     * that handles only specific import forms non-standardly can `return null`
+     * for the common cases and let the central walk handle them.
+     *
+     * **Purity:** must be a pure function of its inputs — same parameters must
+     * yield the same `ScopeId` (or `null`) across invocations. No closure over
+     * mutable state. Required so scope-tree construction stays deterministic
+     * across re-parses.
+     *
+     * Default: undefined (central finalize walks to the nearest enclosing
+     * `Module` or `Namespace` scope).
+     */
+    readonly importOwningScope?: (parsedImport: ParsedImport, innermostScope: Scope, scopeTree: ScopeTree) => ScopeId | null;
+    /**
+     * Merge local declarations and imported bindings for a single (scope, name)
+     * during finalize materialization of a scope's binding table. Language-
+     * specific precedence: Python local hides import; TypeScript namespace
+     * merging keeps both; Ruby constant resolution has its own rules.
+     *
+     * Default: undefined (central finalize uses local-first-then-imports,
+     * deduping by `DefId`).
+     */
+    readonly mergeBindings?: (scope: Scope, bindings: readonly BindingRef[]) => readonly BindingRef[];
+    /**
+     * Classify a `@reference.call` capture as free / member / constructor /
+     * index. Preferred path is declarative via capture sub-tags
+     * (`@reference.call.free`, etc.); this hook handles the languages where
+     * call form can't be decided statically (Ruby bare `foo(x)` is free-or-
+     * member until resolved).
+     *
+     * Default: undefined (central extractor reads capture sub-tag if present;
+     * else treats as `'free'`).
+     */
+    readonly classifyCallForm?: (captures: CaptureMatch, enclosingScope: Scope) => 'free' | 'member' | 'constructor' | 'index';
+    /**
+     * Does a binding at this scope shadow bindings of the same name in outer
+     * scopes? Default: any binding shadows (standard lexical scoping). Return
+     * `false` for transparent-scope edge cases (Python `from x import *`
+     * contexts, JS `var` hoisting quirks, COBOL PARAGRAPH transparency).
+     *
+     * Consulted by `Registry.lookup` Step 1 and by `resolveTypeRef` for
+     * shadowing decisions during the lexical chain walk.
+     *
+     * Default: undefined (treated as `true` — any binding shadows).
+     */
+    readonly shouldShadow?: (scope: Scope, bindings: readonly BindingRef[]) => boolean;
+    /**
+     * Is this callable definition compatible with the given call-site arity?
+     * Language-specific rules: Python `*args`/`**kwargs`/defaults, JS default
+     * params + rest, Kotlin vararg + defaults, Ruby optional/splat/block, Go
+     * straight counts, Rust no-variadic-no-defaults.
+     *
+     * `'incompatible'` is a soft penalty (−0.15 per EvidenceWeights) and is
+     * filtered only when at least one `'compatible'` candidate exists;
+     * otherwise the incompatible candidate is kept with the penalty so the
+     * call-site still links to a best-guess target.
+     *
+     * Default: undefined (treated as `'unknown'` — no signal either way).
+     */
+    readonly arityCompatibility?: (def: SymbolDefinition, callsite: Callsite) => 'compatible' | 'unknown' | 'incompatible';
 }
 /** Runtime type — same as LanguageProviderConfig but with defaults guaranteed present. */
 export interface LanguageProvider extends Omit<LanguageProviderConfig, 'importSemantics' | 'heritageDefaultEdge' | 'mroStrategy'> {

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

@@ -4,7 +4,7 @@
  * 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';
+import type { SymbolDefinition } from '../../../_shared/index.js';
 export interface FieldRegistry {
     /** Look up a field/property by its owning class nodeId and field name. */
     lookupFieldByOwner(ownerNodeId: string, fieldName: string): SymbolDefinition | undefined;

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

@@ -10,7 +10,7 @@
  * `SymbolTable` by design.
  */
 export { type SemanticModel, type MutableSemanticModel, createSemanticModel, } from './semantic-model.js';
-export { type SymbolTableReader, type SymbolTableWriter, createSymbolTable, type SymbolDefinition, 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 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';

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

@@ -17,6 +17,8 @@ export { createSemanticModel, } from './semantic-model.js';
 // 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 `gitnexus-shared` (RFC #909 Ring 1 #910).
+// Consumers should import it directly from `gitnexus-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)

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

@@ -6,7 +6,7 @@
  * `ownerNodeId\0methodName` for O(1) lookup. Supports overloads
  * (array values) and arity-based filtering.
  */
-import type { SymbolDefinition } from './symbol-table.js';
+import type { SymbolDefinition } from '../../../_shared/index.js';
 export interface MethodRegistry {
     /**
      * Look up a method by owner class + name, optionally filtered by arity.

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

@@ -48,8 +48,7 @@
  * 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 { NodeLabel, SymbolDefinition } from '../../../_shared/index.js';
 import type { MutableTypeRegistry } from './type-registry.js';
 import type { MutableMethodRegistry } from './method-registry.js';
 import type { MutableFieldRegistry } from './field-registry.js';

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

@@ -17,7 +17,7 @@
  * - 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 { SymbolDefinition } from '../../../_shared/index.js';
 import type { MutableSemanticModel } from './semantic-model.js';
 /**
  * A single named binding in a source file (e.g. `import { User as U }`).