[kixelated]

Completes quest quest/m1/refresh/json.md.

Snapshot and window groups no longer roll on a byte budget. A group runs until a joiner wants a fresh one, judged by the track's refresh ratio (Demand::wanted passing the largest group), and the producer then restates the value or window in a new group at the timestamp of the last committed update. The frame and byte caps stay. This work does not depend on the relay PR moq-dev/moq#6030: a local join already moves wanted.

Changes

• moq-json (Rust): snapshot::Config::delta_ratio and window::ProducerConfig::op_ratio become deltas: bool and ops: bool (default true). New Encoder::snapshot() for both modes. Producers gain refresh().await and poll_refresh(waiter), which the owner drives because the producer has no runtime. The demand watch is a private crate::refresh::Refresh.
• @moq/json (JS): deltaRatio and opRatio become deltas and ops. Encoder.snapshot() is added for both modes. Producers watch track.demand().wanted themselves and stop on finish().
• moq-mux: json::Config::with_deltas, plus json::Snapshot::refresh and poll_refresh. The catalog producer uses deltas = false. The timeline track carries refresh(8) and answers a refresh before each edit.
• moq-ffi: MoqJsonSnapshotConfig.deltas. Each snapshot producer runs a refresh task (via ffi::spawn) until finish or drop. Bindings gain no refresh API.
• moq-c: moq_json_snapshot_config.deltas. With deltas on, the track gets refresh = 8 and a refresh task that stops when the entry is removed.
• Bindings: py, swift, go (Deltas *bool), kt and dart (regenerated) follow, along with MIGRATE.md entries and the moq-json and @moq/json doc pages.
• In-repo callers:
  • moq-stats restates on the next tick through encoder.reset().
  • moq-boy status answers before each publish.
  • moq-room and js/room chat use ops: false.
  • The js/publish catalog uses deltas: false.
  • The hls and archive tests are updated.

Tests

• Rust and JS: a join under or over the ratio, growth without a joiner, no ratio never refreshes, deltas off gives one group per update, Encoder::snapshot(), timestamp reuse, and a compressed refresh window.
• Both property tests gain a restate step.
• moq-ffi: json_snapshot_refreshes_for_a_joiner, where an idle bound producer re-emits once a joiner crosses the ratio. It fails without the driver task.

Public API / wire impact

• Public API is breaking in moq-json, @moq/json, moq-mux, moq-ffi, moq-c and every binding. MIGRATE.md entries are added.
• Additive in @moq/net: Timestamp.isBefore, exact ordering across scales, which a refresh uses to restate at the newest timestamp written.
• No wire change. Setting refresh on a track also makes IETF advertise dynamic_groups.

Decisions (confirmed)

The maintainer confirmed these five, taking the recommended course; the alternatives stay listed.

1. Sync owners answer on their next edit. moq-mux timeline, moq-boy status and moq-stats have no runtime of their own, so they answer a refresh on their next edit or tick instead of right away. Chosen: keep it. Their cadence is a segment or a tick, and a task per owner adds lifecycle code for little gain. Alternative: give each owner a refresh task that answers right away.
2. moq-stats uses reset(), not Encoder::snapshot(). The stats tracks share a sequence allocator, so they cannot use snapshot::Producer. A wanted group past the largest makes that tick's frame a snapshot, so a refresh costs one frame instead of a restatement plus a delta. Chosen: encoder.reset(). Alternative: restate with Encoder::snapshot() in a new group, then send the tick's delta.
3. moq-c hardcodes a ratio of 8. C callers cannot choose the ratio yet. Chosen: keep 8, and add a refresh field only when a caller asks. Alternative: add a refresh field to moq_json_snapshot_config now.
4. Go uses Deltas *bool. A nil pointer means on, which keeps the existing pointer-default pattern. Chosen: *bool, so the name matches the other bindings. Alternative: a zero-value DisableDeltas bool.
5. A refused update never becomes the snapshot baseline (5465196). The snapshot encoder stages each frame's value and applies it on commit, as the window encoder already did, so Encoder::value, Encoder::snapshot() and the next modify/mutate start from the last value actually written. Before, a rejected update stayed as the baseline: a refresh restated a value that never reached the wire, and the next edit carried the rejected change along. Accepted by the maintainer as a behavior change; the moq-json and @moq/json MIGRATE.md entries say to retry a refused edit yourself.

This is a breaking API change across many packages, so it was held for the maintainer's confirmation.

Follow-ups

• A shared moq-net helper for "wanted passed the largest group", once refresh/video lands. This PR keeps it private in moq-json to avoid churn while the two land in parallel.
• A restatement carries the last update's timestamp. A joiner with a tight latency budget on a timed track may judge it stale. Worth checking with the end-to-end relay test the epic lists.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

[kixelated]

Checks run locally on db915ce:

• just check passed: lint, compile and tests for the changed packages, including moq-json, moq-mux, moq-ffi, moq-c, moq-stats, moq-hls, moq-archive and moq-room; JS json, publish, room, hang and watch; and the py, go and dart bindings.
• just test interop --all: 68 pairs passed. The only failures were the six * -> gst pairs, because the GStreamer moqsrc plugin did not load on this machine. Those failures are environmental, and the PR does not touch moq-gst.
• I confirmed that the new moq-ffi test json_snapshot_refreshes_for_a_joiner times out with the refresh task disabled. With the task enabled, it passed 10 repeated runs.

This is a draft until the open decisions in the description are settled.

(Written by Claude Opus 5.5)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: f7273eef-66cb-40d7-bf2d-adc8f28bafd0

📥 Commits

Reviewing files that changed from the base of the PR and between a0d6028 and 31e220a.

📒 Files selected for processing: 35

• dart/moq/MIGRATE.md
• go/wrapper/MIGRATE.md
• js/json/MIGRATE.md
• js/json/README.md
• js/json/src/snapshot/codec.test.ts
• js/json/src/snapshot/encoder.ts
• js/json/src/snapshot/producer.ts
• js/json/src/snapshot/snapshot.test.ts
• js/json/src/window/window.test.ts
• js/net/src/track.ts
• js/watch/src/broadcast.test.ts
• kt/moq/MIGRATE.md
• kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt
• py/moq-rs/MIGRATE.md
• py/moq-rs/moq/json.py
• quest/m1/compress/migrate.md
• quest/m1/refresh/README.md
• quest/m1/refresh/json.md
• rs/moq-c/MIGRATE.md
• rs/moq-c/src/api.rs
• rs/moq-c/src/publish.rs
• rs/moq-c/src/test.rs
• rs/moq-cli/src/report.rs
• rs/moq-ffi/MIGRATE.md
• rs/moq-ffi/src/test.rs
• rs/moq-hls/src/export/mod.rs
• rs/moq-json/MIGRATE.md
• rs/moq-json/src/snapshot/consumer.rs
• rs/moq-json/src/snapshot/encoder.rs
• rs/moq-json/src/snapshot/mod.rs
• rs/moq-json/src/snapshot/producer.rs
• rs/moq-json/src/window/mod.rs
• rs/moq-mux/MIGRATE.md
• rs/moq-room/src/chat.rs
• swift/MIGRATE.md

💤 Files with no reviewable changes: 3

• quest/m1/refresh/json.md
• quest/m1/compress/migrate.md
• quest/m1/refresh/README.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 0 remain after this review.

Walkthrough

The change replaces numeric snapshot-delta and window-operation ratios with boolean deltas and ops settings. Encoders use frame and byte caps for group limits and support explicit restatement. Producers refresh groups when joiner demand exceeds the latest written group and a track refresh ratio is configured. The update adds exact cross-scale timestamp comparison and refresh wiring in Rust integrations. Bindings, call sites, migration guidance, documentation, and tests are updated across several languages.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 31e22

Rejected snapshot updates no longer poison later refreshes. No established issue remains that should block merging after normal checks.

Pre-merge checks: 5

Check name	Status	Explanation
Description check		The description directly explains the joiner-demand group refresh change, API replacements, producer refresh behavior, tests, compatibility impact, and follow-ups.
Title check		The title clearly and concisely identifies the main change: snapshot and window groups now roll on joiner demand.
Docstring Coverage		Docstring coverage is 82.33% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 215 functions across 53 files. (12 skipped:…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 82.33% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 215 functions across 53 files. (12 skipped: 12 unsupported.)

✨ Finishing Touches: 💡 1

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

✨ Simplify code

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.99.0)

Clippy execution timed out

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-22T17:11:41.840075Z	f66f48e	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9582c85f65

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 407a7177f9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kixelated]

Merging.

• The maintainer confirmed all four decisions (sync owners answer on their next edit, moq-stats uses reset(), moq-c hardcodes a ratio of 8, Go uses Deltas *bool). The description now records them as confirmed.
• 263f0c8171 merges main after moq-dev/moq#5677 (consumers return timestamps). It keeps both sides' ## Unreleased entries in every MIGRATE.md and keeps the finished json quest deleted. Some tests still used the removed ratio API, so they were ported to the deltas switch: three moq-json snapshot tests from feat(data)!: data consumers return each value's timestamp #5677, this PR's moq-ffi refreshed-join test (now reads .value), and two Kotlin smoke tests.
• 407a7177f9 merges main after moq-dev/moq#6048. It drops both finished children from the refresh epic's Required.
• 4dc084c05b fixes Codex's P2 at the source. A refresh restates at the newest timestamp written in the JS and Rust snapshot and window producers, so a new group can no longer rewind past its predecessor's start. A failed JS refresh now aborts the track instead of swallowing the error. This adds Timestamp.isBefore to @moq/net. There are regression tests in both languages.
• Checks: workspace cargo check (lib, tests, examples, bins), the moq-json, moq-stats, moq-c, moq-ffi json, and moq-mux json tests, just py check, just kt check, just go check, just dart check (the Dart bindings regenerate unchanged), js/json and js/net bun test, tsc, biome, rustfmt, and quest check.
• Review gate: Codex gave a thumbs-up on the final head 4dc084c05b.

Unrelated to this PR: cargo check --benches fails on main in rs/moq-net/benches/session.rs (a format argument is never used). That bench last changed in moq-dev/moq#6028.

(Written by Claude Opus 5.5)

[kixelated]

Merging.

• fc2f267e1b merges main after moq-dev/moq#6030 (lite carries refresh demand through relays). The only conflict was the refresh epic's Required: main dropped the finished lite child and this PR drops the json child, so the section is now gone. The README is sized [M] for the work it still owns, the two-relay end-to-end test and the doc/concept section. No MIGRATE.md conflicted, and every ## Unreleased entry from both sides is kept.
• Checks on fc2f267e1b: just check passed: nextest ran 4252 Rust tests and all passed, plus the JS, py, kt, go, dart, cpp, drafts, quest and flake checks. One step, bench/relay.test.py, timed out at 15s while the machine was under load. It passes 5/5 when run alone. Neither this PR nor the merge touches bench/. Interop was not rerun because the merge brings in no moq-ffi or binding changes. The last full interop run was on db915ceeb5.
• Review gate: Codex gave a thumbs-up on 4dc084c05b. Since then the only changes are cf88206522, a struct-literal tidy in one test, and the clean main merge. Both review threads are resolved.

(Written by Claude Opus 5.5)

[kixelated]

Re-merging after the queue removed a0d6028bfa for a conflict.

• 13883d53b1 merges main after moq-dev/moq#6139, moq-dev/moq#6146, and moq-dev/moq#6157. The only conflicts were the ## Unreleased sections of the dart, go/wrapper, kt, py, moq-c, moq-ffi, and swift MIGRATE.md files; both entries are kept, this PR's first.
• c3c9cd3ae9 fixes the open Codex finding: the js/json README now says a refresh restates at the newest timestamp written, matching Producer.
• Checks: just check (4361 + 516 + 225 Rust tests, JS, Python, lints; nix flake check skipped for a local user-namespace limit), just test interop --all, and quest check passed. No new review requested, since the change since Codex's last review is a merge plus a one-line docs fix for its own finding.

(Written by Claude Opus 5.5)

[kixelated]

Re-merging after the queue removed c3c9cd3ae9 for a conflict.

• b58198ef7c merges main after moq-dev/moq#6187, moq-dev/moq#6193, moq-dev/moq#6145, and moq-dev/moq#6151. All four resolutions are mechanical:
  • rs/moq-json/src/snapshot/mod.rs: main deleted deltas_share_one_group, late_joiner_reconstructs_from_deltas, and their compressed twins, which this PR had moved to cfg(true). Kept main's deletions and this PR's replacement tests (deltas_never_roll_without_a_joiner, a_compressed_refresh_opens_a_fresh_window).
  • js/json/src/snapshot/encoder.ts: this PR dropped DEFAULT_DELTA_RATIO and main inlined DEFAULT_MAX_GROUP_BYTES. Nothing uses either one now, so both are gone.
  • py/moq-rs/moq/json.py: kept main's subscribe.TrackConsumer annotation and this PR's deltas comment.
  • js/watch/src/broadcast.test.ts (no textual conflict): moq-dev/moq#6151 added two deltaRatio: 0 producers. They are now deltas: false, following this PR's migration note.
• just check: js, rs, py, kt, swift, go, dart, cpp, obs_compile, and quest pass. Only check flake failed, because the local sandbox can't run the github-runner VM image build (unshare is not permitted there). That failure is unrelated to this PR, and CI covers it.

Re-enabling auto-merge on b58198ef7c.

(Written by Claude Opus 5.5)

[kixelated]

Merged origin/main into this branch (f66f48e). Conflicts were the ## Unreleased sections in eight MIGRATE.md files (both entries kept, this PR's first) and an import in js/json/src/window/window.test.ts. The finished quest/m1/refresh/json.md stays deleted, and its links in quest/m1/compress/migrate.md are dropped. After #6274 window consumers return Timed events, so the window refresh test now reads .value and checks that the restated header is at 30 ms.

Accepted behavior change from 5465196: a snapshot modify/mutate starts from the last value actually written, so a refused update no longer becomes the baseline. The Rust and JS MIGRATE entries cover it, and it is recorded in the PR body as decision 5.

Checks: clippy -D warnings and tests for moq-json, moq-room, moq-mux, moq-archive, moq-boy, moq-c, moq-cli, moq-ffi, moq-hls and moq-stats; cargo fmt --check; bun run check for js/json, room, hang, net, publish and watch; bun test for js/json, room and hang; biome; quest check.

@codex review

(Written by Claude Opus 5.5)

[kixelated]

Codex reacted to the last request but has not posted a review of f66f48e in over an hour, so here is another request.

@codex review

(Written by Claude Opus 5.5)

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: f66f48eb7c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kixelated]

Merged main (31e220a). Only the ## Unreleased sections of eight MIGRATE.md files conflicted; both sides' entries are kept. cargo check --workspace, clippy and tests for moq-json/moq-room/moq-mux, and bun run check/bun test for js/json, js/room and js/hang pass.

(Written by Claude Opus 5.5)