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

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

@@ -1,5 +1,25 @@
 # 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)

{ka9q_python-3.19.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.19.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.19.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.19.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

{ka9q_python-3.19.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.19.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.19.0 → ka9q_python-3.20.0}/pyproject.toml

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

{ka9q_python-3.19.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