68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
# 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`
|