docs: align wire-spec and mark implemented vs proposed

Keep the 45-byte pose frame consistent across docs, simulator, and
prototype, clarify MinIO is not peer sync, and state clearly that the
repo is a from-scratch platform sketch with options rather than mandates.

docs/04-swarm-sync.md

@@ -16,19 +16,27 @@ Bandwidth is the scarcest resource in the system. Every message class gets an ex
 
 ## Broadcast payload: small on the wire, precise at rest
 
-The `state` broadcast is a fixed compact frame:
+The `state` broadcast is a fixed compact frame. The runnable PoC encodes it as
+**45 bytes** little-endian (`simulator/virtual_drone/broadcast.py`); that size is
+what the prototype uses for bandwidth estimates.
 
-| Field | Type | Notes |
+| Field | Wire type (PoC) | Notes |
 | --- | --- | --- |
-| `drone_id` | uint16 | Fleet-scoped registry |
+| `magic` + `version` | 2s + uint8 | `b"SH"`, version `1` |
+| `drone_id` | 8s ascii | Zero-padded; a fleet `uint16` registry id is a natural production swap |
 | `ts_ns` | int64 | Epoch nanoseconds, same clock domain as storage |
-| `pos_x/y/z` | int32 | **Millimeters** in the mission frame — quantized only here, storage keeps full float precision |
-| `att_roll/pitch/yaw` | int16 | Centi-degrees |
-| `vel_x/y/z` | int16 | cm/s |
+| `pos_x/y/z` | 3 × int32 | **Millimeters** in the **mission frame** — quantized on the wire only; storage keeps full float precision |
+| `att_roll/pitch/yaw` | 3 × int16 | Centi-degrees — attitude stays on the wire so peers need no local shape model |
+| `vel_x/y/z` | 3 × int16 | cm/s |
 | `frame_ref` | uint8 | Frame of reference id (GPS-denied: local/visual-odometry frames must be explicit) |
 | `flags` | uint8 | Battery-low, returning, degraded-sensors, … |
 
-~40 bytes per frame → a 50-drone swarm at 5 Hz is ~10 KB/s of pose traffic before transport overhead. Trivial even on a congested mesh.
+45 bytes × 5 Hz × 50 drones ≈ 11 KB/s of pose traffic before transport overhead — still trivial on a congested mesh.
+
+An earlier sketch used relative coordinates and a bounding sphere (no attitude).
+It was dropped: mission-frame pose + attitude is simpler to fuse post-flight and
+costs almost nothing at this frame size. Relative localization remains a
+consumer concern when `frame_ref` differs across peers ([09](09-open-questions.md)).
 
 `detections` events are slightly larger (class, confidence, bounding volume, ego-pose) but event-shaped and rare by comparison.
 
@@ -51,25 +59,27 @@ graph LR
     SB -->|"store-and-forward relay"| SC
 ```
 
-### Recommended: Zenoh
+### Recommended (proposal): Zenoh
 
 - Designed exactly for constrained, dynamic networks: built-in peer discovery, brokerless peer-to-peer mode, store-and-forward, and a query layer on top of pub/sub.
 - First-class robotics citizenship: an official ROS 2 RMW implementation exists, so the ingestion side and the sync side can share one middleware.
 - Tiny footprint, ARM64-native.
 
+**PoC today:** the simulator and the 2D prototype exercise the **raw UDP** pose path only — the minimal degraded profile below. Zenoh is the proposed production pub/sub, not yet wired into the runnable stack.
+
 ### Alternatives considered
 
 | Option | Verdict |
 | --- | --- |
 | **DDS multicast** (ROS 2 default) | Works, battle-tested; but discovery storms and tuning pain on lossy wireless meshes are well documented. Keep as fallback since ROS 2 speaks it natively |
 | **MQTT** | Needs a broker — a per-drone broker bridge is possible but adds moving parts for no gain over Zenoh |
-| **Raw UDP multicast** | Perfect as a last-resort minimal profile for the pose broadcast alone (fixed frame, no discovery); no query layer, no reliability — documented as the degraded mode |
-| **MinIO bucket replication** | Wrong tool for the 5 Hz pose path, right tool for bulk derived datasets — see below |
+| **Raw UDP multicast** | **Implemented in the PoC** for pose broadcast (fixed frame, no discovery); no query layer, no reliability — also the documented degraded mode |
+| **MinIO bucket replication** | Wrong tool for the 5 Hz pose path; optional on board for derived datasets and primary on the ground warehouse — not the in-flight bulk path |
 
 ## Two sync mechanisms, deliberately separate
 
-1. **Fast path — pub/sub (Zenoh):** pose frames and detection events. Fire-and-forget with bounded staleness; consumers keep a peer-state cache.
-2. **Bulk path — rsync over persistent SSH:** sealed `detections`/`state` Parquet partitions are pulled opportunistically between drones when links allow. This is how a drone that was out of range catches up on mission history without anyone re-sending events.
+1. **Fast path — pub/sub (Zenoh proposed; UDP in the PoC):** pose frames and detection events. Fire-and-forget with bounded staleness; consumers keep a peer-state cache.
+2. **Bulk path — rsync over persistent SSH (proposed):** sealed `detections`/`state` Parquet partitions are pulled opportunistically between drones when links allow. This is how a drone that was out of range catches up on mission history without anyone re-sending events. The PoC visualises bulk volume; it does not yet run real rsync between virtual drones.
 
 Why SSH-based bulk sync over object-store replication:
 
@@ -105,7 +115,7 @@ SQL access must not become a write channel. A single "read-only connection" flag
 | Layer | Mechanism | What it stops |
 | --- | --- | --- |
 | 1. Key = operation | Forced command: the query key can only invoke the query wrapper, nothing else | Arbitrary exec, lateral movement |
-| 2. Statement gate | Wrapper accepts a single statement, parses it, rejects anything but `SELECT` (no `COPY`, `ATTACH`, `INSTALL`, `SET`, multi-statements); parameters bound, not interpolated | SQL-as-a-write-channel, config tampering |
+| 2. Statement gate | Wrapper accepts a single statement, rejects anything but `SELECT`/`WITH`/… (no `COPY`, `ATTACH`, `INSTALL`, `SET`, multi-statements); production should prefer a real parser + bound parameters, not keywords alone | SQL-as-a-write-channel, config tampering |
 | 3. OS permissions | Wrapper runs as a dedicated user with **read-only filesystem access** to the data root and write access to nothing | Any write that slips past layer 2 |
 | 4. Engine hardening | `:memory:` database, external access disabled except the data-root glob, extension loading off | Reaching outside the store |
 | 5. Resource caps | Timeout, memory cap, niced CPU (flight software always wins), response size budget | Denial of service via expensive queries |