From 2c69cbdab9f2d0260a6996a7eb95eb447b483a74 Mon Sep 17 00:00:00 2001
From: enricobuehler <buehler@unom.io>
Date: Mon, 27 Jul 2026 08:41:37 +0200
Subject: [PATCH] =?UTF-8?q?docs(host/stats):=20say=20what=20the=20stats=20?=
 =?UTF-8?q?actually=20measure=20=E2=80=94=20three=20field-triage=20traps?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three lines that each sent the 2026-07 PyroWave field triage down a wrong
path, made honest:

- The 'client accepts streamed AUs … will stream per-slice' log fires
  before the encoder exists and regardless of backend support (only Linux
  direct-NVENC implements chunked polling) — it now states the client
  capability only.
- StatsSample::mbps was documented as 'transmit goodput'; it is attempted
  sealed wire bytes at seal time — AU bytes + shard framing + FEC parity
  (+ PyroWave window padding), not reduced by socket send drops.
- The per-stage split's 'encode' stage is the poll() duration, which is
  ~0 by construction for synchronous backends (PyroWave encodes inside
  submit → its time shows as 'submit') — documented at the split's
  definition so 'encode 0.00' stops reading as an instrumentation hole.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 crates/punktfunk-host/src/native/stream.rs  | 13 +++++++++++--
 crates/punktfunk-host/src/stats_recorder.rs |  4 +++-
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/crates/punktfunk-host/src/native/stream.rs b/crates/punktfunk-host/src/native/stream.rs
index 0be9248a..1d353eb6 100644
--- a/crates/punktfunk-host/src/native/stream.rs
+++ b/crates/punktfunk-host/src/native/stream.rs
@@ -335,6 +335,11 @@ struct FrameMsg {
     /// nor a stats capture is armed). The send thread accumulates them for the web-console sample:
     /// `cap_us` = `try_latest` (ring read + colour convert), `submit_us` = NVENC `encode_picture`
     /// launch, `wait_us` = `lock_bitstream` (the scheduling wait + ASIC encode = the "encode" stage).
+    /// SYNCHRONOUS backends (PyroWave: the whole GPU encode + fence wait runs inside `submit`)
+    /// carry their real encode time in `submit_us`, and the "encode" stage reads ~0 by
+    /// construction — read the pair together (the 2026-07 field triage read "encode 0.00" as an
+    /// instrumentation hole; it's the stage split's shape). The client-facing 0xCF `encode_us`
+    /// is unaffected: its anchor is stamped before `submit`, so it spans both.
     cap_us: u32,
     submit_us: u32,
     wait_us: u32,
@@ -1118,9 +1123,13 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
         tracing::info!("gamescope cursor: compositing the XFixes-sourced pointer into the video");
     }
     if streamed_wire {
+        // Client capability only — whether AUs actually stream per-slice depends on the encoder
+        // backend's `supports_chunked_poll()` (today: Linux direct-NVENC only), which doesn't
+        // exist yet at this point. The old wording ("chunked encoder output will stream
+        // per-slice") sent a 2026-07 field triage chasing a streaming path AMF doesn't have.
         tracing::info!(
-            "client accepts streamed AUs (VIDEO_CAP_STREAMED_AU) — chunked encoder output \
-             will stream per-slice"
+            "client accepts streamed AUs (VIDEO_CAP_STREAMED_AU) — used if this session's \
+             encoder supports chunked output"
         );
     }
     tracing::info!(
diff --git a/crates/punktfunk-host/src/stats_recorder.rs b/crates/punktfunk-host/src/stats_recorder.rs
index f2598c0f..c4b3271f 100644
--- a/crates/punktfunk-host/src/stats_recorder.rs
+++ b/crates/punktfunk-host/src/stats_recorder.rs
@@ -45,7 +45,9 @@ pub struct StatsSample {
     pub fps: f32,
     /// Re-encoded holds/s (source-starvation indicator).
     pub repeat_fps: f32,
-    /// Transmit goodput (Mb/s).
+    /// Attempted sealed wire bytes/s (Mb/s): full UDP payloads at seal time — video AU bytes
+    /// plus shard framing (header + AEAD) plus FEC parity, and for PyroWave's datagram-aligned
+    /// mode the zero-padded window tails. NOT goodput, and NOT reduced by socket send drops.
     pub mbps: f32,
     /// Configured target bitrate.
     pub bitrate_kbps: u32,