gitnexus 1.6.6-rc.99 → 1.6.6

package/dist/core/ingestion/pipeline-phases/wildcard-synthesis.js

@@ -1,312 +0,0 @@
-/**
- * Wildcard import binding synthesis.
- *
- * Languages with whole-module import semantics (Go, Ruby, C/C++, Swift)
- * import all exported symbols from a file, not specific named symbols.
- * After parsing, we know which symbols each file exports (via graph
- * `isExported`), so we can expand IMPORTS edges into per-symbol bindings
- * that the cross-file propagation phase can use for type resolution.
- *
- * Also builds Python module-alias maps for namespace-import languages
- * (`import models` → `models.User()` resolves to `models.py:User`).
- *
- * @module
- */
-import { getLanguageFromFilename } from '../../../_shared/index.js';
-import { providers, getProviderForFile } from '../languages/index.js';
-// ── Constants ──────────────────────────────────────────────────────────────
-/** Node labels that represent top-level importable symbols. */
-const IMPORTABLE_SYMBOL_LABELS = new Set([
-    'Function',
-    'Class',
-    'Interface',
-    'Struct',
-    'Enum',
-    'Trait',
-    'TypeAlias',
-    'Const',
-    'Static',
-    'Record',
-    'Union',
-    'Typedef',
-    'Macro',
-]);
-/** Max synthetic bindings per importing file — prevents memory bloat
- *  for C/C++ files that include many large headers. */
-const MAX_SYNTHETIC_BINDINGS_PER_FILE = 1000;
-/** Max files allowed in a single transitive include closure. Guards against
- *  OOM on pathological C/C++ codebases (boost, Linux kernel-style monoheaders)
- *  where a single translation unit can transitively reach many thousands of
- *  headers. When the cap is hit, BFS expansion stops early — the file still
- *  synthesizes bindings from the partial closure rather than failing. */
-const MAX_TRANSITIVE_CLOSURE_SIZE = 5000;
-/** Import semantics tags whose languages need synthesis of whole-module imports.
- *  `wildcard-transitive` (C/C++) and `wildcard-leaf` (Go, Ruby, Swift, Dart) are
- *  the file-based wildcard strategies. `explicit-reexport` is a scaffold tag —
- *  no provider uses it yet, but it goes through the same leaf-style synthesis
- *  path today because a re-exporter is still an importer; only the extra DAG
- *  walk to surface re-exported symbols is missing (future work). */
-const WILDCARD_SEMANTICS = new Set([
-    'wildcard-transitive',
-    'wildcard-leaf',
-    'explicit-reexport',
-]);
-/** Languages with whole-module import semantics (derived from providers at module load). */
-const WILDCARD_LANGUAGES = new Set(Object.values(providers)
-    .filter((p) => WILDCARD_SEMANTICS.has(p.importSemantics))
-    .map((p) => p.id));
-/** Languages that need binding synthesis before call resolution. */
-const SYNTHESIS_LANGUAGES = new Set(Object.values(providers)
-    .filter((p) => p.importSemantics !== 'named')
-    .map((p) => p.id));
-/** Check if a language uses wildcard (whole-module) import semantics. */
-export function isWildcardImportLanguage(lang) {
-    return WILDCARD_LANGUAGES.has(lang);
-}
-/** Check if a language needs synthesis before call resolution.
- *  True for wildcard-import languages AND namespace-import languages (Python). */
-export function needsSynthesis(lang) {
-    return SYNTHESIS_LANGUAGES.has(lang);
-}
-// ── Strategy implementations ───────────────────────────────────────────────
-/**
- * Strategy implementation for `importSemantics: 'wildcard-transitive'` (C, C++).
- *
- * Textual-include languages chain symbols through files: if `dict.c` includes
- * `server.h` and `server.h` includes `dict.h`, then `dict.c` sees symbols from
- * all three files. This helper walks the include graph (combining both the
- * ingestion-context `importMap` and the graph-level IMPORTS edges) until the
- * closure is stable.
- *
- * **Order matters.** The returned `Set` preserves iteration order (insertion
- * order). `synthesizeWildcardImportBindings` dedupes bindings by symbol name
- * on a first-seen-wins basis, so this closure's ordering determines which
- * declaration wins when multiple headers export the same name (e.g. overloaded
- * free functions like `write_audit()` vs `write_audit(const char*)` in
- * different headers). We therefore:
- *   1. Seed the closure with direct imports in declaration order (matches the
- *      order of `#include` directives in the source file).
- *   2. Use FIFO / true BFS (`queue.shift()`) for transitive expansion, so
- *      closer headers are seen before deeper ones.
- *
- * Cycle-safe: the `closure.has(file)` guard prevents infinite loops on circular
- * header includes, which are valid C/C++ when paired with `#pragma once` or
- * include guards.
- *
- * Size-bounded: the closure is capped at `MAX_TRANSITIVE_CLOSURE_SIZE` files to
- * prevent OOM on pathological codebases (e.g. boost, monoheader kernel code)
- * where one translation unit can transitively reach tens of thousands of
- * headers. Partial closures still yield useful bindings for the cluster of
- * headers closest to the importer, which is what overload resolution and
- * cross-file call resolution care about.
- *
- * Queue implementation: uses a head-index over a growing array (O(1) dequeue)
- * instead of `Array.prototype.shift()` (O(n)) so deep chains stay linear.
- */
-export function expandTransitiveIncludeClosure(directImports, importMap, graphImports) {
-    const closure = new Set();
-    const queue = [];
-    let head = 0; // O(1) dequeue: advance the head index instead of shift()-ing.
-    const tryEnqueue = (file) => {
-        if (closure.has(file))
-            return true;
-        if (closure.size >= MAX_TRANSITIVE_CLOSURE_SIZE)
-            return false;
-        closure.add(file);
-        queue.push(file);
-        return true;
-    };
-    // Seed direct imports in declaration order (see JSDoc on order-sensitivity).
-    for (const f of directImports) {
-        if (!tryEnqueue(f))
-            break;
-    }
-    // True BFS for transitive reach: head-index FIFO preserves the "closer
-    // headers first" ordering that overload resolution depends on.
-    while (head < queue.length) {
-        if (closure.size >= MAX_TRANSITIVE_CLOSURE_SIZE)
-            break;
-        const file = queue[head++];
-        const nested = importMap.get(file);
-        if (nested) {
-            for (const n of nested) {
-                if (!tryEnqueue(n))
-                    break;
-            }
-        }
-        const nestedGraph = graphImports.get(file);
-        if (nestedGraph) {
-            for (const n of nestedGraph) {
-                if (!tryEnqueue(n))
-                    break;
-            }
-        }
-    }
-    return closure;
-}
-// ── Main synthesis function ────────────────────────────────────────────────
-/**
- * Synthesize namedImportMap entries for languages with whole-module imports.
- *
- * For each file that imports another file via wildcard semantics:
- * 1. Look up all exported symbols from the imported file (via graph nodes)
- * 2. Create synthetic named bindings: `{ name → { sourcePath, exportedName } }`
- * 3. Build Python module-alias maps for namespace-import languages
- *
- * @param graph  The knowledge graph with parsed symbol nodes
- * @param ctx    Resolution context with importMap and namedImportMap
- * @returns      Number of synthetic bindings created
- */
-export function synthesizeWildcardImportBindings(graph, ctx) {
-    // Build exported symbols index from graph nodes (single pass)
-    const exportedSymbolsByFile = new Map();
-    graph.forEachNode((node) => {
-        if (!node.properties?.isExported)
-            return;
-        if (!IMPORTABLE_SYMBOL_LABELS.has(node.label))
-            return;
-        const fp = node.properties.filePath;
-        const name = node.properties.name;
-        if (!fp || !name)
-            return;
-        let symbols = exportedSymbolsByFile.get(fp);
-        if (!symbols) {
-            symbols = [];
-            exportedSymbolsByFile.set(fp, symbols);
-        }
-        symbols.push({ name, filePath: fp });
-    });
-    if (exportedSymbolsByFile.size === 0)
-        return 0;
-    // Collect graph-level IMPORTS edges for wildcard languages missing from ctx.importMap
-    const FILE_PREFIX = 'File:';
-    const graphImports = new Map();
-    graph.forEachRelationship((rel) => {
-        if (rel.type !== 'IMPORTS')
-            return;
-        if (!rel.sourceId.startsWith(FILE_PREFIX) || !rel.targetId.startsWith(FILE_PREFIX))
-            return;
-        const srcFile = rel.sourceId.slice(FILE_PREFIX.length);
-        const tgtFile = rel.targetId.slice(FILE_PREFIX.length);
-        const lang = getLanguageFromFilename(srcFile);
-        if (!lang || !isWildcardImportLanguage(lang))
-            return;
-        if (ctx.importMap.get(srcFile)?.has(tgtFile))
-            return;
-        let set = graphImports.get(srcFile);
-        if (!set) {
-            set = new Set();
-            graphImports.set(srcFile, set);
-        }
-        set.add(tgtFile);
-    });
-    let totalSynthesized = 0;
-    const synthesizeForFile = (filePath, importedFiles) => {
-        let fileBindings = ctx.namedImportMap.get(filePath);
-        let fileCount = fileBindings?.size ?? 0;
-        for (const importedFile of importedFiles) {
-            const exportedSymbols = exportedSymbolsByFile.get(importedFile);
-            if (!exportedSymbols)
-                continue;
-            for (const sym of exportedSymbols) {
-                if (fileCount >= MAX_SYNTHETIC_BINDINGS_PER_FILE)
-                    return;
-                if (fileBindings?.has(sym.name))
-                    continue;
-                if (!fileBindings) {
-                    fileBindings = new Map();
-                    ctx.namedImportMap.set(filePath, fileBindings);
-                }
-                fileBindings.set(sym.name, {
-                    sourcePath: importedFile,
-                    exportedName: sym.name,
-                });
-                fileCount++;
-                totalSynthesized++;
-            }
-        }
-    };
-    /**
-     * Dispatch wildcard synthesis by the file's language provider strategy.
-     *
-     * Strategy tags (see `ImportSemantics`):
-     *   - `wildcard-transitive`: expand the include closure first (C/C++ #include
-     *     chains — e.g. `dict.c` → `server.h` → `dict.h` so `dictFind` resolves
-     *     across header chains)
-     *   - `wildcard-leaf`: synthesize from direct imports only (Go, Ruby, Swift, Dart)
-     *   - `explicit-reexport`: scaffold tag; falls through to leaf behavior.
-     *     TODO(#821): implement re-export DAG walk for TS `export *` / Rust
-     *     `pub use`. The leaf fallthrough preserves today's TS/Rust behavior
-     *     (their direct imports still synthesize correctly); only the extra
-     *     re-export DAG walk for barrel-file correctness is missing.
-     *   - `namespace` / `named`: no-op here (namespace handled in Loop 3 below,
-     *     named needs no synthesis).
-     *
-     * Used by both Loop 1 (ctx.importMap) and Loop 2 (graphImports) so a future
-     * transitive-import language whose edges arrive via graphImports gets closure
-     * expansion consistently regardless of edge source.
-     */
-    const dispatchSynthesis = (filePath, importedFiles, provider) => {
-        switch (provider.importSemantics) {
-            case 'wildcard-transitive':
-                synthesizeForFile(filePath, expandTransitiveIncludeClosure(importedFiles, ctx.importMap, graphImports));
-                return;
-            case 'wildcard-leaf':
-            case 'explicit-reexport':
-                synthesizeForFile(filePath, importedFiles);
-                return;
-            case 'namespace':
-            case 'named':
-                return;
-            default: {
-                const _exhaustive = provider.importSemantics;
-                void _exhaustive;
-            }
-        }
-    };
-    // Loop 1: synthesize from ctx.importMap (Ruby, C/C++, Swift, Dart file-based imports).
-    for (const [filePath, importedFiles] of ctx.importMap) {
-        const lang = getLanguageFromFilename(filePath);
-        if (!lang || !isWildcardImportLanguage(lang))
-            continue;
-        const provider = getProviderForFile(filePath);
-        if (!provider)
-            continue;
-        dispatchSynthesis(filePath, importedFiles, provider);
-    }
-    // Loop 2: synthesize from graph IMPORTS edges (Go and other wildcard-import
-    // languages whose edges live in the graph rather than ctx.importMap).
-    for (const [filePath, importedFiles] of graphImports) {
-        const provider = getProviderForFile(filePath);
-        if (!provider)
-            continue;
-        dispatchSynthesis(filePath, importedFiles, provider);
-    }
-    // Build Python module-alias maps for namespace-import languages.
-    // `import models` in app.py → moduleAliasMap['app.py']['models'] = 'models.py'
-    // Enables `models.User()` to resolve without ambiguous symbol expansion.
-    for (const [filePath, importedFiles] of ctx.importMap) {
-        const provider = getProviderForFile(filePath);
-        if (!provider || provider.importSemantics !== 'namespace')
-            continue;
-        buildPythonModuleAliasForFile(ctx, filePath, importedFiles);
-    }
-    return totalSynthesized;
-}
-/** Build module alias entries for namespace-import files (e.g. Python). */
-function buildPythonModuleAliasForFile(ctx, callerFile, importedFiles) {
-    let aliasMap = ctx.moduleAliasMap.get(callerFile);
-    for (const importedFile of importedFiles) {
-        const lastSlash = importedFile.lastIndexOf('/');
-        const base = lastSlash >= 0 ? importedFile.slice(lastSlash + 1) : importedFile;
-        const dot = base.lastIndexOf('.');
-        const stem = dot >= 0 ? base.slice(0, dot) : base;
-        if (!stem)
-            continue;
-        if (!aliasMap) {
-            aliasMap = new Map();
-            ctx.moduleAliasMap.set(callerFile, aliasMap);
-        }
-        aliasMap.set(stem, importedFile);
-    }
-}

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

@@ -1,89 +0,0 @@
-/**
- * `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`.
- *   `SupportedLanguages.Cobol` (value `'cobol'`) → `REGISTRY_PRIMARY_COBOL`.
- *   - 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. TypeScript is temporarily accepted under the
- * Ring 3 CI parity gate while corpus-level shadow-mode wiring is tracked
- * in #927 for this migration.
- *
- * 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

@@ -1,122 +0,0 @@
-/**
- * `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`.
- *   `SupportedLanguages.Cobol` (value `'cobol'`) → `REGISTRY_PRIMARY_COBOL`.
- *   - 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';
-import { parseTruthyEnv } from './utils/env.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. TypeScript is temporarily accepted under the
- * Ring 3 CI parity gate while corpus-level shadow-mode wiring is tracked
- * in #927 for this migration.
- *
- * 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,
-    SupportedLanguages.TypeScript,
-    SupportedLanguages.Go,
-    SupportedLanguages.C,
-    SupportedLanguages.CPlusPlus,
-    SupportedLanguages.PHP,
-    SupportedLanguages.JavaScript,
-    SupportedLanguages.Kotlin,
-    SupportedLanguages.Java,
-    SupportedLanguages.Rust,
-    SupportedLanguages.Ruby,
-    SupportedLanguages.Cobol,
-]);
-/**
- * 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 ───────────────────────────────────────────────────────────────
-function parseFlag(raw) {
-    return parseTruthyEnv(raw);
-}

package/dist/core/ingestion/shadow-harness.d.ts

@@ -1,113 +0,0 @@
-/**
- * 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;