xcomponent-ai 0.1.1

package/dist/component-registry.js

@@ -0,0 +1,382 @@
+"use strict";
+/**
+ * Component Registry for Cross-Component Communication
+ *
+ * Manages multiple FSMRuntimes (components) and enables communication
+ * between them, reproducing XComponent's cross-component messaging pattern.
+ *
+ * Features:
+ * - Register/unregister components
+ * - Route events between components
+ * - Broadcast across components
+ * - Property-based routing across component boundaries
+ * - Instance lookup across all components
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComponentRegistry = void 0;
+const events_1 = require("events");
+/**
+ * ComponentRegistry manages multiple components and enables cross-component communication
+ */
+class ComponentRegistry extends events_1.EventEmitter {
+    runtimes;
+    components;
+    constructor() {
+        super();
+        this.runtimes = new Map();
+        this.components = new Map();
+    }
+    /**
+     * Register a component with its runtime
+     *
+     * @param component Component definition
+     * @param runtime FSM runtime instance
+     */
+    registerComponent(component, runtime) {
+        if (this.runtimes.has(component.name)) {
+            throw new Error(`Component ${component.name} is already registered`);
+        }
+        this.runtimes.set(component.name, runtime);
+        this.components.set(component.name, component);
+        // Forward runtime events
+        this.forwardRuntimeEvents(component.name, runtime);
+        this.emit('component_registered', {
+            componentName: component.name,
+            version: component.version,
+            machineCount: component.stateMachines.length,
+        });
+    }
+    /**
+     * Unregister a component
+     *
+     * @param componentName Component name
+     */
+    unregisterComponent(componentName) {
+        const runtime = this.runtimes.get(componentName);
+        if (!runtime) {
+            throw new Error(`Component ${componentName} not found`);
+        }
+        // Cleanup runtime
+        runtime.dispose();
+        this.runtimes.delete(componentName);
+        this.components.delete(componentName);
+        this.emit('component_unregistered', { componentName });
+    }
+    /**
+     * Get runtime for a component
+     *
+     * @param componentName Component name
+     * @returns FSMRuntime or undefined
+     */
+    getRuntime(componentName) {
+        return this.runtimes.get(componentName);
+    }
+    /**
+     * Get component definition
+     *
+     * @param componentName Component name
+     * @returns Component or undefined
+     */
+    getComponent(componentName) {
+        return this.components.get(componentName);
+    }
+    /**
+     * Check if component is registered
+     *
+     * @param componentName Component name
+     * @returns true if registered
+     */
+    hasComponent(componentName) {
+        return this.runtimes.has(componentName);
+    }
+    /**
+     * Get all registered component names
+     *
+     * @returns Array of component names
+     */
+    getComponentNames() {
+        return Array.from(this.runtimes.keys());
+    }
+    /**
+     * Get component information
+     *
+     * @param componentName Component name
+     * @returns Component info or undefined
+     */
+    getComponentInfo(componentName) {
+        const runtime = this.runtimes.get(componentName);
+        const component = this.components.get(componentName);
+        if (!runtime || !component) {
+            return undefined;
+        }
+        return {
+            name: component.name,
+            runtime,
+            version: component.version,
+            machineCount: component.stateMachines.length,
+            instanceCount: runtime.getAllInstances().length,
+        };
+    }
+    /**
+     * Get all component information
+     *
+     * @returns Array of component info
+     */
+    getAllComponentInfo() {
+        return this.getComponentNames()
+            .map(name => this.getComponentInfo(name))
+            .filter((info) => info !== undefined);
+    }
+    /**
+     * Send event to instance in any component
+     *
+     * @param componentName Target component name
+     * @param instanceId Instance ID
+     * @param event Event to send
+     */
+    async sendEventToComponent(componentName, instanceId, event) {
+        const runtime = this.runtimes.get(componentName);
+        if (!runtime) {
+            throw new Error(`Component ${componentName} not found`);
+        }
+        await runtime.sendEvent(instanceId, event);
+    }
+    /**
+     * Broadcast event to instances in a specific component
+     *
+     * @param componentName Target component name
+     * @param machineName Target machine name
+     * @param currentState Current state filter
+     * @param event Event to broadcast
+     * @returns Number of instances processed
+     */
+    async broadcastToComponent(componentName, machineName, currentState, event) {
+        const runtime = this.runtimes.get(componentName);
+        if (!runtime) {
+            throw new Error(`Component ${componentName} not found`);
+        }
+        return await runtime.broadcastEvent(machineName, currentState, event);
+    }
+    /**
+     * Broadcast event to all components
+     *
+     * Useful for system-wide notifications (e.g., shutdown, maintenance mode)
+     *
+     * @param machineName Target machine name
+     * @param currentState Current state filter
+     * @param event Event to broadcast
+     * @returns Total number of instances processed across all components
+     */
+    async broadcastToAll(machineName, currentState, event) {
+        let total = 0;
+        for (const [componentName, runtime] of this.runtimes) {
+            try {
+                const count = await runtime.broadcastEvent(machineName, currentState, event);
+                total += count;
+            }
+            catch (error) {
+                this.emit('broadcast_error', {
+                    componentName,
+                    machineName,
+                    currentState,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return total;
+    }
+    /**
+     * Create instance in a specific component
+     *
+     * @param componentName Target component name
+     * @param machineName Machine name
+     * @param initialContext Initial context
+     * @returns Instance ID
+     */
+    createInstanceInComponent(componentName, machineName, initialContext) {
+        const runtime = this.runtimes.get(componentName);
+        if (!runtime) {
+            throw new Error(`Component ${componentName} not found`);
+        }
+        return runtime.createInstance(machineName, initialContext);
+    }
+    /**
+     * Find instance by ID across all components
+     *
+     * @param instanceId Instance ID
+     * @returns Instance and component name, or undefined
+     */
+    findInstance(instanceId) {
+        for (const [componentName, runtime] of this.runtimes) {
+            const instance = runtime.getInstance(instanceId);
+            if (instance) {
+                return { instance, componentName };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get all instances across all components
+     *
+     * @returns Array of instances with component name
+     */
+    getAllInstances() {
+        const result = [];
+        for (const [componentName, runtime] of this.runtimes) {
+            const instances = runtime.getAllInstances();
+            instances.forEach(instance => {
+                result.push({ instance, componentName });
+            });
+        }
+        return result;
+    }
+    /**
+     * Get statistics across all components
+     *
+     * @returns Registry statistics
+     */
+    getStats() {
+        const components = this.getAllComponentInfo();
+        return {
+            componentCount: components.length,
+            totalInstances: components.reduce((sum, c) => sum + c.instanceCount, 0),
+            totalMachines: components.reduce((sum, c) => sum + c.machineCount, 0),
+            components: components.map(c => ({
+                name: c.name,
+                instances: c.instanceCount,
+                machines: c.machineCount,
+            })),
+        };
+    }
+    /**
+     * Trace event causality across all components
+     *
+     * Follows event chains across component boundaries to show
+     * complete system-wide workflows
+     *
+     * @param eventId Starting event ID
+     * @returns Array of persisted events showing full causality chain
+     */
+    async traceEventAcrossComponents(eventId) {
+        const allEvents = [];
+        const eventMap = new Map();
+        // Collect all events from all components
+        for (const [, runtime] of this.runtimes) {
+            try {
+                const events = await runtime.getAllPersistedEvents();
+                events.forEach(event => {
+                    eventMap.set(event.id, event);
+                    allEvents.push(event);
+                });
+            }
+            catch {
+                // Component may not have persistence enabled, skip
+                continue;
+            }
+        }
+        // Build causality chain
+        const result = [];
+        const visited = new Set();
+        const trace = (id) => {
+            if (visited.has(id))
+                return;
+            visited.add(id);
+            const event = eventMap.get(id);
+            if (!event)
+                return;
+            result.push(event);
+            // Trace caused events recursively
+            if (event.caused && event.caused.length > 0) {
+                for (const causedId of event.caused) {
+                    trace(causedId);
+                }
+            }
+        };
+        trace(eventId);
+        return result;
+    }
+    /**
+     * Get all persisted events across all components
+     *
+     * Useful for system-wide analysis, debugging, and monitoring
+     *
+     * @returns Array of all persisted events from all components
+     */
+    async getAllPersistedEvents() {
+        const eventMap = new Map();
+        for (const [, runtime] of this.runtimes) {
+            try {
+                const events = await runtime.getAllPersistedEvents();
+                // Deduplicate by event ID (in case components share event store)
+                events.forEach(event => eventMap.set(event.id, event));
+            }
+            catch {
+                // Component may not have persistence enabled, skip
+                continue;
+            }
+        }
+        // Convert to array and sort by timestamp
+        return Array.from(eventMap.values()).sort((a, b) => a.persistedAt - b.persistedAt);
+    }
+    /**
+     * Get persisted events for a specific instance across components
+     *
+     * @param instanceId Instance ID to query
+     * @returns Array of persisted events for the instance
+     */
+    async getInstanceHistory(instanceId) {
+        for (const [, runtime] of this.runtimes) {
+            try {
+                const instance = runtime.getInstance(instanceId);
+                if (instance) {
+                    return await runtime.getInstanceHistory(instanceId);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return [];
+    }
+    /**
+     * Forward runtime events to registry
+     */
+    forwardRuntimeEvents(componentName, runtime) {
+        // Forward all runtime events with component context
+        const eventsToForward = [
+            'state_change',
+            'instance_created',
+            'instance_disposed',
+            'instance_error',
+            'guard_failed',
+            'cascade_completed',
+            'cascade_error',
+        ];
+        eventsToForward.forEach(eventName => {
+            runtime.on(eventName, (data) => {
+                this.emit(eventName, {
+                    ...data,
+                    componentName,
+                });
+            });
+        });
+    }
+    /**
+     * Dispose all components and cleanup
+     */
+    dispose() {
+        for (const [componentName, runtime] of this.runtimes) {
+            try {
+                runtime.dispose();
+            }
+            catch (error) {
+                console.error(`Error disposing component ${componentName}:`, error);
+            }
+        }
+        this.runtimes.clear();
+        this.components.clear();
+        this.removeAllListeners();
+    }
+}
+exports.ComponentRegistry = ComponentRegistry;
+//# sourceMappingURL=component-registry.js.map

package/dist/component-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-registry.js","sourceRoot":"","sources":["../src/component-registry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,mCAAsC;AAYtC;;GAEG;AACH,MAAa,iBAAkB,SAAQ,qBAAY;IACzC,QAAQ,CAA0B;IAClC,UAAU,CAAyB;IAE3C;QACE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,SAAoB,EAAE,OAAmB;QACzD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,aAAa,SAAS,CAAC,IAAI,wBAAwB,CAAC,CAAC;QACvE,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAE/C,yBAAyB;QACzB,IAAI,CAAC,oBAAoB,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAEnD,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE;YAChC,aAAa,EAAE,SAAS,CAAC,IAAI;YAC7B,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,YAAY,EAAE,SAAS,CAAC,aAAa,CAAC,MAAM;SAC7C,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,aAAqB;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,aAAa,aAAa,YAAY,CAAC,CAAC;QAC1D,CAAC;QAED,kBAAkB;QAClB,OAAO,CAAC,OAAO,EAAE,CAAC;QAElB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QACpC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QAEtC,IAAI,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IACzD,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,aAAqB;QAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,aAAqB;QAChC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,aAAqB;QAChC,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,iBAAiB;QACf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,aAAqB;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAErD,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;YAC3B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO;YACL,IAAI,EAAE,SAAS,CAAC,IAAI;YACpB,OAAO;YACP,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,YAAY,EAAE,SAAS,CAAC,aAAa,CAAC,MAAM;YAC5C,aAAa,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,MAAM;SAChD,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,mBAAmB;QACjB,OAAO,IAAI,CAAC,iBAAiB,EAAE;aAC5B,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;aACxC,MAAM,CAAC,CAAC,IAAI,EAAyB,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,oBAAoB,CACxB,aAAqB,EACrB,UAAkB,EAClB,KAAe;QAEf,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,aAAa,aAAa,YAAY,CAAC,CAAC;QAC1D,CAAC;QAED,MAAM,OAAO,CAAC,SAAS,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,oBAAoB,CACxB,aAAqB,EACrB,WAAmB,EACnB,YAAoB,EACpB,KAAe;QAEf,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,aAAa,aAAa,YAAY,CAAC,CAAC;QAC1D,CAAC;QAED,OAAO,MAAM,OAAO,CAAC,cAAc,CAAC,WAAW,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,cAAc,CAClB,WAAmB,EACnB,YAAoB,EACpB,KAAe;QAEf,IAAI,KAAK,GAAG,CAAC,CAAC;QAEd,KAAK,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrD,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,WAAW,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;gBAC7E,KAAK,IAAI,KAAK,CAAC;YACjB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE;oBAC3B,aAAa;oBACb,WAAW;oBACX,YAAY;oBACZ,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAC9D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,yBAAyB,CACvB,aAAqB,EACrB,WAAmB,EACnB,cAAmC;QAEnC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,aAAa,aAAa,YAAY,CAAC,CAAC;QAC1D,CAAC;QAED,OAAO,OAAO,CAAC,cAAc,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,UAAkB;QAC7B,KAAK,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrD,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;YACjD,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;YACrC,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACH,eAAe;QACb,MAAM,MAAM,GAA4D,EAAE,CAAC;QAE3E,KAAK,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrD,MAAM,SAAS,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;YAC5C,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAC3B,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,QAAQ;QAMN,MAAM,UAAU,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAE9C,OAAO;YACL,cAAc,EAAE,UAAU,CAAC,MAAM;YACjC,cAAc,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC;YACvE,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;YACrE,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBAC/B,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,SAAS,EAAE,CAAC,CAAC,aAAa;gBAC1B,QAAQ,EAAE,CAAC,CAAC,YAAY;aACzB,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,0BAA0B,CAAC,OAAe;QAC9C,MAAM,SAAS,GAAuC,EAAE,CAAC;QACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA4C,CAAC;QAErE,yCAAyC;QACzC,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,qBAAqB,EAAE,CAAC;gBACrD,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;oBACrB,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;oBAC9B,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACxB,CAAC,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,mDAAmD;gBACnD,SAAS;YACX,CAAC;QACH,CAAC;QAED,wBAAwB;QACxB,MAAM,MAAM,GAAuC,EAAE,CAAC;QACtD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAElC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAE;YAC3B,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,OAAO;YAC5B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAEhB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC/B,IAAI,CAAC,KAAK;gBAAE,OAAO;YAEnB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAEnB,kCAAkC;YAClC,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5C,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;oBACpC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAClB,CAAC;YACH,CAAC;QACH,CAAC,CAAC;QAEF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,qBAAqB;QACzB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA4C,CAAC;QAErE,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,qBAAqB,EAAE,CAAC;gBACrD,iEAAiE;gBACjE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;YACzD,CAAC;YAAC,MAAM,CAAC;gBACP,mDAAmD;gBACnD,SAAS;YACX,CAAC;QACH,CAAC;QAED,yCAAyC;QACzC,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IACrF,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,kBAAkB,CAAC,UAAkB;QACzC,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxC,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;gBACjD,IAAI,QAAQ,EAAE,CAAC;oBACb,OAAO,MAAM,OAAO,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC;gBACtD,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;QACH,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;OAEG;IACK,oBAAoB,CAAC,aAAqB,EAAE,OAAmB;QACrE,oDAAoD;QACpD,MAAM,eAAe,GAAG;YACtB,cAAc;YACd,kBAAkB;YAClB,mBAAmB;YACnB,gBAAgB;YAChB,cAAc;YACd,mBAAmB;YACnB,eAAe;SAChB,CAAC;QAEF,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE;YAClC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAS,EAAE,EAAE;gBAClC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE;oBACnB,GAAG,IAAI;oBACP,aAAa;iBACd,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,OAAO;QACL,KAAK,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrD,IAAI,CAAC;gBACH,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,6BAA6B,aAAa,GAAG,EAAE,KAAK,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC5B,CAAC;CACF;AAvaD,8CAuaC"}

package/dist/fsm-runtime.d.ts

@@ -0,0 +1,263 @@
+/**
+ * FSM Runtime Engine
+ * Implements XComponent-inspired state machine execution with multi-instance support
+ */
+import { EventEmitter } from 'events';
+import { Component, Transition, FSMEvent, FSMInstance, PersistenceConfig } from './types';
+import { PersistenceManager } from './persistence';
+import type { ComponentRegistry } from './component-registry';
+/**
+ * FSM Runtime Engine
+ * Manages multiple FSM instances with event-driven execution
+ */
+export declare class FSMRuntime extends EventEmitter {
+    private instances;
+    private machines;
+    private timerWheel;
+    private timeoutTasks;
+    private persistence;
+    private componentDef;
+    private registry?;
+    private machineIndex;
+    private stateIndex;
+    private propertyIndex;
+    constructor(component: Component, persistenceConfig?: PersistenceConfig);
+    /**
+     * 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: string, initialContext?: Record<string, any>): string;
+    /**
+     * Send event to an instance
+     */
+    sendEvent(instanceId: string, event: FSMEvent): Promise<void>;
+    /**
+     * 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
+     */
+    broadcastEvent(machineName: string, currentState: string, event: FSMEvent): Promise<number>;
+    /**
+     * 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
+     */
+    private findMatchingInstances;
+    /**
+     * 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
+     */
+    private evaluateMatchingRules;
+    /**
+     * 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
+     */
+    private getNestedProperty;
+    /**
+     * 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
+     */
+    private findTransition;
+    /**
+     * Evaluate guards
+     */
+    private evaluateGuards;
+    /**
+     * Execute transition
+     *
+     * Creates a Sender instance and passes it to triggered methods,
+     * enabling cross-instance communication (XComponent pattern)
+     */
+    private executeTransition;
+    /**
+     * 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).
+     */
+    private setupTimeouts;
+    /**
+     * 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
+     */
+    private setupAutoTransitions;
+    /**
+     * 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.
+     */
+    private setupCascadingEngine;
+    /**
+     * Add instance to indexes (for O(1) lookup)
+     * Performance optimization: XComponent hash-based matching
+     */
+    private addToIndex;
+    /**
+     * Remove instance from indexes
+     */
+    private removeFromIndex;
+    /**
+     * Update state index when state changes
+     */
+    private updateIndexOnStateChange;
+    /**
+     * 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
+     */
+    private processCascadingRule;
+    /**
+     * 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 }
+     */
+    private applyPayloadTemplate;
+    /**
+     * Clear timeouts for instance (using timer wheel)
+     */
+    private clearTimeouts;
+    /**
+     * Get instance
+     */
+    getInstance(instanceId: string): FSMInstance | undefined;
+    /**
+     * Get all instances
+     */
+    getAllInstances(): FSMInstance[];
+    /**
+     * Get instances by machine
+     */
+    getInstancesByMachine(machineName: string): FSMInstance[];
+    /**
+     * Simulate FSM path
+     */
+    simulatePath(machineName: string, events: FSMEvent[]): {
+        success: boolean;
+        path: string[];
+        error?: string;
+    };
+    /**
+     * 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
+     */
+    restore(): Promise<{
+        restored: number;
+        failed: number;
+    }>;
+    /**
+     * Resynchronize timeouts after restart
+     *
+     * Recalculates timeout transitions based on current state and elapsed time
+     * Handles expired timeouts by triggering them immediately
+     */
+    resynchronizeTimeouts(): Promise<{
+        synced: number;
+        expired: number;
+    }>;
+    /**
+     * Get persistence manager (for testing/inspection)
+     */
+    getPersistenceManager(): PersistenceManager | null;
+    /**
+     * Get instance event history (for audit/debug)
+     */
+    getInstanceHistory(instanceId: string): Promise<import('./types').PersistedEvent[]>;
+    /**
+     * Get all persisted events for this component
+     */
+    getAllPersistedEvents(): Promise<import('./types').PersistedEvent[]>;
+    /**
+     * Trace event causality chain (for debugging cascades/sender)
+     */
+    traceEventCausality(eventId: string): Promise<import('./types').PersistedEvent[]>;
+    /**
+     * Get component definition
+     */
+    getComponent(): Component;
+    /**
+     * Set component registry for cross-component communication
+     */
+    setRegistry(registry: ComponentRegistry): void;
+    /**
+     * Get available transitions from current state of an instance
+     */
+    getAvailableTransitions(instanceId: string): Transition[];
+    /**
+     * Stop the runtime and cleanup resources
+     * Important: Call this when done to prevent memory leaks from timer wheel
+     */
+    dispose(): void;
+}
+/**
+ * Load component from object
+ */
+export declare function loadComponent(data: any): Component;
+//# sourceMappingURL=fsm-runtime.d.ts.map

package/dist/fsm-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsm-runtime.d.ts","sourceRoot":"","sources":["../src/fsm-runtime.ts"],"names":[],"mappings":"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"}