first

docs/state-machines.md

@@ -0,0 +1,31 @@
+# State Machines
+
+## Event Lifecycle
+
+`scheduled -> prefetch_ready -> preview_open -> locking -> locked -> reveal_open -> settled -> archived`
+
+## Client Round State
+
+`idle -> prefetching -> ready -> preview_playing -> selection_pending -> selection_submitting -> selection_accepted -> locked -> reveal_playing -> result_visible -> transitioning -> error`
+
+## Bet Acceptance State
+
+`received -> validated -> accepted`
+
+Rejection states:
+
+- `rejected_too_late`
+- `rejected_invalid_market`
+- `rejected_invalid_session`
+- `rejected_duplicate`
+
+Terminal state:
+
+- `settled`
+
+## Notes
+
+- Locking is server authoritative
+- Clients may display synced countdowns, but acceptance is decided by the server
+- Selection confirmation must be visually unambiguous
+- The locked state freezes the odds display for the user