/**
 * Headless Runtime
 *
 * Lightweight runtime for server-side execution, IoT devices, edge computing,
 * and testing scenarios. No rendering, audio, or input - just state, events,
 * and trait execution.
 *
 * Features:
 * - State management with reactive updates
 * - Event system for pub/sub
 * - Trait system for behavior composition
 * - Lifecycle hooks (on_mount, on_update, on_unmount)
 * - MQTT/WebSocket protocol support
 * - Memory-efficient (<50MB footprint)
 * - Fast startup (<500ms)
 *
 * @version 1.0.0
 */
import type { HSPlusAST, HSPlusNode } from '@holoscript/core';
import { ReactiveState } from '@holoscript/core';
import type { HostCapabilities } from '@holoscript/core';
import type { RuntimeProfile } from './RuntimeProfile';
type LifecycleHandler = (...args: unknown[]) => void;
export interface HeadlessNodeInstance {
    node: HSPlusNode;
    lifecycleHandlers: Map<string, LifecycleHandler[]>;
    children: HeadlessNodeInstance[];
    parent: HeadlessNodeInstance | null;
    destroyed: boolean;
    data?: Record<string, unknown>;
}
export interface HeadlessSceneObjectReceipt {
    id: string;
    type: string;
    name?: string;
    template?: string | null;
    parentId: string | null;
    path: string[];
    groupPath: string[];
    traits: string[];
    properties: Record<string, unknown>;
    transform: {
        position: unknown;
        rotation: unknown;
        scale: unknown;
    };
    physics: {
        collidable: boolean;
        kinematic: unknown;
        massKg: unknown;
    };
}
export interface HeadlessRuntimeSceneReceipt {
    schema: 'holoscript-headless-scene-receipt-v1';
    source: 'HeadlessRuntime';
    rootId: string | null;
    objectCount: number;
    objects: HeadlessSceneObjectReceipt[];
}
/**
 * Handler function for BT action dispatch via `runtime.registerAction()`.
 * Called when the BehaviorTree's native action bridge emits `action:${name}`.
 * Return true (success) or false (failure). Async handlers return a Promise.
 */
export type ActionHandler = (params: Record<string, unknown>, blackboard: Record<string, unknown>, context: {
    emit: (event: string, payload?: unknown) => void;
    hostCapabilities?: HostCapabilities;
}) => Promise<boolean> | boolean;
export interface HeadlessRuntimeOptions {
    /** Runtime profile (defaults to HEADLESS_PROFILE) */
    profile?: RuntimeProfile;
    /** External state providers */
    stateProviders?: Map<string, () => unknown>;
    /** Update tick rate in Hz (default: 10) */
    tickRate?: number;
    /** Enable debug logging */
    debug?: boolean;
    /** Max instances limit (default: 1000) */
    maxInstances?: number;
    /** Custom builtins to inject */
    builtins?: Record<string, unknown>;
    /** Action dispatcher for BehaviorTreeTrait — maps BT action names to external handlers.
     *  Return true (success), false (failure), or 'running' (async in progress).
     *  The blackboard parameter is the BT's shared state for updating conditions. */
    executeAction?: (owner: unknown, actionName: string, params: Record<string, unknown>, blackboard?: Record<string, unknown>) => boolean | 'running';
    /** Optional capability adapter for host operations used by traits such as shell/file_system. */
    hostCapabilities?: HostCapabilities;
}
export interface HeadlessRuntimeStats {
    /** Number of active node instances */
    instanceCount: number;
    /** Highest active node count observed during this run */
    peakInstanceCount: number;
    /** Memory usage estimate in bytes */
    memoryEstimate: number;
    /** Total updates processed */
    updateCount: number;
    /** Total events emitted */
    eventCount: number;
    /** Uptime in milliseconds */
    uptime: number;
    /** Average tick duration in ms */
    avgTickDuration: number;
}
export declare class HeadlessRuntime {
    private ast;
    private profile;
    private options;
    state: ReactiveState<any>;
    private evaluator;
    private rootInstance;
    private eventHandlers;
    private updateInterval;
    private startTime;
    private lastTickTime;
    private tickDurations;
    private stats;
    private running;
    private builtins;
    private actionRegistry;
    private _routingEvent;
    private lastSceneReceipt;
    constructor(ast: HSPlusAST, options?: HeadlessRuntimeOptions);
    private initializeState;
    private createBuiltins;
    /**
     * Start the headless runtime
     */
    start(): void;
    /**
     * Stop the headless runtime
     */
    stop(): void;
    /**
     * Check if runtime is running
     */
    isRunning(): boolean;
    private tick;
    private updateStateProviders;
    private updateInstance;
    private instantiateNode;
    private processDirectives;
    private registerLifecycleHandler;
    private callLifecycle;
    private createTraitContext;
    /**
     * Route an event to trait onEvent() handlers on all node instances.
     * This enables @shell, @file_system, @llm_agent and other traits to
     * receive events in headless mode (previously only onUpdate/onAttach fired).
     */
    private routeEventToTraits;
    private destroyInstance;
    /**
     * Get current state snapshot
     */
    getState(): Record<string, unknown>;
    /**
     * Update state
     */
    setState(updates: Partial<Record<string, unknown>>): void;
    /**
     * Get a state value
     */
    get<K extends string>(key: K): unknown;
    /**
     * Set a state value
     */
    set<K extends string>(key: K, value: unknown): void;
    /**
     * Emit an event
     */
    emit(event: string, payload?: unknown): void;
    /**
     * Register a named action handler for BehaviorTree's native action bridge.
     * When a BT action node emits `action:${name}`, this handler is called
     * and the result is sent back via `action:result`.
     */
    registerAction(name: string, handler: ActionHandler): void;
    /**
     * Subscribe to an event
     */
    on(event: string, handler: (payload: unknown) => void): () => void;
    /**
     * Subscribe to an event (fires once)
     */
    once(event: string, handler: (payload: unknown) => void): () => void;
    /**
     * Get runtime statistics
     */
    getStats(): HeadlessRuntimeStats;
    /**
     * Get runtime profile
     */
    getProfile(): RuntimeProfile;
    /**
     * Deterministic scene object receipt for non-rendered replay/audit tools.
     *
     * The runtime keeps the last live receipt so callers can inspect object
     * state after stop() has torn down active instances.
     */
    getSceneReceipt(): HeadlessRuntimeSceneReceipt;
    getSceneObjects(): HeadlessSceneObjectReceipt[];
    /**
     * Find a node by ID
     */
    findNode(id: string): HSPlusNode | null;
    /**
     * Execute a manual update tick
     */
    manualTick(delta?: number): void;
    private buildSceneReceipt;
    private describeSceneObject;
    private nodeId;
    private recordOrEmpty;
    private estimateMemory;
    private log;
}
/**
 * Create a new headless runtime instance
 */
export declare function createHeadlessRuntime(ast: HSPlusAST, options?: HeadlessRuntimeOptions): HeadlessRuntime;
export default HeadlessRuntime;
//# sourceMappingURL=HeadlessRuntime.d.ts.map