@mmapp/player-core 0.1.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,1436 @@
+/**
+ * Expression Engine Types
+ *
+ * Defines the contract for expression evaluation across all player contexts.
+ * See player-specification.md §2.3 for full specification.
+ */
+/** Result of evaluating an expression */
+interface ExpressionResult<T = unknown> {
+    value: T;
+    status: 'ok' | 'error' | 'fallback';
+    error?: string;
+    diagnostics?: ExpressionDiagnostics;
+}
+/** Diagnostic information for debugging expressions */
+interface ExpressionDiagnostics {
+    expression: string;
+    duration_ms: number;
+    resolved_paths: string[];
+    unresolved_paths: string[];
+}
+/** Failure policy determines behavior when an expression fails */
+interface FailurePolicy {
+    on_error: 'return_fallback' | 'throw' | 'log_and_skip';
+    fallback_value: unknown;
+    log_level: 'silent' | 'warn' | 'error';
+}
+/** Expression context for evaluation */
+interface ExpressionContext {
+    [key: string]: unknown;
+}
+/** A registered function available in expressions */
+interface ExpressionFunction {
+    name: string;
+    fn: (...args: unknown[]) => unknown;
+    arity?: number;
+    description?: string;
+}
+/** Configuration for createEvaluator factory */
+interface EvaluatorConfig {
+    functions: ExpressionFunction[];
+    failurePolicy: FailurePolicy;
+    maxDepth?: number;
+    maxOperations?: number;
+}
+/** The evaluator interface returned by createEvaluator */
+interface Evaluator {
+    evaluate<T = unknown>(expression: string, context: ExpressionContext): ExpressionResult<T>;
+    evaluateTemplate(template: string, context: ExpressionContext): ExpressionResult<string>;
+    validate(expression: string): {
+        valid: boolean;
+        errors: string[];
+    };
+}
+/** Pre-defined failure policy contexts for the Web Player */
+type FailurePolicyContext = 'VIEW_BINDING' | 'EVENT_REACTION' | 'DURING_ACTION' | 'CONDITIONAL_VISIBILITY';
+
+/**
+ * Core Expression Functions — 31 functions across 6 categories.
+ *
+ * These are the standard functions available in every player context.
+ * Platform-specific functions ($domain, $fe_ref, etc.) are registered
+ * separately by the host environment.
+ */
+
+declare const CORE_FUNCTIONS: ExpressionFunction[];
+/** Lookup map for O(1) function resolution */
+declare function buildFunctionMap(functions: ExpressionFunction[]): Map<string, ExpressionFunction['fn']>;
+
+/**
+ * Expression Evaluator — createEvaluator factory and evaluation engine.
+ *
+ * Parses and evaluates expressions with a safe recursive descent parser.
+ * NO dynamic code compilation (no new Function(), no eval(), no with()).
+ *
+ * Supported syntax:
+ * - Path resolution: `state_data.title`, `$instance.fields.name`
+ * - Function calls: `add(1, 2)`, `if(eq(x, 1), 'yes', 'no')`
+ * - Template interpolation: `"Hello {{name}}, you have {{count}} items"`
+ * - Ternary expressions: `condition ? 'yes' : 'no'`
+ * - Operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `&&`, `||`, `!`
+ * - Literals: strings, numbers, booleans, null
+ *
+ * Grammar:
+ *   expression  → ternary
+ *   ternary     → logicalOr ('?' expression ':' expression)?
+ *   logicalOr   → logicalAnd ('||' logicalAnd)*
+ *   logicalAnd  → equality ('&&' equality)*
+ *   equality    → comparison (('=='|'!=') comparison)*
+ *   comparison  → unary (('>'|'<'|'>='|'<=') unary)*
+ *   unary       → ('!' unary) | call
+ *   call        → primary ('(' args? ')')? ('.' IDENT ('(' args? ')')?)*
+ *   primary     → NUMBER | STRING | BOOL | NULL | IDENT | '(' expression ')'
+ */
+
+/**
+ * WEB_FAILURE_POLICIES — predefined failure policies for Web Player contexts.
+ */
+declare const WEB_FAILURE_POLICIES: Record<string, FailurePolicy>;
+/**
+ * createEvaluator — factory function that builds a configured evaluator.
+ *
+ * @param config - Function registry and failure policy
+ * @returns Evaluator instance with evaluate, evaluateTemplate, and validate methods
+ */
+declare function createEvaluator(config: EvaluatorConfig): Evaluator;
+/** Clear parsed AST cache (for testing) */
+declare function clearExpressionCache(): void;
+
+/**
+ * State Machine Types — browser-side workflow interpretation.
+ *
+ * Mirrors the backend PureWorkflowDefinition/Instance structure
+ * but stripped to only what the browser engine needs.
+ */
+
+/** State type in the workflow */
+type StateType = 'START' | 'REGULAR' | 'END' | 'CANCELLED';
+/** Action that runs during on_event handling */
+interface PlayerAction {
+    type: string;
+    config: Record<string, unknown>;
+    condition?: string;
+}
+/** On-event subscription for browser-side processing */
+interface PlayerOnEventSubscription {
+    match: string;
+    conditions?: string[];
+    actions: PlayerAction[];
+}
+/** State definition for the browser engine */
+interface PlayerStateDefinition {
+    name: string;
+    type: StateType;
+    on_enter?: PlayerAction[];
+    on_exit?: PlayerAction[];
+    on_event?: PlayerOnEventSubscription[];
+}
+/** Transition definition */
+interface PlayerTransitionDefinition {
+    name: string;
+    from: string[];
+    to: string;
+    conditions?: string[];
+    auto?: boolean;
+    actions?: PlayerAction[];
+}
+/** Workflow definition for the browser engine */
+interface PlayerWorkflowDefinition {
+    id: string;
+    slug: string;
+    states: PlayerStateDefinition[];
+    transitions: PlayerTransitionDefinition[];
+}
+/** Runtime instance state */
+interface PlayerInstance {
+    definition: PlayerWorkflowDefinition;
+    current_state: string;
+    state_data: Record<string, unknown>;
+    memory: Record<string, unknown>;
+    status: 'ACTIVE' | 'COMPLETED' | 'CANCELLED';
+}
+/** Transition result from the state machine */
+interface TransitionResult {
+    success: boolean;
+    from_state: string;
+    to_state: string;
+    actions_executed: PlayerAction[];
+    error?: string;
+}
+/** State machine event listener */
+type StateMachineListener = (event: StateMachineEvent) => void;
+/** Events emitted by the state machine */
+interface StateMachineEvent {
+    type: 'transition' | 'state_enter' | 'state_exit' | 'action_executed' | 'error';
+    instance_id: string;
+    from_state?: string;
+    to_state?: string;
+    action?: PlayerAction;
+    error?: string;
+}
+/** Action handler registered with the state machine */
+type ActionHandler = (action: PlayerAction, context: ExpressionContext) => void | Promise<void>;
+
+/**
+ * State Machine Interpreter — browser-side workflow engine.
+ *
+ * Interprets PlayerWorkflowDefinition instances with:
+ * - State transitions (manual + auto)
+ * - on_enter / on_exit action execution
+ * - Condition evaluation via expression engine
+ * - Listener-based event emission
+ * - Auto-transition drain loop with depth limit
+ */
+
+interface StateMachineConfig {
+    evaluator: Evaluator;
+    actionHandlers?: Map<string, ActionHandler>;
+}
+declare class StateMachine {
+    private readonly evaluator;
+    private readonly actionHandlers;
+    private readonly listeners;
+    private instance;
+    constructor(definition: PlayerWorkflowDefinition, initialData: Record<string, unknown> | undefined, config: StateMachineConfig);
+    /** Get the current instance snapshot (immutable copy) */
+    getSnapshot(): Readonly<PlayerInstance>;
+    /** Get current state name */
+    get currentState(): string;
+    /** Get current state_data */
+    get stateData(): Record<string, unknown>;
+    /** Get current status */
+    get status(): string;
+    /** Subscribe to state machine events */
+    on(listener: StateMachineListener): () => void;
+    /** Register an action handler */
+    registerAction(type: string, handler: ActionHandler): void;
+    /** Execute a named transition */
+    transition(transitionName: string, data?: Record<string, unknown>): Promise<TransitionResult>;
+    /** Update state_data directly (for on_event set_field actions) */
+    setField(field: string, value: unknown): void;
+    /** Update memory */
+    setMemory(key: string, value: unknown): void;
+    /** Get available transitions from the current state */
+    getAvailableTransitions(): PlayerTransitionDefinition[];
+    /** Get the current state definition */
+    getCurrentStateDefinition(): PlayerStateDefinition | undefined;
+    private executeTransition;
+    private drainAutoTransitions;
+    private findMatchingAutoTransition;
+    private executeActions;
+    private buildContext;
+    private emit;
+}
+
+/**
+ * Event System Types — browser-side on_event matching and dispatch.
+ */
+/** Subscription registered with the event bus */
+interface EventSubscription {
+    /** Glob-style pattern: "workflow.*:state_enter" or "*:*:completed" */
+    pattern: string;
+    /** Compiled regex for fast matching (derived from pattern) */
+    regex: RegExp;
+    /** Conditions evaluated before actions fire */
+    conditions?: string[];
+    /** Handler called when pattern matches and conditions pass */
+    handler: EventHandler;
+}
+/** Event payload passed to handlers */
+interface BusEvent {
+    topic: string;
+    payload: Record<string, unknown>;
+}
+/** Handler function for matched events */
+type EventHandler = (event: BusEvent) => void | Promise<void>;
+/** Unsubscribe function returned by subscribe */
+type Unsubscribe = () => void;
+
+/**
+ * Pattern Matcher — glob-style topic matching for on_event subscriptions.
+ *
+ * Supports:
+ * - Exact match: "workflow.order:state_enter"
+ * - Single-level wildcard (*): "workflow.*:state_enter" matches "workflow.order:state_enter"
+ * - Multi-level wildcard (**): "workflow.**" matches "workflow.order:state_enter:completed"
+ * - Colon-separated segments (like EventEmitter2)
+ *
+ * Compiled regex is cached per pattern for performance.
+ */
+/**
+ * Compile a glob pattern into a RegExp.
+ *
+ * Pattern rules:
+ * - Segments separated by `:` or `.`
+ * - `*` matches exactly one segment (any chars except `:` and `.`)
+ * - `**` matches zero or more segments (greedy)
+ * - Everything else is literal
+ */
+declare function compilePattern(pattern: string): RegExp;
+/**
+ * Test if a topic matches a compiled pattern.
+ */
+declare function matchTopic(pattern: RegExp, topic: string): boolean;
+/** Clear pattern cache (for testing) */
+declare function clearPatternCache(): void;
+
+/**
+ * Event Bus — browser-side pub/sub for on_event subscriptions.
+ *
+ * Lightweight event bus that matches published topics against
+ * glob-pattern subscriptions. Used by the player to wire
+ * on_event declarations to action handlers.
+ */
+
+declare class EventBus {
+    private subscriptions;
+    /**
+     * Subscribe to events matching a glob pattern.
+     * Returns an unsubscribe function.
+     */
+    subscribe(pattern: string, handler: EventHandler): Unsubscribe;
+    /**
+     * Publish an event. All matching subscriptions fire (async).
+     * Errors in handlers are caught and logged, never propagated.
+     */
+    publish(topic: string, payload?: Record<string, unknown>): Promise<void>;
+    /**
+     * Publish synchronously (fire-and-forget).
+     * Useful when you don't need to await handler completion.
+     */
+    emit(topic: string, payload?: Record<string, unknown>): void;
+    /** Get count of active subscriptions */
+    get size(): number;
+    /** Remove all subscriptions */
+    clear(): void;
+}
+
+/**
+ * Action System Types — handler registry and dispatch.
+ */
+
+/** Action definition from workflow state/transition */
+interface ActionDefinition {
+    type: string;
+    config: Record<string, unknown>;
+    condition?: string;
+}
+/** Registered action handler */
+type ActionHandlerFn = (config: Record<string, unknown>, context: ExpressionContext) => void | Promise<void>;
+/** Result of executing an action */
+interface ActionResult {
+    type: string;
+    success: boolean;
+    error?: string;
+}
+
+/**
+ * Action Dispatcher — executes action definitions against registered handlers.
+ *
+ * The dispatcher:
+ * - Maintains a registry of handler functions by action type
+ * - Evaluates per-action conditions before execution
+ * - Collects results (success/failure) for each action
+ * - Never throws — errors are captured in ActionResult
+ */
+
+declare class ActionDispatcher {
+    private readonly handlers;
+    /** Register a handler for an action type */
+    register(type: string, handler: ActionHandlerFn): void;
+    /** Unregister a handler */
+    unregister(type: string): void;
+    /** Check if a handler is registered for the given type */
+    has(type: string): boolean;
+    /**
+     * Execute a list of actions sequentially.
+     * Each action's condition is evaluated first (if present).
+     * Missing handlers are skipped with a warning.
+     */
+    execute(actions: ActionDefinition[], context: ExpressionContext, evaluator?: Evaluator): Promise<ActionResult[]>;
+    /** Get count of registered handlers */
+    get size(): number;
+    /** Remove all handlers */
+    clear(): void;
+}
+
+/**
+ * Testing OS Types — test declarations for the player-core engine.
+ *
+ * All types are JSON-serializable, enabling:
+ * - LLM generation of test programs
+ * - Database storage of test suites
+ * - Cross-platform execution (browser, iOS, Node)
+ */
+
+/** A node in the workflow state graph */
+interface StateNode {
+    name: string;
+    type: 'START' | 'REGULAR' | 'END' | 'CANCELLED';
+    reachable: boolean;
+    hasOnEvent: boolean;
+    hasOnEnter: boolean;
+    hasOnExit: boolean;
+}
+/** An edge (transition) in the workflow state graph */
+interface TransitionEdge {
+    name: string;
+    from: string;
+    to: string;
+    auto: boolean;
+    hasConditions: boolean;
+}
+/** A path through the state graph */
+interface GraphPath {
+    states: string[];
+    transitions: string[];
+}
+/** Summary statistics for a workflow definition */
+interface AnalysisSummary {
+    totalStates: number;
+    totalTransitions: number;
+    reachableStates: number;
+    terminalPaths: number;
+    cycles: number;
+    unreachableStates: number;
+    deadEndStates: number;
+}
+/** Full static analysis result for a workflow definition */
+interface AnalysisResult {
+    states: StateNode[];
+    edges: TransitionEdge[];
+    terminalPaths: GraphPath[];
+    cycles: GraphPath[];
+    unreachableStates: string[];
+    deadEndStates: string[];
+    summary: AnalysisSummary;
+}
+/** A complete test program with scenarios */
+interface TestProgram {
+    name: string;
+    definitionSlug: string;
+    definitions: Record<string, PlayerWorkflowDefinition>;
+    scenarios: TestScenario[];
+}
+/** Instance declaration for multi-instance scenarios */
+interface TestInstance {
+    id: string;
+    definitionSlug: string;
+    initialData?: Record<string, unknown>;
+}
+/** A test scenario with steps */
+interface TestScenario {
+    name: string;
+    tags?: string[];
+    instances?: TestInstance[];
+    connectEventBuses?: boolean;
+    steps: TestStep[];
+}
+/** A single test step: action + assertions */
+interface TestStep {
+    name: string;
+    instanceId?: string;
+    action: {
+        type: 'transition';
+        name: string;
+        data?: Record<string, unknown>;
+    } | {
+        type: 'set_field';
+        field: string;
+        value: unknown;
+    } | {
+        type: 'publish_event';
+        topic: string;
+        payload?: Record<string, unknown>;
+    } | {
+        type: 'assert_only';
+    };
+    assertions: TestAssertion[];
+}
+/** A single assertion to verify after an action */
+interface TestAssertion {
+    target: 'state' | 'status' | 'state_data' | 'available_transitions';
+    instanceId?: string;
+    path?: string;
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'truthy' | 'falsy';
+    expected: unknown;
+    label?: string;
+}
+/** Result of a single assertion */
+interface AssertionResult {
+    passed: boolean;
+    assertion: TestAssertion;
+    actual: unknown;
+    error?: string;
+}
+/** Result of a single step */
+interface StepResult {
+    stepName: string;
+    passed: boolean;
+    assertionResults: AssertionResult[];
+    durationMs: number;
+    error?: string;
+}
+/** Result of a single scenario */
+interface ScenarioResult {
+    scenarioName: string;
+    passed: boolean;
+    stepResults: StepResult[];
+    durationMs: number;
+    error?: string;
+}
+/** Result of a complete test program */
+interface TestProgramResult {
+    passed: boolean;
+    scenarioResults: ScenarioResult[];
+    durationMs: number;
+    analysis?: AnalysisResult;
+}
+/** Configuration for the in-process test runner */
+interface TestRunnerConfig {
+    actionHandlers?: Record<string, ActionHandlerFn>;
+    onStepComplete?: (scenarioIdx: number, step: StepResult) => void;
+    onScenarioComplete?: (result: ScenarioResult) => void;
+    abortSignal?: AbortSignal;
+}
+/** Snapshot of a server-side workflow instance */
+interface ApiInstanceSnapshot {
+    id: string;
+    currentState: string;
+    status: string;
+    stateData: Record<string, unknown>;
+    availableTransitions: string[];
+}
+/** Result of triggering a transition via API */
+interface ApiTransitionResult {
+    success: boolean;
+    fromState: string;
+    toState: string;
+    error?: string;
+}
+/**
+ * Adapter interface for the API test runner.
+ * Platform-agnostic — implement with fetch, axios, or any HTTP client.
+ * The server (NestJS backend) is the MM Player; the adapter is the client.
+ */
+interface ApiTestAdapter {
+    createInstance(params: {
+        definitionSlug: string;
+        stateData?: Record<string, unknown>;
+        entityType?: string;
+        entityId?: string;
+    }): Promise<ApiInstanceSnapshot>;
+    startInstance(instanceId: string): Promise<ApiInstanceSnapshot>;
+    deleteInstance(instanceId: string): Promise<void>;
+    triggerTransition(instanceId: string, transitionName: string, data?: Record<string, unknown>): Promise<ApiTransitionResult>;
+    updateStateData(instanceId: string, data: Record<string, unknown>): Promise<ApiInstanceSnapshot>;
+    getInstance(instanceId: string): Promise<ApiInstanceSnapshot>;
+}
+/** Configuration for the API test runner */
+interface ApiTestRunnerConfig {
+    adapter: ApiTestAdapter;
+    /** Delay (ms) after actions to let EventRouter settle cross-instance reactions. Default: 200 */
+    settleDelayMs?: number;
+    /** Delete instances after scenario completes. Default: true */
+    cleanupInstances?: boolean;
+    onStepComplete?: (scenarioIdx: number, step: StepResult) => void;
+    onScenarioComplete?: (result: ScenarioResult) => void;
+    /** Called when a real instance is created on the server */
+    onInstanceCreated?: (testInstanceId: string, serverId: string) => void;
+    abortSignal?: AbortSignal;
+}
+
+/**
+ * Graph Walker — static analysis of workflow definitions.
+ *
+ * Treats a PlayerWorkflowDefinition as a directed graph and provides:
+ * - analyzeDefinition(): Full graph analysis (states, edges, paths, cycles)
+ * - generateCoverageScenarios(): Auto-generate test scenarios from paths
+ *
+ * Pure functions, zero dependencies beyond player-core types.
+ */
+
+/**
+ * Analyze a workflow definition as a directed graph.
+ * Returns all states, edges, terminal paths, cycles, unreachable/dead-end states.
+ */
+declare function analyzeDefinition(def: PlayerWorkflowDefinition): AnalysisResult;
+/**
+ * Generate one test scenario per terminal path in the definition.
+ * Each step = one transition, asserting the landing state.
+ */
+declare function generateCoverageScenarios(def: PlayerWorkflowDefinition, analysis?: AnalysisResult): TestScenario[];
+
+/**
+ * Test Runner — executes test programs against the player-core engine.
+ *
+ * Runs test scenarios in-memory using StateMachine + EventBus.
+ * No database, no network, no UI — pure state machine execution.
+ *
+ * Exports:
+ * - runTestProgram(): Execute a full test program (all scenarios)
+ * - runScenario(): Execute a single scenario
+ */
+
+/**
+ * Execute a complete test program (all scenarios).
+ */
+declare function runTestProgram(program: TestProgram, config?: TestRunnerConfig): Promise<TestProgramResult>;
+/**
+ * Execute a single test scenario.
+ */
+declare function runScenario(scenario: TestScenario, definitions: Record<string, PlayerWorkflowDefinition>, config?: TestRunnerConfig): Promise<ScenarioResult>;
+
+/**
+ * Test Compiler — converts TestProgram → PlayerWorkflowDefinition.
+ *
+ * The test program IS a Blueprint. This compiler takes the ergonomic
+ * TestProgram format (scenarios, steps, assertions) and produces a
+ * standard PlayerWorkflowDefinition that any Player can execute.
+ *
+ * The compiled Blueprint uses test-specific action types (__test_*)
+ * in on_enter hooks. The Player executes these via registered action
+ * handlers — which are platform-specific (in-process, API, cross-platform).
+ *
+ * Structure of a compiled scenario Blueprint:
+ *   __setup (START) → on_enter creates instances
+ *   __step_0 (REGULAR) → on_enter performs action + assertions
+ *   __step_1 (REGULAR) → ...
+ *   __pass (END) → test passed
+ *   __fail (CANCELLED) → test failed
+ *
+ * Transitions: all named 'next' with different from states.
+ * The runner drives by calling sm.transition('next') in a loop.
+ * On failure: sm.transition('abort') → __fail.
+ */
+
+/**
+ * Compile a single TestScenario into a PlayerWorkflowDefinition (Blueprint).
+ *
+ * The compiled Blueprint can be:
+ * - Stored in the database
+ * - Serialized to JSON / .mm file
+ * - Executed on any Player (browser, iOS, server)
+ * - Generated by an LLM
+ */
+declare function compileTestScenario(scenario: TestScenario, definitions: Record<string, unknown>, scenarioIndex?: number): PlayerWorkflowDefinition;
+/**
+ * Compile all scenarios in a TestProgram into Blueprints.
+ */
+declare function compileTestProgram(program: TestProgram): PlayerWorkflowDefinition[];
+
+/**
+ * Test Action Handlers — pluggable capabilities for test Blueprints.
+ *
+ * The test Blueprint uses __test_* action types. Which action handlers
+ * are registered determines HOW the test executes:
+ *
+ * - In-process: creates StateMachines in memory, sub-millisecond
+ * - API: makes HTTP calls to a running NestJS backend (MM Server Player)
+ * - Cross-platform (future): orchestrates across multiple Players
+ *
+ * Same Blueprint → different capabilities → same results.
+ *
+ * Architecture (API mode):
+ *   Player (browser/iOS) executes Test Blueprint
+ *     → __test_transition action handler
+ *       → HTTP POST /workflow/instances/:id/transitions/:name
+ *         → NestJS Backend (MM Server Player)
+ *           → EventRouter handles cross-instance reactions
+ */
+
+interface TestActionState {
+    /** All step results collected during execution */
+    stepResults: StepResult[];
+    /** Whether any step has failed */
+    failed: boolean;
+    /** Current step tracking */
+    currentStep: {
+        name: string;
+        index: number;
+        startTime: number;
+        assertions: AssertionResult[];
+        error?: string;
+    } | null;
+    /** Set field on the orchestrator StateMachine (bound after creation) */
+    setOrchestratorField: (field: string, value: unknown) => void;
+}
+/**
+ * Create action handlers for in-process test execution.
+ *
+ * Test instances are StateMachines running in memory.
+ * Cross-instance reactions via shared EventBus.
+ * Sub-millisecond execution.
+ */
+declare function createInProcessTestActions(definitions: Record<string, PlayerWorkflowDefinition>): {
+    handlers: Map<string, ActionHandler>;
+    state: TestActionState;
+};
+/**
+ * Create action handlers for API test execution.
+ *
+ * Test instances are real DB-backed workflow instances on the NestJS backend.
+ * The backend's EventRouter handles cross-instance reactions automatically.
+ * Settle delay allows async reactions to complete before assertions.
+ */
+declare function createApiTestActions(adapter: ApiTestAdapter, options?: {
+    settleDelayMs?: number;
+}): {
+    handlers: Map<string, ActionHandler>;
+    state: TestActionState;
+};
+
+/**
+ * Blueprint Test Runner — executes test programs AS Blueprints on a Player.
+ *
+ * The test orchestrator IS a Player. This runner:
+ * 1. Compiles TestProgram → PlayerWorkflowDefinition (Blueprint)
+ * 2. Creates a StateMachine (Player) with the compiled Blueprint
+ * 3. Registers test action handlers (in-process or API)
+ * 4. Drives the StateMachine through transitions: next, next, next...
+ * 5. Collects results from the action handler state
+ *
+ * The compiled Blueprint can also be extracted, stored, and executed
+ * independently on any Player (browser, iOS, server).
+ *
+ * Exports:
+ * - runBlueprintTestProgram(): Full program execution
+ * - runBlueprintScenario(): Single scenario execution
+ * - Supports both in-process and API modes via action handler factory
+ */
+
+interface BlueprintTestConfig {
+    onStepComplete?: (scenarioIdx: number, step: StepResult) => void;
+    onScenarioComplete?: (result: ScenarioResult) => void;
+    abortSignal?: AbortSignal;
+}
+interface InProcessConfig extends BlueprintTestConfig {
+    mode: 'in-process';
+}
+interface ApiConfig extends BlueprintTestConfig {
+    mode: 'api';
+    adapter: ApiTestAdapter;
+    settleDelayMs?: number;
+    cleanupInstances?: boolean;
+}
+type BlueprintRunnerConfig = InProcessConfig | ApiConfig;
+/**
+ * Execute a complete test program using the Blueprint runner.
+ *
+ * The test program is compiled to Blueprints and executed on a Player
+ * (StateMachine) with the appropriate action handlers for the mode.
+ */
+declare function runBlueprintTestProgram(program: TestProgram, config: BlueprintRunnerConfig): Promise<TestProgramResult>;
+/**
+ * Execute a single scenario as a Blueprint on a Player.
+ */
+declare function runBlueprintScenario(scenario: TestScenario, definitions: Record<string, PlayerWorkflowDefinition>, scenarioIndex: number, config: BlueprintRunnerConfig): Promise<ScenarioResult>;
+
+/**
+ * NRT (Normalized Render Trace) — platform-agnostic representation of rendered UI.
+ *
+ * NRT captures the semantic structure of a rendered workflow view,
+ * abstracting away platform-specific rendering details. This enables:
+ *
+ * 1. Cross-platform testing (browser, iOS, terminal all produce same NRT)
+ * 2. Visual regression detection without screenshots
+ * 3. Accessibility auditing (every visible element has semantic info)
+ * 4. LLM-based test generation (structured, predictable format)
+ *
+ * Usage:
+ *   const nrt = exportNRT(renderedTree);
+ *   expect(nrt.root.children).toHaveLength(3);
+ *   expect(findNode(nrt, 'submit-button').events?.click.target.transition).toBe('submit');
+ */
+/**
+ * A complete Normalized Render Trace snapshot.
+ */
+interface NRT {
+    /** NRT format version. */
+    version: 1;
+    /** The root node of the rendered tree. */
+    root: NRTNode;
+    /** Currently focused element ID (if applicable). */
+    focus?: string;
+    /** Navigation state (if router workflow is active). */
+    nav?: NRTNavState;
+    /** Timestamp of the snapshot. */
+    timestamp?: string;
+    /** Workflow state at time of capture. */
+    workflowState?: string;
+    /** Instance ID if bound to a specific instance. */
+    instanceId?: string;
+}
+/**
+ * A single node in the NRT tree.
+ */
+interface NRTNode {
+    /** Unique ID within the tree. */
+    id: string;
+    /** Component type (e.g., 'Stack', 'Button', 'Text', 'TextInput'). */
+    type: string;
+    /** Text content (for text-bearing elements). */
+    text?: string;
+    /** Current value (for input elements). */
+    value?: unknown;
+    /** Whether this node is visible. */
+    visible: boolean;
+    /** Whether this node is enabled/interactive. */
+    enabled?: boolean;
+    /** Whether this node has focus. */
+    focused?: boolean;
+    /** Semantic role (for accessibility). */
+    role?: string;
+    /** Accessibility label. */
+    label?: string;
+    /** Key-value props that affect behavior (not styling). */
+    props?: Record<string, unknown>;
+    /** Interactive events this node can receive. */
+    events?: Record<string, NRTEvent>;
+    /** Child nodes. */
+    children: NRTNode[];
+    /** Data binding expression (if bound to workflow data). */
+    binding?: string;
+    /** Condition that controls visibility. */
+    visibleWhen?: string;
+}
+/**
+ * An interactive event on an NRT node.
+ */
+interface NRTEvent {
+    /** What kind of action this event triggers. */
+    kind: 'transition' | 'mutation' | 'navigation' | 'custom';
+    /** Target workflow operation. */
+    target: NRTEventTarget;
+}
+/**
+ * Target of an NRT event.
+ */
+interface NRTEventTarget {
+    /** Workflow slug. */
+    workflow?: string;
+    /** Transition name to fire. */
+    transition?: string;
+    /** Mutation type (create, update, delete). */
+    mutation?: string;
+    /** Navigation path. */
+    path?: string;
+    /** Custom handler name. */
+    handler?: string;
+}
+/**
+ * Navigation state for router-bound NRT.
+ */
+interface NRTNavState {
+    /** Current route state name. */
+    routeState: string;
+    /** Current URL path. */
+    path: string;
+    /** Route parameters. */
+    params: Record<string, string>;
+}
+/**
+ * Result of comparing two NRT snapshots.
+ */
+interface NRTDiff {
+    /** Whether the two snapshots are semantically equivalent. */
+    equal: boolean;
+    /** List of differences found. */
+    changes: NRTChange[];
+}
+/**
+ * A single difference between two NRT snapshots.
+ */
+interface NRTChange {
+    /** Type of change. */
+    type: 'added' | 'removed' | 'modified';
+    /** Path to the changed node (e.g., 'root.children[0].children[1]'). */
+    path: string;
+    /** Node ID if available. */
+    nodeId?: string;
+    /** What changed. */
+    field: string;
+    /** Previous value (for modified/removed). */
+    oldValue?: unknown;
+    /** New value (for modified/added). */
+    newValue?: unknown;
+}
+/**
+ * Creates an empty NRT snapshot.
+ */
+declare function createEmptyNRT(): NRT;
+/**
+ * Finds a node by ID in the NRT tree.
+ */
+declare function findNode(nrt: NRT, nodeId: string): NRTNode | undefined;
+/**
+ * Finds all visible nodes in the NRT tree.
+ */
+declare function findVisibleNodes(nrt: NRT): NRTNode[];
+/**
+ * Finds all interactive nodes (nodes with events) in the NRT tree.
+ */
+declare function findInteractiveNodes(nrt: NRT): NRTNode[];
+/**
+ * Counts total nodes in the NRT tree.
+ */
+declare function countNodes(nrt: NRT): number;
+
+/**
+ * NRT Comparator — semantic diff between two NRT snapshots.
+ *
+ * Compares structure, text, visibility, and events while ignoring
+ * platform-specific details like classNames, styles, and layout metrics.
+ *
+ * Usage:
+ *   const diff = compareNRT(before, after);
+ *   if (!diff.equal) {
+ *     console.log('Changes:', diff.changes);
+ *   }
+ */
+
+/**
+ * Compares two NRT snapshots and returns a semantic diff.
+ */
+declare function compareNRT(before: NRT, after: NRT): NRTDiff;
+
+/**
+ * Action Trace — records all workflow actions during execution.
+ *
+ * Captures a chronological trace of every transition, action, timer,
+ * and query that occurs during a workflow session. This enables:
+ *
+ * 1. Replay debugging (step through recorded actions)
+ * 2. Test assertions on action sequences
+ * 3. Performance profiling (timing of each tick)
+ * 4. Compliance auditing (complete action log)
+ *
+ * Usage:
+ *   const recorder = createActionRecorder();
+ *   // ... hook into workflow runtime ...
+ *   const trace = recorder.getTrace();
+ *   expect(trace.ticks).toHaveLength(3);
+ *   expect(trace.ticks[0].kind).toBe('transition');
+ */
+/**
+ * A complete action trace for a workflow session.
+ */
+interface ActionTrace {
+    /** Trace format version. */
+    version: 1;
+    /** Workflow definition slug. */
+    workflowSlug: string;
+    /** Instance ID (if tracking a specific instance). */
+    instanceId?: string;
+    /** When the trace started. */
+    startedAt: string;
+    /** When the trace ended (if finalized). */
+    endedAt?: string;
+    /** Ordered list of action ticks. */
+    ticks: ActionTick[];
+}
+/**
+ * A single action tick in the trace.
+ */
+interface ActionTick {
+    /** Monotonically increasing tick number. */
+    tick: number;
+    /** ISO timestamp of the tick. */
+    timestamp: string;
+    /** Kind of action. */
+    kind: 'transition' | 'action' | 'timer' | 'query' | 'mutation' | 'event' | 'error';
+    /** Name/identifier of the action. */
+    name: string;
+    /** Duration in milliseconds (if measurable). */
+    durationMs?: number;
+    /** Workflow state before this tick. */
+    fromState?: string;
+    /** Workflow state after this tick. */
+    toState?: string;
+    /** Detailed information about the tick. */
+    detail: Record<string, unknown>;
+}
+/**
+ * Action recorder — accumulates ticks into a trace.
+ */
+interface ActionRecorder {
+    /** Record a transition. */
+    recordTransition: (name: string, fromState: string, toState: string, detail?: Record<string, unknown>) => void;
+    /** Record an action execution. */
+    recordAction: (name: string, detail?: Record<string, unknown>) => void;
+    /** Record a timer event. */
+    recordTimer: (name: string, detail?: Record<string, unknown>) => void;
+    /** Record a data query. */
+    recordQuery: (name: string, detail?: Record<string, unknown>) => void;
+    /** Record a mutation. */
+    recordMutation: (name: string, detail?: Record<string, unknown>) => void;
+    /** Record an event. */
+    recordEvent: (name: string, detail?: Record<string, unknown>) => void;
+    /** Record an error. */
+    recordError: (name: string, detail?: Record<string, unknown>) => void;
+    /** Get the current trace. */
+    getTrace: () => ActionTrace;
+    /** Finalize the trace (sets endedAt). */
+    finalize: () => ActionTrace;
+    /** Reset the recorder. */
+    reset: () => void;
+}
+/**
+ * Creates a new action recorder.
+ */
+declare function createActionRecorder(workflowSlug: string, instanceId?: string): ActionRecorder;
+/**
+ * Filters a trace to only transition ticks.
+ */
+declare function getTransitionPath(trace: ActionTrace): string[];
+/**
+ * Gets the final state from a trace.
+ */
+declare function getFinalState(trace: ActionTrace): string | undefined;
+/**
+ * Counts ticks by kind.
+ */
+declare function countByKind(trace: ActionTrace): Record<string, number>;
+/**
+ * Checks if a trace contains a specific transition.
+ */
+declare function hasTransition(trace: ActionTrace, from: string, to: string): boolean;
+
+/**
+ * IR Types — the complete Intermediate Representation contract.
+ *
+ * These types mirror the MM-IR Reference (0-MM-IR-REFERENCE.md).
+ * Standalone — no imports from backend/frontend packages.
+ * The compiler transforms AST nodes into these shapes.
+ */
+type IRStateType = 'START' | 'REGULAR' | 'END' | 'CANCELLED';
+type IRActionMode = 'auto' | 'manual';
+/**
+ * Field type is an open string slug referencing an Element definition.
+ *
+ * Canonical seed types: text, rich_text, number, boolean, date, datetime,
+ * select, multi_select, url, email, phone, currency, percentage, rating,
+ * duration, color, file, image, link_to_one, link_to_many, formula, rollup,
+ * count, lookup, created_at, updated_at, created_by, auto_number, barcode.
+ *
+ * User-defined types use slugs like 'my-org/custom-address'.
+ * The 14 original types remain valid — this is backward compatible.
+ */
+type IRWorkflowFieldType = string;
+type RuntimeProfile = 'backend' | 'collaborative' | 'p2p' | 'local' | 'ephemeral' | 'edge';
+interface IRStateHome {
+    scope: 'ephemeral' | 'route' | 'instance' | 'global';
+    persistence: 'none' | 'local' | 'durable';
+    sync: 'none' | 'tenant' | 'p2p';
+}
+interface IRActionDefinition {
+    id: string;
+    type: string;
+    mode: IRActionMode;
+    config: Record<string, unknown>;
+    condition?: string;
+}
+interface IRDuringAction {
+    id: string;
+    type: 'interval' | 'timeout' | 'poll' | 'once' | 'cron';
+    interval_ms?: number;
+    cron?: string;
+    delay_ms?: number;
+    actions: IRActionDefinition[];
+    condition?: string;
+}
+interface IROnEventAction {
+    type: 'set_field' | 'set_memory' | 'log_event' | 'create_instance';
+    field?: string;
+    expression?: string;
+    key?: string;
+    message?: string;
+    config?: Record<string, unknown>;
+    conditions?: string[];
+}
+interface IROnEventSubscription {
+    match: string;
+    description?: string;
+    conditions?: string[];
+    actions: IROnEventAction[];
+}
+interface IRStateDefinition {
+    name: string;
+    description?: string;
+    type: IRStateType;
+    on_enter: IRActionDefinition[];
+    during: IRDuringAction[];
+    on_exit: IRActionDefinition[];
+    on_event?: IROnEventSubscription[];
+}
+interface IRConditionDefinition {
+    type?: string;
+    field?: string;
+    operator?: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'contains' | 'is_set' | 'is_empty';
+    value?: unknown;
+    expression?: string;
+    OR?: IRConditionDefinition[];
+    AND?: IRConditionDefinition[];
+}
+interface IRTransitionDefinition {
+    name: string;
+    description?: string;
+    from: string[];
+    to: string;
+    conditions?: IRConditionDefinition[];
+    actions: IRActionDefinition[];
+    roles?: string[];
+    auto?: boolean;
+    required_fields?: string[];
+}
+interface IRFieldValidation {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    options?: string[];
+    rules?: Array<{
+        expression: string;
+        message: string;
+        severity: 'error' | 'warning';
+    }>;
+}
+interface IRFieldDefinition {
+    name: string;
+    type: IRWorkflowFieldType;
+    /** Version pin: { type, typeVersion } is canonical storage/API form */
+    typeVersion?: string;
+    /** Structural inheritance: storage + widget + primitive intrinsics from base type */
+    baseType?: string;
+    label?: string;
+    required?: boolean;
+    default_value?: unknown;
+    validation?: IRFieldValidation;
+    computed?: string;
+    computed_deps?: string[];
+    visible_in_states?: string[];
+    editable_in_states?: string[];
+    visible_to_roles?: string[];
+    editable_by_roles?: string[];
+    visible_when?: string;
+    editable_when?: string;
+    state_home?: IRStateHome;
+}
+interface IRRoleDefinition {
+    name: string;
+    description?: string;
+    permissions: string[];
+}
+interface IRWorkflowDefinition {
+    slug: string;
+    name: string;
+    version: string;
+    description?: string;
+    category: string | string[];
+    states: IRStateDefinition[];
+    transitions: IRTransitionDefinition[];
+    fields: IRFieldDefinition[];
+    roles: IRRoleDefinition[];
+    tags?: Array<{
+        tag_name: string;
+    }>;
+    metadata?: Record<string, unknown>;
+    on_event?: IROnEventSubscription[];
+    extensions?: Record<string, IRGrammarIsland[]>;
+}
+interface IRGrammarIsland {
+    slug: string;
+    contextTag: string;
+    rawSource: string;
+    parsed?: unknown;
+}
+interface IRExperienceNode {
+    id: string;
+    /** User-assigned display name for authoring UIs (e.g., "Hero Section", "Login Form") */
+    displayName?: string;
+    /** Reference to a registered experience definition (prefab instantiation) */
+    experienceId?: string;
+    component?: string;
+    /** Slot placeholder — rendered by collecting contributions from sub-workflows */
+    slot?: string;
+    children?: IRExperienceNode[];
+    dataSources?: IRDataSource[];
+    dataScope?: string;
+    layout?: string;
+    /** CSS class on the wrapper div */
+    className?: string;
+    /** Style IR — structured cross-platform styling (opaque to player-core) */
+    style?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    bindings?: Record<string, string>;
+    /** Overrides for a referenced experience's defaults */
+    overrides?: Record<string, unknown>;
+    visible_when?: string;
+}
+interface IRWorkflowDataSource {
+    type: 'workflow';
+    name: string;
+    slug?: string;
+    query: 'latest' | 'list' | 'count';
+    /** Fetch a specific instance by ID. Supports template interpolation: "{{entity_id}}" */
+    instanceId?: string;
+    /** Entity scope for the query (null = no filtering, omitted = inherited) */
+    entity?: {
+        type: string;
+        id: string;
+    } | null;
+    paginated?: boolean;
+    pageSize?: number;
+    /** Static filters always applied (e.g., { current_state: 'todo' }) */
+    filter?: Record<string, string>;
+    /** Dynamic filters with bind expressions */
+    filters?: Record<string, string | {
+        bind: string;
+    }>;
+    sort?: string;
+    search?: string;
+    searchFields?: string[];
+    facets?: string[];
+    /** Range filters: { field: { min?, max? } } */
+    range?: Record<string, {
+        min?: unknown;
+        max?: unknown;
+    }>;
+    /** Aggregate functions: "field:fn,field:fn" */
+    aggregate?: string;
+    groupBy?: string;
+    parentInstanceId?: string;
+    autoStart?: boolean;
+    initialData?: Record<string, unknown>;
+    includeDefinition?: boolean;
+}
+interface IRApiDataSource {
+    type: 'api';
+    name: string;
+    endpoint: string;
+    method?: 'GET' | 'POST';
+    /** Map API response to InstanceData shape */
+    mapping?: {
+        id?: string;
+        state?: string;
+        data?: string;
+        items?: string;
+        total?: string;
+    };
+    staleTime?: number;
+}
+interface IRRefDataSource {
+    type: 'ref';
+    name: string;
+    expression: string;
+}
+interface IRStaticDataSource {
+    type: 'static';
+    name: string;
+    data: Record<string, unknown> | Record<string, unknown>[];
+}
+type IRDataSource = IRWorkflowDataSource | IRApiDataSource | IRRefDataSource | IRStaticDataSource;
+interface IRExperienceDefinition {
+    slug: string;
+    version: string;
+    name: string;
+    description?: string;
+    category: string | string[];
+    view_definition: IRExperienceNode;
+    workflows: string[];
+    children: string[];
+    data_bindings: unknown[];
+    is_default: boolean;
+}
+interface IRBlueprintManifest {
+    workflows: Array<{
+        slug: string;
+        role: 'primary' | 'child' | 'derived' | 'utility';
+    }>;
+    experience_id: string;
+    routes?: Array<{
+        path: string;
+        node: string;
+        entityType?: string;
+        entityIdSource?: 'user' | 'param';
+    }>;
+}
+/**
+ * Canonical workflow tree per spec 041 §1.1.
+ * This is the universal type: { slug, category, parts, metadata }.
+ *
+ * Category invariants (INV-1):
+ *   category.length >= 1
+ *   category[0] = primary (dispatch target, must be IDENT)
+ *   category[1..] = tags (sorted bytewise UTF-8, unique, primary not in tags)
+ */
+interface PureFormWorkflow {
+    slug: string;
+    category: string[];
+    parts?: PureFormWorkflow[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Compiled output: canonical tree (truth) + lowered IR (cache).
+ * Per spec 048 §1.2: canonical tree IS the storage format,
+ * IR is a derivable runtime cache.
+ */
+interface CompiledOutput {
+    canonical: PureFormWorkflow;
+    ir: IRWorkflowDefinition;
+}
+/**
+ * Normalizes a category array to satisfy INV-1:
+ * - category[0] = primary (unchanged)
+ * - category[1..] = sorted bytewise UTF-8, unique, primary excluded
+ */
+declare function normalizeCategory(primary: string, ...tags: string[]): string[];
+type CompilerErrorCode = 'MISSING_STARTS_AT' | 'UNKNOWN_TARGET_STATE' | 'DUPLICATE_FIELD' | 'DUPLICATE_STATE' | 'UNKNOWN_FIELD_TYPE' | 'INVALID_EXPRESSION' | 'UNKNOWN_FRAGMENT' | 'EMPTY_WORKFLOW' | 'STRICT_USE_EFFECT' | 'STRICT_USE_REF' | 'STRICT_USE_MEMO' | 'STRICT_USE_CALLBACK' | 'STRICT_USE_LAYOUT_EFFECT' | 'STRICT_FORBIDDEN_IMPORT' | 'INFER_RAW_JSX';
+interface CompilerError {
+    code: CompilerErrorCode;
+    message: string;
+    lineNumber?: number;
+    severity: 'error' | 'warning';
+}
+interface CompilationResult {
+    workflows: IRWorkflowDefinition[];
+    experiences: IRExperienceDefinition[];
+    manifest?: IRBlueprintManifest;
+    errors: CompilerError[];
+    warnings: CompilerError[];
+}
+
+/**
+ * Definition Validator — static validation of compiled IR definitions.
+ *
+ * Validates structural integrity, referential consistency, and semantic
+ * correctness of IRWorkflowDefinition before it reaches the runtime.
+ *
+ * Categories:
+ * - STRUCTURAL: Missing required fields, type mismatches
+ * - REFERENTIAL: Dangling state refs, missing transition targets
+ * - SEMANTIC: Unreachable states, dead transitions, missing START
+ * - EXPERIENCE: Unknown components, invalid bindings, missing data sources
+ */
+
+type ValidationSeverity = 'error' | 'warning' | 'info';
+type ValidationCategory = 'structural' | 'referential' | 'semantic' | 'experience';
+interface ValidationIssue {
+    /** Unique code for programmatic matching. */
+    code: string;
+    /** Human-readable message. */
+    message: string;
+    /** Severity level. */
+    severity: ValidationSeverity;
+    /** Validation category. */
+    category: ValidationCategory;
+    /** Location path (e.g., 'states[0].on_enter[1]'). */
+    path?: string;
+    /** Suggested fix. */
+    suggestion?: string;
+}
+interface ValidationResult {
+    /** Whether the definition passed all error-level checks. */
+    valid: boolean;
+    /** All issues found. */
+    issues: ValidationIssue[];
+    /** Quick access to error count. */
+    errorCount: number;
+    /** Quick access to warning count. */
+    warningCount: number;
+    /** Summary statistics. */
+    summary: {
+        stateCount: number;
+        transitionCount: number;
+        fieldCount: number;
+        hasExperience: boolean;
+        hasExtensions: boolean;
+    };
+}
+interface ValidatorOptions {
+    /** Known component IDs (for experience validation). */
+    knownComponents?: string[];
+    /** Known binding roots (default: $instance, $definition, $instances, $local, $entity, $user, $fn, $action, $item, $index). */
+    knownBindingRoots?: string[];
+    /** Skip experience tree validation. */
+    skipExperience?: boolean;
+    /** Skip semantic analysis (reachability, etc.). */
+    skipSemantic?: boolean;
+}
+/**
+ * Validates an IRWorkflowDefinition for structural, referential,
+ * semantic, and experience correctness.
+ */
+declare function validateDefinition(def: IRWorkflowDefinition, options?: ValidatorOptions): ValidationResult;
+/**
+ * Quick structural check — returns true if the definition has minimum viable structure.
+ * Much faster than full validateDefinition() for use in render-path guards.
+ */
+declare function isViableDefinition(def: unknown): def is IRWorkflowDefinition;
+
+/**
+ * DSL Compiler — entry point.
+ *
+ * Pipeline: tokenize → parse → collectSymbols → compileWorkflows → compileViews → compileManifest
+ */
+
+/**
+ * Compile DSL source text into the full IR.
+ */
+declare function compile(source: string): CompilationResult;
+
+/**
+ * IR Migration — forward-compatibility layer for workflow definitions.
+ *
+ * Handles differences between IR versions so that older compiled definitions
+ * continue to work with newer runtimes. Each migration transforms from
+ * one version to the next; they chain automatically.
+ *
+ * Version history:
+ * - v1.0: Original format (states use state_type, actions use action_type)
+ * - v1.1: Normalized format (states use type, actions use type, fields use type)
+ * - v1.2: Added extensions, during actions, on_event at workflow level
+ *
+ * The current version is always the latest. Older definitions are migrated
+ * transparently by normalizeDefinition().
+ */
+
+declare const CURRENT_IR_VERSION = "1.2";
+interface MigrationResult {
+    /** The migrated definition. */
+    definition: IRWorkflowDefinition;
+    /** Original IR version detected. */
+    fromVersion: string;
+    /** Target IR version after migration. */
+    toVersion: string;
+    /** Whether any migration was applied. */
+    migrated: boolean;
+    /** Migrations applied (in order). */
+    appliedMigrations: string[];
+}
+/**
+ * Detect the IR version of a definition.
+ * Uses heuristics based on field naming conventions.
+ */
+declare function detectIRVersion(def: Record<string, unknown>): string;
+/**
+ * Normalize a definition to the current IR version.
+ * Applies all necessary migrations in sequence.
+ */
+declare function normalizeDefinition(def: Record<string, unknown>): MigrationResult;
+/**
+ * Check if a definition needs migration.
+ */
+declare function needsMigration(def: Record<string, unknown>): boolean;
+
+export { type ActionDefinition, ActionDispatcher, type ActionHandler, type ActionHandlerFn, type ActionRecorder, type ActionResult, type ActionTick, type ActionTrace, type AnalysisResult, type AnalysisSummary, type ApiInstanceSnapshot, type ApiTestAdapter, type ApiTestRunnerConfig, type ApiTransitionResult, type AssertionResult, type BlueprintRunnerConfig, type BusEvent, CORE_FUNCTIONS, CURRENT_IR_VERSION, type CompilationResult, type CompiledOutput, type CompilerError, type CompilerErrorCode, type Evaluator, type EvaluatorConfig, EventBus, type EventHandler, type EventSubscription, type ExpressionContext, type ExpressionDiagnostics, type ExpressionFunction, type ExpressionResult, type FailurePolicy, type FailurePolicyContext, type GraphPath, type IRActionDefinition, type IRActionMode, type IRApiDataSource, type IRBlueprintManifest, type IRConditionDefinition, type IRDataSource, type IRDuringAction, type IRExperienceDefinition, type IRExperienceNode, type IRFieldDefinition, type IRFieldValidation, type IRGrammarIsland, type IROnEventAction, type IROnEventSubscription, type IRRefDataSource, type IRRoleDefinition, type IRStateDefinition, type IRStateHome, type IRStateType, type IRStaticDataSource, type IRTransitionDefinition, type IRWorkflowDataSource, type IRWorkflowDefinition, type IRWorkflowFieldType, type MigrationResult, type NRT, type NRTChange, type NRTDiff, type NRTEvent, type NRTEventTarget, type NRTNavState, type NRTNode, type PlayerAction, type PlayerInstance, type PlayerOnEventSubscription, type PlayerStateDefinition, type PlayerTransitionDefinition, type PlayerWorkflowDefinition, type PureFormWorkflow, type RuntimeProfile, type ScenarioResult, StateMachine, type StateMachineConfig, type StateMachineEvent, type StateMachineListener, type StateNode, type StateType, type StepResult, type TestActionState, type TestAssertion, type TestInstance, type TestProgram, type TestProgramResult, type TestRunnerConfig, type TestScenario, type TestStep, type TransitionEdge, type TransitionResult, type Unsubscribe, type ValidationCategory, type ValidationIssue, type ValidationResult, type ValidationSeverity, type ValidatorOptions, WEB_FAILURE_POLICIES, analyzeDefinition, buildFunctionMap, clearExpressionCache, clearPatternCache, compareNRT, compile, compilePattern, compileTestProgram, compileTestScenario, countByKind, countNodes, createActionRecorder, createApiTestActions, createEmptyNRT, createEvaluator, createInProcessTestActions, detectIRVersion, findInteractiveNodes, findNode, findVisibleNodes, generateCoverageScenarios, getFinalState, getTransitionPath, hasTransition, isViableDefinition, matchTopic, needsMigration, normalizeCategory, normalizeDefinition, runBlueprintScenario, runBlueprintTestProgram, runScenario, runTestProgram, validateDefinition };