import type { ShoppingEnvelope } from './envelope.js';
/**
 * The minimal fs surface this module needs, injectable for tests. Structurally
 * identical to `SnapshotFs` in `core/output` - declared here rather than
 * imported so `core/shopping` and `core/output` stay one-directional (output
 * renders shopping, shopping never reaches back into output).
 */
export interface ShoppingFs {
    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 saved shopping run is present but not a valid envelope. */
export declare class ShoppingRunParseError extends Error {
    readonly path: string;
    readonly cause: unknown;
    constructor(path: string, cause: unknown);
}
/** The shopping-runs directory inside a state directory. */
export declare function shoppingDir(stateDir: string): string;
/**
 * Filename for a run taken at `generatedAt`. Colons are replaced with `-`
 * (invalid on Windows); the rest of the ISO string stays intact so names sort
 * chronologically as plain strings.
 */
export declare function shoppingFileName(generatedAt: string): string;
/** Node fs.promises adapter for production use. */
export declare function nodeShoppingFs(): ShoppingFs;
/** Persist a shopping envelope as pretty JSON, creating the directory. */
export declare function saveShoppingRun(envelope: ShoppingEnvelope, stateDir: string, fs: ShoppingFs): Promise<string>;
/** Load a saved shopping run; a corrupt file throws rather than reading empty. */
export declare function loadShoppingRun(path: string, fs: ShoppingFs): Promise<ShoppingEnvelope>;
/** List saved run paths, oldest first. Empty when nothing has been saved. */
export declare function listShoppingRuns(stateDir: string, fs: ShoppingFs): Promise<string[]>;