From 102ef455c7dd5dd6397bf29c126528ebdc2576d5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 16:43:06 -0800 Subject: [PATCH] =?UTF-8?q?quest:=20plan=20the=20main=20=E2=86=92=20releas?= =?UTF-8?q?e=20audit's=20gaps,=20and=20fix=20its=20small=20findings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plans the 2026-11-20 release audit's unowned findings: a shared Rust/JS range table the cut waits on, explicit route forwarding states after the cut, the archive guide correction, the moq.pro attach recheck, and extra candidate checks in the cut. Fixes the small findings: Swift validates a track's refresh interval before UniFFI aborts on it, @moq/json's mutate keeps a published null, and the cut PR runs the full moq-transport matrix and released wire compatibility. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/interop.yml | 15 ++++---- js/json/src/snapshot/producer.ts | 6 ++-- js/json/src/snapshot/snapshot.test.ts | 21 +++++++++++ quest/m2/auth-attach-downstream.md | 23 +++++++++--- quest/m2/time-addressing/range-table.md | 47 +++++++++++++++++++++++++ quest/m3/release/cut.md | 20 +++++++++++ quest/m3/release/migrate-audit.md | 13 +++++++ quest/m4/route-forward-states.md | 44 +++++++++++++++++++++++ swift/Sources/Moq/Durations.swift | 1 + swift/Tests/MoqTests/SmokeTests.swift | 3 ++ 10 files changed, 179 insertions(+), 14 deletions(-) create mode 100644 quest/m2/time-addressing/range-table.md create mode 100644 quest/m4/route-forward-states.md diff --git a/.github/workflows/interop.yml b/.github/workflows/interop.yml index 88ce27d5350..be43c0e529a 100644 --- a/.github/workflows/interop.yml +++ b/.github/workflows/interop.yml @@ -124,9 +124,9 @@ jobs: # A release PR fails, rather than skips, a browser the lite-07 cut waits on to prove its route key. CI_STRICT: ${{ github.event_name == 'pull_request' && '1' || '' }} - # The same matrix with every client pinned to one moq-transport draft per pass. A release - # PR runs the oldest and newest even draft between Rust and native JS; nightly and manual - # runs cover every even draft and every client. + # The same matrix with every client pinned to one moq-transport draft per pass. A backport + # PR into release runs the oldest and newest even draft between Rust and native JS; the cut + # PR (head `main`), nightly, and manual runs cover every even draft and every client. - name: Interop (moq-transport) id: interop-ietf if: ${{ !cancelled() && steps.setup.outcome == 'success' }} @@ -135,15 +135,16 @@ jobs: nix develop --command just test interop "${args[@]}" shell: bash -leo pipefail {0} env: - INTEROP_ARGS: ${{ github.event_name == 'pull_request' && '--publishers rust --subscribers rust,js-native-node,js-native-bun --versions moq-transport-18,moq-transport-22' || '--all --versions ietf' }} + INTEROP_ARGS: ${{ github.event_name == 'pull_request' && github.head_ref != 'main' && '--publishers rust --subscribers rust,js-native-node,js-native-bun --versions moq-transport-18,moq-transport-22' || '--all --versions ietf' }} HARNESS_RUNS: ${{ runner.temp }}/moq-test-runs HARNESS_RESULTS: ${{ runner.temp }}/moq-test-runs/results.jsonl - # Registry installs and the release matrix run only on main, nightly or - # on demand: a break only needs catching before the next release. + # Registry installs and the release matrix run on main (nightly or on demand) + # and on the cut PR, whose head is `main`: the last chance to catch a break + # against the published versions before it ships. Backports skip it. - name: Released wire compatibility id: wire-compat - if: ${{ !cancelled() && steps.setup.outcome == 'success' && github.ref == 'refs/heads/main' && github.event_name != 'pull_request' }} + if: ${{ !cancelled() && steps.setup.outcome == 'success' && ((github.ref == 'refs/heads/main' && github.event_name != 'pull_request') || (github.event_name == 'pull_request' && github.head_ref == 'main')) }} run: nix develop --command just test wire-compat shell: bash -leo pipefail {0} env: diff --git a/js/json/src/snapshot/producer.ts b/js/json/src/snapshot/producer.ts index 69bb9d826a8..3062685bd19 100644 --- a/js/json/src/snapshot/producer.ts +++ b/js/json/src/snapshot/producer.ts @@ -197,8 +197,10 @@ export class Producer { */ mutate(fn: (value: T) => void, at: Time.Timestamp): void { // Start from the last-published value, falling back to the configured initial value. We - // don't invent an empty object: mutating with nothing to start from is a usage error. - const base = this.#encoder.value ?? this.#initial; + // don't invent an empty object: mutating with nothing to start from is a usage error. A + // published JSON null is a value, so only `undefined` means nothing was published. + const published = this.#encoder.value; + const base = published !== undefined ? published : this.#initial; if (base === undefined) { throw new Error("mutate() requires a prior update() or `initial` in the config"); } diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 02b5dba6b82..e6909e73c44 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -376,6 +376,27 @@ test("mutate starts from the configured initial value", async () => { expect((await consumer.next())?.value).toEqual({ a: 1 }); }); +// JSON null is a published value: mutate must hand it over rather than the stale `initial`, and +// must not refuse it as if nothing had been published. +test("mutate starts from a published null", async () => { + for (const initial of [undefined, { a: 1 }]) { + const track = new Track.Producer("test"); + const producer = new Producer({ track, initial }); + producer.update(null, key()); + + let seen: Value | null | undefined; + producer.mutate((v) => { + seen = v; + }, key()); + expect(seen).toBeNull(); + producer.finish(); + const consumer = new Consumer({ track }); + const states: (Value | null)[] = []; + for (let state = await consumer.latest(); state; state = await consumer.latest()) states.push(state.value); + expect(states).toEqual([null]); + } +}); + // A rejected edit never reached the wire, so the next owner starts from the last value that did. // Carrying the rejected edit forward would fail every later publish the same way. (Mirrors the Rust // `a_rejected_edit_leaves_modify_at_the_last_written_value`.) diff --git a/quest/m2/auth-attach-downstream.md b/quest/m2/auth-attach-downstream.md index e47f35773be..53876c40852 100644 --- a/quest/m2/auth-attach-downstream.md +++ b/quest/m2/auth-attach-downstream.md @@ -26,10 +26,23 @@ Until moq.pro reads `token`, it must not meet a relay with this change: marked temporary migration in `rs/moq-auth/src/serve.rs`), but moq.pro has no such reader for the new shape. +Rechecked 2026-11-20 by the main → release audit at moq.pro `828766e510`: +still unfixed. `rs/edge/src/auth/mod.rs` reads only `query_jwt(request.query)` +(`:1064`, `:1316` on `End`, `:1339` on `Attach` and `Revalidate`) and never +`request.token`, and no moq.pro quest owns the change. The planning PR lists +it as a follow-up for moq.pro's own `/quest-plan`, required by moq.pro's +[cut pin adoption](https://github.com/moq-dev/moq.pro/blob/main/quest/m0/adopt-cut-pin.md), +so moq.pro never runs a relay with this change before it reads `token`. Its +test presents distinct credentials through attach, revalidate, and end +against both the last released relay and the candidate. + ## Waiting -- Maintainer: check the moq.pro and Kixel auth handlers read `attach` from - `token`, and fix one that does not before it meets a relay with this change. - An agent cannot read those private repositories from here. Done when both - handlers' tests present an attach whose `query` holds an expired `jwt` and - whose `token` holds a valid one. +- moq-dev/moq.pro: the edge auth handler reads an attached credential from + `token` on `attach`, `revalidate`, and `end`. Check with + `grep -n "request.token" rs/edge/src/auth/mod.rs` on moq.pro `main`, and a + test whose attach carries an expired `jwt` in `query` and a valid `token`. +- kixel-ai/kixel.ai: `Mesh.admit` (`src/mesh.ts:557`, rechecked 2026-11-20) + reads a `credential` query parameter on every event, `attach` included, and + its client attaches nothing yet. Before a Kixel client attaches, it reads + `token` there too; check the same way. diff --git a/quest/m2/time-addressing/range-table.md b/quest/m2/time-addressing/range-table.md new file mode 100644 index 00000000000..6e8256f1240 --- /dev/null +++ b/quest/m2/time-addressing/range-table.md @@ -0,0 +1,47 @@ +# [M] Rust and JS deliver the same groups from one range table + +## Goal + +One shared table of range cases pins which groups a subscription delivers, and both Rust and +`@moq/net` pass it. Each case gives a track's groups at the origin, what a copy holds +(complete, sparse, or partly evicted), a lite-07 range (a time start, a Position, or no anchor +with a Min Age, and a time end or none), and the exact group IDs delivered, plus whether the copy +must ask upstream. Every case runs direct from the origin, through a relay copy cold and warm, as +a late join, and across a route switch mid-read. The copy's answer always equals the origin's, +so the cut publishes lite-07 knowing the two implementations agree. + +## Plan + +Decided 2026-11-20 (maintainer, /quest-plan of the main → release audit): ✅ m2, so the cut +waits on it (rejected: m4 after the cut, since a divergence found then is a lite-07 behavior fix +after publication; dropping it for the per-language tests no relative anchors adds, which never +compare Rust with JS). + +The audit reproduced why per-language tests weren't enough: with latest group 9, the same +`relative: 2` through `time: 8` subscription returned `[7, 8]` from a complete JS copy and `[1, 2]` +from one holding `[1, 2, 9]`. [No relative anchors](/quest/m2/time-addressing/no-relative-anchors.md) +removes that anchor, but a live join by Min Age and a time start resolve against holdings the +same way, and nothing compares the two languages' answers. + +Recommended: + +- One JSON fixture read by a Rust test and a `bun:test` file, as + `rs/moq-json/tests/window-vectors.json` and `js/json/src/window/vectors.test.ts` already + share one. Expected outputs are group IDs, never timings. +- Seed it with the audit's sparse-copy case restated without the relative anchor, and the cases + no relative anchors names: a Min Age reaching past what a copy holds, an oldest reader and a + live reader on one relay, a time start between held groups linked by Previous Start (which a + copy may answer from cache) and one that isn't (which must ask). +- The relayed run uses the real copy path in each language, so a JS copy under a Rust origin + is covered the way `just test relay-fill` already covers fills. +- Drive time with the manual clocks both test suites already use. + +Public API: none. Wire: none; a divergence this finds is fixed under lite-07-wip before the cut. + +## Required + +- [No relative anchors](/quest/m2/time-addressing/no-relative-anchors.md) - the range shapes this table pins + +## Related + +- [A relay fetches a group's missing head](/quest/m1/missing-head-asks-upstream.md) - a partial group a copy holds is another case for the table diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index 9e1aeced74d..4bf0548d3cd 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -249,6 +249,26 @@ observe withdrawal. All four paths passed on lite-06 with 0.17.17 and audited ma Re-run the existing cut checks on the resolved merge and version bump. After publication, check that Release remeasure opened or updated its pin PR, as RELEASE.md describes. +From the 2026-11-20 main → release audit (main `9828a20cab` against release `381b802d9b`: 4,241 +main-only and 307 release-only commits, 330 paths conflicted in a trial merge), for the +candidate: +- Keep the behavior of release-only fixes while resolving conflicts, not just their text, and + run a test of each on the candidate: stopped-stream receive credit (`b834502dfa`, qmux 0.5.4 + and `@moq/qmux` 0.3.5), a far-ahead group sequence costing a relay nothing extra + (`0c9ffdd7a7`, backport of [moq-dev/moq#9044](https://github.com/moq-dev/moq/pull/9044)), a + relay restarting under its old hop ID stranding nothing (`4a9005c3c5`), a 64-bit Hop ID read + as unknown in Rust and JS (`f48b7a066e`, `a480bba27c`), and a restarted publisher winning over + its lingering session (`5511441a02`). List the rest with + `git log --no-merges origin/main..origin/release`. +- Widen the two-relay smoke above: keep a reader attached through each roll, in both directions + (last published relay to candidate and back), and check it keeps receiving the same frames + after the roll and after a withdrawal and return. +- The cut PR (head `main`) now runs the full moq-transport matrix and Released wire + compatibility in its Release gate, which a backport PR still skips (planned by the audit's + PR). Read both results on the cut PR rather than repeating them by hand. +- Attach each result to the candidate SHA in the cut PR body, so a later push visibly + invalidates it. + ## Required - [Breaking release readiness](/quest/m2/README.md) - code, protocol and package proofs diff --git a/quest/m3/release/migrate-audit.md b/quest/m3/release/migrate-audit.md index 69b868ab649..1f0025ba3ed 100644 --- a/quest/m3/release/migrate-audit.md +++ b/quest/m3/release/migrate-audit.md @@ -110,6 +110,19 @@ m1 quest on 2026-10-22. - moq-gst: the request pad's `encoder` property, shipped in `moq-gst-v0.4.24`, was removed with no entry, so a `gst-launch` line setting it now fails at runtime. + - moq-archive (added 2026-11-20, from the main → release audit): + `rs/moq-archive/MIGRATE.md`'s "Recording format version 4 drops the + datagram form" and "Recording format version 3 replaces version 1" are + wrong since [moq-dev/moq#8932](https://github.com/moq-dev/moq/pull/8932): + `VERSION` is 2, the only version written or read, and `Error::Form` is + gone. Replace both with #8932's Impact text: format version 2 replaces + version 1; start a new recording prefix; main builds' versions 2 to 4 are + unsupported; `Info::version` and `Error::Form` are removed and `Info` no + longer implements `Serialize`/`Deserialize` (use `Info::encode` and + `Info::decode`); keep a release build's reader for retained version 1 + archives. Keep the `i8` priority and optional timescale notes, and check + the "Objects are keyed by timeline segment" entry's `Key::Segments`, + `Store::get_segments`, and `Error::Span`, none of which exist on `main`. ## Required diff --git a/quest/m4/route-forward-states.md b/quest/m4/route-forward-states.md new file mode 100644 index 00000000000..f381eda2d59 --- /dev/null +++ b/quest/m4/route-forward-states.md @@ -0,0 +1,44 @@ +# [L] A route's forwarding and advertising decide reachability in one place + +## Goal + +A lite-07 node decides once whether a broadcast is ready to forward, waiting for something +named, or unavailable, and both what it advertises and where it forwards a request follow that +one decision. A request that has to wait names what it waits for, and that event wakes it, so +no reader is refused for a broadcast the node still advertises, or left waiting for something +that will never arrive. The failover model covers a claim missing for a while and a live route +coming back, and an already attached reader resumes delivery in both. + +## Plan + +Decided 2026-11-20 (maintainer, /quest-plan of the main → release audit): ✅ m4, after the cut +(rejected: m2, which puts an L routing refactor right before the cut; dropping it and fixing +races one replay at a time). [moq-dev/moq#9231](https://github.com/moq-dev/moq/pull/9231) +fixed the race the audit found, and +[mesh replay violations](/quest/m0/nightly/mesh-replay-violations.md) owns the replay's open +strands. If that quest traces one to forwarding, move this quest up. + +The shape today: `Node::forward` (`rs/moq-net/src/route/node.rs`) returns +`Option>`, where the outer `None` waits and `Some(None)` refuses, and announce +discovery judges reachability from other facts. #9231's stranded reader came from that gap: a +route to the claimant existed before the next hop held its claim, `forward` refused for good, +and the reader had no reason to retry once the claim landed. + +Recommended: + +- One enum, such as `Ready(Via)`, `Waiting(Reason)`, and `Unavailable(Reason)`, computed by one + function that both the advertised availability and `poll_forward` read. A `Waiting` reason + names the event that wakes it, so `Unavailable` is terminal only when nothing advertised can + change it. +- Extend `rs/moq-net/verify/failover/FailoverChain.tla` with a claim that disappears and comes + back while its route stays up, and a route that leaves and returns live. Check that an attached + reader resumes in both (`/verify-failover`). +- Keep [route wakes](/quest/m4/route-wakes.md)'s write-once and targeted-wake goals in view: the + waiting reason is what lets a change wake only the requests it affects. + +Public API: none expected. Wire: none. + +## Related + +- [Route wakes](/quest/m4/route-wakes.md) - which fronts a route change wakes +- [A lite-07 claim is shown no broader than its grants](/quest/m2/lite07-claim-reach-routes.md) - an advertised claim a request is then refused on diff --git a/swift/Sources/Moq/Durations.swift b/swift/Sources/Moq/Durations.swift index 53606198fa9..a71d400b511 100644 --- a/swift/Sources/Moq/Durations.swift +++ b/swift/Sources/Moq/Durations.swift @@ -26,6 +26,7 @@ func checkSubscription(_ subscription: Subscription?) throws { func checkTrackInfo(_ info: TrackInfo?) throws { try checkDuration(info?.maxAge, "maxAge") + try checkDuration(info?.refresh.interval, "refresh.interval") } func checkFetch(_ options: FetchGroupOptions?) throws { diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index 17ed8b9c189..750f2ba7768 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -195,6 +195,9 @@ final class SmokeTests: XCTestCase { var info = try broadcast.publishTrack(name: "info").consume().info() info.maxAge = bad assertConfig({ _ = try broadcast.publishTrack(name: "bad", info: info) }, "max age \(bad)") + info.maxAge = 0 + info.refresh = TrackRefresh(interval: bad) + assertConfig({ _ = try broadcast.publishTrack(name: "bad", info: info) }, "refresh interval \(bad)") var subscription = Subscription.default subscription.delay.max = bad