arceus-s 1.6.4

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

@@ -0,0 +1,318 @@
+/**
+ * Process Detection Processor
+ *
+ * Detects execution flows (Processes) in the code graph by:
+ * 1. Finding entry points (functions with no internal callers)
+ * 2. Tracing forward via CALLS edges (BFS)
+ * 3. Grouping and deduplicating similar paths
+ * 4. Labeling with heuristic names
+ *
+ * Processes help agents understand how features work through the codebase.
+ */
+import { calculateEntryPointScore, isTestFile } from './entry-point-scoring.js';
+import { SupportedLanguages } from '../../_shared/index.js';
+import { isDev } from './utils/env.js';
+import { logger } from '../logger.js';
+const DEFAULT_CONFIG = {
+    maxTraceDepth: 10,
+    maxBranching: 4,
+    maxProcesses: 75,
+    minSteps: 3, // 3+ steps = genuine multi-hop flow (2-step is just "A calls B")
+};
+// ============================================================================
+// MAIN PROCESSOR
+// ============================================================================
+/**
+ * Detect processes (execution flows) in the knowledge graph
+ *
+ * This runs AFTER community detection, using CALLS edges to trace flows.
+ */
+export const processProcesses = async (knowledgeGraph, memberships, onProgress, config = {}) => {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    onProgress?.('Finding entry points...', 0);
+    // Build lookup maps
+    const membershipMap = new Map();
+    memberships.forEach((m) => membershipMap.set(m.nodeId, m.communityId));
+    const callsEdges = buildCallsGraph(knowledgeGraph);
+    const reverseCallsEdges = buildReverseCallsGraph(knowledgeGraph);
+    const nodeMap = new Map();
+    for (const n of knowledgeGraph.iterNodes())
+        nodeMap.set(n.id, n);
+    // Step 1: Find entry points (functions that call others but have few callers)
+    const entryPoints = findEntryPoints(knowledgeGraph, reverseCallsEdges, callsEdges);
+    onProgress?.(`Found ${entryPoints.length} entry points, tracing flows...`, 20);
+    onProgress?.(`Found ${entryPoints.length} entry points, tracing flows...`, 20);
+    // Step 2: Trace processes from each entry point
+    const allTraces = [];
+    for (let i = 0; i < entryPoints.length && allTraces.length < cfg.maxProcesses * 2; i++) {
+        const entryId = entryPoints[i];
+        const traces = traceFromEntryPoint(entryId, callsEdges, cfg);
+        // Filter out traces that are too short
+        traces.filter((t) => t.length >= cfg.minSteps).forEach((t) => allTraces.push(t));
+        if (i % 10 === 0) {
+            onProgress?.(`Tracing entry point ${i + 1}/${entryPoints.length}...`, 20 + (i / entryPoints.length) * 40);
+        }
+    }
+    onProgress?.(`Found ${allTraces.length} traces, deduplicating...`, 60);
+    // Step 3: Deduplicate similar traces (subset removal)
+    const uniqueTraces = deduplicateTraces(allTraces);
+    // Step 3b: Deduplicate by entry+terminal pair (keep longest path per pair)
+    const endpointDeduped = deduplicateByEndpoints(uniqueTraces);
+    onProgress?.(`Deduped ${uniqueTraces.length} → ${endpointDeduped.length} unique endpoint pairs`, 70);
+    // Step 4: Limit to max processes (prioritize longer traces)
+    const limitedTraces = endpointDeduped
+        .sort((a, b) => b.length - a.length)
+        .slice(0, cfg.maxProcesses);
+    onProgress?.(`Creating ${limitedTraces.length} process nodes...`, 80);
+    // Step 5: Create process nodes
+    const processes = [];
+    const steps = [];
+    limitedTraces.forEach((trace, idx) => {
+        const entryPointId = trace[0];
+        const terminalId = trace[trace.length - 1];
+        // Get communities touched
+        const communitiesSet = new Set();
+        trace.forEach((nodeId) => {
+            const comm = membershipMap.get(nodeId);
+            if (comm)
+                communitiesSet.add(comm);
+        });
+        const communities = Array.from(communitiesSet);
+        // Determine process type
+        const processType = communities.length > 1 ? 'cross_community' : 'intra_community';
+        // Generate label
+        const entryNode = nodeMap.get(entryPointId);
+        const terminalNode = nodeMap.get(terminalId);
+        const entryName = entryNode?.properties.name || 'Unknown';
+        const terminalName = terminalNode?.properties.name || 'Unknown';
+        const heuristicLabel = `${capitalize(entryName)} → ${capitalize(terminalName)}`;
+        const processId = `proc_${idx}_${sanitizeId(entryName)}`;
+        processes.push({
+            id: processId,
+            label: heuristicLabel,
+            heuristicLabel,
+            processType,
+            stepCount: trace.length,
+            communities,
+            entryPointId,
+            terminalId,
+            trace,
+        });
+        // Create step relationships
+        trace.forEach((nodeId, stepIdx) => {
+            steps.push({
+                nodeId,
+                processId,
+                step: stepIdx + 1, // 1-indexed
+            });
+        });
+    });
+    onProgress?.('Process detection complete!', 100);
+    // Calculate stats
+    const crossCommunityCount = processes.filter((p) => p.processType === 'cross_community').length;
+    const avgStepCount = processes.length > 0
+        ? processes.reduce((sum, p) => sum + p.stepCount, 0) / processes.length
+        : 0;
+    return {
+        processes,
+        steps,
+        stats: {
+            totalProcesses: processes.length,
+            crossCommunityCount,
+            avgStepCount: Math.round(avgStepCount * 10) / 10,
+            entryPointsFound: entryPoints.length,
+        },
+    };
+};
+/**
+ * Minimum edge confidence for process tracing.
+ * Filters out ambiguous fuzzy-global matches (0.3) that cause
+ * traces to jump across unrelated code areas.
+ */
+const MIN_TRACE_CONFIDENCE = 0.5;
+const buildCallsGraph = (graph) => {
+    const adj = new Map();
+    for (const rel of graph.iterRelationships()) {
+        if (rel.type === 'CALLS' && rel.confidence >= MIN_TRACE_CONFIDENCE) {
+            if (!adj.has(rel.sourceId)) {
+                adj.set(rel.sourceId, []);
+            }
+            adj.get(rel.sourceId).push(rel.targetId);
+        }
+    }
+    return adj;
+};
+const buildReverseCallsGraph = (graph) => {
+    const adj = new Map();
+    for (const rel of graph.iterRelationships()) {
+        if (rel.type === 'CALLS' && rel.confidence >= MIN_TRACE_CONFIDENCE) {
+            if (!adj.has(rel.targetId)) {
+                adj.set(rel.targetId, []);
+            }
+            adj.get(rel.targetId).push(rel.sourceId);
+        }
+    }
+    return adj;
+};
+/**
+ * Find functions/methods that are good entry points for tracing.
+ *
+ * Entry points are scored based on:
+ * 1. Call ratio (calls many, called by few)
+ * 2. Export status (exported/public functions rank higher)
+ * 3. Name patterns (handle*, on*, *Controller, etc.)
+ *
+ * Test files are excluded entirely.
+ */
+const findEntryPoints = (graph, reverseCallsEdges, callsEdges) => {
+    const symbolTypes = new Set(['Function', 'Method']);
+    const entryPointCandidates = [];
+    for (const node of graph.iterNodes()) {
+        if (!symbolTypes.has(node.label))
+            continue;
+        const filePath = node.properties.filePath || '';
+        // Skip test files entirely
+        if (isTestFile(filePath))
+            continue;
+        const callers = reverseCallsEdges.get(node.id) || [];
+        const callees = callsEdges.get(node.id) || [];
+        // Must have at least 1 outgoing call to trace forward
+        if (callees.length === 0)
+            continue;
+        // Calculate entry point score using new scoring system
+        const { score: baseScore, reasons } = calculateEntryPointScore(node.properties.name, (node.properties.language ?? SupportedLanguages.JavaScript), node.properties.isExported ?? false, callers.length, callees.length, filePath);
+        let score = baseScore;
+        const astFrameworkMultiplier = node.properties.astFrameworkMultiplier ?? 1.0;
+        if (astFrameworkMultiplier > 1.0) {
+            score *= astFrameworkMultiplier;
+            reasons.push(`framework-ast:${node.properties.astFrameworkReason || 'decorator'}`);
+        }
+        if (score > 0) {
+            entryPointCandidates.push({ id: node.id, score, reasons });
+        }
+    }
+    // Sort by score descending and return top candidates
+    const sorted = entryPointCandidates.sort((a, b) => b.score - a.score);
+    // DEBUG: Log top candidates with new scoring details
+    if (sorted.length > 0 && isDev) {
+        logger.info(`[Process] Top 10 entry point candidates (new scoring):`);
+        sorted.slice(0, 10).forEach((c, i) => {
+            const node = graph.getNode(c.id);
+            const exported = node?.properties.isExported ? '✓' : '✗';
+            const shortPath = node?.properties.filePath?.split('/').slice(-2).join('/') || '';
+            logger.info(`  ${i + 1}. ${node?.properties.name} [exported:${exported}] (${shortPath})`);
+            logger.info(`     score: ${c.score.toFixed(2)} = [${c.reasons.join(' × ')}]`);
+        });
+    }
+    return sorted
+        .slice(0, 200) // Limit to prevent explosion
+        .map((c) => c.id);
+};
+// ============================================================================
+// HELPER: Trace from entry point (BFS)
+// ============================================================================
+/**
+ * Trace forward from an entry point using BFS.
+ * Returns all distinct paths up to maxDepth.
+ */
+const traceFromEntryPoint = (entryId, callsEdges, config) => {
+    const traces = [];
+    // BFS with path tracking
+    // Each queue item: [currentNodeId, pathSoFar]
+    const queue = [[entryId, [entryId]]];
+    while (queue.length > 0 && traces.length < config.maxBranching * 3) {
+        const [currentId, path] = queue.shift();
+        // Get outgoing calls
+        const callees = callsEdges.get(currentId) || [];
+        if (callees.length === 0) {
+            // Terminal node - this is a complete trace
+            if (path.length >= config.minSteps) {
+                traces.push([...path]);
+            }
+        }
+        else if (path.length >= config.maxTraceDepth) {
+            // Max depth reached - save what we have
+            if (path.length >= config.minSteps) {
+                traces.push([...path]);
+            }
+        }
+        else {
+            // Continue tracing - limit branching
+            const limitedCallees = callees.slice(0, config.maxBranching);
+            let addedBranch = false;
+            for (const calleeId of limitedCallees) {
+                // Avoid cycles
+                if (!path.includes(calleeId)) {
+                    queue.push([calleeId, [...path, calleeId]]);
+                    addedBranch = true;
+                }
+            }
+            // If all branches were cycles, save current path as terminal
+            if (!addedBranch && path.length >= config.minSteps) {
+                traces.push([...path]);
+            }
+        }
+    }
+    return traces;
+};
+// ============================================================================
+// HELPER: Deduplicate traces
+// ============================================================================
+/**
+ * Merge traces that are subsets of other traces.
+ * Keep longer traces, remove redundant shorter ones.
+ */
+const deduplicateTraces = (traces) => {
+    if (traces.length === 0)
+        return [];
+    // Sort by length descending
+    const sorted = [...traces].sort((a, b) => b.length - a.length);
+    const unique = [];
+    for (const trace of sorted) {
+        // Check if this trace is a subset of any already-added trace
+        const traceKey = trace.join('->');
+        const isSubset = unique.some((existing) => {
+            const existingKey = existing.join('->');
+            return existingKey.includes(traceKey);
+        });
+        if (!isSubset) {
+            unique.push(trace);
+        }
+    }
+    return unique;
+};
+// ============================================================================
+// HELPER: Deduplicate by entry+terminal endpoints
+// ============================================================================
+/**
+ * Keep only the longest trace per unique entry→terminal pair.
+ * Multiple paths between the same two endpoints are redundant for agents.
+ */
+const deduplicateByEndpoints = (traces) => {
+    if (traces.length === 0)
+        return [];
+    const byEndpoints = new Map();
+    // Sort longest first so the first seen per key is the longest
+    const sorted = [...traces].sort((a, b) => b.length - a.length);
+    for (const trace of sorted) {
+        const key = `${trace[0]}::${trace[trace.length - 1]}`;
+        if (!byEndpoints.has(key)) {
+            byEndpoints.set(key, trace);
+        }
+    }
+    return Array.from(byEndpoints.values());
+};
+// ============================================================================
+// HELPER: String utilities
+// ============================================================================
+const capitalize = (s) => {
+    if (!s)
+        return s;
+    return s.charAt(0).toUpperCase() + s.slice(1);
+};
+const sanitizeId = (s) => {
+    return s
+        .replace(/[^a-zA-Z0-9]/g, '_')
+        .substring(0, 20)
+        .toLowerCase();
+};

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

@@ -0,0 +1,88 @@
+/**
+ * `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 (`ARC_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

@@ -0,0 +1,117 @@
+/**
+ * `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 (`ARC_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 const MIGRATED_LANGUAGES = new Set([
+    SupportedLanguages.Python,
+    SupportedLanguages.CSharp,
+    SupportedLanguages.TypeScript,
+    SupportedLanguages.Go,
+    SupportedLanguages.C,
+    SupportedLanguages.PHP,
+]);
+/**
+ * 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 };