import type { CacheMode, CacheOptions, CacheSource, CacheStore } from "./types.js";
/** Lives for the lifetime of the process. Useful in tests, and for re-runs. */
export declare function memoryStore(): CacheStore;
/**
 * One JSON file, holding every slot that points at it. Several phases may
 * share a path safely, and concurrent writes to one path are serialised.
 *
 * A missing, unreadable or malformed file all mean the same thing — no cache
 * yet — so deleting the file is always a valid way to start over. Values must
 * survive `JSON.stringify`; anything that does not (a `Date`, a class
 * instance) comes back as its JSON shape.
 */
export declare function fileStore(filePath: string): CacheStore;
/** `cache: someStore` is shorthand for `cache: { store: someStore }`. */
export declare function normalizeCache(source: CacheSource | undefined): CacheOptions | undefined;
export type CacheLookup = {
    hit: true;
    value: unknown;
    ageMs: number;
} | {
    hit: false;
};
/**
 * Read an entry and put it through every gate. A failure at any gate is a
 * miss — the work runs and the entry is replaced — never an error.
 */
export declare function readCache(cache: CacheOptions, slot: string, input: unknown, ctx: unknown, mode: CacheMode, flags: unknown): Promise<CacheLookup>;
/** Only ever called after the phase or step has fully succeeded. */
export declare function writeCache(cache: CacheOptions, slot: string, value: unknown, mode: CacheMode): Promise<void>;
/** Identifies a phase's entry. Steps hang off their phase to avoid collisions. */
export declare const phaseSlot: (phase: string) => string;
export declare const stepSlot: (phase: string, step: string) => string;
/**
 * Wrap a value read back from a store so that touching a field it does not
 * have throws {@link CacheShapeError} instead of yielding `undefined`.
 *
 * Only reads are trapped. Assigning a new property is how you'd legitimately
 * patch an entry before writing it back, so it is left alone — the lie is
 * always on the read side, where the type promised something the JSON lacks.
 *
 * Absent array indices pass through too: `orders[9]` on a short list is
 * ordinary JavaScript, not a shape mismatch.
 */
export declare function guardShape<T>(value: T, slot: string, path?: string): T;
/** Which store backs each slot, and whether that slot validates on read. */
export interface SlotBinding {
    store: CacheStore;
    schema: boolean;
}
/**
 * Build the `cache` handle a handler sees. Slots it does not know about are
 * already unreachable through the types; at runtime they throw rather than
 * silently doing nothing, which is what a plain `store.clear("typo")` does.
 */
export declare function createCacheHandle(slots: Map<string, SlotBinding>): {
    read(slot: string, options?: {
        raw?: boolean;
    }): Promise<unknown>;
    write(slot: string, value: unknown, options?: {
        keepAge?: boolean;
    }): Promise<void>;
    clear(slot: string): Promise<void>;
    ageOf(slot: string): Promise<number | undefined>;
};
//# sourceMappingURL=cache.d.ts.map