ka9q-python 3.20.0__tar.gz → 3.26.0__tar.gz

{ka9q_python-3.20.0 → ka9q_python-3.26.0}/CHANGELOG.md

@@ -1,5 +1,213 @@
 # Changelog
 
+## 3.25.2 (2026-08-22)
+
+### Fixed
+
+- **`poll_channel()` can now see a channel radiod holds at 0 Hz** (#6).
+  radiod answers a poll for a channel it is still reaping after
+  `remove_channel()` — or one parked at 0 Hz, or one a dynamic-create build
+  minted for the poll itself — with the same `frequency = 0` reply it gives
+  for an unknown SSRC. `poll_channel()` discarded those as "no such
+  channel", so a purging SSRC was indistinguishable from a free one and any
+  "is this SSRC free?" logic re-created the dying channel (answers status,
+  never emits RTP). New `allow_idle=True` returns that reply as a
+  `ChannelInfo` with `frequency == 0.0`, meaning "radiod currently answers
+  for this SSRC at 0 Hz — not free to reuse". Default behaviour is
+  unchanged; `expected_freq` still rejects 0 Hz. `remove_channel()`'s
+  docstring now states the purge window.
+
+## 3.25.1 (2026-08-18)
+
+### Fixed
+
+- **`DEMOD_TYPE` no longer contradicts the preset it is sent with.**
+  `create_channel()` derived the demodulator from a five-name allowlist —
+  `demod_type = 0 if preset in ['iq','usb','lsb','cw','am'] else 1` — and sent
+  it immediately after `PRESET` in the same packet, so the later value won.
+  Every preset outside that list got `FM_DEMOD`, including `wfm`: radiod ran
+  the *narrowband* FM demodulator behind the wfm preset's ±110 kHz filter,
+  which emits nothing and reports `snr=-inf` indefinitely. Broadcast FM was
+  unusable through this library and the failure was silent — the channel
+  existed, verified, and simply never produced RTP.
+
+  `sam`, `ame`, `dsb`, `cwu`, `cwl`, `wspr`, `nam` and `amsq` were mislabelled
+  the same way (all are `demod = linear` in `presets.conf`), and `spectrum`
+  got FM rather than `SPECT_DEMOD`. Only the five allowlisted names were right.
+
+  `demod_type_for_preset()` now mirrors the `demod =` line of each stock
+  preset, and defaults to `LINEAR_DEMOD` — which `radio.h` defines as
+  "everything else" — rather than to FM.
+
+  Verified against radiod: a `wfm` channel now reports `demod_type=2` and,
+  with a squelch threshold below the signal, streams continuously (301
+  packets in 6 s where it previously produced none).
+
+  Note for callers: radiod's `wfm.c` sets `chan->squelch.snr_enable = true`
+  unconditionally when the demod thread starts, so `set_squelch(enable=False)`
+  is reverted on a wfm channel. Hold it open with a low `open_snr_db` instead.
+
+## 3.25.0 (2026-08-18)
+
+### Added
+
+- **`raw_payloads=True` on `RadiodStream` and `ManagedStream`: deliver
+  undecoded RTP payloads for the framed encodings.** `parse_rtp_samples()`
+  deliberately returns `None` for OPUS/OPUS_VOIP/AX25 — they have no
+  raw-sample representation — and `_process_packet` drops a `None`, so a
+  stream on any of those encodings ran healthy and silent: packets arrived,
+  the callback never fired, and nothing logged. The only way to consume an
+  Opus channel was `OpusDecoder`, i.e. decoding to PCM.
+
+  That is the wrong shape for a consumer that wants the codec frames
+  themselves — forwarding Opus to a browser's WebCodecs decoder, or writing
+  an Ogg/AX25 file — where decoding to PCM and re-encoding is pure loss.
+  With `raw_payloads=True`, `on_samples` receives a `List[bytes]`, one
+  entry per RTP packet in arrival order, and with
+  `deliver_interval_packets=1` that is exactly one frame per call.
+
+  Two properties callers must respect:
+
+  - The resequencer is **bypassed**. A codec frame is opaque: it can be
+    neither concatenated nor zero-filled, and gap concealment belongs to
+    the decoder (Opus has built-in PLC). Loss and reorder therefore surface
+    to the caller, which for a sequenced transport like TCP/WebSocket is
+    exactly right, and for a lossy one means the caller owns concealment.
+  - Quality accounting switches to **frames, not samples**:
+    `batch_samples_delivered` and `total_samples_expected` count RTP
+    packets, and the resequencer statistics stay zero because it never ran.
+
+  `stop()` no longer flushes the resequencer in this mode — its ndarray
+  output would otherwise be appended to a buffer of `bytes` and blow up in
+  `np.concatenate` on the final delivery.
+
+  The parameter is additive and defaults to `False`; the sample path is
+  unchanged. `tests/client_usage_manifest.json` is updated for the new
+  signature.
+
+- **`FILTER_DROPS` (tag 77) now decodes in `decode_status_dict()`, and is
+  carried on `ChannelInfo.filter_drops`.** radiod's per-channel count of
+  output blocks its demod thread lapped was decodable only in
+  `decode_status_packet()` → `ChannelStatus.filter_drops` — the typed
+  decoder nothing polls continuously. The lightweight decoder that
+  `StatusListener` runs on *every* broadcast silently skipped the tag, and
+  since listener callbacks receive a `ChannelInfo` rather than the status
+  dict, the counter never reached a long-running client at all. Measuring
+  radiod's own loss therefore meant either `metadump` (which follows one
+  stream, not the fleet) or hand-rolling a TLV walk.
+
+  This matters more since ka9q-radio `55d9048d`: a lapped block is now
+  counted *and* emitted as a block of zeros, so `PacketResequencer`'s
+  zero-block detection and this counter are two independent views of the
+  same event. Cross-checking them is what makes either trustworthy — the
+  same test that showed the pre-`55d9048d` counter accounted for only
+  6–15% of real timeline loss.
+
+  Two properties callers must respect, both covered by tests:
+
+  - The counter is **cumulative since radiod started**. Difference it
+    across two reads; a level on its own says nothing about current loss.
+  - **Absent ≠ zero.** A status packet without the tag leaves
+    `filter_drops` as `None` and does not clear a previously known count
+    — clearing it would read as a counter reset and produce a spurious
+    negative delta.
+
+  `ChannelInfo.filter_drops` is appended as the last field, so the change
+  is purely additive for positional construction. `client_usage_manifest.json`
+  is updated accordingly; the two signature entries were edited by hand
+  because `scripts/gen_client_manifest.py` scans `/opt/git/sigmond`, which
+  is not present on a dev box — re-run it on an appliance to confirm.
+
+### Deprecated
+
+- **`rtp_to_wallclock()` now emits `DeprecationWarning` on every call**
+  (audit F16, completing the 2026-06-27 rename). Signature and behavior
+  are unchanged — it delegates to `rtp_to_utc()`. The in-tree clients
+  (hf-timestd, wspr-recorder) migrated to `rtp_to_utc` before this
+  landed; internal callers (`RadiodStream`, `MultiStream`, `RTPRecorder`)
+  were migrated in the same commit so the library never warns about
+  itself on the per-packet path.
+
+## 3.22.0 (2026-08-13)
+
+Audit remediation follow-up (findings F1, F3-F8, F10-F14 from the
+2026-08 upstream-alignment audit; see `docs/audit/` and
+`.superpowers/sdd/2026-08-13-audit-remediation/`). Minor bump: adds
+public capability and one deliberate, owner-ruled behavior change.
+
+### Changed (behavior)
+
+- **`create_channel()` now derives a per-client multicast destination
+  from `client_id` when `destination=` is not given, and raises
+  `ValidationError` when *neither* is available** (F5). Previously a
+  bare `create_channel()` call with no `client_id` and no
+  `destination=` omitted the `OUTPUT_DATA_DEST_SOCKET` TLV entirely,
+  so radiod created no channel at all, rather than failing loudly on
+  the client side. Any caller that relied on that silent no-op must
+  now pass `client_id=` (recommended) or an explicit `destination=`.
+  One deliberate side effect: for direct `create_channel()` calls that
+  set `client_id`, omit `destination=`, and let the SSRC be
+  auto-allocated, the newly derived destination now participates in
+  the SSRC hash — SSRCs for that specific path differ from what they
+  were pre-3.22.
+
+### Added
+
+- **`set_spectrum()`** gains `window_type`, `avg`, `overlap`, `base`,
+  `step` parameters (plus `demod_type`/`frequency_hz`); `SpectrumStream`
+  delegates to it (F11).
+- **`ChannelStatus.options`** decodes the `SETOPTS` TLV (F12).
+- **`DemodType.INVALID_DEMOD = -1`** now parses correctly from
+  upstream headers (negative enum literals were previously dropped by
+  `sync_types.py`) (F10); `set_demod_type()`'s bound now derives from
+  `DemodType.N_DEMOD` so `IDLE_DEMOD` is no longer wrongly rejected
+  (F13).
+- **`resolve_multicast_address` re-exported from `ka9q`** (F14).
+
+### Fixed
+
+- **`MultiStream` re-sends `agc`/`gain`/filter-edges/requested-encoding**
+  on channel re-creation after a radiod restart — these fields were
+  never stored on the `MultiStream` side, so re-creation could not
+  re-assert them; this was an origin bug, not a regression (F1, P0).
+- **`tune()` records `_requested_encoding`** so keepalives re-assert
+  the caller's chosen encoding instead of drifting back to the
+  channel's current one (F4).
+- **`set_lock()` warns** that radiod silently discards `LOCK` rather
+  than failing (F6).
+
+### Docs
+
+- Corrected re-create/lifetime semantics (delta-update only; polls
+  don't extend lifetime; units are frames, not seconds) (F3, F7).
+- Corrected a stale pre-3.14 fallback claim in the `client_id`
+  docstring (F5 follow-up).
+- README Troubleshooting: a `lo`-route silently swallows control
+  commands; use `interface=` (F8).
+
+## 3.21.1 (2026-08-11)
+
+- **Fix: `StreamQuality.copy()` dropped `delivered_rtp_start`** — the
+  hand-maintained field list predated the new field, so every
+  RadiodStream callback received `None` (MultiStream, which passes its
+  quality object directly, was unaffected). `copy()` now uses
+  `dataclasses.replace`, carrying every present and future field; a
+  fields-iteration regression test guards the class.
+
+## 3.21.0 (2026-08-11)
+
+- **`StreamQuality.delivered_rtp_start`** — the true RTP timestamp of the
+  FIRST sample of each delivered batch, from the resequencer's emission
+  tracking (`PacketResequencer.last_chunk_rtp_start`; zero fills
+  included).  Both `RadiodStream` and `MultiStream` populate it.
+  Consumers that label samples MUST prefer this over
+  `last_rtp_timestamp`: the latter is the last RECEIVED packet's header
+  (pre-resequencer) and desynchronizes from delivered samples under
+  loss — steady-state ±1-packet label wobble, and block-scale label
+  slips during stall-and-catchup (root cause of hf-timestd's T6 origin
+  instability; see hf-timestd docs/T6-BLOCK-SLIP-ROOT-CAUSE-2026-08-10).
+  `None` when nothing has been delivered yet.
+
 ## [3.20.0] - 2026-06-29
 
 ### Added — `SlotClock` ambiguous-unwrap guard (fail loud, never silent)

{ka9q_python-3.20.0/ka9q_python.egg-info → ka9q_python-3.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.20.0
+Version: 3.26.0
 Summary: Python interface for ka9q-radio control and monitoring
 Author-email: Michael Hauan AC0G <ac0g@hauan.org>
 License: MIT
@@ -53,6 +53,7 @@ Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, S
 - [Documentation](#documentation)
 - [Examples](#examples)
 - [Use Cases](#use-cases)
+- [Troubleshooting](#troubleshooting)
 - [License](#license)
 
 ## Features
@@ -105,7 +106,7 @@ pip install -e .
 from ka9q import RadiodControl
 
 # Connect to radiod (default test host: bee1-hf-status.local)
-control = RadiodControl("bee1-hf-status.local")
+control = RadiodControl("bee1-hf-status.local", client_id="am-demo")
 
 # Create AM channel on 10 MHz WWV
 control.create_channel(
@@ -123,7 +124,7 @@ control.create_channel(
 ```python
 from ka9q import RadiodControl, Encoding
 
-control = RadiodControl("bee1-hf-status.local")
+control = RadiodControl("bee1-hf-status.local", client_id="hq-encoding-demo")
 
 # Create a channel with 32-bit float output (highest quality)
 control.ensure_channel(
@@ -139,7 +140,7 @@ control.ensure_channel(
 ```python
 from ka9q import RadiodControl
 
-control = RadiodControl("bee1-hf-status.local")
+control = RadiodControl("bee1-hf-status.local", client_id="wspr-demo")
 
 wspr_bands = [
     (1.8366e6, "160m"),
@@ -216,7 +217,7 @@ ensure your channels survive radiod restarts:
 ```python
 from ka9q import RadiodControl, ChannelMonitor
 
-control = RadiodControl("bee1-hf-status.local")
+control = RadiodControl("bee1-hf-status.local", client_id="monitor-demo")
 monitor = ChannelMonitor(control)
 monitor.start()
 
@@ -233,7 +234,7 @@ monitor.monitor_channel(
 `radiod` removes channels by polling for streams whose frequency is set to `0 Hz`. Always call `remove_channel(ssrc)` (or explicitly set `set_frequency(ssrc, 0.0)` if you build TLVs yourself) when tearing down a stream so the background poller can reclaim it:
 
 ```python
-with RadiodControl("bee1-hf-status.local") as control:
+with RadiodControl("bee1-hf-status.local", client_id="cleanup-demo") as control:
     info = control.ensure_channel(
         frequency_hz=10e6,
         preset="iq",
@@ -339,6 +340,49 @@ See [docs/RECIPES.md](docs/RECIPES.md) for worked examples of:
 - **Nimble channel switching** — single-channel SWL-style retuning driven from the CLI or an app
 - **SDR portability** — ka9q-python talks to `radiod`, which talks to the SDR; reporting frontend capabilities via `FrontendStatus`. Primary tested frontend is the RX888; AirspyR2 and Airspy HF+ support is in development.
 
+## Troubleshooting
+
+### Created channels never appear (silent write-path failure)
+
+**Symptom:** `discover_channels()` works — you can see the radiod's
+existing channels — but every `create_channel()` / `ensure_channel()`
+you issue "succeeds" (no exception from the send), and then the channel
+never shows up. The only visible error is a later
+`TimeoutError: Channel SSRC ... not verified within ...s` or a
+`poll_channel()` that returns `None` — neither of which names the cause.
+
+**Cause:** some hosts carry a kernel route that sends **all
+locally-originated multicast to loopback** (e.g. a `239.0.0.0/8 dev lo`
+entry). Inbound multicast still arrives on the real NIC — so discovery
+(the read path) looks healthy — while every outbound control command is
+routed to `lo` and never reaches radiod. There is no socket error: the
+packet is delivered, just to the wrong interface. This was
+tcpdump-confirmed during the 2026-08-12 audit: `tcpdump -i <nic>` saw
+zero command packets while `tcpdump -i lo` captured all of them
+(sourced from 127.0.0.1).
+
+**Check:**
+
+```bash
+# Substitute the group your radiod status DNS name resolves to:
+ip route get 239.205.73.40
+# BAD:  ... dev lo   src ...   <- commands never leave this host
+# GOOD: ... dev eth0 src ...
+```
+
+**Remedy:** pass your NIC's IP as `interface=` so ka9q-python sets
+`IP_MULTICAST_IF` on the send socket, overriding the kernel route:
+
+```python
+control = RadiodControl("bee1-status.local", interface="192.168.1.176")
+channels = discover_channels("bee1-status.local", interface="192.168.1.176")
+```
+
+**Rule of thumb:** a working `discover_channels()` proves only the
+*read* path. If reads work but writes vanish, check `ip route get`
+first — send-side ACKs don't exist in this protocol, so routing
+misconfiguration is otherwise invisible.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

{ka9q_python-3.20.0 → ka9q_python-3.26.0}/README.md

@@ -19,6 +19,7 @@ Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, S
 - [Documentation](#documentation)
 - [Examples](#examples)
 - [Use Cases](#use-cases)
+- [Troubleshooting](#troubleshooting)
 - [License](#license)
 
 ## Features
@@ -71,7 +72,7 @@ pip install -e .
 from ka9q import RadiodControl
 
 # Connect to radiod (default test host: bee1-hf-status.local)
-control = RadiodControl("bee1-hf-status.local")
+control = RadiodControl("bee1-hf-status.local", client_id="am-demo")
 
 # Create AM channel on 10 MHz WWV
 control.create_channel(
@@ -89,7 +90,7 @@ control.create_channel(
 ```python
 from ka9q import RadiodControl, Encoding
 
-control = RadiodControl("bee1-hf-status.local")
+control = RadiodControl("bee1-hf-status.local", client_id="hq-encoding-demo")
 
 # Create a channel with 32-bit float output (highest quality)
 control.ensure_channel(
@@ -105,7 +106,7 @@ control.ensure_channel(
 ```python
 from ka9q import RadiodControl
 
-control = RadiodControl("bee1-hf-status.local")
+control = RadiodControl("bee1-hf-status.local", client_id="wspr-demo")
 
 wspr_bands = [
     (1.8366e6, "160m"),
@@ -182,7 +183,7 @@ ensure your channels survive radiod restarts:
 ```python
 from ka9q import RadiodControl, ChannelMonitor
 
-control = RadiodControl("bee1-hf-status.local")
+control = RadiodControl("bee1-hf-status.local", client_id="monitor-demo")
 monitor = ChannelMonitor(control)
 monitor.start()
 
@@ -199,7 +200,7 @@ monitor.monitor_channel(
 `radiod` removes channels by polling for streams whose frequency is set to `0 Hz`. Always call `remove_channel(ssrc)` (or explicitly set `set_frequency(ssrc, 0.0)` if you build TLVs yourself) when tearing down a stream so the background poller can reclaim it:
 
 ```python
-with RadiodControl("bee1-hf-status.local") as control:
+with RadiodControl("bee1-hf-status.local", client_id="cleanup-demo") as control:
     info = control.ensure_channel(
         frequency_hz=10e6,
         preset="iq",
@@ -305,6 +306,49 @@ See [docs/RECIPES.md](docs/RECIPES.md) for worked examples of:
 - **Nimble channel switching** — single-channel SWL-style retuning driven from the CLI or an app
 - **SDR portability** — ka9q-python talks to `radiod`, which talks to the SDR; reporting frontend capabilities via `FrontendStatus`. Primary tested frontend is the RX888; AirspyR2 and Airspy HF+ support is in development.
 
+## Troubleshooting
+
+### Created channels never appear (silent write-path failure)
+
+**Symptom:** `discover_channels()` works — you can see the radiod's
+existing channels — but every `create_channel()` / `ensure_channel()`
+you issue "succeeds" (no exception from the send), and then the channel
+never shows up. The only visible error is a later
+`TimeoutError: Channel SSRC ... not verified within ...s` or a
+`poll_channel()` that returns `None` — neither of which names the cause.
+
+**Cause:** some hosts carry a kernel route that sends **all
+locally-originated multicast to loopback** (e.g. a `239.0.0.0/8 dev lo`
+entry). Inbound multicast still arrives on the real NIC — so discovery
+(the read path) looks healthy — while every outbound control command is
+routed to `lo` and never reaches radiod. There is no socket error: the
+packet is delivered, just to the wrong interface. This was
+tcpdump-confirmed during the 2026-08-12 audit: `tcpdump -i <nic>` saw
+zero command packets while `tcpdump -i lo` captured all of them
+(sourced from 127.0.0.1).
+
+**Check:**
+
+```bash
+# Substitute the group your radiod status DNS name resolves to:
+ip route get 239.205.73.40
+# BAD:  ... dev lo   src ...   <- commands never leave this host
+# GOOD: ... dev eth0 src ...
+```
+
+**Remedy:** pass your NIC's IP as `interface=` so ka9q-python sets
+`IP_MULTICAST_IF` on the send socket, overriding the kernel route:
+
+```python
+control = RadiodControl("bee1-status.local", interface="192.168.1.176")
+channels = discover_channels("bee1-status.local", interface="192.168.1.176")
+```
+
+**Rule of thumb:** a working `discover_channels()` proves only the
+*read* path. If reads work but writes vanish, check `ip route get`
+first — send-side ACKs don't exist in this protocol, so routing
+misconfiguration is otherwise invisible.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

{ka9q_python-3.20.0 → ka9q_python-3.26.0}/docs/GETTING_STARTED.md

@@ -47,13 +47,13 @@ The `RadiodControl` class is the primary interface for sending commands to `radi
 ### Step 2: Connect to radiod
 
 ```python
-control = RadiodControl("radiod.local")
+control = RadiodControl("radiod.local", client_id="getting-started")
 ```
 
-Replace `"radiod.local"` with the mDNS name or IP address of your `radiod` instance. If you're on a multi-homed system (multiple network interfaces), you may need to specify which interface to use:
+Replace `"radiod.local"` with the mDNS name or IP address of your `radiod` instance. `client_id` identifies this application so ka9q-python can derive a per-client multicast destination for the channels you create. If you're on a multi-homed system (multiple network interfaces), you may need to specify which interface to use:
 
 ```python
-control = RadiodControl("radiod.local", interface="192.168.1.100")
+control = RadiodControl("radiod.local", client_id="getting-started", interface="192.168.1.100")
 ```
 
 ### Step 3: Create a Channel
@@ -89,7 +89,7 @@ Here's the full program:
 from ka9q import RadiodControl
 
 # Connect to radiod
-control = RadiodControl("radiod.local")
+control = RadiodControl("radiod.local", client_id="getting-started")
 
 # Create AM channel for WWV 10 MHz
 control.create_channel(
@@ -194,7 +194,7 @@ def on_stream_restored(channel):
     print(f"✓ Stream restored: {channel.frequency/1e6:.3f} MHz")
 
 # Connect to radiod
-control = RadiodControl("radiod.local")
+control = RadiodControl("radiod.local", client_id="getting-started")
 
 # Create a self-healing stream
 stream = ManagedStream(

ka9q_python-3.26.0/docs/POLL-SUPPRESSION-DESIGN.md

@@ -0,0 +1,136 @@
+# Keeping channels alive on a shared control plane
+
+**Status:** design, not built. 2026-09-21.
+**Supersedes in practice:** the 30-second `set_channel_lifetime` keepalive.
+
+## What Phil asks of a controller
+
+Four rules, from ka9q's author on 2026-09-21:
+
+1. The control/status protocol stays **multicast, idempotent and shared**, so
+   several controllers can drive one radiod and all hold a coherent view.
+2. A controller sends configuration parameters autonomously **only** when
+   retransmitting a command whose tag has not yet been echoed. Otherwise it
+   sends an empty poll.
+3. Because every poll response dumps the whole channel state, a controller
+   should **share other controllers' responses** rather than ask again, and
+   should **randomize its poll timing**.
+4. A controller resets its poll timer when a status arrives that another
+   controller's poll triggered.
+
+And one prohibition that shapes everything below: no controller should
+automatically *correct* what it believes to be a wrong channel state. That
+starts a tuning war. State changes follow the user.
+
+## What we do today, and why it has to change
+
+`set_channel_lifetime(ssrc, 6000)` every 30 seconds per channel, carrying a
+re-asserted output encoding alongside. On AC0G-B4 that is 120 autonomous
+configuration broadcasts an hour, which every other controller on the plane
+must receive and parse.
+
+Rule 2 rules it out. Two measurements say we can drop it outright:
+
+- **An empty poll refreshes the self-destruct timer.** `decode_radio_commands`
+  begins `chan->lifetime = chan->lifestart`, for any command of length ≥ 2,
+  and `poll_channel` sends `COMMAND_TAG + OUTPUT_SSRC + EOL` and nothing
+  else. Measured on B4 2026-09-21: an unpolled control channel died at
+  37.7 s; a channel polled every 5 s outlived it and then died 43.7 s after
+  the polls stopped — one fresh lifetime from its last poll.
+- **The re-asserted encoding defends against nothing.** `loadpreset` sits
+  inside `case PRESET:` at both our pin and `ka9q/main`, so a LIFETIME-only
+  command never reaches it. Our own issue (HamSCI/ka9q-python#3) records that
+  we never reproduced the downgrade it guards against.
+
+## The design
+
+### The fact that makes it simple
+
+Every status packet carries the channel's **current remaining lifetime**
+(`radio_status.c`: `encode_int32(&bp,LIFETIME,chan->lifetime)`), and
+`status.py` already decodes it into `ChannelStatus.lifetime`.
+
+So a controller never has to *infer* whether someone else's command refreshed
+a timer. It reads the answer. When another controller polls a channel we own,
+the next status we see carries a lifetime that has jumped back up, and our
+own poll becomes unnecessary — rules 3 and 4 satisfied by observation rather
+than by bookkeeping about tags.
+
+That turns the keepalive from open loop (fire every 30 s regardless) into
+closed loop (act when the channel actually needs it).
+
+### Shape
+
+A `ChannelKeepalive` holding, per owned SSRC:
+
+- `lifetime_frames` — the last value seen in a status
+- `observed_at` — the monotonic time of that reading
+- `block_time_s` — measured, not assumed (see below)
+
+On each tick it projects the remaining lifetime forward from the last
+reading, and polls a channel only when that projection falls under a
+threshold, with jitter applied so two controllers do not synchronise.
+
+```
+remaining_s ≈ (lifetime_frames × block_time_s) − (now − observed_at)
+poll when    remaining_s < threshold_s × uniform(0.85, 1.15)
+```
+
+### Three things that must not go wrong
+
+**⛔ Absence of status must never read as health.** If no status has arrived
+for a channel within some bound, the controller knows nothing about its
+lifetime and must poll unconditionally. A suppression rule whose quiet state
+is "do nothing" turns a dropped multicast group into a fleet of channels
+quietly self-destructing. The fail-safe direction is to poll.
+
+**⛔ Suppression is per-SSRC, never global.** `chan->lifetime` is refreshed by
+a command addressed to *that channel*. Another controller polling a different
+SSRC refreshes nothing of ours. Seeing traffic on the plane is not evidence
+our channel was touched; seeing a status *for our SSRC* is.
+
+**⚠ Block time is a measurement, not a constant.** `lifetime` counts radiod
+main-loop blocks, and the conversion to seconds depends on the configured
+block time. B4 measured ~18.9 ms on 2026-09-21 (2000 frames ≈ 37.7 s) with no
+`blocktime` in its radiod config, so that is a default rather than a fleet
+constant. Derive it per station by watching the lifetime count down between
+two statuses, and fall back to polling on a fixed short period when it cannot
+be derived.
+
+### Threshold
+
+Margin has to cover the status cadence (`STATUS_INTERVAL`), the poll round
+trip, and lost packets on a multicast group with no retransmission. A
+threshold near a third of the configured lifetime leaves room for two missed
+statuses before the channel is at risk. With our 6000 frames ≈ 113 s, that
+puts a poll roughly every 35–40 s in the worst case — no worse than today —
+while a plane with several active controllers should see us poll rarely.
+
+### What it needs from the library
+
+`ChannelInfo` does not carry `lifetime`, though `ChannelStatus` does. Same
+plumbing gap that `demod_type` and `output_channels` had, and the same fix:
+decode it in `decode_status_dict` and pass it through in `discovery.py`.
+
+## What this design refuses to do
+
+It does not reconcile channel state. If a status shows a frequency or a
+filter we did not ask for, the keepalive records it and says nothing. Putting
+it back is the tuning war Phil warns against, and a controller that "knows
+better" than the operator is exactly the thing a shared plane cannot carry.
+
+`ChannelManager.ensure_channels_exist(update_existing=...)` already defaults
+to `False` and is reached only from operator-invoked CLI verbs. That default
+is load-bearing on a shared plane and should be commented as such, rather
+than left looking like an ordinary convenience.
+
+## Testing it
+
+The arrangement that settled the empty-poll question generalises: run two
+channels, drive one and leave the other, and let the untouched arm reveal the
+timescale. Then stop driving the first and confirm it dies — without that
+third arm, survival proves nothing about cause.
+
+For suppression specifically, the case worth building is two controllers on
+one SSRC: confirm the second suppresses while the first polls, and — the one
+that matters — confirm it resumes promptly when the first goes away.

{ka9q_python-3.20.0 → ka9q_python-3.26.0}/docs/RECIPES.md

@@ -161,7 +161,7 @@ def make_callback(label):
         handle(label, samples, quality)
     return on_samples
 
-with RadiodControl("bee3-status.local") as control:
+with RadiodControl("bee3-status.local", client_id="band-recorder") as control:
     multi = MultiStream(control=control)
     for label, fhz, preset, rate in BAND_PLAN:
         multi.add_channel(
@@ -241,7 +241,7 @@ retune it in place.
 ```python
 from ka9q import RadiodControl, ManagedStream
 
-with RadiodControl("bee1-hf-status.local") as control:
+with RadiodControl("bee1-hf-status.local", client_id="swl-tuner") as control:
     stream = ManagedStream(
         control=control,
         frequency_hz=14.074e6,
@@ -323,7 +323,7 @@ For a desktop-style tuner, the usual shape is:
 ```python
 class Receiver:
     def __init__(self, host):
-        self._control = RadiodControl(host)
+        self._control = RadiodControl(host, client_id="swl-tuner")
         self._stream = ManagedStream(
             control=self._control,
             frequency_hz=14.200e6,
@@ -653,7 +653,7 @@ frequency with `ManagedStream`. Both use the same `RadiodControl`:
 ```python
 from ka9q import RadiodControl, SpectrumStream, ManagedStream
 
-with RadiodControl("radiod.local") as ctl:
+with RadiodControl("radiod.local", client_id="spectrogram-demo") as ctl:
     # Wideband spectrum display
     spectrum = SpectrumStream(
         control=ctl,

{ka9q_python-3.20.0 → ka9q_python-3.26.0}/docs/REQUIREMENTS.md

@@ -224,6 +224,12 @@ ka9q-python's "actors" are its consumers and the protocol it tracks:
   concurrent long-running use.
 - `KQP-Q-003` `[CODE]` ✅ Receive sockets SHALL set **`SO_RCVBUF` = 64 MB** on
   both `RadiodStream` and `MultiStream` to resist GIL-stall packet loss.
+- `KQP-Q-010` `[CODE]` ✅ Every delivered sample batch SHALL carry the true
+  RTP timestamp of its FIRST sample (`StreamQuality.delivered_rtp_start`,
+  gap fills included), computed from the resequencer's emission tracking.
+  Consumers labelling samples SHALL prefer it over `last_rtp_timestamp`
+  (the last RECEIVED packet's header), which desynchronizes from the
+  delivered stream under loss. (2026-08-11; hf-timestd T6 origin slips.)
 - `KQP-Q-004` `[CODE]` ✅ `ManagedStream` SHALL recover automatically from
   radiod restart and network interruption without consumer intervention.
 - `KQP-Q-005` `[DOC]` ✅ Protocol definitions SHALL be **provably in sync** with