From 5751e65ef95e0501769ee786b809ec5bdcf6cd78 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:46:05 -0800 Subject: [PATCH 1/3] chore(quest): claim quest/m1/api-audit/route/handle.md Quest-Claim: ed6f29e8e04accb8 From 12a7cb667bf104026035f1868da1c2fcab942600 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:59:45 -0800 Subject: [PATCH 2/3] docs(quest): record Route job-retirement decision Co-Authored-By: GPT-6.1 Sol --- quest/m1/api-audit/route/handle.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/quest/m1/api-audit/route/handle.md b/quest/m1/api-audit/route/handle.md index 2df9273eb47..dd223c3ff20 100644 --- a/quest/m1/api-audit/route/handle.md +++ b/quest/m1/api-audit/route/handle.md @@ -106,6 +106,24 @@ 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. +## Waiting + +- Maintainer: choose the default when a job ends and the same prefix serves its + path again. The inherited-instance default above would reuse the ended job's + instance even though its group sequences restart. The dependent + [takeover quest](/quest/m1/announce-takeover.md) requires a fresh instance and + refusal of pins to the ended job before relying on inheritance. Recommend + making `request.route(options)` mint a fresh instance by default, with an + explicit stable instance only for callers that continue its sequences; + keep the existing predecessor handling until that quest replaces it. + Alternatively, preserve the inherited default by making the prefix terminal + when a materialized job ends, requiring a new prefix route for later jobs. + Keeping both an immutable prefix instance and automatic per-path restarts + needs an ownership bound for ended-path history: serial requests must not + leave a growing tombstone map. Resolve the default and its safety scope before + migrating the public API. See + [the implementation audit](https://github.com/moq-dev/moq/pull/7770). + ## Related - No constructible internal handles - the same JS hygiene rule From 7e43fe0a7fefe81df2f3c2e8a8f88089e6dc7f9f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 17:13:16 -0800 Subject: [PATCH 3/3] docs(quest): decide a job's Route mints a fresh instance by default Record the maintainer's 2026-11-03 decision on One Route handle and update announce takeover, which assumed handle inherited the prefix route's instance. Co-Authored-By: Claude Opus 5.5 --- quest/m1/announce-takeover.md | 18 ++++++++----- quest/m1/api-audit/route/handle.md | 42 ++++++++++++++---------------- 2 files changed, 31 insertions(+), 29 deletions(-) diff --git a/quest/m1/announce-takeover.md b/quest/m1/announce-takeover.md index e7f7a7618ca..c9db540f92d 100644 --- a/quest/m1/announce-takeover.md +++ b/quest/m1/announce-takeover.md @@ -58,11 +58,17 @@ this quest removes the predecessor machinery and grows to [XL]. `lite/announce.ts` and `lite/subscriber.ts`. Remove the takeover sections from `drafts/draft-lcurley-moq-lite.md`, `doc/concept/identity.md` and `doc/concept/moq-lite.md`. -- **Inheriting the instance.** `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 instance by default, and the - answer it gives the waiting request is that route's broadcast. A job - that serves a held broadcast through `Request::serve` +- **Inheriting the instance.** Decided 2026-11-03 (maintainer, on + [moq-dev/moq#7770](https://github.com/moq-dev/moq/pull/7770)): + `request.route(options)` from + [One Route handle](/quest/m1/api-audit/route/handle.md) mints a fresh + instance by default, and ending a job leaves its prefix route open, with + no history of ended paths. Carrying the prefix route's instance onto the + path's exact route, so that the answer the waiting request gets is that + route's broadcast, is this quest's change, and it must keep those + properties: a restarted job still gets a fresh instance, and job + lifetimes stay independent without per-path history of ended jobs. + A job that serves a held broadcast through `Request::serve` never announces an exact route, so it needs none of this. - **One stream per path and instance.** A claim may answer a path under its instance only while that stream is live. Once the job's route ends, @@ -144,7 +150,7 @@ beyond [Instance and epoch](https://github.com/moq-dev/moq/pull/7489)'s fields. ## Required -- [One Route handle](/quest/m1/api-audit/route/handle.md) - `request.route` creates the exact route under the claim's instance +- [One Route handle](/quest/m1/api-audit/route/handle.md) - `request.route` creates the path's exact route, minting a fresh instance by default ## Related diff --git a/quest/m1/api-audit/route/handle.md b/quest/m1/api-audit/route/handle.md index dd223c3ff20..adf63a37a88 100644 --- a/quest/m1/api-audit/route/handle.md +++ b/quest/m1/api-audit/route/handle.md @@ -64,11 +64,25 @@ JS and the bindings identical. - **Prefix routes.** A prefix route yields requests, and each one is answered by `serve(consumer)`, by `route(options)`, or by `reject`. `route(options)` creates the path's - exact `Route`, which inherits the prefix route's instance 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. + exact `Route`. 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. +- **A job's instance.** ✅ Decided 2026-11-03 (maintainer, on + [moq-dev/moq#7770](https://github.com/moq-dev/moq/pull/7770)): + `request.route(options)` mints a fresh instance by default, as + `Request::prepare` does today, so a job that ends and restarts beneath + the same prefix gets a new instance for its restarted sequences. An + explicit stable instance in the options is only for a caller that + continues its sequences. Ending a job's route withdraws only that path: + the prefix route stays open and keeps answering later requests, each + with its own job lifetime, and the origin keeps no history of ended + paths. The existing predecessor handling stays until + [announce takeover](/quest/m1/announce-takeover.md) replaces it, and + that quest owns continuing the claim's readers on the job's route. + Rejected: inheriting the prefix route's instance by default and making + the prefix terminal once a materialized job ends, which would change + long-lived services; and inheriting it with automatic restarts, which + needs ended-path history or a retirement design this quest does not own. - **Visibility, not unannounced broadcasts.** Callers that fill the catalog first (`moq-cli` hls, rtsp and publish; moq-mux `ts/programs.rs`) or announce after SDP (`moq-rtc/server/whip.rs`) create @@ -106,24 +120,6 @@ 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. -## Waiting - -- Maintainer: choose the default when a job ends and the same prefix serves its - path again. The inherited-instance default above would reuse the ended job's - instance even though its group sequences restart. The dependent - [takeover quest](/quest/m1/announce-takeover.md) requires a fresh instance and - refusal of pins to the ended job before relying on inheritance. Recommend - making `request.route(options)` mint a fresh instance by default, with an - explicit stable instance only for callers that continue its sequences; - keep the existing predecessor handling until that quest replaces it. - Alternatively, preserve the inherited default by making the prefix terminal - when a materialized job ends, requiring a new prefix route for later jobs. - Keeping both an immutable prefix instance and automatic per-path restarts - needs an ownership bound for ended-path history: serial requests must not - leave a growing tombstone map. Resolve the default and its safety scope before - migrating the public API. See - [the implementation audit](https://github.com/moq-dev/moq/pull/7770). - ## Related - No constructible internal handles - the same JS hygiene rule