gitnexus 1.6.3-rc.8 → 1.6.3

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

@@ -0,0 +1,86 @@
+/**
+ * `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';
+/**
+ * Languages whose RFC #909 Ring 3 scope-resolution migration is complete.
+ *
+ * This is the single source of truth for "migrated" — the list drives:
+ *
+ *   1. **Production default behavior.** `isRegistryPrimary(lang)` returns
+ *      `true` by default for languages in this set (env-var override to
+ *      any falsy value still wins — e.g. `REGISTRY_PRIMARY_PYTHON=0`).
+ *   2. **CI parity gate.** `.github/workflows/ci-scope-parity.yml` auto-
+ *      discovers this set and, for every language in it, runs the
+ *      resolver integration test at `test/integration/resolvers/<slug>.test.ts`
+ *      TWICE on every PR — once with the legacy DAG (flag forced off)
+ *      and once with the registry-primary path (flag forced on). BOTH
+ *      must pass. Adding a language is automatic — no workflow edit,
+ *      no JSON registry.
+ *   3. **Legacy-path gating.** `call-processor.ts` / `import-processor.ts`
+ *      skip per-language work when `isRegistryPrimary(lang)` is `true`,
+ *      so this set also controls what gets silenced in the legacy DAG.
+ *
+ * Add a language here ONLY after shadow parity ≥ 99% fixtures / ≥ 98%
+ * corpus per RFC §6.4. The parity CI gate will block the PR otherwise.
+ *
+ * The set is intentionally a static TypeScript literal (not a JSON import,
+ * not an env lookup) so CI can discover it via `tsx` without a build step
+ * and reviewers see the change inline with the code that consumes it.
+ */
+export declare const MIGRATED_LANGUAGES: ReadonlySet<SupportedLanguages>;
+/**
+ * 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` runs through the registry-primary call-resolution path.
+ *
+ * Resolution order: an explicit env-var value wins (so operators and CI
+ * can force either path for a given run), and the default falls back to
+ * `MIGRATED_LANGUAGES.has(lang)` — so languages whose migration is
+ * complete default to registry-primary without touching any env.
+ */
+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>;

package/dist/core/ingestion/registry-primary-flag.js

@@ -0,0 +1,111 @@
+/**
+ * `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';
+/**
+ * Languages whose RFC #909 Ring 3 scope-resolution migration is complete.
+ *
+ * This is the single source of truth for "migrated" — the list drives:
+ *
+ *   1. **Production default behavior.** `isRegistryPrimary(lang)` returns
+ *      `true` by default for languages in this set (env-var override to
+ *      any falsy value still wins — e.g. `REGISTRY_PRIMARY_PYTHON=0`).
+ *   2. **CI parity gate.** `.github/workflows/ci-scope-parity.yml` auto-
+ *      discovers this set and, for every language in it, runs the
+ *      resolver integration test at `test/integration/resolvers/<slug>.test.ts`
+ *      TWICE on every PR — once with the legacy DAG (flag forced off)
+ *      and once with the registry-primary path (flag forced on). BOTH
+ *      must pass. Adding a language is automatic — no workflow edit,
+ *      no JSON registry.
+ *   3. **Legacy-path gating.** `call-processor.ts` / `import-processor.ts`
+ *      skip per-language work when `isRegistryPrimary(lang)` is `true`,
+ *      so this set also controls what gets silenced in the legacy DAG.
+ *
+ * Add a language here ONLY after shadow parity ≥ 99% fixtures / ≥ 98%
+ * corpus per RFC §6.4. The parity CI gate will block the PR otherwise.
+ *
+ * The set is intentionally a static TypeScript literal (not a JSON import,
+ * not an env lookup) so CI can discover it via `tsx` without a build step
+ * and reviewers see the change inline with the code that consumes it.
+ */
+export const MIGRATED_LANGUAGES = new Set([
+    SupportedLanguages.Python,
+    SupportedLanguages.CSharp,
+]);
+/**
+ * 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 function envVarNameFor(lang) {
+    return `REGISTRY_PRIMARY_${lang.toUpperCase()}`;
+}
+/**
+ * Whether `lang` runs through the registry-primary call-resolution path.
+ *
+ * Resolution order: an explicit env-var value wins (so operators and CI
+ * can force either path for a given run), and the default falls back to
+ * `MIGRATED_LANGUAGES.has(lang)` — so languages whose migration is
+ * complete default to registry-primary without touching any env.
+ */
+export function isRegistryPrimary(lang) {
+    const raw = process.env[envVarNameFor(lang)];
+    if (raw !== undefined)
+        return parseFlag(raw);
+    return MIGRATED_LANGUAGES.has(lang);
+}
+/**
+ * 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 function primaryLanguages() {
+    const out = new Set();
+    for (const lang of Object.values(SupportedLanguages)) {
+        if (isRegistryPrimary(lang))
+            out.add(lang);
+    }
+    return out;
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/** Accepted truthy strings (case-insensitive, trimmed). */
+const TRUTHY_VALUES = new Set(['true', '1', 'yes']);
+function parseFlag(raw) {
+    if (raw === undefined)
+        return false;
+    return TRUTHY_VALUES.has(raw.trim().toLowerCase());
+}

package/dist/core/ingestion/resolve-references.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `resolveReferenceSites` — drain `ReferenceSite[]` from a finalized
+ * `ScopeResolutionIndexes` into a `ReferenceIndex` by routing each site
+ * through the appropriate scope-aware `Registry.lookup` (RFC §3.2 Phase 4).
+ *
+ * This is the missing producer that `emit-references.ts` (#925) was
+ * waiting on. The two together form the registry-primary resolution
+ * pipeline:
+ *
+ *     ScopeResolutionIndexes.referenceSites
+ *        │  resolveReferenceSites
+ *        ▼
+ *     ReferenceIndex
+ *        │  emitReferencesToGraph
+ *        ▼
+ *     graph: CALLS / ACCESSES / INHERITS / USES edges
+ *
+ * ## What this module does
+ *
+ *   - For each `ReferenceSite`, picks the registry by `kind`:
+ *     · `call` / `inherits`        → MethodRegistry / ClassRegistry (call-form aware)
+ *     · `read` / `write`           → FieldRegistry  (falls through to MethodRegistry for free names)
+ *     · `type-reference`           → ClassRegistry
+ *     · `import-use`               → all three (best-effort name-lookup)
+ *   - Calls `Registry.lookup` with the site's `inScope`, optional
+ *     explicit receiver, and arity.
+ *   - Takes the top-ranked `Resolution` (best by confidence + tie-break
+ *     cascade); folds it into a `Reference` record and bins by source scope.
+ *
+ * ## What this module does NOT do
+ *
+ *   - No AST walks. The `ReferenceSite[]` is already extracted.
+ *   - No language switches. Per-language behavior flows through
+ *     `RegistryProviders.arityCompatibility` (see `RegistryContext`).
+ *   - No multi-candidate fan-out. We pick `[0]` per RFC §4.3 ("one-shot
+ *     answer"). The full ranked list is preserved in the per-site
+ *     resolution but not emitted as multiple edges; callers that want
+ *     branch-on-ambiguity behavior should consume the registries directly.
+ */
+import { CLASS_KINDS, FIELD_KINDS, METHOD_KINDS, type ReferenceIndex, type RegistryProviders } from '../../_shared/index.js';
+import type { ScopeResolutionIndexes } from './model/scope-resolution-indexes.js';
+export interface ResolveReferencesInput {
+    readonly scopes: ScopeResolutionIndexes;
+    /** Provider hooks consumed by the registries (e.g. `arityCompatibility`). */
+    readonly providers?: RegistryProviders;
+}
+export interface ResolveStats {
+    readonly sitesProcessed: number;
+    readonly referencesEmitted: number;
+    /** Sites where `Registry.lookup` returned no candidates. */
+    readonly unresolved: number;
+}
+export interface ResolveReferencesOutput {
+    readonly referenceIndex: ReferenceIndex;
+    readonly stats: ResolveStats;
+}
+/**
+ * Resolve every `ReferenceSite` in `scopes.referenceSites` against the
+ * matching registry and produce a `ReferenceIndex` keyed by source scope
+ * + target def.
+ */
+export declare function resolveReferenceSites(input: ResolveReferencesInput): ResolveReferencesOutput;
+export { CLASS_KINDS, METHOD_KINDS, FIELD_KINDS };

package/dist/core/ingestion/resolve-references.js

@@ -0,0 +1,175 @@
+/**
+ * `resolveReferenceSites` — drain `ReferenceSite[]` from a finalized
+ * `ScopeResolutionIndexes` into a `ReferenceIndex` by routing each site
+ * through the appropriate scope-aware `Registry.lookup` (RFC §3.2 Phase 4).
+ *
+ * This is the missing producer that `emit-references.ts` (#925) was
+ * waiting on. The two together form the registry-primary resolution
+ * pipeline:
+ *
+ *     ScopeResolutionIndexes.referenceSites
+ *        │  resolveReferenceSites
+ *        ▼
+ *     ReferenceIndex
+ *        │  emitReferencesToGraph
+ *        ▼
+ *     graph: CALLS / ACCESSES / INHERITS / USES edges
+ *
+ * ## What this module does
+ *
+ *   - For each `ReferenceSite`, picks the registry by `kind`:
+ *     · `call` / `inherits`        → MethodRegistry / ClassRegistry (call-form aware)
+ *     · `read` / `write`           → FieldRegistry  (falls through to MethodRegistry for free names)
+ *     · `type-reference`           → ClassRegistry
+ *     · `import-use`               → all three (best-effort name-lookup)
+ *   - Calls `Registry.lookup` with the site's `inScope`, optional
+ *     explicit receiver, and arity.
+ *   - Takes the top-ranked `Resolution` (best by confidence + tie-break
+ *     cascade); folds it into a `Reference` record and bins by source scope.
+ *
+ * ## What this module does NOT do
+ *
+ *   - No AST walks. The `ReferenceSite[]` is already extracted.
+ *   - No language switches. Per-language behavior flows through
+ *     `RegistryProviders.arityCompatibility` (see `RegistryContext`).
+ *   - No multi-candidate fan-out. We pick `[0]` per RFC §4.3 ("one-shot
+ *     answer"). The full ranked list is preserved in the per-site
+ *     resolution but not emitted as multiple edges; callers that want
+ *     branch-on-ambiguity behavior should consume the registries directly.
+ */
+import { buildClassRegistry, buildFieldRegistry, buildMethodRegistry, CLASS_KINDS, FIELD_KINDS, METHOD_KINDS, } from '../../_shared/index.js';
+/**
+ * Resolve every `ReferenceSite` in `scopes.referenceSites` against the
+ * matching registry and produce a `ReferenceIndex` keyed by source scope
+ * + target def.
+ */
+export function resolveReferenceSites(input) {
+    const { scopes } = input;
+    const providers = input.providers ?? {};
+    const ctx = {
+        scopes: scopes.scopeTree,
+        defs: scopes.defs,
+        qualifiedNames: scopes.qualifiedNames,
+        moduleScopes: scopes.moduleScopes,
+        methodDispatch: scopes.methodDispatch,
+        providers,
+    };
+    const classRegistry = buildClassRegistry(ctx);
+    const methodRegistry = buildMethodRegistry(ctx);
+    const fieldRegistry = buildFieldRegistry(ctx);
+    // bySourceScope is the canonical index; byTargetDef is derived from it.
+    const bySourceScope = new Map();
+    const byTargetDef = new Map();
+    let sitesProcessed = 0;
+    let referencesEmitted = 0;
+    let unresolved = 0;
+    for (const site of scopes.referenceSites) {
+        sitesProcessed++;
+        const resolutions = lookupForSite(site, classRegistry, methodRegistry, fieldRegistry);
+        if (resolutions.length === 0) {
+            unresolved++;
+            continue;
+        }
+        const top = resolutions[0];
+        const ref = buildReference(site, top);
+        referencesEmitted++;
+        let bySource = bySourceScope.get(site.inScope);
+        if (bySource === undefined) {
+            bySource = [];
+            bySourceScope.set(site.inScope, bySource);
+        }
+        bySource.push(ref);
+        let byTarget = byTargetDef.get(top.def.nodeId);
+        if (byTarget === undefined) {
+            byTarget = [];
+            byTargetDef.set(top.def.nodeId, byTarget);
+        }
+        byTarget.push(ref);
+    }
+    // Freeze inner arrays so consumers don't accidentally mutate.
+    const frozenBySource = new Map();
+    for (const [k, v] of bySourceScope)
+        frozenBySource.set(k, Object.freeze([...v]));
+    const frozenByTarget = new Map();
+    for (const [k, v] of byTargetDef)
+        frozenByTarget.set(k, Object.freeze([...v]));
+    return {
+        referenceIndex: { bySourceScope: frozenBySource, byTargetDef: frozenByTarget },
+        stats: { sitesProcessed, referencesEmitted, unresolved },
+    };
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/**
+ * Pick the right registry for the site's `kind` and call `lookup`.
+ *
+ * The kind→registry mapping mirrors `mapKindToType` in `emit-references.ts`:
+ *
+ *   | site.kind        | primary registry  | acceptedKinds source         |
+ *   |------------------|-------------------|------------------------------|
+ *   | `call`           | MethodRegistry    | METHOD_KINDS (Method/Func/Ctor)
+ *   | `inherits`       | ClassRegistry     | CLASS_KINDS                  |
+ *   | `type-reference` | ClassRegistry     | CLASS_KINDS                  |
+ *   | `read`/`write`   | FieldRegistry     | FIELD_KINDS                  |
+ *   | `import-use`     | tiered fallback   | METHOD ∪ CLASS ∪ FIELD       |
+ *
+ * `import-use` doesn't have a single registry — the imported name might
+ * be a class, a function, or a constant. Try each in priority order and
+ * return the first non-empty result. Provenance still flows through the
+ * scope's `bindings` (Step 1 lexical hit), so the lookup is correct
+ * regardless of which registry surfaces the def.
+ */
+function lookupForSite(site, classRegistry, methodRegistry, fieldRegistry) {
+    switch (site.kind) {
+        case 'call': {
+            const opts = {
+                ...(site.arity !== undefined ? { callsite: { arity: site.arity } } : {}),
+                ...(site.explicitReceiver !== undefined ? { explicitReceiver: site.explicitReceiver } : {}),
+            };
+            return methodRegistry.lookup(site.name, site.inScope, opts);
+        }
+        case 'inherits':
+        case 'type-reference': {
+            return classRegistry.lookup(site.name, site.inScope);
+        }
+        case 'read':
+        case 'write': {
+            // Try field first; fall through to method then class so bare-name
+            // reads of a function (e.g. `cb = save`) still resolve.
+            const fieldHits = fieldRegistry.lookup(site.name, site.inScope);
+            if (fieldHits.length > 0)
+                return fieldHits;
+            const methodHits = methodRegistry.lookup(site.name, site.inScope);
+            if (methodHits.length > 0)
+                return methodHits;
+            return classRegistry.lookup(site.name, site.inScope);
+        }
+        case 'import-use': {
+            // Try class, method, then field. The lexical-hit Step 1 in
+            // `lookupCore` handles the actual binding lookup; the choice of
+            // registry only narrows `acceptedKinds`.
+            const classHits = classRegistry.lookup(site.name, site.inScope);
+            if (classHits.length > 0)
+                return classHits;
+            const methodHits = methodRegistry.lookup(site.name, site.inScope);
+            if (methodHits.length > 0)
+                return methodHits;
+            return fieldRegistry.lookup(site.name, site.inScope);
+        }
+    }
+}
+/** Compose a `Reference` record from a site + its top resolution. */
+function buildReference(site, top) {
+    return {
+        fromScope: site.inScope,
+        toDef: top.def.nodeId,
+        atRange: site.atRange,
+        kind: site.kind,
+        confidence: top.confidence,
+        evidence: top.evidence,
+    };
+}
+// Re-export the kind sets so consumers don't have to import them
+// separately when constructing custom resolution flows. The mappings
+// stay in `gitnexus-shared` (single source of truth); this is a
+// convenience pass-through only.
+export { CLASS_KINDS, METHOD_KINDS, FIELD_KINDS };

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, cachedTree?: unknown): 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, cachedTree) {
+    if (provider.emitScopeCaptures === undefined)
+        return undefined;
+    try {
+        const captures = provider.emitScopeCaptures(sourceText, filePath, cachedTree);
+        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/scope-extractor.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `ScopeExtractor` — the central, source-agnostic driver that turns a
+ * language provider's `CaptureMatch[]` into a `ParsedFile`
+ * (RFC §5.3 + §3.2 Phase 1; Ring 2 PKG #919).
+ *
+ * Exactly one entry point: `extract(matches, filePath, provider) → ParsedFile`.
+ * Runs a five-pass pipeline over the matches. Each pass is internal; the
+ * public contract is the output `ParsedFile`.
+ *
+ * ## Design principles
+ *
+ *   - **Source-agnostic.** Consumes `CaptureMatch[]` from providers;
+ *     doesn't know whether they came from tree-sitter queries or COBOL's
+ *     regex tagger. No `Tree` / `SyntaxNode` types leak into this file.
+ *   - **One AST walk per language.** Providers do the AST walk inside
+ *     their `emitScopeCaptures` hook; this driver does zero further
+ *     traversal — it consumes captures only.
+ *   - **Pure-ish.** The extractor itself is pure (same matches →
+ *     same ParsedFile) when providers are pure. No side effects, no I/O.
+ *   - **Centralized invariant enforcement.** Structural invariants on the
+ *     scope tree (non-module has parent; parent contains child; siblings
+ *     don't overlap) are enforced by `buildScopeTree` from Ring 2 SHARED
+ *     (#912). Malformed inputs throw `ScopeTreeInvariantError`.
+ *
+ * ## The five passes
+ *
+ *   1. **Build scope tree.** Walk `@scope.*` matches. For each, consult
+ *      `provider.resolveScopeKind` (default: suffix of the capture name).
+ *      Derive parent by lexical-range containment. Hand the resulting
+ *      `Scope[]` to `buildScopeTree` for validation.
+ *   2. **Attach declarations + local bindings.** Walk `@declaration.*`
+ *      matches. For each, build a `SymbolDefinition` and attach it to
+ *      `provider.bindingScopeFor` (default: innermost containing scope)
+ *      as `ownedDefs` + a local `BindingRef { origin: 'local' }`.
+ *   3. **Collect raw imports.** Walk `@import.*` matches. Call
+ *      `provider.interpretImport` per match; attach the returned
+ *      `ParsedImport` to the ParsedFile (not to any `Scope` — finalize
+ *      reconstructs the owning scope via `provider.importOwningScope`
+ *      during Phase 2).
+ *   4. **Collect type bindings.** Walk `@type-binding.*` matches. Call
+ *      `provider.interpretTypeBinding` per match. Attach the resulting
+ *      `TypeRef` to the innermost containing scope's `typeBindings`
+ *      (or override via `provider.bindingScopeFor` if set).
+ *   5. **Collect reference sites.** Walk `@reference.*` matches. Emit
+ *      one `ReferenceSite` per match. Classify call form via
+ *      `provider.classifyCallForm` (default: the capture's sub-tag if
+ *      present; else `'free'`).
+ *
+ * ## What gets attached where
+ *
+ *   - `Scope.bindings`     — **local bindings only** at this stage (Pass 2).
+ *                            Finalize (#915) merges imports/wildcards on top.
+ *   - `Scope.ownedDefs`    — declarations structurally owned by this scope.
+ *   - `Scope.typeBindings` — local type facts (parameter annotations, `self`).
+ *   - `Scope.imports`      — empty here. Populated by the finalize algorithm
+ *                            when it resolves `ParsedImport.targetRaw`.
+ *   - `ParsedFile.parsedImports` — every raw import in this file.
+ *   - `ParsedFile.localDefs`     — flattened union of `Scope.ownedDefs`.
+ *   - `ParsedFile.referenceSites` — pre-resolution usage facts.
+ */
+import type { CaptureMatch, ParsedFile } from '../../_shared/index.js';
+import type { LanguageProvider } from './language-provider.js';
+/**
+ * The subset of `LanguageProvider` hooks that `extract()` reads. Declared
+ * as its own type so:
+ *
+ *   - Tests can implement just these six hooks without faking the whole
+ *     `LanguageProvider` interface (which is ~40 fields including the
+ *     legacy-DAG surface).
+ *   - The extractor's dependency contract stays explicit — adding a new
+ *     hook read requires updating this type.
+ *
+ * Real callers pass a full `LanguageProvider` — structural typing makes it
+ * a `ScopeExtractorHooks` for free.
+ */
+export type ScopeExtractorHooks = Pick<LanguageProvider, 'resolveScopeKind' | 'bindingScopeFor' | 'interpretImport' | 'interpretTypeBinding' | 'classifyCallForm'>;
+/**
+ * Drive the five extraction passes and return a `ParsedFile`.
+ *
+ * Throws `ScopeTreeInvariantError` (from #912) when the provider emits
+ * captures that violate structural scope invariants. The error surfaces
+ * upward rather than being silently corrected — a malformed capture set
+ * is a bug in the provider's `emitScopeCaptures`, not a data condition
+ * to tolerate.
+ */
+export declare function extract(matches: readonly CaptureMatch[], filePath: string, provider: ScopeExtractorHooks): ParsedFile;