@higher.archi/boe 1.0.0

package/src/engines/state-machine/compiler.ts

@@ -0,0 +1,266 @@
+/**
+ * State Machine Engine Compiler
+ *
+ * Compiles state machine definitions into an optimized format for execution.
+ */
+
+import { compileCondition } from '../../core';
+
+import {
+  StateMachineDefinition,
+  StateMachineConfig,
+  StateDefinition,
+  StateTransition,
+  StateMachineActionItem,
+  CompiledStateMachineDefinition,
+  CompiledStateDefinition,
+  CompiledTransition,
+  CompiledStateMachineAction
+} from './types';
+
+// ========================================
+// Default Configuration
+// ========================================
+
+const DEFAULT_CONFIG: StateMachineConfig = {
+  mode: 'state-machine',
+  strict: true,
+  maxHistory: 100
+};
+
+// ========================================
+// Action Compilation
+// ========================================
+
+function compileAction(action: StateMachineActionItem): CompiledStateMachineAction {
+  // { set: { path: value, ... } }
+  if ('set' in action) {
+    const assignments: Array<{ path: string[]; value: any }> = [];
+    for (const [path, value] of Object.entries(action.set)) {
+      assignments.push({
+        path: path.split('.'),
+        value
+      });
+    }
+    return { type: 'set', assignments };
+  }
+
+  // { emit: 'EventName', data?: {...} }
+  if ('emit' in action) {
+    return {
+      type: 'emit',
+      event: action.emit,
+      data: action.data
+    };
+  }
+
+  // { call: 'handlerName' }
+  if ('call' in action) {
+    return {
+      type: 'call',
+      handler: action.call
+    };
+  }
+
+  // { log: 'message' }
+  if ('log' in action) {
+    return {
+      type: 'log',
+      message: action.log
+    };
+  }
+
+  throw new Error(`Unknown action format: ${JSON.stringify(action)}`);
+}
+
+function compileActions(actions?: StateMachineActionItem[]): CompiledStateMachineAction[] {
+  if (!actions) return [];
+  return actions.map(compileAction);
+}
+
+// ========================================
+// Transition Compilation
+// ========================================
+
+function compileTransition(transition: StateTransition): CompiledTransition {
+  return {
+    event: transition.event,
+    target: transition.target,
+    guard: transition.guard ? compileCondition(transition.guard) : undefined,
+    actions: compileActions(transition.actions)
+  };
+}
+
+// ========================================
+// State Compilation
+// ========================================
+
+function compileState(
+  name: string,
+  state: StateDefinition,
+  parent?: string
+): CompiledStateDefinition {
+  const transitions = (state.transitions ?? []).map(compileTransition);
+
+  // Collect all valid events from this state
+  const validEvents = transitions.map(t => t.event);
+
+  const compiled: CompiledStateDefinition = {
+    name,
+    type: state.type,
+    initial: state.initial,
+    transitions,
+    onEnter: compileActions(state.onEnter),
+    onExit: compileActions(state.onExit),
+    validEvents,
+    parent
+  };
+
+  // Compile nested states if present
+  if (state.states) {
+    compiled.states = {};
+    for (const [childName, childState] of Object.entries(state.states)) {
+      compiled.states[childName] = compileState(childName, childState, name);
+    }
+  }
+
+  return compiled;
+}
+
+// ========================================
+// State Map Building (Flattening)
+// ========================================
+
+function buildStateMap(
+  states: Record<string, CompiledStateDefinition>,
+  prefix: string = ''
+): Map<string, CompiledStateDefinition> {
+  const map = new Map<string, CompiledStateDefinition>();
+
+  for (const [name, state] of Object.entries(states)) {
+    const fullName = prefix ? `${prefix}.${name}` : name;
+    map.set(fullName, state);
+
+    // Recursively add nested states
+    if (state.states) {
+      const nestedMap = buildStateMap(state.states, fullName);
+      for (const [nestedName, nestedState] of nestedMap) {
+        map.set(nestedName, nestedState);
+      }
+    }
+  }
+
+  return map;
+}
+
+// ========================================
+// Validation
+// ========================================
+
+function validateStateMachine(definition: StateMachineDefinition): void {
+  // Check initial state exists
+  if (!definition.states[definition.initial]) {
+    throw new Error(`Initial state '${definition.initial}' does not exist`);
+  }
+
+  // Validate all transition targets exist
+  const allStateNames = new Set<string>();
+
+  function collectStateNames(states: Record<string, StateDefinition>, prefix: string = '') {
+    for (const [name, state] of Object.entries(states)) {
+      const fullName = prefix ? `${prefix}.${name}` : name;
+      allStateNames.add(fullName);
+
+      if (state.states) {
+        collectStateNames(state.states, fullName);
+      }
+    }
+  }
+
+  collectStateNames(definition.states);
+
+  function validateTransitions(states: Record<string, StateDefinition>, prefix: string = '') {
+    for (const [name, state] of Object.entries(states)) {
+      const fullName = prefix ? `${prefix}.${name}` : name;
+
+      for (const transition of state.transitions ?? []) {
+        // Handle special target syntax (e.g., '#stateName' for root-level reference)
+        let target = transition.target;
+        if (target.startsWith('#')) {
+          target = target.slice(1);
+        }
+
+        // Check if target is relative or absolute
+        const possibleTargets = [
+          target,
+          prefix ? `${prefix}.${target}` : target,
+          // Also check siblings
+          ...(prefix ? [`${prefix}.${target}`] : [])
+        ];
+
+        const targetExists = possibleTargets.some(t => allStateNames.has(t));
+
+        if (!targetExists && !allStateNames.has(target)) {
+          throw new Error(
+            `Invalid transition target '${transition.target}' from state '${fullName}'`
+          );
+        }
+      }
+
+      // Validate compound state has initial
+      if (state.states && !state.initial) {
+        throw new Error(`Compound state '${fullName}' must have an 'initial' property`);
+      }
+
+      // Recursively validate nested states
+      if (state.states) {
+        validateTransitions(state.states, fullName);
+      }
+    }
+  }
+
+  validateTransitions(definition.states);
+}
+
+// ========================================
+// Main Compiler Function
+// ========================================
+
+/**
+ * Compile a state machine definition into an optimized format
+ */
+export function compileStateMachine(
+  definition: StateMachineDefinition
+): CompiledStateMachineDefinition {
+  // Validate the definition
+  validateStateMachine(definition);
+
+  // Merge config with defaults
+  const config: StateMachineConfig = {
+    ...DEFAULT_CONFIG,
+    ...definition.config
+  };
+
+  // Compile all states
+  const compiledStates: Record<string, CompiledStateDefinition> = {};
+  for (const [name, state] of Object.entries(definition.states)) {
+    compiledStates[name] = compileState(name, state);
+  }
+
+  // Build flattened state map for quick lookups
+  const stateMap = buildStateMap(compiledStates);
+
+  return {
+    id: definition.id,
+    name: definition.name,
+    mode: 'state-machine',
+    initial: definition.initial,
+    initialContext: definition.context ?? {},
+    states: compiledStates,
+    stateMap,
+    config
+  };
+}
+
+// Alias for consistency with other engines
+export const compileStateMachineDefinition = compileStateMachine;

package/src/engines/state-machine/engine.ts

@@ -0,0 +1,128 @@
+/**
+ * State Machine Engine
+ *
+ * Manages state machine definitions and creates instances.
+ * Unlike other engines, state machines don't use working memory directly -
+ * each instance maintains its own state and context.
+ */
+
+import {
+  CompiledStateMachineDefinition,
+  StateMachineOptions,
+  MachineSnapshot,
+  IStateMachineInstance
+} from './types';
+
+import { StateMachineStrategy } from './strategy';
+
+/**
+ * State Machine Engine
+ *
+ * Creates and manages state machine instances. State machines track entity
+ * lifecycles through defined states and transitions.
+ *
+ * Unlike other engines (Forward, Sequential, etc.), state machines:
+ * - Don't use working memory for matching
+ * - Maintain their own state and context per instance
+ * - Are event-driven rather than fact-driven
+ * - Can be persisted and restored
+ *
+ * @example
+ * ```typescript
+ * const engine = new StateMachineEngine();
+ *
+ * // Create a new order state machine
+ * const order = engine.create(compiledOrderMachine, {
+ *   context: { orderId: 'ORD-123' }
+ * });
+ *
+ * console.log(order.state);        // 'pending'
+ * console.log(order.can('PAY'));   // true
+ *
+ * order.send('PAY', { amount: 99.99 });
+ * console.log(order.state);        // 'paid'
+ *
+ * // Persist and restore later
+ * const snapshot = order.snapshot();
+ * await db.save(snapshot);
+ *
+ * // ... later ...
+ * const savedSnapshot = await db.load();
+ * const restored = engine.restore(compiledOrderMachine, savedSnapshot);
+ * console.log(restored.state);     // 'paid'
+ * ```
+ */
+export class StateMachineEngine {
+  private strategy: StateMachineStrategy;
+  private defaultOptions: StateMachineOptions;
+
+  constructor(options: StateMachineOptions = {}) {
+    this.strategy = new StateMachineStrategy();
+    this.defaultOptions = options;
+  }
+
+  /**
+   * Create a new state machine instance
+   *
+   * @param definition - Compiled state machine definition
+   * @param options - Runtime options (actions, callbacks)
+   * @returns A new state machine instance
+   */
+  create(
+    definition: CompiledStateMachineDefinition,
+    options: StateMachineOptions = {}
+  ): IStateMachineInstance {
+    const mergedOptions = { ...this.defaultOptions, ...options };
+    return this.strategy.create(definition, mergedOptions);
+  }
+
+  /**
+   * Restore a state machine instance from a snapshot
+   *
+   * Use this to resume a machine that was previously persisted.
+   * The snapshot contains the state, context, and history.
+   *
+   * @param definition - Compiled state machine definition
+   * @param snapshot - Previously saved snapshot
+   * @param options - Runtime options (actions, callbacks)
+   * @returns A restored state machine instance
+   */
+  restore(
+    definition: CompiledStateMachineDefinition,
+    snapshot: MachineSnapshot,
+    options: StateMachineOptions = {}
+  ): IStateMachineInstance {
+    const mergedOptions = { ...this.defaultOptions, ...options };
+    return this.strategy.restore(definition, snapshot, mergedOptions);
+  }
+
+  /**
+   * Create a machine instance with initial context override
+   *
+   * Convenience method to create a machine with custom initial context,
+   * merging with the definition's default context.
+   *
+   * @param definition - Compiled state machine definition
+   * @param context - Context to merge with definition defaults
+   * @param options - Runtime options
+   * @returns A new state machine instance
+   */
+  createWithContext(
+    definition: CompiledStateMachineDefinition,
+    context: Record<string, any>,
+    options: StateMachineOptions = {}
+  ): IStateMachineInstance {
+    // Create a modified snapshot with merged context
+    const initialSnapshot: MachineSnapshot = {
+      state: definition.initial,
+      context: { ...definition.initialContext, ...context },
+      history: []
+    };
+
+    const mergedOptions = { ...this.defaultOptions, ...options };
+
+    // Use restore to create with merged context
+    // Note: onEnter for initial state will still be called
+    return this.strategy.restore(definition, initialSnapshot, mergedOptions);
+  }
+}

package/src/engines/state-machine/index.ts

@@ -0,0 +1,45 @@
+/**
+ * State Machine Engine
+ *
+ * Provides state machine execution for tracking entity lifecycles
+ * through defined states and transitions.
+ */
+
+// Types
+export {
+  // Source types
+  StateMachineDefinition,
+  StateMachineConfig,
+  StateDefinition,
+  StateTransition,
+  StateMachineActionItem,
+  // Compiled types
+  CompiledStateMachineDefinition,
+  CompiledStateDefinition,
+  CompiledTransition,
+  CompiledStateMachineAction,
+  // Runtime types
+  MachineSnapshot,
+  TransitionRecord,
+  TransitionResult,
+  StateMachineOptions,
+  StateMachineActionHandler,
+  StateMachineActionRegistry,
+  StateMachineEventListener,
+  IStateMachineInstance
+} from './types';
+
+// Compiler
+export {
+  compileStateMachine,
+  compileStateMachineDefinition
+} from './compiler';
+
+// Strategy
+export {
+  StateMachineStrategy,
+  stateMachineStrategy
+} from './strategy';
+
+// Engine
+export { StateMachineEngine } from './engine';