Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
b7af477
chore(quest): claim quest/m1/cluster-routing/routes/wire.md
kixelated Nov 3, 2026
6ffb075
quest: plan per-certificate chain rules for moq auth serve
kixelated Nov 5, 2026
33452f4
quest: plan the datagram answer race and clear resolved waits
kixelated Nov 5, 2026
02d6117
Merge remote-tracking branch 'origin/main' into feat/lite-07-route-wire
kixelated Nov 5, 2026
17484e2
feat(net)!: specify the lite-07 route wire and decode its messages
kixelated Nov 5, 2026
a37852b
Merge remote-tracking branch 'origin/quest/m1/cluster-routing/routes/…
kixelated Nov 5, 2026
527f6bc
fix(net): format, seed the reply fuzz kind, and allow the undriven re…
kixelated Nov 5, 2026
9448429
fix(drafts): the feasibility distance keeps the lowest metric within …
kixelated Nov 5, 2026
17fd39d
Merge remote-tracking branch 'origin/main' into feat/lite-07-route-wire
kixelated Nov 5, 2026
ecc8ab9
fix(drafts): merge main and record route wire decisions
kixelated Nov 5, 2026
c5d21a3
docs(drafts): align route request node scope and record floor limit d…
kixelated Nov 5, 2026
c4367d3
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 5, 2026
9f49958
feat(net)!: make ANNOUNCE_FLOOR a marker and collapse clamped claims
kixelated Nov 5, 2026
c21d4cd
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 5, 2026
42c479b
feat(net)!: hold routes with ROUTE_HOLD and offset the floor revision
kixelated Nov 5, 2026
26b0772
fix(net): seed every route message type, rank draining claims last, n…
kixelated Nov 5, 2026
8a04aa1
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 5, 2026
81395cf
Merge origin/main into quest/m1/cluster-routing/routes/wire
kixelated Nov 5, 2026
ea55b48
fix(net): seed ROUTE_START and keep the highest pending ROUTE_REQUEST…
kixelated Nov 5, 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
591 changes: 379 additions & 212 deletions drafts/draft-lcurley-moq-lite.md

Large diffs are not rendered by default.

5 changes: 2 additions & 3 deletions quest/m1/announce-takeover.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,9 +130,8 @@ separate from the identity rewrite of this Plan, which landed with

- Reword "takeover" as an event or operation, in terms of identity
continuity, in [moq-bench pins the instances it measures](/quest/m2/bench-epoch-pin.md)
(Goal and Plan), [the HLS server follows each path once](/quest/m2/hls-follow-once.md)
(Goal and Tests), and [lite-07 route wire](/quest/m1/cluster-routing/routes/wire.md)
(the wire sketch, "the separately proven Takeover operation").
(Goal and Plan) and [the HLS server follows each path once](/quest/m2/hls-follow-once.md)
(Goal and Tests).
- Rewrite the EPOCH references in `drafts/draft-lcurley-moq-cluster.md` and
`drafts/draft-lcurley-moq-epoch.md` in terms of IDENTITY.
- Add a regression test where a publisher restart's new announcement
Expand Down
2 changes: 1 addition & 1 deletion quest/m1/api-audit/route/handle.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Non-goals: the instance model ([Instance and epoch](https://github.com/moq-dev/m
announce events (a path listing plus `follow` since
[moq-dev/moq#7678](https://github.com/moq-dev/moq/pull/7678)),
the read side, which instance owns, and the route layer's wire metric
([lite-07 route wire](/quest/m1/cluster-routing/routes/wire.md)).
(`drafts/draft-lcurley-moq-lite.md`).

## Plan

Expand Down
24 changes: 17 additions & 7 deletions quest/m1/bench-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,26 @@ runs on the hosted ARM runners, and a deliberately slowed bench fails the job.

- Maintainer: dispatch the slowed-bench Nightly run below. Agents never
dispatch Nightly; the 2026-11-04 authorization covered the two A/A runs only.
- moq-dev/moq: once A/A run
[41921320690](https://github.com/moq-dev/moq/actions/runs/41921320690)
finishes, dispatch the second A/A run under the same authorization
(`gh workflow run nightly.yml --ref main -f bench-base=<main's head>`; as of
2026-11-04 it is not dispatched yet), then read both runs' `paired.json` (the
`bench-rust*` artifacts). Find the second with `gh run list --repo
moq-dev/moq --workflow nightly.yml --event workflow_dispatch`.
- Maintainer: authorize one more A/A Nightly run for the moq-net
(`bench-rust`) and `bench-rust-relay` groups, now that
[moq-dev/moq#7940](https://github.com/moq-dev/moq/pull/7940) lets moq-net's
benches run to completion.
Neither group produced a `paired.json` in either 2026-11-04 run, because
their benches panic. Check: both groups' `paired.json` exist in that run.

## Plan

A/A results, 2026-11-04 (/quest-unblock): runs
[41921320690](https://github.com/moq-dev/moq/actions/runs/41921320690) and
[41933525520](https://github.com/moq-dev/moq/actions/runs/41933525520) both
produced `paired.json` for the shared, extra, and uring groups. The first was
cancelled by Nightly's concurrency group after its bench artifacts uploaded.
At a 10% threshold over 3 rounds, neither run confirmed a regression: every
case the 20-case confirmation budget (`CONFIRMATIONS`) reached came back as
noise. Single-pass crossings: shared 18 and 26 of 716, extra 10 and 15 of 460,
uring 1 and 1 of 41, so the second run left 6 shared cases `unconfirmed`. |delta| p95 was
3.7-8.3%, p99 10-23%. Tune the threshold for those groups from these.

Decided 2026-11-04 (maintainer, /quest-unblock): ✅ authorize one-time agent
dispatch of the two A/A Nightly runs on `main`, with `bench-base` set to each
run's own commit. Not chosen: the maintainer dispatching them, or skipping.
Expand Down
65 changes: 45 additions & 20 deletions quest/m1/cluster-routing/routes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,22 @@ claim whose withdrawal is already known.

## Plan

1. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **The draft describes the target before the code switches.** A hop-less ANNOUNCE cannot run before the router drives sessions; the quest's own Plan says so. So the draft now specifies the whole lite-07 route wire, while main's lite-07 session keeps sending hop-based ANNOUNCEs until [Route session integration](https://github.com/moq-dev/moq/blob/main/quest/m1/cluster-routing/routes/session.md) lands. lite-07 is unpublished `-wip`, off by default, and the epic lands in one release before the cut. The other option was to put only the new message sections in the draft and leave ANNOUNCE hop-based. I rejected it because ANNOUNCE_FLOOR's "for that route" and the Route ID would then be undefined in the draft.
2. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **The request field is `Node ID (i)`, with 0 meaning "the publisher selects".** It is added to every request that resolves a path: TRACK, TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS. Node ID 0 is reserved everywhere.
3. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **ROUTE_REQUEST names a Node ID, not a Route ID.** A request can then never race a ROUTE_END into a protocol violation.
4. ~~A held ROUTE_UPDATE carries a seqno and down-only bit of 0.~~ Superseded by item 14: a held route is its own message and carries no seqno or bit.
5. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **Floor regions have no order, and a repeated region is a violation.** A sorted order would need Rust's `Path` ordering reproduced exactly in JS. Decoding into a map rejects duplicates at the same cost. Superseded the same day by item 10, which removes regions.
6. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **The Hop setup parameter and ANNOUNCE_OK's Hop ID are dropped from lite-07.** Their only roles were path-vector exclusion and the implicit trailing hop. ANNOUNCE_OK reserves no body for a route-key proof: [moq-dev/moq#7937](https://github.com/moq-dev/moq/pull/7937), accepted the same day, proves the route key once per session in SETUP. The live hop-based codec still switches in session integration, as choice 1 requires.
7. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **An echo naming a Route ID that was never ended, or was already echoed, is a violation at the publisher.** The publisher can check this from its live and unacknowledged ids alone, with no growing state.
8. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **ANNOUNCE_TAKEOVER keeps its shape, with a Route ID in place of hops, and its predecessor must be under the same route.** [quest/m1/announce-takeover.md](https://github.com/moq-dev/moq/blob/main/quest/m1/announce-takeover.md) deletes the message, so this keeps the change minimal.
9. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **Unknown announce types stay skipped by length on lite-06+**, as before. An unknown reply type is refused.
10. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **ANNOUNCE_FLOOR is a marker, not a region list:** `{Route ID, Revision}`. It closes a batch and certifies the stream's claims for that route across the whole requested prefix as the origin's at that Revision. A publisher that cannot vouch for the whole requested prefix at one Revision still closes the batch, with a floor that certifies nothing, encoded per item 13. Regions, the replacing list, and the 65,535-byte overflow go away. Accepted cost: a relay with partial knowledge of an origin certifies nothing for that route, so a receiver lets its stale claims go only on ROUTE_END. Rejected: one region per message; a multipart atomic list.
11. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **Clamped claims collapse to the best one.** When several of a route's claims cover a request's prefix (`live` at cost 10 and `live/a` at cost 1, request `live/a/x`), the publisher presents only the most specific, and when it is withdrawn moves the presented claim to the next covering one with ANNOUNCE_UPDATE or ANNOUNCE_RESTART instead of ending it. No wire change; one live claim per prefix per route holds, and a receiver merges claims at the prefix each stream presents them. Rejected: carrying each claim's ancestor depth.
12. ✅ Decided 2026-11-05 (maintainer, /quest-plan): **A floor certifies only what its own request shows.** A stream whose request did not set `Hidden` certifies nothing about hidden claims. No new wire field. Rejected: isolating differently filtered views.
13. ✅ Decided 2026-11-05 (maintainer): **ANNOUNCE_FLOOR encodes `Revision + 1`, with 0 meaning the floor certifies nothing,** the same offset as `Max Age`. Rust decodes it to `Option`. It replaces a Revision of 2^64-1 as the marker: a huge sentinel is a bad pattern and costs 9 bytes as a lite-07 varint. Rejected: a separate message; a boolean field.
14. ✅ Decided 2026-11-05 (maintainer: "use 0 as a sentinel, or make a new message type"; the agent picked the message): **A held route is ROUTE_HOLD (0xB), `{Route ID}`,** replacing a ROUTE_UPDATE with a Metric of 2^64-1. A metric of 0 is real (the origin's own route), so 0 cannot mark held, and offsetting every metric by one would still leave a held update's seqno and down-only bit meaningless and refused. The message carries only what a hold means, item 4's rule goes away, and a metric is now only bounded by overflow, so the wire refuses no metric. The 2^64-1 Seqno and Revision bounds stay: they are bounds, not markers, leaving room for a ROUTE_REQUEST's successor and for the floor's offset.


The route layer's core landed in
[moq-dev/moq#7676](https://github.com/moq-dev/moq/pull/7676): a
crate-private, sans-IO `Router` in `rs/moq-net/src/route/`, generic over the
Expand All @@ -39,7 +55,10 @@ Settled by the core, for review:
interest overlaps it (`a_claim_above_an_interest_overlaps_it`).
- Letting go of a region keeps the proof's rule: keep every still-certified
region, or rebuild them all if a lost floor is newer than a kept one, a
collection whose replay is bounded like any other.
collection whose replay is bounded like any other. The core and the proof
keep per-region floors internally; the wire carries only item 10's
whole-interest marker, which [session integration](/quest/m1/cluster-routing/routes/session.md)
projects the view onto.
- A rotated identity ends the old one with ROUTE_END on every stream rather
than closing sessions, since the own identity is no longer proven per
session.
Expand All @@ -51,7 +70,10 @@ contract below. The routing contract's remaining model fixtures live in
port each topology to the implementation as acceptance, then delete the model.
The handoff contract below, decided 2026-10-16, settles claim freshness:

The wire sketch is in [wire](/quest/m1/cluster-routing/routes/wire.md); the bullets below are the contract it carries.
The lite-07 wire is specified in `drafts/draft-lcurley-moq-lite.md` (Announce,
Floors, and Routing), and `rs/moq-net/src/lite/announce.rs` encodes and decodes
its new messages ([moq-dev/moq#7764](https://github.com/moq-dev/moq/pull/7764));
the bullets below are the contract it carries.

- The announce cost is the origin's per-prefix seed (`transcode/**` at 10 and
`transcode/foobar` at 1 from one node, decided 2026-10-01) and nobody
Expand Down Expand Up @@ -149,8 +171,8 @@ The wire sketch is in [wire](/quest/m1/cluster-routing/routes/wire.md); the bull
by metric overflow.
- Loop freedom is Babel's feasibility condition (RFC 8966) keyed by node:
accept a route if its seqno is newer, or equal with a metric below the
feasibility distance. Only the origin advances its seqno. Retraction is an
infinite metric or ROUTE_END; there is no count to infinity.
feasibility distance. Only the origin advances its seqno. Retraction is
ROUTE_HOLD or ROUTE_END; there is no count to infinity.
- Starvation recovery is Babel's seqno request (RFC 8966 s3.8, decided
2026-10-12). A node whose routes to an origin are all infeasible sends
ROUTE_REQUEST for that origin, with its feasibility seqno plus one, to the
Expand Down Expand Up @@ -239,18 +261,20 @@ loss never reports an END:
- Each origin numbers the changes to its own claims with a revision that
starts at zero for each routing identity, separate from the route seqno.
Both are varints. An origin never advertises the last value, 2^64-1 (the
largest lite-07 varint, as for the infinite metric): a
largest lite-07 varint): a
seqno advance, claim change, or seqno request that would reach it rotates
the identity instead, ending the old one everywhere and announcing the
claims again under a fresh one, so nothing wraps and every advertised
seqno leaves room for the successor a request names
(`exhausted_counters_rotate_the_identity`).
A session sends an origin's announcements in batches, each closed by its
floors: per region, the revision as of which the stream's announcements
for that route within the region are complete. A bare identity's region is
the stream's interest. A qualified key certifies only within the
grant scopes it arrived through, and one key can arrive through grants
whose pattern unions differ, so its view carries one floor per scope.
floor: the revision at which the stream's announcements for that route,
across the whole interest, are the origin's, or nothing when the sender
does not know them across the interest at one revision (Plan item 10). A
qualified key is known only within the grant scopes it arrived through,
and one key can arrive through grants whose pattern unions differ, so the
view inside a node carries one floor per scope, and a stream whose
interest is wider than those scopes certifies nothing.
- A receiver keeps each session's last view, to apply the next batch, and
merges every session's view into its own claim by claim: whichever view
covers the claim with the newer floor decides. A floor certifies only the
Expand Down Expand Up @@ -290,7 +314,7 @@ loss never reports an END:
withdrawing one origin's wildcard leaves another origin's copy
(`wildcard_claims_end_per_origin_and_are_certified_below`).
- A node tracks the regions each neighbour's last view certifies. Only a
neighbour whose last finite advertisement is feasible here counts, held or
neighbour whose last advertisement is feasible here counts, held or
not: feasible edges strictly decrease the metric toward the origin, so two
nodes never keep a region alive through each other. While the node has a
usable route and every such neighbour has answered the current interest, a
Expand Down Expand Up @@ -321,9 +345,8 @@ loss never reports an END:
withdrawal.
- Per identity, a node is usable (a feasible selected route: announcements
shown available), held, or let go. It is held while starved, or while a
neighbor's held route has a last finite advertisement feasible here; it
keeps showing the announcements as unavailable and sends ROUTE_UPDATE with
an infinite metric. Holds therefore follow strictly decreasing metrics
neighbor's held route has a last advertisement feasible here; it
keeps showing the announcements as unavailable and sends ROUTE_HOLD. Holds therefore follow strictly decreasing metrics
down to a starved node and cannot prop each other up. Otherwise the node
lets go: ROUTE_END to every neighbor it advertised to, and its reader sees
the announcements go offline, a distinct event from an END the origin
Expand Down Expand Up @@ -393,8 +416,10 @@ Decided with the maintainer 2026-10-16, from the handoff proof:
which adds bytes and removes no state, since a receiver still needs each
session's last view to apply a batch from a sender whose own view jumped;
and the floor on ROUTE_UPDATE, which ties claim churn to route processing.
2. Held encoding: ✅ an infinite metric (2^64-1) means held and ROUTE_END
means let go, with no new field. Rejected: an explicit held bit.
2. Held encoding: ~~an infinite metric (2^64-1) means held and ROUTE_END
means let go, with no new field. Rejected: an explicit held bit.~~
Superseded 2026-11-05 by Plan item 14: ROUTE_HOLD means held, and
ROUTE_END still means let go.
3. Reader API: ✅ an announcement carries availability, and letting go is a
distinct offline event, separate from the origin's END, in Rust and JS.
Rejected: presence alone, which gives a reader nothing to re-request on
Expand Down Expand Up @@ -436,7 +461,8 @@ Decided with the maintainer 2026-10-16, from the handoff proof:
which grows with publisher churn times uptime on every relay that saw an
identity, about 16 bytes each, until a restart; and Babel's source GC
timer, which assumes stale echoes are gone by then rather than proving it.
7. Scope coverage under one key: ✅ per-region floors. ANNOUNCE_FLOOR
7. Scope coverage under one key: ✅ per-region floors (superseded on the
wire 2026-11-05 by Plan item 10; the core keeps regions internally). ANNOUNCE_FLOOR
names the region it certifies, a suffix of the stream's interest prefix
(the scope met with the interest), each node tracks which regions each
feasible neighbour's last view certifies, and a region none certifies
Expand All @@ -449,7 +475,8 @@ Decided with the maintainer 2026-10-16, from the handoff proof:
implementation, which leaves the proof's freshness claim false for scoped
delivery.

8. Region-set framing: ✅ one ANNOUNCE_FLOOR per batch lists every region
8. Region-set framing (superseded 2026-11-05 by Plan item 10, a
whole-interest marker): ✅ one ANNOUNCE_FLOOR per batch lists every region
the sender certifies for the route: (Route ID, count, then a region suffix
and revision per region). The list replaces the last, so a sender stops
certifying a region it lost by leaving it out, and a count of zero answers
Expand Down Expand Up @@ -501,8 +528,6 @@ benchmarks.
## Required

- [Scoped peers prove a route key](/quest/m1/cluster-routing/routes/proof.md) - records the session proof decision and implementation

- [lite-07 route wire](/quest/m1/cluster-routing/routes/wire.md) - lite-07 and the draft carry ROUTE, ANNOUNCE_FLOOR, ROUTE_REQUEST, and path-less ANNOUNCE
- [Route session integration](/quest/m1/cluster-routing/routes/session.md) - one router per origin node drives the origin and every lite-07 announce stream
- [Announcement availability](/quest/m1/cluster-routing/routes/availability.md) - announcements report availability, and a let-go is offline rather than END, in Rust and JS
- [js/net route layer](/quest/m1/cluster-routing/routes/js.md) - `js/net` encodes, decodes, and resolves the route layer
Expand Down
4 changes: 2 additions & 2 deletions quest/m1/cluster-routing/routes/acceptance.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ replace are retired.
go out to a stream whose interest meets none of the origin's claims:
- a transit node forwarding requests for paths outside its own interest;
- a node holding or forwarding a seqno request for that identity;
- a sender whose certified regions miss the interest, which must still
answer with an empty floor list
- a sender that cannot certify the interest, which must still close the
batch with a floor that certifies nothing
(`a_disjoint_interest_is_answered_with_nothing`).

The counterexamples from #4349 (closed; this epic still owns the fix) are the `residual_*` tests in
Expand Down
3 changes: 1 addition & 2 deletions quest/m1/cluster-routing/routes/js.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,10 @@ Decided 2026-10-27 (maintainer), from
`origin.ts` a detached request stays on its own route instead of following
the cheapest one; fix it with the route-selection rework here.
- Feed the availability API from [Announcement availability](/quest/m1/cluster-routing/routes/availability.md).
- Rust/JS interop covers the route messages, the floor list, and the echo.
- Rust/JS interop covers the route messages, the floor marker, and the echo.

## Required

- [lite-07 route wire](/quest/m1/cluster-routing/routes/wire.md) - the messages
- [Announcement availability](/quest/m1/cluster-routing/routes/availability.md) - the API this feeds

## Related
Expand Down
1 change: 0 additions & 1 deletion quest/m1/cluster-routing/routes/proof.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,4 +47,3 @@ signature. No ANNOUNCE_OK proof body is needed by this draft or implementation;
## Related

- [Route session integration](/quest/m1/cluster-routing/routes/session.md) - files identities under the proven key
- [lite-07 route wire](/quest/m1/cluster-routing/routes/wire.md) - coordinates announce messages
Loading
Loading