Realtime Connection State

The bug this exists to prevent

Realtime voice fails in ways that are individually recoverable and collectively confusing. The usual implementation is a boolean connected, then a second flag for reconnecting, then a third for "degraded" — and the combinations nobody enumerated are where users get stranded.

The specific failure worth naming: a connection that drops while already in a fallback mode. A naive reconnect handler sends it back to reconnecting, which then fails again, and the user oscillates between two broken states instead of settling into the one that works.

Rule 1 — degradation is one-way and ordered

streaming → reconnecting → fallback_rest → fallback_typed, and never backwards on a failure. A second-order failure while already in fallback_rest degrades further, to fallback_typed. fallback_typed and ended are floors: a further disconnect is a no-op, never a crash and never a regression upward.

Recovery is a separate, deliberate act. Automatic promotion on a single good signal is what produces the oscillation.

Rule 2 — typing is the bright line

allowTypedInput is true in every single state, and there is a test asserting exactly that across all of them. Whatever else has failed, the user can still type.

This is the rule most easily lost in a refactor, because disabling input during "reconnecting" looks like correct UI hygiene. It is the moment a user with a broken microphone is locked out of the only channel still working.

Rule 3 — an unhandled state must throw at compile time

The exhaustive never check means adding a state without updating every switch is caught by tsc, not discovered live mid-session. There is a test proving the never branch throws rather than falling through — a dead branch in normal use, asserted so it stays dead.

What this does NOT do

No transport. No WebSocket, WebRTC, retry timers, audio, or transcription. It decides what state you are in and what is permitted there; you own the sockets.

It does not implement recovery — promotion back up the ladder is a caller decision, deliberately.

Verified

15 tests: every state described without throwing, allowTypedInput true in all states, ordered degradation, exhausted reconnect attempts, second-order failure degrading further, floor states absorbing further disconnects, and the never branch throwing.

Not covered: no test drives a real transport, and there is no timing or flap-detection test — how long to wait before declaring a drop is yours.