kixelated · Sep 25, 2026 · Sep 25, 2026 · Sep 26, 2026 · Sep 27, 2026 · Sep 28, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md
@@ -234,6 +234,15 @@ and auth root, split by a **tier** label chosen by the auth server's grant or
 possible. [Stats](/concept/stats) describes the paths, tracks, and encodings;
 read them with the [`moq-stats`](https://docs.rs/moq-stats) crate.
 
+`publisher.json` also reports how far behind each broadcast's viewers are. Every
+`interval` the relay samples each subscription's lag, the newest frame produced
+minus the newest frame the viewer acknowledged, into a byte-weighted `lag`
+histogram with buckets at 50 ms, 100 ms, 250 ms, 500 ms, 1 s, 2 s, 5 s, and above.
+`dropped` counts the duration, bytes, and groups of media written to a
+viewer on a group stream that ended before the viewer acknowledged it. Both
+resolve one group at a time, so they overstate lag and drops for long groups;
+see [Lag](/concept/stats#lag).
+
 ## \[iroh]
 
 ```toml

diff --git a/doc/concept/stats.md b/doc/concept/stats.md
@@ -93,6 +93,8 @@ return later as a new broadcast.
     "fetches": 0,
     "bytes": 1048576, "frames": 900, "groups": 30, "datagrams": 0,
     "stale": { "bytes": 0, "frames": 0, "groups": 0, "datagrams": 0 },
+    "lag": { "50ms": 1040000, "1s": 8576 },
+    "dropped": { "duration": 966.5, "bytes": 8576, "groups": 1 },
     "announced": 1, "announced_closed": 0,
     "broadcasts": 3, "broadcasts_closed": 1,
     "subscriptions": 6, "subscriptions_closed": 2
@@ -110,11 +112,47 @@ return later as a new broadcast.
 | `bytes` / `frames` / `groups` | Payload delivered. |
 | `datagrams` | Groups delivered as an unreliable datagram. A subset of `groups`. |
 | `stale` | Payload skipped because it aged past a subscriber's latency budget, with the same four fields. Disjoint from the top-level payload counters. |
+| `lag` | `publisher.json` only: how far behind the viewers' acknowledged media is, as bytes per bucket of media time. See [Lag](#lag). Omitted while empty. |
+| `dropped` | `publisher.json` only: media written to a viewer on a group stream that was reset or abandoned before the viewer acknowledged it, as `duration` (fractional milliseconds), `bytes`, and `groups`. Omitted while empty. |
 
-The last six fields are legacy spellings of the `*_started` and `*_ended`
+The last six fields in the example are legacy spellings of the `*_started` and `*_ended`
 counters, still written so an older consumer reads a newer relay. A reader
 should prefer the canonical name and fall back to the legacy one.
 
+### Lag
+
+Each track subscription has an acknowledged **frontier**: the newest frame
+timestamp the viewer is known to have received. It starts at the track's newest
+frame when the subscription opens, so a backlog the viewer deliberately starts
+behind never counts, and advances when the viewer acknowledges the end (FIN) of
+a group stream. Every stats interval the relay samples each subscription's lag,
+the newest frame the track has produced minus the frontier, or the wall-clock
+time the frontier has stood still while newer media exists if that is larger.
+It adds the bytes the track produced during the interval to the bucket that lag
+falls in, and the broadcast's subscriptions sum into one entry. A subscription
+that ends between two intervals takes one last sample when it closes, so the
+bytes since its previous sample are not lost, even if it opened and closed
+between two ticks.
+
+| Bucket | Lag |
+| --- | --- |
+| `50ms` | under 50 ms |
+| `100ms` | 50 ms to 100 ms |
+| `250ms` | 100 ms to 250 ms |
+| `500ms` | 250 ms to 500 ms |
+| `1s` | 500 ms to 1 s |
+| `2s` | 1 s to 2 s |
+| `5s` | 2 s to 5 s |
+| `inf` | 5 s and above |
+
+Each bucket is a cumulative byte counter, so the difference of two frames is
+the byte-weighted lag distribution over that interval, from which a dashboard
+reads percentiles or a mean. A paused broadcast produces nothing and adds
+nothing. The frontier moves once per group, so a healthy viewer of a stream
+with two-second groups still spreads across the buckets below `2s`; the dropped
+counters likewise count a whole group's written span, including frames the
+viewer did receive.
+
 ### Presence
 
 ```json
@@ -128,7 +166,8 @@ ends on the old one and starts on the new.
 
 ### Counters
 
-Every counter is a cumulative, monotonic unsigned integer. A rate is the
+Every counter is cumulative and monotonic: an unsigned integer, apart from
+`dropped.duration` in fractional milliseconds. A rate is the
 difference between two frames divided by the time between them, and a live
 count is started minus ended. A frame never shows ended above started.
 

diff --git a/quest/m1/qos/README.md b/quest/m1/qos/README.md
@@ -44,14 +44,6 @@ on `main`.
 
 ## Required
 
-- [Lag across a splice](/quest/m1/qos/lag-splice.md) - a route switch
-  neither loses pending lag weight nor keeps weighing a segment replaced
-  before its first frame; the line does not land until it is fixed
-- [Starvation](/quest/m1/qos/starvation.md) - per broadcast, how far behind
-  the acknowledged frontier of its subscriptions is, in media time, plus the
-  media dropped before it was acknowledged
-- [Final lag sample](/quest/m1/qos/final-lag-sample.md) - a closing
-  subscription records its last partial interval instead of losing it
 - [Lag dashboard](/quest/m1/qos/lag-dashboard.md) - the demo stats
   dashboard shows viewer lag percentiles and dropped media
 - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - per

diff --git a/quest/m1/qos/final-lag-sample.md b/quest/m1/qos/final-lag-sample.md
diff --git a/quest/m1/qos/lag-dashboard.md b/quest/m1/qos/lag-dashboard.md
@@ -25,8 +25,3 @@ and per node like the existing counters.
   package is planned.
 
 Public API: none. Wire: none.
-
-## Required
-
-- [Starvation](/quest/m1/qos/starvation.md) - the `lag` histogram and
-  `dropped` counters (#4298)
diff --git a/quest/m1/qos/lag-splice.md b/quest/m1/qos/lag-splice.md
diff --git a/quest/m1/qos/publisher-timeliness.md b/quest/m1/qos/publisher-timeliness.md
@@ -10,8 +10,8 @@ cooperation.
 
 ## Plan
 
-This is the ingress mirror of [starvation](/quest/m1/qos/starvation.md) and
-needs no acknowledgments: the relay is the receiver, and a frame is measured
+This is the ingress mirror of the egress `lag` histogram on `stats::Traffic`
+and needs no acknowledgments: the relay is the receiver, and a frame is measured
 when its last byte arrives, because a partial frame is not useful.
 
 Frame timestamps are relative and jittered with no epoch, so measure each
@@ -27,8 +27,9 @@ milliseconds, and the re-anchor happens on its own as old minima expire.
 Document the window length beside the bucket edges.
 
 Aggregate as a byte-weighted cumulative histogram of drift on the
-`Role::Subscriber` (ingress) rows, with the same bucket edges and the same
-monotonic contract as the starvation histogram. Beside it keep two cumulative
+`Role::Subscriber` (ingress) rows, reusing `stats::Histogram` (its
+`EDGES` and cumulative contract) and its crate-private atomic backing, as the
+egress `lag` field does. Beside it keep two cumulative
 counters: `timestamp_regressions`, frames whose timestamp is below the
 previous group's newest timestamp, and `stalls`, gaps between complete frames
 longer than a documented threshold. Compare only across group boundaries for
@@ -53,8 +54,5 @@ excluded.
 ## Related
 
 - [Untimed model](/quest/m1/untimed-model.md) - pre-lite-05 tracks arrive untimed instead of stamped on arrival
-
-- [Starvation](/quest/m1/qos/starvation.md) - the egress half, same
-  histogram shape
 - [Media stats](/quest/m1/stats/schema.md) - the publisher's own view
   of the same uplink, in the transport section of its stats track
diff --git a/quest/m1/qos/starvation.md b/quest/m1/qos/starvation.md
diff --git a/quest/m1/quest-flat-lines.md b/quest/m1/quest-flat-lines.md
@@ -57,8 +57,7 @@ Remaining:
 
 - Land each line's umbrella PR with `/quest-complete`, then delete its branch:
   #4403 wildcard, #4034 archive, #4039 auth, #4079 cpp, #4519 ffi-shape,
-  #4080 obs-moq-video, #4133 qos (held until
-  [Lag across a splice](/quest/m1/qos/lag-splice.md) is fixed), #4437 rs2ts,
+  #4080 obs-moq-video, #4133 qos, #4437 rs2ts,
-  #4080 obs-moq-video, #4133 qos, #4437 rs2ts,
+  #4080 obs-moq-video, #4133 qos (held until
+  [Lag across a splice](/quest/m1/qos/lag-splice.md) is fixed), #4437 rs2ts,
-  #4080 obs-moq-video, #4133 qos, #4437 rs2ts,
+  #4080 obs-moq-video, #4133 qos (held until
+  [Lag across a splice](/quest/m1/qos/lag-splice.md) is fixed), #4437 rs2ts,
   #4653 test-flakes-2, #4180 transport-upgrade, #4640 tstd. #4162
   (audio-jitter-target) landed, and #4438 folded into rs2ts.
 - Fold #4255 (archive/track-timeline) into the archive branch before #4034

diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md
@@ -72,8 +72,6 @@ consumes them.
 
 - [Scope track priority](/quest/m1/track-priority-scope.md) - the
   per-broadcast fairness policy on cluster sessions
-- [Starvation](/quest/m1/qos/starvation.md) - the first consumer of ACK
-  progress: how far behind viewers are, from the relay's point of view
 - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic
 - [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement
 - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate

diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md
@@ -80,7 +80,5 @@ change.
 
 ## Related
 
-- [Starvation](/quest/m1/qos/starvation.md) - the relay-side signal that
-  shows a starved subscription
 - [Signed priority](/quest/m2/signed-priority.md) - changes the priority type,
   not which streams it competes with