gitnexus 1.6.3-rc.2 → 1.6.3-rc.21

package/dist/core/ingestion/import-target-adapter.js

@@ -0,0 +1,95 @@
+/**
+ * Bridge between CLI-package per-language `ImportResolverFn`s and the
+ * shared `FinalizeHooks.resolveImportTarget` contract
+ * (RFC §5.2; Ring 2 PKG #922).
+ *
+ * The shared finalize algorithm (#915) asks one question:
+ *
+ *     resolveImportTarget(targetRaw, fromFile, workspaceIndex): string | null
+ *
+ * The CLI already has 16 language-specific resolvers satisfying a
+ * richer signature:
+ *
+ *     ImportResolverFn(rawImportPath, filePath, resolveCtx): ImportResult
+ *
+ * This module builds a dispatch adapter — one FinalizeHook implementation
+ * that looks up the file's language from its path and delegates to the
+ * right per-language resolver. Callers package per-language resolvers +
+ * a shared `ResolveCtx` into an opaque `ImportTargetWorkspace` and pass
+ * it as `workspaceIndex` to `finalizeScopeModel`.
+ *
+ * ## What's deliberately NOT here
+ *
+ *   - **Re-implementation of any per-language resolver.** We wrap the
+ *     existing `importResolver` field on each `LanguageProvider` — the
+ *     same code path the legacy DAG uses today.
+ *   - **Dynamic-import handling.** The shared finalize algorithm short-
+ *     circuits `ParsedImport { kind: 'dynamic-unresolved' }` before
+ *     calling `resolveImportTarget`, so the adapter never sees those.
+ *   - **`importPathPreprocessor`.** Preprocessing belongs inside the
+ *     provider's `interpretImport` hook (which writes the final
+ *     `ParsedImport.targetRaw`). By the time finalize passes a
+ *     `targetRaw` to this adapter, it is the string the provider wants
+ *     resolved verbatim.
+ */
+import { getLanguageFromFilename, } from '../../_shared/index.js';
+/**
+ * Build the workspace index from a map of language → provider. Providers
+ * whose `importResolver` is absent are silently skipped (no language will
+ * ever hit that branch at dispatch time).
+ *
+ * The `resolveCtx` is shared across all languages. Callers assemble it
+ * once per run (the existing pipeline already does this for the legacy
+ * DAG) and hand it to both the legacy resolution path and this factory.
+ */
+export function buildImportTargetWorkspace(providers, resolveCtx) {
+    const perLanguage = new Map();
+    for (const [lang, provider] of providers) {
+        if (provider.importResolver === undefined)
+            continue;
+        perLanguage.set(lang, { resolver: provider.importResolver, ctx: resolveCtx });
+    }
+    return { perLanguage };
+}
+/**
+ * The FinalizeHooks-compatible implementation. Dispatches on `fromFile`'s
+ * extension → per-language resolver. Returns the first resolved file,
+ * or `null` if the resolver returns `null` or doesn't know about the
+ * language.
+ *
+ * Picks the first entry of `files[]` for both `'files'` and `'package'`
+ * result kinds — the legacy pipeline uses the whole array, but the
+ * shared `finalize()` hook contract is single-file. If the workspace
+ * later needs richer semantics (split-target packages), this is the
+ * single site to extend.
+ */
+export function resolveImportTargetAcrossLanguages(targetRaw, fromFile, workspaceIndex) {
+    const workspace = workspaceIndex;
+    if (workspace === undefined || workspace.perLanguage === undefined)
+        return null;
+    const lang = getLanguageFromFilename(fromFile);
+    if (lang === null)
+        return null;
+    const entry = workspace.perLanguage.get(lang);
+    if (entry === undefined)
+        return null;
+    let result;
+    try {
+        result = entry.resolver(targetRaw, fromFile, entry.ctx);
+    }
+    catch {
+        // Existing resolvers can throw on malformed inputs (e.g., Python
+        // relative paths above the workspace root). Swallow — the shared
+        // algorithm treats a null here as `linkStatus: 'unresolved'`, which
+        // is the right fallback.
+        return null;
+    }
+    if (result === null)
+        return null;
+    // Both `files` and `package` variants expose a `files` array; the
+    // package variant also carries `dirSuffix` which we ignore at the
+    // FinalizeHook boundary (single-file contract). Legacy consumers
+    // continue to see the full result via `importResolver` directly.
+    const first = result.files[0];
+    return first ?? null;
+}

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, 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,192 @@ 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, **pre-grouped per tree-sitter
+     * query match**. Tree-sitter-based providers run a `scopes.scm` query
+     * and emit one `CaptureMatch` per query match; standalone providers
+     * (COBOL) emit matches from a regex tagger. The return shape is
+     * parser-agnostic: the central `ScopeExtractor` consumes
+     * `CaptureMatch[]` without knowing which parser produced them.
+     *
+     * **Pre-grouping is the provider's job.** The extractor expects each
+     * `CaptureMatch` to correspond to one logical match — e.g., an import
+     * statement match carries `@import.statement` + `@import.source` +
+     * `@import.name` keyed under their capture names. Providers MUST
+     * preserve the tree-sitter match boundaries so the extractor's topic
+     * routing (scope / declaration / import / type-binding / reference)
+     * lands on coherent records.
+     *
+     * 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>`).
+     *
+     * **Sync return.** Tree-sitter query execution and COBOL's regex
+     * tagger are both synchronous; no current or foreseeable provider
+     * needs async work inside this hook. The sync signature lets
+     * `parse-worker.ts` (#920) invoke it inline in its already-sync
+     * per-file loop without cascading `async` through the batch pipeline.
+     *
+     * Default: undefined (language continues to use legacy DAG).
+     */
+    readonly emitScopeCaptures?: (sourceText: string, filePath: string) => readonly CaptureMatch[];
+    /**
+     * 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/scope-resolution-indexes.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `ScopeResolutionIndexes` — the bundle of materialized indexes produced
+ * by the finalize-orchestrator (RFC #909 Ring 2 PKG #921) and attached
+ * to `MutableSemanticModel`.
+ *
+ * Produced by `finalizeScopeModel(parsedFiles, hooks)` in
+ * `finalize-orchestrator.ts`. Consumed by the resolution phase (future
+ * tickets) where `Registry.lookup` / `resolveTypeRef` query this bundle
+ * to answer call-resolution questions without re-walking any AST.
+ *
+ * ## Lifecycle
+ *
+ *   1. Pipeline collects `ParsedFile[]` from the parsing-processor (#920).
+ *   2. Pipeline invokes `finalizeScopeModel(parsedFiles, hooks)` →
+ *      returns a `ScopeResolutionIndexes` (this interface).
+ *   3. Pipeline calls `model.attachScopeIndexes(indexes)` to stamp them
+ *      onto the `MutableSemanticModel`. This is a **one-shot write**;
+ *      subsequent calls throw. After attachment, the indexes are frozen
+ *      at the type level (everything is `readonly`) and at runtime via
+ *      `Object.freeze` on the bundle.
+ *   4. Resolution callers hold a `SemanticModel` reference and read
+ *      `model.scopes` to query.
+ *
+ * ## Content
+ *
+ *   - `scopeTree` / `moduleScopes` / `defs` / `qualifiedNames` — the
+ *     four Ring 2 SHARED indexes built over per-file artifacts.
+ *   - `methodDispatch` — MRO + implements materialized view (#914).
+ *   - `imports` — finalized `ImportEdge[]` per module scope (`parsedImports`
+ *     resolved through cross-file link + wildcard expansion).
+ *   - `bindings` — merged bindings per module scope (local + import +
+ *     wildcard + re-export), with the provider's precedence applied.
+ *   - `referenceSites` — union of every file's pre-resolution usage
+ *     facts. Consumed by the resolution phase (future) to emit
+ *     `Reference` records into `ReferenceIndex`.
+ *   - `stats` — coarse-grained counts from the shared finalize algorithm
+ *     (total files/edges, linked vs unresolved, SCC topology).
+ *
+ * `ReferenceIndex` is deliberately NOT here — it is populated in a later
+ * phase (RFC §3.2 Phase 4 / Ring 2 PKG #925) and owned separately.
+ */
+import type { BindingRef, DefIndex, FinalizedScc, FinalizeStats, ImportEdge, MethodDispatchIndex, ModuleScopeIndex, QualifiedNameIndex, ReferenceSite, ScopeId, ScopeTree } from '../../../_shared/index.js';
+export interface ScopeResolutionIndexes {
+    readonly scopeTree: ScopeTree;
+    readonly defs: DefIndex;
+    readonly qualifiedNames: QualifiedNameIndex;
+    readonly moduleScopes: ModuleScopeIndex;
+    readonly methodDispatch: MethodDispatchIndex;
+    /** Finalized `ImportEdge[]` per module scope. */
+    readonly imports: ReadonlyMap<ScopeId, readonly ImportEdge[]>;
+    /** Merged bindings (local + imports + wildcards) per module scope. */
+    readonly bindings: ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>;
+    /** Pre-resolution usage facts; consumed by the resolution phase. */
+    readonly referenceSites: readonly ReferenceSite[];
+    /** SCC condensation of the file-level import graph — callers that want
+     *  parallel per-SCC processing in the resolution phase read this. */
+    readonly sccs: readonly FinalizedScc[];
+    readonly stats: FinalizeStats;
+}

package/dist/core/ingestion/model/scope-resolution-indexes.js

@@ -0,0 +1,42 @@
+/**
+ * `ScopeResolutionIndexes` — the bundle of materialized indexes produced
+ * by the finalize-orchestrator (RFC #909 Ring 2 PKG #921) and attached
+ * to `MutableSemanticModel`.
+ *
+ * Produced by `finalizeScopeModel(parsedFiles, hooks)` in
+ * `finalize-orchestrator.ts`. Consumed by the resolution phase (future
+ * tickets) where `Registry.lookup` / `resolveTypeRef` query this bundle
+ * to answer call-resolution questions without re-walking any AST.
+ *
+ * ## Lifecycle
+ *
+ *   1. Pipeline collects `ParsedFile[]` from the parsing-processor (#920).
+ *   2. Pipeline invokes `finalizeScopeModel(parsedFiles, hooks)` →
+ *      returns a `ScopeResolutionIndexes` (this interface).
+ *   3. Pipeline calls `model.attachScopeIndexes(indexes)` to stamp them
+ *      onto the `MutableSemanticModel`. This is a **one-shot write**;
+ *      subsequent calls throw. After attachment, the indexes are frozen
+ *      at the type level (everything is `readonly`) and at runtime via
+ *      `Object.freeze` on the bundle.
+ *   4. Resolution callers hold a `SemanticModel` reference and read
+ *      `model.scopes` to query.
+ *
+ * ## Content
+ *
+ *   - `scopeTree` / `moduleScopes` / `defs` / `qualifiedNames` — the
+ *     four Ring 2 SHARED indexes built over per-file artifacts.
+ *   - `methodDispatch` — MRO + implements materialized view (#914).
+ *   - `imports` — finalized `ImportEdge[]` per module scope (`parsedImports`
+ *     resolved through cross-file link + wildcard expansion).
+ *   - `bindings` — merged bindings per module scope (local + import +
+ *     wildcard + re-export), with the provider's precedence applied.
+ *   - `referenceSites` — union of every file's pre-resolution usage
+ *     facts. Consumed by the resolution phase (future) to emit
+ *     `Reference` records into `ReferenceIndex`.
+ *   - `stats` — coarse-grained counts from the shared finalize algorithm
+ *     (total files/edges, linked vs unresolved, SCC topology).
+ *
+ * `ReferenceIndex` is deliberately NOT here — it is populated in a later
+ * phase (RFC §3.2 Phase 4 / Ring 2 PKG #925) and owned separately.
+ */
+export {};

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

@@ -49,6 +49,7 @@ import type { TypeRegistry, MutableTypeRegistry } from './type-registry.js';
 import type { MethodRegistry, MutableMethodRegistry } from './method-registry.js';
 import type { FieldRegistry, MutableFieldRegistry } from './field-registry.js';
 import type { SymbolTableReader, SymbolTableWriter } from './symbol-table.js';
+import type { ScopeResolutionIndexes } from './scope-resolution-indexes.js';
 /**
  * Aggregated read-only view of the semantic registries plus the nested
  * file/callable SymbolTable.
@@ -70,6 +71,19 @@ export interface SemanticModel {
     readonly methods: MethodRegistry;
     readonly fields: FieldRegistry;
     readonly symbols: SymbolTableReader;
+    /**
+     * Materialized scope-resolution indexes from RFC #909 Ring 2 PKG #921.
+     *
+     * `undefined` until the finalize-orchestrator attaches them. While
+     * `undefined`, the legacy DAG is the sole resolution surface; once set,
+     * resolvers whose language has `REGISTRY_PRIMARY_<LANG>=true` consult
+     * these indexes instead.
+     *
+     * The attach is a one-shot write (see `MutableSemanticModel`). Callers
+     * holding a read-only `SemanticModel` handle see either `undefined` or
+     * the final frozen bundle — never a half-populated view.
+     */
+    readonly scopes?: ScopeResolutionIndexes;
 }
 /** Mutable variant — exposes the MutableX registries, a Writer-typed
  *  `symbols` facade, and a full-cascade reset. This is the interface
@@ -82,5 +96,16 @@ export interface MutableSemanticModel extends SemanticModel {
     readonly symbols: SymbolTableWriter;
     /** Clear all registries AND the nested SymbolTable. */
     clear(): void;
+    /**
+     * Stamp the finalize-orchestrator's output onto this model.
+     *
+     * **One-shot write.** Throws when called a second time — the indexes are
+     * meant to be materialized once per ingestion run. `Object.freeze` is
+     * applied to the attached bundle so consumers cannot mutate after attach.
+     *
+     * `clear()` resets the attached bundle back to `undefined`, enabling a
+     * fresh re-ingestion to attach a new bundle.
+     */
+    attachScopeIndexes(indexes: ScopeResolutionIndexes): void;
 }
 export declare const createSemanticModel: () => MutableSemanticModel;

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

@@ -85,6 +85,17 @@ export const createSemanticModel = () => {
         }
         return def;
     };
+    // Scope-resolution bundle slot. Starts `undefined`; populated by a
+    // one-shot `attachScopeIndexes(...)` from the finalize-orchestrator.
+    // Held inside the factory closure so the returned `SemanticModel`
+    // surface exposes it as a plain `readonly` property without a setter.
+    let attachedScopes;
+    const attachScopeIndexes = (indexes) => {
+        if (attachedScopes !== undefined) {
+            throw new Error('SemanticModel: scope indexes already attached. ' + 'Call `clear()` before re-attaching.');
+        }
+        attachedScopes = Object.freeze(indexes);
+    };
     // Cascade clear: single source of truth for "reset the entire model".
     // Wired into both `model.clear()` AND `model.symbols.clear()` so that a
     // caller holding only a SymbolTable reference can't leave the
@@ -95,6 +106,7 @@ export const createSemanticModel = () => {
         methods.clear();
         fields.clear();
         rawSymbols.clear();
+        attachedScopes = undefined;
     };
     // Writer-typed facade: exposes reads + add, but NO `clear` field.
     // Callers holding a `SemanticModel.symbols` reference cannot desync
@@ -115,6 +127,10 @@ export const createSemanticModel = () => {
         methods,
         fields,
         symbols,
+        get scopes() {
+            return attachedScopes;
+        },
         clear: cascadeClear,
+        attachScopeIndexes,
     };
 };

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

@@ -1,6 +1,7 @@
 import { KnowledgeGraph } from '../graph/types.js';
 import type { SymbolTableWriter, ExtractedHeritage } from './model/index.js';
 import { ASTCache } from './ast-cache.js';
+import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
 import type { ExtractedImport, ExtractedCall, ExtractedAssignment, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedToolDef, FileConstructorBindings, FileScopeBindings, ExtractedORMQuery } from './workers/parse-worker.js';
 export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
@@ -16,6 +17,14 @@ export interface WorkerExtractedData {
     ormQueries: ExtractedORMQuery[];
     constructorBindings: FileConstructorBindings[];
     fileScopeBindings: FileScopeBindings[];
+    /**
+     * Per-file `ParsedFile` artifacts from the new scope-based resolution
+     * pipeline (RFC #909 Ring 2). Empty until a provider implements
+     * `emitScopeCaptures` — additive to the legacy DAG path. Aggregated
+     * from every worker chunk; consumed downstream by #921's
+     * finalize-orchestrator.
+     */
+    parsedFiles: ParsedFile[];
 }
 export declare const processParsing: (graph: KnowledgeGraph, files: {
     path: string;

package/dist/core/ingestion/parsing-processor.js

@@ -34,6 +34,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
             ormQueries: [],
             constructorBindings: [],
             fileScopeBindings: [],
+            parsedFiles: [],
         };
     const total = files.length;
     // Dispatch to worker pool — pool handles splitting into chunks and sub-batching
@@ -52,6 +53,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
     const allORMQueries = [];
     const allConstructorBindings = [];
     const fileScopeBindingsByFile = [];
+    const allParsedFiles = [];
     for (const result of chunkResults) {
         for (const node of result.nodes) {
             graph.addNode({
@@ -98,6 +100,13 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
         if (result.fileScopeBindings)
             for (const item of result.fileScopeBindings)
                 fileScopeBindingsByFile.push(item);
+        // RFC #909 Ring 2: aggregate per-file scope artifacts. Tolerant of
+        // workers that don't emit the field yet (older worker builds or
+        // partial rollouts), since the additive contract means undefined =
+        // "this worker produced no ParsedFiles for this chunk".
+        if (result.parsedFiles)
+            for (const item of result.parsedFiles)
+                allParsedFiles.push(item);
     }
     // Merge and log skipped languages from workers
     const skippedLanguages = new Map();
@@ -126,6 +135,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
         ormQueries: allORMQueries,
         constructorBindings: allConstructorBindings,
         fileScopeBindings: fileScopeBindingsByFile,
+        parsedFiles: allParsedFiles,
     };
 };
 // ============================================================================

package/dist/core/ingestion/registry-primary-flag.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `REGISTRY_PRIMARY_<LANG>` per-language feature flags for the scope-based
+ * resolution rollout (RFC §6.1 Ring 3; Ring 2 PKG #924).
+ *
+ * This module is the single source of truth for whether a given language
+ * has been flipped to registry-primary call resolution. When a language's
+ * flag is true, its files route through `Registry.lookup` (RFC §4) instead
+ * of the legacy call-resolution DAG; when false (the default), the legacy
+ * DAG runs unchanged.
+ *
+ * ## Contract
+ *
+ *   - Env-var name per language: `REGISTRY_PRIMARY_<UPPER(enum-value)>`.
+ *     Example: `SupportedLanguages.Python` → `REGISTRY_PRIMARY_PYTHON`;
+ *     `SupportedLanguages.CPlusPlus` (value `'cpp'`) → `REGISTRY_PRIMARY_CPP`.
+ *   - Truthy values: `'true'`, `'1'`, `'yes'` (case-insensitive,
+ *     whitespace-trimmed). Anything else — including `undefined`, empty
+ *     string, or unknown tokens — is `false`.
+ *   - No per-process caching. `process.env` is read on every call. The
+ *     flag is consulted once per file at call-resolution time, so the
+ *     overhead is negligible; skipping caching keeps test isolation
+ *     trivial (no `resetFlagCache()` coordination needed).
+ *
+ * ## Integration site
+ *
+ * `call-processor.ts` integration lands in **#921** (`finalize-orchestrator`)
+ * where the `SemanticModel` becomes accessible and `Registry.lookup` can
+ * actually be called with a populated context. This module ships the flag
+ * primitive in isolation so #921 has a clean, tested utility to consult.
+ *
+ * ## Shadow mode is orthogonal
+ *
+ * Shadow mode (`GITNEXUS_SHADOW_MODE=1`, introduced in #923) runs BOTH
+ * legacy and registry paths regardless of the per-language flag, so the
+ * parity dashboard has signal even for un-flipped languages. That logic
+ * lives in `shadow-harness.ts` (#923), not here.
+ */
+import { SupportedLanguages } from '../../_shared/index.js';
+/**
+ * Return the env-var name that controls a given language's registry-
+ * primary flag. Exported for test assertions and for the PR-labeling
+ * CI job that cross-references per-language flag changes.
+ */
+export declare function envVarNameFor(lang: SupportedLanguages): string;
+/**
+ * Whether `lang` has been flipped to registry-primary call resolution.
+ *
+ * Returns `false` by default — a language must explicitly set its env
+ * var to a truthy value to opt in. The flag is the sole control surface:
+ * flipping it requires no code change, and reverting it requires no code
+ * change.
+ */
+export declare function isRegistryPrimary(lang: SupportedLanguages): boolean;
+/**
+ * All languages whose registry-primary flag is currently on. Useful for
+ * startup-time logging + the shadow-harness dashboard, which wants to
+ * distinguish "primary: legacy" from "primary: registry" rows.
+ */
+export declare function primaryLanguages(): ReadonlySet<SupportedLanguages>;