import type { WikiPageRecord } from "./page-record.js";
export declare const RETRIEVAL_CHECKPOINT_SCHEMA_VERSION = 2;
export declare const RETRIEVAL_BUILDER_VERSION = "global-flat-v3-fenced-passages";
export declare const RETRIEVAL_CHECKPOINT_ENCODING = "global-flat-v1";
export interface RetrievalCheckpointWriteLimits {
    maxSnapshotBytes?: number;
    maxJournalBytes?: number;
    maxRecords?: number;
    maxTerms?: number;
    maxPostings?: number;
}
export type RetrievalCheckpointWriteBoundsReason = "snapshot_bytes" | "journal_bytes" | "record_limit" | "term_limit" | "posting_limit" | "payload_invalid";
/**
 * A normal capacity boundary, not checkpoint corruption. Callers may keep the
 * canonical Markdown generation live while reporting that warm persistence was
 * skipped. No artifact has been written when this error is raised.
 */
export declare class RetrievalCheckpointBoundsError extends Error {
    readonly reason: RetrievalCheckpointWriteBoundsReason;
    readonly code = "retrieval_checkpoint_bounds_exceeded";
    constructor(reason: RetrievalCheckpointWriteBoundsReason);
}
export interface RetrievalPosting {
    body: number;
    title: number;
    metadata: number;
}
export interface RetrievalFileMetadata {
    mtimeMs: number;
    ctimeMs?: number;
    size: number;
    dev?: number;
    ino?: number;
}
export interface RetrievalCheckpointData {
    records: Map<string, WikiPageRecord>;
    postings: Map<string, Map<string, RetrievalPosting>>;
    fingerprints: Map<string, string>;
    fileMetadata: Map<string, RetrievalFileMetadata>;
    totalTokenCount: number;
    corpusRevision: string;
}
export type IndexedTermTuple = readonly [term: string, body: number, title: number, metadata: number];
export type RetrievalFallbackReason = "none" | "forced_rebuild" | "snapshot_missing" | "snapshot_v1_migration" | "checkpoint_directory_symlink" | "checkpoint_directory_not_directory" | "snapshot_symlink" | "snapshot_not_regular" | "snapshot_oversized" | "snapshot_malformed" | "snapshot_schema_mismatch" | "snapshot_builder_mismatch" | "snapshot_checksum_mismatch" | "snapshot_bounds_invalid" | "snapshot_revision_mismatch" | "journal_without_snapshot" | "journal_symlink" | "journal_oversized" | "journal_malformed" | "journal_lineage_mismatch" | "journal_revision_mismatch";
export type RetrievalCheckpointRead = {
    kind: "v2";
    data: RetrievalCheckpointData;
    persistedRevision: string;
    deltaCount: number;
    deltaBytes: number;
    fallbackReason: "none";
} | {
    kind: "v1";
    records: WikiPageRecord[];
    fallbackReason: "snapshot_v1_migration";
} | {
    kind: "empty";
    fallbackReason: RetrievalFallbackReason;
};
export interface RetrievalDeltaInput {
    path: string;
    record: WikiPageRecord | null;
    fingerprint?: string;
    metadata?: RetrievalFileMetadata;
    indexedTerms?: IndexedTermTuple[];
}
export declare function retrievalSnapshotFile(wikiRoot: string): string;
export declare function retrievalDeltaFile(wikiRoot: string): string;
/**
 * Cheap compare-and-swap token for a generation already validated by the full
 * checkpoint reader. Atomic replacement changes inode/ctime, while a journal
 * append changes size/ctime, so stale processes are detected without parsing
 * a multi-megabyte snapshot for every single-page update.
 */
export declare function retrievalArtifactToken(wikiRoot: string): Promise<string>;
export declare function emptyRetrievalCheckpointData(): RetrievalCheckpointData;
export declare function fingerprintWikiRaw(raw: string): string;
/**
 * Deterministic Merkle revision ledger. Existing-path edits update O(log n)
 * nodes; add/delete/rename rebuilds the sorted tree because its path roster
 * changes. Domain bytes distinguish leaves, parents, and the empty corpus.
 */
export declare class CorpusRevisionLedger {
    private readonly paths;
    private readonly indexes;
    private readonly capacity;
    private readonly nodes;
    private constructor();
    static from(fingerprints: ReadonlyMap<string, string>): CorpusRevisionLedger;
    clone(): CorpusRevisionLedger;
    updateExisting(pathValue: string, fingerprint: string): boolean;
    get revision(): string;
}
export declare function computeCorpusRevision(fingerprints: ReadonlyMap<string, string>): string;
export declare function removeCheckpointRecord(data: RetrievalCheckpointData, relPath: string): void;
export declare function addCheckpointRecord(data: RetrievalCheckpointData, input: {
    record: WikiPageRecord;
    fingerprint: string;
    metadata: RetrievalFileMetadata;
    indexedTerms: readonly IndexedTermTuple[];
}): void;
export declare function readRetrievalCheckpoint(wikiRoot: string): Promise<RetrievalCheckpointRead>;
export declare function serializeRetrievalCheckpoint(data: RetrievalCheckpointData, writeLimits?: RetrievalCheckpointWriteLimits): string;
export declare function serializeRetrievalDelta(baseRevision: string, newRevision: string, changes: readonly RetrievalDeltaInput[], writeLimits?: RetrievalCheckpointWriteLimits): string;
//# sourceMappingURL=retrieval-checkpoint.d.ts.map