# 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`