ktstr/stats/group.rs
1use super::*;
2
3/// One of the nine dimensions that compose a `GauntletRow`'s
4/// identity in the comparison pipeline: `kernel`, `scheduler`,
5/// `topology`, `work-type`, `project-commit`, `kernel-commit`,
6/// `run-source`, `resolve-source`, `cpu-budget`. Each maps to the corresponding
7/// `RowFilter` field and `GauntletRow` field; the dimension
8/// model lets `compare_partitions` derive its slicing dims and
9/// dynamic pairing key without hardcoding the dimension list at
10/// every call site. Variant names match the CLI flag suffix
11/// (e.g. `Dimension::ProjectCommit` ↔ `--project-commit`,
12/// `Dimension::RunSource` ↔ `--run-source`,
13/// `Dimension::CpuBudget` ↔ `--cpu-budget`) so a reader can map
14/// from operator surface to internal enum without a translation
15/// table.
16///
17/// `scenario` is NOT a dimension — it is the test name and is
18/// always part of the pairing key (you can't compare scenario A
19/// against scenario B; that would compare unrelated tests).
20///
21/// Iteration order via [`Dimension::ALL`] is deterministic and
22/// matches the order operators read in the CLI flags
23/// (`--kernel` / `--scheduler` / `--topology` / `--work-type` /
24/// `--project-commit` / `--kernel-commit` / `--run-source` /
25/// `--resolve-source` / `--cpu-budget`), so generated labels and error messages list
26/// dims in a stable, predictable order.
27#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
28pub enum Dimension {
29 Kernel,
30 Scheduler,
31 Topology,
32 WorkType,
33 ProjectCommit,
34 KernelCommit,
35 RunSource,
36 ResolveSource,
37 CpuBudget,
38}
39
40impl Dimension {
41 /// Every dimension in CLI-flag order. Used by
42 /// [`Self::pairing_dims`] (invoked from `compare_partitions`) to
43 /// compute the pairing-dim complement set (all dims minus slicing
44 /// dims). The sliceable subset [`derive_slicing_dims`] contrasts on
45 /// is [`Self::SLICEABLE`].
46 pub const ALL: &'static [Dimension] = &[
47 Dimension::Kernel,
48 Dimension::Scheduler,
49 Dimension::Topology,
50 Dimension::WorkType,
51 Dimension::ProjectCommit,
52 Dimension::KernelCommit,
53 Dimension::RunSource,
54 Dimension::ResolveSource,
55 Dimension::CpuBudget,
56 ];
57
58 /// The dimensions that may form an A/B CONTRAST (slice). Only the
59 /// version axes are contrastable: comparing across a project commit,
60 /// a kernel version, or a kernel commit is a purposeful "did this
61 /// change regress" question. Every other dimension
62 /// (scheduler/topology/work_type/run_source/resolve_source/cpu_budget)
63 /// is FILTER + PAIRING only — it narrows the cohort and joins A to B,
64 /// but contrasting across it bulk-compares heterogeneous runs
65 /// (different configs/hosts/conditions), which the significance math
66 /// cannot soundly attribute. A cross-config question is answered
67 /// in-test via the Verdict DSL (`better_across_phases`), not here.
68 pub const SLICEABLE: &'static [Dimension] = &[
69 Dimension::Kernel,
70 Dimension::ProjectCommit,
71 Dimension::KernelCommit,
72 ];
73
74 /// Compute pairing dims from a slicing-dim set: every
75 /// dimension in [`Dimension::ALL`] that is NOT in `slicing`,
76 /// in canonical order. This is the dynamic key derivation the
77 /// comparison pipeline uses everywhere — slicing dims define
78 /// the contrast (different on A vs B), pairing dims define
79 /// the join (same across A and B). A non-[`Self::SLICEABLE`] dimension is
80 /// never in `slicing`, so it is always a pairing dim.
81 pub fn pairing_dims(slicing: &[Dimension]) -> Vec<Dimension> {
82 Self::ALL
83 .iter()
84 .copied()
85 .filter(|d| !slicing.contains(d))
86 .collect()
87 }
88
89 /// Operator-readable name for diagnostic and table output.
90 /// Matches the CLI flag suffix (e.g. `--kernel` →
91 /// `"kernel"`, `--work-type` → `"work-type"`). Used in the
92 /// "slicing dimensions: ..." / "pairing on: ..." header
93 /// lines and in the "A and B select identical rows" error.
94 pub fn name(self) -> &'static str {
95 match self {
96 Dimension::Kernel => "kernel",
97 Dimension::Scheduler => "scheduler",
98 Dimension::Topology => "topology",
99 Dimension::WorkType => "work-type",
100 Dimension::ProjectCommit => "project-commit",
101 Dimension::KernelCommit => "kernel-commit",
102 Dimension::RunSource => "run-source",
103 Dimension::ResolveSource => "resolve-source",
104 Dimension::CpuBudget => "cpu-budget",
105 }
106 }
107}
108
109/// Legacy pairing-dim set used by tests that pre-date the
110/// dimensional-slicing refactor. Equivalent to the historical
111/// hardcoded tuple `(scenario, topology, work_type)` — scenario
112/// is always implicit in [`PairingKey::from_row`] and the
113/// remaining two dimensions are listed here. Production
114/// callers (`compare_partitions`) compute pairing dims via
115/// [`Dimension::pairing_dims`] from the slicing-dim derivation;
116/// only test fixtures use this constant directly, so it is gated
117/// behind `#[cfg(test)]`.
118#[cfg(test)]
119pub(crate) const LEGACY_PAIRING_DIMS: &[Dimension] = &[Dimension::Topology, Dimension::WorkType];
120
121/// Derive the set of dimensions on which `filter_a` and
122/// `filter_b` differ. These are the SLICING dimensions —
123/// dimensions on which the two sides select disjoint cohorts and
124/// therefore form the A/B contrast. The complement (every other
125/// dimension) is the PAIRING-key dimension set used by
126/// `compare_rows` to join A-side rows against B-side rows.
127///
128/// Comparison shape per dimension: every dim uses the same
129/// SORTED-DEDUPED `Vec<&str>` comparison — order and multiplicity
130/// don't matter (`--a-kernel 6.14 --a-kernel 6.15` and
131/// `--b-kernel 6.15 --b-kernel 6.14` are NOT a slice). All nine
132/// dimensions are repeatable Vec filters; the previously
133/// `Option<String>`-typed `scheduler` / `topology` / `work_type`
134/// dims were promoted to `Vec<String>` so the operator-visible
135/// shape is uniform across every dimension.
136///
137/// Returns dimensions in canonical ([`Dimension::ALL`]) order so callers
138/// (header lines, error messages, side labels) get a stable presentation.
139/// Only a [`Dimension::SLICEABLE`] dimension can be a slicing dim; the
140/// non-sliceable dims are filter + pairing only and are only ever set via a
141/// single shared `--<x>` filter (applied to BOTH sides), so they can never
142/// differ A↔B — the walk skips them.
143pub fn derive_slicing_dims(filter_a: &RowFilter, filter_b: &RowFilter) -> Vec<Dimension> {
144 let mut out = Vec::new();
145 for &dim in Dimension::SLICEABLE {
146 let differs = match dim {
147 Dimension::Kernel => sorted_dedup(&filter_a.kernels) != sorted_dedup(&filter_b.kernels),
148 Dimension::ProjectCommit => {
149 sorted_dedup(&filter_a.project_commits) != sorted_dedup(&filter_b.project_commits)
150 }
151 Dimension::KernelCommit => {
152 sorted_dedup(&filter_a.kernel_commits) != sorted_dedup(&filter_b.kernel_commits)
153 }
154 // Non-sliceable dims are filter + pairing only (see
155 // [`Dimension::SLICEABLE`]); the walk never reaches them.
156 Dimension::Scheduler
157 | Dimension::Topology
158 | Dimension::WorkType
159 | Dimension::RunSource
160 | Dimension::ResolveSource
161 | Dimension::CpuBudget => {
162 unreachable!("non-sliceable dimension {dim:?} in SLICEABLE walk")
163 }
164 };
165 if differs {
166 out.push(dim);
167 }
168 }
169 out
170}
171
172fn sorted_dedup(v: &[String]) -> Vec<&str> {
173 let mut s: Vec<&str> = v.iter().map(String::as_str).collect();
174 s.sort_unstable();
175 s.dedup();
176 s
177}
178
179/// Render a side's filter values into a column-header label for
180/// the comparison table. `dims` is the slicing-dimension set —
181/// the only dims whose values vary between A and B. The label
182/// concatenates each dim's per-side filter value(s) with `:`
183/// between dim values (e.g. `"6.14.2:scx_rusty"` when both
184/// `kernel` and `scheduler` slice). For multi-value Vec filters
185/// (kernels, commits) the values join with `|` when there
186/// are ≤3; longer lists collapse to `"A"` or `"B"` (the bare
187/// side label) to keep the column header readable.
188///
189/// `bare_label` is `"A"` / `"B"`, used as the fallback when a
190/// slicing dim's filter has more than 3 values OR the slicing
191/// dim's filter is empty on this side (the slice exists because
192/// the OTHER side populated the filter — the empty-side label is
193/// the bare letter).
194pub(crate) fn render_side_label(
195 filter: &RowFilter,
196 dims: &[Dimension],
197 bare_label: &str,
198) -> String {
199 if dims.is_empty() {
200 return bare_label.to_string();
201 }
202 let mut parts: Vec<String> = Vec::new();
203 for &dim in dims {
204 let part = match dim {
205 Dimension::Kernel => render_vec_dim(&filter.kernels, bare_label),
206 Dimension::Scheduler => render_vec_dim(&filter.schedulers, bare_label),
207 Dimension::Topology => render_vec_dim(&filter.topologies, bare_label),
208 Dimension::WorkType => render_vec_dim(&filter.work_types, bare_label),
209 Dimension::ProjectCommit => render_vec_dim(&filter.project_commits, bare_label),
210 Dimension::KernelCommit => render_vec_dim(&filter.kernel_commits, bare_label),
211 Dimension::RunSource => render_vec_dim(&filter.run_sources, bare_label),
212 Dimension::ResolveSource => render_vec_dim(&filter.resolve_sources, bare_label),
213 Dimension::CpuBudget => render_vec_dim(&filter.cpu_budgets, bare_label),
214 };
215 parts.push(part);
216 }
217 parts.join(":")
218}
219
220/// `≤3` values: join with `|`. `>3` values: collapse to
221/// `bare_label`. Empty Vec: also bare label (slicing exists
222/// because the OTHER side populated the same dim).
223fn render_vec_dim(values: &[String], bare_label: &str) -> String {
224 if values.is_empty() || values.len() > 3 {
225 bare_label.to_string()
226 } else {
227 let mut sorted: Vec<&str> = values.iter().map(String::as_str).collect();
228 sorted.sort_unstable();
229 sorted.join("|")
230 }
231}
232
233/// Dynamic pairing key for [`compare_rows_by`] — the tuple of
234/// values on every NON-slicing dimension, plus the always-pinned
235/// `scenario`. Two rows pair iff their dynamic keys match.
236///
237/// Stored as a `Vec<String>` so the same struct shape works for
238/// any `pairing_dims` slice (the alternative — a tuple of
239/// `Option<&str>` per dim — would force every consumer to know
240/// the dim list at compile time, defeating the point of
241/// dimension-set parametrisation).
242///
243/// First element is always `scenario`; subsequent elements
244/// follow `pairing_dims` order (which is itself
245/// [`Dimension::ALL`] order minus the slicing dims).
246#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize)]
247pub(crate) struct PairingKey(pub Vec<String>);
248
249impl PairingKey {
250 /// Extract the pairing key for `row` given the list of
251 /// dimensions to include. The scenario is ALWAYS the first
252 /// component; the `pairing_dims` list controls the rest.
253 /// Each non-scenario dim contributes a single string slot:
254 /// `Option<String>` fields render `None` as the empty
255 /// string, `Vec<String>` fields render as a sorted-deduped
256 /// `|`-joined string so the same set produces the same key
257 /// regardless of input order.
258 ///
259 /// Commit dimensions (`ProjectCommit`, `KernelCommit`) strip the
260 /// trailing `-dirty` suffix before contributing to the key.
261 /// Without the strip, a clean run at HEAD `abc1234` and a
262 /// dirty run at the same HEAD (`abc1234-dirty`) would shatter
263 /// into two separate pairing buckets, defeating
264 /// [`group_and_average_by`]'s `+mixed` cohort detection — that
265 /// helper can only surface "this aggregate has both clean and
266 /// dirty contributors" when the two contributors actually land
267 /// in the same group. Stripping at the key level pairs them by
268 /// canonical hex; the per-row `-dirty` distinction is preserved
269 /// downstream in the aggregate's `commit` / `kernel_commit`
270 /// field via the `+mixed` marker in
271 /// `group_and_average_by`'s `render_mixed_dirty` helper.
272 pub fn from_row(row: &GauntletRow, pairing_dims: &[Dimension]) -> Self {
273 let mut parts = Vec::with_capacity(2 + pairing_dims.len());
274 parts.push(row.scenario.clone());
275 // Throughput-denomination era is ALWAYS the second component (not an
276 // operator Dimension): the throughput rate keys kept their names
277 // across the wall→CPU-second denomination change, so a wall-era row
278 // must never pair with — or group-average into — a cpu-era row.
279 // Slot index 1 is a stable contract: `denomination_agnostic` blanks
280 // it to detect cross-era near-misses for the compare diagnostic.
281 parts.push(row.throughput_denomination.as_str().to_string());
282 for &dim in pairing_dims {
283 parts.push(match dim {
284 Dimension::Kernel => row.kernel_version.clone().unwrap_or_default(),
285 Dimension::Scheduler => row.scheduler.clone(),
286 Dimension::Topology => row.topology.clone(),
287 Dimension::WorkType => row.work_type.clone(),
288 Dimension::ProjectCommit => commit_pairing_key_part(&row.commit),
289 Dimension::KernelCommit => commit_pairing_key_part(&row.kernel_commit),
290 Dimension::RunSource => row.run_source.clone().unwrap_or_default(),
291 Dimension::ResolveSource => row.resolve_source.clone().unwrap_or_default(),
292 // Cross-budget rows never pair: a row's budget value
293 // becomes part of its pairing key (None -> empty, distinct
294 // from any real budget). A skip (None) only pairs with
295 // another skip.
296 Dimension::CpuBudget => row.cpu_budget.map(|n| n.to_string()).unwrap_or_default(),
297 });
298 }
299 PairingKey(parts)
300 }
301
302 /// The same key with the throughput-denomination slot (index 1, see
303 /// [`Self::from_row`]) blanked. Two rows whose full keys differ but whose
304 /// denomination-agnostic keys match are the SAME logical run pair split
305 /// only by the wall→CPU-second denomination change — the compare path
306 /// counts these as `denomination_mismatches` so the refusal to pair them
307 /// is flagged, not silent.
308 pub fn denomination_agnostic(&self) -> PairingKey {
309 let mut parts = self.0.clone();
310 if parts.len() > 1 {
311 parts[1] = String::new();
312 }
313 PairingKey(parts)
314 }
315
316 /// Human-readable `/`-joined label WITHOUT the throughput-denomination
317 /// slot: the denomination is a schema-era marker, not row identity an
318 /// operator narrows by, and stuttering `wall`/`cpu_sec` into every
319 /// finding label would bloat the tables for zero disambiguation (a
320 /// mixed-era cohort never pairs, so a rendered pair is single-era by
321 /// construction). Render sites use this; the raw `self.0` remains the
322 /// join/uniqueness key.
323 pub fn label(&self) -> String {
324 let mut parts: Vec<&str> = self.0.iter().map(String::as_str).collect();
325 if parts.len() > 1 {
326 parts.remove(1);
327 }
328 parts.join("/")
329 }
330}
331
332/// Strip the trailing `-dirty` suffix from a commit dimension's
333/// value before it contributes to a [`PairingKey`]. `None` and
334/// already-clean values pass through unchanged (`None` → empty
335/// string; `Some("abc1234")` → `"abc1234"`); a dirty value
336/// (`Some("abc1234-dirty")`) is canonicalized to `"abc1234"` so
337/// it pairs with its clean sibling.
338///
339/// Used by [`PairingKey::from_row`] for both the `ProjectCommit`
340/// and `KernelCommit` arms; the per-row `-dirty` distinction is
341/// preserved separately by [`group_and_average_by`] via its
342/// dirty-tracking accumulator and `+mixed` marker.
343fn commit_pairing_key_part(value: &Option<String>) -> String {
344 let Some(s) = value.as_deref() else {
345 return String::new();
346 };
347 s.strip_suffix("-dirty").unwrap_or(s).to_string()
348}
349
350/// One aggregated `GauntletRow` produced by `group_and_average_by`,
351/// plus the pass-bookkeeping needed to render the per-group summary
352/// block (`N/M passed` + the `(S skip, I inc, F fail)` breakdown).
353///
354/// `row` carries arithmetic-mean metric values across every real
355/// Pass contributor in the group; the (`scenario`, `topology`,
356/// `work_type`, `scheduler`, `kernel_version`) identity is taken
357/// verbatim from the first contributor in iteration order — every
358/// contributor in the group shares the identity tuple by
359/// construction (`scenario`, `topology`, and `work_type` ARE the
360/// group key, and `scheduler` / `kernel_version` are
361/// typed-filter-narrowed at the call site so they can only vary if
362/// the operator passed no `--scheduler` / `--kernel` filter).
363///
364/// The verdict bits on `row` (`passed`, `skipped`, `inconclusive`)
365/// fold under the strict 4-state
366/// `Fail > Inconclusive > Pass > Skip` lattice: any failing
367/// contributor sets the aggregate to Fail (`passed=false`,
368/// `inconclusive=false`, `skipped=false`); else any inconclusive
369/// contributor sets `inconclusive=true`; else any skipped
370/// contributor sets `skipped=true`; only an all-pass cohort yields
371/// `passed=true`. The lattice mechanics match
372/// `GauntletRow::is_pass`'s triple-conjunct, so the aggregated
373/// row's accessor reads honestly. Aggregate rows that are not real
374/// Pass route the pair through `compare_rows_by`'s
375/// `excluded_pairs` gate.
376///
377/// `passes_observed`, `skips_observed`, `inconclusives_observed`,
378/// `failures_observed` and `total_observed` count contributors per
379/// the strict 4-state mutex: the four bucket counters sum to
380/// `total_observed` because every contributor falls into exactly
381/// one bucket. Only real Pass contributors feed the per-row sums —
382/// failing, inconclusive, and skipped contributors all carry no
383/// comparable per-run signal (failure-mode telemetry; "couldn't
384/// evaluate" non-signal; "didn't run" non-signal). When no
385/// contributor passed cleanly the running sum is zero and the
386/// aggregate `row` carries default-zero metric values plus
387/// `passed = false` — the downstream `excluded_pairs` gate then
388/// drops the pair from the regression math.
389#[derive(Clone, Debug)]
390#[non_exhaustive]
391pub struct AveragedGroup {
392 /// Aggregated row carrying arithmetic-mean metric values plus
393 /// the lattice-folded `(passed, skipped, inconclusive)` bits
394 /// matching the `Fail > Inconclusive > Pass > Skip`
395 /// dominance. `passed` is true only when every contributor was
396 /// a real pass; `inconclusive` fires when at least one
397 /// contributor was Inconclusive and none failed; `skipped`
398 /// fires when at least one contributor was Skip and none
399 /// failed or was Inconclusive. Fed directly into
400 /// `compare_rows` (averaging is the fixed compare_partitions fold).
401 pub row: GauntletRow,
402 /// Number of contributors that were a real pass
403 /// (`is_pass() == true`). Renders as the numerator of the
404 /// per-group `N/M` summary.
405 pub passes_observed: u32,
406 /// Number of contributors that were Skip (`is_skip() == true`).
407 /// Surfaced in the per-group rendering as the "S skipped"
408 /// breakdown so an operator can distinguish "scenario didn't
409 /// run" from real failures.
410 pub skips_observed: u32,
411 /// Number of contributors that were Inconclusive
412 /// (`is_inconclusive() == true`). Surfaced in the per-group
413 /// rendering as the "I inconclusive" breakdown so an operator
414 /// can distinguish "couldn't evaluate" from real failures —
415 /// same defense-in-depth pattern as
416 /// `format_dimension_summary`'s inconc bucket.
417 pub inconclusives_observed: u32,
418 /// Number of contributors that were a real Fail
419 /// (`is_fail() == true`). Surfaced in the per-group rendering
420 /// as the "F failed" breakdown.
421 pub failures_observed: u32,
422 /// Total contributors in the group (`= group.len()`). Renders
423 /// as the denominator of the per-group `N/M` summary.
424 /// Mechanically:
425 /// `total_observed == passes_observed + skips_observed +
426 /// inconclusives_observed + failures_observed`
427 /// under the strict 4-state mutex.
428 pub total_observed: u32,
429}
430
431/// Per-row dirty-status update used by [`group_and_average_by`] to
432/// detect when a group's contributors disagree on the `-dirty`
433/// suffix for a commit dimension. `value` is `Some(hex)` /
434/// `Some(hex-dirty)` / `None`; the function flips `any_clean` if
435/// the value lacks the `-dirty` suffix and `any_dirty` if it
436/// carries one. `first_base` records the first un-suffixed form
437/// seen (used to render the `+mixed` marker against a canonical
438/// hex even when `acc.first` happens to be the dirty form).
439///
440/// Per-row scope spans EVERY contributor (passing, failing,
441/// skipped). Mixed-dirty is metadata about the cohort's working-
442/// tree state, not about which contributors succeeded — surfacing
443/// it only across passes would hide WIP-vs-committed disagreement
444/// that the operator needs to know about. `None` values do not
445/// flip either flag and do not seed `first_base`.
446fn update_dirty_tracking(
447 value: &Option<String>,
448 any_clean: &mut bool,
449 any_dirty: &mut bool,
450 first_base: &mut Option<String>,
451) {
452 let Some(s) = value.as_deref() else { return };
453 let (base, is_dirty) = match s.strip_suffix("-dirty") {
454 Some(base) => (base, true),
455 None => (s, false),
456 };
457 if is_dirty {
458 *any_dirty = true;
459 } else {
460 *any_clean = true;
461 }
462 if first_base.is_none() {
463 *first_base = Some(base.to_string());
464 }
465}
466
467/// Render the aggregate's commit string for one dimension
468/// (project_commit or kernel_commit) given the cohort-wide
469/// dirty/clean tracking state. When `any_clean && any_dirty` for
470/// the same un-suffixed hex, the rendered form is
471/// `Some("{first_base}+mixed")`; otherwise the function returns
472/// `acc.first.commit` (or `acc.first.kernel_commit`) verbatim,
473/// preserving the existing first-seen behaviour for homogeneous
474/// cohorts (every contributor clean, every contributor dirty, or
475/// every contributor `None`).
476///
477/// `first_base` is the canonical un-suffixed hex captured by
478/// [`update_dirty_tracking`]; using it (rather than stripping
479/// `acc.first.commit`) ensures the rendered form is `abc1234+mixed`
480/// regardless of whether the first contributor was clean or dirty.
481fn render_mixed_dirty(
482 any_clean: bool,
483 any_dirty: bool,
484 first_base: &Option<String>,
485 first_commit: &Option<String>,
486) -> Option<String> {
487 if any_clean
488 && any_dirty
489 && let Some(base) = first_base
490 {
491 return Some(format!("{base}+mixed"));
492 }
493 first_commit.clone()
494}
495
496/// Per-pairing-group fold accumulator for [`group_and_average_by`].
497/// Built via [`Accumulator::new`] from the group's first contributor,
498/// fed one contributor at a time via [`Accumulator::observe`], and
499/// folded into the emitted [`AveragedGroup`] via
500/// [`Accumulator::into_averaged_group`]. Split out of
501/// `group_and_average_by` only to satisfy the source-function size
502/// guard — the field set and fold math are unchanged from the
503/// in-function definition.
504struct Accumulator<'a> {
505 first: &'a GauntletRow,
506 total_observed: u32,
507 passes_observed: u32,
508 skips_observed: u32,
509 inconclusives_observed: u32,
510 failures_observed: u32,
511 any_skipped: bool,
512 any_failed: bool,
513 any_inconclusive: bool,
514 any_expected_failure: bool,
515 // Tracks whether contributors disagree on the `-dirty`
516 // suffix for the project_commit / kernel_commit dimensions.
517 // `any_*_clean` is true if any contributor's value is the
518 // un-suffixed form; `any_*_dirty` is true if any contributor
519 // ends in `-dirty`. When BOTH are true the aggregate is
520 // mixed-dirty and the rendered `commit` / `kernel_commit`
521 // gets a `+mixed` marker so downstream readers don't see a
522 // single arbitrary contributor's status. Tracked across
523 // EVERY contributor (passing, failing, skipped) — a mixed
524 // working-tree state is metadata about the cohort, not
525 // about the metric mean. Empty / `None` values are ignored
526 // and do not flip either flag.
527 any_project_clean: bool,
528 any_project_dirty: bool,
529 any_kernel_clean: bool,
530 any_kernel_dirty: bool,
531 // First-seen un-suffixed (clean-form) project / kernel
532 // commit string. Held separately from `first` because
533 // `first.commit` may be `Some("abc1234-dirty")` when the
534 // first contributor was dirty but later contributors carry
535 // the clean form — the rendered `+mixed` marker should
536 // still attach to the canonical un-suffixed hex so the
537 // operator sees `abc1234+mixed` not `abc1234-dirty+mixed`.
538 first_project_base: Option<String>,
539 first_kernel_base: Option<String>,
540 // Sums across passing+non-skipped contributors only.
541 // Counts are tracked per ext_metric key separately because
542 // a key may be absent from some contributors.
543 // Per-row sum for mean-fold fields (Counter / Gauge(Last) /
544 // Gauge(Avg) — though no typed Gauge(Avg) field exists
545 // today). Arithmetic mean across runs is the operator-
546 // facing cohort-comparison default; per-RUN totals are
547 // averaged to produce a comparable per-run quantity
548 // across cohorts of different run counts.
549 sum_spread: f64,
550 sum_migrations: u64,
551 sum_migration_ratio: f64,
552 sum_stuck_count: f64,
553 sum_fallback_count: i64,
554 sum_keep_last_count: i64,
555 sum_total_iterations: u64,
556 max_host_dilation: Option<f64>,
557 // sum_page_locality + sum_cross_node_mig removed: both NUMA roll-ups are now
558 // ext-sourced (worst_page_locality = WorstLowest, worst_cross_node_migration_ratio
559 // = WorstCrossNodeRatio), re-pooled from the per-phase carriers and
560 // cross-run-MEAN-folded via the ext fold like the other migrated worst_*
561 // selectors — not typed GauntletRow columns, so no per-row group-average
562 // accumulators.
563 // Per-row MAX-fold for Peak-kind fields. Per
564 // `MetricKind::Peak` contract, cross-RUN aggregation
565 // surfaces the worst-instant observed across the cohort —
566 // averaging Peak across runs dilutes the high-water signal
567 // (a 1-run spike at 100 averaged with 4 runs at 0 reports
568 // 20, hiding the actual peak). MAX preserves "did this
569 // peak ever fire in this cohort".
570 max_gap_ms: u64,
571 max_imbalance_ratio: f64,
572 max_max_dsq_depth: u32,
573 // Per-ext-metric (value, weight) pairs, accumulated across
574 // contributors. At emit time the kind-aware fold dispatches
575 // each key through `aggregate_samples` with `Some(&weights)`
576 // so Gauge(Avg) metrics get a weighted mean (per the F-C
577 // fix on aggregate_samples) and other kinds fold by their
578 // own semantics. Unregistered metric names (no MetricDef)
579 // fall back to arithmetic mean — same legacy semantic the
580 // previous (sum, u32) shape produced.
581 ext_pairs: BTreeMap<String, Vec<(f64, usize)>>,
582 // Union of the Dynamic monotonic-counter ext keys across contributors
583 // (`GauntletRow::ext_counter_keys`). `fold_ext_metrics` SUM-folds these
584 // instead of averaging — they are not in the static `METRICS` registry, so
585 // `metric_def` can't classify them. Carried onto the aggregated row so a
586 // second-level cross-RUN fold keeps SUM-folding them.
587 ext_counter_keys: BTreeSet<String>,
588 // Sum of `run_sample_count` across contributors. Carries
589 // through to the aggregated row's `run_sample_count` so a
590 // downstream cross-RUN consumer that further folds these
591 // already-aggregated rows can apply the same weighted
592 // semantic. Currently no typed Gauge(Avg) field exists
593 // (imbalance_ratio is registered as `max_imbalance_ratio`
594 // kind=Peak, NOT Gauge(Avg) — the Gauge(Avg) sibling
595 // `avg_imbalance_ratio` lands in ext_metrics where the
596 // weighted-mean dispatch already fires); the sum is
597 // preserved here for future typed-field Gauge(Avg)
598 // additions and for downstream cohort-of-cohort
599 // aggregation that wants a meaningful weight.
600 sum_run_sample_count: usize,
601}
602
603impl<'a> Accumulator<'a> {
604 /// Seed an accumulator from the group's first contributor.
605 /// Identity is taken from `first`; every counter / sum / max
606 /// starts at its zero value. `observe` (called once per
607 /// contributor, including `first`) performs the per-row fold.
608 fn new(first: &'a GauntletRow) -> Self {
609 Accumulator {
610 first,
611 total_observed: 0,
612 passes_observed: 0,
613 skips_observed: 0,
614 inconclusives_observed: 0,
615 failures_observed: 0,
616 any_skipped: false,
617 any_failed: false,
618 any_inconclusive: false,
619 any_expected_failure: false,
620 any_project_clean: false,
621 any_project_dirty: false,
622 any_kernel_clean: false,
623 any_kernel_dirty: false,
624 first_project_base: None,
625 first_kernel_base: None,
626 sum_spread: 0.0,
627 sum_migrations: 0,
628 sum_migration_ratio: 0.0,
629 sum_stuck_count: 0.0,
630 sum_fallback_count: 0,
631 sum_keep_last_count: 0,
632 sum_total_iterations: 0,
633 max_host_dilation: None,
634 max_gap_ms: 0,
635 max_imbalance_ratio: 0.0,
636 max_max_dsq_depth: 0,
637 ext_pairs: BTreeMap::new(),
638 ext_counter_keys: BTreeSet::new(),
639 sum_run_sample_count: 0,
640 }
641 }
642
643 /// Fold one contributor into the accumulator. Called once per
644 /// row in the group (including the group's first contributor).
645 /// Skip / fail / inconclusive contributors flip their verdict
646 /// bits and return early without feeding the metric sums; only
647 /// real passes contribute to the per-row sums and maxes.
648 fn observe(&mut self, row: &GauntletRow) {
649 self.total_observed += 1;
650 // Dirty-status tracking spans ALL contributors. Same hex
651 // with mixed dirty/clean across the cohort is the case the
652 // `+mixed` marker exists to surface — the per-row scope
653 // (passing, failing, skipped) is irrelevant since the
654 // marker describes WIP-vs-committed disagreement among the
655 // contributors, not their metric outcomes.
656 update_dirty_tracking(
657 &row.commit,
658 &mut self.any_project_clean,
659 &mut self.any_project_dirty,
660 &mut self.first_project_base,
661 );
662 update_dirty_tracking(
663 &row.kernel_commit,
664 &mut self.any_kernel_clean,
665 &mut self.any_kernel_dirty,
666 &mut self.first_kernel_base,
667 );
668 if row.expected_failure {
669 // An expect_err / expect_auto_repro run inverted to a pass:
670 // OR the flag so the aggregated row stays OUT of the
671 // ab-compare regression math (its telemetry is
672 // failure-mode-dominated). Its metrics may still fold into
673 // the cohort sums below, but compare_rows_by excludes any
674 // expected_failure row, so the aggregate is never read.
675 self.any_expected_failure = true;
676 }
677 if row.is_skip() {
678 self.any_skipped = true;
679 self.skips_observed += 1;
680 return;
681 }
682 if row.is_fail() {
683 self.any_failed = true;
684 self.failures_observed += 1;
685 return;
686 }
687 if row.is_inconclusive() {
688 // Inconclusive contributors are not passes (the gate
689 // could not be evaluated) and carry no measured signal
690 // worth folding into the cohort means. Track the bit
691 // for the aggregated verdict's `inconclusive` field
692 // (so the aggregate row reads Inconclusive in the
693 // `Fail > Inconclusive > Pass > Skip` lattice when no
694 // contributor failed) and skip the per-row sums.
695 self.any_inconclusive = true;
696 self.inconclusives_observed += 1;
697 return;
698 }
699 self.passes_observed += 1;
700 self.sum_spread += row.spread;
701 self.sum_migrations = self.sum_migrations.saturating_add(row.migrations);
702 self.sum_migration_ratio += row.migration_ratio;
703 self.sum_stuck_count += row.stuck_count;
704 self.sum_fallback_count = self.sum_fallback_count.saturating_add(row.fallback_count);
705 self.sum_keep_last_count = self.sum_keep_last_count.saturating_add(row.keep_last_count);
706 self.sum_total_iterations = self
707 .sum_total_iterations
708 .saturating_add(row.total_iterations);
709 if let Some(dilation) = row.host_dilation.filter(|d| d.is_finite()) {
710 self.max_host_dilation = Some(
711 self.max_host_dilation
712 .map_or(dilation, |current| current.max(dilation)),
713 );
714 }
715 // Peak-kind typed fields: cross-RUN aggregation surfaces
716 // the worst-instant observed across the cohort, NOT the
717 // arithmetic mean (which dilutes a single peak across
718 // many quiet runs and hides the high-water signal).
719 self.max_gap_ms = self.max_gap_ms.max(row.gap_ms);
720 if row.imbalance_ratio > self.max_imbalance_ratio {
721 self.max_imbalance_ratio = row.imbalance_ratio;
722 }
723 self.max_max_dsq_depth = self.max_max_dsq_depth.max(row.max_dsq_depth);
724 self.sum_run_sample_count = self
725 .sum_run_sample_count
726 .saturating_add(row.run_sample_count);
727 // Floor the cross-RUN weight at 1: a passing run that emitted this ext
728 // key contributes one observation to a Gauge(Avg) weighted mean, never
729 // zero-weighted out of a mixed cohort. A run with run_sample_count==0
730 // (e.g. snapshot-bridge-sourced metrics with no monitor samples) would
731 // otherwise be silently dropped from the mean. Matches the .max(1) floors
732 // at run_metrics.rs (populate_run_ext_metrics_from_phases) and
733 // stats_types.rs (merge_metric_values).
734 for (k, v) in &row.ext_metrics {
735 self.ext_pairs
736 .entry(k.clone())
737 .or_default()
738 .push((*v, row.run_sample_count.max(1)));
739 }
740 // Union the Dynamic monotonic-counter key tags across contributors.
741 // Load-bearing, NOT merely defensive: per-run bpf-field resolution (and
742 // which topology levels are present) can vary within a pairing group, so
743 // a key tagged in only some rows must still be recognized as a counter
744 // for the whole group. fold_ext_metrics SUM-folds the union, not means.
745 self.ext_counter_keys
746 .extend(row.ext_counter_keys.iter().cloned());
747 }
748
749 /// Emit the folded [`AveragedGroup`] for this group. Identity
750 /// fields are first-seen; metric fields are the kind-correct
751 /// cross-RUN fold (mean for Counter / mean-fold, MAX for Peak,
752 /// rounded mean for integer-typed fields); the verdict bits
753 /// fold under the `Fail > Inconclusive > Pass > Skip` lattice.
754 fn into_averaged_group(self) -> AveragedGroup {
755 let acc = self;
756 let n = acc.passes_observed;
757 let denom = if n == 0 { 1.0 } else { f64::from(n) };
758 // Rounded mean for integer-typed Counter / mean-fold
759 // fields. When n == 0 the sums are all zero, so dividing
760 // by 1.0 still yields 0 — the aggregate's passed=false
761 // routes the pair through excluded_pairs downstream and
762 // the metrics are never consulted. Peak-kind integer
763 // fields (max_dsq_depth) take the MAX-fold path directly
764 // and don't need a rounding helper.
765 let round_u64 = |sum: u64| -> u64 { (sum as f64 / denom).round() as u64 };
766 let round_i64 = |sum: i64| -> i64 { (sum as f64 / denom).round() as i64 };
767
768 // Mixed-dirty markers. When the cohort contains both a
769 // clean-form and dirty-form contributor for the same hex
770 // (e.g. some sidecars from a clean tree, others from a
771 // -dirty WIP), the rendered commit field carries `+mixed`
772 // appended to the canonical un-suffixed hex. The
773 // alternative — taking `acc.first.commit` verbatim — would
774 // hide WIP-vs-committed disagreement, presenting `abc1234`
775 // when half the contributors actually came from a dirty
776 // tree (or `abc1234-dirty` when half came from a clean
777 // tree). Operators reading averaged stats need to know the
778 // cohort spanned a working-tree state change, since that
779 // changes the meaning of the metric mean. `+mixed` is the
780 // chosen separator (not `-mixed`) so it cannot be confused
781 // with the existing `-dirty` suffix grammar — `dirty` is a
782 // per-record property, `mixed` is a cohort-level property.
783 let project_commit_rendered = render_mixed_dirty(
784 acc.any_project_clean,
785 acc.any_project_dirty,
786 &acc.first_project_base,
787 &acc.first.commit,
788 );
789 let kernel_commit_rendered = render_mixed_dirty(
790 acc.any_kernel_clean,
791 acc.any_kernel_dirty,
792 &acc.first_kernel_base,
793 &acc.first.kernel_commit,
794 );
795 // ext_metrics is built BEFORE the struct so Rate keys can be
796 // re-derived from the folded components as a post-pass. Rate and PerPhase
797 // are skipped here: Rate's components survive cross-RUN as their own ext
798 // keys so it re-derives Σnum/Σdenom (folding two ready-made ratios would
799 // lose the re-pool, and routing a Rate through
800 // aggregate_samples_weighted would hit the aggregate_finite guard);
801 // PerPhase is a per-phase-only scalar with no cross-RUN aggregate.
802 // Distribution / WorstLowest / WakeLatencyTailRatio / WorstCrossNodeRatio
803 // are NOT skipped — their raw components do
804 // NOT survive cross-RUN (phases are dropped), so there is no pooled set
805 // to re-derive; they fall through to aggregate_samples_weighted and
806 // fold by kind (MEAN for the percentile / CV / mean reductions and
807 // every WorstLowest, MAX for SampleReduction::Worst — the
808 // aggregate_finite arms). Dispatch by registered MetricKind so
809 // Gauge(Avg) gets the weighted-mean fold (matches the per-phase merge
810 // contract); unregistered names (no metric_def) fall back to
811 // arithmetic mean, the legacy (sum, count) semantic. Skip a key whose
812 // reduction is None (every value NaN — defensive post sidecar_to_row
813 // sanitize).
814 let ext_metrics = fold_ext_metrics(acc.ext_pairs, &acc.ext_counter_keys);
815 let aggregated = GauntletRow {
816 scenario: acc.first.scenario.clone(),
817 // Per-test gate declarations are identical across a test's grouped
818 // runs (same entry), so the first row's carry the group's.
819 perf_delta_assertions: acc.first.perf_delta_assertions.clone(),
820 topology: acc.first.topology.clone(),
821 work_type: acc.first.work_type.clone(),
822 scheduler: acc.first.scheduler.clone(),
823 kernel_version: acc.first.kernel_version.clone(),
824 commit: project_commit_rendered,
825 kernel_commit: kernel_commit_rendered,
826 run_source: acc.first.run_source.clone(),
827 resolve_source: acc.first.resolve_source.clone(),
828 // First-seen budget metadata, like scheduler/kernel_version
829 // above. CpuBudget is a PAIRING dim (not sliceable — see
830 // Dimension::SLICEABLE), so it is part of the group key and every
831 // contributor shares one budget; the first row's value is the
832 // group's. vcpus is likewise first-seen metadata — and is NOT a
833 // Dimension. No post-aggregation consumer reads the aggregated
834 // vcpus (`render_overcommit_warning` and the other overcommit
835 // checks run pre-aggregation on the raw rows), so the first-seen
836 // value is metadata only.
837 cpu_budget: acc.first.cpu_budget,
838 vcpus: acc.first.vcpus,
839 // First-seen like the fields above — and safe by construction:
840 // the denomination era is an unconditional PairingKey component
841 // (slot 1), so every contributor in a group shares one value.
842 throughput_denomination: acc.first.throughput_denomination,
843 // ALL must pass: any failed, inconclusive, or skipped
844 // contributor flips the aggregate. A group with zero
845 // passes_observed (every contributor failed, was
846 // inconclusive, or was skipped) collapses to
847 // passed=false here. The four-bit verdict is
848 // strict 4-state (exactly one of pass/skip/inconc/fail
849 // set per row); the lattice
850 // `Fail > Inconclusive > Pass > Skip` determines which
851 // bit dominates when a cohort has mixed contributors.
852 // Skip is the lowest-precedence bit — it fires only
853 // when no contributor failed AND no contributor was
854 // inconclusive AND at least one was skipped. Fail
855 // (all-false) dominates Inconclusive dominates Skip;
856 // exactly one of the four states is encoded per row.
857 passed: !acc.any_failed && !acc.any_inconclusive && !acc.any_skipped && n > 0,
858 skipped: !acc.any_failed && !acc.any_inconclusive && acc.any_skipped,
859 inconclusive: !acc.any_failed && acc.any_inconclusive,
860 expected_failure: acc.any_expected_failure,
861 // Sum across contributors so the aggregated row's
862 // weight is the cohort's total sample population. A
863 // downstream consumer that further folds these
864 // aggregated rows can apply the same weighted semantic
865 // (a 5-RUN cohort of 50-sample runs weighs 250 vs a
866 // 1-RUN cohort of 10 samples weighting 10).
867 run_sample_count: acc.sum_run_sample_count,
868 spread: acc.sum_spread / denom,
869 // Peak-kind typed fields: MAX across runs (kind-correct
870 // cross-RUN fold; arithmetic mean dilutes the
871 // worst-instant signal).
872 gap_ms: acc.max_gap_ms,
873 imbalance_ratio: acc.max_imbalance_ratio,
874 max_dsq_depth: acc.max_max_dsq_depth,
875 migrations: round_u64(acc.sum_migrations),
876 migration_ratio: acc.sum_migration_ratio / denom,
877 stuck_count: acc.sum_stuck_count / denom,
878 fallback_count: round_i64(acc.sum_fallback_count),
879 keep_last_count: round_i64(acc.sum_keep_last_count),
880 total_iterations: round_u64(acc.sum_total_iterations),
881 host_dilation: acc.max_host_dilation,
882 ext_metrics,
883 // Carry the Dynamic counter-key tags forward so a second-level
884 // cross-RUN fold of these already-aggregated rows keeps SUM-folding
885 // them (the SUM-of-SUMs stays a SUM).
886 ext_counter_keys: acc.ext_counter_keys,
887 // Phase buckets do not aggregate cleanly across an
888 // averaged group: two contributors might run different
889 // scenarios with different phase counts, and per-phase
890 // averaging across mismatched step_index sets would
891 // invent rows neither side carried. Surface the empty
892 // slice so downstream consumers fall back to the flat
893 // bucket. Averaged groups carry no per-phase data; the
894 // per-step_index intersection + one-sided-step surfacing
895 // semantic lives in the per-run noise path
896 // (noise_phase_findings), not the averaging path.
897 phases: Vec::new(),
898 };
899 AveragedGroup {
900 row: aggregated,
901 passes_observed: acc.passes_observed,
902 skips_observed: acc.skips_observed,
903 inconclusives_observed: acc.inconclusives_observed,
904 failures_observed: acc.failures_observed,
905 total_observed: acc.total_observed,
906 }
907 }
908}
909
910/// Fold one group's accumulated per-ext-metric (value, weight) pairs
911/// into the aggregated row's `ext_metrics` map. Rate, PerPhase, and
912/// PerRunDistribution are skipped in the kind dispatch: Rate's components
913/// survive cross-RUN as their own ext keys so it re-derives Σnum/Σdenom
914/// (folding two ready-made ratios would lose the re-pool, and routing a Rate
915/// through aggregate_samples_weighted would hit the aggregate_finite guard);
916/// PerPhase is a per-phase-only scalar with no cross-RUN aggregate;
917/// PerRunDistribution is a whole-run percentile/min/max that CANNOT be
918/// cross-RUN folded (a percentile of a union is not a mean of per-run
919/// percentiles, and the per-phase histograms are dropped cross-RUN so there is
920/// no pooled set to re-derive) — its only cross-RUN consumer is the per-run
921/// noise-compare (`noise_findings`), so it must never be averaged here.
922/// Distribution / WorstLowest / WakeLatencyTailRatio / WorstCrossNodeRatio
923/// are NOT skipped — their raw components do
924/// NOT survive cross-RUN (phases are dropped), so there is no pooled set
925/// to re-derive; they fall through to aggregate_samples_weighted and
926/// fold by kind (MEAN for the percentile / CV / mean reductions and
927/// every WorstLowest, MAX for SampleReduction::Worst — the
928/// aggregate_finite arms). Dispatch by registered MetricKind so
929/// Gauge(Avg) gets the weighted-mean fold (matches the per-phase merge
930/// contract); an unregistered name (no metric_def) folds by `counter_keys`: a
931/// Dynamic monotonic-counter key (lb_*/alb_* schedstat delta, ScalarCounter bpf
932/// field) SUM-folds (matching the registered-Counter convention), every other
933/// unregistered name falls back to arithmetic mean, the legacy (sum, count)
934/// semantic. Skip a key whose
935/// reduction is None (every value NaN — defensive post sidecar_to_row
936/// sanitize). Rate metrics are then re-derived from the folded
937/// components (Σnum/Σdenom) as a post-pass.
938fn fold_ext_metrics(
939 ext_pairs: BTreeMap<String, Vec<(f64, usize)>>,
940 counter_keys: &BTreeSet<String>,
941) -> BTreeMap<String, f64> {
942 let mut ext_metrics: std::collections::BTreeMap<String, f64> = ext_pairs
943 .into_iter()
944 .filter_map(|(k, pairs)| {
945 if let Some(def) = metric_def(&k) {
946 // Rate re-derives from its folded components (post-pass below);
947 // PerPhase is a per-phase-only scalar with no meaningful
948 // cross-RUN aggregate — both are skipped here. The PerPhase skip
949 // is also load-bearing: a PerPhase key reaching
950 // aggregate_samples_weighted would hit aggregate_finite's
951 // unreachable!() arm. (PerPhase keys should never reach here —
952 // populate_run_ext_metrics_from_phases skips is_derived keys —
953 // so this is defensive belt-and-suspenders.)
954 if matches!(
955 def.kind,
956 MetricKind::Rate { .. } | MetricKind::PerPhase | MetricKind::PerRunDistribution
957 ) {
958 return None;
959 }
960 aggregate_samples_weighted(&pairs, def.kind).map(|v| (k, v))
961 } else {
962 let n = pairs.len();
963 if n == 0 {
964 None
965 } else {
966 let sum: f64 = pairs.iter().map(|(v, _)| *v).sum();
967 // A Dynamic monotonic-counter key (lb_*/alb_* schedstat delta
968 // or a ScalarCounter bpf field) SUM-folds across runs,
969 // matching the registered-Counter convention (aggregate_finite's
970 // Counter arm). Untagged keys (gauges, per-CPU _avg/_max) keep
971 // the legacy arithmetic-mean fold.
972 let v = if counter_keys.contains(&k) {
973 sum
974 } else {
975 sum / n as f64
976 };
977 Some((k, v))
978 }
979 }
980 })
981 .collect();
982 // Re-derive Rate metrics from the folded components (Σnum/Σdenom).
983 derive_rate_metrics(&mut ext_metrics);
984 ext_metrics
985}
986
987/// Group `rows` by the dynamic pairing key (`scenario` plus every
988/// dimension in `pairing_dims`) and arithmetic-mean their metric
989/// fields, returning one [`AveragedGroup`] per distinct key.
990/// Slicing dims are EXCLUDED from `pairing_dims` (rows on the A/B
991/// sides differ on them by design); pairing dims are INCLUDED.
992///
993/// Group key matches [`compare_rows_by`]' pairing key so the post-
994/// aggregation row vec joins cleanly across A/B sides under the
995/// same identity contract.
996///
997/// Aggregation rules:
998/// - The verdict bits `(passed, skipped, inconclusive)` aggregate
999/// under the strict 4-state mutex per the
1000/// `Fail > Inconclusive > Pass > Skip` lattice. Fail (all-false)
1001/// dominates: any failed contributor flips the aggregate's
1002/// `passed` to `false` and leaves `skipped`/`inconclusive` clear,
1003/// yielding Fail at the aggregate level. Otherwise Inconclusive
1004/// dominates: any inconclusive contributor sets the aggregate's
1005/// `inconclusive = true`. Otherwise Skip dominates: any skipped
1006/// contributor sets `skipped = true`. Only when every contributor
1007/// was a real Pass does the aggregate carry `passed = true`. This
1008/// matches [`GauntletRow::is_pass`]'s triple-conjunct semantics
1009/// so the aggregate's accessor reads honestly.
1010/// - Metrics (`f64` / `u64` / `i64` fields, plus `ext_metrics`
1011/// entries) are summed only across contributors where
1012/// `passed && !skipped`, then divided by that count to yield an
1013/// arithmetic mean. Failing/skipped contributors carry telemetry
1014/// dominated by the failure mode, NOT scheduler behaviour, and
1015/// are therefore excluded from the mean. When no contributor
1016/// passed cleanly, every metric defaults to zero and the
1017/// aggregate's `passed = false` routes the pair to
1018/// [`compare_rows_by`]' `excluded_pairs` gate.
1019/// - `u64` / `i64` fields take the rounded mean
1020/// (`(sum / count).round() as u64`). The up-to-0.5-unit per-side
1021/// rounding error (up to 1.0 across an A/B pair) stays below each
1022/// such field's `default_abs` gate: the smallest is
1023/// `total_iterations` / `total_migrations` at 2.0, held `>= 2.0` by
1024/// the scale-varying #28 recalibration precisely so a rounding-only
1025/// delta (`<= 1.0`) never clears the gate and fabricates a unit
1026/// regression.
1027/// - `stuck_count` is the exception: it is `f64` and carries the
1028/// EXACT mean (`sum / count`, no rounding). Its `default_abs` is
1029/// 1.0 — tight enough that a rounded mean's up-to-1.0 per-A/B-pair
1030/// error would fabricate single-stall regressions from sub-integer
1031/// differences (an A-side mean of 1.4 vs a B-side 1.6 rounds to
1032/// 1 vs 2, a spurious delta of 1).
1033/// - `ext_metrics` keys are unioned across passing contributors;
1034/// each key's mean is computed only across contributors that
1035/// carried it. A key present in some passing rows and absent
1036/// from others uses the present-only count as its denominator —
1037/// absent-and-zero are not equivalent (the `BTreeMap<String,
1038/// f64>` shape cannot represent "absent" with a stored zero).
1039/// - Identity fields (`scenario`, `topology`, `work_type`,
1040/// `scheduler`, `kernel_version`) come from the first contributor
1041/// in iteration order. Every contributor in the group shares the
1042/// first three by construction (group key); `scheduler` and
1043/// `kernel_version` may vary across the group if the operator did
1044/// not narrow via typed filters first, but the aggregated row
1045/// carries the first contributor's value in any case — the join
1046/// downstream uses the three-tuple, so scheduler/version on the
1047/// aggregate is metadata, not a join key.
1048/// - Commit dimensions (`commit`, `kernel_commit`) follow a
1049/// first-seen rule with one exception: when contributors disagree
1050/// on the `-dirty` suffix for the same canonical hex (some clean,
1051/// some dirty), the rendered form becomes `{hex}+mixed` so the
1052/// working-tree disagreement is surfaced rather than hidden by
1053/// first-seen. `+mixed` (not `-mixed`) is intentional —
1054/// `-dirty` is a per-record property of one sidecar, `+mixed`
1055/// is a cohort-level property of the average. Mixed-dirty
1056/// tracking spans EVERY contributor (passing, failing, skipped)
1057/// because the cohort's WIP state is metadata, not a metric.
1058///
1059/// Group iteration order matches the order of FIRST appearance of
1060/// each key in `rows`; `BTreeMap` ordering is by key (not iteration
1061/// order) so we maintain a parallel `Vec<key>` to preserve
1062/// first-seen ordering. Stable order keeps test fixtures
1063/// deterministic across runs.
1064pub fn group_and_average_by(
1065 rows: &[GauntletRow],
1066 pairing_dims: &[Dimension],
1067) -> Vec<AveragedGroup> {
1068 // Dynamic pairing key — scenario + every NON-slicing
1069 // dimension's value, in [`Dimension::ALL`] order. The
1070 // `PairingKey` newtype is owned (`Vec<String>`) so the
1071 // BTreeMap can hold keys without lifetime gymnastics; the
1072 // alternative — borrowing slices into `rows` — would force
1073 // every consumer to keep `rows` alive for the duration of
1074 // the map.
1075 type Key = PairingKey;
1076
1077 let mut order: Vec<Key> = Vec::new();
1078 let mut groups: BTreeMap<Key, Accumulator<'_>> = BTreeMap::new();
1079
1080 for row in rows {
1081 let key = PairingKey::from_row(row, pairing_dims);
1082 let acc = groups.entry(key.clone()).or_insert_with(|| {
1083 order.push(key);
1084 Accumulator::new(row)
1085 });
1086 acc.observe(row);
1087 }
1088
1089 let mut out = Vec::with_capacity(order.len());
1090 for key in order {
1091 let acc = groups
1092 .remove(&key)
1093 .expect("first-seen key must still be in groups map");
1094 out.push(acc.into_averaged_group());
1095 }
1096 out
1097}
1098
1099/// Convert a SidecarResult to a GauntletRow for run-to-run comparison.
1100///
1101/// Non-finite f64 values (NaN, ±Infinity) are sanitized to 0.0 with a
1102/// warn before they reach the row. `serde_json::to_string` rejects
1103/// non-finite, so a single poisoned metric would otherwise halt every
1104/// downstream JSON write. Sanitizing at the ingress boundary keeps the
1105/// serializer happy without silencing the upstream data quality issue.
1106///
1107/// # NaN → 0.0 ambiguity for zero-meaningful metrics
1108///
1109/// The 0.0 substitution is indistinguishable from a legitimate 0.0
1110/// measurement for metrics whose natural zero carries its own signal.
1111/// One direct f64 field is especially affected — note the in-tree producer
1112/// already guards the typical divide-by-zero path
1113/// (`assert::reductions::migration_ratio_of` emits `0.0` for
1114/// migration_ratio when `total_iterations == 0`), so a NaN reaching
1115/// this boundary indicates an upstream producer outside that guard (e.g. an
1116/// external `ext_metrics` contributor, or a schedstat arithmetic
1117/// edge that slipped past a guard):
1118///
1119/// - `migration_ratio`: lower-better. A real 0.0 means "no task was
1120/// migrated" (ideal locality). A sanitized NaN collapses to the
1121/// same value and reads as *falsely good* — a downstream regression
1122/// gate sees "perfect locality" where the truth is "no data".
1123/// (`page_locality` is NO LONGER a finite_or_zero typed field: it is the
1124/// ext-sourced `worst_page_locality` WorstLowest metric, re-pooled from the
1125/// per-phase NUMA carriers, so a non-finite value is DROPPED via the ext path —
1126/// absence preserved — not coerced to a falsely-bad 0.0 here.)
1127///
1128/// The reclassified wake-latency / run-delay distributions (e.g.
1129/// `worst_wake_latency_cv`) are NO LONGER direct f64 fields — they flow
1130/// through `ext_metrics`, where a non-finite value is DROPPED (the entry is
1131/// absent), NOT substituted with 0.0. That is the opposite, no-false-zero
1132/// contract: an absent key reads as no-data, distinct from a measured 0.0.
1133///
1134/// The accompanying `tracing::warn!` is the only signal that
1135/// separates a sanitized NaN from a real 0.0; downstream aggregation
1136/// by value alone cannot distinguish them.
1137pub fn sidecar_to_row(sc: &crate::test_support::SidecarResult) -> GauntletRow {
1138 // Local closure so the warn can carry the scenario name as
1139 // context — keyed by field so the operator can pinpoint which
1140 // metric produced the bad value.
1141 let finite_or_zero = |field: &str, v: f64| -> f64 {
1142 if v.is_finite() {
1143 v
1144 } else {
1145 tracing::warn!(
1146 test = %sc.test_name,
1147 field,
1148 value = v,
1149 "non-finite f64 in GauntletRow field; substituting 0.0",
1150 );
1151 0.0
1152 }
1153 };
1154
1155 // Build ext_metrics from the in-guest payload map (dropping the
1156 // walk-truncation sentinel + non-finite values), then layer in the
1157 // host-side monitor schedstat aggregates below.
1158 let mut ext_metrics: BTreeMap<String, f64> = sc
1159 .stats
1160 .ext_metrics
1161 .iter()
1162 .filter_map(|(k, &v)| {
1163 if crate::test_support::is_truncation_sentinel_name(k) {
1164 return None;
1165 }
1166 if v.is_finite() {
1167 Some((k.clone(), v))
1168 } else {
1169 tracing::warn!(
1170 test = %sc.test_name,
1171 metric = %k,
1172 value = v,
1173 "dropping non-finite ext_metric; serde_json rejects NaN/Infinity",
1174 );
1175 None
1176 }
1177 })
1178 .collect();
1179 // Run-level ext-only monitor metrics (avg_nr_running + the PELT IRQ load
1180 // pair + the PSI-irq pair + event/schedstat CPU-time components), folded
1181 // from the run's MonitorSummary. Inserted
1182 // only when the run has monitor samples (a 0-sample run carries no
1183 // occupancy / IRQ signal — absent, not a false 0.0); the IRQ fields insert
1184 // only on Some (loud-absent on a kernel without the source). Shared with
1185 // VmResult::run_metric via fold_run_level_ext so the key list + loud-absent
1186 // guard can't drift between the sidecar row and the in-test accessor.
1187 // Dynamic monotonic-counter ext keys (lb_*/alb_* schedstat deltas + any
1188 // ScalarCounter bpf field) collected alongside the values so the cross-run
1189 // fold SUM-folds them (they are not in the static METRICS registry, so
1190 // metric_def can't classify them — see fold_ext_metrics).
1191 let mut ext_counter_keys = BTreeSet::new();
1192 if let Some(m) = sc.monitor.as_ref() {
1193 m.fold_run_level_ext_with_counter_keys(&mut ext_metrics, &mut ext_counter_keys);
1194 }
1195
1196 GauntletRow {
1197 scenario: sc.test_name.clone(),
1198 perf_delta_assertions: sc.perf_delta_assertions.clone(),
1199 topology: sc.topology.clone(),
1200 work_type: sc.work_type.clone(),
1201 scheduler: sc.scheduler.clone(),
1202 kernel_version: sc.kernel_version.clone(),
1203 commit: sc.project_commit.clone(),
1204 kernel_commit: sc.kernel_commit.clone(),
1205 run_source: sc.run_source.clone(),
1206 resolve_source: sc.resolve_source.clone(),
1207 // 0 = skip rows (never booted) -> None: skips carry no budget
1208 // identity, so they don't pair into a "budget 0" bucket.
1209 cpu_budget: (sc.cpu_budget != 0).then_some(sc.cpu_budget),
1210 vcpus: (sc.vcpus != 0).then_some(sc.vcpus),
1211 host_dilation: sc.host_dilation.filter(|d| d.is_finite()),
1212 throughput_denomination: sc.throughput_denomination,
1213 passed: sc.is_pass(),
1214 skipped: sc.is_skip(),
1215 inconclusive: sc.is_inconclusive(),
1216 expected_failure: sc.expected_failure,
1217 run_sample_count: sc.monitor.as_ref().map(|m| m.total_samples).unwrap_or(0),
1218 spread: finite_or_zero("spread", sc.stats.worst_spread),
1219 gap_ms: sc.stats.worst_gap_ms,
1220 migrations: sc.stats.total_migrations,
1221 migration_ratio: finite_or_zero("migration_ratio", sc.stats.worst_migration_ratio),
1222 imbalance_ratio: finite_or_zero(
1223 "imbalance_ratio",
1224 sc.monitor
1225 .as_ref()
1226 .map(|m| m.max_imbalance_ratio)
1227 .unwrap_or(0.0),
1228 ),
1229 max_dsq_depth: sc
1230 .monitor
1231 .as_ref()
1232 .map(|m| m.max_local_dsq_depth)
1233 .unwrap_or(0),
1234 stuck_count: sc.monitor.as_ref().map(|m| m.stuck_count).unwrap_or(0) as f64,
1235 fallback_count: sc
1236 .monitor
1237 .as_ref()
1238 .and_then(|m| m.event_deltas.as_ref())
1239 .map(|e| e.total_fallback)
1240 .unwrap_or(0),
1241 keep_last_count: sc
1242 .monitor
1243 .as_ref()
1244 .and_then(|m| m.event_deltas.as_ref())
1245 .map(|e| e.total_dispatch_keep_last)
1246 .unwrap_or(0),
1247 total_iterations: sc.stats.total_iterations,
1248 // Built above: in-guest payload ext keys (non-finite values and
1249 // the walk-truncation sentinel dropped — a dropped non-finite must
1250 // not be confused with a real 0.0, and the sentinel is JSON-walker
1251 // diagnostic metadata, not a scenario metric) plus the host-side
1252 // monitor schedstat aggregates.
1253 ext_metrics,
1254 // Which of the Dynamic ext keys are monotonic counters (SUM-fold
1255 // cross-run); empty when there is no monitor / no counter keys.
1256 ext_counter_keys,
1257 // Carry per-phase buckets verbatim from the source
1258 // ScenarioStats. The bucket structure has already been
1259 // reduced by the host-side phase aggregator (Counter via
1260 // `phase_counter_delta`, Gauge/Peak/Timestamp via
1261 // `aggregate_samples`), so the sidecar -> row step just
1262 // forwards the prebuilt slice. An empty `phases` slot on
1263 // the source sidecar (single-phase scenario or legacy
1264 // file) flows through as an empty slice.
1265 phases: sc.stats.phases.clone(),
1266 }
1267}