Skip to content

ADR 0007: Paired session and sample clock

  • Status: accepted
  • Date: 2026-08-27

Context

The v1 IQ header carries a 64-bit server monotonic timestamp and a sample counter, but monotonic time alone cannot align FT8, WSPR, broadcast time, or recorded decoder events to UTC. JavaScript numbers also cannot represent nanosecond epoch values exactly.

Decision

session.ready carries an additive anchor containing paired CLOCK_REALTIME and CLOCK_MONOTONIC nanoseconds as decimal strings plus measured uncertainty. The gateway samples monotonic time immediately before and after realtime; their midpoint is the anchor and half their span is its uncertainty.

IQ frame timestamps denote assembly of a completed block. The decoder clock derives its first-sample monotonic time from the exact block duration, maps it through the session anchor, and advances arbitrary sample counters in integer nanoseconds. Every gap, overflow, retune, settings boundary, replay seek, or route/session change starts a new capture epoch.

SigMF core:datetime and explicit raw-CU8 capture time create replay-metadata anchors at monotonic zero. Missing or malformed timestamps remain unavailable. Decoders whose manifest requires UTC must reject input whose anchor is absent or exceeds their allowed uncertainty.

Consequences

The binary IQ v1 header is unchanged, existing control clients remain compatible, and UTC-aligned decoders can report their timing provenance rather than relying on the browser's arrival time. A long-running client must treat a later system-clock step as a new anchor/epoch when periodic anchor refresh is implemented; Phase 6A deliberately makes no silent drift correction.