flatudp: the source, kind, mock sender and stream probes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/claude/probe-readings.md

@@ -1827,9 +1827,10 @@ are unrealized and measure 0x0.
 ## `[source-kinds]`
 
 ```
-[source-kinds] kinds=udps,e1608,probe
+[source-kinds] kinds=udps,e1608,flatudp,probe
 [source-kinds] form udps: round_trip=1 valid=1
 [source-kinds] form e1608: round_trip=1 valid=1
+[source-kinds] form flatudp: round_trip=1 valid=1
 [source-kinds] form probe: round_trip=1 valid=1
 [source-kinds] panel disconnected: panels=1 present=1 sensitive=0
 [source-kinds] panel connected: panels=1 present=1 sensitive=1
@@ -1841,10 +1842,10 @@ are unrealized and measure 0x0.
 source-plugin path from the registry to the producer thread. The variable also registers the test-only `probe`
 kind, so a run without it never shows that kind. The `form` line appears once per registered kind.
 
-- `kinds=udps,e1608,probe`: a missing kind means `register_builtin_sources()` was not called before `parse_args()`,
+- `kinds=udps,e1608,flatudp,probe`: a missing kind means `register_builtin_sources()` was not called before `parse_args()`,
   or the env var gate is wrong.
 - `round_trip=0`: a form's `write` and `read` disagree about a key -- a renamed `SourceConfig` key, or an
-  absent key that was not defaulted. `valid=0` is a default configuration the form refuses. The e1608 form's sample sets address, port, scan_rate, mode, ai1, trigger, dir1 and plot0; a mismatch names one of those.
+  absent key that was not defaulted. `valid=0` is a default configuration the form refuses. The e1608 form's sample sets address, port, scan_rate, mode, ai1, trigger, dir1 and plot0; a mismatch names one of those. The flatudp sample sets port, bind, multicast, iface, rate, endian and signals.
 - `panel disconnected: sensitive=0 present=1`: **disable, don't hide.** `present=0` is a panel that was hidden
   or never added; `sensitive=1` is a panel that stays live with no source behind it.
 - `panel connected: sensitive=1`: anything else means `apply_source_panels` acted on the wrong widget (it must
@@ -1907,6 +1908,54 @@ the one `[e1608] handshake with ...: Connection refused` line, `stream: ... sign
   the scan (it also reads 0 when `connects` is still 1, since a frame count that grows on a link that never dropped
   proves nothing).
 
+## `[flatudp]`
+
+```
+[flatudp] codec: ok=1
+[flatudp] datagram of 22 bytes, expected 21, check the signal list
+[flatudp] stream: connected=1 signals=4 names=Trigger,Ia,Cnt,Wave expect=Trigger,Ia,Cnt,Wave frames=3735 rate=1000.000 ok=1
+[flatudp] channels: count=4 expect=4 ok=1
+[flatudp] continuity: ch0_breaks=0 ch1_breaks=0 ok=1
+[flatudp] wrong size: count=3 message='datagram of 22 bytes, expected 21, check the signal list' ok=1
+[flatudp] capture button: present=1 sensitive=1
+[flatudp] state: valid=3735 wrong=3
+[flatudp] silence: connected=0 model_connected=0 ok=1
+[flatudp] resumed: connected=1 frames_before=4990 frames_after=7147 ok=1
+```
+
+`UDPSCOPE_PROBE_FLATUDP=2500` (the first lines; counts vary) and `UDPSCOPE_PROBE_FLATUDP_GAP=8000` (the last two)
+run as `--source flatudp` against `tools/mock_flatudp.py` with the options in `verification.md`. The second line is
+the source's own stderr message, printed once per distinct wrong size, not a probe line. The `continuity` line
+above is the scalar-list run (`Trigger,Ia,Cnt`, big endian); the mixed-list run with `Wave:int16[4]` reads
+`continuity: skipped (...)`. With no sender the stream lines read `connected=0 ... frames=0 ... ok=0`, `continuity`
+is skipped and the capture button reads `sensitive=0`: a reading, not a failure. A run without `--bad-every` reads
+`wrong size: count=0 ... ok=0` for the same reason.
+
+- `codec: ok=1`: the `signals` text round-trips, a hand-built 24-byte datagram decodes to the hand-computed
+  values in both byte orders (`uint8` 254, `int16` -2, `float32` 1.5, `uint64[2]` 1 and 4294967298, `int8` -1)
+  and the validity rules refuse what they should. It needs no source, so `--source probe` shows it too.
+  `ok=0` is a codec defect: a swapped byte order, a wrong width or a rule that does not fire.
+- `stream: ... ok=1`: the model's signals are the list's rows in order, at the declared rate. `names` out of
+  order is a decode that mixed rows; `rate` of 1000 against a different declared rate is a `sampling_rate`
+  that did not reach the model (the ring and the decimation are then sized for the wrong cadence).
+- `channels: count=4`: one channel per signal. A vector signal is **not** one channel per element: the model
+  reads its `count` values as consecutive samples of one channel, as for a UDPStreamer block signal.
+- `continuity: ch0_breaks=0 ch1_breaks=0`: consecutive samples of the mock's first two signals step by 1 and
+  by 2 modulo 100. A break is a lost or reordered datagram, a batch flushed with the wrong number of samples,
+  a wrong byte order or ingest decimation that is not 1:1. It is skipped for a list with a vector row: the
+  model spans each frame by its largest element block, so the scalar channels of a mixed list are padded
+  with zeros (`Frame::value` reads 0 out of range) and a continuity check on them would read nearly every
+  step as a break.
+- `wrong size: ok=1`: wrong-size datagrams were counted and the message names the received and expected size.
+  The message must also be the only stderr line of its kind: one per distinct size, however many arrive.
+- `capture button: present=1 sensitive=1`: the kind reports datagrams, so the capture UI is live (contrast
+  `[source-kinds]`, where the probe kind leaves it disabled). With no stream it reads `sensitive=0`.
+- `silence: connected=0 model_connected=0`: 2 s without a valid datagram raised `Disconnected`. `connected=1`
+  is the timeout not firing, wrong-size datagrams refreshing the silence clock (they must not), or the mock's
+  gap not covering the probe (see the timing note in `verification.md`).
+- `resumed: ok=1`: `Connected` was raised again and frames resumed. `connected=0` here means the source never
+  recovered after the sender came back.
+
 ## `[prefs-probe]`
 
 ```