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.