ka9q-python 3.19.0__tar.gz → 3.22.0__tar.gz

{ka9q_python-3.19.0 → ka9q_python-3.22.0}/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## 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)
+
+- **`SlotClock.offset_of_rtp` now raises `SlotClockDesyncError`** when a wrapped
+  RTP timestamp is more than `2**30` samples (half the signed-32 window, ~24.8 h
+  @ 12 kHz / ~4.7 h @ 64 kHz IQ) from the unwrap high-water in either direction.
+  The high-water unwrap (3.18.0) keeps continuous streams correct past the
+  `2**31` window, but it only disambiguates while each step stays within
+  `±2**31` of the high-water. A *single* forward jump `>= 2**31` samples (a
+  `>49.7 h` stall-then-resume, a missed re-anchor, or a discontinuous timestamp)
+  aliased into a backward step — `advance()` then harvested **0 slots forever on
+  live RF**, the exact silent failure `SlotClock` exists to prevent.
+- **`SlotClock.advance` catches the desync, logs an ERROR, drops the anchor, and
+  returns `[]`**, so the caller's normal `if not clk.anchored: clk.anchor(...)`
+  path re-establishes the grid on a fresh RTP reference instead of stalling. The
+  `2**30` margin never false-fires: continuous advancing steps a few hundred
+  samples per call.
+- **`SlotClockDesyncError` is exported** from the package.
+
 ## [3.19.0] - 2026-06-28
 
 ### Removed / Changed — simplify how we look at radiod (defer to RTP)

{ka9q_python-3.19.0/ka9q_python.egg-info → ka9q_python-3.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.19.0
+Version: 3.22.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.19.0 → ka9q_python-3.22.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.19.0 → ka9q_python-3.22.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.19.0 → ka9q_python-3.22.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.19.0 → ka9q_python-3.22.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

ka9q_python-3.22.0/docs/audit/2026-08-12-alignment/README.md

@@ -0,0 +1,52 @@
+# Upstream Alignment & Client-Compat Audit — 2026-08-12
+
+Audit of ka9q-python's alignment with `ka9q-radio` upstream
+(`14d780af624e821941708bd0d64fd895a0c80a2a` →
+`cedec349f7b4212078de3e007d142b4c64d36546`, 149 commits) and its
+sigmond-suite client contracts. Read `findings.md` first — it is the
+document Checkpoint A reviews.
+
+## Reports
+
+| File | Task | Contents |
+|---|---|---|
+| [`upstream.md`](./upstream.md) | 2 | Drift-watcher verdict, full 149-commit classification |
+| [`contract.md`](./contract.md) | 3 | Enum-level header diff, `sync_types.py` reconciliation, pin-advance verdict |
+| [`control-surface.md`](./control-surface.md) | 4 | Every writable/readable radiod TLV mapped against `RadiodControl`/`status.py` |
+| [`clients.md`](./clients.md) | 5 | Per-client symbol contract matrix + no-bypass sweep across all `/opt/git/sigmond` repos |
+| [`idempotency.md`](./idempotency.md) | 6–7 | Five idempotency spec questions, code-level verdicts, and live probes against `bee1`/`bee2` radiod |
+| [`findings.md`](./findings.md) | 8 | **This audit's output** — every finding above, ranked P0–P3 with evidence links and remediation |
+
+## Executive summary
+
+**Drift verdict:** `CONTRACT: CRITICAL-CHANGE — DO NOT ADVANCE` (Task 3).
+The only client-visible enum change in range is `DemodType.N_DEMOD`
+shifting 5→6 (upstream inserted `IDLE_DEMOD`); `check_upstream_drift.py`'s
+`STREAM_CRITICAL_ENUMS` policy classifies this `fail` regardless of usage.
+Zero live code anywhere references `N_DEMOD` by value, so nothing decodes
+wrong today — the block is a mechanical policy trigger, not a demonstrated
+break (see `findings.md` F2).
+
+**Is the pin safe to advance?** Not yet, per the mechanical gate — but the
+remediation is small and well-scoped: regenerate `types.py`
+(`sync_types.py --apply`, plus a manual add for the negative-literal
+`INVALID_DEMOD` the parser misses — F10), widen `control.py`'s hardcoded
+demod-range check (F13), then re-run the watcher. None of this is an
+emergency fix for a live bug; it's the normal Task 4/9 capability-exposure
+step this project's process expects before a pin with a flagged enum
+change advances.
+
+**Findings:** 23 total — **1 P0, 9 P1, 4 P2, 9 P3**. The P0 (`F1`) is
+`MultiStream`'s restore path silently changing a channel's SSRC identity
+on recovery when a channel has non-default gain/AGC — the shared
+recovery substrate every major sigmond client depends on. Several P1s are
+environment/deployment findings from the live Task 7 probes (silent
+`destination=` failure, a host-routing trap that swallows outbound control
+commands with zero error, and a keepalive docstring claim that doesn't
+hold empirically) — each is explicitly flagged with its own ambiguity
+note rather than forced into a clean bucket, per the audit's ranking
+rubric. Zero confirmed no-bypass violations exist among sigmond-authored
+Python clients (`clients.md`); the one bypass found (`ka9q-web`, vendored
+third-party C) is a policy-scope question, not a ka9q-python code fix.
+
+**Artifact:** https://claude.ai/code/artifact/13cb509f-9248-49ed-bb05-0be0354d4361