Software-only show-control readiness baseline

docs/protocol.md

@@ -0,0 +1,67 @@
+# Protocol
+
+## Design Rules
+
+- Separate control traffic from realtime traffic
+- Version every envelope
+- Keep realtime messages disposable
+- Prefer idempotent control commands
+- Let nodes recover independently after packet loss or reconnect
+
+## Control Protocol
+
+Purpose:
+
+- Discovery
+- Heartbeat
+- Config sync
+- Preset recall
+- Panic and blackout
+- Telemetry
+
+Current envelope model:
+
+- `protocol_version`
+- `sequence`
+- `sent_at_millis`
+- `message`
+
+Current control messages:
+
+- `discovery_hello`
+- `discovery_ack`
+- `config_sync`
+- `heartbeat_request`
+- `heartbeat`
+- `preset_recall`
+- `blackout`
+
+`config_sync` carries the authoritative per-node hardware assignment so the node can reject invalid activation before the first frame.
+
+## Realtime Protocol
+
+Purpose:
+
+- Scene parameters for distributed rendering
+- Explicit pixel frames for frame streaming mode
+- Resync requests
+
+Current realtime messages:
+
+- `scene_parameters`
+- `pixel_frame`
+- `resync_request`
+
+## Delivery Semantics
+
+- Control messages must be small and replay-safe where possible
+- Realtime messages use latest-state-wins semantics
+- Nodes may drop stale realtime frames rather than replay them
+- A reconnecting node must request or receive a clean config sync before resuming output
+
+## DDP Compatibility
+
+DDP is treated as an optional compatibility shell for frame streaming mode only.
+
+The internal model is intentionally broader than DDP because the preferred operating path is distributed scene mode with time-based parameters and node-local rendering.
+