/** Structural, DOM-free storage backend: the browser `localStorage` satisfies it, as does a test stub or `null`. The one storage seam core primitives target so persistence code never needs the DOM `Storage` lib. */
export interface KeyValueStorage {
    getItem(key: string): string | null;
    setItem(key: string, value: string): void;
    removeItem(key: string): void;
}
/** The ambient `localStorage` when available, otherwise `null`. An optional observer receives denied getter errors; it may rethrow to reject fallback. Never references the DOM `Storage` type, so it is safe in core. */
export declare function defaultKeyValueStorage(onError?: (error: unknown) => void): KeyValueStorage | null;
/** A failed storage operation, retaining the backend's original error and affected key. */
export interface KeyValueStorageFailure {
    operation: "read" | "write" | "remove";
    key: string;
    error: unknown;
}
/** Fallback keeps session state after a failed operation; throw exposes failure and preserves the previous cell value. Observers must not throw. */
export interface KeyValueStorageErrorPolicy {
    errorMode?: "fallback" | "throw";
    onError?: (failure: KeyValueStorageFailure) => void;
}
/** @internal */
export declare function reportStorageFailure(policy: KeyValueStorageErrorPolicy, failure: KeyValueStorageFailure): void;
/** A single persisted, mutable cell: read the current value, overwrite it, or read-modify-write with {@link KeyValueStore.update}. Unlike a record book it has no monotonic guard — the value goes wherever you set it. */
export interface KeyValueStore<T> {
    get(): T;
    set(value: T): void;
    update(mutate: (previous: T) => T): T;
    clear(): void;
}
/** Config for {@link createKeyValueStore}: the storage `key`, the `initial` value used before anything is saved, an optional `storage` backend (defaults to `localStorage`, pass `null` for memory-only), and optional custom `serialize`/`deserialize` (default JSON). */
export interface KeyValueStoreConfig<T> extends KeyValueStorageErrorPolicy {
    readonly key: string;
    readonly initial: T;
    readonly storage?: KeyValueStorage | null;
    readonly serialize?: (value: T) => string;
    readonly deserialize?: (raw: string) => T;
}
/** A mutable local save cell through {@link KeyValueStorage}. Default fallback keeps session state on failure; `errorMode: "throw"` exposes failed reads/writes/removals through the original error. `storage: null` deliberately uses memory only. */
export declare function createKeyValueStore<T>(config: KeyValueStoreConfig<T>): KeyValueStore<T>;