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}