50 lines
2.3 KiB
Markdown
50 lines
2.3 KiB
Markdown
# Capability Spec: fsm
|
|
|
|
**Package**: `@suaveplan/fsm`
|
|
**Version**: 0.0.0 (genesis)
|
|
**Status**: ADDED
|
|
|
|
---
|
|
|
|
## ADDED Requirements
|
|
|
|
### FSM-01 — Config validation
|
|
|
|
`validateConfig(config)` MUST reject machines with unknown target states, duplicate state ids, or cyclic hierarchical parents. Invalid configs MUST throw `FSM.INVALID_CONFIG`.
|
|
|
|
### FSM-02 — Transition contract
|
|
|
|
`StateMachine.send(event)` MUST run each candidate transition's guards in declared order, halt on the first `true`, execute the transition's actions, and emit `TransitionResult { fromState, toState, event, eventType: FsmEventType }`. Guard rejection across all candidates MUST emit `FSM.INVALID_TRANSITION`.
|
|
|
|
### FSM-03 — Async guards / actions
|
|
|
|
`AsyncGuardFn` MUST return `Promise<boolean>`; `AsyncActionFn` MUST return `Promise<void>`. `send` MUST await them in order. Concurrent `send` calls MUST be serialised by the machine (FIFO).
|
|
|
|
### FSM-04 — Snapshot / restore
|
|
|
|
`StateMachine.snapshot()` MUST return `MachineSnapshot` serialisable via `JSON.stringify`. `StateMachine.restore(snapshot)` MUST restore the machine to that exact state + context. Snapshots from a different `config.id` MUST be rejected.
|
|
|
|
### FSM-05 — Hierarchical semantics
|
|
|
|
`HierarchicalStateMachine` MUST resolve the deepest active leaf on entry. `onEntry` / `onExit` MUST fire in outer→inner / inner→outer order respectively.
|
|
|
|
### FSM-06 — Parallel regions
|
|
|
|
`ParallelStateMachine` MUST evaluate transitions independently per `RegionConfig`. `SyncPoint` MUST block progress until every named region enters the configured state.
|
|
|
|
### FSM-07 — History
|
|
|
|
`HistoryType` MUST be `'shallow' | 'deep'`. `HistoryStateManager` MUST return the last active leaf on re-entry for `deep`, and the last active direct child for `shallow`. Empty history on `onExit`-before-`onEntry` paths MUST emit `FSM.HISTORY_EMPTY`.
|
|
|
|
### FSM-08 — Deferred events
|
|
|
|
`DeferredEventQueue` MUST buffer events per `StateDeferConfig` and release them when the state exits. Overflow MUST surface as `FSM.DEFER_OVERFLOW`.
|
|
|
|
### FSM-09 — Visualisation
|
|
|
|
`toDot(config)` MUST produce Graphviz DOT representing states + transitions. `toMermaid(config)` MUST produce Mermaid state-diagram syntax. Both MUST handle hierarchical + parallel configs.
|
|
|
|
### FSM-10 — Observability
|
|
|
|
`send` MUST record `fsm.transition.duration_ms` histogram and `fsm.transition.total{outcome}` counter.
|