/**
 * VM Bridge
 *
 * Bridges the HoloVM (spatial scene execution at 60fps) with the uAAL VM
 * (cognitive agent cycles via the 7-phase protocol).
 *
 * Key concepts:
 *   - SceneSnapshot: serializable view of the ECS world
 *   - AgentAction: typed mutation the agent wants to apply to the scene
 *   - SpatialCognitiveAgent: the core bridge — perceive → decide → mutate
 *   - registerSpatialHandlers: wires uAAL spatial opcodes to HoloVM
 *
 * @packageDocumentation
 */
import type { HoloVM, ECSWorld, TransformComponent, Vec3 } from '../vm/executor';
import type { UAALVirtualMachine, UAALBytecode, UAALExecutionLog } from '@holoscript/uaal';
import { type N4TypedMoveAction } from '@holoscript/core/world-model';
export interface EntitySnapshot {
    id: number;
    name: string;
    parentId: number;
    childIds: number[];
    traits: number[];
    transform?: TransformComponent;
    geometry?: {
        type: number;
        params: Record<string, number>;
    };
    material?: {
        color: number;
        metalness: number;
        roughness: number;
        opacity: number;
    };
    rigidBody?: {
        mass: number;
        bodyType: number;
        velocity: Vec3;
    };
}
export interface SceneSnapshot {
    entityCount: number;
    entities: EntitySnapshot[];
    timestamp: number;
}
/**
 * Capture a serializable snapshot of the ECS world
 */
export declare function captureSceneSnapshot(world: ECSWorld): SceneSnapshot;
export type AgentAction = {
    type: 'spawn';
    name: string;
    position?: Vec3;
    geometryType?: number;
} | {
    type: 'despawn';
    entityId: number;
} | {
    type: 'move';
    entityId: number;
    position: Vec3;
} | {
    type: 'setComponent';
    entityId: number;
    componentType: number;
    data: unknown;
} | {
    type: 'applyTrait';
    entityId: number;
    traitId: number;
} | {
    type: 'removeTrait';
    entityId: number;
    traitId: number;
};
/**
 * Apply a batch of agent actions to the ECS world
 */
export declare function applyActions(world: ECSWorld, actions: AgentAction[]): number[];
export interface BridgeConfig {
    /** Cognitive cycle frequency in Hz (default: 2 — runs every 500ms) */
    cognitiveHz?: number;
    /** Enable logging */
    enableLogging?: boolean;
    /** Max actions per cognitive tick */
    maxActionsPerTick?: number;
    /**
     * Pre-compiled uAAL program to run each cognitive cycle. When provided,
     * {@link SpatialCognitiveAgent.decide} executes this bytecode instead of
     * the default 7-phase `buildFullCycle(task)`. This is the channel a
     * marketplace-acquired agent template flows through: the acquired uAAL
     * program drives the agent's behavior instead of a generic observe-and-act
     * cycle.
     */
    program?: UAALBytecode;
}
export interface CognitiveTickResult {
    perceived: boolean;
    decided: boolean;
    actionsApplied: number;
    sceneSnapshot?: SceneSnapshot;
    cycleResult?: unknown;
}
export interface N4RoundTripCustody {
    readonly sourceDigest: string;
    readonly graphDigest: string;
    readonly modelDigest: string;
}
export interface N4OwnedRuntimeRoundTrip {
    readonly kind: 'N4OwnedRuntimeRoundTrip';
    readonly actionDigest: string;
    readonly entityId: number;
    readonly entityName: string;
    readonly before: Vec3;
    readonly after: Vec3;
    readonly uaalProgram: UAALBytecode;
    readonly uaalLog: UAALExecutionLog;
    readonly uaalTaskStatus: string;
    readonly mutationApplied: boolean;
}
export declare class SpatialCognitiveAgent {
    private world;
    private cognitiveVM;
    private compiler;
    private config;
    private program?;
    private lastCognitiveTickMs;
    private cognitiveIntervalMs;
    private pendingActions;
    private lastSnapshot;
    private tickCount;
    constructor(world: ECSWorld, cognitiveVM: UAALVirtualMachine, config?: BridgeConfig);
    /**
     * Snapshot the ECS world for agent perception
     */
    perceive(): SceneSnapshot;
    /**
     * Run a cognitive cycle with the current scene as context.
     *
     * If a pre-compiled {@link BridgeConfig.program} was supplied (e.g. a
     * marketplace-acquired uAAL template), that bytecode is executed; otherwise
     * the default 7-phase `buildFullCycle(task)` runs.
     */
    decide(task: string): Promise<unknown>;
    /**
     * Replace the agent's standing program at runtime. Pass `undefined` to fall
     * back to the default 7-phase cycle.
     */
    setProgram(program: UAALBytecode | undefined): void;
    getProgram(): UAALBytecode | undefined;
    /**
     * Apply agent actions to the ECS world
     */
    mutate(actions: AgentAction[]): number[];
    /**
     * Queue actions for the next cognitive tick
     */
    queueAction(action: AgentAction): void;
    /**
     * Queue multiple actions
     */
    queueActions(actions: AgentAction[]): void;
    /**
     * Main tick — called each frame. Runs cognitive cycle at configured frequency.
     * Returns whether a cognitive tick was performed.
     */
    tick(currentTimeMs: number): Promise<CognitiveTickResult>;
    getLastSnapshot(): SceneSnapshot | null;
    getPendingActionCount(): number;
    getTickCount(): number;
}
/**
 * Execute one compiler-bound N4 typed move through the real uAAL VM and the
 * existing HoloVM ECS mutation bridge.
 *
 * Security is lexical/structural: this adapter accepts only the closed `move`
 * action and the three compiler-declared residual targets. It exposes no
 * arbitrary opcode, component, host callback, filesystem, or process concept
 * to the learned processor.
 */
export declare function executeN4TypedMoveRoundTrip(holoVM: HoloVM, cognitiveVM: UAALVirtualMachine, action: N4TypedMoveAction, expected: N4RoundTripCustody): Promise<N4OwnedRuntimeRoundTrip>;
//# sourceMappingURL=bridge.d.ts.map