import { type FSWatcher } from "node:fs";
import { type DerivedCheckpointLock } from "./checkpoint-lock.js";
import { type WikiPageRecord } from "./page-record.js";
import { type RetrievalProfile } from "./text-analysis.js";
import { CorpusRevisionLedger, type RetrievalCheckpointData, type RetrievalCheckpointWriteBoundsReason, type RetrievalFallbackReason, type RetrievalPosting } from "./retrieval-checkpoint.js";
export { indexedTermsForRecord } from "./retrieval-terms.js";
interface CachedPhraseBigrams {
    record: WeakRef<WikiPageRecord>;
    title: ReadonlySet<string>;
    passages: ReadonlyArray<ReadonlySet<string>>;
    estimatedBytes: number;
}
interface IndexState extends RetrievalCheckpointData {
    records: Map<string, WikiPageRecord>;
    postings: Map<string, Map<string, RetrievalPosting>>;
    totalTokenCount: number;
    lastScanMs: number;
    loaded: boolean;
    dirty: boolean;
    persistenceDirty: boolean;
    persistenceStatus: "available" | "skipped_oversized";
    persistenceReason: RetrievalCheckpointWriteBoundsReason | null;
    watcherReliable: boolean;
    generation: number;
    persistedRevision: string | null;
    persistedArtifactToken: string | null;
    revisionLedger: CorpusRevisionLedger;
    deltaCount: number;
    deltaBytes: number;
    fallbackReason: RetrievalFallbackReason;
    recovery: "pending" | "restored" | "patched" | "rebuilt";
    verificationMode: RetrievalVerificationMode;
    reusedRecords: number;
    changedRecords: number;
    snapshotLoadMs: number;
    verificationMs: number;
    phraseCache: Map<string, CachedPhraseBigrams>;
    phraseCacheBytes: number;
    refreshPromise?: Promise<IndexState>;
    persistencePromise?: Promise<void>;
    watcher?: FSWatcher;
}
export type RetrievalVerificationMode = "metadata" | "content";
export interface RetrievalIndexDiagnostics {
    snapshotLoaded: boolean;
    deltaCount: number;
    reusedRecords: number;
    changedRecords: number;
    verificationMode: RetrievalVerificationMode;
    fallbackReason: RetrievalFallbackReason;
    recovery: IndexState["recovery"];
    persistenceStatus: IndexState["persistenceStatus"];
    persistenceReason: RetrievalCheckpointWriteBoundsReason | null;
    corpusRevision: string;
    timingsMs: {
        snapshotLoad: number;
        verification: number;
    };
}
export interface RetrievalPersistenceIdentity {
    corpusRevision: string;
    persistedRevision: string | null;
    artifactToken: string | null;
    persistenceStatus: IndexState["persistenceStatus"];
    persistenceReason: RetrievalCheckpointWriteBoundsReason | null;
}
export interface RetrievalHit {
    path: string;
    title: string;
    type: string;
    tags: string[];
    sources: string[];
    requestId?: string;
    score: number;
    /** Internal pre-phrase lexical signal used for coverage-safe graph seeding. */
    lexicalBaselineScore?: number;
    /** Internal one-based pre-phrase rank; never serialized by MCP tools. */
    lexicalBaselineRank?: number;
    excerpt: string;
    heading: string;
    record: WikiPageRecord;
}
export interface PhraseRankChange {
    path: string;
    baselineRank: number;
    rerankedRank: number;
    matchedBigrams: number;
    heading: string;
}
export interface PhraseRerankDiagnostics {
    enabled: boolean;
    queryBigramCount: number;
    protectedIdentifierCount: number;
    candidateCount: number;
    rescoredCount: number;
    rankChanges: PhraseRankChange[];
}
export declare function refreshRetrievalIndex(wikiRoot: string, options?: {
    force?: boolean;
    persist?: boolean;
    verificationMode?: RetrievalVerificationMode;
    rebuild?: boolean;
}): Promise<IndexState>;
export declare function getRetrievalIndexGeneration(wikiRoot: string): number;
export declare function getRetrievalCorpusRevision(wikiRoot: string): string | null;
export declare function getRetrievalPersistenceIdentity(wikiRoot: string): RetrievalPersistenceIdentity | null;
export declare function getRetrievalIndexDiagnostics(wikiRoot: string): RetrievalIndexDiagnostics;
export declare function updateRetrievalPaths(wikiRoot: string, relPaths: readonly string[], options?: {
    checkpointLock?: DerivedCheckpointLock;
}): Promise<void>;
export declare function searchRetrievalIndex(params: {
    wikiRoot: string;
    query?: string;
    maxResults?: number;
    pageTypes?: readonly string[];
    profile?: RetrievalProfile;
    forceRefresh?: boolean;
    verificationMode?: RetrievalVerificationMode;
    /** Internal soak/benchmark switch. Production defaults to enabled. */
    phraseRerank?: boolean;
    /** Internal benchmark diagnostics; never added to MCP result payloads. */
    onPhraseDiagnostics?: (diagnostics: PhraseRerankDiagnostics) => void;
    /** Opt-in local profiling; not part of MCP results. */
    onLexicalDiagnostics?: (diagnostics: {
        candidates: number;
        scoringMs: number;
        sortingMs: number;
    }) => void;
    /** Persist refreshed derived state. Read-only MCP operations set this to false. */
    persist?: boolean;
}): Promise<RetrievalHit[]>;
export declare function getWikiPageRecords(wikiRoot: string, forceRefresh?: boolean, options?: {
    persist?: boolean;
}): Promise<WikiPageRecord[]>;
export declare function getVerifiedWikiCorpus(wikiRoot: string, forceRefresh?: boolean, options?: {
    persist?: boolean;
    verificationMode?: RetrievalVerificationMode;
}): Promise<{
    records: WikiPageRecord[];
    corpusRevision: string;
    generation: number;
}>;
export declare function clearRetrievalIndexes(): void;
//# sourceMappingURL=retrieval-index.d.ts.map