state-machines-and-invariants

# State Machines and Invariants ## Cardinal Rule State is the source of truth. If state is not READY, the system must not behave as if it is. Never compute, merge, or present results that imply correctness when state indicates degradation, staleness, or invalidity. When any mandatory invariant fails: **fail fast** with a structured reason. ## No Policy, No Answer If the system depends on thresholds (staleness ms, consecutive events N, failure count K, cooldown period T) and those values are not provided or configured, **refuse to make state decisions**. Return: > "Missing policy values — cannot decide state transitions. Provide thresholds." Never invent or guess threshold values. ## Core Concepts ### Event vs State - **Events** are inputs: WS messages, REST responses, timeouts, validation failures. - **State** is the maintained truth of what the system currently believes. - A single good event does NOT erase a bad state unless the state machine rules explicitly allow it. ### No Silent Recovery Recovery must be explicit. Document: - What changed? - Why is it safe now? - Which invariants are passing again? ## State Models ### System State (Global) ```typescript type SystemState = | 'BOOTING' // starting up, loading config | 'WARMING' // acquiring initial data | 'READY' // fully operational | 'DEGRADED' // some sources unavailable | 'UNHEALTHY' // critical invariants failing | 'DISABLED'; // manually turned off ``` ### Source ...