crates/rutster-tap/src/protocol.rs

@@ -15,6 +15,29 @@
 //! implement a byte-parser. ~33% wire overhead (65 KB/s at 24 kHz mono
 //! i16) is negligible at slice-2's scale; brain-authoring ergonomics
 //! dominate. A future-rung `v: 2` may negotiate a binary mode (spec §9).
+//!
+//! ## v2 reservations (documented 2026-07-04; implemented at the version bump)
+//!
+//! The 2026-07-04 scalability review (finding M4) identified the missing
+//! reconnect semantics as the most calcifying gap in the system — wire
+//! protocols are the hardest surface to retrofit. v1 stays frozen; the
+//! v2 negotiation MUST carry:
+//!
+//! - **`hello.resume_token`** — an opaque token the brain returned on a
+//!   prior accept for this session, plus a **connection epoch** counter.
+//!   Lets a brain fleet distinguish "resume this conversation" (state
+//!   held / recoverable) from "unknown session" (context lost).
+//! - **`hello_ack.resume: accepted | rejected`** — the brain's explicit
+//!   answer. A rejected resume tells the core the brain is amnesiac, so
+//!   the core (not the caller's ears) decides: re-prime, escalate, or end.
+//! - **`bye.reason: terminal | transient`** — today every close funnels
+//!   into infinite re-dial (5s cap, forever); a brain that deliberately
+//!   ends a session is re-dialed for the rest of the call. `terminal`
+//!   exits the retry loop.
+//!
+//! Anything in this list changes BOTH sides of the wire — which is why it
+//! is reserved here, in the protocol's own doc, rather than in a review
+//! doc nobody re-reads at implementation time.
 
 use rutster_media::PcmFrame;
 use serde::ser::{SerializeStruct, Serializer};