gitnexus 1.6.3-rc.12 → 1.6.3-rc.14

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/language-provider.d.ts

@@ -242,9 +242,15 @@ interface LanguageProviderConfig {
      * 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) => Promise<readonly CaptureMatch[]>;
+    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

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/scope-extractor-bridge.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bridge between a language provider's `emitScopeCaptures` hook and the
+ * `ScopeExtractor` (RFC #909 Ring 2 PKG #920).
+ *
+ * Extracted into its own module so it can be imported by test code
+ * without pulling in `parse-worker.ts` — which has a top-level
+ * `parentPort!.on('message', ...)` call that assumes a worker-thread
+ * context and throws on direct import.
+ *
+ * The bridge:
+ *
+ *   1. Short-circuits when the provider has NOT implemented
+ *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
+ *      the state of every language today — `ParsedFile` production stays
+ *      dormant until a language migrates.
+ *   2. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   3. **Swallows exceptions from either side.** A failure here returns
+ *      `undefined` and emits a warning via `onWarn`; legacy parsing on
+ *      the same file continues unaffected by the scope-extraction miss.
+ *      Scope-based resolution is the new path under construction — it
+ *      must not destabilize the legacy DAG.
+ */
+import type { ParsedFile } from '../../_shared/index.js';
+import type { LanguageProvider } from './language-provider.js';
+/** Callback used to report scope-extraction warnings to the host (worker or direct). */
+export type ScopeBridgeWarn = (message: string) => void;
+/**
+ * Produce a `ParsedFile` for the given file, or `undefined` when the
+ * provider hasn't migrated / the extractor throws. Never propagates
+ * exceptions.
+ */
+export declare function extractParsedFile(provider: LanguageProvider, sourceText: string, filePath: string, onWarn?: ScopeBridgeWarn): ParsedFile | undefined;

package/dist/core/ingestion/scope-extractor-bridge.js

@@ -0,0 +1,44 @@
+/**
+ * Bridge between a language provider's `emitScopeCaptures` hook and the
+ * `ScopeExtractor` (RFC #909 Ring 2 PKG #920).
+ *
+ * Extracted into its own module so it can be imported by test code
+ * without pulling in `parse-worker.ts` — which has a top-level
+ * `parentPort!.on('message', ...)` call that assumes a worker-thread
+ * context and throws on direct import.
+ *
+ * The bridge:
+ *
+ *   1. Short-circuits when the provider has NOT implemented
+ *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
+ *      the state of every language today — `ParsedFile` production stays
+ *      dormant until a language migrates.
+ *   2. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   3. **Swallows exceptions from either side.** A failure here returns
+ *      `undefined` and emits a warning via `onWarn`; legacy parsing on
+ *      the same file continues unaffected by the scope-extraction miss.
+ *      Scope-based resolution is the new path under construction — it
+ *      must not destabilize the legacy DAG.
+ */
+import { extract as extractScope } from './scope-extractor.js';
+/**
+ * Produce a `ParsedFile` for the given file, or `undefined` when the
+ * provider hasn't migrated / the extractor throws. Never propagates
+ * exceptions.
+ */
+export function extractParsedFile(provider, sourceText, filePath, onWarn) {
+    if (provider.emitScopeCaptures === undefined)
+        return undefined;
+    try {
+        const captures = provider.emitScopeCaptures(sourceText, filePath);
+        return extractScope(captures, filePath, provider);
+    }
+    catch (err) {
+        const message = `scope extraction failed for ${filePath}: ${err instanceof Error ? err.message : String(err)}`;
+        if (onWarn !== undefined)
+            onWarn(message);
+        else
+            console.warn(message);
+        return undefined;
+    }
+}

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -4,6 +4,7 @@ import { type MixedChainStep } from '../utils/call-analysis.js';
 import type { ConstructorBinding } from '../type-env.js';
 import type { NamedBinding } from '../named-bindings/types.js';
 import type { NodeLabel } from '../../../_shared/index.js';
+import type { ParsedFile } from '../../../_shared/index.js';
 interface ParsedNode {
     id: string;
     label: string;
@@ -174,6 +175,14 @@ export interface ParseWorkerResult {
     constructorBindings: FileConstructorBindings[];
     /** All-scope type bindings from TypeEnv for BindingAccumulator (includes function-local). */
     fileScopeBindings: FileScopeBindings[];
+    /**
+     * Per-file `ParsedFile` artifacts from the new scope-based resolution
+     * pipeline (RFC #909 Ring 2). Empty unless the file's provider implements
+     * `emitScopeCaptures` — default for every language today, so this is
+     * additive and leaves the legacy DAG untouched. Consumed by #921's
+     * finalize-orchestrator.
+     */
+    parsedFiles: ParsedFile[];
     skippedLanguages: Record<string, number>;
     fileCount: number;
 }

package/dist/core/ingestion/workers/parse-worker.js

@@ -43,6 +43,7 @@ import { generateId } from '../../../lib/utils.js';
 import { preprocessImportPath } from '../import-processor.js';
 import { extractVueScript, extractTemplateComponents, isVueSetupTopLevel, } from '../vue-sfc-extractor.js';
 import { buildMethodProps, arityForIdFromInfo, typeTagForId, constTagForId, buildCollisionGroups, } from '../utils/method-props.js';
+import { extractParsedFile } from '../scope-extractor-bridge.js';
 // ============================================================================
 // Worker-local parser + language map
 // ============================================================================
@@ -415,6 +416,7 @@ const processBatch = (files, onProgress) => {
         ormQueries: [],
         constructorBindings: [],
         fileScopeBindings: [],
+        parsedFiles: [],
         skippedLanguages: {},
         fileCount: 0,
     };
@@ -1017,11 +1019,25 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             console.warn(`Query execution failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
             continue;
         }
+        const provider = getProvider(language);
+        // RFC #909 Ring 2: produce a `ParsedFile` for the new scope-based
+        // resolution pipeline. No-op (returns undefined) for every language
+        // today — only fires once a provider implements `emitScopeCaptures`.
+        // Runs BEFORE legacy extraction and its result is independent: a
+        // failure here is caught inside `extractParsedFile` and does NOT
+        // affect the legacy DAG path that follows.
+        const parsedFile = extractParsedFile(provider, parseContent, file.path, (message) => {
+            if (parentPort)
+                parentPort.postMessage({ type: 'warning', message });
+            else
+                console.warn(message);
+        });
+        if (parsedFile !== undefined)
+            result.parsedFiles.push(parsedFile);
         // Pre-pass: extract heritage from query matches to build parentMap for buildTypeEnv.
         // Heritage edges (EXTENDS/IMPLEMENTS) are created by heritage-processor which runs
         // in PARALLEL with call-processor, so the graph edges don't exist when buildTypeEnv
         // runs. This pre-pass makes parent class information available for type resolution.
-        const provider = getProvider(language);
         const fileParentMap = new Map();
         if (provider.heritageExtractor) {
             for (const match of matches) {
@@ -1804,6 +1820,7 @@ let accumulated = {
     ormQueries: [],
     constructorBindings: [],
     fileScopeBindings: [],
+    parsedFiles: [],
     skippedLanguages: {},
     fileCount: 0,
 };
@@ -1830,6 +1847,7 @@ const mergeResult = (target, src) => {
     appendAll(target.ormQueries, src.ormQueries);
     appendAll(target.constructorBindings, src.constructorBindings);
     appendAll(target.fileScopeBindings, src.fileScopeBindings);
+    appendAll(target.parsedFiles, src.parsedFiles);
     for (const [lang, count] of Object.entries(src.skippedLanguages)) {
         target.skippedLanguages[lang] = (target.skippedLanguages[lang] || 0) + count;
     }
@@ -1878,6 +1896,7 @@ parentPort.on('message', (msg) => {
                 ormQueries: [],
                 constructorBindings: [],
                 fileScopeBindings: [],
+                parsedFiles: [],
                 skippedLanguages: {},
                 fileCount: 0,
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.12",
+  "version": "1.6.3-rc.14",
   "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",