/**
 * Retrieval eval runner — measurement law for the Retrieval Truth Spine.
 *
 * Loads gold queries from evals/gold/retrieval.jsonl, runs every query
 * through every search mode against a fixture corpus, and reports
 * precision@1 and precision@3 per (mode × class) plus per-mode and
 * overall aggregates.
 *
 * The runner is deliberately retrieval-native: assertions check whether
 * the expected path appears in the top-K hits, not whether the answer
 * is correct. Answer synthesis is slice 5; measurement is the floor
 * under it.
 *
 * No product-surface changes ride on this file. It is a pure consumer
 * of searchCorpus() and the corpus schema.
 */
import type { CorpusFile } from "../corpus/storage.js";
import { type SearchMode } from "../corpus/searcher.js";
import type { OllamaClient } from "../ollama.js";
export type QueryClass = "semantic" | "fact" | "procedural" | "confusable";
export declare const QUERY_CLASSES: readonly QueryClass[];
export interface GoldQuery {
    id: string;
    class: QueryClass;
    query: string;
    /** Paths that count as correct answers. Match is OR: at least one must appear in top-K. Paths are matched by basename so fixture-dir location doesn't matter. */
    expected_paths: string[];
    /** Optional factual anchor. If present, at least one matching chunk's text must contain every phrase. */
    expected_phrases?: string[];
}
export declare function loadGold(filePath: string): Promise<GoldQuery[]>;
export interface EvalRecord {
    id: string;
    class: QueryClass;
    query: string;
    mode: SearchMode;
    top_paths: string[];
    hit1: boolean;
    hit3: boolean;
    /** null if no expected_phrases on the query. */
    phrasesHit: boolean | null;
}
export interface RunEvalOptions {
    gold: GoldQuery[];
    corpus: CorpusFile;
    client: OllamaClient;
    model: string;
    topK?: number;
    previewChars?: number;
}
export declare function runRetrievalEval(opts: RunEvalOptions): Promise<EvalRecord[]>;
export interface CellMetrics {
    n: number;
    precision1: number;
    precision3: number;
}
export interface EvalSummary {
    overall: CellMetrics;
    byMode: Record<SearchMode, CellMetrics>;
    byModeByClass: Record<SearchMode, Record<QueryClass, CellMetrics>>;
}
export declare function summarizeEval(records: EvalRecord[]): EvalSummary;
/**
 * Markdown-friendly report suitable for console.log during tests. The
 * shape is stable so it can be diffed between runs.
 */
export declare function formatEvalReport(summary: EvalSummary): string;
//# sourceMappingURL=retrieval.d.ts.map