feat(mux): report TS health and the export's release clock

doc/bin/cli.md

@@ -463,7 +463,8 @@ The `stats` and `echo` sinks print reports as JSON lines. `export stats`
 follows one broadcast's stats track until the broadcast ends; `export echo`
 prints `{"broadcast", "feedback"}` for every `.echo` broadcast under
 `--broadcast` as they come and go, reading one that ends for 5 s more for its
-final report. Either sink stops reading a report that grows past 1 MiB.
+final report. Either sink stops reading a report that grows past 8 MiB, twice
+the largest a TS import publishes.
 
 ```bash
 moq ... --broadcast event import --stats ts < feed.ts
@@ -478,6 +479,13 @@ A report holds 1,024 rendition IDs at most: past that, each new ID replaces
 one that has ended.
 [Stats](/concept/stats#media-reports) has the schema.
 
+A TS import adds an `mpegts` section: each elementary stream's access units
+and quiet time, and the TR 101 290 counters it logs. A TS export adds its
+streams' rows and a `release` section: frames dropped late, the margin frames
+arrive with, and its clock's offset and drift from the source. A passthrough
+reports `release` alone at export and neither at import. See
+[MPEG-TS sections](/concept/stats#mpeg-ts-sections).
+
 ## Debugging
 
 `RUST_LOG=debug` prints the negotiated version and every subscription.

doc/concept/stats.md

@@ -39,6 +39,64 @@ it reads and records its newest arrival. See the
 [hang draft](/draft/moq-hang#media-stats) for track framing, field units, and
 the feedback convention.
 
+### MPEG-TS sections
+
+A TS import or export adds sections of its own, which
+`moq_mux::container::ts::stats::Report` reads. As above, counters are
+cumulative and omitted at zero, and a gauge is omitted until it is measured.
+
+`mpegts` holds `streams`, one row per elementary stream keyed by its PID in
+decimal, and the stream-wide counters. A row has `track` (the track suffix),
+`class` (`audio`, `video`, or `data`; an unknown class reads as `data`),
+`units` (access units delivered), and `quiet`, a gauge: milliseconds of
+program clock since its last access unit. Its losses are `resyncs`, bytes
+`discarded` scanning for audio sync, `unconfirmed` frames, `damaged` units,
+`unplaced` units the program clock could not place, the times the stream was
+`refused`, and its shares of `continuityCountError`, `transportError`, and
+`ptsError`.
+
+The stream-wide counters count ETSI TR 101 290 checks at that standard's
+fixed limits:
+
+| Field | Check |
+| --- | --- |
+| `tsSyncLoss` | 1.1 `TS_sync_loss` |
+| `syncByteError` | 1.2 `Sync_byte_error` |
+| `patError` | 1.3 `PAT_error_2` |
+| `continuityCountError` | 1.4 `Continuity_count_error` |
+| `pmtError` | 1.5 `PMT_error_2` |
+| `transportError` | 2.1 `Transport_error` |
+| `crcError` | 2.2 `CRC_error`, on the PAT and PMT only |
+| `pcrRepetitionError` | 2.3a `PCR_repetition_error` |
+| `pcrDiscontinuityIndicatorError` | 2.3b `PCR_discontinuity_indicator_error` |
+| `ptsError` | 2.5 `PTS_error` |
+
+An import grades the stream as it arrived. An export builds every header
+itself and runs no checks, so its counters stay zero and only its rows'
+`units` and `quiet` move. Neither grades the wire a receiver sees downstream.
+The PCR checks are graded on PCR values, not arrival: they speak for the
+encoder's insertion, since the network re-times arrival, and a forward step
+over 100 ms counts as both. 1.6 `PID_error` is covered, more strictly, by each
+row's `units` and `quiet`: a dead video path behind a live mux still sends
+PCR-only packets on its PID, which a packet count reads as live.
+`PCR_accuracy_error` is not measured. No verdict is computed: a sparse stream
+such as SCTE-35 is quiet for seconds by design, so an alarm reads counter
+rates and `quiet` against its own thresholds.
+
+An export also reports `release`, how it keeps up with the source: what it
+drops, trims and never receives, and how its output clock tracks the
+source's. `export ts --passthrough` reports it without `mpegts`.
+
+| Field | Meaning |
+| --- | --- |
+| `dropped` | Frames lost from the output after their stream began: missed their release deadline, or a video track dropped them waiting for its next keyframe. |
+| `trimmed` | Frames dropped before their stream's first went out, so the output starts on a whole group led by a keyframe. Nothing is missing for these. |
+| `gaps` | Times the source skipped media it will never deliver: a group lost or expired upstream, or a resubscription. A declared break is not one. |
+| `margin` | Gauge, milliseconds rounded away from zero: the least time any frame arrived before its deadline over the last second. Negative when one missed, however narrowly. |
+| `offset` | Gauge, milliseconds rounded away from zero: how far the output clock sits from the source's plus the delay. Positive holds frames longer than the delay. The clock pulls it shut over ten minutes. |
+| `drift` | Gauge, parts per million: the source clock's rate against ours, positive running fast. |
+| `outOfTolerance` | Measurements that found the source clock past the 30 ppm ISO/IEC 13818-1 allows, which the output cannot follow. |
+
 ## Broadcasts
 
 Each node publishes under a prefix, `.stats` by default, which

quest/m1/ts-reliability/README.md

@@ -105,6 +105,5 @@ remain with their current quests.
 ## Related
 
 - [TS over RTP legs](/quest/m2/ts-rtp-egress.md) - TS identity alone is not ST 2022-7, which also needs matching RTP headers
-- [TS health counters](/quest/m2/ts-health-stats.md) - ingress and egress evidence need distinct monitoring points
 - [MSFTS mapping](/quest/m3/msfts-convergence.md) - document the exact equivalence and differences between the carriage modes
 

quest/m2/README.md

@@ -144,7 +144,6 @@ ranked just below deterministic TS legs, which it requires.
 - [Probes resume on the peer](/quest/m2/quic-outage-probe.md) - after an outage, the next probe follows the peer's first packet instead of the backed-off timer
 - [Keep-alive from the idle timeout](/quest/m2/quic-keep-alive.md) - the keep-alive interval defaults to a fraction of the negotiated idle timeout; an explicit `quic.keep_alive` overrides
 - [Socket close](/quest/m2/quic-socket-close.md) - moq-tokio's QUIC endpoint releases its socket on close, so it drops its wrapper
-- [TS health stats](/quest/m2/ts-health-stats.md) - the TS counters ride the stats plumbing beside the media counters
 - [Windows.Graphics.Capture](/quest/m2/capture-wgc.md) - the WGC display and window backend verified on real Windows hardware
 - [Windows capture parity](/quest/m2/capture-windows.md) - system audio and a settled app-capture policy
 - [Linux capture parity](/quest/m2/capture-linux.md) - Wayland window/system-audio capture with explicit display-selection and app-capture limits

quest/m2/stats/health.md

@@ -42,7 +42,7 @@ Guidance, to be settled while building:
   starts over rather than going negative.
 - Container sections such as `mpegts` are excluded from the verdict; their
   counters are read by their own consumers
-  ([TS health counters](/quest/m2/ts-health-stats.md)).
+  ([MPEG-TS sections](/doc/concept/stats.md#mpeg-ts-sections)).
 - Thresholds are a documented default the caller can override, not policy
   baked into the types. Start from a few measured cases rather than guesses.
 - A verdict carries its evidence: which inputs drove it and who observed them.
@@ -65,4 +65,3 @@ Public API: new health types in `hang` and `@moq/hang`. Wire: none.
 
 - [QoS](/quest/m2/qos/README.md) - the relay's delivery counters, which a combined downstream verdict also reads
 - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - a new epoch is one way a counter reset shows
-- [TS health counters](/quest/m2/ts-health-stats.md) - container counters kept out of the verdict

quest/m2/stats/rust.md

@@ -41,5 +41,4 @@
 
 ## Related
 
-- [TS health stats](/quest/m2/ts-health-stats.md) - adds TS-specific counters to the reports
 - [Encrypted native CLI](/quest/m2/e2ee/cli.md) - refuses stats and feedback on an encrypted broadcast

rs/moq-cli/src/main.rs

@@ -923,6 +923,7 @@ async fn run_stdout(
 		return subscribe.run().await;
 	};
 	let mut echo = report::Echo::new(echo, subscribe.source().clone(), catalog);
+	let subscribe = subscribe.with_sections(echo.sections());
 	let result = tokio::select! {
 		result = subscribe.run() => result,
 		never = echo.run() => match never {},

rs/moq-cli/src/publish.rs

@@ -606,6 +606,12 @@ async fn decode(
 	// they have to surface as they accumulate rather than at exit.
 	let mut log = ts::stats::Log::default();
 	let mut sampled = tokio::time::Instant::now();
+	let sections = report.as_ref().map(crate::report::Stats::sections);
+	let report_mpegts = |snapshot: &ts::stats::Snapshot| {
+		if let Some(sections) = &sections {
+			sections.set(|report| report.mpegts = Some(snapshot.clone()));
+		}
+	};
 
 	// Run the read/decode loop so an error surfaces here rather than
 	// dropping the decoder (and its tracks) with a bare Error::Dropped.
@@ -626,6 +632,7 @@ async fn decode(
 			if sampled.elapsed() >= ts::stats::Log::INTERVAL {
 				sampled = tokio::time::Instant::now();
 				if let Some(stats) = decoder.stats() {
+					report_mpegts(&stats);
 					log.sample(stats);
 				}
 			}
@@ -656,6 +663,7 @@ async fn decode(
 	// The drain at end of input can publish a frame nothing vouched for, so the
 	// final snapshot is only complete after `finish`.
 	if let Some(stats) = decoder.stats() {
+		report_mpegts(&stats);
 		log.finish(&stats);
 	}
 	match outcome {