From 62c28323044c76d0b3a66dc66c974b512ef69860 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 13:28:24 -0700 Subject: [PATCH 1/5] quest: plan routes as the origin API Plans the route epic under the API audit (serve, identity and epoch, one Route handle, listing and follow) and a JS Following type, from the 2026-10-30 origin/epoch API audit. Amends announce-takeover and routes. Co-Authored-By: Claude Opus 5.5 --- quest/m1/announce-takeover.md | 35 ++++-- quest/m1/api-audit/README.md | 1 + quest/m1/api-audit/resolve/README.md | 1 + quest/m1/api-audit/resolve/js-following.md | 20 ++++ quest/m1/api-audit/route/README.md | 124 +++++++++++++++++++++ quest/m1/api-audit/route/events.md | 46 ++++++++ quest/m1/api-audit/route/handle.md | 93 ++++++++++++++++ quest/m1/api-audit/route/identity.md | 96 ++++++++++++++++ quest/m1/api-audit/route/serve.md | 47 ++++++++ quest/m1/cluster-routing/routes.md | 9 ++ 10 files changed, 465 insertions(+), 7 deletions(-) create mode 100644 quest/m1/api-audit/resolve/js-following.md create mode 100644 quest/m1/api-audit/route/README.md create mode 100644 quest/m1/api-audit/route/events.md create mode 100644 quest/m1/api-audit/route/handle.md create mode 100644 quest/m1/api-audit/route/identity.md create mode 100644 quest/m1/api-audit/route/serve.md diff --git a/quest/m1/announce-takeover.md b/quest/m1/announce-takeover.md index 00470d8891b..523380a1513 100644 --- a/quest/m1/announce-takeover.md +++ b/quest/m1/announce-takeover.md @@ -2,11 +2,12 @@ ## Goal -A worker advertises an epochless prefix to accept lazy work, then announces -an independent, more-specific route with a unique job epoch without resetting -readers already served by that same job. A different worker or replacement -job never inherits those readers. Rust and JS expose the transition as -`Takeover`, distinct from `Restart`. +A worker advertises a prefix route to accept lazy work, then announces +an independent, more-specific route with a unique job instance without +resetting readers already served by that same job. A different worker or +replacement job never inherits those readers. Readers holding `follow` or +`request` continue across the transition, which is distinct from a restart; +no public `Takeover` event is added. ## Plan @@ -18,6 +19,19 @@ gets no counterpart, since [moq-transport carries no epoch](/quest/m1/ietf-epoch Start/Restart is a supported fallback, including the accepted cold-start reset before this lands. +Amended 2026-10-30 (maintainer, the [route epic](/quest/m1/api-audit/route/README.md)). +Routes now name `Instance { identity, epoch }` +([Identity and epoch](/quest/m1/api-audit/route/identity.md)), so the +worker's prefix route carries the worker's own instance instead of being +epochless. A job answers with `request.announce` from +[One Route handle](/quest/m1/api-audit/route/handle.md) in place of +`Request::prepare` then `publish`. Continuity stays inside `follow` and +`request` ([Listing and follow](/quest/m1/api-audit/route/events.md)), so +the `Takeover` event bullet below is superseded. Below, read "epoch" as the +job's `Instance` and "epochless prefix" as the worker's prefix route. A job +that serves a held broadcast through +[serve](/quest/m1/api-audit/route/serve.md) needs no takeover. + - A worker advertises `transcode/` without an epoch. Demand for a path starts one job, which announces `transcode/path` with its own freshly minted epoch through `Request::prepare` then `publish`, the claim-to-route operation. @@ -99,12 +113,19 @@ Remove the cold-start warm-up reads that discard a claim's first subscription Run `just check`, `just test interop --all`, and `just drafts check`; wire regressions and benchmarks into existing CI lanes. -Public API: a `Takeover` event, mirrored across languages and exposed -bindings, on top of `Request::prepare` and `publish`. Wire: lite-07-wip gains +Public API: none beyond the route handle; `follow` and `request` continue +across a takeover. Wire: lite-07-wip gains ANNOUNCE_TAKEOVER; published versions retain their framing. +## Required + +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - takeover names the `Instance { identity, epoch }` this replaces the UUIDv7 epoch with +- [One Route handle](/quest/m1/api-audit/route/handle.md) - `request.announce` replaces `Request::prepare` then `publish` + ## Related +- [Listing and follow](/quest/m1/api-audit/route/events.md) - takeover continuity shows up inside `follow`, not as an event + - [Claim answer epochs](https://github.com/moq-dev/moq/pull/5678) - `Request::prepare` then `publish` answers a claim at the exact path under a fresh epoch, the operation TAKEOVER continues - [Routes and announces](/quest/m1/cluster-routing/routes.md) - the route layer whose ANNOUNCE_START layout overlaps this one's - [Retired requests](https://github.com/moq-dev/moq/pull/5294) - replacements never substitute content into held handles diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index 37e07504fdf..f1b2ae735de 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -74,6 +74,7 @@ Rejected in planning: ## Required - [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) - Rust, JS, and the bindings resolve a broadcast with `request(path, epoch)` or `follow(path, epoch)`, and every racy two-step caller is gone +- [Routes are the origin API](/quest/m1/api-audit/route/README.md) - apps announce exact or prefix routes through one `Route` handle naming `Instance { identity, epoch }`, prefix routes can serve a held broadcast, and readers get a listing plus `follow` - [Demand is wanted, everywhere](/quest/m1/api-audit/wanted.md) - every `used`/`unused` pair becomes `wanted()` and `wanted_changed()`, and unused ones go - [QMux datagrams obey or refuse their policy](/quest/m1/api-audit/qmux-datagrams.md) - `Session.datagrams` is the DOM interface, its high-water mark is live, and the inert settings throw - [No constructible internal handles](/quest/m1/api-audit/internal-constructors.md) - `Rendition`, `Lister`, `Arrivals`, and e2ee's generations get private constructors, and a lint rule stops new ones diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index 431c57d41c5..afee1cb9e91 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -54,6 +54,7 @@ Wire: none. - [The player takes any read-side origin](/quest/m1/api-audit/resolve/watch-origin.md) - `@moq/watch`'s `Player` and `Broadcast` accept a read-only `Origin.Consumer` as well as a `Table` - [The carla demo pins its driver epoch](/quest/m1/api-audit/resolve/callers.md) - the demo's driver watcher requests each run pinned to its announced epoch +- [JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md) - `follow` and `request` get their own JS types, matching Rust and the bindings ## Related diff --git a/quest/m1/api-audit/resolve/js-following.md b/quest/m1/api-audit/resolve/js-following.md new file mode 100644 index 00000000000..6b26b6899f2 --- /dev/null +++ b/quest/m1/api-audit/resolve/js-following.md @@ -0,0 +1,20 @@ +# [S] JS follow returns a Following + +## Goal + +In `@moq/net`, `Origin.Consumer.follow(path, ...)` returns its own +`Following` type, matching Rust and every binding, and `request` keeps +`Requesting`. Each type documents one meaning. js/watch's annotation +(`js/watch/src/broadcast.ts:284`) and the other callers compile against it. + +## Plan + +Found by the 2026-10-30 origin API audit +([route epic](/quest/m1/api-audit/route/README.md)). Today both methods +return `Requesting`, whose docs (`js/net/src/origin.ts:1624-1650`) describe +both behaviors. Keep the `active`/`closed` shape, and rename only where a +member means something different for `follow`. A local helper in +`js/net/src/connection/forward.ts:121` is also named `follow` but +re-receives a route; rename it so it stops reading as `Consumer.follow`. + +Public API: breaking for TypeScript type annotations only. Wire: none. diff --git a/quest/m1/api-audit/route/README.md b/quest/m1/api-audit/route/README.md new file mode 100644 index 00000000000..ec17a9a8485 --- /dev/null +++ b/quest/m1/api-audit/route/README.md @@ -0,0 +1,124 @@ +# Routes are the origin API + +## Goal + +An application talks to the origin only in routes, as the wire does. It +announces an exact path or a prefix and holds one `Route` handle. Every +route names its publisher `Instance { identity, epoch }`, and nothing in the +app API is epochless. A prefix route answers each request by serving a +broadcast it already holds or by announcing a per-path route. Readers see a +listing of paths, plus `follow` and `request` for instance changes, instead +of four announce event kinds. Rust, JS, moq-ffi, moq-c and the wrappers +mirror it. + +Non-goals: the route layer's wire messages and federation +([Routes and announces](/quest/m1/cluster-routing/routes.md)), lite-07 +takeover ([announce takeover](/quest/m1/announce-takeover.md)), and any +moq-transport identity ([moq-transport carries no epoch](/quest/m1/ietf-epoch-cut.md)). + +## Plan + +Planned 2026-10-30 (`/quest-plan`, maintainer). It started from an external +relay operator's question about [moq-dev/moq#6496](https://github.com/moq-dev/moq/pull/6496). +Their relay claims `requests("")`, a separate task publishes the pulled +broadcast at the exact path, and the client's first SUBSCRIBE fails with +Unroutable. A probe over `transport::memory` reproduced this on +moq-transport-18/22, moq-lite-06 and moq-lite-07-wip, whatever the handler +does: prepare and publish, drop, reject, or the crate-private `accept`. It +is the cold-start reset. The downstream's claim-prefix selection is replaced +once the exact route lands (`Selected::change`, +`rs/moq-net/src/model/origin.rs:4255-4299`). The one answer that never +resets is serving a held broadcast with no separate exact route. +The user's "it worked before #6496" did not reproduce on any older tree, +including one before [moq-dev/moq#5678](https://github.com/moq-dev/moq/pull/5678). +Their proposed `accept_published(&Publication)` would not avoid the reset, +so it was dropped. Their relay instead gets [serve](/quest/m1/api-audit/route/serve.md). + +The maintainer then asked for an audit of the origin, claim and epoch API. +Four read-only audits covered the Rust surface, JS and the bindings, the +epoch concept and its history, and moq.pro's usage. Findings that shaped +the decisions: + +- Every production publisher calls `Epoch::mint()` once per publication; + apps choose only when. The CLI already refuses a shared epoch. +- `Route` mixes what an app sets (epoch, cost, auth) with what relays fill + in (hops, via, source). `Route::default()` is epochless, so forgetting + `with_epoch`, or re-pricing with `Route::default().with_cost(..)`, + silently gives up resume. +- `Publication`, `Prepared`, `Announcer` and `Requests` describe one + lifecycle: unannounced, then announced. Claims and prepared answers + cannot carry cost or auth. +- Almost every caller merges `Start`/`Update`/`Restart`. Only moq-boy's + input handles `Restart` alone, and no JS consumer does. +- The worst internals exist for epochless routes, not because of epochs: + `Instance::Route(generation)`, `renew`, the held restart, and Selection + retirement. +- moq.pro needs prefix routes answered on demand. Its `.dash` dashboard + (`rs/dash/src/dashboard.rs`) answers with prepare and publish and works + around the reset in three places. Its sync-ingest mirror + (`rs/edge/src/sync/ingest.rs`) answers with `request.accept(broadcast)` + under a forwarded route. On `main` both calls are crate-private, so the + mirror breaks at its next moq bump. +- The selection order is documented three ways: `doc/concept/identity.md`, + the `Consumer::request` rustdoc, and the `Route.cost` doc. None of them + says that a more specific prefix outranks the epoch. + +Decision prompts: + +- Goal for the user's question: add a same-origin resolve; keep the reset; + fold it into takeover. The maintainer instead asked for the API audit. +- Mint the epoch in the library: ✅ yes, per announce; optional only; + leave as is. +- Claims: the maintainer asked what moq.pro needs. ✅ Keep prefix routes + with requests answered dynamically, since moq.pro's `.dash` and mirror + need them. +- Request answers: ✅ announce and serve; serve only; announce only. +- Lifecycle: ✅ one `Route` type for exact and prefix routes; two typed + route kinds. This came from "broadcasts don't actually exist on the + wire; only routes do". +- Where the epoch lives: ✅ on the route, minted at each announce; per + broadcast. A re-announce after js/publish's toggle is a restart, never a + splice. +- Announce events: ✅ shrink them, with continuity in `follow`; keep four + plus `Takeover`; keep four without it. +- Prefix routes get an instance like any route: ✅ yes, so a crashed + `.dash` that comes back up wins with its newer epoch. +- Explicit instance override for forwarders (mirror, archive resume, FFI): + ✅ yes; crate-private only. +- Pool tie-break: ✅ keep the per-path hash; newest first; out of scope. + The maintainer then reframed pools and restarts as identity. Routes with + one identity are runs of one publisher; different identities are + interchangeable and spread by hash. +- Naming: ✅ `identity` (a string, possibly a public key later) and `epoch` + (start time), paired as ✅ `Instance`. "group" is taken, and the UUIDv7 + epoch is retired. +- Wire: ✅ two explicit fields; packed into the UUIDv7. +- Epochless off the wire: ✅ the receiving hop mints one; keep it + wire-only. +- Run uniqueness: ✅ start time only. Pool hosts each use their own + identity, such as a hostname, so no two hosts share one. +- Ranking: ✅ newest-wins only within an identity, cost before the hash; + hash before cost. +- Default identity: ✅ random per process; hostname (it would leak machine + names across a CDN). +- Identity an edge mints: ✅ the session ID; auth subject, else session. +- Epochless machinery: ✅ [identity](/quest/m1/api-audit/route/identity.md) + deletes it; leave it to routes.md. +- Milestone: ✅ m1 under the API audit; m1 standalone; m2. +- The external user's PR offer: ✅ we do all of it; offer them serve. + +The epic owns no work of its own: each child updates the docs it makes +stale, including `doc/concept/identity.md`. + +## Required + +- [Serve a held broadcast](/quest/m1/api-audit/route/serve.md) - a prefix route's request can be answered with a broadcast the app already holds, and the first subscribe succeeds on every wire +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - every route names `Instance { identity, epoch }`, ranked newest within an identity and hashed across identities, with no epochless routes left in the origin +- [One Route handle](/quest/m1/api-audit/route/handle.md) - `Publication`, `Prepared`, `Announcer` and `Requests` become one `Route`, with app options separate from transit facts +- [Listing and follow](/quest/m1/api-audit/route/events.md) - apps read a path listing plus `follow`/`request`, and route metadata moves to a relay-level stream + +## Related + +- [Announce takeover](/quest/m1/announce-takeover.md) - builds on the identity and handle shapes here +- [Routes and announces](/quest/m1/cluster-routing/routes.md) - the wire route layer; identity takes over its epochless deletion +- [Grant subject](/quest/m1/cluster-routing/grant-subject.md) - key identities that a future public-key `identity` could reuse diff --git a/quest/m1/api-audit/route/events.md b/quest/m1/api-audit/route/events.md new file mode 100644 index 00000000000..ebb1024ac54 --- /dev/null +++ b/quest/m1/api-audit/route/events.md @@ -0,0 +1,46 @@ +# [M] Listing and follow + +## Goal + +Applications read announcements as a listing: each path is present or +absent. Instance changes, whether a restart or a takeover, are handled +inside `follow` and `request`, not seen as announce events. The `Start`, +`Update`, `End` and `Restart` variants leave the app API in Rust, JS, +moq-ffi, moq-c and the wrappers. Route metadata changes (cost, hops, +preference) move to a relay-level `routes()` stream that moq-relay and +stats use. + +Non-goals: the wire's ANNOUNCE and ANNOUNCE_RESTART messages, which stay as +they are, and the route handle ([One Route handle](/quest/m1/api-audit/route/handle.md)). + +## Plan + +Decided 2026-10-30 (maintainer); see the [epic](/quest/m1/api-audit/route/README.md). +The audit found that almost every production caller merges the variants, +for example `rs/moq-relay/src/internal.rs:933`, `rs/moq-rtc/src/lib.rs:81` +and `rs/moq-cli/src/archive.rs:85`. Every JS consumer branches only on +`end`. Only `rs/moq-boy/src/input.rs:76` handles `Restart` alone, and it +moves to `follow`. + +- The listing yields present and absent per path, with the announcement's + read-only facts. A path that changes instance stays present. To see an + instance change, hold a `follow`. +- `follow` reports the new instance on a restart. It also needs an `End` + signal for when the path goes absent, so that `moq_mux::follow::Instances` + can fold into it: delete the wrapper's duplicate epoch filter and keep + its one-shot fixed mode only if a caller needs it. +- `routes()` lives on the origin consumer for relays and stats, and is + hidden from the app-level docs. +- Bindings: replace `MoqAnnounceEvent`'s variants, and the go and python + interop clients' and carla `publish.py:303-340`'s Restart handling, with + the listing plus `follow`. +- Update `doc/concept/identity.md`'s follower section and the binding docs. + +Run `just check` and `just test interop --all`. + +Public API: breaking across the announce stream in every language. Wire: +none. + +## Related + +- [Announce takeover](/quest/m1/announce-takeover.md) - its continuity shows up inside `follow`, with no public `Takeover` variant diff --git a/quest/m1/api-audit/route/handle.md b/quest/m1/api-audit/route/handle.md new file mode 100644 index 00000000000..a09bcec2257 --- /dev/null +++ b/quest/m1/api-audit/route/handle.md @@ -0,0 +1,93 @@ +# [XL] One Route handle + +## Goal + +An application publishes by announcing a route and holding the `Route` +handle it gets back. `Publication`, `Prepared`, `Announcer`, `Requests` and +`Producer::publish` are gone, in Rust, JS, moq-ffi, moq-c and the wrappers: + +```rust +// An exact route serves one broadcast; dropping the route withdraws it. +let broadcast = broadcast::Producer::new(); +broadcast.create_track("catalog", info)?; +let route = origin.announce("live/alice", broadcast, Options::default())?; +route.set_cost(5); // re-prices in place, same instance + +// A prefix route serves requests. +let claim = origin.announce_prefix("transcode", Options::default())?; +while let Some(request) = claim.requested().await { + // Either serve a broadcast already held, under the claim's instance... + // request.serve(held); + // ...or announce the path as its own route and instance. + let job = request.announce(broadcast::Producer::new(), Options::default())?; + spawn(run(job)); +} +``` + +Apps pass only options: `cost`, `auth`, and an `Instance` override for +re-publishing a run they did not start (a mirror, archive resume, FFI +pass-through). Without the override, `announce` mints a new instance under +the origin's identity on every call, so re-announcing a broadcast is a +restart and never a splice. Hops, via, source and the anonymous mark become +read-only facts on a received announcement; `Hop`, `Hops` and `HopLimit` +leave the public API. + +Non-goals: the instance model ([Identity and epoch](/quest/m1/api-audit/route/identity.md)), +announce events ([Listing and follow](/quest/m1/api-audit/route/events.md)), +and the route layer's wire metric ([Routes and announces](/quest/m1/cluster-routing/routes.md)). + +## Plan + +Decided 2026-10-30 (maintainer); see the [epic](/quest/m1/api-audit/route/README.md). +The names above are a sketch. Settle the final ones in the PR, keeping Rust, +JS and the bindings identical. + +- **One type.** An exact route derefs to the `broadcast::Producer` it + serves. A prefix route yields requests. Each request is answered by + `serve(consumer)` (from [serve](/quest/m1/api-audit/route/serve.md)), + by `announce(broadcast, options)`, which returns that path's exact + `Route`, or by `reject`. A prefix route takes cost and auth just as an + exact one does, so claims can be priced. Today `Requests::route()` is + always the default and `update_route` is crate-private. +- **No unannounced state.** Today's `create_broadcast`-then-`announce` + callers become a plain `broadcast::Producer` that is announced once it + is ready. They are: catalog first (`moq-cli` hls, rtsp and publish; + moq-studio; moq-mux `ts/programs.rs`), announce after SDP + (`moq-rtc/server/whip.rs`), and js/publish's on/off toggle. +- **Sessions.** Relay forwarding keeps its crate-private construction with + forwarded instance, hops and cost, which the deleted `requests_route` + and `dynamic_route` did. `moq_net::fuzz`'s hatches shrink to what tests + still need. +- **JS leaks.** Removing `Requests`/`requestsRoute`/`updateRoute` also + removes their `@internal`-but-public exposure on `Table`. Stop exporting + `Epoch.toBytes`/`fromBytes`, `RequestSlot` and `RouteEntry`, and delete + the orphaned `@internal` doc blocks (`js/net/src/origin.ts:2160-2176`). +- **Bindings.** moq-ffi's `MoqRoute`/`MoqPublication`/ + `MoqBroadcastRequest`/`MoqBroadcastPrepared`, moq-c's `moq_origin_requests`, + `moq_broadcast_request_*`, `moq_broadcast_prepared_*`, `moq_publication_*` + and `moq_mint_epoch`, and the py/kt/swift/dart/go wrappers all move to + the route handle. [moq-c's API gaps](/quest/m1/c/api-gaps.md) error-code + fix applies to whichever functions remain. +- **Callers.** Migrate every caller: about 25 crates use `create_broadcast` + or `publish`, about 19 set an epoch, plus `@moq/publish`, moq-boy, carla + and the e2ee generations. The rs/moq-net and js/net `MIGRATE.md` entries + and the PR's Impact section give the mapping, including moq.pro's + `.dash` claim and sync-ingest mirror. +- **Docs.** Update `doc/concept/identity.md`'s publishing and lazy-job + examples, `doc/lib/rs`, `doc/lib/js` and `doc/lib/c`, and each binding's + README. + +Run `just check` and `just test interop --all`. + +Public API: breaking across moq-net, @moq/net, moq-ffi, moq-c and the +wrappers. Wire: none. + +## Required + +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - the instance the handle's options and minting name +- [Serve a held broadcast](/quest/m1/api-audit/route/serve.md) - the served answer this handle carries over + +## Related + +- [The player takes any read-side origin](/quest/m1/api-audit/resolve/watch-origin.md) - also retypes JS `Table` +- [No constructible internal handles](/quest/m1/api-audit/internal-constructors.md) - the same JS hygiene rule diff --git a/quest/m1/api-audit/route/identity.md b/quest/m1/api-audit/route/identity.md new file mode 100644 index 00000000000..241e279cd66 --- /dev/null +++ b/quest/m1/api-audit/route/identity.md @@ -0,0 +1,96 @@ +# [XL] Identity and epoch + +## Goal + +Every route in an origin names its publisher `Instance { identity, epoch }`: +`identity` is a string naming the publisher, and `epoch` is when this run +started. The UUIDv7 `Epoch` is retired, and the origin no longer holds any +epochless route. A route resolving a path is chosen like this: + +1. The most specific prefix wins. +2. Within one identity, only its newest epoch is eligible. An identity + publishes one run per path at a time, so a reconnect supersedes its + stale route at once, even when that route is cheaper. +3. Among different identities, the order is link preference, then cost, + then a broadcast published on this origin, then hop length, then a hash + of the identity and the full requested path. Relays agree on the result, + and paths spread over a pool's hosts. +4. Routes with equal identity and epoch are one run, so a reader resumes + across them without a seam. + +Non-goals: moq-transport identity (it carries none, +[decided 2026-10-28](/quest/m1/ietf-epoch-cut.md)), public-key identities +(a later option), and the route-handle API shape +([One Route handle](/quest/m1/api-audit/route/handle.md)). + +## Plan + +Decided 2026-10-30 (maintainer); every prompt is in the +[epic](/quest/m1/api-audit/route/README.md). + +- **Types.** In `rs/moq-net`, `Identity` (string) and `Epoch` (start time + in microseconds, monotonic within a process) together form `Instance`. + Rename the internal `Instance`/`Resolution` types out of the way. Mirror + in `js/net`, moq-ffi, moq-c and the wrappers. `request(path, instance)`, + `follow`, catalog references and archive keys pin an `Instance`. +- **Default identity.** It is random, minted once per process (per origin + in JS) and kept for that process's lifetime, so reconnects within the + process supersede their own stale routes. A process restart is a new + identity until its old route is withdrawn. Services set a stable one + (`--identity` on the CLI and relay, an origin config field in the + libraries), for example a hostname. The default is never a hostname, + since routes reach every relay and subscriber. +- **Pools.** A pool is several hosts with distinct identities on one + prefix: transcoders, or moq.pro's three `.dash` control nodes. Step 3 + spreads paths over them. A host that is full withdraws its route (a + leaky bucket); a crashed host's route goes when its session closes or + drains. Document this pattern in `doc/concept/identity.md`, replacing + the epochless-claim lifecycle. +- **Wire, lite-07-wip.** Announcements carry `identity` and `epoch` as two + explicit fields in place of the UUIDv7 epoch, and requests that pin an + instance carry both. Update `drafts/` (the lite draft's announce and + epoch sections) and `doc/concept/moq-lite.md`. Released versions keep + their framing. lite-06 and older read the old field. Account for it + wherever lite-07 epochs flow today: announce IDs, compression bases, + snapshots and route filtering. +- **Minting off the wire.** A session that receives a route with no + identity mints one for it: identity = the session ID, epoch = when the + route arrived. This covers moq-transport, older lite and third-party + peers. The origin then holds no epochless route. A pool reached through + an older-lite relay hop can pick different winners per relay + ([moq-dev/moq#6948](https://github.com/moq-dev/moq/pull/6948)'s + objection), which is accepted because m1 prefers lite-07 between relays. + The objection does not apply otherwise: newest-wins only compares epochs + within one identity, so mint order never outranks cost or preference. +- **Delete the epochless machinery.** `Instance::Route(generation)` and + its renewals, `restarted_since`, the held-restart Release for epochless + routes, Selection retirement, and the epochless refusal from + [moq-dev/moq#6816](https://github.com/moq-dev/moq/pull/6816). This + replaces that part of [Routes and announces](/quest/m1/cluster-routing/routes.md) + (decided there 2026-10-27). +- **Docs.** Rewrite `doc/concept/identity.md`'s identity, selection-order + and lazy-job sections to the rule above, so the guide, the + `Consumer::request` rustdoc and the `Route` docs give one order, with + specificity first. Also update `doc/setup/redundancy.md` (a redundant + pair is two identities), `doc/bin/cli.md` ("Publisher runs" and + `--epoch`, which becomes `--identity`) and `doc/bin/relay/config.md`. +- **moq.pro.** Recording resume compares `routeEpoch` + (`api/src/recording.ts`), and recordings are keyed `/@/...`. + The Impact section says how to key on `Instance` instead, for moq.pro's + bump. +- **Tests.** Cover a reconnect superseding its stale route across a + cheaper path; two identities hashing per path; same-instance resume + across two relays; a host withdrawing when full; minting at a + moq-transport and a lite-06 ingest; and archive and catalog pins. Update + every epoch fixture. Run `just check`, `just test interop --all` and + `just drafts check`. Any compat cell that asserted UUID epochs gets a + planned break in `test/interop/compat/planned-breaks.json`. + +Public API: breaking. `Epoch` becomes the start-time half of `Instance`, +and `Route::with_epoch` gives way to the handle's options. Wire: lite-07-wip +announce and request fields change; released versions are unchanged. + +## Related + +- [Routes and announces](/quest/m1/cluster-routing/routes.md) - its ANNOUNCE_START layout overlaps; whichever lands second rebases +- [Grant subject](/quest/m1/cluster-routing/grant-subject.md) - a later public-key `identity` could reuse its key identities diff --git a/quest/m1/api-audit/route/serve.md b/quest/m1/api-audit/route/serve.md new file mode 100644 index 00000000000..95c274ca07e --- /dev/null +++ b/quest/m1/api-audit/route/serve.md @@ -0,0 +1,47 @@ +# [M] Serve a held broadcast + +## Goal + +An application answering a prefix route's request can hand over a broadcast +it already holds: `request.serve(consumer)` in Rust and +`request.serve(broadcast)` in JS, mirrored in moq-ffi, moq-c and the +wrappers. The answer is served under the prefix route's own instance and +announces no exact route. A client's first subscribe through it succeeds +over moq-transport-18, moq-transport-22, moq-lite-06 and moq-lite-07-wip. + +Non-goals: the route handle rename ([One Route handle](/quest/m1/api-audit/route/handle.md) +carries `serve` over), and removing the reset for answers that announce a +per-path route ([announce takeover](/quest/m1/announce-takeover.md)). + +## Plan + +Decided 2026-10-30 (maintainer); see the [epic](/quest/m1/api-audit/route/README.md). +This lands first, on today's `origin::Requests`/`Request`, so moq.pro's +sync-ingest mirror (`rs/edge/src/sync/ingest.rs`, which calls +`request.accept`) and the external relay operator have a supported answer +before the larger rework. + +- Make the crate-private `Request::accept` (`rs/moq-net/src/model/origin.rs`) + public as `serve`, for application claims as well as sessions. Replace the + `compile_fail,E0624` doctest with usage docs. In JS, expose `#accept` as + `serve` and drop `hooks.acceptRequest` if nothing else needs it. +- Contract, in rustdoc and `doc/concept/identity.md`: a served answer is + the prefix route's instance. To restart a served path with different + bytes, re-announce the route rather than serving new bytes under it. A + job that may restart per path answers with `prepare`/`publish`, and takes + the cold-start reset. +- Tests: turn the reproduction from planning into an integration test in + `rs/moq-net-tests/tests/integration/`. A server origin `requests("")` + linked over `transport::memory`; the handler serves a held broadcast; the + client's first `request` plus `subscribe` reads a frame on every version + above. Keep the prepare/publish case asserting today's reset, so + takeover's change to it is visible. Mirror it in `js/net`. +- `MIGRATE.md` (rs/moq-net, js/net): mention `serve` beside the existing + #6496 entry. It is additive. + +Public API: additive `Request::serve` in Rust, JS and the bindings. Wire: +none. + +## Related + +- [moq-dev/moq#6496](https://github.com/moq-dev/moq/pull/6496) - made `accept` crate-private; this reopens it under a stated contract diff --git a/quest/m1/cluster-routing/routes.md b/quest/m1/cluster-routing/routes.md index 5d1fe8e82aa..b414227b00a 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -669,6 +669,15 @@ mints at its own time, so mint order outranks cost, preference, and the local-broadcast tie and relays disagree on a pool path's winner, while ranking a minted epoch last keeps the renewal it was meant to delete. +Moved 2026-10-30 (maintainer, the [route epic](/quest/m1/api-audit/route/README.md)): +[Identity and epoch](/quest/m1/api-audit/route/identity.md) now deletes that +epochless machinery, so this quest no longer does. A session mints +`Instance { identity, epoch }` for any route that arrives without one, and +newest-wins compares epochs only within one identity, so mint order no +longer outranks cost or preference. The rest of the 2026-10-27 decision +stands. Build the route layer's identity fields on that `Instance` instead of +the UUIDv7 epoch. + Decided 2026-10-27 (maintainer), from [grant subject](https://github.com/moq-dev/moq/pull/6992): decide what key identities are filed under for sessions allowed to publish part of the tree From 3d0a9cba48d7b70b9307a5462fce64757dea97fd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 13:46:53 -0700 Subject: [PATCH 2/5] quest: address review on the route epic Co-Authored-By: Claude Opus 5.5 --- quest/m1/announce-takeover.md | 24 +++++++++++----------- quest/m1/api-audit/resolve/README.md | 4 ++++ quest/m1/api-audit/resolve/js-following.md | 5 ++++- quest/m1/api-audit/route/README.md | 3 ++- quest/m1/api-audit/route/handle.md | 7 ++++++- quest/m1/api-audit/route/identity.md | 8 +++++++- quest/m1/api-audit/route/serve.md | 4 ++++ quest/m1/cluster-routing/routes.md | 5 +++-- 8 files changed, 42 insertions(+), 18 deletions(-) diff --git a/quest/m1/announce-takeover.md b/quest/m1/announce-takeover.md index 523380a1513..8b6b27a9dd9 100644 --- a/quest/m1/announce-takeover.md +++ b/quest/m1/announce-takeover.md @@ -27,14 +27,15 @@ epochless. A job answers with `request.announce` from [One Route handle](/quest/m1/api-audit/route/handle.md) in place of `Request::prepare` then `publish`. Continuity stays inside `follow` and `request` ([Listing and follow](/quest/m1/api-audit/route/events.md)), so -the `Takeover` event bullet below is superseded. Below, read "epoch" as the -job's `Instance` and "epochless prefix" as the worker's prefix route. A job +the bullets below use those names. Where they still say "epoch", read the +job's `Instance`. A job that serves a held broadcast through [serve](/quest/m1/api-audit/route/serve.md) needs no takeover. -- A worker advertises `transcode/` without an epoch. Demand for a path starts - one job, which announces `transcode/path` with its own freshly minted epoch - through `Request::prepare` then `publish`, the claim-to-route operation. +- A worker advertises `transcode/` as a prefix route under its own + instance. Demand for a path starts one job, which announces + `transcode/path` with its own freshly minted instance through + `request.announce`, the claim-to-route operation. Lazy catalog references and initial requests need no anticipated epoch. Identical encoder settings do not make two workers the same instance. - TAKEOVER is START plus a predecessor Announce ID: it carries the child @@ -69,12 +70,11 @@ that serves a held broadcast through A takeover from A cannot adopt B's readers. Forward TAKEOVER only where its continuity assertion remains true; otherwise use ordinary Start/Restart. Initial snapshots can use START without replaying historical takeovers. -- Add an explicit `Takeover` announcement event carrying the new announcement - and predecessor identity, mirrored in Rust, JS and exposed bindings. Use - model identity rather than leaking stream-local wire IDs. This replaces - expanding Update, whose existing meaning is an in-place metadata change. - Relays preserve the relationship and applications distinguish continuity - from replacement. A proven takeover does not renew a composed catalog. +- Applications see no takeover event: a reader holding `follow` or `request` + simply continues across a proven takeover, and sees a restart otherwise. + Relays preserve the predecessor relationship in model identity rather than + leaking stream-local wire IDs. A proven takeover does not renew a composed + catalog. - An epoch-bound request still requires a matching advertised epoch; response metadata alone does not make an epochless route eligible. Legacy best-effort catalog verification remains weaker and never authorizes implicit stitching. @@ -86,7 +86,7 @@ Decided 2026-10-27 (maintainer): this no longer waits on relay-minted route epochs, only the job's own epoch above: an epochless route stays ineligible for an epoch-bound request, as above. Takeover builds on what lite-07-wip and `main` already have: stream-local Announce IDs, -ANNOUNCE_RESTART, Base compression, `Request::prepare`/`publish`, and the +ANNOUNCE_RESTART, Base compression, the claim-to-route answer, and the claim helpers. Its ANNOUNCE_START field layout overlaps with routes (hops become a Route ID), so whichever of the two lands second rebases onto the other. diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index afee1cb9e91..3606950794b 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -13,6 +13,10 @@ Rust, JS, and every binding: - `follow(path, epoch)` follows the path across publisher instances (today's `announced_broadcast`), pinned to `epoch` when given. +[Identity and epoch](/quest/m1/api-audit/route/identity.md) later changes the +pin from `epoch` to `Instance { identity, epoch }` in both; the two +resolutions stay as they are. + No caller can assemble a racy two-step resolve, and no crate hand-rolls "resolve once discovery synced". diff --git a/quest/m1/api-audit/resolve/js-following.md b/quest/m1/api-audit/resolve/js-following.md index 6b26b6899f2..4b02b3cefbc 100644 --- a/quest/m1/api-audit/resolve/js-following.md +++ b/quest/m1/api-audit/resolve/js-following.md @@ -5,7 +5,10 @@ In `@moq/net`, `Origin.Consumer.follow(path, ...)` returns its own `Following` type, matching Rust and every binding, and `request` keeps `Requesting`. Each type documents one meaning. js/watch's annotation -(`js/watch/src/broadcast.ts:284`) and the other callers compile against it. +(`js/watch/src/broadcast.ts:284`) and the other callers compile against it. js/watch's cache +entry (`js/watch/src/broadcast.ts:172`) and the local at `:285` hold either +result, so they take a shared read-side type (the common `active`/`closed` +shape) or `Requesting | Following`. ## Plan diff --git a/quest/m1/api-audit/route/README.md b/quest/m1/api-audit/route/README.md index ec17a9a8485..7c49b36dbc8 100644 --- a/quest/m1/api-audit/route/README.md +++ b/quest/m1/api-audit/route/README.md @@ -63,7 +63,8 @@ the decisions: the `Consumer::request` rustdoc, and the `Route.cost` doc. None of them says that a more specific prefix outranks the epoch. -Decision prompts: +Decision prompts (options separated by semicolons; the chosen one is marked ✅, +and every option after it was rejected): - Goal for the user's question: add a same-origin resolve; keep the reset; fold it into takeover. The maintainer instead asked for the API audit. diff --git a/quest/m1/api-audit/route/handle.md b/quest/m1/api-audit/route/handle.md index a09bcec2257..2767609d1e9 100644 --- a/quest/m1/api-audit/route/handle.md +++ b/quest/m1/api-audit/route/handle.md @@ -26,7 +26,12 @@ while let Some(request) = claim.requested().await { Apps pass only options: `cost`, `auth`, and an `Instance` override for re-publishing a run they did not start (a mirror, archive resume, FFI -pass-through). Without the override, `announce` mints a new instance under +pass-through). The override grants no more than a minted instance does: +publishing still requires the path's grant, as an explicit epoch does today +through `Route::with_epoch`. Only an app that may already publish the path +can claim continuity with a run on it. Binding identities to keys is the +later public-key option in +[Identity and epoch](/quest/m1/api-audit/route/identity.md). Without the override, `announce` mints a new instance under the origin's identity on every call, so re-announcing a broadcast is a restart and never a splice. Hops, via, source and the anonymous mark become read-only facts on a received announcement; `Hop`, `Hops` and `HopLimit` diff --git a/quest/m1/api-audit/route/identity.md b/quest/m1/api-audit/route/identity.md index 241e279cd66..af004b3af5c 100644 --- a/quest/m1/api-audit/route/identity.md +++ b/quest/m1/api-audit/route/identity.md @@ -36,7 +36,13 @@ Decided 2026-10-30 (maintainer); every prompt is in the - **Default identity.** It is random, minted once per process (per origin in JS) and kept for that process's lifetime, so reconnects within the process supersede their own stale routes. A process restart is a new - identity until its old route is withdrawn. Services set a stable one + identity until its old route is withdrawn. A stable identity orders its + runs by wall-clock start time, as UUIDv7 epochs do today. If a restart's + clock rolls back, or lands on an equal epoch, the stale route keeps + winning until it is withdrawn, and never splices: an equal epoch from a + restarted process is refused as a conflicting copy, as differing track + info is today ([moq-dev/moq#6460](https://github.com/moq-dev/moq/pull/6460)). + Test both cases. Services set a stable one (`--identity` on the CLI and relay, an origin config field in the libraries), for example a hostname. The default is never a hostname, since routes reach every relay and subscriber. diff --git a/quest/m1/api-audit/route/serve.md b/quest/m1/api-audit/route/serve.md index 95c274ca07e..a160bf02094 100644 --- a/quest/m1/api-audit/route/serve.md +++ b/quest/m1/api-audit/route/serve.md @@ -30,6 +30,10 @@ before the larger rework. bytes, re-announce the route rather than serving new bytes under it. A job that may restart per path answers with `prepare`/`publish`, and takes the cold-start reset. +- Served-answer cache: an answer that `prepare`/`publish` stored in the + prefix route's served cache must not serve a later request once its + exact route is withdrawn. Check `ServeState`'s cache on withdrawal, fix + it if the answer survives, and test it. - Tests: turn the reproduction from planning into an integration test in `rs/moq-net-tests/tests/integration/`. A server origin `requests("")` linked over `transport::memory`; the handler serves a held broadcast; the diff --git a/quest/m1/cluster-routing/routes.md b/quest/m1/cluster-routing/routes.md index b414227b00a..d7c53924481 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -239,8 +239,9 @@ The handoff contract below, decided 2026-10-16, settles claim freshness: - Claim freshness follows the handoff contract below, independently of the requested path's forwarding choice. - Only the first hop selects the origin. It keeps `route_order`'s shape over - the origin nodes announcing the path: longest prefix, newest epoch, the - link's priority (`origin::Producer::with_preference`), seed plus route + the origin nodes announcing the path: longest prefix, newest epoch (within + one identity only, per [Identity and epoch](/quest/m1/api-audit/route/identity.md), + decided 2026-10-30), the link's priority (`origin::Producer::with_preference`), seed plus route metric, then a rendezvous hash of the path and the identity, and the newest connection only for an otherwise identical route. The hash drops the hop chain, which differs per node, so every node agrees on a pool member From e23efda6ab4a055443bb1d13fe057138bab7ad41 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 14:17:29 -0700 Subject: [PATCH 3/5] quest: routes own their broadcasts, identity is one stream Routes create and own their broadcasts; identity is a continuous sequence space with a private per-identity epoch; edges mint per announcement; and announce-takeover is re-planned around inherited identity. Co-Authored-By: Claude Opus 5.5 --- quest/m1/announce-takeover.md | 183 ++++++++++----------------- quest/m1/api-audit/README.md | 2 +- quest/m1/api-audit/resolve/README.md | 2 +- quest/m1/api-audit/route/README.md | 54 ++++++-- quest/m1/api-audit/route/events.md | 10 +- quest/m1/api-audit/route/handle.md | 120 ++++++++++-------- quest/m1/api-audit/route/identity.md | 138 +++++++++++--------- quest/m1/api-audit/route/serve.md | 13 +- quest/m1/cluster-routing/routes.md | 13 +- quest/m1/lite07-finalize.md | 2 +- 10 files changed, 282 insertions(+), 255 deletions(-) diff --git a/quest/m1/announce-takeover.md b/quest/m1/announce-takeover.md index 8b6b27a9dd9..7c5ba98aaee 100644 --- a/quest/m1/announce-takeover.md +++ b/quest/m1/announce-takeover.md @@ -1,131 +1,86 @@ -# [XL] Announcements take over a claim's existing instances +# [L] A job's exact route continues its claim's readers ## Goal -A worker advertises a prefix route to accept lazy work, then announces -an independent, more-specific route with a unique job instance without -resetting readers already served by that same job. A different worker or -replacement job never inherits those readers. Readers holding `follow` or -`request` continue across the transition, which is distinct from a restart; -no public `Takeover` event is added. +A worker advertises a prefix route to accept lazy work. When a request +starts a job, the job's exact route carries the prefix route's identity, so +a reader first served through the claim continues on the exact route with +no cold-start reset, across relays, on lite-07. A different worker, or a +restarted job, never continues those readers: each is another identity. No +new wire message and no public event are added. Readers holding `follow` or +`request` simply continue, and see a new broadcast only when the identity +changes. -## Plan - -Decided in the 2026-10-10 quest audit interview: replace response-only claim -epochs with `ANNOUNCE_TAKEOVER`. Keep this shared-model and lite-07 work in -m1 and a prerequisite of the lite-07 cut, not the m0 release. moq-transport -gets no counterpart, since [moq-transport carries no epoch](/quest/m1/ietf-epoch-cut.md) -(decided 2026-10-28), so a moq-transport hop uses Start/Restart. Ordinary -Start/Restart is a supported fallback, including the accepted cold-start -reset before this lands. +Non-goals: moq-transport, which keeps the cold-start reset +([moq-transport carries no epoch](/quest/m1/ietf-epoch-cut.md), and an +edge mints a new identity for each announcement, +[Identity and epoch](/quest/m1/api-audit/route/identity.md)). -Amended 2026-10-30 (maintainer, the [route epic](/quest/m1/api-audit/route/README.md)). -Routes now name `Instance { identity, epoch }` -([Identity and epoch](/quest/m1/api-audit/route/identity.md)), so the -worker's prefix route carries the worker's own instance instead of being -epochless. A job answers with `request.announce` from -[One Route handle](/quest/m1/api-audit/route/handle.md) in place of -`Request::prepare` then `publish`. Continuity stays inside `follow` and -`request` ([Listing and follow](/quest/m1/api-audit/route/events.md)), so -the bullets below use those names. Where they still say "epoch", read the -job's `Instance`. A job -that serves a held broadcast through -[serve](/quest/m1/api-audit/route/serve.md) needs no takeover. +## Plan -- A worker advertises `transcode/` as a prefix route under its own - instance. Demand for a path starts one job, which announces - `transcode/path` with its own freshly minted instance through - `request.announce`, the claim-to-route operation. - Lazy catalog references and initial requests need no anticipated epoch. - Identical encoder settings do not make two workers the same instance. -- TAKEOVER is START plus a predecessor Announce ID: it carries the child - prefix, epoch and ordinary announcement routing metadata, and allocates - its own announcement ID. The predecessor is a one-time continuity - reference, not a lifetime dependency. Either route can end independently; - ending the new route never silently returns its readers to the pool. -- The predecessor must be live on the same ordered announcement stream. - A sender that has not advertised it sends START instead. An unknown or - retired received ID is a protocol violation. No active reader is required: - with no instance to adopt, the message simply installs the new route. -- TAKEOVER explicitly asserts continuation of the same content, not just - common prefix ancestry. Adopt only instances actually resolved through the - named predecessor incarnation and covered by the new prefix. Preserve - their handles, group positions, metadata, object and negative caches, - catalog pins and outstanding requests. Unrelated siblings are unchanged. - A known epoch must match; a requested epoch must be verified when possible. -- Bind the publishing operation to the same live broadcast served through - the claim. A worker restarting a job under an unchanged claim cannot use - TAKEOVER to relabel the previous job's cached content. Use ordinary - replacement when continuity cannot be asserted. In the model, prove that - the predecessor relationship identifies the accepted instance, including - old retained generations and pending answers, before fixing the final wire - fields; do not infer it from a matching worker or configuration. -- RESTART retains an Announce ID today. TAKEOVER names its current - incarnation in stream order, never old handles merely sharing that ID. - The new prefix must lie within predecessor coverage and authorization. - Announce-request clamping may make the visible prefixes equal; distinguish - the advertisements without requiring a strictly longer encoded prefix. -- Relays translate predecessor IDs per stream using actual serving - provenance. An aggregated prefix can serve paths through different workers. - A takeover from A cannot adopt B's readers. Forward TAKEOVER only where - its continuity assertion remains true; otherwise use ordinary Start/Restart. - Initial snapshots can use START without replaying historical takeovers. -- Applications see no takeover event: a reader holding `follow` or `request` - simply continues across a proven takeover, and sees a restart otherwise. - Relays preserve the predecessor relationship in model identity rather than - leaking stream-local wire IDs. A proven takeover does not renew a composed - catalog. -- An epoch-bound request still requires a matching advertised epoch; response - metadata alone does not make an epochless route eligible. Legacy best-effort - catalog verification remains weaker and never authorizes implicit stitching. - On older wires, translate this optimization into ordinary announcements - and required Restart rather than changing published framing. +Re-planned 2026-10-30 (maintainer, the [route epic](/quest/m1/api-audit/route/README.md)): +continuity is the identity promise, not an `ANNOUNCE_TAKEOVER` predecessor +ID. An identity is one continuous sequence space at a path, so the exact +route and the claim's answer are the same consumer route, +origin → route(path, identity) → broadcast. The 2026-10-10 plan (TAKEOVER as +START plus a predecessor Announce ID, with per-stream ID translation in +relays) is dropped. Its safety requirements carry over, as follows. -Decided 2026-10-27 (maintainer): this no longer waits on -[Routes and announces](/quest/m1/cluster-routing/routes.md), and needs no -relay-minted route epochs, only the job's own epoch above: an epochless -route stays ineligible for an epoch-bound request, as above. Takeover builds on -what lite-07-wip and `main` already have: stream-local Announce IDs, -ANNOUNCE_RESTART, Base compression, the claim-to-route answer, and the -claim helpers. Its ANNOUNCE_START field layout overlaps with routes (hops -become a Route ID), so whichever of the two lands second rebases onto the -other. +- **Inheriting the identity.** `request.route(options)` from + [One Route handle](/quest/m1/api-audit/route/handle.md) creates the + path's exact route under the prefix route's identity by default, and the + answer it gives the waiting request is that route's broadcast. A job + that serves a held broadcast through [serve](/quest/m1/api-audit/route/serve.md) + never announces an exact route, so it needs none of this. +- **One stream per path and identity.** A claim may answer a path under + its identity only while that stream is live. Once the job's route ends, + the next request for that path gets a fresh identity, because its + sequences restart. A request pinned to the old identity is refused as + ended, never answered with new bytes. This is the old rule "a worker + restarting a job under an unchanged claim cannot relabel the previous + job's cached content", now enforced in the origin. Prove it in the + model, including retained generations and pending answers, before + relying on it. +- **Relays.** An aggregated prefix can be served by several workers, but + each worker has its own identity. A relay can therefore only continue a + reader on routes carrying the identity it resolved, and readers of A + never move to B. A relay that cannot keep the identity, such as an + older-lite hop, mints a new one, so its readers see a new broadcast + rather than a splice. +- **What a continued reader keeps.** Handles, group positions, metadata, + object and negative caches, catalog pins, and outstanding + TRACK/SUBSCRIBE/FETCH requests. Unrelated sibling paths are unchanged. A + continued stream does not renew a composed catalog. +- **Docs.** Update the lazy-job lifecycle in `doc/concept/identity.md`: + the cold-start step no longer resets on lite-07. Also update the lite + draft's announce section where it mentions claims. -Implement against lite-07-wip, and reuse the routing fields and identity -model of whichever ROUTE/ANNOUNCE shape is on `main` rather than adding a -second one. Account for TAKEOVER in announcement IDs, compression bases, -snapshot counts, route filtering, duplicate-advertisement rules and -retirement. Update the lite draft and existing identity/compatibility docs in -the implementation PR, and add a takeover section to the identity and -recovery guide (`doc/concept/identity.md`), whose cold-start step and -lazy-job lifecycle it changes; the guide does not replace inline docs. +Tests with controlled time cover: +- the first reader before and after the exact route lands, with no reader + at all, and with two workers at one prefix; +- a job restarting on one worker, and a request pinned to an ended stream; +- pending TRACK/SUBSCRIBE/FETCH and late groups across the transition; +- independently ending prefix and exact routes, and late snapshots; +- multi-hop and diamond relays, and mixed versions with an older-lite hop; +- held catalog and media pins, the actual players, and the composer. -Tests with controlled time: first view before/after takeover; absent reader; -invalid/retired predecessor; same ID after Restart; two workers at one prefix; -job restart on one worker; pending TRACK/SUBSCRIBE/FETCH and late groups across -takeover; conflicting epochs; equal clamped prefixes; independently ending -parent/child; late snapshots; multi-hop and diamond relays; mixed versions; -and held catalog/media pins. Include the actual players and composer-facing -event, not only route-table checks. Measure route/readers fanout on both axes. -Remove the cold-start warm-up reads that discard a claim's first subscription -(`claimed` in `rs/moq-net-tests/tests/integration/restart.rs` and the -`rs/moq-net/tests/integration/drained_claim.rs` helper) and assert that first subscription succeeds instead. -Run `just check`, `just test interop --all`, and `just drafts check`; wire -regressions and benchmarks into existing CI lanes. +Remove the cold-start warm-up reads (`claimed` in +`rs/moq-net-tests/tests/integration/restart.rs` and the +`rs/moq-net/tests/integration/drained_claim.rs` helper) for lite-07 and +assert that the first subscription succeeds. Keep them for moq-transport. +Run `just check`, `just test interop --all` and `just drafts check`. -Public API: none beyond the route handle; `follow` and `request` continue -across a takeover. Wire: lite-07-wip gains -ANNOUNCE_TAKEOVER; published versions retain their framing. +Public API: none beyond the route handle. Wire: none beyond +[Identity and epoch](/quest/m1/api-audit/route/identity.md)'s fields. ## Required -- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - takeover names the `Instance { identity, epoch }` this replaces the UUIDv7 epoch with -- [One Route handle](/quest/m1/api-audit/route/handle.md) - `request.announce` replaces `Request::prepare` then `publish` +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - the identity a job's exact route inherits +- [One Route handle](/quest/m1/api-audit/route/handle.md) - `request.route` creates the exact route under the claim's identity ## Related -- [Listing and follow](/quest/m1/api-audit/route/events.md) - takeover continuity shows up inside `follow`, not as an event - -- [Claim answer epochs](https://github.com/moq-dev/moq/pull/5678) - `Request::prepare` then `publish` answers a claim at the exact path under a fresh epoch, the operation TAKEOVER continues -- [Routes and announces](/quest/m1/cluster-routing/routes.md) - the route layer whose ANNOUNCE_START layout overlaps this one's +- [Listing and follow](/quest/m1/api-audit/route/events.md) - continuity shows up inside `follow`, not as an event +- [Claim answer epochs](https://github.com/moq-dev/moq/pull/5678) - why a restarted job must never be stitched to its predecessor - [Retired requests](https://github.com/moq-dev/moq/pull/5294) - replacements never substitute content into held handles +- [Routes and announces](/quest/m1/cluster-routing/routes.md) - the route layer whose ANNOUNCE_START layout carries the identity diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index f1b2ae735de..4834fea7683 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -74,7 +74,7 @@ Rejected in planning: ## Required - [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) - Rust, JS, and the bindings resolve a broadcast with `request(path, epoch)` or `follow(path, epoch)`, and every racy two-step caller is gone -- [Routes are the origin API](/quest/m1/api-audit/route/README.md) - apps announce exact or prefix routes through one `Route` handle naming `Instance { identity, epoch }`, prefix routes can serve a held broadcast, and readers get a listing plus `follow` +- [Routes are the origin API](/quest/m1/api-audit/route/README.md) - apps announce exact or prefix routes through one `Route` handle that owns its broadcast and carries an `identity`, prefix routes can serve a held broadcast, and readers get a listing plus `follow` - [Demand is wanted, everywhere](/quest/m1/api-audit/wanted.md) - every `used`/`unused` pair becomes `wanted()` and `wanted_changed()`, and unused ones go - [QMux datagrams obey or refuse their policy](/quest/m1/api-audit/qmux-datagrams.md) - `Session.datagrams` is the DOM interface, its high-water mark is live, and the inert settings throw - [No constructible internal handles](/quest/m1/api-audit/internal-constructors.md) - `Rendition`, `Lister`, `Arrivals`, and e2ee's generations get private constructors, and a lint rule stops new ones diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index 3606950794b..4ed2e08ff57 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -14,7 +14,7 @@ Rust, JS, and every binding: `announced_broadcast`), pinned to `epoch` when given. [Identity and epoch](/quest/m1/api-audit/route/identity.md) later changes the -pin from `epoch` to `Instance { identity, epoch }` in both; the two +pin from `epoch` to an `identity` in both; the two resolutions stay as they are. No caller can assemble a racy two-step resolve, and no crate hand-rolls diff --git a/quest/m1/api-audit/route/README.md b/quest/m1/api-audit/route/README.md index 7c49b36dbc8..43a04315182 100644 --- a/quest/m1/api-audit/route/README.md +++ b/quest/m1/api-audit/route/README.md @@ -2,13 +2,17 @@ ## Goal -An application talks to the origin only in routes, as the wire does. It -announces an exact path or a prefix and holds one `Route` handle. Every -route names its publisher `Instance { identity, epoch }`, and nothing in the -app API is epochless. A prefix route answers each request by serving a -broadcast it already holds or by announcing a per-path route. Readers see a -listing of paths, plus `follow` and `request` for instance changes, instead -of four announce event kinds. Rust, JS, moq-ffi, moq-c and the wrappers +An application talks to the origin only in routes, as the wire does. On the +publishing side, ownership runs origin → route → broadcast → track → group → +frame: a `Route` handle, for an exact path or a prefix, creates and owns +its broadcast. Every route carries an `identity` naming one continuous +stream, and an `epoch` that is private and only orders a single identity's +incarnations. On the read side the chain is origin → route(path, identity) +→ broadcast, and consumers see only the identity. A prefix route answers +each request by serving a broadcast it already holds, or by creating the +path's exact route under its identity. Readers see a listing of paths, plus +`follow` and `request` for identity changes, instead of four announce event +kinds. Rust, JS, moq-ffi, moq-c and the wrappers mirror it. Non-goals: the route layer's wire messages and federation @@ -108,18 +112,48 @@ and every option after it was rejected): - Milestone: ✅ m1 under the API audit; m1 standalone; m2. - The external user's PR offer: ✅ we do all of it; offer them serve. +Second round, the same day. The maintainer asked whether broadcasts should +hang off routes (origin → route → broadcast → track → group → frame). An +audit found the producer side inverted today: the broadcast holds its own +announcer (`rs/moq-net/src/model/broadcast.rs:252-292`). A standalone +broadcast cannot be announced in Rust. A consumer's broadcast, by contrast, +moves between the routes that reach it (`origin.rs:6730`). These decisions +supersede the epoch-minting, pairing and run-uniqueness answers above: + +- Producer ownership: ✅ the route creates and owns its broadcast; pass a + broadcast in. +- Mint point: ✅ per Route, which keeps its identity across withdraw and + re-announce, so js/publish's toggle continues; per announce. +- Read side: ✅ origin → route(path, identity) → broadcast, with only the + identity public; the instance on the consumer; a consumer route handle. + The maintainer added: "we can never stitch broadcasts over two different + identities, only different epochs". The epoch is only a restart + tie-break, relative to its identity, and need not be a clock. moq.pro + records start times itself. +- Epoch change under a reader: the maintainer answered "that would be a + new identity?". So identity is one continuous sequence space, and a + publisher whose sequences restart is a new identity. ✅ Confirmed: the + default is a fresh identity per stream, and a stable identity promises + continued sequences and an increasing epoch. `Instance` and the + hostname advice for pools are dropped. +- Edge minting: ✅ per announcement (the session ID plus the announcement's + ID); per session, which would splice a job restarted on one session. +- Takeover: ✅ re-plan it around identity, where a job's exact route + inherits its claim's identity and ANNOUNCE_TAKEOVER is dropped; keep the + predecessor-ID plan. + The epic owns no work of its own: each child updates the docs it makes stale, including `doc/concept/identity.md`. ## Required - [Serve a held broadcast](/quest/m1/api-audit/route/serve.md) - a prefix route's request can be answered with a broadcast the app already holds, and the first subscribe succeeds on every wire -- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - every route names `Instance { identity, epoch }`, ranked newest within an identity and hashed across identities, with no epochless routes left in the origin -- [One Route handle](/quest/m1/api-audit/route/handle.md) - `Publication`, `Prepared`, `Announcer` and `Requests` become one `Route`, with app options separate from transit facts +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - every route carries an `identity` (one continuous stream) and a private per-identity epoch, ranked newest within an identity and hashed across identities, with no epochless routes left in the origin +- [One Route handle](/quest/m1/api-audit/route/handle.md) - `Publication`, `Prepared`, `Announcer` and `Requests` become one `Route` that owns its broadcast, with app options separate from transit facts - [Listing and follow](/quest/m1/api-audit/route/events.md) - apps read a path listing plus `follow`/`request`, and route metadata moves to a relay-level stream ## Related -- [Announce takeover](/quest/m1/announce-takeover.md) - builds on the identity and handle shapes here +- [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - a job's route inherits its claim's identity, so lite-07 readers keep the first subscribe - [Routes and announces](/quest/m1/cluster-routing/routes.md) - the wire route layer; identity takes over its epochless deletion - [Grant subject](/quest/m1/cluster-routing/grant-subject.md) - key identities that a future public-key `identity` could reuse diff --git a/quest/m1/api-audit/route/events.md b/quest/m1/api-audit/route/events.md index ebb1024ac54..79c81b88d43 100644 --- a/quest/m1/api-audit/route/events.md +++ b/quest/m1/api-audit/route/events.md @@ -23,9 +23,11 @@ and `rs/moq-cli/src/archive.rs:85`. Every JS consumer branches only on moves to `follow`. - The listing yields present and absent per path, with the announcement's - read-only facts. A path that changes instance stays present. To see an - instance change, hold a `follow`. -- `follow` reports the new instance on a restart. It also needs an `End` + read-only facts. A path that changes identity stays present. To see an + identity change, hold a `follow`. +- `follow` yields a new broadcast when the path's identity changes, as the + read side of [Identity and epoch](/quest/m1/api-audit/route/identity.md) + defines (an epoch change within one identity is invisible). It also needs an `End` signal for when the path goes absent, so that `moq_mux::follow::Instances` can fold into it: delete the wrapper's duplicate epoch filter and keep its one-shot fixed mode only if a caller needs it. @@ -43,4 +45,4 @@ none. ## Related -- [Announce takeover](/quest/m1/announce-takeover.md) - its continuity shows up inside `follow`, with no public `Takeover` variant +- [Announce takeover](/quest/m1/announce-takeover.md) - a job's exact route continues its claim's readers inside `follow`, with no public event diff --git a/quest/m1/api-audit/route/handle.md b/quest/m1/api-audit/route/handle.md index 2767609d1e9..ca6999f1fe4 100644 --- a/quest/m1/api-audit/route/handle.md +++ b/quest/m1/api-audit/route/handle.md @@ -2,44 +2,46 @@ ## Goal -An application publishes by announcing a route and holding the `Route` -handle it gets back. `Publication`, `Prepared`, `Announcer`, `Requests` and -`Producer::publish` are gone, in Rust, JS, moq-ffi, moq-c and the wrappers: +On the publishing side, ownership runs origin → route → broadcast → track → +group → frame. An application creates a `Route` on the origin, and the +route creates and owns its broadcast. `Publication`, `Prepared`, +`Announcer`, `Requests` and `Producer::publish` are gone, in Rust, JS, +moq-ffi, moq-c and the wrappers: ```rust -// An exact route serves one broadcast; dropping the route withdraws it. -let broadcast = broadcast::Producer::new(); -broadcast.create_track("catalog", info)?; -let route = origin.announce("live/alice", broadcast, Options::default())?; -route.set_cost(5); // re-prices in place, same instance +// An exact route owns one broadcast; dropping the route withdraws it. +let route = origin.route("live/alice", Options::hidden())?; +route.broadcast().create_track("catalog", info)?; +route.announce(); // visible now, same identity +route.set_cost(5); // re-prices in place +route.withdraw(); // hidden; announce() again continues the same stream // A prefix route serves requests. -let claim = origin.announce_prefix("transcode", Options::default())?; +let claim = origin.route_prefix("transcode", Options::default())?; while let Some(request) = claim.requested().await { - // Either serve a broadcast already held, under the claim's instance... + // Either serve a broadcast already held, under the claim's identity... // request.serve(held); - // ...or announce the path as its own route and instance. - let job = request.announce(broadcast::Producer::new(), Options::default())?; + // ...or create the path's own exact route. + let job = request.route(Options::default())?; spawn(run(job)); } ``` -Apps pass only options: `cost`, `auth`, and an `Instance` override for -re-publishing a run they did not start (a mirror, archive resume, FFI -pass-through). The override grants no more than a minted instance does: -publishing still requires the path's grant, as an explicit epoch does today -through `Route::with_epoch`. Only an app that may already publish the path -can claim continuity with a run on it. Binding identities to keys is the -later public-key option in -[Identity and epoch](/quest/m1/api-audit/route/identity.md). Without the override, `announce` mints a new instance under -the origin's identity on every call, so re-announcing a broadcast is a -restart and never a splice. Hops, via, source and the anonymous mark become -read-only facts on a received announcement; `Hop`, `Hops` and `HopLimit` -leave the public API. - -Non-goals: the instance model ([Identity and epoch](/quest/m1/api-audit/route/identity.md)), +A `Route` mints its identity when it is created and keeps it for its +lifetime, across withdraw, re-announce and reconnects, because it owns the +same broadcast and its sequences continue. A new run is a new `Route`. Apps +pass only options: visibility at creation, `cost`, `auth`, and a stable +`identity` for a publisher that keeps its sequence space across restarts +(see [Identity and epoch](/quest/m1/api-audit/route/identity.md)). Setting +an identity grants no more than a minted one does: publishing still +requires the path's grant. Hops, via, source and the anonymous mark become +read-only facts on a received announcement, and `Hop`, `Hops` and +`HopLimit` leave the public API. + +Non-goals: the identity model ([Identity and epoch](/quest/m1/api-audit/route/identity.md)), announce events ([Listing and follow](/quest/m1/api-audit/route/events.md)), -and the route layer's wire metric ([Routes and announces](/quest/m1/cluster-routing/routes.md)). +the read side, which identity owns, and the route layer's wire metric +([Routes and announces](/quest/m1/cluster-routing/routes.md)). ## Plan @@ -47,39 +49,55 @@ Decided 2026-10-30 (maintainer); see the [epic](/quest/m1/api-audit/route/README The names above are a sketch. Settle the final ones in the PR, keeping Rust, JS and the bindings identical. -- **One type.** An exact route derefs to the `broadcast::Producer` it - serves. A prefix route yields requests. Each request is answered by - `serve(consumer)` (from [serve](/quest/m1/api-audit/route/serve.md)), - by `announce(broadcast, options)`, which returns that path's exact - `Route`, or by `reject`. A prefix route takes cost and auth just as an - exact one does, so claims can be priced. Today `Requests::route()` is - always the default and `update_route` is crate-private. -- **No unannounced state.** Today's `create_broadcast`-then-`announce` - callers become a plain `broadcast::Producer` that is announced once it - is ready. They are: catalog first (`moq-cli` hls, rtsp and publish; - moq-studio; moq-mux `ts/programs.rs`), announce after SDP - (`moq-rtc/server/whip.rs`), and js/publish's on/off toggle. -- **Sessions.** Relay forwarding keeps its crate-private construction with - forwarded instance, hops and cost, which the deleted `requests_route` - and `dynamic_route` did. `moq_net::fuzz`'s hatches shrink to what tests - still need. +- **The route owns the broadcast.** `route.broadcast()` returns the + `broadcast::Producer` that the 18 library entry points already take + (`moq-mux` catalog and importers, `moq-hls` import, the `moq-rtc` codecs, + `moq-room` chat, `moq-boy` status). Today the broadcast holds its own + announcer (`rs/moq-net/src/model/broadcast.rs:252-292`, and + `js/net/src/broadcast.ts:391`). That inversion goes: the broadcast knows + nothing of routes, and `broadcast::Producer::announce`/`unannounce`/ + `route` are removed. A standalone `broadcast::Producer` stays for + in-process pipelines and tests. It can only be published through a + prefix route's `serve`, as today, where a standalone broadcast cannot be + announced. +- **Prefix routes.** A prefix route yields requests, and each one is + answered by `serve(consumer)` (from [serve](/quest/m1/api-audit/route/serve.md)), + by `route(options)`, or by `reject`. `route(options)` creates the path's + exact `Route`, which inherits the prefix route's identity by default so + that the reader continues (see [announce takeover](/quest/m1/announce-takeover.md)). + A prefix route takes cost and auth as an exact one does, so claims can + be priced. Today `Requests::route()` is always the default and + `update_route` is crate-private. +- **Visibility, not unannounced broadcasts.** Callers that fill the catalog + first (`moq-cli` hls, rtsp and publish; moq-studio; moq-mux + `ts/programs.rs`) or announce after SDP (`moq-rtc/server/whip.rs`) create + the route hidden and announce it when ready. js/publish's on/off toggle + becomes withdraw and announce on one route, so viewers continue rather + than restart. +- **Sessions.** Relay forwarding keeps a crate-private construction with + forwarded identity, epoch, hops and cost, which the deleted + `requests_route` and `dynamic_route` did. `moq_net::fuzz`'s hatches + shrink to what tests still need. - **JS leaks.** Removing `Requests`/`requestsRoute`/`updateRoute` also removes their `@internal`-but-public exposure on `Table`. Stop exporting `Epoch.toBytes`/`fromBytes`, `RequestSlot` and `RouteEntry`, and delete the orphaned `@internal` doc blocks (`js/net/src/origin.ts:2160-2176`). -- **Bindings.** moq-ffi's `MoqRoute`/`MoqPublication`/ - `MoqBroadcastRequest`/`MoqBroadcastPrepared`, moq-c's `moq_origin_requests`, - `moq_broadcast_request_*`, `moq_broadcast_prepared_*`, `moq_publication_*` - and `moq_mint_epoch`, and the py/kt/swift/dart/go wrappers all move to - the route handle. [moq-c's API gaps](/quest/m1/c/api-gaps.md) error-code - fix applies to whichever functions remain. +- **Bindings.** These all move to the route handle: + - moq-ffi's `MoqRoute`, `MoqPublication`, `MoqBroadcastRequest` and + `MoqBroadcastPrepared`. + - moq-c's `moq_origin_requests`, `moq_broadcast_request_*`, + `moq_broadcast_prepared_*`, `moq_publication_*` and `moq_mint_epoch`. + - The py, kt, swift, dart and go wrappers. + + [moq-c's API gaps](/quest/m1/c/api-gaps.md) error-code fix applies to + whichever functions remain. - **Callers.** Migrate every caller: about 25 crates use `create_broadcast` or `publish`, about 19 set an epoch, plus `@moq/publish`, moq-boy, carla and the e2ee generations. The rs/moq-net and js/net `MIGRATE.md` entries and the PR's Impact section give the mapping, including moq.pro's `.dash` claim and sync-ingest mirror. - **Docs.** Update `doc/concept/identity.md`'s publishing and lazy-job - examples, `doc/lib/rs`, `doc/lib/js` and `doc/lib/c`, and each binding's + examples, `doc/lib/rs`, `doc/lib/js`, `doc/lib/c`, and each binding's README. Run `just check` and `just test interop --all`. @@ -89,7 +107,7 @@ wrappers. Wire: none. ## Required -- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - the instance the handle's options and minting name +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - the identity a route mints and keeps - [Serve a held broadcast](/quest/m1/api-audit/route/serve.md) - the served answer this handle carries over ## Related diff --git a/quest/m1/api-audit/route/identity.md b/quest/m1/api-audit/route/identity.md index af004b3af5c..ca03060b76b 100644 --- a/quest/m1/api-audit/route/identity.md +++ b/quest/m1/api-audit/route/identity.md @@ -2,23 +2,34 @@ ## Goal -Every route in an origin names its publisher `Instance { identity, epoch }`: -`identity` is a string naming the publisher, and `epoch` is when this run -started. The UUIDv7 `Epoch` is retired, and the origin no longer holds any -epochless route. A route resolving a path is chosen like this: +Every route in an origin carries an `identity`, a string naming one +continuous stream at its path. Within an identity, group sequences never +restart and never name two different groups, so readers can stitch across +any routes and incarnations that share it. Different identities are +independent streams that are never stitched together. Each route also +carries an `epoch`: an opaque counter that increases within its identity +and is never compared across identities. It only picks the live +incarnation when stale routes linger. The UUIDv7 `Epoch` is retired, and +the origin holds no route without an identity. + +A route resolving a path is chosen like this: 1. The most specific prefix wins. -2. Within one identity, only its newest epoch is eligible. An identity - publishes one run per path at a time, so a reconnect supersedes its - stale route at once, even when that route is cheaper. +2. Within one identity, only its highest epoch is eligible, even over a + cheaper route. Readers continue across an epoch change without a seam, + because the sequence space continues. 3. Among different identities, the order is link preference, then cost, then a broadcast published on this origin, then hop length, then a hash of the identity and the full requested path. Relays agree on the result, and paths spread over a pool's hosts. -4. Routes with equal identity and epoch are one run, so a reader resumes - across them without a seam. -Non-goals: moq-transport identity (it carries none, +On the read side, the chain is origin → route(path, identity) → broadcast. +`request(path)` resolves one identity and returns its broadcast. Moving to +another identity, such as a pool failover or a redundant-ingest switch, +ends that broadcast, and `follow` yields the next one. Consumers, pins and +catalog references see only the identity; the epoch is never public. + +Non-goals: carrying identity over moq-transport (it carries none, [decided 2026-10-28](/quest/m1/ietf-epoch-cut.md)), public-key identities (a later option), and the route-handle API shape ([One Route handle](/quest/m1/api-audit/route/handle.md)). @@ -28,73 +39,76 @@ Non-goals: moq-transport identity (it carries none, Decided 2026-10-30 (maintainer); every prompt is in the [epic](/quest/m1/api-audit/route/README.md). -- **Types.** In `rs/moq-net`, `Identity` (string) and `Epoch` (start time - in microseconds, monotonic within a process) together form `Instance`. - Rename the internal `Instance`/`Resolution` types out of the way. Mirror - in `js/net`, moq-ffi, moq-c and the wrappers. `request(path, instance)`, - `follow`, catalog references and archive keys pin an `Instance`. -- **Default identity.** It is random, minted once per process (per origin - in JS) and kept for that process's lifetime, so reconnects within the - process supersede their own stale routes. A process restart is a new - identity until its old route is withdrawn. A stable identity orders its - runs by wall-clock start time, as UUIDv7 epochs do today. If a restart's - clock rolls back, or lands on an equal epoch, the stale route keeps - winning until it is withdrawn, and never splices: an equal epoch from a - restarted process is refused as a conflicting copy, as differing track - info is today ([moq-dev/moq#6460](https://github.com/moq-dev/moq/pull/6460)). - Test both cases. Services set a stable one - (`--identity` on the CLI and relay, an origin config field in the - libraries), for example a hostname. The default is never a hostname, - since routes reach every relay and subscriber. -- **Pools.** A pool is several hosts with distinct identities on one - prefix: transcoders, or moq.pro's three `.dash` control nodes. Step 3 +- **Types.** In `rs/moq-net`, add `Identity` (a string) and keep `epoch` as + a crate-private `u64` on routes. Replace `broadcast::Info.epoch` and JS + `Broadcast.Consumer.epoch` with `identity()`. `request(path, identity)`, + `follow(path, identity)`, catalog references and archive keys pin an + identity. Rename the internal `Instance`/`Resolution` types if they + confuse. Mirror this in `js/net`, moq-ffi, moq-c and the wrappers. +- **Default identity.** Random, minted for each new stream, so a publisher + that restarts its sequences can never be stitched to its old run. A + [Route](/quest/m1/api-audit/route/handle.md) mints it when created and + keeps it, with epoch 0, while it is withdrawn and re-announced or + reconnects, since its sequences continue. +- **Stable identity.** A publisher may set its own identity (`--identity` + on the CLI, an option on the route) only if it continues the sequence + space across restarts and announces a higher epoch each time, for + example a counter persisted on disk. Nothing assumes the epoch is a + clock. Document the promise and the cost of breaking it (spliced groups) + wherever the option is documented. +- **Pools.** Several hosts on one prefix, such as transcoders or moq.pro's + three `.dash` control nodes, each have their own identities, and step 3 spreads paths over them. A host that is full withdraws its route (a leaky bucket); a crashed host's route goes when its session closes or - drains. Document this pattern in `doc/concept/identity.md`, replacing - the epochless-claim lifecycle. + drains. Document this in `doc/concept/identity.md`, replacing the + epochless-claim lifecycle. - **Wire, lite-07-wip.** Announcements carry `identity` and `epoch` as two - explicit fields in place of the UUIDv7 epoch, and requests that pin an - instance carry both. Update `drafts/` (the lite draft's announce and - epoch sections) and `doc/concept/moq-lite.md`. Released versions keep - their framing. lite-06 and older read the old field. Account for it - wherever lite-07 epochs flow today: announce IDs, compression bases, - snapshots and route filtering. -- **Minting off the wire.** A session that receives a route with no - identity mints one for it: identity = the session ID, epoch = when the - route arrived. This covers moq-transport, older lite and third-party - peers. The origin then holds no epochless route. A pool reached through - an older-lite relay hop can pick different winners per relay + explicit fields in place of the UUIDv7 epoch, and requests that pin carry + the identity. Update `drafts/` (the lite draft's announce and epoch + sections) and `doc/concept/moq-lite.md`. Released versions keep their + framing. Account for the change wherever lite-07 epochs flow today: + announce IDs, compression bases, snapshots and route filtering. +- **Minting off the wire.** A session mints an identity for each route it + receives without one: the session ID plus that announcement's ID, with + epoch 0. This covers moq-transport, older lite and third-party peers, and + the origin then holds no route without an identity. A re-announcement is + a new identity, so a job restarting on the same session is never spliced + to its predecessor ([moq-dev/moq#5678](https://github.com/moq-dev/moq/pull/5678)'s + bug). moq-transport keeps the cold-start reset. A pool reached through an + older-lite relay hop can pick different winners per relay ([moq-dev/moq#6948](https://github.com/moq-dev/moq/pull/6948)'s objection), which is accepted because m1 prefers lite-07 between relays. - The objection does not apply otherwise: newest-wins only compares epochs - within one identity, so mint order never outranks cost or preference. -- **Delete the epochless machinery.** `Instance::Route(generation)` and - its renewals, `restarted_since`, the held-restart Release for epochless - routes, Selection retirement, and the epochless refusal from + Elsewhere the objection is gone: epochs are compared only within one + identity, so mint order never outranks cost or preference. +- **Delete the epochless machinery.** That is `Instance::Route(generation)` + and its renewals, `restarted_since`, the held-restart Release for + epochless routes, Selection retirement, and the epochless refusal from [moq-dev/moq#6816](https://github.com/moq-dev/moq/pull/6816). This replaces that part of [Routes and announces](/quest/m1/cluster-routing/routes.md) (decided there 2026-10-27). - **Docs.** Rewrite `doc/concept/identity.md`'s identity, selection-order and lazy-job sections to the rule above, so the guide, the - `Consumer::request` rustdoc and the `Route` docs give one order, with - specificity first. Also update `doc/setup/redundancy.md` (a redundant - pair is two identities), `doc/bin/cli.md` ("Publisher runs" and - `--epoch`, which becomes `--identity`) and `doc/bin/relay/config.md`. + `Consumer::request` rustdoc and the route docs give one order, with + specificity first. Update `doc/setup/redundancy.md` (a redundant pair is + two identities), `doc/bin/cli.md` ("Publisher runs", and `--epoch`, which + becomes `--identity`) and `doc/bin/relay/config.md`. - **moq.pro.** Recording resume compares `routeEpoch` (`api/src/recording.ts`), and recordings are keyed `/@/...`. - The Impact section says how to key on `Instance` instead, for moq.pro's - bump. -- **Tests.** Cover a reconnect superseding its stale route across a - cheaper path; two identities hashing per path; same-instance resume - across two relays; a host withdrawing when full; minting at a - moq-transport and a lite-06 ingest; and archive and catalog pins. Update - every epoch fixture. Run `just check`, `just test interop --all` and + The Impact section says to key on identity and record the start time on + moq.pro's side, for moq.pro's bump. +- **Tests.** Cover a higher epoch superseding a cheaper stale route of the + same identity; a reader continuing across an epoch change; two identities + hashing per path; a failover to another identity ending the broadcast and + `follow` yielding the next; a host withdrawing when full; per-announcement + minting at a moq-transport and a lite-06 ingest, including a job + re-announced on one session; and archive and catalog pins. Update every + epoch fixture. Run `just check`, `just test interop --all` and `just drafts check`. Any compat cell that asserted UUID epochs gets a planned break in `test/interop/compat/planned-breaks.json`. -Public API: breaking. `Epoch` becomes the start-time half of `Instance`, -and `Route::with_epoch` gives way to the handle's options. Wire: lite-07-wip -announce and request fields change; released versions are unchanged. +Public API: breaking. `Epoch` leaves the public API and `Identity` takes its +place in pins and on consumers. Wire: lite-07-wip announce and request +fields change; released versions are unchanged. ## Related diff --git a/quest/m1/api-audit/route/serve.md b/quest/m1/api-audit/route/serve.md index a160bf02094..2f00e95cce1 100644 --- a/quest/m1/api-audit/route/serve.md +++ b/quest/m1/api-audit/route/serve.md @@ -5,7 +5,7 @@ An application answering a prefix route's request can hand over a broadcast it already holds: `request.serve(consumer)` in Rust and `request.serve(broadcast)` in JS, mirrored in moq-ffi, moq-c and the -wrappers. The answer is served under the prefix route's own instance and +wrappers. The answer is served under the prefix route's own identity and announces no exact route. A client's first subscribe through it succeeds over moq-transport-18, moq-transport-22, moq-lite-06 and moq-lite-07-wip. @@ -26,10 +26,13 @@ before the larger rework. `compile_fail,E0624` doctest with usage docs. In JS, expose `#accept` as `serve` and drop `hooks.acceptRequest` if nothing else needs it. - Contract, in rustdoc and `doc/concept/identity.md`: a served answer is - the prefix route's instance. To restart a served path with different - bytes, re-announce the route rather than serving new bytes under it. A - job that may restart per path answers with `prepare`/`publish`, and takes - the cold-start reset. + part of the prefix route's stream at that path. Today that means its + instance; after [Identity and epoch](/quest/m1/api-audit/route/identity.md), + its identity, which promises one continuous sequence space per path. To + serve different bytes at a path that was already served, start a new + prefix route rather than serving new bytes under the old one. A job that + may restart per path answers with `prepare`/`publish`, and takes the + cold-start reset until [announce takeover](/quest/m1/announce-takeover.md). - Served-answer cache: an answer that `prepare`/`publish` stored in the prefix route's served cache must not serve a later request once its exact route is withdrawn. Check `ServeState`'s cache on withdrawal, fix diff --git a/quest/m1/cluster-routing/routes.md b/quest/m1/cluster-routing/routes.md index d7c53924481..383d07b87d0 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -35,7 +35,8 @@ The handoff contract below, decided 2026-10-16, settles claim freshness: permission to stitch. A concrete serving-route change without an epoch remains Restart even when the origin node is unchanged; only a matching explicit epoch or the separately proven Takeover operation preserves an - instance. Test a same-origin next-hop change with no epoch. + instance (superseded 2026-10-30: a shared `identity` preserves it, per + [Identity and epoch](/quest/m1/api-audit/route/identity.md)). Test a same-origin next-hop change with no epoch. ANNOUNCE_UPDATE re-prices it and ANNOUNCE_END withdraws this origin's claim while the route stays up. A wildcard claim is capability, not an inventory of broadcasts; another origin may still serve the same epoch. An announce @@ -673,11 +674,11 @@ ranking a minted epoch last keeps the renewal it was meant to delete. Moved 2026-10-30 (maintainer, the [route epic](/quest/m1/api-audit/route/README.md)): [Identity and epoch](/quest/m1/api-audit/route/identity.md) now deletes that epochless machinery, so this quest no longer does. A session mints -`Instance { identity, epoch }` for any route that arrives without one, and -newest-wins compares epochs only within one identity, so mint order no -longer outranks cost or preference. The rest of the 2026-10-27 decision -stands. Build the route layer's identity fields on that `Instance` instead of -the UUIDv7 epoch. +an `identity` (the session ID plus the announcement's ID) for any route that +arrives without one, and newest-wins compares epochs only within one +identity, so mint order no longer outranks cost or preference. The rest of +the 2026-10-27 decision stands. Build the route layer's identity fields on +that identity and per-identity epoch instead of the UUIDv7 epoch. Decided 2026-10-27 (maintainer), from [grant subject](https://github.com/moq-dev/moq/pull/6992): decide what key diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 0ce44d7c2ef..253940808c1 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -108,7 +108,7 @@ timestamp bound in [#6168](https://github.com/moq-dev/moq/pull/6168). - [Remove FETCH from lite-07](/quest/m1/subscribe-ranges/lite07-fetch.md) - lite FETCH is gone from lite-07, in Rust and JS - [Lite-07 by start](/quest/m1/time-addressing/lite07.md) - lite-07 carries group starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers - [@moq/net by start](/quest/m1/time-addressing/js.md) - JS speaks the same lite-07 wire -- [Announcement takeover](/quest/m1/announce-takeover.md) - ANNOUNCE_TAKEOVER preserves a proven instance under a new independent route +- [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - the job's route inherits the claim's identity, with no new wire message ## Related From dc300c9781ef5835287c4997b39f10550bb8a150 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 14:24:52 -0700 Subject: [PATCH 4/5] quest: keep publisher identity apart from route-layer node identity Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/route/identity.md | 5 ++++- quest/m1/cluster-routing/routes.md | 7 +++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/quest/m1/api-audit/route/identity.md b/quest/m1/api-audit/route/identity.md index ca03060b76b..87a754f6bd1 100644 --- a/quest/m1/api-audit/route/identity.md +++ b/quest/m1/api-audit/route/identity.md @@ -55,7 +55,10 @@ Decided 2026-10-30 (maintainer); every prompt is in the space across restarts and announces a higher epoch each time, for example a counter persisted on disk. Nothing assumes the epoch is a clock. Document the promise and the cost of breaking it (spliced groups) - wherever the option is documented. + wherever the option is documented. This publisher identity is not + [Routes and announces](/quest/m1/cluster-routing/routes.md)'s origin-node + identity, whose seqno and revision are route-layer state. A restarted + relay node still takes a fresh node identity there. - **Pools.** Several hosts on one prefix, such as transcoders or moq.pro's three `.dash` control nodes, each have their own identities, and step 3 spreads paths over them. A host that is full withdraws its route (a diff --git a/quest/m1/cluster-routing/routes.md b/quest/m1/cluster-routing/routes.md index 383d07b87d0..5dfbec234d1 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -677,8 +677,11 @@ epochless machinery, so this quest no longer does. A session mints an `identity` (the session ID plus the announcement's ID) for any route that arrives without one, and newest-wins compares epochs only within one identity, so mint order no longer outranks cost or preference. The rest of -the 2026-10-27 decision stands. Build the route layer's identity fields on -that identity and per-identity epoch instead of the UUIDv7 epoch. +the 2026-10-27 decision stands. The broadcast epoch fields here become that +publisher identity and its per-identity epoch, in place of the UUIDv7 +epoch. The route layer's own origin-node identity, with its seqno and +revision, stays separate ("keep administrative identity and broadcast epoch +separate", above). Decided 2026-10-27 (maintainer), from [grant subject](https://github.com/moq-dev/moq/pull/6992): decide what key From 25ed72c132997941ab8e85fd94c66e51576acaff Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 22:01:30 -0700 Subject: [PATCH 5/5] quest: plan the route epic follow-ups FollowOptions and percent-encoded identities in m1, a moq-room benchmark in m2; fold a route identity getter, the epoch rename sweep and the interop formatting into their quests. Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/resolve/README.md | 1 + quest/m1/api-audit/resolve/follow-options.md | 26 ++++++++++++++++++ quest/m1/api-audit/route/README.md | 1 + quest/m1/api-audit/route/events.md | 2 ++ quest/m1/api-audit/route/handle.md | 3 ++- quest/m1/api-audit/route/identity-encoding.md | 27 +++++++++++++++++++ quest/m1/api-audit/route/identity.md | 2 ++ quest/m2/README.md | 1 + quest/m2/room-bench.md | 25 +++++++++++++++++ 9 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 quest/m1/api-audit/resolve/follow-options.md create mode 100644 quest/m1/api-audit/route/identity-encoding.md create mode 100644 quest/m2/room-bench.md diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index 4ed2e08ff57..64fac8d07bd 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -59,6 +59,7 @@ Wire: none. - [The player takes any read-side origin](/quest/m1/api-audit/resolve/watch-origin.md) - `@moq/watch`'s `Player` and `Broadcast` accept a read-only `Origin.Consumer` as well as a `Table` - [The carla demo pins its driver epoch](/quest/m1/api-audit/resolve/callers.md) - the demo's driver watcher requests each run pinned to its announced epoch - [JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md) - `follow` and `request` get their own JS types, matching Rust and the bindings +- [JS follow takes FollowOptions](/quest/m1/api-audit/resolve/follow-options.md) - `follow` and `request` get their own JS options types ## Related diff --git a/quest/m1/api-audit/resolve/follow-options.md b/quest/m1/api-audit/resolve/follow-options.md new file mode 100644 index 00000000000..6ef60260c0d --- /dev/null +++ b/quest/m1/api-audit/resolve/follow-options.md @@ -0,0 +1,26 @@ +# [S] JS follow takes FollowOptions + +## Goal + +In `@moq/net`, `Origin.Consumer.follow` (and the `Producer` and `Table` +passthroughs) takes its own `FollowOptions`, and `request` keeps +`RequestOptions`. Each options type documents only what its method does. +Every caller in `js/` compiles against the split, and the API report is +regenerated. + +## Plan + +Planned 2026-10-31 (`/quest-plan`, maintainer), a follow-up from +[JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md), +which split the return types but kept one `RequestOptions` for both +methods. Keep the shared fields' names. Drop a field from `FollowOptions` +only if `follow` ignores it today, and say which in the PR. If the two +types still end up identical, a shared base with two aliases is fine; the +point is that each method's docs describe one behavior. + +Public API: breaking for TypeScript type annotations that name +`RequestOptions` for a `follow` call. Wire: none. + +## Required + +- [JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md) - the `Following` return type this finishes diff --git a/quest/m1/api-audit/route/README.md b/quest/m1/api-audit/route/README.md index 43a04315182..8ca8a15666b 100644 --- a/quest/m1/api-audit/route/README.md +++ b/quest/m1/api-audit/route/README.md @@ -150,6 +150,7 @@ stale, including `doc/concept/identity.md`. - [Serve a held broadcast](/quest/m1/api-audit/route/serve.md) - a prefix route's request can be answered with a broadcast the app already holds, and the first subscribe succeeds on every wire - [Identity and epoch](/quest/m1/api-audit/route/identity.md) - every route carries an `identity` (one continuous stream) and a private per-identity epoch, ranked newest within an identity and hashed across identities, with no epochless routes left in the origin - [One Route handle](/quest/m1/api-audit/route/handle.md) - `Publication`, `Prepared`, `Announcer` and `Requests` become one `Route` that owns its broadcast, with app options separate from transit facts +- [Identities are percent-encoded in paths](/quest/m1/api-audit/route/identity-encoding.md) - HLS URLs and archive keys round-trip any stable identity - [Listing and follow](/quest/m1/api-audit/route/events.md) - apps read a path listing plus `follow`/`request`, and route metadata moves to a relay-level stream ## Related diff --git a/quest/m1/api-audit/route/events.md b/quest/m1/api-audit/route/events.md index 79c81b88d43..6ecaf63651b 100644 --- a/quest/m1/api-audit/route/events.md +++ b/quest/m1/api-audit/route/events.md @@ -33,6 +33,8 @@ moves to `follow`. its one-shot fixed mode only if a caller needs it. - `routes()` lives on the origin consumer for relays and stats, and is hidden from the app-level docs. +- Format the go and python interop clients while touching them (two lines + were already unformatted on 2026-10-30). - Bindings: replace `MoqAnnounceEvent`'s variants, and the go and python interop clients' and carla `publish.py:303-340`'s Restart handling, with the listing plus `follow`. diff --git a/quest/m1/api-audit/route/handle.md b/quest/m1/api-audit/route/handle.md index ca6999f1fe4..8f3fc272d48 100644 --- a/quest/m1/api-audit/route/handle.md +++ b/quest/m1/api-audit/route/handle.md @@ -34,7 +34,8 @@ pass only options: visibility at creation, `cost`, `auth`, and a stable `identity` for a publisher that keeps its sequence space across restarts (see [Identity and epoch](/quest/m1/api-audit/route/identity.md)). Setting an identity grants no more than a minted one does: publishing still -requires the path's grant. Hops, via, source and the anonymous mark become +requires the path's grant. A route exposes its own identity (`route.identity()`), so the OBS dock can +show it again. Hops, via, source and the anonymous mark become read-only facts on a received announcement, and `Hop`, `Hops` and `HopLimit` leave the public API. diff --git a/quest/m1/api-audit/route/identity-encoding.md b/quest/m1/api-audit/route/identity-encoding.md new file mode 100644 index 00000000000..966c58e44cb --- /dev/null +++ b/quest/m1/api-audit/route/identity-encoding.md @@ -0,0 +1,27 @@ +# [XS] Identities are percent-encoded in paths + +## Goal + +Wherever an identity becomes a URL or storage path segment (moq-hls's HLS +URLs and the archive's recording keys, `/@`), it is +percent-encoded as one segment and decoded on the way back. A stable +identity containing `/`, `?`, `%` or `#` round-trips, and one test per +surface proves it. + +## Plan + +Planned 2026-10-31 (`/quest-plan`, maintainer), a follow-up reported by the +[Identity and epoch](/quest/m1/api-audit/route/identity.md) implementation. +Minted identities (`~` plus random bits) are URL-safe, so only a stable +identity set by a publisher can break these paths today. Reuse the +percent-encoding the archive already applies to track names (see +[archives](/quest/m1/archive/README.md)) rather than adding a second +scheme. List any other surface that embeds an identity, found with +`git grep`, in the PR. + +Public API: none. Wire: none. Existing keys stay readable, since minted +identities encode to themselves. + +## Required + +- [Identity and epoch](/quest/m1/api-audit/route/identity.md) - the identity these paths embed diff --git a/quest/m1/api-audit/route/identity.md b/quest/m1/api-audit/route/identity.md index 87a754f6bd1..281c50d63bd 100644 --- a/quest/m1/api-audit/route/identity.md +++ b/quest/m1/api-audit/route/identity.md @@ -45,6 +45,8 @@ Decided 2026-10-30 (maintainer); every prompt is in the `follow(path, identity)`, catalog references and archive keys pin an identity. Rename the internal `Instance`/`Resolution` types if they confuse. Mirror this in `js/net`, moq-ffi, moq-c and the wrappers. + Rename tests and variables that still say `epoch` where they mean the + identity. - **Default identity.** Random, minted for each new stream, so a publisher that restarts its sequences can never be stitched to its old run. A [Route](/quest/m1/api-audit/route/handle.md) mints it when created and diff --git a/quest/m2/README.md b/quest/m2/README.md index ebfc42924ec..f85f6e75c34 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -102,6 +102,7 @@ lite-07; bitrate enforcement is not part of this release. - [Flatten nested Options](/quest/m2/nested-options.md) - three moq-net functions stop building `Option>`, so the TS translation reaches them - [Fewer allocations in announce fan-out](/quest/m2/announce-fanout-allocs.md) - a deep path costs no more allocations per subscriber than a shallow one - [Keyed prefix polling](/quest/m2/keyed-prefix-polling.md) - `SubscriberDriver` polls only the prefixes a wake concerns, if a bench shows the slope +- [moq-room scales to large rooms](/quest/m2/room-bench.md) - a benchmark measures `Room` with large participant counts, and polling narrows only if it shows a slope - [Route health](/quest/m2/route-health/README.md) - epoch-only active/passive track recovery over metadata-only subscriptions - [Wrapper traits over moq-net](/quest/m2/net-wrap/README.md) - moq-net exports producer and consumer traits, and every writer and reader above it takes them, so a wrapper such as e2ee passes through unchanged - [E2EE](/quest/m2/e2ee/README.md) - TypeScript and Rust peers interoperate over encrypted broadcasts no relay can decrypt diff --git a/quest/m2/room-bench.md b/quest/m2/room-bench.md new file mode 100644 index 00000000000..0c713c3fede --- /dev/null +++ b/quest/m2/room-bench.md @@ -0,0 +1,25 @@ +# [S] moq-room scales to large rooms + +## Goal + +A benchmark measures `moq-room`'s `Room` with large participant counts +(for example 10, 100 and 1,000 followed paths), covering the cost of one +participant's change and of steady-state wakes. If the cost grows with room +size per wake, the room polls only the followers a wake concerns, and the +benchmark shows the change. + +## Plan + +Planned 2026-10-31 (`/quest-plan`, maintainer), a follow-up reported by the +[Listing and follow](/quest/m1/api-audit/route/events.md) implementation: +`Room` now holds a follower per listed path and polls every follower on each +wake, which is fine at room sizes seen today. Benchmark first, as +[Keyed prefix polling](/quest/m2/keyed-prefix-polling.md) does, and fix +only if it shows a slope. Wire the benchmark into the existing bench lanes +([Benchmark sources](/quest/m2/bench-sources.md)). + +Public API: none. Wire: none. + +## Required + +- [Listing and follow](/quest/m1/api-audit/route/events.md) - the follower-per-path room this measures