/**
 * ActionEvent — state machine for action lifecycle management.
 *
 * Manages an action through its phases (send_request → receive_response, etc.)
 * and steps (initial → parsed → handling → handled/failed).
 *
 * @module
 */
import type { ActionEventPhase, ActionSpecUnion } from './action_spec.js';
import type { JsonrpcRequest, JsonrpcResponseOrError, JsonrpcNotification } from '../http/jsonrpc.js';
import type { ActionEventEnvironment, ActionEventStep } from './action_event_types.js';
import { type ActionEventDataUnion } from './action_event_data.js';
export type ActionEventChangeObserver<TMethod extends string = string> = (new_data: ActionEventDataUnion<TMethod>, old_data: ActionEventDataUnion<TMethod>, event: ActionEvent<TMethod>) => void;
/**
 * Action event that manages the lifecycle of an action through its state machine.
 */
export declare class ActionEvent<TMethod extends string = string, TPhase extends ActionEventPhase = ActionEventPhase, TStep extends ActionEventStep = ActionEventStep> {
    #private;
    readonly environment: ActionEventEnvironment;
    /**
     * `method` narrows to `TMethod` so consumers passing a typed `TApi` to
     * `create_rpc_client` get `event.spec.method` typed as the union of
     * their API's method names rather than plain `string`. The runtime
     * value comes from `lookup_action_spec(method)` keyed off the Proxy
     * get trap, so the narrowing matches the dispatched method.
     */
    readonly spec: ActionSpecUnion & {
        method: TMethod;
    };
    get data(): ActionEventDataUnion<TMethod> & {
        phase: TPhase;
        step: TStep;
    };
    constructor(environment: ActionEventEnvironment, spec: ActionSpecUnion, data: ActionEventDataUnion<TMethod>);
    toJSON(): ActionEventDataUnion<TMethod>;
    /**
     * Subscribe a listener fired on every `data` transition.
     *
     * @param listener - called with `(new_data, old_data, event)` after each mutation
     * @returns unsubscribe function
     * @mutates this - adds `listener` to the internal observer set
     */
    observe(listener: ActionEventChangeObserver<TMethod>): () => void;
    /**
     * Replace the event's `data` and notify observers.
     *
     * @mutates this - sets `data` and fires every registered observer in insertion order
     */
    set_data(new_data: ActionEventDataUnion<TMethod>): void;
    /**
     * Parse input data according to the action's schema.
     *
     * @returns `this` for chaining with `handle_async` / `handle_sync`
     * @mutates this - transitions step from `initial` to `parsed` (or to
     *   `failed` / `receive_error` on validation or response error)
     * @throws Error if called from a step other than `initial`
     */
    parse(): this;
    /**
     * Execute the handler for the current phase.
     *
     * @mutates this - transitions step `parsed → handling → handled`, or to
     *   `failed` / `send_error` / `receive_error` on handler throw. No-op
     *   when already `failed`.
     * @throws Error if called from a step other than `parsed` (or `failed`,
     *   which no-ops). Handler-thrown `ThrownJsonrpcError` is caught and
     *   routed through error phases; other throws are wrapped as
     *   `internal_error`.
     */
    handle_async(): Promise<void>;
    /**
     * Execute handler synchronously (only for sync `local_call` actions).
     *
     * @mutates this - transitions step `parsed → handling → handled`, or to
     *   `failed` on handler throw. No-op when already `failed`.
     * @throws Error if the spec is not a sync `local_call`, or if called
     *   from a step other than `parsed` (or `failed`, which no-ops).
     */
    handle_sync(): void;
    /**
     * Transition to a new phase.
     *
     * @param phase - the next phase to transition into
     * @mutates this - replaces `data` with a fresh phase-initial record,
     *   carrying forward `request` / `response` / `error` / `output` as
     *   appropriate for the kind/phase pair
     * @throws Error if called from a step other than `handled` (or
     *   `failed`, which no-ops), or if the phase transition is illegal for
     *   the current phase
     */
    transition(phase: ActionEventPhase): void;
    is_complete(): boolean;
    update_progress(progress: unknown): void;
    set_request(request: JsonrpcRequest): void;
    set_response(response: JsonrpcResponseOrError): void;
    set_notification(notification: JsonrpcNotification): void;
}
/**
 * Create an action event from a spec and initial input.
 *
 * @throws Error if `initial_phase` is omitted and the executor cannot
 *   initiate the action (per `spec.initiator`)
 */
export declare const create_action_event: <TMethod extends string = string>(environment: ActionEventEnvironment, spec: ActionSpecUnion, input: unknown, initial_phase?: ActionEventPhase) => ActionEvent<TMethod>;
/**
 * Reconstruct an action event from serialized JSON data.
 *
 * @throws Error if the JSON's `method` field has no spec registered in `environment`
 */
export declare const create_action_event_from_json: <TMethod extends string = string>(json: ActionEventDataUnion<TMethod>, environment: ActionEventEnvironment) => ActionEvent<TMethod>;
export declare const parse_action_event: (raw_json: unknown, environment: ActionEventEnvironment) => ActionEvent;
//# sourceMappingURL=action_event.d.ts.map