[kixelated]

Closes #699. Completes quest/m1/quic/scheduler.md, which this PR deletes.

What

One QUIC connection now carries the MoQ scheduling hierarchy instead of packing it into a scalar:

• moq-quic replaces quinn's single pending-stream heap with send groups (streams/schedule.rs).
  • Streams outside every group go first, in quinn's order. That covers control and HTTP/3 streams.
  • Groups sit in a scheduling domain; there is one default domain. Within a domain, the highest backlogged priority is served strictly.
  • Groups at equal priority share bytes by deficit round robin. They are charged in wire bytes, with a 1200 byte quantum.
  • Domains share bytes the same way, so opening more groups earns a domain nothing.
  • A stream's priority widens to i64: the priority within the stream's send group, or session-wide when ungrouped.
  • Debt carries over when a group goes idle; unused credit does not. A blocked stream does not hold a turn.
  • Retransmits re-queue through the same schedule.
• moq-tokio / moq-uring drivers wrap a group in a shared SendGroup handle that closes on drop. Their streams gain set_group.
• moq-net transport traits gain send groups. The lite and IETF publishers open one group per subscription at the subscriber priority, and one per standalone FETCH; a joining FETCH shares its subscription's group.
  • Group streams join it ordered by sequence in the subscription's group order, and a group's first stream goes ahead of the rest of that group.
  • SUBSCRIBE_UPDATE moves the group once rather than reranking every stream.
  • Transports without groups (browsers, iroh, qmux, ffi and wasm adapters) keep the session-wide PriorityQueue exactly as before.

Results

cargo bench -p moq-net --bench schedule compares the groups against the PriorityQueue and two scalar packings on a congested link. The shares, lag and queue work are deterministic. The timings were taken at load 60 to 150 on a shared host, so read them only as a relative comparison.

workload	scheduler	equal-priority Jain	queue work	notes
alice-bob (#699)	groups	1.000	0	audio p5 preempts; both p4 subscriptions get 7.5 KB/tick
	queue	0.500	584k reranks	the deeper backlog takes the whole p4 share
	scalar [p][seq]	0.500	0	sequences compete across subscriptions
	scalar [p]	0.644	0	shares by stream count, loses newest first (lag 698)
wrap (seq crosses 2^24)	groups	1.000	0
	queue	0.800	349k
	scalar [p][seq]	1.000	0	wrap inverts order: lag 1401 groups
sparse (ms-clock seqs)	groups	1.000	0
	scalar [p][seq]	0.814	0	lag 1451
crowd (64 subs, mixed cadence)	groups	1.000	0
	queue	0.341	244k
	scalar [p][seq]	0.202	0

The groups beat the queue on every workload: alice-bob took 8.5 ms against 186 ms, wrap 24 against 181 ms, sparse 61 against 376 ms, and crowd 12.7 ms against 76 ms. The crowd figures come from a re-run at load 23; the first run's crowd timing was taken at the load peak and was noise. The fanout sweep times one frame and one join, push and leave across subscriptions in {1, 16, 256, 4096} and in-flight streams per subscription in {1, 16, 256}. Each case stays between 20 and 700 ns with no slope against the table size. The benchmark is picked up by bench/run.sh in nightly.

Public API

Breaking, in every case:

• moq-net transport::poll:
  • Session::send_group(&mut self, i64) -> Option<…::Group> is required, not defaulted, like protocol.
  • SendStream::Group and SendStream::set_group(&Self::Group) are added.
  • SendStream::set_priority takes i64 instead of i32. It is the only stream ordering setter: the priority within the stream's send group, or session-wide when ungrouped.
  • New SendGroup trait (Clone, set_priority(i64)) and Ungrouped, the uninhabited group for flat transports.
  • Group and stream priorities are both i64, so neither side converts.
  • Boxable also requires Group: MaybeSend + MaybeSync.
• moq-quic:
  • Connection::send_groups() -> SendGroups<'_> with open, close, set_priority, priority, open_domain and close_domain. Group priorities are i64.
  • SendGroup and SendDomain are owned, non-Clone tokens tagged with their connection, so another connection panics on them.
  • SendStream::set_group(Option<&SendGroup>) is added, and SendStream::{set_priority, priority} use i64.
• moq-tokio:
  • quic::driver::SendGroup (set_priority/priority in i64), Connection::send_group(i64), and quic::web::Session::send_group(i64) are added.
  • Driver and web SendStream::set_group are added, and their set_priority and priority use i64.
  • transport::Session<S> now accepts only this crate's backends: native QUIC/WebTransport (real groups), iroh and qmux (flat). Its bound is a sealed trait pair, Grouped and GroupedSend, which is not public API (see decision 3), so a custom web_transport_trait::Session no longer fits. No crate in the repo wraps one. Custom transports implement moq-net's transport::poll traits directly, which already carry send groups, and Drop web-transport-trait deletes these adapters.
• moq-uring: mirrors moq-tokio. It adds quic::SendGroup, Connection::send_group, web::Session::send_group, and stream set_group and set_priority(i64). Its transport::Session<S> adapter uses the same sealed pair, so it accepts only the crate's native QUIC session.

Wire: none. Priorities stay local scheduling state; no message, field or draft changes. That is why just test interop --all was not run.

Decisions

1. ✅ Streams outside every group go strictly first. Control, HTTP/3 and WebTransport header streams can never queue behind media; everything ungrouped is ours.
2. ✅ Domains stay in moq-quic only until Scope track priority wires the broadcast domains. The drivers and moq-net open every group in the default domain.
3. ✅ One ordering setter, no public extension traits (changed in review).
   • set_priority(i64) is the single name everywhere: the moq-net trait, both drivers and the adapters. It means the priority within the stream's send group, or session-wide when ungrouped. set_order is gone.
   • Grouped and GroupedSend are not public API. pub(crate) was tried and is refused with E0446: the public adapters' poll::SendStream impl says type Group = S::Group, which projects through GroupedSend, and an associated type may not leak a crate-private trait. So each pair is pub inside a private module (moq_tokio::transport::grouped, moq_uring::transport::adapter) and never re-exported. Other crates can neither name nor implement them, which is stronger than #[doc(hidden)], and nothing outside either crate needs them.
4. ✅ In-group order is 2 * seq (negated for ascending), plus 1 for a stream that starts at object 0. This keeps the joining FETCH prefix ahead of the live rest of its group.
5. ✅ PriorityQueue stays as the flat fallback for browsers, iroh, qmux, ffi and wasm.
6. ✅ One PR. moq-quic plus the drivers has no consumer without the moq-net half.

Follow-ups

• Schedule datagrams by subscription priority: add a datagram queue to each send group, charged against the group's credit.
• Scope track priority: open a SendDomain per broadcast scope.
• qmux on moq-quic: run streams/saturated.rs through its record writer once it adopts the scheduler.
• Drop web-transport-trait, added in this PR: every backend implements moq-net's transport::poll traits, and the generic web_transport_trait adapters with the sealed Grouped/GroupedSend pair are deleted.
• Re-run the schedule bench on an idle host for absolute timings, since the shared host never got below load 23.

Checks

• just check origin/main on the merged head is green: clippy, docs, the moq-net no-default-features build, and 7369 workspace tests. cargo clippy --all-targets --all-features -D warnings covers the schedule bench.
• New tests:
  • moq-quic schedule and saturated: byte fairness, preemption, per-group order, priority updates, wrap and sparse sequences, blocked streams, retransmits not starved, domains, reset cleanup, leaving a group.
  • lite and IETF grouped_streams_rank_within_their_subscription.
  • moq-tokio send_defers_a_group_across_an_inflight_write.
  • moq-quic send_group_from_another_connection and send_domain_from_another_connection.
  • moq-quic reliable_reset_sends_its_prefix_then_frees_its_group and stop_sending_drops_a_reliable_prefix_from_the_schedule: a RESET_STREAM_AT stream (feat(quic)!: reliable reset from a send-stream checkpoint #5690) stays in its group only for its Reliable Size prefix.

🤖 Generated with Claude Code

(Written by Opus 5.5)

[kixelated]

Status: draft, ready for maintainer review once #5664 lands.

• Landed:
  • moq-quic send groups (strict by priority, byte-fair DRR at equal priority, and a domain tier).
  • Shared SendGroup handles in the moq-tokio and moq-uring drivers.
  • moq-net transport send groups, with one group per subscription and standalone FETCH in the lite and IETF publishers.
  • The PriorityQueue kept as the fallback on flat transports.
• Checks: just check against the merged base is green (7282 workspace tests plus per-crate suites, clippy, docs, model-only build). Interop was not run, because nothing changes on the wire.
• Bench: on equal-priority subscriptions the groups score Jain 1.000, against 0.34 to 0.80 for the queue and 0.20 to 0.81 for the scalar packings. The queue does 244k to 584k reranks per run; the groups do none.
• Decisions: six are in the description. My recommendations: keep ungrouped streams first, keep domains private until track-priority-scope, keep the Grouped/GroupedSend names, accept the one-bit start tie-break, keep the queue fallback, and land as one PR.

(Written by Opus 5.5)

[kixelated]

Iterated on review:

• Decisions 1, 2, 4, 5 and 6 are recorded as settled in the description.
• Decision 3: set_order is gone. set_priority(i64) is the one ordering setter everywhere, documented as the priority within the stream's send group, or session-wide when ungrouped.
• Grouped and GroupedSend are out of the public API. pub(crate) is refused with E0446, because the public adapters' type Group = S::Group projects through GroupedSend. Each pair is now pub inside a private module and never re-exported, so other crates can neither name nor implement them.
• Merged main after feat(quic)!: run moq-tokio and moq-uring on moq-quic #5664 squashed. git diff origin/main...HEAD shows only this PR's changes, and just check origin/main is green.

(Written by Opus 5.5)

[kixelated]

TS validation failure on 674746b, checked against main:

• just test ts --full ("source's clock runs +22135.1 ppm off") is the start-up drift flake flaky: just test ts --full exits on the release clock's first rate estimates (~1 in 5 local runs) #5564, which fix(moq-mux): judge a source's clock on slack the floors saw #5714 fixes.
• just test ts (video-content, "decoded pictures are not an intact suffix of the source"): the CI step does not print exporter logs, so I reproduced it locally. Rates at load at or below 24:

head	runs	failures
this branch	19	1
main (eb73457, then d29e6ee)	18	0

The last 10 of each ran interleaved, branch then main, so both saw the same load. The single local failure has the #5565 signature exactly: current group evicted ... track="0.avc3" group=1 error=Hang(Moq(Stream(Old))), 6 ms after the max_delay: 0 video subscribe. That reset comes from the publisher's delivery budget once the next group exists, not from send order, so the in-group ordering here cannot cause it. One failure in 19 is within the flake's rate and not distinguishable from main's 0 in 18. #5713 fixes it at the exporter.

(Written by Opus 5.5)

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 76296c742a

ℹ️ 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]

@codex review

(Written by Opus 5.5)

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: 1031168d2c

ℹ️ 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]

@codex review

(Written by Opus 5.5)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2c16b117fc

ℹ️ 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]

@codex review

(Written by Opus 5.5)

[kixelated]

@codex review

(Written by Opus 5.5)

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: ddeb5232ff

ℹ️ 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]

Heads-up: #5781 (moq-quic characterization tests) adds exact-order scheduling goldens in rs/moq-quic/src/tests/characterize/schedule.rs that pin today's order. When this PR rebases onto it, update each golden in this diff so the ordering changes are reviewable, and consider adding a golden for a priority change partway through a stream.

(Written by Claude Opus 5.5)

[kixelated]

Ready to land at ddeb5232ff.

• moq-quic gets a hierarchical send scheduler. Ungrouped streams go first, then send groups strict by priority, with byte DRR at equal priority, inside DRR-shared domains. Group and stream priorities are both i64.
• moq-tokio and moq-uring hand each subscription its own send group through moq-net's transport::poll traits. The web_transport_trait adapters are sealed to this crate's backends, and Drop web-transport-trait removes that layer.
• Composes with reliable reset (feat(quic)!: reliable reset from a send-stream checkpoint #5690): a RESET_STREAM_AT stream stays in its group only for its Reliable Size prefix, and tests cover both the reset and STOP_SENDING paths.
• doc/concept/moq-lite.md scopes the equal-priority split to native stream data. The datagram-priority quest owns extending it to datagrams.

Checks:

• CI is green, and Codex found no issues on the head.
• The platform dispatch (run 38983031021) failed only on two known flakes: macOS moq-tokio quic::driver::tests::zero_rtt, and Windows moq-relay::drills relay_killed_mid_group_aborts_then_resumes.
• Fail-fast stopped Windows after hang, moq-auth and moq-relay. The merge queue reruns the full macOS and Windows suites.

(Written by Opus 5.5)

[kixelated]

moq-quic now has Criterion benchmarks (#5812, landing shortly): stream send/priority, receive/reset/stop, endpoint routing, and wire codec cases, each swept over two axes. Once it merges, please rebase and run just bench <the #5812 merge commit> on an idle machine pinned to one core type, and post the moq-quic deltas here. On a shared or mixed-core host, identical builds swing about 5% on small cases and 20-130% on large-working-set cases (see #5812's noise table), so only changes well outside that band count.

(Written by Claude Opus 5.5)