gitnexus 1.6.3-rc.8 → 1.6.3

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/dist/core/ingestion/utils/ast-helpers.d.ts

@@ -1,5 +1,5 @@
 import type Parser from 'tree-sitter';
-import type { NodeLabel } from '../../../_shared/index.js';
+import type { Capture, NodeLabel, Range } from '../../../_shared/index.js';
 import type { LanguageProvider } from '../language-provider.js';
 /** Tree-sitter AST node. Re-exported for use across ingestion modules. */
 export type SyntaxNode = Parser.SyntaxNode;
@@ -69,3 +69,21 @@ export declare function findDescendant(root: SyntaxNode, type: string): SyntaxNo
 export declare function extractStringContent(node: SyntaxNode | null | undefined): string | null;
 /** Find the first direct named child of a tree-sitter node matching the given type. */
 export declare function findChild(node: SyntaxNode, type: string): SyntaxNode | null;
+/** Convert a tree-sitter node to a `Capture` with 1-based line numbers
+ *  (matching RFC §2.1). The tag includes the leading `@`. */
+export declare function nodeToCapture(name: string, node: SyntaxNode): Capture;
+/** Build a `Capture` whose range mirrors `atNode` but whose `text` is
+ *  caller-supplied. Used to synthesize markers that don't have a
+ *  corresponding source token. */
+export declare function syntheticCapture(name: string, atNode: SyntaxNode, text: string): Capture;
+/** Walk a subtree to find a node whose range exactly matches AND whose
+ *  type matches `expectedType` (when given). When multiple nodes share
+ *  the range — e.g., `function_definition` and its inner `block` body
+ *  for a one-liner — the type filter disambiguates.
+ *
+ *  Iterative depth-first-left-to-right via an explicit stack. Children
+ *  are pushed in reverse index order so LIFO pop visits them in source
+ *  order. Prunes branches that can't contain the target range by
+ *  row bounds — same optimization the prior recursive form used, minus
+ *  the early-break since stack-push is cheap. */
+export declare function findNodeAtRange(root: SyntaxNode, range: Range, expectedType?: string): SyntaxNode | null;

package/dist/core/ingestion/utils/ast-helpers.js

@@ -463,3 +463,73 @@ export function findChild(node, type) {
     }
     return null;
 }
+// ============================================================================
+// Capture + range helpers (formerly python/ast-utils.ts — language-agnostic)
+// ============================================================================
+/** Convert a tree-sitter node to a `Capture` with 1-based line numbers
+ *  (matching RFC §2.1). The tag includes the leading `@`. */
+export function nodeToCapture(name, node) {
+    return {
+        name,
+        range: {
+            startLine: node.startPosition.row + 1,
+            startCol: node.startPosition.column,
+            endLine: node.endPosition.row + 1,
+            endCol: node.endPosition.column,
+        },
+        text: node.text,
+    };
+}
+/** Build a `Capture` whose range mirrors `atNode` but whose `text` is
+ *  caller-supplied. Used to synthesize markers that don't have a
+ *  corresponding source token. */
+export function syntheticCapture(name, atNode, text) {
+    return {
+        name,
+        range: {
+            startLine: atNode.startPosition.row + 1,
+            startCol: atNode.startPosition.column,
+            endLine: atNode.endPosition.row + 1,
+            endCol: atNode.endPosition.column,
+        },
+        text,
+    };
+}
+function rangeMatches(node, range) {
+    return (node.startPosition.row + 1 === range.startLine &&
+        node.startPosition.column === range.startCol &&
+        node.endPosition.row + 1 === range.endLine &&
+        node.endPosition.column === range.endCol);
+}
+/** Walk a subtree to find a node whose range exactly matches AND whose
+ *  type matches `expectedType` (when given). When multiple nodes share
+ *  the range — e.g., `function_definition` and its inner `block` body
+ *  for a one-liner — the type filter disambiguates.
+ *
+ *  Iterative depth-first-left-to-right via an explicit stack. Children
+ *  are pushed in reverse index order so LIFO pop visits them in source
+ *  order. Prunes branches that can't contain the target range by
+ *  row bounds — same optimization the prior recursive form used, minus
+ *  the early-break since stack-push is cheap. */
+export function findNodeAtRange(root, range, expectedType) {
+    const startRow = range.startLine - 1;
+    const endRow = range.endLine - 1;
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (rangeMatches(node, range) && (expectedType === undefined || node.type === expectedType)) {
+            return node;
+        }
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+            const child = node.namedChild(i);
+            if (child === null)
+                continue;
+            if (child.endPosition.row < startRow)
+                continue;
+            if (child.startPosition.row > endRow)
+                continue;
+            stack.push(child);
+        }
+    }
+    return null;
+}

package/dist/core/ingestion/utils/max-file-size.d.ts

@@ -0,0 +1,20 @@
+/** Default threshold (512 KB). Files larger than this are skipped by the walker. */
+export declare const DEFAULT_MAX_FILE_SIZE_BYTES: number;
+/** Hard upper bound — tree-sitter refuses buffers above this regardless. */
+export declare const MAX_FILE_SIZE_UPPER_BOUND_BYTES: number;
+/**
+ * Resolve the effective file-size skip threshold (bytes) for the walker.
+ * Reads `GITNEXUS_MAX_FILE_SIZE` (KB). Invalid values fall back to the default
+ * and emit a one-time warning. Values above the tree-sitter ceiling are clamped.
+ */
+export declare const getMaxFileSizeBytes: () => number;
+/**
+ * Build the CLI banner message announcing an active file-size override.
+ * Returns `null` when the effective threshold equals the default — the caller
+ * should print nothing in that case. The returned message reflects the
+ * *effective* post-clamp threshold, not the raw env value, so operators reading
+ * startup output see the actual configuration the walker will use.
+ */
+export declare const getMaxFileSizeBannerMessage: () => string | null;
+/** Test-only: reset the warn-once cache so repeated test runs can re-observe warnings. */
+export declare const _resetMaxFileSizeWarnings: () => void;

package/dist/core/ingestion/utils/max-file-size.js

@@ -0,0 +1,52 @@
+import { TREE_SITTER_MAX_BUFFER } from '../constants.js';
+/** Default threshold (512 KB). Files larger than this are skipped by the walker. */
+export const DEFAULT_MAX_FILE_SIZE_BYTES = 512 * 1024;
+/** Hard upper bound — tree-sitter refuses buffers above this regardless. */
+export const MAX_FILE_SIZE_UPPER_BOUND_BYTES = TREE_SITTER_MAX_BUFFER;
+const warned = new Set();
+const warnOnce = (key, message) => {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    console.warn(message);
+};
+/**
+ * Resolve the effective file-size skip threshold (bytes) for the walker.
+ * Reads `GITNEXUS_MAX_FILE_SIZE` (KB). Invalid values fall back to the default
+ * and emit a one-time warning. Values above the tree-sitter ceiling are clamped.
+ */
+export const getMaxFileSizeBytes = () => {
+    const raw = process.env.GITNEXUS_MAX_FILE_SIZE;
+    if (!raw)
+        return DEFAULT_MAX_FILE_SIZE_BYTES;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+        warnOnce(`invalid:${raw}`, `  GITNEXUS_MAX_FILE_SIZE must be a positive integer (KB), got "${raw}" — using default ${DEFAULT_MAX_FILE_SIZE_BYTES / 1024}KB`);
+        return DEFAULT_MAX_FILE_SIZE_BYTES;
+    }
+    const bytes = parsed * 1024;
+    if (bytes > MAX_FILE_SIZE_UPPER_BOUND_BYTES) {
+        warnOnce(`clamp:${raw}`, `  GITNEXUS_MAX_FILE_SIZE=${parsed}KB exceeds tree-sitter ceiling (${MAX_FILE_SIZE_UPPER_BOUND_BYTES / 1024}KB) — clamping`);
+        return MAX_FILE_SIZE_UPPER_BOUND_BYTES;
+    }
+    return bytes;
+};
+/**
+ * Build the CLI banner message announcing an active file-size override.
+ * Returns `null` when the effective threshold equals the default — the caller
+ * should print nothing in that case. The returned message reflects the
+ * *effective* post-clamp threshold, not the raw env value, so operators reading
+ * startup output see the actual configuration the walker will use.
+ */
+export const getMaxFileSizeBannerMessage = () => {
+    const effectiveBytes = getMaxFileSizeBytes();
+    if (effectiveBytes === DEFAULT_MAX_FILE_SIZE_BYTES)
+        return null;
+    const effectiveKb = effectiveBytes / 1024;
+    const defaultKb = DEFAULT_MAX_FILE_SIZE_BYTES / 1024;
+    return `  GITNEXUS_MAX_FILE_SIZE: effective threshold ${effectiveKb}KB (default ${defaultKb}KB)`;
+};
+/** Test-only: reset the warn-once cache so repeated test runs can re-observe warnings. */
+export const _resetMaxFileSizeWarnings = () => {
+    warned.clear();
+};

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

@@ -6,7 +6,8 @@ import Python from 'tree-sitter-python';
 import Java from 'tree-sitter-java';
 import C from 'tree-sitter-c';
 import CPP from 'tree-sitter-cpp';
-import CSharp from 'tree-sitter-c-sharp';
+// Explicit subpath import — see parser-loader.ts for rationale (#1013).
+import CSharp from 'tree-sitter-c-sharp/bindings/node/index.js';
 import Go from 'tree-sitter-go';
 import Rust from 'tree-sitter-rust';
 import PHP from 'tree-sitter-php';
@@ -43,6 +44,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
 // ============================================================================
@@ -286,31 +288,47 @@ const findEnclosingFunctionId = (node, filePath, provider) => {
                 }
                 // Qualify with enclosing class to match definition-phase node IDs
                 const classInfo = cachedFindEnclosingClassInfo(current, filePath, provider.resolveEnclosingOwner);
-                const qualifiedName = classInfo ? `${classInfo.className}.${funcName}` : funcName;
+                const encLang = getLanguageFromFilename(filePath);
+                const standaloneMethodInfo = (finalLabel === 'Method' || finalLabel === 'Constructor') &&
+                    encLang === SupportedLanguages.Go &&
+                    provider.methodExtractor?.extractFromNode
+                    ? provider.methodExtractor.extractFromNode(current, {
+                        filePath,
+                        language: encLang,
+                    })
+                    : null;
+                const ownerName = classInfo?.className ?? standaloneMethodInfo?.receiverType ?? undefined;
+                const qualifiedName = ownerName ? `${ownerName}.${funcName}` : funcName;
                 // Include #<arity> suffix to match definition-phase Method/Constructor IDs.
                 // Use the same MethodExtractor (getMethodInfo) as the definition phase.
                 // When same-arity collisions exist, also append ~type1,type2.
                 let arity;
                 let encTypeTag = '';
                 if (finalLabel === 'Method' || finalLabel === 'Constructor') {
-                    const encLang = getLanguageFromFilename(filePath);
-                    const classNode = findEnclosingClassNode(current) ?? findClassNodeByQualifiedName(current);
-                    if (classNode && encLang) {
-                        const methodMap = getMethodInfo(classNode, provider, {
-                            filePath,
-                            language: encLang,
-                        });
-                        const defLine = current.startPosition.row + 1;
-                        const info = methodMap?.get(`${funcName}:${defLine}`);
-                        if (info) {
-                            arity = info.parameters.some((p) => p.isVariadic)
-                                ? undefined
-                                : info.parameters.length;
-                            if (methodMap && arity !== undefined) {
-                                const g = buildCollisionGroups(methodMap);
-                                encTypeTag =
-                                    typeTagForId(methodMap, funcName, arity, info, encLang, g) +
-                                        constTagForId(methodMap, funcName, arity, info, g);
+                    if (standaloneMethodInfo) {
+                        arity = standaloneMethodInfo.parameters.some((p) => p.isVariadic)
+                            ? undefined
+                            : standaloneMethodInfo.parameters.length;
+                    }
+                    else {
+                        const classNode = findEnclosingClassNode(current) ?? findClassNodeByQualifiedName(current);
+                        if (classNode && encLang) {
+                            const methodMap = getMethodInfo(classNode, provider, {
+                                filePath,
+                                language: encLang,
+                            });
+                            const defLine = current.startPosition.row + 1;
+                            const info = methodMap?.get(`${funcName}:${defLine}`);
+                            if (info) {
+                                arity = info.parameters.some((p) => p.isVariadic)
+                                    ? undefined
+                                    : info.parameters.length;
+                                if (methodMap && arity !== undefined) {
+                                    const g = buildCollisionGroups(methodMap);
+                                    encTypeTag =
+                                        typeTagForId(methodMap, funcName, arity, info, encLang, g) +
+                                            constTagForId(methodMap, funcName, arity, info, g);
+                                }
                             }
                         }
                     }
@@ -415,6 +433,7 @@ const processBatch = (files, onProgress) => {
         ormQueries: [],
         constructorBindings: [],
         fileScopeBindings: [],
+        parsedFiles: [],
         skippedLanguages: {},
         fileCount: 0,
     };
@@ -1017,11 +1036,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 +1837,7 @@ let accumulated = {
     ormQueries: [],
     constructorBindings: [],
     fileScopeBindings: [],
+    parsedFiles: [],
     skippedLanguages: {},
     fileCount: 0,
 };
@@ -1830,6 +1864,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 +1913,7 @@ parentPort.on('message', (msg) => {
                 ormQueries: [],
                 constructorBindings: [],
                 fileScopeBindings: [],
+                parsedFiles: [],
                 skippedLanguages: {},
                 fileCount: 0,
             };

package/dist/core/lbug/lbug-adapter.d.ts

@@ -123,9 +123,17 @@ export declare const deleteNodesForFile: (filePath: string, dbPath?: string) =>
 export declare const getEmbeddingTableName: () => string;
 /**
  * Load the FTS extension (required before using FTS functions).
- * Safe to call multiple times — tracks loaded state via module-level ftsLoaded.
+ *
+ * Safe to call multiple times — when invoked without arguments, tracks loaded
+ * state via module-level `ftsLoaded`. When invoked with an explicit
+ * connection, loads on that connection and returns whether the load
+ * succeeded — letting callers (e.g. the pool adapter) track their own state.
+ *
+ * Tries `LOAD EXTENSION fts` first so previously-cached installs skip the
+ * network entirely; falls back to `INSTALL` + `LOAD` only when the extension
+ * hasn't been cached yet.
  */
-export declare const loadFTSExtension: () => Promise<void>;
+export declare const loadFTSExtension: (targetConn?: lbug.Connection) => Promise<boolean>;
 /**
  * Load the VECTOR extension (required before using QUERY_VECTOR_INDEX).
  * Safe to call multiple times -- tracks loaded state via module-level vectorExtensionLoaded.
@@ -139,6 +147,18 @@ export declare const loadVectorExtension: () => Promise<void>;
  * @param stemmer - Stemming algorithm (default: 'porter')
  */
 export declare const createFTSIndex: (tableName: string, indexName: string, properties: string[], stemmer?: string) => Promise<void>;
+/**
+ * Lazy-create an FTS index, caching the fact in-process.
+ *
+ * Used by `queryFTS` so that `analyze` doesn't pay the ~440 ms × 5 fixed
+ * LadybugDB cost up-front (it dominates analyze on small repos). Instead,
+ * the cost is moved to the first `query`/`context` call in a session,
+ * where it's amortised across many lookups.
+ *
+ * Safe to call repeatedly — the in-process Set guarantees only the first
+ * call hits LadybugDB. `closeLbug` clears the cache so re-init starts fresh.
+ */
+export declare const ensureFTSIndex: (tableName: string, indexName: string, properties: string[], stemmer?: string) => Promise<void>;
 /**
  * Query a full-text search index
  * @param tableName - The node table name