gitnexus 1.6.3-rc.13 → 1.6.3-rc.15

package/dist/core/ingestion/finalize-orchestrator.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `finalizeScopeModel` — turn a workspace's `ParsedFile[]` into a
+ * materialized `ScopeResolutionIndexes` (RFC §3.2 Phase 2; Ring 2 PKG #921).
+ *
+ * Thin integration glue, per issue #884's boundary: all algorithmic logic
+ * lives in `gitnexus-shared` (finalize algorithm #915, the four per-file
+ * indexes #913, the method-dispatch materialization #914, the scope tree
+ * #912). This file does three things only:
+ *
+ *   1. Map `ParsedFile[]` → `FinalizeInput` and call shared `finalize()`.
+ *   2. Build the four workspace-wide indexes from the union of per-file
+ *      defs/scopes/modules/qualified-names.
+ *   3. Bundle the results into `ScopeResolutionIndexes` for
+ *      `MutableSemanticModel.attachScopeIndexes(...)`.
+ *
+ * ## What this module is NOT responsible for
+ *
+ *   - Invoking tree-sitter or running AST walks. That's the extractor (#919).
+ *   - Per-language import-target resolution. Hooks are plumbed through
+ *     but default to "unresolved" when no provider supplies them — the
+ *     real adapters land with #922.
+ *   - Populating `ReferenceIndex`. That's the resolution phase (#925).
+ *   - Deciding which language uses registry-primary lookup. That's the
+ *     flag reader (#924).
+ *
+ * ## Empty-input behavior
+ *
+ * When `parsedFiles` is empty (the common case today — no language has
+ * migrated yet), the orchestrator produces a valid but empty bundle: all
+ * indexes are zero-sized, the scope tree is empty, and
+ * `finalize.stats.totalFiles === 0`. This lets downstream consumers
+ * safely consult `model.scopes` without branching on presence.
+ */
+import type { FinalizeHooks, ParsedFile, WorkspaceIndex } from '../../_shared/index.js';
+import type { ScopeResolutionIndexes } from './model/scope-resolution-indexes.js';
+/**
+ * Options forwarded to the orchestrator. All fields optional so callers
+ * that don't yet have per-language hooks (today) get sensible defaults;
+ * #922 will populate `hooks.resolveImportTarget` + friends per language.
+ */
+export interface FinalizeOrchestratorOptions {
+    /**
+     * Hooks forwarded to shared `finalize()`. Any omitted field gets a
+     * no-op default: unresolved targets, empty wildcard expansion, append
+     * merge for bindings.
+     */
+    readonly hooks?: Partial<FinalizeHooks>;
+    /**
+     * Opaque workspace context forwarded to hooks. `undefined` today; Ring
+     * 2 PKG #922 populates this with a real cross-file index for the
+     * per-language resolvers.
+     */
+    readonly workspaceIndex?: WorkspaceIndex;
+}
+/**
+ * Produce a fully materialized `ScopeResolutionIndexes` from the
+ * workspace's per-file artifacts.
+ *
+ * Pure function (given pure hooks). No I/O, no globals consulted. The
+ * pipeline calls this once per ingestion run and hands the result to
+ * `MutableSemanticModel.attachScopeIndexes`.
+ */
+export declare function finalizeScopeModel(parsedFiles: readonly ParsedFile[], options?: FinalizeOrchestratorOptions): ScopeResolutionIndexes;

package/dist/core/ingestion/finalize-orchestrator.js

@@ -0,0 +1,139 @@
+/**
+ * `finalizeScopeModel` — turn a workspace's `ParsedFile[]` into a
+ * materialized `ScopeResolutionIndexes` (RFC §3.2 Phase 2; Ring 2 PKG #921).
+ *
+ * Thin integration glue, per issue #884's boundary: all algorithmic logic
+ * lives in `gitnexus-shared` (finalize algorithm #915, the four per-file
+ * indexes #913, the method-dispatch materialization #914, the scope tree
+ * #912). This file does three things only:
+ *
+ *   1. Map `ParsedFile[]` → `FinalizeInput` and call shared `finalize()`.
+ *   2. Build the four workspace-wide indexes from the union of per-file
+ *      defs/scopes/modules/qualified-names.
+ *   3. Bundle the results into `ScopeResolutionIndexes` for
+ *      `MutableSemanticModel.attachScopeIndexes(...)`.
+ *
+ * ## What this module is NOT responsible for
+ *
+ *   - Invoking tree-sitter or running AST walks. That's the extractor (#919).
+ *   - Per-language import-target resolution. Hooks are plumbed through
+ *     but default to "unresolved" when no provider supplies them — the
+ *     real adapters land with #922.
+ *   - Populating `ReferenceIndex`. That's the resolution phase (#925).
+ *   - Deciding which language uses registry-primary lookup. That's the
+ *     flag reader (#924).
+ *
+ * ## Empty-input behavior
+ *
+ * When `parsedFiles` is empty (the common case today — no language has
+ * migrated yet), the orchestrator produces a valid but empty bundle: all
+ * indexes are zero-sized, the scope tree is empty, and
+ * `finalize.stats.totalFiles === 0`. This lets downstream consumers
+ * safely consult `model.scopes` without branching on presence.
+ */
+import { buildDefIndex, buildMethodDispatchIndex, buildModuleScopeIndex, buildQualifiedNameIndex, buildScopeTree, finalize, } from '../../_shared/index.js';
+/**
+ * Produce a fully materialized `ScopeResolutionIndexes` from the
+ * workspace's per-file artifacts.
+ *
+ * Pure function (given pure hooks). No I/O, no globals consulted. The
+ * pipeline calls this once per ingestion run and hands the result to
+ * `MutableSemanticModel.attachScopeIndexes`.
+ */
+export function finalizeScopeModel(parsedFiles, options = {}) {
+    const hooks = withDefaultHooks(options.hooks ?? {});
+    const workspaceIndex = options.workspaceIndex ?? undefined;
+    // ── Step 1: Shared finalize — runs SCC-aware cross-file link + binding
+    // materialization. Returns linked imports + merged bindings per module
+    // scope + SCC condensation + stats.
+    const finalizeInput = {
+        files: parsedFiles.map(toFinalizeFile),
+        workspaceIndex,
+    };
+    const finalizeOut = finalize(finalizeInput, hooks);
+    // ── Step 2: Workspace-wide indexes built from the per-file unions.
+    // These are pure aggregations — no algorithm beyond what the builders
+    // in gitnexus-shared already encapsulate (first-write-wins, qname
+    // collision buckets, etc.).
+    const allScopes = [];
+    const allDefs = [];
+    const moduleEntries = [];
+    const allReferenceSites = [];
+    for (const file of parsedFiles) {
+        for (const s of file.scopes)
+            allScopes.push(s);
+        for (const d of file.localDefs)
+            allDefs.push(d);
+        moduleEntries.push({ filePath: file.filePath, moduleScopeId: file.moduleScope });
+    }
+    // References kept out of the loop above to centralize list-init.
+    allReferenceSites.push(...collectReferenceSites(parsedFiles));
+    const scopeTree = buildScopeTree(allScopes);
+    const defs = buildDefIndex(allDefs);
+    const qualifiedNames = buildQualifiedNameIndex(allDefs);
+    const moduleScopes = buildModuleScopeIndex(moduleEntries);
+    // ── Step 3: MethodDispatchIndex. Today we lack per-language MRO
+    // strategies wired into this orchestrator (that belongs with the
+    // HeritageMap bridge, a separate piece of work). Ship an EMPTY index
+    // so the bundle shape is consistent; the callbacks return `[]` for
+    // every owner and `implementsOf` returns `[]`. Populating this
+    // properly is tracked alongside the per-language provider hooks.
+    const methodDispatch = buildMethodDispatchIndex({
+        owners: [], // empty → no MRO entries; `mroFor(x)` returns the frozen empty array
+        computeMro: () => [],
+        implementsOf: () => [],
+    });
+    return {
+        scopeTree,
+        defs,
+        qualifiedNames,
+        moduleScopes,
+        methodDispatch,
+        imports: finalizeOut.imports,
+        bindings: finalizeOut.bindings,
+        referenceSites: Object.freeze([...allReferenceSites]),
+        sccs: finalizeOut.sccs,
+        stats: finalizeOut.stats,
+    };
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/** Shape-reduce a `ParsedFile` to the narrower `FinalizeFile` the shared
+ *  algorithm reads. The subset is stable — `FinalizeFile` is a proper
+ *  subset of `ParsedFile`. */
+function toFinalizeFile(file) {
+    return {
+        filePath: file.filePath,
+        moduleScope: file.moduleScope,
+        parsedImports: file.parsedImports,
+        localDefs: file.localDefs,
+    };
+}
+/** Flatten every file's reference sites into one list. Order reflects
+ *  input-file order, then capture order inside each file. Deterministic. */
+function collectReferenceSites(parsedFiles) {
+    const out = [];
+    for (const file of parsedFiles) {
+        for (const site of file.referenceSites)
+            out.push(site);
+    }
+    return out;
+}
+/**
+ * Fill in no-op defaults for any omitted hook. Keeps `finalize()`
+ * behavior well-defined for the zero-provider case today:
+ *
+ *   - `resolveImportTarget: () => null` — every import edge ends up
+ *     `linkStatus: 'unresolved'` (or dynamic-unresolved pass-through).
+ *   - `expandsWildcardTo: () => []` — wildcards don't materialize.
+ *   - `mergeBindings: (existing, incoming) => [...existing, ...incoming]`
+ *     — append without precedence; providers override to implement local-
+ *     shadows-import and similar rules.
+ */
+function withDefaultHooks(partial) {
+    return {
+        resolveImportTarget: partial.resolveImportTarget ?? (() => null),
+        expandsWildcardTo: partial.expandsWildcardTo ?? (() => []),
+        mergeBindings: partial.mergeBindings ??
+            ((existing, incoming) => [...existing, ...incoming]),
+    };
+}

package/dist/core/ingestion/import-target-adapter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 { type SupportedLanguages, type WorkspaceIndex } from '../../_shared/index.js';
+import type { ImportResolverFn, ResolveCtx } from './import-resolvers/types.js';
+import type { LanguageProvider } from './language-provider.js';
+/** A single language's resolver bundled with the context it needs. */
+export interface LanguageResolverEntry {
+    readonly resolver: ImportResolverFn;
+    readonly ctx: ResolveCtx;
+}
+/**
+ * The opaque `workspaceIndex` shape recognized by
+ * `resolveImportTargetAcrossLanguages`. Built once per ingestion run via
+ * `buildImportTargetWorkspace`, threaded through `finalizeScopeModel`.
+ */
+export interface ImportTargetWorkspace {
+    readonly perLanguage: ReadonlyMap<SupportedLanguages, LanguageResolverEntry>;
+}
+/**
+ * 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 declare function buildImportTargetWorkspace(providers: ReadonlyMap<SupportedLanguages, LanguageProvider>, resolveCtx: ResolveCtx): ImportTargetWorkspace;
+/**
+ * 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 declare function resolveImportTargetAcrossLanguages(targetRaw: string, fromFile: string, workspaceIndex: WorkspaceIndex): string | null;

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/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/shadow-harness.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Shadow-mode parity harness — dual-run observability for the RFC #909
+ * registry rollout (RFC §6.3; Ring 2 PKG #923).
+ *
+ * ## What it does
+ *
+ *   - Exposes `record({ language, callsite, legacy, newResult })` for
+ *     every call site where the caller has BOTH a legacy-DAG resolution
+ *     and a new `Registry.lookup` resolution.
+ *   - Computes a `ShadowDiff` per record via shared `diffResolutions`
+ *     (#918) and accumulates them in a per-language bucket.
+ *   - At the end of a run, aggregates into a `ShadowParityReport` via
+ *     shared `aggregateDiffs` (#918) — per-language parity %,
+ *     evidence-kind breakdown of divergences, grand-total overall row.
+ *   - Optionally persists the report as JSON under
+ *     `.gitnexus/shadow-parity/` so the static dashboard at
+ *     `gitnexus/shadow-parity-dashboard/` can render it offline.
+ *
+ * ## What it does NOT do
+ *
+ *   - **Invoke either resolution path itself.** The caller must run
+ *     legacy + `Registry.lookup` and pass results in. The harness is a
+ *     side-car, not a dispatcher — this keeps call-processor integration
+ *     surgical when it lands (tracked as a follow-up; the shared model
+ *     doesn't dual-invoke on its own).
+ *   - **Flip anything.** `REGISTRY_PRIMARY_<LANG>` lives in
+ *     `registry-primary-flag.ts` (#924); the harness records the
+ *     caller-supplied "which side is primary" bit for each record so the
+ *     dashboard can label rows, but it does not consult the flag itself.
+ *
+ * ## Activation
+ *
+ * `GITNEXUS_SHADOW_MODE=1` (or `'true'`, `'yes'`, case-insensitive,
+ * trimmed) enables the harness. When disabled, `record()` is a cheap
+ * no-op: no accumulation, no allocation beyond the harness object
+ * itself. Callers can always construct a harness and hand it through;
+ * the "off" overhead is near-zero.
+ *
+ * ## Persistence shape
+ *
+ * When `persist()` is called, the harness writes TWO files:
+ *
+ *   - `<outputDir>/<runId>.json` — the timestamped snapshot (immutable)
+ *   - `<outputDir>/latest.json`  — a pointer that the dashboard reads
+ *
+ * Both files contain the same `PersistedShadowReport` payload:
+ *
+ *   {
+ *     schemaVersion: 1,
+ *     runId: "<iso-8601>-<rand>",
+ *     generatedAt: "<iso-8601>",
+ *     primaryByLanguage: { [lang]: "legacy" | "registry" },
+ *     report: <ShadowParityReport>
+ *   }
+ *
+ * Schema-version-gated so future format changes don't silently confuse
+ * older dashboards. The dashboard renders `report.perLanguage` rows and
+ * annotates each with `primaryByLanguage[lang]`.
+ */
+import { type Resolution, type ShadowCallsite, type ShadowParityReport, type SupportedLanguages } from '../../_shared/index.js';
+/** Which side of the dual-run is considered authoritative for this language. */
+export type PrimarySide = 'legacy' | 'registry';
+/** One record per call site the caller dual-runs. */
+export interface ShadowRecordInput {
+    readonly language: SupportedLanguages;
+    readonly callsite: ShadowCallsite;
+    readonly legacy: readonly Resolution[];
+    readonly newResult: readonly Resolution[];
+    /**
+     * Which side drove the actual runtime answer for this record. Lets the
+     * dashboard distinguish "registry-primary, legacy is shadow" from the
+     * default "legacy-primary, registry is shadow" without re-reading
+     * `REGISTRY_PRIMARY_<LANG>` env vars at render time.
+     */
+    readonly primary: PrimarySide;
+}
+/** Persisted JSON shape. Schema-versioned for future migrations. */
+export interface PersistedShadowReport {
+    readonly schemaVersion: 1;
+    readonly runId: string;
+    readonly generatedAt: string;
+    readonly primaryByLanguage: Readonly<Partial<Record<SupportedLanguages, PrimarySide>>>;
+    readonly report: ShadowParityReport;
+}
+export interface ShadowHarness {
+    /** `true` iff `GITNEXUS_SHADOW_MODE` is truthy. When `false`, `record()` is a no-op. */
+    readonly enabled: boolean;
+    /** Accumulate a dual-run observation. No-op when `enabled === false`. */
+    record(input: ShadowRecordInput): void;
+    /** Number of records accumulated so far. Useful for diagnostics / tests. */
+    size(): number;
+    /**
+     * Aggregate the accumulated records into a `ShadowParityReport`
+     * without persisting. Returns a deterministic snapshot each call;
+     * idempotent with respect to `record()` ordering.
+     */
+    snapshot(now?: Date): ShadowParityReport;
+    /**
+     * Write the aggregated snapshot to JSON. Resolves to the path of the
+     * per-run file. Also writes/overwrites `latest.json` alongside.
+     *
+     * Creates `outputDir` if it doesn't exist.
+     */
+    persist(outputDir: string, now?: Date): Promise<string>;
+    /** Reset the accumulator. Preserves `enabled`. */
+    clear(): void;
+}
+/**
+ * Construct a harness. Reads `GITNEXUS_SHADOW_MODE` at construction time
+ * (not per-`record()` call) so repeated no-op records don't re-check the
+ * env var in the hot path.
+ */
+export declare function createShadowHarness(): ShadowHarness;

package/dist/core/ingestion/shadow-harness.js

@@ -0,0 +1,148 @@
+/**
+ * Shadow-mode parity harness — dual-run observability for the RFC #909
+ * registry rollout (RFC §6.3; Ring 2 PKG #923).
+ *
+ * ## What it does
+ *
+ *   - Exposes `record({ language, callsite, legacy, newResult })` for
+ *     every call site where the caller has BOTH a legacy-DAG resolution
+ *     and a new `Registry.lookup` resolution.
+ *   - Computes a `ShadowDiff` per record via shared `diffResolutions`
+ *     (#918) and accumulates them in a per-language bucket.
+ *   - At the end of a run, aggregates into a `ShadowParityReport` via
+ *     shared `aggregateDiffs` (#918) — per-language parity %,
+ *     evidence-kind breakdown of divergences, grand-total overall row.
+ *   - Optionally persists the report as JSON under
+ *     `.gitnexus/shadow-parity/` so the static dashboard at
+ *     `gitnexus/shadow-parity-dashboard/` can render it offline.
+ *
+ * ## What it does NOT do
+ *
+ *   - **Invoke either resolution path itself.** The caller must run
+ *     legacy + `Registry.lookup` and pass results in. The harness is a
+ *     side-car, not a dispatcher — this keeps call-processor integration
+ *     surgical when it lands (tracked as a follow-up; the shared model
+ *     doesn't dual-invoke on its own).
+ *   - **Flip anything.** `REGISTRY_PRIMARY_<LANG>` lives in
+ *     `registry-primary-flag.ts` (#924); the harness records the
+ *     caller-supplied "which side is primary" bit for each record so the
+ *     dashboard can label rows, but it does not consult the flag itself.
+ *
+ * ## Activation
+ *
+ * `GITNEXUS_SHADOW_MODE=1` (or `'true'`, `'yes'`, case-insensitive,
+ * trimmed) enables the harness. When disabled, `record()` is a cheap
+ * no-op: no accumulation, no allocation beyond the harness object
+ * itself. Callers can always construct a harness and hand it through;
+ * the "off" overhead is near-zero.
+ *
+ * ## Persistence shape
+ *
+ * When `persist()` is called, the harness writes TWO files:
+ *
+ *   - `<outputDir>/<runId>.json` — the timestamped snapshot (immutable)
+ *   - `<outputDir>/latest.json`  — a pointer that the dashboard reads
+ *
+ * Both files contain the same `PersistedShadowReport` payload:
+ *
+ *   {
+ *     schemaVersion: 1,
+ *     runId: "<iso-8601>-<rand>",
+ *     generatedAt: "<iso-8601>",
+ *     primaryByLanguage: { [lang]: "legacy" | "registry" },
+ *     report: <ShadowParityReport>
+ *   }
+ *
+ * Schema-version-gated so future format changes don't silently confuse
+ * older dashboards. The dashboard renders `report.perLanguage` rows and
+ * annotates each with `primaryByLanguage[lang]`.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { aggregateDiffs, diffResolutions, } from '../../_shared/index.js';
+/**
+ * Construct a harness. Reads `GITNEXUS_SHADOW_MODE` at construction time
+ * (not per-`record()` call) so repeated no-op records don't re-check the
+ * env var in the hot path.
+ */
+export function createShadowHarness() {
+    const enabled = parseShadowModeEnv(process.env['GITNEXUS_SHADOW_MODE']);
+    const records = [];
+    const primaryByLanguage = {};
+    const recordImpl = (input) => {
+        if (!enabled)
+            return;
+        const diff = diffResolutions(input.callsite, input.legacy, input.newResult);
+        records.push({ language: input.language, diff });
+        // Primary per-language is resolved by last-write. In practice a run
+        // is single-threaded with respect to flag readings, so this is
+        // deterministic; a language's primary cannot change mid-run.
+        primaryByLanguage[input.language] = input.primary;
+    };
+    const snapshotImpl = (now = new Date()) => {
+        return aggregateDiffs(records, now);
+    };
+    const persistImpl = async (outputDir, now = new Date()) => {
+        await fs.mkdir(outputDir, { recursive: true });
+        const report = snapshotImpl(now);
+        const runId = makeRunId(now);
+        const payload = {
+            schemaVersion: 1,
+            runId,
+            generatedAt: now.toISOString(),
+            primaryByLanguage,
+            report,
+        };
+        const json = JSON.stringify(payload, null, 2);
+        const perRunPath = path.join(outputDir, `${runId}.json`);
+        const latestPath = path.join(outputDir, 'latest.json');
+        await fs.writeFile(perRunPath, json, 'utf8');
+        await fs.writeFile(latestPath, json, 'utf8');
+        return perRunPath;
+    };
+    const clearImpl = () => {
+        records.length = 0;
+        for (const key of Object.keys(primaryByLanguage)) {
+            delete primaryByLanguage[key];
+        }
+    };
+    return {
+        enabled,
+        record: recordImpl,
+        size: () => records.length,
+        snapshot: snapshotImpl,
+        persist: persistImpl,
+        clear: clearImpl,
+    };
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────
+/**
+ * Env-var parser for `GITNEXUS_SHADOW_MODE`. Accepts the same truthy
+ * conventions as `REGISTRY_PRIMARY_<LANG>` from #924: `'true'` / `'1'` /
+ * `'yes'`, case-insensitive, whitespace-trimmed. Anything else — including
+ * `undefined`, `''`, `'false'`, `'off'`, typos — is false.
+ */
+function parseShadowModeEnv(raw) {
+    if (raw === undefined)
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === 'true' || normalized === '1' || normalized === 'yes';
+}
+/**
+ * Deterministic run id derived from the timestamp plus 4 random bytes
+ * of entropy. The timestamp comes first so files sort chronologically;
+ * the entropy suffix prevents collisions when multiple runs share a
+ * clock-second. Shape: `YYYYMMDD-HHMMSS-xxxxxxxx`.
+ */
+function makeRunId(now) {
+    const y = now.getUTCFullYear().toString().padStart(4, '0');
+    const m = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+    const d = now.getUTCDate().toString().padStart(2, '0');
+    const h = now.getUTCHours().toString().padStart(2, '0');
+    const min = now.getUTCMinutes().toString().padStart(2, '0');
+    const s = now.getUTCSeconds().toString().padStart(2, '0');
+    const entropy = Math.floor(Math.random() * 0xffffffff)
+        .toString(16)
+        .padStart(8, '0');
+    return `${y}${m}${d}-${h}${min}${s}-${entropy}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.13",
+  "version": "1.6.3-rc.15",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",