moq-net + js/net: pre-merge API hardening for moq-lite-05

[kixelated]

Tightens the moq-net public surface before dev lands on main and its shapes become semver-load-bearing. Targets dev: renames, removals, and signature changes to pub items in moq-net, js/net, and moq-ffi break existing contracts.

Came out of an extensive review of the moq-net dev delta ahead of the dev→main merge (the "actually start using moq-lite-05" milestone). The goal was the API shape: catch every change that is a one-line fix now but a breaking change forever once it ships on main.

Future-proofing (avoid an immediate semver bump after merge)

• #[non_exhaustive] on Subscription, group::Fetch, and the Announced enum (all will gain fields/variants).
• Move Subscription under track:: (track::Subscription); it only appears in track signatures.
• Rename the last flat Bandwidth{Producer,Consumer} into a bandwidth::{Producer,Consumer} role module, matching every other Producer/Consumer pair.
• Rename the kio::Pending payload futures to a consistent gerund scheme: track::{Subscribe→Subscribing, Fetch→Fetching, InfoQuery→Querying}, origin::Requested→Requesting.
• Turn the announce update tuple (PathOwned, Announced) into a named #[non_exhaustive] struct announce::Update { path, event }.
• Re-export web_transport_trait (it bounds the Client/Server entry points but was unnameable).

Misuse resistance / correctness

• read_frame / poll_read_frame (group + track) now return the full frame::Frame { timestamp, payload } instead of bare Bytes, so the mandatory per-frame timestamp is no longer silently dropped.
• Remove the inherent Timestamp::max that panicked on mixed scales and shadowed the total Ord::max.
• De-panic track::Producer::subscribe after abort(); Subscriber::update / Subscribing::update return Result instead of panicking on a closed track.
• Session close state is shared across clones: first close wins, transport closes on last-clone drop (was: any clone's drop killed the shared connection).
• server::Request rejects the handshake on drop with a warning (was: silent client hang until idle timeout).
• Wire the full SUBSCRIBE_UPDATE into the model subscriber so the producer aggregate reflects it and relays re-forward it upstream (was priority + end only).
• Counters fields are crate-private (load-bearing atomic orderings must not leak).

Ordered delivery is now a DVR-only opt-in

Subscription::default is ordered: false, and the aggregate is ordered only when every live subscriber asks for it (AND, was OR). Mirrored in the js/net wire defaults and moq-ffi's MoqSubscription default.

Datagrams

Drop the misleading public MAX_DATAGRAM_PAYLOAD (advertised 1200, but the encoded body overshot it). Enforce a 65535 buffering ceiling as FrameTooLarge, and drop oversize datagrams per hop against max_datagram_size() with a debug log, so the limit is enforced where it actually applies (including a future hop with a smaller MTU).

js/net (mirrors the above)

subscribe() takes a Subscription options object (not a positional priority), Subscriber.update() replaces updatePriority(), Datagram/Bandwidth are namespaced (Track.Datagram, Bandwidth.*), detached public consumer constructors are hidden, dead AnnouncedOptions.ignoreSelf is removed, datagram age uses performance.now(), plus doc fixes.

Test plan

• cargo test -p moq-net (444 pass) + moq-mux/json/hang/ffi/relay/transcode/native
• cargo check --workspace --all-targets clean (excluding the pre-existing macOS libmoq video build, libmoq: video.rs fails to compile on macOS (CVBuffer !Send across await) #2165)
• cargo clippy + RUSTDOCFLAGS=-D warnings cargo doc clean on moq-net
• all 13 js/* packages pass check (biome + tsc + tests)

Follow-ups (filed, out of scope here)

• Binding/parity gaps: moq-ffi: expose track datagrams across bindings #2148–js/net: full Subscription model (ordered/stale/range) and Subscriber.update() #2155
• moq-ffi: fold subscribe_media max_latency_ms into an options record #2164 subscribe_media positional arg → options record
• libmoq: video.rs fails to compile on macOS (CVBuffer !Send across await) #2165 pre-existing libmoq macOS video !Send build failure (unrelated to this change)
• moq-net: document all public items and enable missing_docs #2166 moq-net missing-docs sweep + enable the lint

🤖 Generated with Claude Code

(Written by Claude Fable 5)

---

Update — rebased on dev + fixes (Written by Claude Opus 4.8)

• Fixed a SIGABRT the original branch introduced: the session close-once refactor deferred the transport close to the last Session clone's drop, which in MoqSession runs off the tokio runtime; the backend's lingering-CLOSE tokio::spawn then panicked under panic=abort. Now closed under the runtime guard on drop. (Surfaced as the Python test_server crash.)
• Reconciled with overlapping work that landed on dev. Where dev reshaped the same surface: kept this branch's read_frame() -> frame::Frame and dropped dev Preserve raw frame timestamps #2174's additive read_frame_full split; kept the update() -> Result de-panic (dev Add moq-ffi track info and update #2177 still panicked) and applied it to SubscriberControl too; kept the js Subscription type name over dev js/net: model subscription priority as an options object #2167's SubscribeOptions; took dev's announce-id machinery (feat(moq-net,js/net): moq-lite-06-wip announce ids (typed START/END/RESTART, opt-in) #2160) and datagram FFI (Expose track datagrams through moq-ffi #2175) as-is; moved dev's libmoq refs to moq_net::track::Subscription.
• Validated: cargo check/clippy --workspace clean; moq-net/moq-ffi/libmoq/moq-native/moq-mux tests; js/net tsc+biome+236 tests; py 45 tests.

[sourcery-ai]

Sorry @kixelated, your pull request is larger than the review limit of 150000 diff characters