feat(net)!: carry publisher epochs on routes

doc/bin/relay/cluster.md

@@ -29,15 +29,23 @@ has usually removed the other stale routes too, and the relay sends one
 retraction instead of advertising each stale path in turn. Requests still
 follow the current best route immediately; only the announcement waits.
 
-A path names one broadcast, whoever publishes it. When the route serving a
-broadcast dies, withdraws, or is beaten by a cheaper route, each subscription
-continues on the new route from the first frame its readers lack, so they see
+Routes carrying the same [publisher epoch](/concept/moq-lite#publisher-epochs)
+serve one broadcast. When the route serving it dies, withdraws, or is beaten by
+a cheaper route with that epoch, each subscription continues on the new route
+from the first frame its readers lack, so they see
 every frame once, mid-group included. A route that is still up finishes the
 groups it has open, overlapping the new one. A group neither route delivers is
 dropped once the readers' max age has passed it. A route through the subscribing peer
 itself is never used. A publisher whose groups restart, such as an encoder
-restarting from group 0, must publish under a new broadcast name; resumed under
-the old one, readers wait for its sequence to catch up.
+restarting from group 0, publishes under a new epoch, which replaces the old
+broadcast instead of resuming it. A route without an epoch, including every
+route on moq-lite 06 and older or moq-transport, keeps its subscriptions until it
+goes. Seamless failover needs both: a publisher that announces an epoch, and
+moq-lite 07 on every link the route crosses, since epochs travel on nothing
+older. A cluster that mixes moq-lite 06 and 07 links to the same content has a
+second cost: the route that carries the epoch supersedes the one that does not
+each time it appears, so a flapping moq-lite 07 link cuts the viewers resolved
+through the older one.
 
 Failover routes must carry copies of the same broadcast. For each track, the
 relay requires matching timescale, retention window, publisher priority, and

doc/concept/hang.md

@@ -11,9 +11,9 @@ timestamp. It is modeled on [WebCodecs](https://www.w3.org/TR/webcodecs/) so a
 browser can decode it directly. The spec is
 [draft-lcurley-moq-hang](/draft/moq-hang). Plaintext broadcast names end in
 `.hang` so a player knows which catalog to expect. End-to-end encrypted
-broadcasts live under `<opaque>/<epoch>`, where `<opaque>` is derived from the
-credential and a semantic name such as `foo.hang`, and one epoch identifies
-each publisher run. The path exposes no format or protection marker; the
+broadcasts live at `<opaque>`, derived from the credential and a semantic name
+such as `foo.hang`, and the [epoch](/concept/moq-lite#publisher-epochs) on
+their route identifies each publisher run. The path exposes no format or protection marker; the
 payloads follow [moq-e2ee](/draft/moq-e2ee).
 
 ## Catalog

doc/concept/moq-lite.md

@@ -97,9 +97,9 @@ always a prefix, on every wire version and on moq-transport alike; a service
 that serves only some of the paths beneath its prefix refuses the rest as they
 are requested. Each route carries the chain of relay identities it passed
 through, which is how forwarding loops are caught, and a cost, which is how a
-subscriber picks among several routes to the same broadcast. A path names one
-broadcast whoever publishes it, so a subscription moves between routes without
-a seam; a publisher must not reuse a path for different content. A hop of 0 is
+subscriber picks among several routes to the same broadcast. A route may also
+carry a [publisher epoch](#publisher-epochs), which says which routes serve the
+same bytes. A hop of 0 is
 the anonymous mark and travels the chain unchanged; when it is the first hop, a
 relay puts a random ID, fresh per connection, in front of it. A route that passed through an
 anonymous hop at any depth ranks below every fully identified route, whatever
@@ -113,8 +113,10 @@ compresses when it helps; TypeScript decodes it but always sends literally.
 A broadcast exists only while it is announced, for consumers in the same
 process and across a session alike: one that is created but never announced
 can be neither discovered nor requested. A broadcast published locally
-competes with remote routes to its path on cost like any other route, winning
-only a tie. Retracting a route (an unannounce, or the peer's `ANNOUNCE_END`)
+competes with remote routes to its path like any other route: a newer epoch
+beats it whatever the cost, so a local broadcast without an epoch loses to any
+remote route that carries one, and among equal epochs it wins a cost tie.
+Retracting a route (an unannounce, or the peer's `ANNOUNCE_END`)
 stops new requests from resolving through it but leaves subscriptions already
 in flight alone: each track runs to its own end or failure, or until its last
 subscriber leaves, which cancels it upstream. On moq-lite 05 and
@@ -136,22 +138,44 @@ without waiting, since it has no FIN to acknowledge.
 
 ### Publisher epochs
 
-An application can identify each publisher instance with a shared `Epoch` from
-`moq-net` or `@moq/net`. It is a lowercase hyphenated UUIDv7, ordered newest
-last, with its wall-clock creation time available as `Epoch::time()` in Rust
-or `Epoch.time(epoch)` in TypeScript. Minting is explicit; publishing does not
-add an epoch automatically.
-
-`Path::join_epoch(Some(&epoch))` and `Path.joinEpoch(name, epoch)` append an
-`@<uuidv7>` segment. `Path::split_epoch()` and `Path.splitEpoch(path)` return
-the name and optional epoch. Only the final segment and canonical UUIDv7 text
-count: `@alice`, bare UUIDs, uppercase UUIDs, and other UUID versions remain
-ordinary path segments. Existing path normalization still applies.
-
-The segment travels as part of the ordinary broadcast path on every supported
-wire version. Pattern grants still match the full path: `room/**` covers an
-epoch-qualified instance, while `room/camera` is an exact name. Epochs do not
-hide a broadcast; a leading `.` in a name segment still does.
+A route may carry an `Epoch`: a UUIDv7 naming the publisher instance behind it,
+ordered newest last, with its creation time available as `Epoch::time()` in
+Rust or `Epoch.time(epoch)` in TypeScript. A path and an epoch name one
+broadcast. The path never changes, so authorization, patterns, and hidden
+names work exactly as without one.
+
+- **Publishing**: the epoch is whatever the route names, and nothing is minted
+  for you. A publisher mints one per run (`Epoch::mint()` with
+  `Route::with_epoch`, or `announce({ epoch: Epoch.mint() })`), so a restart is
+  a new broadcast. Replicas of the same content announce the same one. A route
+  without an epoch, such as a prefix claim, names no instance.
+- **Resolution** ranks the newest epoch first among routes at the same prefix,
+  ahead of cost, and a route without an epoch last. Newest means the latest
+  UUIDv7 timestamp, so ordering instances minted on different hosts trusts
+  their clocks: a restart on a host whose clock runs behind loses to the old
+  instance until that one retracts.
+- **Re-pricing**: announcing again (or `update` on a dynamic route) replaces
+  the whole route, epoch included. Start from the current route, as in
+  `broadcast.route()` or `dynamic.route()`, and change the cost, or the update
+  names another instance.
+- **Resume**: a subscription moves between routes with the same epoch without a
+  seam, continuing from the first frame it lacks. A route without an epoch
+  names no instance, so its subscriptions stay on that route (a transcoder
+  claim stays on the worker that first served it) and end when it goes.
+- **Replacement**: when a newer epoch wins the path, subscriptions to the old
+  one end with `Unroutable`, even ones in flight, and announcement streams see
+  the old route end and the new one start. Clients re-request and get the new
+  broadcast instead of stalling on the old.
+
+The epoch travels on moq-lite 07 in `ANNOUNCE_START`, and relays fill it into
+the `TRACK`, `SUBSCRIBE`, and `FETCH` they send upstream; a publisher refuses a
+request naming another epoch. Older moq-lite versions and moq-transport cannot
+carry it: their routes have no epoch, so they keep their subscriptions on one
+route and see a replacement as an ordinary end and start at the same path. In
+a mixed deployment, where the same content reaches a relay over both an older
+link (no epoch) and a moq-lite 07 link (with one), the epoch-carrying route
+supersedes the other each time it appears, so a flapping moq-lite 07 link cuts
+the viewers resolved through the older one.
 
 ### Hidden broadcasts
 

doc/lib/js/net.md

@@ -9,9 +9,8 @@ description: The pub/sub layer in TypeScript
 
 The TypeScript twin of [`moq-net`](/lib/rs/moq-net): connections, origins,
 broadcasts, tracks, groups, and frames, negotiating moq-lite or moq-transport
-at setup. `Epoch` provides the shared publisher identity, and `Path.splitEpoch`
-and `Path.joinEpoch` carry it in the broadcast path; see
-[publisher epochs](/concept/moq-lite#publisher-epochs).
+at setup. `Epoch` provides the shared publisher identity, carried on each
+route as `route.epoch`; see [publisher epochs](/concept/moq-lite#publisher-epochs).
 
 ```ts
 import * as Moq from "@moq/net";
@@ -93,7 +92,11 @@ Three operations, on an origin:
   invisible and unreachable, for local consumers and peers alike, until
   `broadcast.announce()`.
 - `broadcast.announce(route)` / `broadcast.unannounce()` own that
-  advertisement. Announcing again re-prices the standing route.
+  advertisement. Announcing again replaces the standing route as given, epoch
+  included, so re-price from the current one
+  (`broadcast.announce({ ...broadcast.route, cost })`); another epoch, or
+  none, announces a new broadcast. `Origin.Dynamic` has the same `route` and
+  `update(route)`.
 - `origin.dynamic(prefix, route)` claims `prefix` and every path beneath it
   (`""` claims everything). Hold the returned `Origin.Dynamic` while the
   claim should stay advertised; `close()` retracts it. A request beneath it

doc/lib/rs/moq-net.md

@@ -17,7 +17,7 @@ above ([hang](/lib/rs/hang)); relays and CDNs implement only this.
 
 - **Origins** scope what a session can see, and merge duplicate subscriptions so a broadcast is pulled upstream once no matter how many local readers.
 - **Broadcasts** are created unannounced and invisible to everyone, then announced as an exact route, or served below a prefix with `dynamic`. A consumer of the same origin sees exactly what a peer sees. Discovery accepts pattern unions; events carry the advertised prefix and captures for a complete match.
-- **Epochs** identify publisher instances with a canonical UUIDv7 and explicit path helpers; see [publisher epochs](/concept/moq-lite#publisher-epochs).
+- **Epochs** identify publisher instances with a canonical UUIDv7 carried on each route (`Route::epoch`): the newest wins a path, and only routes with the same epoch resume a subscription; see [publisher epochs](/concept/moq-lite#publisher-epochs).
 - **Patterns** (`Pattern`, `Patterns`) are re-exported from [`moq-pattern`](https://docs.rs/moq-pattern). Literal `Path` stays a coordinate.
 - **Tracks** carry groups with a priority, an optional publisher retention window (`Info::max_age`), and a timescale. Subscribers set their own priority and max age and can change them live.
 - **Groups** are written frame by frame and delivered on independent streams. Old groups are cached for fetch-by-sequence; stale groups are skipped per the subscriber's budget.
@@ -137,9 +137,13 @@ Three operations, on an origin:
   invisible and unroutable, for local consumers and peers alike, until
   `broadcast.announce(route)`.
 - `broadcast.announce(route)` / `broadcast.unannounce()` own that
-  advertisement. Announcing again re-prices the standing route, which competes
-  on cost with remote routes at the same path (a tie goes to the local
-  broadcast). The route retracts on `unannounce()`, `close()`, or the last
+  advertisement. Announcing again replaces the standing route as given, epoch
+  included, so re-price from the current one
+  (`broadcast.announce(broadcast.route().unwrap_or_default().with_cost(c))`);
+  another epoch, or none, announces a new broadcast; `origin::Dynamic` has the
+  same `route()` and `update(route)`. The route competes with
+  remote routes at the same path: the newest epoch wins, then the cheapest (a
+  tie goes to the local broadcast). The route retracts on `unannounce()`, `close()`, or the last
   producer dropping; tracks already in flight carry on to their own end.
 - `broadcast.close()` ends the broadcast for good: it retracts, leaves local
   discovery, and answers every later track lookup with `Unroutable`. Tracks

drafts/draft-lcurley-moq-e2ee.md

@@ -132,21 +132,21 @@ Each instance of a broadcast MUST mint an epoch that no other instance under the
 Two instances MUST NOT share an epoch: they would derive the same keys and collide on nonces.
 Its leading 48-bit timestamp makes epochs sort by creation time and its random bits make collisions negligible.
 
-A protected broadcast is published at `<opaque>/@<epoch>`, where `<opaque>` is the 22-character base64url segment derived from the credential and the application's semantic broadcast name according to {{derive}}, and `<epoch>` is the UUID text.
-The `@` marker is part of the path segment only; the HKDF `bytes(epoch)` input remains the UUID text without `@`.
-The opaque derivation does not include the epoch, so every instance of the same semantic broadcast shares a discovery prefix.
+A protected broadcast is published at `<opaque>`, the 22-character base64url segment derived from the credential and the application's semantic broadcast name according to {{derive}}.
+Each instance announces its epoch as the route's moq-lite Epoch; the HKDF `bytes(epoch)` input is the UUID text.
+The opaque derivation does not include the epoch, so every instance of the same semantic broadcast shares one path.
 The path carries no format or protection marker; for example, the semantic name `meeting.hang` appears only as an input to the opaque derivation.
 A plaintext consumer that opens the protected broadcast fails because it cannot find the plaintext catalog it expects, not because of a path naming rule.
-Subscribers discover instances by the `<opaque>/` prefix and select the greatest epoch, where greatest is newest.
-A subscriber that already knows the full path parses the epoch from its last segment after removing `@`.
+Subscribers resolve `<opaque>` and take the epoch from its route, where relays rank the newest first.
+On a wire that cannot carry the route's epoch, the application supplies it over its own authenticated channel.
 
 The epoch and the path are not secret and are not authenticated.
 A relay that presents a wrong epoch causes authentication failure; a relay that withholds a newer instance denies service.
 Neither can cause a nonce to repeat, because only the publisher instance chooses the epoch it encrypts under.
 
 A restart or replacement of a publisher is a new instance and mints a new epoch.
 Transport sequence numbers therefore restart freely without any coordination between instances.
-Ended instances remain readable at their own path for as long as relays or archives retain them.
+An ended instance stays readable only for as long as relays or archives retain it under its epoch; once a newer epoch wins the shared path, subscribers resolve the newer one.
 
 
 # Canonical Encoding {#encoding}
@@ -364,8 +364,8 @@ This document requests no registrations.
 ## draft-lcurley-moq-e2ee-00
 {:numbered="false"}
 
-- Require canonical UUIDv7 epochs and carry them in `@<epoch>` path segments, leaving HKDF UUID inputs unchanged.
-- Initial `moq-e2ee-00` profile: out-of-band credential, opaque broadcast path with a publisher-minted epoch as its last segment, HKDF physical names and keys, AES-128-GCM payloads, identity bounds, typed failures, and shared primitive vectors.
+- Require canonical UUIDv7 epochs, carried on the route rather than in the path, leaving HKDF UUID inputs unchanged.
+- Initial `moq-e2ee-00` profile: out-of-band credential, opaque broadcast path with a publisher-minted epoch on its route, HKDF physical names and keys, AES-128-GCM payloads, identity bounds, typed failures, and shared primitive vectors.
 
 
 # Acknowledgments