import type { VisibilityEnvelope } from './envelope.js';
/** The minimal fs surface snapshot persistence needs, injectable for tests. */
export interface SnapshotFs {
    readFile(path: string): Promise<string>;
    writeFile(path: string, data: string): Promise<void>;
    mkdir(path: string): Promise<void>;
    readdir(path: string): Promise<string[]>;
}
/** Thrown when a snapshot file is present but not a valid envelope. */
export declare class SnapshotParseError extends Error {
    readonly path: string;
    readonly cause: unknown;
    constructor(path: string, cause: unknown);
}
/** The snapshots directory inside a state directory. */
export declare function snapshotsDir(stateDir: string): string;
/**
 * Filename for a snapshot taken at `generatedAt`. Colons are replaced with `-`
 * (invalid in Windows filenames); the rest of the ISO string is left intact so
 * names still sort chronologically as plain strings.
 */
export declare function snapshotFileName(generatedAt: string): string;
/** Node fs.promises adapter for production use. */
export declare function nodeSnapshotFs(): SnapshotFs;
/**
 * Persist an envelope as pretty JSON, ensuring the snapshots dir exists.
 *
 * Files are keyed by `generatedAt` (the plan's `<ISO>.json`), so a re-save at
 * the identical millisecond overwrites - idempotent by design. A real `check`
 * run spends seconds querying engines, so two runs never share a millisecond
 * timestamp; the collision only arises under a deliberately fixed clock.
 */
export declare function saveSnapshot(envelope: VisibilityEnvelope, stateDir: string, fs: SnapshotFs): Promise<string>;
/**
 * Load a persisted snapshot. A present-but-corrupt file throws
 * {@link SnapshotParseError} rather than being treated as empty.
 */
export declare function loadSnapshot(path: string, fs: SnapshotFs): Promise<VisibilityEnvelope>;
/**
 * List saved snapshot paths, sorted chronologically (oldest first). Returns an
 * empty list when no snapshots directory exists yet.
 */
export declare function listSnapshots(stateDir: string, fs: SnapshotFs): Promise<string[]>;