Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
7c53c18
chore(quest): claim quest/m2/cache-routing-proof.md
kixelated Nov 10, 2026
e3c5409
test(net): prove cache-aware routing over the route layer
kixelated Nov 10, 2026
6341038
test(net): list the long cache sweep in the test inventory
kixelated Nov 10, 2026
520f68a
feat(net)!: carry warm routes and Serves in moq-lite-07
kixelated Nov 11, 2026
42922ba
quest: plan the origin seqno churn that warm children pay
kixelated Nov 11, 2026
f4c5a91
test(interop): quarantine the go -> cpp cell and plan its fix
kixelated Nov 11, 2026
196c218
test(doc): quarantine the doc API's failing-render test and plan its fix
kixelated Nov 11, 2026
c12d988
fix(drafts): an Alone warm route counts warm whatever the receiver's …
kixelated Nov 11, 2026
20801d1
quest: record the other interop lanes that failed once under load
kixelated Nov 11, 2026
35af7ed
Merge origin/main into quest/m2/cache-routing-proof
kixelated Nov 11, 2026
70f512e
Merge origin/main into quest/m2/cache-routing-proof
kixelated Nov 11, 2026
492ef3d
style: format the merged route tests
kixelated Nov 11, 2026
d267b79
Merge origin/main into quest/m2/cache-routing-proof
kixelated Nov 12, 2026
8b16ca8
test(interop): quarantine the rust finish cells, and let INTEROP_QUAR…
kixelated Nov 12, 2026
865c105
Merge remote-tracking branch 'origin/main' into quest/m2/cache-routin…
kixelated Nov 12, 2026
a6a0933
test(interop): a rerun line carries INTEROP_QUARANTINED
kixelated Nov 12, 2026
36d3ce4
Merge remote-tracking branch 'origin/main' into quest/m2/cache-routin…
kixelated Nov 12, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion doc/.vitepress/api/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,8 @@ export declare class Thing {}
});
});

test("an unexported declaration that a public one names fails the run", async () => {
// Quarantined: quest/m0/test-flakes-2/doc-api-typedoc-timeout.md.
test.skip("an unexported declaration that a public one names fails the run", async () => {
const files = {
"src/index.ts": `export { read } from "./access";
/** A public value. */
Expand Down
151 changes: 146 additions & 5 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -416,6 +416,9 @@ The publisher replies with a single ANNOUNCE_OK message followed by the matching
- ANNOUNCE_UPDATE: a claim's cost changed.
- ANNOUNCE_RESTART: a claim now serves another Instance, or a higher Epoch of the same one.
- ANNOUNCE_FLOOR: a batch of a route's claims is complete.
- WARM_START: the publisher keeps a copy of a broadcast whether or not the subscriber pulls through it (see [Warm Routes](#warm-routes)).
- WARM_UPDATE: a warm route's Serves or Warm Cost changed.
- WARM_END: the publisher withdrew a warm route.
- SYNCED: the initial set is complete.

In the other direction, the subscriber sends ROUTE_REQUEST and echoes every ROUTE_END (see [Routing](#routing)).
Expand All @@ -426,10 +429,10 @@ The initial set is relative to this hop: a relay answers with what it holds with
The publisher MAY coalesce changes to a claim it has not yet sent, and sends no more claims before SYNCED than the initial set holds.
A retraction of a claim or route already sent MAY precede SYNCED.

Each ROUTE_START implicitly assigns the next Route ID on the stream, and each ANNOUNCE_START the next Announce ID: two counters starting at 0 that increment by 1 per assignment.
Neither id appears on the wire where it is assigned; both endpoints derive it from the message order on the (reliable, ordered) stream, and other messages reference it instead of repeating the origin node or the claim's prefix.
Each ROUTE_START implicitly assigns the next Route ID on the stream, each ANNOUNCE_START the next Announce ID, and each WARM_START the next Warm ID: three counters starting at 0 that increment by 1 per assignment.
No id appears on the wire where it is assigned; both endpoints derive it from the message order on the (reliable, ordered) stream, and other messages reference it instead of repeating the origin node, the claim's prefix, or the warm route's path.
Ids are never reused within a stream.
A ROUTE_END retires its Route ID and the Announce ID of every claim under the route; an ANNOUNCE_END retires one Announce ID.
A ROUTE_END retires its Route ID, the Announce ID of every claim under the route, and the Warm ID of every warm route under it; an ANNOUNCE_END retires one Announce ID, and a WARM_END one Warm ID.

A stream has at most one live route per origin node, and each route at most one live claim per prefix.
Another origin claiming the same prefix is another claim, under its own route.
Expand Down Expand Up @@ -543,7 +546,7 @@ No peer then routes through the node, and the Hops refuse any copy of its own ro

A SUBSCRIBE, FETCH, TRACK, TRACKS, or DATAGRAMS request names the origin node that serves it.
A subscriber that names 0 lets the publisher select one (see [Resolution](#resolution)), and a relay forwarding a request names the origin node it selected or was given.
A relay forwards a request naming an origin node only on its selected route to that node, and resets it with UNROUTABLE when it has no usable route to it, so the request never reaches another origin.
A relay forwards a request naming an origin node only on its selected route to that node, or a SUBSCRIBE through the neighbor [Warm Routes](#warm-routes) chooses for its broadcast, and resets it with UNROUTABLE when it has no usable route to it, so the request never reaches another origin.

Claims with the same Instance serve the same Broadcast, so a relay MAY move a live subscription between them, including onto a higher Epoch, continuing from the first frame the subscriber lacks, and a route change (a reconnect, a cheaper path, a draining session) is invisible to the subscriber.
A relay MUST NOT move a subscription to a claim with a different Instance: it stays on its Instance's claims and ends with the last of them.
Expand Down Expand Up @@ -574,6 +577,41 @@ An advertiser that will not serve a resolved request resets the request stream w
Every refusal is terminal and propagates without re-resolution, so probing unserved paths costs one round trip per path.
An advertiser signals capacity through its claim alone, withdrawing or re-pricing it before it runs out.

#### Warm Routes {#warm-routes}
A relay MAY pull each broadcast through a neighbor of its choosing rather than along its selected route to the origin node, so a broadcast crosses fewer relays and neighboring relays share one copy.
A warm route tells a neighbor that the sender carries a broadcast and keeps it whether or not that neighbor pulls through it.
An endpoint that does not choose per broadcast ignores every WARM_START, WARM_UPDATE, and WARM_END, and sends a `Serves` of Unknown unless it serves only its own readers.

Every SUBSCRIBE names whom it serves in `Serves`:

- Alone: demand of the subscriber's own, either a local reader or pulls that trace back to two or more relays.
- Relay: demand that traces back to one relay alone, its root, named by its Node ID. A downstream pull that serves Alone traces back to the relay that sent it, and one that serves Relay to its root.
- Unknown: the subscriber does not say, or some of its demand came from a pull that serves Unknown and the rest traces back to fewer than two relays.

A copy kept after its demand is gone serves whom it last served.

A relay that pulls a broadcast for demand MAY send a warm route for it, under its route to the broadcast's origin node, on an Announce Stream it answers whose request covers the path.
It sends one only while its `Serves` is not Unknown and its selected route to the origin node is usable, and only to a neighbor that has no usable route to that origin node or whose last route to it has a Metric at least the relay's own.
A warm route travels one hop: a receiver never forwards it.
It carries the sender's `Serves` and its `Warm Cost`, the price it pays for its own pull, as defined below.
The sender sends a WARM_UPDATE when either changes, and a WARM_END once it no longer pulls the broadcast.
A change that narrows whom the copy serves, from Alone to a Relay, from one Relay to another, or to no warm route at all, waits until the sender has kept the copy without the old demand for as long as it keeps any copy whose demand is gone, so a neighbor that just joined it does not move straight back; until then the warm route stands as last sent, `Warm Cost` included.

A receiver counts a neighbor warm for a broadcast when the neighbor's warm route serves Alone, or serves a Relay that is neither the receiver nor the root of the receiver's own pull while that pull does not serve Unknown.
Demand a receiver causes, through any number of relays, then never warms a neighbor toward it.
The receiver prices a pull through each neighbor as:

- the link cost alone, through a neighbor it counts warm, whose copy is paid for already;
- the link cost plus the neighbor's `Warm Cost`, through a neighbor with a warm route it does not count warm, whose copy depends on the receiver's demand;
- otherwise its metric through that neighbor.

A relay MUST pull a broadcast only through a neighbor eligible for it: one whose last route to the request's origin node is feasible (see [Routing](#routing)), or was advertised with exactly the Seqno and Metric of the relay's feasibility distance while the neighbor's Rendezvous Hash for the broadcast's path is lower than the relay's own.
The Rendezvous Hash is as defined in [Resolution](#resolution), with the neighbor's or the relay's own Node ID (see [Node ID Parameter](#node-id-parameter)).
A feasibility distance only falls within a Seqno, so the Seqno rises, or the Metric and then the hash fall, along every pull, and the pulls of a broadcast never form a loop, even over stale routes.

Among the eligible neighbors, a relay SHOULD prefer a session that has not received a GOAWAY, then the lowest price, then a neighbor it counts warm, then the lowest Rendezvous Hash.
It SHOULD move an existing pull only to a neighbor strictly better by GOAWAY and then price, so two relays pricing each other's copies settle instead of swapping.

### Subscribe
A subscriber opens Subscribe Streams to request a Track.

Expand Down Expand Up @@ -1159,7 +1197,7 @@ An Announce Stream ending before SYNCED is a PROTOCOL_VIOLATION; a Tracks Stream

## ROUTE_START {#route-start}
A publisher sends a ROUTE_START message when it reaches an origin node (see [Routing](#routing)).
Each ROUTE_START implicitly assigns the next Route ID on the stream, later referenced by ROUTE_UPDATE, ROUTE_HOLD, ROUTE_END, ANNOUNCE_FLOOR, and ANNOUNCE_START (see [Announce](#announce)).
Each ROUTE_START implicitly assigns the next Route ID on the stream, later referenced by ROUTE_UPDATE, ROUTE_HOLD, ROUTE_END, ANNOUNCE_FLOOR, ANNOUNCE_START, and WARM_START (see [Announce](#announce)).

~~~
ROUTE_START Message {
Expand Down Expand Up @@ -1464,6 +1502,92 @@ The ordinal implicitly assigned by a prior ROUTE_START on this stream.
The origin's Revision at which the floor certifies the stream's claims for the route, plus one, or 0 when it certifies nothing.


## WARM_START {#warm-start}
A publisher sends a WARM_START message to tell the subscriber that it carries a broadcast and keeps it whether or not the subscriber pulls through it (see [Warm Routes](#warm-routes)).
Each WARM_START implicitly assigns the next Warm ID on the stream, later referenced by WARM_UPDATE and WARM_END (see [Announce](#announce)).

~~~
WARM_START Message {
Type (i) = 0xC
Message Length (i)
Route ID (i),
Broadcast Path Suffix (s),
Instance (b),
Minted (8),
Serves (..),
Warm Cost (i),
}
~~~

**Type**:
Set to 0xC to indicate a WARM_START message.

**Route ID**:
The route to the broadcast's origin node: the ordinal implicitly assigned by a prior ROUTE_START on this stream.
A warm route never changes its Route ID.

**Broadcast Path Suffix**:
Combined with the requested prefix to form the broadcast's path.

**Instance** and **Minted**:
The Instance of the copy the publisher carries, as defined for [ANNOUNCE_START](#announce-start).

**Serves**:
Whom the publisher's own pull of the broadcast serves, as defined for [SUBSCRIBE](#subscribe).
Unknown is a PROTOCOL_VIOLATION here.

**Warm Cost**:
The publisher's price for its own pull of the broadcast (see [Warm Routes](#warm-routes)), in the units of the route's Metric.

A stream has at most one live warm route per route and path.
A subscriber that uses warm routes MUST close the session with a PROTOCOL_VIOLATION on a WARM_START naming a Route ID that was never assigned or already retired, or a path its route already has a live warm route for.


## WARM_UPDATE {#warm-update}
A publisher sends a WARM_UPDATE message when a warm route's `Serves` or `Warm Cost` changes, referencing its Warm ID.
The id stays live.

~~~
WARM_UPDATE Message {
Type (i) = 0xD
Message Length (i)
Warm ID (i),
Serves (..),
Warm Cost (i),
}
~~~

**Type**:
Set to 0xD to indicate a WARM_UPDATE message.

**Warm ID**:
The ordinal implicitly assigned by a prior WARM_START on this stream.

**Serves** and **Warm Cost**:
As defined for [WARM_START](#warm-start), replacing the warm route's.


## WARM_END {#warm-end}
A publisher sends a WARM_END message when it withdraws a warm route, referencing its Warm ID.
The id is retired and MUST NOT be referenced again.
A ROUTE_END retires the warm routes under its route without a WARM_END.

~~~
WARM_END Message {
Type (i) = 0xE
Message Length (i)
Warm ID (i)
}
~~~

**Type**:
Set to 0xE to indicate a WARM_END message.

**Warm ID**:
As defined for [WARM_UPDATE](#warm-update).
A subscriber that uses warm routes MUST close the session with a PROTOCOL_VIOLATION on a WARM_UPDATE or WARM_END naming a Warm ID that was never assigned or already retired.


## SUBSCRIBE
SUBSCRIBE is sent by a subscriber to start a subscription.

Expand All @@ -1483,6 +1607,7 @@ SUBSCRIBE Message {
Range Count (i)
Range (..) ...
Update (i)
Serves (..)
}

Range {
Expand All @@ -1497,6 +1622,11 @@ Anchor {
[Groups Back (i)]
[Timestamp (i)]
}

Serves {
Serves Type (i)
[Node ID (i)]
}
~~~

**Subscribe ID**:
Expand Down Expand Up @@ -1555,6 +1685,15 @@ A Range resolves once: an update that leaves it live does not resolve it again.
The number of the subscription's terms this message sets: 0 on SUBSCRIBE, and on each SUBSCRIBE_UPDATE a larger value than the one before it.
A [SUBSCRIBE_DROP](#subscribe-drop) echoes the number in effect when its groups were given up, so the subscriber can tell a stale verdict on its current terms from one an update has since replaced.

**Serves Type**:
Whom the subscription serves (see [Warm Routes](#warm-routes)), and which field follows:

- Unknown (0x0): no fields.
- Alone (0x1): no fields.
- Relay (0x2): the `Node ID` of the one relay its demand traces back to. 0 is a PROTOCOL_VIOLATION.

Any other value is a PROTOCOL_VIOLATION.

A `Start` is a floor, not a request; `Subscriber Max Age` is the only thing that asks for data.
The publisher SHOULD start at the oldest group at or above the floor that [Expiration](#expiration) has not expired, and MUST NOT deliver an older one.
A `Subscriber Max Age` of 0 therefore starts at the latest group, since every older group is already stale.
Expand Down Expand Up @@ -1590,6 +1729,7 @@ SUBSCRIBE_UPDATE Message {
Range (..) ...
Update (i)
Wanted Group (i)
Serves (..)
}
~~~

Expand Down Expand Up @@ -2286,6 +2426,7 @@ The `Message Length` describes the payload size on the wire.
- The Cost parameter must be at least 1.
- Replaced the shortest-path, Hop ID, Instance Hash, and Chain Hash tie-breaks with the local priority of the route's session, the Announce Cost plus the route's metric, and a Rendezvous Hash of the requested path and the origin's Node ID.
- Removed the standby-ordering deployment requirements on Route Cost seeds and bounds.
- Added warm routes: WARM_START (0xC), WARM_UPDATE (0xD), and WARM_END (0xE) on the Announce Stream, and `Serves` on SUBSCRIBE and SUBSCRIBE_UPDATE. A relay MAY pull each broadcast through a neighbor that already carries it, priced by whom that neighbor's copy serves, and only through a neighbor whose route is feasible or tied at its feasibility distance with a lower Rendezvous Hash, so the pulls never loop.
- Added the temporary Lite-06 Chain Setup Parameter (0x9) and a trailing Lite-06 Chain on ANNOUNCE_START, ANNOUNCE_UPDATE, and ANNOUNCE_RESTART: the moq-lite-06 Hop ID list of a claim learned over moq-lite-06, which a node drops when it names that node.

### Tracks {#changelog-07-tracks}
Expand Down
5 changes: 3 additions & 2 deletions js/net/src/lite/subscribe.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -200,10 +200,11 @@ test("lite-07 carries the span as its only range, exclusive at the end", async (

test("a lite-07 list decodes as the span covering it", async () => {
// Priority, order, max delay, and an unstated min delay as SubscribeUpdate writes them,
// then no Range ID to retire, the ranges it adds, the update number, and an absent wanted group.
// then no Range ID to retire, the ranges it adds, the update number, an absent wanted group, and
// a pull that serves Alone.
const head = (await encodeMessage(Version.DRAFT_07, new SubscribeUpdate({ priority: 0, ranges: [] }))).slice(1, 5);
const update = async (ranges: number[]) => {
const body = [...head, 0, ...ranges, 0, 0];
const body = [...head, 0, ...ranges, 0, 0, 1];
const got = await SubscribeUpdate.decode(
new Reader(undefined, new Uint8Array([body.length, ...body]), Version.DRAFT_07),
Version.DRAFT_07,
Expand Down
26 changes: 26 additions & 0 deletions js/net/src/lite/subscribe.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ import {
hasRanges,
hasRefresh,
hasSkip,
hasWarm,
resolvesStart,
Version,
} from "./version.ts";
Expand All @@ -42,6 +43,27 @@ async function encodeUpdate(w: Writer, version: Version, update: bigint) {
if (hasSkip(version)) await w.u62(update);
}

// `Serves Type`: whom a pull serves. A relay names the one relay its demand traces back to.
const SERVES_UNKNOWN = 0n;
const SERVES_ALONE = 1n;
const SERVES_RELAY = 2n;

/** Encode whom a pull serves: Alone, since this endpoint forwards nothing and every pull is its own. */
async function encodeServes(w: Writer, version: Version) {
if (hasWarm(version)) await w.u62(SERVES_ALONE);
}

/** Decode whom a pull serves, and ignore it: only a relay choosing a parent per broadcast prices by it. */
async function decodeServes(r: Reader, version: Version) {
if (!hasWarm(version)) return;
const serves = await r.u62();
if (serves === SERVES_RELAY) {
if ((await r.u62()) === 0n) throw new ProtocolViolation("serves names relay 0");
} else if (serves !== SERVES_UNKNOWN && serves !== SERVES_ALONE) {
throw new ProtocolViolation(`unknown serves type ${serves}`);
}
}

/**
* Encode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE.
*
Expand Down Expand Up @@ -731,6 +753,7 @@ export class SubscribeUpdate {
}
await encodeUpdate(w, version, this.update);
if (hasRefresh(version)) await w.u62(this.wantedGroup === undefined ? 0n : this.wantedGroup + 1n);
await encodeServes(w, version);
break;
}
}
Expand All @@ -757,6 +780,7 @@ export class SubscribeUpdate {
}
const update = await decodeUpdate(r, version);
const wanted = hasRefresh(version) ? await r.u62() : 0n;
await decodeServes(r, version);
return new SubscribeUpdate({
wantedGroup: wanted === 0n ? undefined : wanted - 1n,
priority,
Expand Down Expand Up @@ -894,6 +918,7 @@ export class Subscribe {
break;
}
await encodeUpdate(w, version, this.update);
await encodeServes(w, version);
}

static async #decode(r: Reader, version: Version): Promise<Subscribe> {
Expand All @@ -914,6 +939,7 @@ export class Subscribe {
const minDelay = await decodeMinDelay(r, version);
const span = await decodeSpan(r, version);
const update = await decodeUpdate(r, version);
await decodeServes(r, version);
return new Subscribe({
id,
broadcast,
Expand Down
17 changes: 17 additions & 0 deletions js/net/src/lite/version.ts
Original file line number Diff line number Diff line change
Expand Up @@ -488,6 +488,23 @@ export function hasAnnounceCompression(version: Version): boolean {
}
}

/** Whether the announce stream carries warm routes (WARM_START, WARM_UPDATE, and WARM_END), and
* SUBSCRIBE and SUBSCRIBE_UPDATE say whom each pull serves. Added in lite-07. */
export function hasWarm(version: Version): boolean {
// Explicitly list older versions so future versions keep the lite-07+ behavior.
switch (version) {
case Version.DRAFT_01:
case Version.DRAFT_02:
case Version.DRAFT_03:
case Version.DRAFT_04:
case Version.DRAFT_05:
case Version.DRAFT_06:
return false;
default:
return true;
}
}

/** Whether TRACK_INFO carries the refresh ratio and SUBSCRIBE_UPDATE a wanted group. Added in lite-07.
* Older peers see a track that never refreshes. */
export function hasRefresh(version: Version): boolean {
Expand Down
23 changes: 23 additions & 0 deletions quest/m0/test-flakes-2/doc-api-typedoc-timeout.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# [S] The doc API's failing-render test holds up under load

## Goal

`doc/.vitepress/api/index.test.ts`'s "an unexported declaration that a
public one names fails the run" passes on a loaded host, and its
`test.skip` is removed.

## Plan

Planned 2026-11-10 under the repository's flaky-test rule, while iterating
[moq-dev/moq#8457](https://github.com/moq-dev/moq/pull/8457): one loaded
`just check` failed it as `this test timed out after 5000ms`, and the run
before passed. [moq-dev/moq#8426](https://github.com/moq-dev/moq/pull/8426)
saw the same timeout. It is the only case that renders inside its test body:
the other cases render at module load, which bun does not time out, so each
run of TypeDoc there races bun's default 5 second test timeout. Render it at
module load as the others do (capturing the rejection), or otherwise take
TypeDoc's run out of the timed body, rather than raising the timeout.

## Related

- [Interop's go -> cpp cell holds up under load](/quest/m0/test-flakes-2/interop-go-cpp.md) - quarantined from the same PR
Loading