From 069d4bd7ece4f4e5c1a4ab6223b75f553dcc64bd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 17 Oct 2026 21:00:24 -0700 Subject: [PATCH 1/2] quest(m1): plan exact timestamps in every binding Bindings carry {value, scale} timestamps mirroring moq_net::Timestamp instead of lossy microsecond fields, after #5677 lands. Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/binding-timestamps.md | 60 ++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 quest/m1/binding-timestamps.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 93f3222a7d9..de2571ffdf9 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -73,6 +73,7 @@ lands before the cut. - [Lazy discovery](/quest/m1/lazy-discovery/README.md) - a `consume` session requests announcements only for prefixes the origin is watching, in JS then Rust; `follow`, `broadcasts`, and the `discovery` option go away - [A spinning loop fails a sim test](/quest/m1/spinning-loops.md) - a sim test names any loop that holds a task poll too long, and each one yields through a budget - [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - json and binary consumers return each value's timestamp, in Rust and every binding; snapshots add `latest()` beside an in-order `next()` +- [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds - [JSON window timestamps](/quest/m1/json-window-timestamps.md) - Rust and JS window consumers return each event's frame timestamp like the snapshot and stream consumers - [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface - [IETF fill timeout](/quest/m1/ietf-fill-timeout.md) - native FILL_TIMEOUT bounds upstream waiting on drafts 18-22, alongside local content-age enforcement diff --git a/quest/m1/binding-timestamps.md b/quest/m1/binding-timestamps.md new file mode 100644 index 00000000000..817bddac443 --- /dev/null +++ b/quest/m1/binding-timestamps.md @@ -0,0 +1,60 @@ +# [L] Exact timestamps in every binding + +## Goal + +Every binding (moq-ffi, moq-c, cpp and cpp/obs, and the py, swift, kt, go and +dart wrappers) carries media timestamps as an exact `{value, scale}` record +mirroring `moq_net::Timestamp`, with untimed as absent. It replaces the lossy +microsecond fields on frames, datagrams, media and audio frames, producer +arguments, and the data values that +[Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) adds. + +The Rust core and `@moq/net` already carry exact timestamps. Wire: none. +Public API: breaking in every binding. + +## Plan + +Today every binding speaks microseconds: moq-ffi `timestamp_us: Option` +(about 160 sites in 9 files: `MoqFrame`, `MoqDatagram`, `MoqMediaFrame`, audio +frames, json/flate producer `update`/`append`, media `flush`), moq-c +`timestamp_us` plus `timestamp_present` pairs (about 140 sites in 6 files), and +each wrapper's native type (Python `timedelta`, Go `*time.Duration`, Swift +`UInt64`, Kotlin `Duration`, Dart `int`, C++ `std::optional`, OBS +microseconds). Reads floor through `as_micros()`, so any scale that does not +divide a microsecond loses: a 90 kHz tick reads as 11 µs, and republishing it +onto a 90 kHz track floors again to tick 0. + +Decided with the maintainer on 2026-10-18: + +- **Scope is the bindings only.** The core and JS types stay as they are. +- **m1**, beside data consumer timestamps. +- **Lands after #5677**, which ships the data-value timestamps with the + interim microsecond fields; this quest converts every site at once, + `MoqJsonValue` included. +- **Shape mirrors the core:** one `{value, scale}` per value, `value` at most + `2^62 - 1` and `scale` non-zero. The FFI boundary refuses anything else with + an error. Rejected: raw ticks at the track scale beside + `MoqTrackInfo.timescale`, because a producer argument needs its own scale + and per-value records match the core and JS. +- **Names:** UniFFI record `MoqTimestamp`, C `moq_timestamp`, wrappers + `Timestamp`. +- **C untimed is a nullable pointer:** `const moq_timestamp *`, `NULL` for + untimed, in arguments and callback structs. No sentinel scale and no + `_present` flag; the existing `timestamp_present` pairs go. +- **Wrappers expose the record plus duration helpers** to and from the + language's duration type (`timedelta`, `Duration`, `time.Duration`, ...). + From a duration is exact at the duration's own scale. To a duration rounds + to nearest and says so in its doc; the record itself stays exact. +- **One PR across every binding**, per the cross-package sync table, so each + binding breaks once. No shim: the microsecond fields are removed, not kept + beside the record. Each package gets a `MIGRATE.md` entry, and `doc/lib/*` + and `doc/bin/obs.md` update in the same PR. + +Verification: round-trip a 90 kHz tick, a present zero, and untimed through +moq-ffi, moq-c, C++ and every wrapper's tests; refuse scale 0 and an +out-of-range value; `just test interop --all`. + +## Related + +- [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - lands first with the interim microsecond fields this replaces +- [Controlled time](/quest/m1/time/README.md) - wall and monotonic time, not media timestamps; keep the types distinct From c7836899c45eb6d402d5cc08f97a713c7176bc64 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 17 Oct 2026 21:07:11 -0700 Subject: [PATCH 2/2] quest(m1): bound the binding timestamp scale like the core Co-Authored-By: Claude Opus 5.5 --- quest/m1/binding-timestamps.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/quest/m1/binding-timestamps.md b/quest/m1/binding-timestamps.md index 817bddac443..20403c6446c 100644 --- a/quest/m1/binding-timestamps.md +++ b/quest/m1/binding-timestamps.md @@ -32,7 +32,8 @@ Decided with the maintainer on 2026-10-18: interim microsecond fields; this quest converts every site at once, `MoqJsonValue` included. - **Shape mirrors the core:** one `{value, scale}` per value, `value` at most - `2^62 - 1` and `scale` non-zero. The FFI boundary refuses anything else with + `2^62 - 1` and `scale` non-zero and at most `2^62 - 1`, matching + `Timestamp::new` and `Timescale::new`. The FFI boundary refuses anything else with an error. Rejected: raw ticks at the track scale beside `MoqTrackInfo.timescale`, because a producer argument needs its own scale and per-value records match the core and JS. @@ -51,8 +52,8 @@ Decided with the maintainer on 2026-10-18: and `doc/bin/obs.md` update in the same PR. Verification: round-trip a 90 kHz tick, a present zero, and untimed through -moq-ffi, moq-c, C++ and every wrapper's tests; refuse scale 0 and an -out-of-range value; `just test interop --all`. +moq-ffi, moq-c, C++ and every wrapper's tests; refuse scale 0, an +out-of-range scale, and an out-of-range value; `just test interop --all`. ## Related