From 54cd502009648da7cf290d7c2345c16326689a68 Mon Sep 17 00:00:00 2001 From: npub1cc3ha7z055mu0rwwu7806t2wt8mj3pvu0uv5mfp2c50dahaqhczshdalg6 Date: Sat, 1 Aug 2026 20:29:45 -0400 Subject: [PATCH] docs(desktop): record why G3's max bound cannot be widened The p95 comment claimed 31x of headroom "lets this run on a loaded CI runner," and read as if it justified the whole gate. It justifies the quantile only. A p95 discards its worst samples by construction and so degrades gracefully under load; a max over 200 samples is one observation that any single scheduler preemption exceeds. No budget makes it robust, because that tail belongs to the scheduler. Measured on one 16-core host at the same commit: pass at load ~6, fail at ~31 (p95 65535 us, max 164889 us). Sami measured a run where p95 sat 4x inside budget while max alone blew at 38150 us -- a p95-only gate would have called a 38 ms stall green. That asymmetry is what makes the ignore-plus-native-release placement load-bearing rather than tidy, and it is the reason the repair for a flake here is to fix the host, never to raise the number: a hitch is a max-event, so widening the max is the one change that removes the only assert catching the user-visible failure. Co-authored-by: Dawn (sprout agent) Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com> --- .../crates/buzz-terminal/tests/latency.rs | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/desktop/src-tauri/crates/buzz-terminal/tests/latency.rs b/desktop/src-tauri/crates/buzz-terminal/tests/latency.rs index 9eab0444b..57d672d91 100644 --- a/desktop/src-tauri/crates/buzz-terminal/tests/latency.rs +++ b/desktop/src-tauri/crates/buzz-terminal/tests/latency.rs @@ -22,10 +22,29 @@ use buzz_terminal::{SharedTerminal, Size, Terminal}; /// One frame at 60 Hz. No acquire may exceed this: a single wait this long is /// a dropped frame regardless of how good the distribution looks. +/// +/// Unlike the p95 below, this bound **cannot be protected by headroom**, and +/// that asymmetry is why this test is `#[ignore]`d and run only in release on +/// an idle host. A quantile discards its worst samples by construction, so it +/// degrades gracefully as a machine gets noisy; a maximum over `FRAMES` samples +/// is a single observation, and any one scheduler preemption exceeds it. There +/// is no budget that makes the max arm robust to contention -- the tail it +/// catches belongs to the scheduler, not to this code. +/// +/// Measured on one 16-core host at `FRAMES = 200`: at load average ~6 the gate +/// passes; at ~31 it fails with p95 65535 us / max 164889 us. A run at ambient +/// load produced p95 1023 us -- 4x *inside* budget -- while max alone blew at +/// 38150 us. +/// +/// So the repair for a flake here is to fix the host, never to raise this +/// number. Raising it is the one change that silently removes the only assert +/// that catches the user-visible failure: a hitch is a max-event, and a +/// p95-only gate passes a run containing a 38 ms stall. const FRAME_MICROS: u64 = 16_667; /// p95 budget. Measured at 127 us with F1 on -- 31x of headroom, which is the -/// margin that lets this run on a loaded CI runner without becoming a coin flip. +/// margin that lets *this* arm tolerate a loaded machine without becoming a +/// coin flip. The reasoning covers the quantile only; see `FRAME_MICROS`. const P95_MICROS: u64 = 4_000; /// Frames sampled per arm. Counted rather than timed: sample count under a