gitnexus 1.6.3-rc.8 → 1.6.3

package/dist/core/group/resolve-at-member.js

@@ -0,0 +1,31 @@
+/**
+ * Map MCP/CLI `@groupName` or `@groupName/memberPath` to a concrete member path in group.yaml.
+ */
+import { loadGroupConfig } from './config-parser.js';
+import { getDefaultGitnexusDir, getGroupDir } from './storage.js';
+export async function resolveAtGroupMemberRepoPath(groupName, explicitMemberPath) {
+    const trimmed = groupName.trim();
+    if (!trimmed)
+        return { ok: false, error: 'Group name is empty.' };
+    try {
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), trimmed);
+        const config = await loadGroupConfig(groupDir);
+        const keys = Object.keys(config.repos).sort((a, b) => a.localeCompare(b));
+        if (keys.length === 0) {
+            return { ok: false, error: `Group "${trimmed}" has no repos in group.yaml.` };
+        }
+        if (explicitMemberPath !== undefined && explicitMemberPath !== '') {
+            if (!(explicitMemberPath in config.repos)) {
+                return {
+                    ok: false,
+                    error: `Unknown member path "${explicitMemberPath}" in group "${trimmed}". Known paths: ${keys.join(', ')}`,
+                };
+            }
+            return { ok: true, repoPath: explicitMemberPath };
+        }
+        return { ok: true, repoPath: keys[0] };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/core/group/service.d.ts

@@ -2,6 +2,7 @@
  * Group orchestration shared by MCP (LocalBackend) and CLI.
  * DB access is injected via GroupToolPort so this module stays free of LocalBackend private API.
  */
+import type { GroupContextResult } from './types.js';
 export interface GroupRepoHandle {
     id: string;
     name: string;
@@ -34,6 +35,12 @@ export interface GroupToolPort {
         minConfidence: number;
         includeTests: boolean;
     }): Promise<unknown | null>;
+    context(repo: GroupRepoHandle, params: {
+        name?: string;
+        uid?: string;
+        file_path?: string;
+        include_content?: boolean;
+    }): Promise<unknown>;
 }
 export declare class GroupService {
     private readonly port;
@@ -41,6 +48,8 @@ export declare class GroupService {
     groupList(params: Record<string, unknown>): Promise<unknown>;
     groupSync(params: Record<string, unknown>): Promise<unknown>;
     groupContracts(params: Record<string, unknown>): Promise<unknown>;
+    groupImpact(params: Record<string, unknown>): Promise<unknown>;
+    groupContext(params: Record<string, unknown>): Promise<GroupContextResult>;
     groupQuery(params: Record<string, unknown>): Promise<unknown>;
     groupStatus(params: Record<string, unknown>): Promise<unknown>;
 }

package/dist/core/group/service.js

@@ -2,15 +2,125 @@
  * Group orchestration shared by MCP (LocalBackend) and CLI.
  * DB access is injected via GroupToolPort so this module stays free of LocalBackend private API.
  */
+import fsp from 'node:fs/promises';
+import path from 'node:path';
 import { checkStaleness } from '../git-staleness.js';
-import { loadGroupConfig } from './config-parser.js';
+import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
+import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
 import { getDefaultGitnexusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
 import { syncGroup } from './sync.js';
-function repoInSubgroup(repoPath, subgroup) {
-    if (!subgroup?.trim())
-        return true;
-    const s = subgroup.replace(/\/+$/, '');
-    return repoPath === s || repoPath.startsWith(`${s}/`);
+function isStoredContract(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const o = raw;
+    return (typeof o.contractId === 'string' &&
+        typeof o.type === 'string' &&
+        typeof o.repo === 'string' &&
+        typeof o.role === 'string' &&
+        (o.role === 'provider' || o.role === 'consumer') &&
+        typeof o.symbolUid === 'string' &&
+        typeof o.symbolName === 'string' &&
+        typeof o.confidence === 'number' &&
+        o.meta !== undefined &&
+        typeof o.meta === 'object' &&
+        o.meta !== null &&
+        o.symbolRef !== undefined &&
+        typeof o.symbolRef === 'object' &&
+        o.symbolRef !== null &&
+        typeof o.symbolRef.filePath === 'string' &&
+        typeof o.symbolRef.name === 'string');
+}
+function filterQueryByServicePrefix(queryResult, servicePrefix) {
+    const symbols = (queryResult.process_symbols || []).filter((s) => fileMatchesServicePrefix(typeof s.filePath === 'string' ? s.filePath : undefined, servicePrefix));
+    const allowed = new Set(symbols.map((s) => String(s.process_id ?? '')).filter(Boolean));
+    const processes = (queryResult.processes || []).filter((p) => allowed.has(String(p.id)));
+    return { processes, process_symbols: symbols };
+}
+function isCrossLink(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const o = raw;
+    const from = o.from;
+    const to = o.to;
+    if (!from || !to)
+        return false;
+    if (typeof from.repo !== 'string' || typeof to.repo !== 'string')
+        return false;
+    return typeof o.contractId === 'string' && typeof o.type === 'string';
+}
+async function loadContractRegistryResilient(groupDir) {
+    const filePath = path.join(groupDir, 'contracts.json');
+    let raw;
+    try {
+        raw = await fsp.readFile(filePath, 'utf-8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            return { ok: false, error: `No contracts.json for this group. Run group_sync first.` };
+        }
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+    let root;
+    try {
+        root = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: 'contracts.json is not valid JSON' };
+    }
+    if (!root || typeof root !== 'object' || Array.isArray(root)) {
+        return { ok: false, error: 'contracts.json has an invalid root object' };
+    }
+    const base = root;
+    const contractsRaw = base.contracts;
+    const crossRaw = base.crossLinks;
+    let skippedCorrupt = 0;
+    const contracts = [];
+    if (Array.isArray(contractsRaw)) {
+        for (const row of contractsRaw) {
+            try {
+                if (isStoredContract(row)) {
+                    contracts.push(row);
+                }
+                else {
+                    skippedCorrupt++;
+                    console.warn('[group] skipping corrupt contract row in contracts.json');
+                }
+            }
+            catch {
+                skippedCorrupt++;
+                console.warn('[group] skipping corrupt contract row in contracts.json');
+            }
+        }
+    }
+    const crossLinks = [];
+    if (Array.isArray(crossRaw)) {
+        for (const row of crossRaw) {
+            try {
+                if (isCrossLink(row)) {
+                    crossLinks.push(row);
+                }
+                else {
+                    skippedCorrupt++;
+                    console.warn('[group] skipping corrupt crossLinks row in contracts.json');
+                }
+            }
+            catch {
+                skippedCorrupt++;
+                console.warn('[group] skipping corrupt crossLinks row in contracts.json');
+            }
+        }
+    }
+    const registry = {
+        version: typeof base.version === 'number' ? base.version : 0,
+        generatedAt: typeof base.generatedAt === 'string' ? base.generatedAt : '',
+        repoSnapshots: base.repoSnapshots && typeof base.repoSnapshots === 'object' && base.repoSnapshots !== null
+            ? base.repoSnapshots
+            : {},
+        missingRepos: Array.isArray(base.missingRepos) ? base.missingRepos : [],
+        contracts,
+        crossLinks,
+    };
+    return { ok: true, registry, skippedCorrupt };
 }
 export class GroupService {
     port;
@@ -24,7 +134,15 @@ export class GroupService {
             return { groups };
         }
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         return {
             name: config.name,
             description: config.description,
@@ -37,7 +155,15 @@ export class GroupService {
         if (!name)
             return { error: 'name is required' };
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         const result = await syncGroup(config, {
             groupDir,
             exactOnly: Boolean(params.exactOnly),
@@ -57,10 +183,14 @@ export class GroupService {
         if (!name)
             return { error: 'name is required' };
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const registry = await readContractRegistry(groupDir);
-        if (!registry) {
-            return { error: `No contracts.json for group "${name}". Run group_sync first.` };
+        const loaded = await loadContractRegistryResilient(groupDir);
+        if (loaded.ok === false) {
+            if (loaded.error.includes('No contracts.json')) {
+                return { error: `No contracts.json for group "${name}". Run group_sync first.` };
+            }
+            return { error: loaded.error };
         }
+        const { registry, skippedCorrupt } = loaded;
         let contracts = registry.contracts;
         if (params.type)
             contracts = contracts.filter((c) => c.type === params.type);
@@ -73,21 +203,117 @@ export class GroupService {
             ]));
             contracts = contracts.filter((c) => !matchedIds.has(`${c.repo}::${c.contractId}`));
         }
-        return { contracts, crossLinks: registry.crossLinks };
+        const out = { contracts, crossLinks: registry.crossLinks };
+        if (skippedCorrupt > 0)
+            out.skippedCorrupt = skippedCorrupt;
+        return out;
+    }
+    async groupImpact(params) {
+        const { runGroupImpact } = await import('./cross-impact.js');
+        return runGroupImpact({ port: this.port, gitnexusDir: getDefaultGitnexusDir() }, params);
+    }
+    async groupContext(params) {
+        const name = String(params.name ?? '').trim();
+        const target = typeof params.target === 'string' ? params.target.trim() : '';
+        const uid = typeof params.uid === 'string' ? params.uid.trim() : undefined;
+        const file_path = typeof params.file_path === 'string' ? params.file_path : undefined;
+        const include_content = Boolean(params.include_content);
+        if (params.service !== undefined &&
+            params.service !== null &&
+            String(params.service).trim() === '') {
+            return { group: name || '', error: 'service must not be an empty string', results: [] };
+        }
+        const servicePrefix = normalizeServicePrefix(params.service);
+        const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+        const subgroupExact = params.subgroupExact === true;
+        if (!name) {
+            return { group: '', error: 'name is required', results: [] };
+        }
+        if (!uid && !target) {
+            return { group: name, error: 'target or uid is required', results: [] };
+        }
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (e) {
+            if (e instanceof GroupNotFoundError)
+                return {
+                    group: name,
+                    target: target || uid,
+                    service: servicePrefix,
+                    error: `Group "${name}" not found. Run group_list to see configured groups.`,
+                    results: [],
+                };
+            return {
+                group: name,
+                target: target || uid,
+                service: servicePrefix,
+                error: e instanceof Error ? e.message : String(e),
+                results: [],
+            };
+        }
+        const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
+        const results = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
+            try {
+                const repoObj = await this.port.resolveRepo(registryName);
+                const payload = await this.port.context(repoObj, {
+                    name: target || undefined,
+                    uid,
+                    file_path,
+                    include_content,
+                });
+                if (servicePrefix) {
+                    const st = payload?.status;
+                    const sym = payload?.symbol;
+                    if (st === 'found' && !fileMatchesServicePrefix(sym?.filePath, servicePrefix)) {
+                        return { repoPath, registryName, payload: {} };
+                    }
+                }
+                return { repoPath, registryName, payload };
+            }
+            catch (e) {
+                return {
+                    repoPath,
+                    registryName,
+                    payload: { error: e instanceof Error ? e.message : String(e) },
+                };
+            }
+        }));
+        return {
+            group: name,
+            target: target || uid,
+            service: servicePrefix,
+            results,
+        };
     }
     async groupQuery(params) {
         const name = String(params.name ?? '').trim();
         const queryText = String(params.query ?? '').trim();
         if (!name || !queryText)
             return { error: 'name and query are required' };
+        if (params.service !== undefined &&
+            params.service !== null &&
+            String(params.service).trim() === '') {
+            return { error: 'service must not be an empty string' };
+        }
+        const servicePrefix = normalizeServicePrefix(params.service);
         const limit = typeof params.limit === 'number' && params.limit > 0 ? params.limit : 5;
         const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+        const subgroupExact = params.subgroupExact === true;
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
-        const perRepo = [];
-        for (const [repoPath, registryName] of Object.entries(config.repos)) {
-            if (!repoInSubgroup(repoPath, subgroup))
-                continue;
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
+        const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
+        const perRepo = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
             try {
                 const repoObj = await this.port.resolveRepo(registryName);
                 const queryResult = (await this.port.query(repoObj, {
@@ -96,18 +322,20 @@ export class GroupService {
                     max_symbols: 10,
                     include_content: false,
                 }));
-                const processes = queryResult.processes || [];
+                const processes = servicePrefix
+                    ? filterQueryByServicePrefix(queryResult, servicePrefix).processes
+                    : queryResult.processes || [];
                 const scored = processes.map((p, idx) => ({
                     ...p,
                     _rrf_score: 1 / (idx + 1 + 60),
                     _repo: repoPath,
                 }));
-                perRepo.push({ repo: repoPath, score: 0, processes: scored });
+                return { repo: repoPath, score: 0, processes: scored };
             }
             catch {
-                perRepo.push({ repo: repoPath, score: 0, processes: [] });
+                return { repo: repoPath, score: 0, processes: [] };
             }
-        }
+        }));
         const allProcesses = perRepo.flatMap((r) => r.processes);
         allProcesses.sort((a, b) => b._rrf_score - a._rrf_score);
         const topN = allProcesses.slice(0, limit);
@@ -123,15 +351,21 @@ export class GroupService {
         if (!name)
             return { error: 'name is required' };
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         const registry = await readContractRegistry(groupDir);
         const repoStatuses = {};
-        const fsp = await import('node:fs/promises');
-        const pathMod = await import('node:path');
         for (const [repoPath, registryName] of Object.entries(config.repos)) {
             try {
                 const repoObj = await this.port.resolveRepo(registryName);
-                const metaPath = pathMod.join(repoObj.storagePath, 'meta.json');
+                const metaPath = path.join(repoObj.storagePath, 'meta.json');
                 const metaRaw = await fsp.readFile(metaPath, 'utf-8').catch(() => '{}');
                 const meta = JSON.parse(metaRaw);
                 const staleness = meta.lastCommit

package/dist/core/group/types.d.ts

@@ -83,6 +83,8 @@ export interface RepoHandle {
     repoPath: string;
     storagePath: string;
 }
+/** Why local impact or fan-out stopped early (e.g. wall-clock budget exhausted). */
+export type GroupImpactTruncationReason = 'timeout' | 'partial';
 export interface GroupImpactResult {
     local: unknown;
     group: string;
@@ -97,6 +99,34 @@ export interface GroupImpactResult {
         cross_repo_hits: number;
     };
     risk: string;
+    /**
+     * Milliseconds budget applied to the **Phase 1 local impact** leg (`safeLocalImpact`).
+     * If the walk hits this wall first, expect `truncationReason: 'timeout'` and a partial `local` payload.
+     */
+    timeoutMs?: number;
+    /** Present when local impact or fan-out stopped early (timeout, graph cap, etc.). */
+    truncationReason?: GroupImpactTruncationReason;
+    /**
+     * Human-readable note when `crossDepth` was clamped (e.g. multi-hop not implemented yet).
+     */
+    crossDepthWarning?: string;
+}
+/** One repo’s `context` tool payload in a group-scoped context run. */
+export interface GroupContextRepoEntry {
+    repoPath: string;
+    registryName: string;
+    payload: unknown;
+}
+/**
+ * Aggregated group `context`: explicit per-repo rows (no merged symbol payloads).
+ * Use top-level `error` only for unrecoverable failures, not for “no matches” or service scope misses.
+ */
+export interface GroupContextResult {
+    group: string;
+    target?: string;
+    service?: string;
+    error?: string;
+    results: GroupContextRepoEntry[];
 }
 export interface CrossRepoImpact {
     repo: string;

package/dist/core/ingestion/ast-cache.d.ts

@@ -1,5 +1,20 @@
 import Parser from 'tree-sitter';
-export interface ASTCache {
+/**
+ * Minimal structural shape consumers need when reading Trees back
+ * through a phase-dependency boundary. Declared here so phases that
+ * receive ASTCache via `getPhaseOutput<...>` don't hand-roll their
+ * own inline structural types that silently drift when ASTCache's
+ * contract changes.
+ *
+ * Typed as `unknown` at the Tree boundary because consumers on the
+ * other side of the phase-output map don't share tree-sitter's type
+ * graph (e.g. COBOL's standalone processor).
+ */
+export interface ASTCacheReader {
+    get(filePath: string): unknown;
+    clear(): void;
+}
+export interface ASTCache extends ASTCacheReader {
     get: (filePath: string) => Parser.Tree | undefined;
     set: (filePath: string, tree: Parser.Tree) => void;
     clear: () => void;

package/dist/core/ingestion/ast-cache.js

@@ -7,8 +7,20 @@ export const createASTCache = (maxSize = 50) => {
         max: effectiveMax,
         dispose: (tree) => {
             try {
-                // NOTE: web-tree-sitter has tree.delete(); native tree-sitter trees are GC-managed.
-                // Keep this try/catch so we don't crash on either runtime.
+                // NOTE: web-tree-sitter has tree.delete(); native tree-sitter
+                // trees are GC-managed and .delete is absent (no-op here).
+                //
+                // Single-owner invariant (load-bearing under WASM): a given
+                // Parser.Tree reference must live in AT MOST ONE ASTCache
+                // that disposes. The parse-phase chunk-local cache clears
+                // between chunks; the cross-phase `scopeTreeCache` (also an
+                // ASTCache today) holds the same Tree by reference. Under
+                // native tree-sitter this is benign (dispose is a no-op).
+                // If/when GitNexus adopts web-tree-sitter for sequential
+                // parsing, the cross-phase cache must either (a) skip
+                // writing Trees that are already owned by a disposing cache,
+                // or (b) use tree.copy() per entry. Failing to pick one
+                // will hand freed memory to scope-resolution.
                 tree.delete?.();
             }
             catch (e) {

package/dist/core/ingestion/call-processor.js

@@ -26,6 +26,7 @@ import { isLanguageAvailable, loadParser, loadLanguage } from '../tree-sitter/pa
 import { getProvider } from './languages/index.js';
 import { generateId } from '../../lib/utils.js';
 import { getLanguageFromFilename, SupportedLanguages } from '../../_shared/index.js';
+import { isRegistryPrimary } from './registry-primary-flag.js';
 import { isVerboseIngestionEnabled } from './utils/verbose.js';
 import { yieldToEventLoop } from './utils/event-loop.js';
 import { FUNCTION_NODE_TYPES, findEnclosingClassId, findEnclosingClassInfo, genericFuncName, inferFunctionLabel, } from './utils/ast-helpers.js';
@@ -594,6 +595,9 @@ importedRawReturnTypesMap, heritageMap, bindingAccumulator) => {
         const language = getLanguageFromFilename(file.path);
         if (!language)
             continue;
+        // Registry-primary gate: scope-based phase owns CALLS for this lang.
+        if (isRegistryPrimary(language))
+            continue;
         if (!isLanguageAvailable(language)) {
             if (skippedByLang) {
                 skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);
@@ -2162,6 +2166,11 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
             onProgress?.(filesProcessed, totalFiles);
             await yieldToEventLoop();
         }
+        // Registry-primary gate: skip Python (etc.) entirely when the
+        // scope-based phase owns CALLS for this language.
+        const fileLanguage = getLanguageFromFilename(filePath);
+        if (fileLanguage && isRegistryPrimary(fileLanguage))
+            continue;
         ctx.enableCache(filePath);
         const widenCache = new Map();
         const receiverMap = fileReceiverTypes.get(filePath);

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

@@ -0,0 +1,88 @@
+/**
+ * Phase 5 of the RFC #909 ingestion lifecycle: drain `ReferenceIndex`
+ * into the knowledge graph as labeled edges with `confidence` and
+ * `evidence` properties (Ring 2 PKG #925).
+ *
+ * The resolution phase (future PR) writes `Reference` records into
+ * `model.scopes.referenceSites`-derived `ReferenceIndex`; this module
+ * materializes those records as `GraphRelationship`s via
+ * `graph.addRelationship`. Every emitted edge carries:
+ *
+ *   - `type`: one of `'CALLS' | 'ACCESSES' | 'INHERITS' | 'USES'`
+ *     (mapped from `Reference.kind` — `'read'` and `'write'` both route
+ *     to `ACCESSES`; `'type-reference'` and `'import-use'` route to
+ *     `USES`; `'call'` stays `CALLS`; `'inherits'` stays `INHERITS`).
+ *   - `confidence`: the pre-computed confidence from the Reference record.
+ *   - `reason`: human-readable summary (`"scope-resolution: call | confidence 0.75"`).
+ *   - `evidence`: the full `ResolutionEvidence[]` trace — additive graph
+ *     property (see `GraphRelationship.evidence` in gitnexus-shared),
+ *     so queries that don't know about it are unaffected.
+ *   - `step`: carries the reference's access-kind discriminant when
+ *     available (`1` for read, `2` for write) so `ACCESSES` edges retain
+ *     the read/write distinction without forcing a new edge type.
+ *
+ * ## Optional scope-tree flush
+ *
+ * When `INGESTION_EMIT_SCOPES=1` is set, this module also emits:
+ *
+ *   - `Scope` nodes for every `Scope` in the tree
+ *   - `CONTAINS` edges from parent scope to child scope
+ *   - `DEFINES` edges from scope to its `ownedDefs` members
+ *   - `IMPORTS` edges from scope to `targetModuleScope` of each finalized
+ *     `ImportEdge` that carries one
+ *
+ * Off by default — existing queries that don't know about `Scope` nodes
+ * continue to work, and the storage cost is opt-in.
+ *
+ * ## Source-of-truth: the caller def for a reference
+ *
+ * A `Reference` says "some code inside `fromScope` references `toDef`".
+ * The graph wants `(callerNodeId, calleeNodeId)`. We resolve the caller
+ * by walking up the scope tree from `fromScope` until we find a scope
+ * whose `ownedDefs` contains a Function-like def. If no such ancestor
+ * exists, the edge is attributed to the first def owned by the innermost
+ * ancestor scope, and if THAT produces nothing either the edge is
+ * skipped (with a count returned in `EmitStats.skippedNoCaller`).
+ */
+import type { ReferenceIndex } from '../../_shared/index.js';
+import type { KnowledgeGraph } from '../graph/types.js';
+import type { ScopeResolutionIndexes } from './model/scope-resolution-indexes.js';
+export interface EmitStats {
+    readonly edgesEmitted: number;
+    /** References dropped because no caller def could be resolved. */
+    readonly skippedNoCaller: number;
+    /** References dropped because `toDef` was not found in the DefIndex. */
+    readonly skippedMissingTarget: number;
+    /** Scope nodes emitted — `0` unless `INGESTION_EMIT_SCOPES=1`. */
+    readonly scopeNodesEmitted: number;
+    /** Scope-tree structural edges emitted — `0` unless `INGESTION_EMIT_SCOPES=1`. */
+    readonly scopeEdgesEmitted: number;
+}
+export interface EmitReferencesInput {
+    readonly graph: KnowledgeGraph;
+    readonly scopes: ScopeResolutionIndexes;
+    readonly referenceIndex: ReferenceIndex;
+    /** Human-consumable label for the `reason` prefix. Defaults to `'scope-resolution'`. */
+    readonly sourceLabel?: string;
+}
+/**
+ * Drain `referenceIndex.bySourceScope` into graph edges.
+ *
+ * The scope-tree flush is controlled separately by
+ * `INGESTION_EMIT_SCOPES` — callers can run `emitReferencesToGraph`
+ * without scope-node emission or layer the two calls as needed.
+ */
+export declare function emitReferencesToGraph(input: EmitReferencesInput): EmitStats;
+/**
+ * Emit `Scope` nodes + `CONTAINS`/`DEFINES`/`IMPORTS` edges representing
+ * the lexical scope tree itself. Skipped unless `INGESTION_EMIT_SCOPES=1`
+ * at the public entry point; exported here for tests that want to
+ * exercise the path directly.
+ */
+export declare function emitScopeGraph(input: {
+    readonly graph: KnowledgeGraph;
+    readonly scopes: ScopeResolutionIndexes;
+}): {
+    readonly scopeNodesEmitted: number;
+    readonly scopeEdgesEmitted: number;
+};