feat(diagnostics): correlate movement acknowledgements with painted views

docs/M016_LATENCY_PROCEDURE.md

@@ -0,0 +1,49 @@
+# Milestone 016 movement-latency procedure
+
+## Measurement model
+
+Each accepted movement uses one correlation path. Browser times use
+`performance.now()` and ESP times use its monotonic timer; do not subtract a
+browser timestamp from an ESP timestamp.
+
+| Interval | Clock | Measurement point |
+| --- | --- | --- |
+| pointer feedback | browser | pointer event to next animation frame |
+| command to acknowledgement | browser | `move` send to matching `ack` |
+| command to complete view | browser | `move` send to matching assembled view sequence |
+| command to painted view | browser | `move` send to next frame after matching view render |
+| handler and send | ESP | existing `/diagnostics` maxima |
+| network round trip | client | ICMP and WebSocket heartbeat samples |
+
+The accepted command acknowledgement contains the authoritative `stateSequence`.
+The browser records a sample only after the complete view with that sequence is
+rendered and the next animation frame occurs. Samples are local-only, capped at
+256, and do not alter a command, projection, or server result.
+
+## Controlled runs
+
+1. Record the firmware build identity, device address, Wi-Fi access point,
+   client device, browser/version, signal conditions, and viewport.
+2. Collect 100 `ping -c 100 -q <device>` samples. Record loss, min, average,
+   maximum, and deviation.
+3. Run 200 accepted moves per player with two players and no observers. Include
+   direction changes, a sustained hold, a release, and one blocked move.
+4. Repeat with two players and four observers. Capture `/diagnostics` before
+   and after each run.
+5. For each browser, copy
+   `window.maze32PlayerApp.latencySamples()` after the run. Compute p50, p95,
+   p99, and maximum for all browser intervals. Keep raw samples only for the
+   duration of the report and do not store player names or tokens.
+6. Compare command-to-acknowledgement with command-to-painted-view, ESP handler
+   and send maxima, queue high-water marks, observer view chunk count, and
+   ICMP/WebSocket round trips. Attribute a delay only when the matching
+   interval is elevated.
+
+## Safety checks
+
+- Confirm no dropped, failed, malformed, oversized, or rate-limited message
+  increased unexpectedly outside the deliberate blocked-move case.
+- Confirm queue high water stays within its published limit and browser sample
+  storage remains at or below 256 entries.
+- Record blocked-command rejection separately; it does not count as an
+  accepted-move sample.