suaveplan/openspec/archive/2026-04-19-enterprise-fsm/proposal.md

OpenSpec Change: enterprise-fsm

• Change ID: enterprise-fsm
• Package: @suaveplan/fsm
• Category: universal
• Target path: universal/control-flow/fsm
• Status: PROPOSED
• Date: 2026-04-19
• Reference spec: /mnt/s/web/suaveplan/enterprise/fsm.md

Summary

Finite state machine with hierarchical, parallel, and history-state extensions, deferred-event queue, transition guards/actions (sync + async), snapshot/restore, lifecycle listener API, declarative transition hooks, DOT/Mermaid visualisers, and exhaustive config validation. Shape-compatible with XState-lite state configurations but zero-dependency.

Current-state audit (genesis)

Package does not exist yet — fresh build.

Dependencies

• Workspace: @suaveplan/error, @suaveplan/events, @suaveplan/types
• External (via catalog): zod, tslib, @opentelemetry/api
• Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata

Preserved public surface

Core FSM

• createMachine, StateMachine
• Types: ActionFn, AsyncActionFn, AsyncGuardFn, CompletedTransition, FsmError, FsmErrorCode, FsmEventType, FsmListenerMap, GuardFn, LifecycleListener, MachineConfig, MachineSnapshot, StateConfig, TransitionDefinition, TransitionInfo, TransitionListener, TransitionResult
• Hooks: FsmHookMap, FsmTransitionHookData, FsmTransitioningHandler

Utilities

• buildTransitionIndex, createFsmError, validateConfig

Hierarchical

• createHierarchicalMachine, HierarchicalStateMachine, HierarchicalConfig, HierarchicalStateNode, HierarchicalTransition, HierarchicalTransitionResult

History

• createHistoryManager, HistoryStateManager, HistoryEntry, HistoryStateConfig, HistoryType

Parallel

• createParallelMachine, ParallelStateMachine, ParallelConfig, ParallelState, ParallelTransitionResult, RegionConfig, RegionTransition, SyncPoint

Deferred queue

• createDeferredQueue, DeferredEventQueue, DeferredEvent, DeferredQueueConfig, StateDeferConfig

Visualisation

• toDot, toMermaid, VisualizerOptions

New genesis additions

• Codes: FSM.INVALID_CONFIG, FSM.INVALID_TRANSITION, FSM.GUARD_REJECTED, FSM.HISTORY_EMPTY, FSM.DEFER_OVERFLOW.
• Zod schemas for every config input.
• OTel histograms fsm.transition.duration_ms, counter fsm.transition.total{outcome}.
• Property tests: config round-trip via snapshot/restore, parallel-region determinism under identical event order.

Impact

• Adds one new package: universal/control-flow/fsm
• Adds one new spec capability: fsm