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..20403c6446c --- /dev/null +++ b/quest/m1/binding-timestamps.md @@ -0,0 +1,61 @@ +# [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 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. +- **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, an +out-of-range scale, 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