import type { Storage } from '../storage/interface.ts';
import { OBSERVABLE_SYMBOL, type AtomicStateCommitResult, type AtomicStateEvent, type AtomicStateObserver, type AtomicStateOptions, type AtomicStateScope, type AtomicStateSnapshot, type AtomicStateSubscription } from './atomic-state-events.ts';
import { WeftError } from './weft-error.ts';
export { AtomicStateChangeEvent, AtomicStateConflictEvent, AtomicStateExhaustedEvent, OBSERVABLE_SYMBOL, } from './atomic-state-events.ts';
export type { AtomicStateCommitResult, AtomicStateEvent, AtomicStateObserver, AtomicStateOptions, AtomicStateScope, AtomicStateSnapshot, AtomicStateSubscription, SleepFunction, } from './atomic-state-events.ts';
/**
 * Thrown by {@link AtomicState.update} when the CAS (compare-and-swap) loop
 * exhausts its retry budget without successfully committing.
 *
 * @example
 * ```ts
 * import { AtomicState, AtomicStateConflictError } from '@lostgradient/weft';
 * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
 *
 * const storage = new MemoryStorage();
 * const state = new AtomicState<number>(storage, 'state:workflow-scope:default:counter', {
 *   initial: 0,
 *   maxRetries: 3,
 * });
 * try {
 *   await state.increment();
 * } catch (error) {
 *   if (error instanceof AtomicStateConflictError) {
 *     console.error('conflict on', error.stateKey, 'after', error.attempts, 'attempts');
 *   }
 * }
 * ```
 */
export declare class AtomicStateConflictError extends WeftError<'AtomicStateConflictError'> {
    readonly stateKey: string;
    readonly attempts: number;
    constructor(stateKey: string, attempts: number);
}
export declare function atomicStateDataKey(scope: AtomicStateScope, key: string): string;
export declare function atomicStateVersionKey(dataKey: string): string;
export declare function readAtomicStateSnapshot<T>(storage: Storage, dataKey: string, options?: Pick<AtomicStateOptions<T>, 'initial'>): Promise<AtomicStateSnapshot<T>>;
export declare function commitAtomicStateValue<T>(storage: Storage, dataKey: string, expectedVersion: number, value: T): Promise<AtomicStateCommitResult<T>>;
export declare function commitAtomicStateDelete(storage: Storage, dataKey: string, expectedVersion: number): Promise<AtomicStateCommitResult<never>>;
/**
 * Storage-backed compare-and-swap state slot. `AtomicState` is scoped by the
 * storage key supplied to the constructor; use `engine.state.*` and
 * `ctx.state.*` for the built-in execution and workflow scopes.
 *
 * @example
 * ```ts
 * import { AtomicState } from '@lostgradient/weft';
 * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
 *
 * const storage = new MemoryStorage();
 * const counter = new AtomicState<number>(storage, 'state:workflow-scope:default:count', { initial: 0 });
 * await counter.increment();
 * console.log(await counter.get()); // 1
 * ```
 */
export declare class AtomicState<T> extends EventTarget {
    #private;
    constructor(storage: Storage, dataKey: string, options?: AtomicStateOptions<T>);
    /** Read the current value. */
    get(): Promise<T | undefined>;
    /** Update the state with optimistic concurrency and automatic retry. */
    update(updater: (current: T | undefined) => T): Promise<T>;
    /** Replace the state value. */
    set(value: T): Promise<T>;
    /**
     * Delete the state value while still advancing the version tombstone so
     * concurrent writers cannot silently overwrite a delete.
     */
    delete(): Promise<void>;
    increment(this: AtomicState<number>, amount?: number): Promise<number>;
    decrement(this: AtomicState<number>, amount?: number): Promise<number>;
    merge<TObject extends Record<string, unknown>>(this: AtomicState<TObject>, patch: Partial<TObject>): Promise<TObject>;
    append<TItem>(this: AtomicState<TItem[]>, item: TItem): Promise<TItem[]>;
    removeFirst<TItem>(this: AtomicState<TItem[]>): Promise<TItem | undefined>;
    removeLast<TItem>(this: AtomicState<TItem[]>): Promise<TItem | undefined>;
    [OBSERVABLE_SYMBOL](): {
        subscribe: (observer: AtomicStateObserver<T>) => AtomicStateSubscription;
    };
    [Symbol.asyncIterator](): AsyncIterator<AtomicStateEvent<T>>;
}