xcomponent-ai 0.1.1

package/dist/fsm-runtime.js

@@ -0,0 +1,1122 @@
+"use strict";
+/**
+ * FSM Runtime Engine
+ * Implements XComponent-inspired state machine execution with multi-instance support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FSMRuntime = void 0;
+exports.loadComponent = loadComponent;
+const events_1 = require("events");
+const uuid_1 = require("uuid");
+const types_1 = require("./types");
+const timer_wheel_1 = require("./timer-wheel");
+const persistence_1 = require("./persistence");
+/**
+ * Sender implementation for triggered methods
+ * Provides controlled access to runtime operations
+ * Supports both intra-component and cross-component communication
+ */
+class SenderImpl {
+    runtime;
+    registry;
+    constructor(runtime, registry) {
+        this.runtime = runtime;
+        this.registry = registry;
+    }
+    async sendTo(instanceId, event) {
+        return this.runtime.sendEvent(instanceId, event);
+    }
+    async sendToComponent(componentName, instanceId, event) {
+        if (!this.registry) {
+            throw new Error('Cross-component communication requires ComponentRegistry');
+        }
+        return this.registry.sendEventToComponent(componentName, instanceId, event);
+    }
+    async broadcast(machineName, currentState, event) {
+        return this.runtime.broadcastEvent(machineName, currentState, event);
+    }
+    async broadcastToComponent(componentName, machineName, currentState, event) {
+        if (!this.registry) {
+            throw new Error('Cross-component communication requires ComponentRegistry');
+        }
+        return this.registry.broadcastToComponent(componentName, machineName, currentState, event);
+    }
+    createInstance(machineName, initialContext) {
+        return this.runtime.createInstance(machineName, initialContext);
+    }
+    createInstanceInComponent(componentName, machineName, initialContext) {
+        if (!this.registry) {
+            throw new Error('Cross-component communication requires ComponentRegistry');
+        }
+        return this.registry.createInstanceInComponent(componentName, machineName, initialContext);
+    }
+}
+/**
+ * FSM Runtime Engine
+ * Manages multiple FSM instances with event-driven execution
+ */
+class FSMRuntime extends events_1.EventEmitter {
+    instances;
+    machines;
+    timerWheel; // Performance: Single timer for all timeouts
+    timeoutTasks; // instanceId → taskIds (for cleanup)
+    persistence;
+    componentDef;
+    registry; // For cross-component communication
+    // Performance: Hash-based indexes for efficient property matching (XComponent pattern)
+    machineIndex; // machineName → Set<instanceId>
+    stateIndex; // "machineName:state" → Set<instanceId>
+    propertyIndex; // "machineName:propName:propValue" → Set<instanceId>
+    constructor(component, persistenceConfig) {
+        super();
+        this.instances = new Map();
+        this.machines = new Map();
+        // Timer wheel: 10ms ticks for high precision, 6000 buckets = 60s max
+        // Still O(1) with single timer - 10ms granularity is sufficient for most use cases
+        // For longer timeouts (>60s), tasks will wrap around (multi-lap)
+        this.timerWheel = new timer_wheel_1.TimerWheel(10, 6000);
+        this.timeoutTasks = new Map(); // Track tasks for cleanup
+        this.componentDef = component;
+        // Initialize indexes
+        this.machineIndex = new Map();
+        this.stateIndex = new Map();
+        this.propertyIndex = new Map();
+        // Start timer wheel
+        this.timerWheel.start();
+        // Setup persistence (optional)
+        if (persistenceConfig && (persistenceConfig.eventSourcing || persistenceConfig.snapshots)) {
+            const eventStore = persistenceConfig.eventStore || new persistence_1.InMemoryEventStore();
+            const snapshotStore = persistenceConfig.snapshotStore || new persistence_1.InMemorySnapshotStore();
+            this.persistence = new persistence_1.PersistenceManager(eventStore, snapshotStore, {
+                eventSourcing: persistenceConfig.eventSourcing,
+                snapshots: persistenceConfig.snapshots,
+                snapshotInterval: persistenceConfig.snapshotInterval,
+            });
+        }
+        else {
+            this.persistence = null;
+        }
+        // Index machines by name
+        component.stateMachines.forEach(machine => {
+            this.machines.set(machine.name, machine);
+        });
+        // Setup cascading rules engine (XComponent pattern)
+        this.setupCascadingEngine();
+    }
+    /**
+     * Create a new FSM instance
+     *
+     * If the state machine defines a publicMemberType (XComponent pattern),
+     * the instance will have separate publicMember and internalMember.
+     * Otherwise, it uses the simple context pattern.
+     *
+     * @param machineName State machine name
+     * @param initialContext Initial context or public member data
+     * @returns Instance ID
+     */
+    createInstance(machineName, initialContext = {}) {
+        const machine = this.machines.get(machineName);
+        if (!machine) {
+            throw new Error(`Machine ${machineName} not found`);
+        }
+        const instanceId = (0, uuid_1.v4)();
+        // XComponent pattern: separate publicMember and internalMember
+        const instance = {
+            id: instanceId,
+            machineName,
+            currentState: machine.initialState,
+            context: machine.publicMemberType ? {} : initialContext,
+            publicMember: machine.publicMemberType ? initialContext : undefined,
+            internalMember: machine.publicMemberType ? {} : undefined,
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+            status: 'active',
+        };
+        this.instances.set(instanceId, instance);
+        // Add to indexes for fast lookups
+        this.addToIndex(instance);
+        this.emit('instance_created', instance);
+        // Setup timeout transitions if any from initial state
+        this.setupTimeouts(instanceId, machine.initialState);
+        // Setup auto-transitions if any from initial state
+        this.setupAutoTransitions(instanceId, machine.initialState);
+        return instanceId;
+    }
+    /**
+     * Send event to an instance
+     */
+    async sendEvent(instanceId, event) {
+        const instance = this.instances.get(instanceId);
+        if (!instance) {
+            throw new Error(`Instance ${instanceId} not found`);
+        }
+        if (instance.status !== 'active') {
+            throw new Error(`Instance ${instanceId} is not active`);
+        }
+        const machine = this.machines.get(instance.machineName);
+        if (!machine) {
+            throw new Error(`Machine ${instance.machineName} not found`);
+        }
+        // Use publicMember if available (XComponent pattern), otherwise fallback to context
+        const instanceContext = instance.publicMember || instance.context;
+        // Find applicable transition
+        const transition = this.findTransition(machine, instance.currentState, event, instanceContext);
+        if (!transition) {
+            this.emit('event_ignored', { instanceId, event, currentState: instance.currentState });
+            return;
+        }
+        // Check guards
+        if (transition.guards && !this.evaluateGuards(transition.guards, event, instanceContext)) {
+            this.emit('guard_failed', { instanceId, event, transition });
+            return;
+        }
+        const previousState = instance.currentState;
+        try {
+            // Execute transition
+            await this.executeTransition(instance, transition, event);
+            // Update instance
+            instance.currentState = transition.to;
+            instance.updatedAt = Date.now();
+            // Update indexes
+            this.updateIndexOnStateChange(instance, previousState, transition.to);
+            // Persist event (event sourcing)
+            let eventId = '';
+            if (this.persistence) {
+                eventId = await this.persistence.persistEvent(instanceId, instance.machineName, this.componentDef.name, event, previousState, transition.to);
+                // Set as current event for causality tracking
+                this.persistence.setCurrentEventId(eventId);
+            }
+            // Clear old timeouts
+            this.clearTimeouts(instanceId);
+            // Emit state change
+            this.emit('state_change', {
+                instanceId,
+                previousState,
+                newState: transition.to,
+                event,
+                eventId,
+                timestamp: Date.now(),
+            });
+            // Save snapshot if needed
+            // Note: With timer wheel, we don't pass pending timeouts map
+            // Timeouts are resynchronized during restore() based on elapsed time
+            if (this.persistence) {
+                await this.persistence.maybeSnapshot(instance, eventId, undefined);
+            }
+            // Check if final or error state
+            const targetState = machine.states.find(s => s.name === transition.to);
+            if (targetState && (targetState.type === types_1.StateType.FINAL || targetState.type === types_1.StateType.ERROR)) {
+                instance.status = targetState.type === types_1.StateType.FINAL ? 'completed' : 'error';
+                // Remove from indexes before disposing
+                this.removeFromIndex(instance);
+                this.emit('instance_disposed', instance);
+                this.instances.delete(instanceId);
+                return;
+            }
+            // Setup new timeouts
+            this.setupTimeouts(instanceId, transition.to);
+            // Setup auto-transitions
+            this.setupAutoTransitions(instanceId, transition.to);
+            // Handle inter-machine transitions
+            if (transition.type === types_1.TransitionType.INTER_MACHINE && transition.targetMachine) {
+                const newInstanceId = this.createInstance(transition.targetMachine, { ...instance.context });
+                this.emit('inter_machine_transition', {
+                    sourceInstanceId: instanceId,
+                    targetInstanceId: newInstanceId,
+                    targetMachine: transition.targetMachine,
+                });
+            }
+        }
+        catch (error) {
+            instance.status = 'error';
+            // Remove from indexes before deleting
+            this.removeFromIndex(instance);
+            this.emit('instance_error', { instanceId, error: error.message });
+            this.instances.delete(instanceId);
+        }
+    }
+    /**
+     * Broadcast event to all matching instances (XComponent-style property matching)
+     *
+     * This method implements XComponent's property-based instance routing:
+     * - Finds all instances of the target machine in the specified state
+     * - Evaluates matching rules (property equality checks)
+     * - Routes event to ALL instances where matching rules pass
+     *
+     * Example:
+     *   // 100 Order instances exist
+     *   // Event: ExecutionInput { OrderId: 42, Quantity: 500 }
+     *   // Matching rule: ExecutionInput.OrderId = Order.Id
+     *   // → Automatically routes to Order instance with Id=42
+     *
+     * @param machineName Target state machine name
+     * @param currentState Current state filter (only instances in this state)
+     * @param event Event to broadcast
+     * @returns Number of instances that received the event
+     */
+    async broadcastEvent(machineName, currentState, event) {
+        const machine = this.machines.get(machineName);
+        if (!machine) {
+            throw new Error(`Machine ${machineName} not found`);
+        }
+        // Find ALL transitions with matching rules for this state/event combination
+        const transitionsWithMatchingRules = machine.transitions.filter(t => t.from === currentState && t.event === event.type && t.matchingRules && t.matchingRules.length > 0);
+        if (transitionsWithMatchingRules.length === 0) {
+            throw new Error(`No transition with matching rules found for ${machineName}.${currentState} on event ${event.type}`);
+        }
+        let processedCount = 0;
+        const processedInstances = new Set();
+        // For each transition with matching rules, find and process matching instances
+        for (const transition of transitionsWithMatchingRules) {
+            // Find all instances that match this transition's rules
+            const matchingInstances = this.findMatchingInstances(machineName, currentState, event, transition.matchingRules);
+            // Send event to each matching instance (only once per instance)
+            for (const instance of matchingInstances) {
+                if (processedInstances.has(instance.id)) {
+                    continue; // Already processed by another transition
+                }
+                try {
+                    const stateBefore = instance.currentState;
+                    await this.sendEvent(instance.id, event);
+                    // Check if state actually changed (or instance was disposed)
+                    const instanceAfter = this.instances.get(instance.id);
+                    const transitioned = !instanceAfter || instanceAfter.currentState !== stateBefore;
+                    if (transitioned) {
+                        processedInstances.add(instance.id);
+                        processedCount++;
+                    }
+                }
+                catch (error) {
+                    this.emit('broadcast_error', {
+                        instanceId: instance.id,
+                        event,
+                        error: error.message,
+                    });
+                }
+            }
+        }
+        this.emit('broadcast_completed', {
+            machineName,
+            currentState,
+            event,
+            matchedCount: processedInstances.size,
+            processedCount,
+        });
+        return processedCount;
+    }
+    /**
+     * Find instances that match the property matching rules
+     *
+     * @param machineName Target machine name
+     * @param currentState Current state filter
+     * @param event Event to match against
+     * @param matchingRules Property matching rules
+     * @returns Array of matching instances
+     */
+    findMatchingInstances(machineName, currentState, event, matchingRules) {
+        // Performance optimization: Use hash-based index for O(1) lookup
+        // Instead of iterating all instances, use state index
+        // Try to use property index for direct lookup (fastest path)
+        // If we have a single matching rule with === operator, we can use the property index
+        if (matchingRules.length === 1 && (!matchingRules[0].operator || matchingRules[0].operator === '===')) {
+            const rule = matchingRules[0];
+            const eventValue = this.getNestedProperty(event.payload, rule.eventProperty);
+            if (eventValue !== undefined) {
+                // Check if property is top-level (no dots) for direct index lookup
+                if (!rule.instanceProperty.includes('.')) {
+                    const propKey = `${machineName}:${rule.instanceProperty}:${String(eventValue)}`;
+                    const candidateIds = this.propertyIndex.get(propKey);
+                    if (candidateIds) {
+                        // Filter by state and status
+                        return Array.from(candidateIds)
+                            .map(id => this.instances.get(id))
+                            .filter(instance => instance &&
+                            instance.currentState === currentState &&
+                            instance.status === 'active');
+                    }
+                }
+            }
+        }
+        // Fallback: Use state index (still faster than iterating all instances)
+        const stateKey = `${machineName}:${currentState}`;
+        const candidateIds = this.stateIndex.get(stateKey);
+        if (!candidateIds || candidateIds.size === 0) {
+            return [];
+        }
+        // Get instances and filter by matching rules
+        const candidates = Array.from(candidateIds)
+            .map(id => this.instances.get(id))
+            .filter(instance => instance && instance.status === 'active');
+        // Filter by matching rules
+        return candidates.filter(instance => {
+            return this.evaluateMatchingRules(instance, event, matchingRules);
+        });
+    }
+    /**
+     * Evaluate matching rules for an instance
+     *
+     * @param instance FSM instance to check
+     * @param event Event to match against
+     * @param matchingRules Matching rules to evaluate
+     * @returns true if all matching rules pass
+     */
+    evaluateMatchingRules(instance, event, matchingRules) {
+        return matchingRules.every(rule => {
+            const eventValue = this.getNestedProperty(event.payload, rule.eventProperty);
+            // Use publicMember if available (XComponent pattern), otherwise fallback to context
+            const instanceData = instance.publicMember || instance.context;
+            const instanceValue = this.getNestedProperty(instanceData, rule.instanceProperty);
+            // Handle undefined values
+            if (eventValue === undefined || instanceValue === undefined) {
+                return false;
+            }
+            // Apply operator (default to strict equality)
+            // Semantics: instanceValue operator eventValue
+            // Example: balance > threshold means instanceValue (balance) > eventValue (threshold)
+            const operator = rule.operator || '===';
+            switch (operator) {
+                case '===':
+                    return instanceValue === eventValue;
+                case '!==':
+                    return instanceValue !== eventValue;
+                case '>':
+                    return instanceValue > eventValue;
+                case '<':
+                    return instanceValue < eventValue;
+                case '>=':
+                    return instanceValue >= eventValue;
+                case '<=':
+                    return instanceValue <= eventValue;
+                default:
+                    return instanceValue === eventValue;
+            }
+        });
+    }
+    /**
+     * Get nested property value from object using dot notation
+     *
+     * Example: getNestedProperty({ customer: { id: 42 } }, "customer.id") → 42
+     *
+     * @param obj Object to get property from
+     * @param path Property path (dot notation)
+     * @returns Property value or undefined
+     */
+    getNestedProperty(obj, path) {
+        return path.split('.').reduce((current, prop) => current?.[prop], obj);
+    }
+    /**
+     * Find applicable transition with support for specific triggering rules
+     *
+     * When multiple transitions exist from the same state with the same event,
+     * specific triggering rules differentiate them (XComponent pattern).
+     *
+     * @param machine State machine
+     * @param currentState Current state name
+     * @param event Event to match
+     * @param instanceContext Instance context for specific triggering rule evaluation
+     * @returns Matching transition or null
+     */
+    findTransition(machine, currentState, event, instanceContext) {
+        // Find all candidate transitions
+        const candidates = machine.transitions.filter(t => t.from === currentState && t.event === event.type);
+        if (candidates.length === 0) {
+            return null;
+        }
+        // Single candidate - return it
+        if (candidates.length === 1) {
+            return candidates[0];
+        }
+        // Multiple candidates - try specific triggering rules first
+        for (const transition of candidates) {
+            if (transition.specificTriggeringRule) {
+                try {
+                    const func = new Function('event', 'context', `return ${transition.specificTriggeringRule}`);
+                    if (func(event, instanceContext)) {
+                        return transition;
+                    }
+                }
+                catch {
+                    // Rule evaluation failed, skip this transition
+                    continue;
+                }
+            }
+        }
+        // If no specific triggering rules matched, try matching rules
+        // This handles cases where multiple transitions differentiate by matching rules (e.g., different operators)
+        for (const transition of candidates) {
+            if (transition.matchingRules && transition.matchingRules.length > 0) {
+                // Create a mock instance to evaluate matching rules
+                const mockInstance = {
+                    id: 'temp',
+                    machineName: machine.name,
+                    currentState,
+                    context: instanceContext,
+                    publicMember: instanceContext,
+                    createdAt: Date.now(),
+                    updatedAt: Date.now(),
+                    status: 'active',
+                };
+                if (this.evaluateMatchingRules(mockInstance, event, transition.matchingRules)) {
+                    return transition;
+                }
+            }
+        }
+        // No rules matched - return first candidate (backward compatibility)
+        return candidates[0];
+    }
+    /**
+     * Evaluate guards
+     */
+    evaluateGuards(guards, event, context) {
+        return guards.every(guard => {
+            // Key matching
+            if (guard.keys) {
+                return guard.keys.every(key => event.payload[key] !== undefined);
+            }
+            // Contains check
+            if (guard.contains) {
+                return JSON.stringify(event.payload).includes(guard.contains);
+            }
+            // Custom function (evaluate as string - in production, use sandboxed eval)
+            if (guard.customFunction) {
+                try {
+                    const func = new Function('event', 'context', `return ${guard.customFunction}`);
+                    return func(event, context);
+                }
+                catch {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }
+    /**
+     * Execute transition
+     *
+     * Creates a Sender instance and passes it to triggered methods,
+     * enabling cross-instance communication (XComponent pattern)
+     */
+    async executeTransition(instance, transition, event) {
+        // In production, execute triggered methods here
+        if (transition.triggeredMethod) {
+            const sender = new SenderImpl(this, this.registry);
+            const instanceContext = instance.publicMember || instance.context;
+            this.emit('triggered_method', {
+                instanceId: instance.id,
+                method: transition.triggeredMethod,
+                event,
+                context: instanceContext,
+                sender,
+            });
+        }
+    }
+    /**
+     * Setup timeout transitions
+     */
+    /**
+     * Setup timeout transitions using timer wheel (performance optimized)
+     *
+     * Instead of creating one setTimeout per instance (O(n) timers),
+     * use a single timer wheel that manages all timeouts (O(1) timer).
+     */
+    setupTimeouts(instanceId, stateName) {
+        const instance = this.instances.get(instanceId);
+        if (!instance)
+            return;
+        const machine = this.machines.get(instance.machineName);
+        if (!machine)
+            return;
+        const timeoutTransitions = machine.transitions.filter(t => t.from === stateName && t.type === types_1.TransitionType.TIMEOUT);
+        timeoutTransitions.forEach(transition => {
+            if (transition.timeoutMs) {
+                const taskId = `${instanceId}-${stateName}-${transition.event}`;
+                // Track task for cleanup
+                if (!this.timeoutTasks.has(instanceId)) {
+                    this.timeoutTasks.set(instanceId, []);
+                }
+                this.timeoutTasks.get(instanceId).push(taskId);
+                // Use timer wheel instead of setTimeout
+                this.timerWheel.addTimeout(taskId, transition.timeoutMs, () => {
+                    // Check if instance still exists and is in the same state
+                    const currentInstance = this.instances.get(instanceId);
+                    if (currentInstance && currentInstance.currentState === stateName) {
+                        this.sendEvent(instanceId, {
+                            type: transition.event,
+                            payload: { reason: 'timeout' },
+                            timestamp: Date.now(),
+                        }).catch(error => {
+                            console.error(`Timeout event failed for ${instanceId}:`, error);
+                        });
+                    }
+                    // Remove taskId from tracking
+                    const tasks = this.timeoutTasks.get(instanceId);
+                    if (tasks) {
+                        const index = tasks.indexOf(taskId);
+                        if (index >= 0)
+                            tasks.splice(index, 1);
+                    }
+                });
+            }
+        });
+    }
+    /**
+     * Setup auto-transitions (XComponent-style automatic transitions)
+     *
+     * Auto-transitions are triggered automatically when entering a state,
+     * typically with timeoutMs: 0 for immediate execution.
+     *
+     * Example:
+     *   - from: Validated
+     *     to: Processing
+     *     event: AUTO_PROCESS
+     *     type: auto
+     *     timeoutMs: 0
+     */
+    setupAutoTransitions(instanceId, stateName) {
+        const instance = this.instances.get(instanceId);
+        if (!instance)
+            return;
+        const machine = this.machines.get(instance.machineName);
+        if (!machine)
+            return;
+        const autoTransitions = machine.transitions.filter(t => t.from === stateName && t.type === types_1.TransitionType.AUTO);
+        autoTransitions.forEach(transition => {
+            // Use publicMember if available (XComponent pattern), otherwise fallback to context
+            const instanceContext = instance.publicMember || instance.context;
+            // Check guards before scheduling auto-transition
+            if (transition.guards && !this.evaluateGuards(transition.guards, { type: transition.event, payload: {}, timestamp: Date.now() }, instanceContext)) {
+                return; // Guard failed, skip this auto-transition
+            }
+            const delay = transition.timeoutMs || 0; // Default to immediate (0ms)
+            const taskId = `${instanceId}-${stateName}-auto-${transition.event}`;
+            // Track task for cleanup
+            if (!this.timeoutTasks.has(instanceId)) {
+                this.timeoutTasks.set(instanceId, []);
+            }
+            this.timeoutTasks.get(instanceId).push(taskId);
+            // Use timer wheel for auto-transitions
+            this.timerWheel.addTimeout(taskId, delay, () => {
+                // Check if instance still exists and is in the same state
+                const currentInstance = this.instances.get(instanceId);
+                if (currentInstance && currentInstance.currentState === stateName) {
+                    this.sendEvent(instanceId, {
+                        type: transition.event,
+                        payload: { reason: 'auto-transition' },
+                        timestamp: Date.now(),
+                    }).catch(error => {
+                        console.error(`Auto-transition failed for ${instanceId}:`, error);
+                    });
+                }
+                // Remove taskId from tracking
+                const tasks = this.timeoutTasks.get(instanceId);
+                if (tasks) {
+                    const index = tasks.indexOf(taskId);
+                    if (index >= 0)
+                        tasks.splice(index, 1);
+                }
+            });
+        });
+    }
+    /**
+     * Setup cascading rules engine (XComponent pattern)
+     *
+     * Listens to state_change events and automatically triggers cross-machine updates
+     * based on cascading rules defined in state definitions.
+     */
+    setupCascadingEngine() {
+        this.on('state_change', async (data) => {
+            const { instanceId, newState } = data;
+            const instance = this.instances.get(instanceId);
+            if (!instance)
+                return;
+            const machine = this.machines.get(instance.machineName);
+            if (!machine)
+                return;
+            // Find the state definition
+            const state = machine.states.find(s => s.name === newState);
+            if (!state || !state.cascadingRules || state.cascadingRules.length === 0) {
+                return; // No cascading rules for this state
+            }
+            // Process each cascading rule
+            for (const rule of state.cascadingRules) {
+                try {
+                    await this.processCascadingRule(instance, rule);
+                }
+                catch (error) {
+                    this.emit('cascade_error', {
+                        sourceInstanceId: instanceId,
+                        rule,
+                        error: error.message,
+                    });
+                }
+            }
+        });
+    }
+    /**
+     * Add instance to indexes (for O(1) lookup)
+     * Performance optimization: XComponent hash-based matching
+     */
+    addToIndex(instance) {
+        const { id, machineName, currentState, publicMember, context } = instance;
+        // Machine index
+        if (!this.machineIndex.has(machineName)) {
+            this.machineIndex.set(machineName, new Set());
+        }
+        this.machineIndex.get(machineName).add(id);
+        // State index
+        const stateKey = `${machineName}:${currentState}`;
+        if (!this.stateIndex.has(stateKey)) {
+            this.stateIndex.set(stateKey, new Set());
+        }
+        this.stateIndex.get(stateKey).add(id);
+        // Property index (for commonly matched properties)
+        const instanceData = publicMember || context;
+        if (instanceData) {
+            // Index all top-level properties for fast matching
+            for (const [propName, propValue] of Object.entries(instanceData)) {
+                if (propValue !== null && propValue !== undefined) {
+                    const propKey = `${machineName}:${propName}:${String(propValue)}`;
+                    if (!this.propertyIndex.has(propKey)) {
+                        this.propertyIndex.set(propKey, new Set());
+                    }
+                    this.propertyIndex.get(propKey).add(id);
+                }
+            }
+        }
+    }
+    /**
+     * Remove instance from indexes
+     */
+    removeFromIndex(instance) {
+        const { id, machineName, currentState, publicMember, context } = instance;
+        // Machine index
+        this.machineIndex.get(machineName)?.delete(id);
+        // State index
+        const stateKey = `${machineName}:${currentState}`;
+        this.stateIndex.get(stateKey)?.delete(id);
+        // Property index
+        const instanceData = publicMember || context;
+        if (instanceData) {
+            for (const [propName, propValue] of Object.entries(instanceData)) {
+                if (propValue !== null && propValue !== undefined) {
+                    const propKey = `${machineName}:${propName}:${String(propValue)}`;
+                    this.propertyIndex.get(propKey)?.delete(id);
+                }
+            }
+        }
+    }
+    /**
+     * Update state index when state changes
+     */
+    updateIndexOnStateChange(instance, oldState, newState) {
+        const { id, machineName } = instance;
+        // Remove from old state index
+        const oldStateKey = `${machineName}:${oldState}`;
+        this.stateIndex.get(oldStateKey)?.delete(id);
+        // Add to new state index
+        const newStateKey = `${machineName}:${newState}`;
+        if (!this.stateIndex.has(newStateKey)) {
+            this.stateIndex.set(newStateKey, new Set());
+        }
+        this.stateIndex.get(newStateKey).add(id);
+    }
+    /**
+     * Process a single cascading rule
+     *
+     * Applies payload templating and broadcasts event to target instances
+     * If matchingRules exist, uses property-based routing
+     * Otherwise, sends to ALL instances in the target state
+     */
+    async processCascadingRule(sourceInstance, rule) {
+        // Get source context (publicMember or context)
+        const sourceContext = sourceInstance.publicMember || sourceInstance.context;
+        // Apply payload templating
+        const payload = rule.payload ? this.applyPayloadTemplate(rule.payload, sourceContext) : {};
+        const event = {
+            type: rule.event,
+            payload,
+            timestamp: Date.now(),
+        };
+        let processedCount = 0;
+        if (rule.matchingRules && rule.matchingRules.length > 0) {
+            // Use property-based routing
+            processedCount = await this.broadcastEvent(rule.targetMachine, rule.targetState, event);
+        }
+        else {
+            // No matching rules - send to ALL instances in target state
+            // Performance: Use state index instead of iterating all instances
+            const stateKey = `${rule.targetMachine}:${rule.targetState}`;
+            const candidateIds = this.stateIndex.get(stateKey);
+            if (candidateIds) {
+                for (const instanceId of candidateIds) {
+                    const instance = this.instances.get(instanceId);
+                    if (!instance || instance.status !== 'active')
+                        continue;
+                    try {
+                        await this.sendEvent(instance.id, event);
+                        processedCount++;
+                    }
+                    catch (error) {
+                        // Continue processing other instances even if one fails
+                        this.emit('cascade_error', {
+                            sourceInstanceId: sourceInstance.id,
+                            targetInstanceId: instance.id,
+                            error: error.message,
+                        });
+                    }
+                }
+            }
+        }
+        this.emit('cascade_completed', {
+            sourceInstanceId: sourceInstance.id,
+            targetMachine: rule.targetMachine,
+            targetState: rule.targetState,
+            event: rule.event,
+            processedCount,
+        });
+    }
+    /**
+     * Apply payload template with {{property}} syntax
+     *
+     * Replaces {{property}} with actual values from source context
+     *
+     * Example:
+     *   payload: { orderId: "{{Id}}", total: "{{Total}}" }
+     *   context: { Id: 42, Total: 99.99 }
+     *   result: { orderId: 42, total: 99.99 }
+     */
+    applyPayloadTemplate(template, context) {
+        const result = {};
+        for (const [key, value] of Object.entries(template)) {
+            if (typeof value === 'string' && value.startsWith('{{') && value.endsWith('}}')) {
+                // Extract property name: "{{Id}}" → "Id"
+                const propertyPath = value.slice(2, -2).trim();
+                result[key] = this.getNestedProperty(context, propertyPath);
+            }
+            else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                // Recursively apply template for nested objects
+                result[key] = this.applyPayloadTemplate(value, context);
+            }
+            else {
+                // Use value as-is
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Clear timeouts for instance (using timer wheel)
+     */
+    clearTimeouts(instanceId) {
+        const taskIds = this.timeoutTasks.get(instanceId);
+        if (taskIds) {
+            // Remove all timeout tasks for this instance
+            taskIds.forEach(taskId => {
+                this.timerWheel.removeTimeout(taskId);
+            });
+            this.timeoutTasks.delete(instanceId);
+        }
+    }
+    /**
+     * Get instance
+     */
+    getInstance(instanceId) {
+        return this.instances.get(instanceId);
+    }
+    /**
+     * Get all instances
+     */
+    getAllInstances() {
+        return Array.from(this.instances.values());
+    }
+    /**
+     * Get instances by machine
+     */
+    getInstancesByMachine(machineName) {
+        return Array.from(this.instances.values()).filter(i => i.machineName === machineName);
+    }
+    /**
+     * Simulate FSM path
+     */
+    simulatePath(machineName, events) {
+        const machine = this.machines.get(machineName);
+        if (!machine) {
+            return { success: false, path: [], error: `Machine ${machineName} not found` };
+        }
+        const path = [machine.initialState];
+        let currentState = machine.initialState;
+        const context = {};
+        for (const event of events) {
+            const transition = this.findTransition(machine, currentState, event, context);
+            if (!transition) {
+                return { success: false, path, error: `No transition from ${currentState} for event ${event.type}` };
+            }
+            if (transition.guards && !this.evaluateGuards(transition.guards, event, context)) {
+                return { success: false, path, error: `Guard failed for transition from ${currentState}` };
+            }
+            currentState = transition.to;
+            path.push(currentState);
+            const state = machine.states.find(s => s.name === currentState);
+            if (state && (state.type === types_1.StateType.FINAL || state.type === types_1.StateType.ERROR)) {
+                break;
+            }
+        }
+        return { success: true, path };
+    }
+    // ============================================================
+    // PHASE 4: PERSISTENCE & RESTORATION
+    // ============================================================
+    /**
+     * Restore all instances from snapshots (for long-running workflows)
+     *
+     * Called after restart to restore system state from persistence
+     *
+     * Example:
+     *   const runtime = new FSMRuntime(component, { snapshots: true });
+     *   await runtime.restore();
+     *   // System is now in same state as before restart
+     */
+    async restore() {
+        if (!this.persistence) {
+            throw new Error('Persistence is not enabled');
+        }
+        const snapshots = await this.persistence.getAllSnapshots();
+        let restored = 0;
+        let failed = 0;
+        for (const snapshot of snapshots) {
+            try {
+                const instance = snapshot.instance;
+                // Validate machine exists
+                if (!this.machines.has(instance.machineName)) {
+                    failed++;
+                    this.emit('restore_error', {
+                        instanceId: instance.id,
+                        error: `Machine ${instance.machineName} not found`,
+                    });
+                    continue;
+                }
+                // Restore instance
+                this.instances.set(instance.id, instance);
+                restored++;
+                this.emit('instance_restored', {
+                    instanceId: instance.id,
+                    machineName: instance.machineName,
+                    currentState: instance.currentState,
+                });
+            }
+            catch (error) {
+                failed++;
+                this.emit('restore_error', {
+                    instanceId: snapshot.instance.id,
+                    error: error.message,
+                });
+            }
+        }
+        // Resynchronize timeouts after restore
+        if (restored > 0) {
+            await this.resynchronizeTimeouts();
+        }
+        return { restored, failed };
+    }
+    /**
+     * Resynchronize timeouts after restart
+     *
+     * Recalculates timeout transitions based on current state and elapsed time
+     * Handles expired timeouts by triggering them immediately
+     */
+    async resynchronizeTimeouts() {
+        let synced = 0;
+        let expired = 0;
+        for (const [instanceId, instance] of this.instances.entries()) {
+            if (instance.status !== 'active') {
+                continue;
+            }
+            const machine = this.machines.get(instance.machineName);
+            if (!machine) {
+                continue;
+            }
+            // Find timeout transitions from current state
+            const timeoutTransitions = machine.transitions.filter(t => t.from === instance.currentState && t.type === types_1.TransitionType.TIMEOUT);
+            for (const transition of timeoutTransitions) {
+                if (!transition.timeoutMs) {
+                    continue;
+                }
+                // Calculate elapsed time since last update
+                const elapsedMs = Date.now() - instance.updatedAt;
+                const remainingMs = transition.timeoutMs - elapsedMs;
+                if (remainingMs <= 0) {
+                    // Timeout already expired - trigger immediately
+                    try {
+                        await this.sendEvent(instanceId, {
+                            type: transition.event,
+                            payload: { reason: 'timeout_expired_during_restart' },
+                            timestamp: Date.now(),
+                        });
+                        expired++;
+                    }
+                    catch (error) {
+                        this.emit('timeout_resync_error', {
+                            instanceId,
+                            error: error.message,
+                        });
+                    }
+                }
+                else {
+                    // Timeout still pending - reschedule with remaining time using timer wheel
+                    const taskId = `${instanceId}-${instance.currentState}-${transition.event}`;
+                    // Track task for cleanup
+                    if (!this.timeoutTasks.has(instanceId)) {
+                        this.timeoutTasks.set(instanceId, []);
+                    }
+                    this.timeoutTasks.get(instanceId).push(taskId);
+                    this.timerWheel.addTimeout(taskId, remainingMs, () => {
+                        const currentInstance = this.instances.get(instanceId);
+                        if (currentInstance && currentInstance.currentState === instance.currentState) {
+                            this.sendEvent(instanceId, {
+                                type: transition.event,
+                                payload: { reason: 'timeout' },
+                                timestamp: Date.now(),
+                            }).catch(error => {
+                                console.error(`Timeout resync failed for ${instanceId}:`, error);
+                            });
+                        }
+                        // Remove taskId from tracking
+                        const tasks = this.timeoutTasks.get(instanceId);
+                        if (tasks) {
+                            const index = tasks.indexOf(taskId);
+                            if (index >= 0)
+                                tasks.splice(index, 1);
+                        }
+                    });
+                    synced++;
+                }
+            }
+            // Resynchronize auto-transitions (should trigger immediately if not already transitioned)
+            const autoTransitions = machine.transitions.filter(t => t.from === instance.currentState && t.type === types_1.TransitionType.AUTO);
+            for (const transition of autoTransitions) {
+                // Use publicMember if available (XComponent pattern), otherwise fallback to context
+                const instanceContext = instance.publicMember || instance.context;
+                // Check guards before scheduling auto-transition
+                if (transition.guards && !this.evaluateGuards(transition.guards, { type: transition.event, payload: {}, timestamp: Date.now() }, instanceContext)) {
+                    continue; // Guard failed, skip this auto-transition
+                }
+                const delay = transition.timeoutMs || 0;
+                // Calculate elapsed time
+                const elapsedMs = Date.now() - instance.updatedAt;
+                const remainingMs = Math.max(0, delay - elapsedMs);
+                const taskId = `${instanceId}-${instance.currentState}-auto-${transition.event}`;
+                // Track task for cleanup
+                if (!this.timeoutTasks.has(instanceId)) {
+                    this.timeoutTasks.set(instanceId, []);
+                }
+                this.timeoutTasks.get(instanceId).push(taskId);
+                this.timerWheel.addTimeout(taskId, remainingMs, () => {
+                    const currentInstance = this.instances.get(instanceId);
+                    if (currentInstance && currentInstance.currentState === instance.currentState) {
+                        this.sendEvent(instanceId, {
+                            type: transition.event,
+                            payload: { reason: 'auto-transition' },
+                            timestamp: Date.now(),
+                        }).catch(error => {
+                            console.error(`Auto-transition resync failed for ${instanceId}:`, error);
+                        });
+                    }
+                    // Remove taskId from tracking
+                    const tasks = this.timeoutTasks.get(instanceId);
+                    if (tasks) {
+                        const index = tasks.indexOf(taskId);
+                        if (index >= 0)
+                            tasks.splice(index, 1);
+                    }
+                });
+                synced++;
+            }
+        }
+        return { synced, expired };
+    }
+    /**
+     * Get persistence manager (for testing/inspection)
+     */
+    getPersistenceManager() {
+        return this.persistence;
+    }
+    /**
+     * Get instance event history (for audit/debug)
+     */
+    async getInstanceHistory(instanceId) {
+        if (!this.persistence) {
+            return [];
+        }
+        return await this.persistence.getInstanceEvents(instanceId);
+    }
+    /**
+     * Get all persisted events for this component
+     */
+    async getAllPersistedEvents() {
+        if (!this.persistence) {
+            return [];
+        }
+        return await this.persistence.getAllEvents();
+    }
+    /**
+     * Trace event causality chain (for debugging cascades/sender)
+     */
+    async traceEventCausality(eventId) {
+        if (!this.persistence) {
+            return [];
+        }
+        return await this.persistence.traceEventCausality(eventId);
+    }
+    /**
+     * Get component definition
+     */
+    getComponent() {
+        return this.componentDef;
+    }
+    /**
+     * Set component registry for cross-component communication
+     */
+    setRegistry(registry) {
+        this.registry = registry;
+    }
+    /**
+     * Get available transitions from current state of an instance
+     */
+    getAvailableTransitions(instanceId) {
+        const instance = this.getInstance(instanceId);
+        if (!instance) {
+            return [];
+        }
+        const machine = this.machines.get(instance.machineName);
+        if (!machine) {
+            return [];
+        }
+        // Find all transitions from current state
+        return machine.transitions.filter(t => t.from === instance.currentState);
+    }
+    /**
+     * Stop the runtime and cleanup resources
+     * Important: Call this when done to prevent memory leaks from timer wheel
+     */
+    dispose() {
+        // Stop timer wheel
+        this.timerWheel.stop();
+        // Clear all instances
+        this.instances.clear();
+        this.timeoutTasks.clear();
+        // Clear indexes
+        this.machineIndex.clear();
+        this.stateIndex.clear();
+        this.propertyIndex.clear();
+        // Remove all event listeners
+        this.removeAllListeners();
+    }
+}
+exports.FSMRuntime = FSMRuntime;
+/**
+ * Load component from object
+ */
+function loadComponent(data) {
+    return data;
+}
+//# sourceMappingURL=fsm-runtime.js.map