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

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

@@ -1,5 +1,54 @@
 # Changelog
 
+## [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)
+
+- **Removed `SlotClock.divergence_sec`** (added in 3.18.0). It recomputed a
+  boundary's UTC from the live, StatusListener-refreshed `channel_info` and
+  compared it to the grid — inviting consumers to re-anchor when the two
+  disagree. In practice a busy radiod's status pair (`gps_time`/`rtp_timesnap`)
+  jitters ~0.45 s and occasionally tears between ~450 ms snapshots, so the check
+  reported large spurious divergences and drove downstream recorders into a
+  re-anchor storm. The `SlotClock` grid is RTP-driven and drift-immune by
+  design; nothing should second-guess it against the noisy status feed.
+
+- **Removed the per-update RTP↔GPS offset-step detection in
+  `ChannelInfo.update_anchor`** (`discovery.py`). It bumped `anchor_epoch` and
+  logged a loud `radiod RTP↔GPS offset STEPPED … (consumers will re-anchor)`
+  WARNING whenever consecutive status snapshots implied a stepped offset — but
+  that "step" was almost always status-feed jitter/tearing, not a real radiod
+  slide (radiod's RTP data path stayed consistent; decodes never stopped).
+  `update_anchor` now simply adopts the latest anchor pair. The `anchor_epoch`,
+  `last_offset_step_sec`, and `anchor_step_threshold_sec` fields remain
+  (vestigial, at their defaults) for backward compatibility.
+
+The principle: **anchor once off radiod's RTP timestamp and defer to it.** A
+genuine radiod restart is still handled downstream via the stream-restored path
+(MultiStream's drop/restore callback), not by polling the status feed for
+divergence. The sigmond recorders (psk/meteor/wspr) drop their matching
+re-anchor machinery in lockstep.
+
 ## [3.18.0] - 2026-06-28
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.18.0
+Version: 3.20.0
 Summary: Python interface for ka9q-radio control and monitoring
 Author-email: Michael Hauan AC0G <ac0g@hauan.org>
 License: MIT

{ka9q_python-3.18.0 → ka9q_python-3.20.0}/ka9q/__init__.py

@@ -115,7 +115,7 @@ from .managed_stream import (
     StreamState,
 )
 from .multi_stream import MultiStream
-from .slot_clock import SlotClock, Slot, rtp_diff
+from .slot_clock import SlotClock, Slot, SlotClockDesyncError, rtp_diff
 from .spectrum_stream import SpectrumStream
 from .status_listener import StatusListener, StatusListenerStats
 
@@ -165,6 +165,7 @@ __all__ = [
     # Slot timing (epoch-aligned, RTP-referenced)
     'SlotClock',
     'Slot',
+    'SlotClockDesyncError',
     'rtp_diff',
 
     # Stream API (sample-oriented)

{ka9q_python-3.18.0 → ka9q_python-3.20.0}/ka9q/discovery.py

@@ -132,9 +132,6 @@ class ChannelInfo:
         ``_anchor_pair``.  Tuple is written first so the atomic snapshot
         is the leading edge of any state change.
         """
-        # Snapshot the previous pair BEFORE overwriting, for step detection.
-        prev = getattr(self, '_anchor_pair', None)
-
         # Atomic pair first — this is the source of truth for
         # transactional readers.
         self._anchor_pair = (gps_time, rtp_timesnap)
@@ -144,36 +141,14 @@ class ChannelInfo:
         # ``.gps_time`` directly sees the current value.
         self.gps_time = gps_time
         self.rtp_timesnap = rtp_timesnap
-
-        # ── Offset-step detection ──
-        # Consecutive snapshots are ~450 ms apart, so the signed 32-bit RTP
-        # delta is tiny (no wrap ambiguity, unlike the projection path in
-        # rtp_to_wallclock).  ``move_sec`` is the change in the RTP→GPS
-        # mapping: ~0 when radiod is consistent, a gross jump when it steps.
-        # Only the StatusListener thread calls update_anchor (single writer),
-        # so the ``anchor_epoch += 1`` read-modify-write is race-free; the
-        # epoch is bumped AFTER ``_anchor_pair`` is published so any reader
-        # that observes the new epoch also reads the new (or newer) anchor.
-        if (
-            prev is not None
-            and prev[0] is not None
-            and prev[1] is not None
-            and self.sample_rate
-        ):
-            d_rtp = int((rtp_timesnap - prev[1]) & 0xFFFFFFFF)
-            if d_rtp > 0x7FFFFFFF:
-                d_rtp -= 0x100000000
-            move_sec = (
-                (gps_time - prev[0]) - d_rtp * 1_000_000_000 / self.sample_rate
-            ) / 1e9
-            if abs(move_sec) > self.anchor_step_threshold_sec:
-                self.last_offset_step_sec = move_sec
-                self.anchor_epoch += 1
-                logger.warning(
-                    "ChannelInfo ssrc=%s: radiod RTP↔GPS offset STEPPED "
-                    "%+.3fs — anchor_epoch=%d (consumers will re-anchor)",
-                    self.ssrc, move_sec, self.anchor_epoch,
-                )
+        # NOTE (2026-06-28): the per-update RTP↔GPS offset-step detection was
+        # removed.  It compared consecutive ~450 ms status snapshots and bumped
+        # ``anchor_epoch`` (with a loud WARNING) on any jump — but a busy
+        # radiod's status pair jitters/tears at that cadence, so it fired
+        # constantly and drove downstream recorders into a re-anchor storm.
+        # We now simply adopt the latest pair and defer to radiod's RTP; the
+        # ``anchor_epoch`` / ``last_offset_step_sec`` fields remain (vestigial,
+        # at their defaults) for backward compatibility.
 
 
 def _create_status_listener_socket(multicast_addr: str, interface: Optional[str] = None) -> socket.socket:

{ka9q_python-3.18.0 → ka9q_python-3.20.0}/ka9q/slot_clock.py

@@ -68,6 +68,28 @@ def rtp_diff(a: int, b: int) -> int:
     return d
 
 
+# Largest single unwrap step (in samples) we trust from the high-water.  The
+# signed-32 unwrap is only unambiguous within +/-2**31 of the high-water; we
+# refuse anything past the half-window (2**30 ~= 24.8 h @ 12 kHz, ~4.7 h @
+# 64 kHz IQ) so the unwrap fails LOUD with a wide margin instead of silently
+# aliasing a huge forward jump into a backward step (-> advance() harvests 0
+# slots on live RF: the exact silent failure SlotClock exists to prevent).
+# Continuous advancing steps by a few hundred samples per call, so this never
+# false-fires in normal operation — only a >24.8 h stall, a missed re-anchor,
+# or a bogus/discontinuous timestamp reaches it.
+_SAFE_UNWRAP_SAMPLES = 2 ** 30
+
+
+class SlotClockDesyncError(RuntimeError):
+    """A wrapped RTP timestamp is too far from the unwrap high-water to be
+    disambiguated (a >24.8 h gap, a missed re-anchor, or a discontinuous/bogus
+    timestamp).  The grid can no longer be trusted from this timestamp alone;
+    the caller must re-anchor against a fresh RTP reference.  ``advance``
+    catches this, drops the anchor, and returns no slots, so the caller's
+    normal ``if not clk.anchored: clk.anchor(...)`` path re-establishes the
+    grid rather than silently stalling at zero decodes."""
+
+
 @dataclass(frozen=True)
 class Slot:
     """One completed, epoch-aligned slot.
@@ -189,10 +211,26 @@ class SlotClock:
         within the last slot), which are always within one signed-32 window of
         the high-water — so the unwrap is unambiguous.  Advances the high-water
         when a query is ahead of it; never rewinds it on a stale/past query.
+
+        Raises ``SlotClockDesyncError`` if the timestamp is more than
+        ``_SAFE_UNWRAP_SAMPLES`` (half the signed-32 window) from the
+        high-water in either direction: at that distance a wrapped 32-bit
+        value can no longer be told apart from a ~2**32-aliased one, so any
+        unwrap would be a guess.  This converts the old silent alias (huge
+        forward jump read as a backward step -> 0 slots forever) into a loud,
+        recoverable signal.
         """
         assert self._anchor_rtp is not None
         ref_rtp = (self._anchor_rtp + self._latest_off) & 0xFFFFFFFF
-        off = self._latest_off + rtp_diff(rtp_timestamp, ref_rtp)
+        delta = rtp_diff(rtp_timestamp, ref_rtp)
+        if abs(delta) > _SAFE_UNWRAP_SAMPLES:
+            raise SlotClockDesyncError(
+                f"rtp={rtp_timestamp} is {delta} samples from the unwrap "
+                f"high-water (offset {self._latest_off}); |delta| exceeds the "
+                f"safe window {_SAFE_UNWRAP_SAMPLES} — cannot unwrap "
+                f"unambiguously, re-anchor required"
+            )
+        off = self._latest_off + delta
         if off > self._latest_off:
             self._latest_off = off
         return off
@@ -209,7 +247,21 @@ class SlotClock:
         """
         if self._anchor_rtp is None or self._next_boundary_off is None:
             return []
-        latest_off = self.offset_of_rtp(latest_rtp_timestamp)
+        try:
+            latest_off = self.offset_of_rtp(latest_rtp_timestamp)
+        except SlotClockDesyncError as exc:
+            # A wrapped timestamp this far from the high-water can't be
+            # unwrapped safely.  Fail LOUD and drop the anchor so the caller's
+            # ``if not anchored: anchor()`` path re-establishes the grid on a
+            # fresh RTP reference — instead of silently harvesting 0 slots on
+            # live RF (the failure mode this whole class exists to prevent).
+            logger.error(
+                "SlotClock(cadence=%.3fs, sr=%d): %s; dropping anchor to force "
+                "a clean re-anchor (was at slot index %d)",
+                self.cadence_sec, self.sample_rate, exc, self._next_index,
+            )
+            self.reset()
+            return []
         out: List[Slot] = []
         while latest_off >= (
             self._next_boundary_off + self.cadence_samples + self.settle_samples
@@ -226,33 +278,3 @@ class SlotClock:
             self._next_boundary_off = start_off + self.cadence_samples
             self._next_index += 1
         return out
-
-    # ── RTP-reference re-validation ──────────────────────────────────
-
-    def divergence_sec(self, channel_info, rtp_to_utc) -> Optional[float]:
-        """Grid-vs-GPS divergence at the next boundary, in seconds.
-
-        Recomputes the next boundary's true UTC straight from radiod's
-        (StatusListener-refreshed) ``channel_info`` via ``rtp_to_utc``
-        and compares it to the grid projection.  A sustained nonzero result
-        means the anchor is stale/wrong — the caller should ``anchor()``
-        again off the fresh reference.  Returns None if it can't be computed.
-
-        ``rtp_to_utc`` is passed in (rather than imported) so the caller binds
-        the exact projector it anchored with; ``ka9q.rtp_to_wallclock`` works
-        too as a deprecated alias of the same function.
-        """
-        if self._anchor_rtp is None or self._next_boundary_off is None:
-            return None
-        boundary_rtp = self.rtp_of_offset(self._next_boundary_off)
-        projected = self.utc_of_offset(self._next_boundary_off)
-        try:
-            ref = rtp_to_utc(
-                boundary_rtp, channel_info, wallclock_hint_sec=projected,
-            )
-        except Exception as exc:  # noqa: BLE001 — detection must not crash audio
-            logger.debug("SlotClock divergence check raised: %s", exc)
-            return None
-        if ref is None:
-            return None
-        return projected - ref

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.18.0
+Version: 3.20.0
 Summary: Python interface for ka9q-radio control and monitoring
 Author-email: Michael Hauan AC0G <ac0g@hauan.org>
 License: MIT

{ka9q_python-3.18.0 → ka9q_python-3.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ka9q-python"
-version = "3.18.0"
+version = "3.20.0"
 description = "Python interface for ka9q-radio control and monitoring"
 readme = "README.md"
 authors = [

{ka9q_python-3.18.0 → ka9q_python-3.20.0}/tests/test_slot_clock.py

@@ -3,7 +3,13 @@ import math
 
 import pytest
 
-from ka9q.slot_clock import SlotClock, Slot, rtp_diff
+from ka9q.slot_clock import (
+    SlotClock,
+    Slot,
+    SlotClockDesyncError,
+    rtp_diff,
+    _SAFE_UNWRAP_SAMPLES,
+)
 
 
 SR = 12000
@@ -136,6 +142,44 @@ def test_offset_of_rtp_unwraps_past_window():
     assert off > 2 ** 31  # we genuinely crossed the signed-32 boundary
 
 
+def test_safe_unwrap_limit_allows_full_half_window_step():
+    """A single step of exactly the safe limit (half the signed-32 window) is
+    still unambiguous and must be accepted — the guard rejects only *past* it."""
+    clk = SlotClock(15.0, SR)
+    clk.anchor(rtp_timestamp=0, utc=900_000_000.0)
+    off = _SAFE_UNWRAP_SAMPLES
+    assert clk.offset_of_rtp(off & 0xFFFFFFFF) == off
+
+
+def test_offset_of_rtp_raises_on_ambiguous_jump():
+    """A single unwrap step past the safe half-window can alias a huge forward
+    jump into a backward step; offset_of_rtp must raise rather than guess."""
+    clk = SlotClock(15.0, SR)
+    clk.anchor(rtp_timestamp=0, utc=900_000_000.0)
+    with pytest.raises(SlotClockDesyncError):
+        clk.offset_of_rtp((_SAFE_UNWRAP_SAMPLES + 1) & 0xFFFFFFFF)
+
+
+def test_advance_big_jump_fails_loud_and_drops_anchor(caplog):
+    """Regression: a single advance() forward jump > 2**31 from the anchor used
+    to alias to a backward step and silently harvest 0 slots forever (live RF,
+    zero decodes).  The guard must instead log loudly, drop the anchor, and
+    return [] so the caller re-anchors — turning a silent stall into recovery."""
+    clk = SlotClock(15.0, SR, settle_sec=1.5)
+    clk.anchor(rtp_timestamp=0, utc=900_000_000.0)
+    # 50 h in samples: 2,160,000,000 > 2**31 (2,147,483,648) in ONE call.
+    big = 50 * 3600 * SR & 0xFFFFFFFF
+    with caplog.at_level("ERROR"):
+        slots = clk.advance(big)
+    assert slots == []                 # no garbage slots
+    assert not clk.anchored            # anchor dropped -> caller must re-anchor
+    assert any("SlotClock" in r.message for r in caplog.records)
+    # and recovery works: re-anchor near the real leading edge, harvest normally
+    clk.anchor(rtp_timestamp=big, utc=900_180_000.0)  # multiple of 15
+    out = clk.advance((big + 180000 + 24000 + 1) & 0xFFFFFFFF)
+    assert len(out) == 1 and out[0].index == 0
+
+
 def test_settle_delays_completion():
     clk = SlotClock(15.0, SR, settle_sec=2.0)
     clk.anchor(rtp_timestamp=0, utc=900_000_000.0)  # 900000000 % 15 == 0 -> boundary0 at offset 0