/**
 * AsyncTraitExecutor — HoloScript+ First-Class Async Handlers
 *
 * Wraps trait lifecycle calls (onAttach, onUpdate, onEvent, onDetach) so
 * they can return Promises. Tracks per-node-per-handler async state and
 * emits lifecycle events back through the node's event bus.
 *
 * Design:
 *  - Zero-overhead for sync handlers (fast-path check).
 *  - Per-node concurrency cap (maxConcurrent, default 3).
 *  - FIFO queue for excess concurrent calls.
 *  - Emits: on_async_start, on_async_done, on_async_error.
 *
 * @module AsyncTraitExecutor
 * @version 1.0.0
 */
export type AsyncStatus = 'idle' | 'loading' | 'error' | 'done';
export interface AsyncHandlerState {
    status: AsyncStatus;
    error?: Error;
    /** Wall-clock ms when the last op started */
    startedAt?: number;
    /** Wall-clock ms when the last op finished */
    finishedAt?: number;
}
export interface AsyncTraitExecutorOptions {
    /** Maximum concurrent async handlers per node. Default: 3 */
    maxConcurrent?: number;
    /**
     * Function to emit events back to the node.
     * Signature mirrors the EventBus.emit() / node.emit() API.
     */
    emit?: (event: string, payload?: unknown) => void;
}
export interface AsyncExecuteResult {
    /** Resolved value (if handler returned a Promise) */
    value?: unknown;
    /** Status after execution */
    status: AsyncStatus;
    /** Error if status === 'error' */
    error?: Error;
}
export declare class AsyncTraitExecutor {
    /**
     * By handler key: current in-flight count.
     * Key format: `${nodeId}:${handlerName}`
     */
    private inflightCounts;
    /**
     * Pending queue when maxConcurrent is reached.
     * Key format: `${nodeId}:${handlerName}`
     */
    private queues;
    /**
     * Latest state per handler key.
     */
    private states;
    private readonly maxConcurrent;
    private readonly emit;
    constructor(options?: AsyncTraitExecutorOptions);
    /**
     * Execute a (potentially async) trait handler function.
     *
     * - If the handler returns a non-Promise, it short-circuits (no state change).
     * - If the handler returns a Promise, it tracks loading state and emits events.
     * - Excess concurrent calls are queued and run FIFO.
     */
    execute(nodeId: string, handlerName: string, fn: (...args: unknown[]) => unknown, args?: unknown[]): Promise<AsyncExecuteResult>;
    /**
     * Get latest async state for a specific handler.
     */
    getState(nodeId: string, handlerName: string): AsyncHandlerState;
    /**
     * Get all handler states for a given node.
     */
    getNodeStates(nodeId: string): Map<string, AsyncHandlerState>;
    /**
     * True if any handler for the node is currently loading.
     */
    isLoading(nodeId: string): boolean;
    /**
     * Reset all state (useful in tests or on scene reload).
     */
    reset(): void;
    private setState;
}
//# sourceMappingURL=AsyncTraitExecutor.d.ts.map