ktstr/stats/
row.rs

1use super::*;
2
3/// Per-scenario result row for gauntlet analysis and run-to-run comparison.
4///
5/// Populated by [`sidecar_to_row`] from on-disk [`SidecarResult`](crate::test_support::SidecarResult)s. The
6/// comparison pipeline reads metric values through [`MetricDef::read`]
7/// / [`METRICS`] rather than dereferencing fields directly so new
8/// metrics can land through the registry without touching every
9/// reader.
10///
11/// # NaN-ambiguity on direct f64 fields
12///
13/// All direct f64 fields on this struct are sanitized via
14/// `finite_or_zero` at [`sidecar_to_row`] ingress. A `0.0` on any
15/// direct f64 field may represent either a genuine zero measurement
16/// or a sanitized non-finite upstream value (NaN / ±Infinity). See
17/// [`sidecar_to_row`]'s NaN-ambiguity doc for the full policy;
18/// `tracing::warn!` is the disambiguation channel — the sanitizer
19/// warns on every non-finite it rewrites to zero, so the log
20/// timeline tells you which run's zeroes were real. Consumers that
21/// cannot accept the ambiguity should prefer metric paths that
22/// flow through `ext_metrics` (a `BTreeMap<String, f64>` — see the
23/// field definition below): non-finite entries are DROPPED at
24/// [`sidecar_to_row`] ingress rather than stored. A subsequent
25/// `ext_metrics.get(name)` returns `None` because the key is
26/// absent, not because an `Option::None` sentinel is stored — the
27/// map's value type is `f64`, which cannot represent "missing".
28/// Absent-key and zero-valued metrics therefore remain distinguishable
29/// for downstream consumers.
30///
31/// # `#[non_exhaustive]` migration note
32///
33/// Downstream code that pattern-matches a `GauntletRow` must end
34/// the match with `..`; future fields added alongside new metrics
35/// otherwise break every matcher. Prefer reading values via
36/// [`MetricDef::read`] / the registry — the point of the
37/// registry indirection is that new metrics do not touch
38/// existing readers.
39#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
40#[non_exhaustive]
41pub struct GauntletRow {
42    pub scenario: String,
43    pub topology: String,
44    pub work_type: String,
45    /// Effective host-CPU budget the run's vCPU threads ran on
46    /// (`SidecarResult::cpu_budget`); `None` for skip rows (budget 0).
47    /// Drives the [`Dimension::CpuBudget`] pairing so cross-budget runs
48    /// are never compared (confining 32 vCPUs to 4 host CPUs measures
49    /// something different), and (with [`vcpus`](Self::vcpus)) feeds the
50    /// compare-path overcommit warning in [`render_overcommit_warning`].
51    #[serde(default, skip_serializing_if = "Option::is_none")]
52    pub cpu_budget: Option<u32>,
53    /// Guest vCPU count (`SidecarResult::vcpus`); `None` for skip rows.
54    /// NOT a Dimension — it rides alongside [`cpu_budget`](Self::cpu_budget)
55    /// so [`render_overcommit_warning`] can flag a compared run whose host
56    /// time-sliced its vCPUs (`cpu_budget < vcpus`), whose guest-scheduler
57    /// timing metrics are then host-contention-confounded.
58    #[serde(default, skip_serializing_if = "Option::is_none")]
59    pub vcpus: Option<u32>,
60    /// Measured host scheduling dilation (`wall / delivered vCPU CPU time`).
61    /// CPU-denominated rates exclude it; genuinely wall-semantic latency and
62    /// upstream wall-throughput metrics retain it as explicit comparison
63    /// context. `None` when the run could not measure vCPU schedstat.
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub host_dilation: Option<f64>,
66    /// Denomination of this row's workload-throughput rate metrics,
67    /// carried from `SidecarResult::throughput_denomination`
68    /// (`#[serde(default)]` = `Wall` for pre-marker rows). NOT an
69    /// operator-facing Dimension — it is an unconditional part of every
70    /// `PairingKey` (like `scenario`; see `super::group`), so a
71    /// wall-era row never pairs with, or group-averages into, a
72    /// cpu-era row: the throughput keys kept their names across the
73    /// denomination change and their values are not comparable across it.
74    /// Cross-era near-misses are surfaced by
75    /// `CompareReport::denomination_mismatches`.
76    #[serde(default)]
77    pub throughput_denomination: crate::test_support::ThroughputDenomination,
78    /// Scheduler binary name carried from the source sidecar
79    /// (`SidecarResult::scheduler`). Surfaced through the substring
80    /// filter in [`compare_rows_by`] and the typed
81    /// `RowFilter::schedulers` so users can narrow A/B comparisons
82    /// by scheduler name.
83    pub scheduler: String,
84    /// Kernel version carried from the source sidecar
85    /// (`SidecarResult::kernel_version`). `None` when the sidecar
86    /// writer could not extract a version (e.g. a raw kernel image
87    /// path with no metadata.json sibling, or a dirty source tree
88    /// where HEAD does not describe the build). Surfaced via the
89    /// typed [`RowFilter::kernels`] for narrowing — when the user
90    /// passes `--kernel 6.14.2` (repeatable), rows with `None` are
91    /// dropped to preserve the operator's intent ("only these
92    /// kernels"); a `None`-as-wildcard would silently dilute the
93    /// filtered set.
94    #[serde(default, skip_serializing_if = "Option::is_none")]
95    pub kernel_version: Option<String>,
96    /// ktstr project git commit carried from the source sidecar
97    /// (`SidecarResult::project_commit`). Short hex with optional
98    /// `-dirty` suffix (e.g. `"abcdef1"` or `"abcdef1-dirty"`).
99    /// `None` when the sidecar writer could not probe a git repo
100    /// at write time (cwd not inside a checkout, or
101    /// `crate::test_support::sidecar::detect_project_commit`
102    /// failed for any reason). Surfaced via the typed
103    /// [`RowFilter::project_commits`] for narrowing — when the
104    /// user passes `--project-commit abcdef1` (repeatable), rows
105    /// with `None` are dropped to preserve the operator's intent
106    /// ("only these commits"); a `None`-as-wildcard would silently
107    /// dilute the filtered set, mirroring the [`RowFilter::kernels`]
108    /// policy.
109    ///
110    /// Sourced from `SidecarResult::project_commit`; shortened to
111    /// `commit` on the row because the project commit is the
112    /// most-frequently-narrowed-on of the three commit dimensions
113    /// on [`SidecarResult`](crate::test_support::SidecarResult). The other two commit fields —
114    /// `SidecarResult::scheduler_commit` and
115    /// `SidecarResult::kernel_commit` — get fully-qualified names
116    /// here (`scheduler_commit` is reserved and not yet exposed,
117    /// `kernel_commit` is the typed filter `RowFilter::kernel_commits`
118    /// applies). The bare `commit` shortening is internal to
119    /// `GauntletRow`; the CLI flag is the disambiguated
120    /// `--project-commit` form so an operator never has to guess
121    /// which "commit" dimension a bare `--commit` would have meant.
122    #[serde(default, skip_serializing_if = "Option::is_none")]
123    pub commit: Option<String>,
124    /// Kernel SOURCE TREE git commit carried from the source
125    /// sidecar (`SidecarResult::kernel_commit`). Short hex with
126    /// optional `-dirty` suffix (e.g. `"abcdef1"` or
127    /// `"abcdef1-dirty"`). `None` when the sidecar writer could
128    /// not probe a git repo for the kernel directory at write
129    /// time (KTSTR_KERNEL points at a non-git path, the
130    /// underlying source is `Tarball` / `Git` rather than
131    /// `Local`, or
132    /// `crate::test_support::sidecar::detect_kernel_commit`
133    /// failed for any reason).
134    ///
135    /// Distinct from [`GauntletRow::commit`]: that field tracks
136    /// the ktstr framework HEAD ("which version of the harness
137    /// produced this sidecar?"); this field tracks the kernel
138    /// tree HEAD ("which kernel commit did this run boot?"). Two
139    /// runs with the same `commit` but different `kernel_commit`
140    /// values are typical when the kernel under test is updated
141    /// without re-checking out the harness; two runs with the
142    /// same `kernel_commit` but different `commit` values are
143    /// typical when the harness is bumped without rebuilding the
144    /// kernel.
145    ///
146    /// Surfaced via the typed [`RowFilter::kernel_commits`] for
147    /// narrowing — same opt-in policy as [`RowFilter::project_commits`]:
148    /// rows with `None` never match a populated filter.
149    #[serde(default, skip_serializing_if = "Option::is_none")]
150    pub kernel_commit: Option<String>,
151    /// Run-environment provenance tag carried from
152    /// `SidecarResult::run_source` (`"local"` for developer runs,
153    /// `"ci"` when `crate::test_support::sidecar::KTSTR_CI_ENV`
154    /// was set at write time, `"archive"` when the consumer pulled
155    /// the pool from a non-default `--dir`). `None` for sidecars
156    /// produced before the field existed (pre-1.0 disposable
157    /// schema; re-running the test regenerates the entry).
158    /// Surfaced via the typed [`RowFilter::run_sources`] for
159    /// narrowing — when the user passes `--run-source local`
160    /// (repeatable), rows with `None` are dropped to preserve the
161    /// operator's intent ("only these environments"); a
162    /// `None`-as-wildcard would silently dilute the filtered set,
163    /// mirroring the [`RowFilter::kernels`] /
164    /// [`RowFilter::project_commits`] / [`RowFilter::kernel_commits`]
165    /// policy.
166    ///
167    /// Field name `run_source` (renamed from `source`) disambiguates
168    /// from [`crate::cache::KernelSource`] / `KernelMetadata.source`
169    /// — those describe the kernel build's input (tarball / git /
170    /// local), this describes the run-environment provenance.
171    #[serde(default, skip_serializing_if = "Option::is_none")]
172    pub run_source: Option<String>,
173    /// Scheduler-resolution provenance carried from
174    /// [`crate::test_support::SidecarResult::resolve_source`] —
175    /// the snake_case resolution-path tag (`"auto_built"`,
176    /// `"env_var"`, `"path"`, ...; historical sidecars may carry retired
177    /// tags such as `"target_debug"`). `None` for sidecars produced
178    /// before the field existed (pre-1.0 disposable schema) and for skip
179    /// rows (no binary resolved). Surfaced via the typed
180    /// [`RowFilter::resolve_sources`] (`--resolve-source`) for narrowing +
181    /// pairing — same opt-in policy as `run_source` — and listed by
182    /// `stats list-values`. Provenance, not identity: distinct
183    /// from `scheduler` / `kernel_commit` — it records HOW the scheduler
184    /// binary was found, so a reader can tell an auto-built-from-HEAD run
185    /// from a possibly-stale `$PATH` binary.
186    #[serde(default, skip_serializing_if = "Option::is_none")]
187    pub resolve_source: Option<String>,
188    /// True when the underlying [`crate::assert::AssertResult::is_pass`] returned
189    /// true at sidecar emission time — a real pass with at least one
190    /// observed outcome and no Fail/Inconclusive/Skip. Mutually
191    /// exclusive with [`Self::skipped`] and [`Self::inconclusive`]:
192    /// the three bits encode a strict 4-state verdict where exactly
193    /// one of (Pass, Skip, Inconclusive, Fail) is set per row.
194    pub passed: bool,
195    /// True when the run was skipped (topology mismatch, missing
196    /// resource). Mutually exclusive with [`Self::passed`] (Skip is
197    /// not Pass; the empty / all-Skip outcomes vec maps to Skip,
198    /// not Pass) and with [`Self::inconclusive`]. Lets stats tooling
199    /// exclude these from pass counts so skipped runs don't inflate
200    /// the apparent pass rate.
201    pub skipped: bool,
202    /// True when at least one assertion recorded
203    /// [`crate::assert::Outcome::Inconclusive`] — the run ran but a
204    /// zero-denominator ratio gate could not be evaluated. Mutually
205    /// exclusive with [`Self::passed`] and [`Self::skipped`]; in the
206    /// `Fail > Inconclusive > Pass > Skip` lattice, Inconclusive
207    /// dominates Pass/Skip but loses to Fail, so a row with both
208    /// Inconclusive and Fail outcomes records `inconclusive = false,
209    /// passed = false` (Fail wins). Surfaced as a distinct bit so
210    /// `is_fail` can exclude these from hard-fail counts and
211    /// dashboards can triage zero-denominator runs separately from
212    /// real regressions.
213    #[serde(default)]
214    pub inconclusive: bool,
215    /// True when this row's source run was an `expect_err` /
216    /// `expect_auto_repro` test whose actual scenario failure was
217    /// inverted to a pass — its telemetry is failure-mode-dominated
218    /// (short / stalled run), so [`compare_rows_by`] excludes it from
219    /// the regression math even though [`passed`](Self::passed) is now
220    /// `true`. Carried from `SidecarResult::expected_failure`;
221    /// OR-folded across a cohort in `group_and_average_by`.
222    #[serde(default)]
223    pub expected_failure: bool,
224    /// Number of monitor samples this run was averaged over —
225    /// the natural per-RUN weight for `Gauge(Avg)` metrics when
226    /// folded across multiple runs at cross-RUN comparison time
227    /// (`group_and_average_by`). Sourced from
228    /// `MonitorSummary::total_samples` at sidecar-write time;
229    /// `0` when the monitor did not run for this scenario
230    /// (host-only test, early VM failure). A `0` weight
231    /// degenerates to unweighted mean per the fallback at
232    /// `aggregate_samples`'s zero-total-weight branch.
233    ///
234    /// The field exists because the cross-RUN aggregator
235    /// previously computed unweighted arithmetic mean for every
236    /// metric — biased for `Gauge(Avg)` when runs in a cohort
237    /// had different sample populations (a 5-sample run and a
238    /// 50-sample run contributing equally to the cohort mean).
239    /// Carrying the per-RUN count here lets the aggregator dispatch
240    /// per-`MetricKind` weighted folds via the helper.
241    #[serde(default)]
242    pub run_sample_count: usize,
243    /// Worst-case per-cgroup spread across the run. Four names
244    /// describe the same quantity across the pipeline:
245    /// - [`ScenarioStats::worst_spread`](crate::assert::ScenarioStats::worst_spread)
246    ///   — the upstream source. `sidecar_to_row` reads it and
247    ///   writes the value into this field via `finite_or_zero`.
248    /// - `GauntletRow.spread` (this field) — the Rust-side
249    ///   struct access path inside the comparison pipeline.
250    /// - `MetricDef.name == "worst_spread"` — the [`METRICS`]
251    ///   registry key, which is the domain-level name that appears
252    ///   in sidecars, CI gates, and `cargo ktstr perf-delta`
253    ///   output.
254    /// - DataFrame column `"spread"` — the polars column name used
255    ///   when the rows are projected into a DataFrame for group /
256    ///   aggregate operations.
257    ///
258    /// The registry name is not renamed to match the field name
259    /// because existing sidecars and CI regression gates reference
260    /// `"worst_spread"` by string and a rename would silently
261    /// invalidate them. The DataFrame column stays `"spread"` for
262    /// terseness and to match the field; consumers that cross
263    /// the registry / DataFrame boundary translate via
264    /// [`MetricDef::read`] rather than by string comparison.
265    pub spread: f64,
266    /// Worst-case per-cgroup scheduling gap (ms). Surfaced in
267    /// [`METRICS`] under registry name `worst_gap_ms`; the
268    /// field / registry / DataFrame-column divergence is catalogued
269    /// in the triples table on [`METRICS`].
270    pub gap_ms: u64,
271    /// Total CPU migrations across the run. Surfaced in [`METRICS`]
272    /// under registry name `total_migrations`; see the triples
273    /// table on [`METRICS`] for the rationale behind the
274    /// field / registry / DataFrame-column divergence.
275    pub migrations: u64,
276    /// Worst-case per-cgroup migrations-per-iteration ratio.
277    /// Surfaced in [`METRICS`] under registry name
278    /// `worst_migration_ratio`; see the triples table on
279    /// [`METRICS`] for the field / registry / DataFrame-column
280    /// divergence.
281    pub migration_ratio: f64,
282    // Monitor fields (host-side telemetry from guest memory reads).
283    /// Worst per-sample cgroup imbalance ratio. Surfaced in
284    /// [`METRICS`] under registry name `max_imbalance_ratio`
285    /// (DataFrame column `imbalance`); see the triples table on
286    /// [`METRICS`] for the registry/field/column rationale.
287    pub imbalance_ratio: f64,
288    /// Worst observed DSQ queue depth. Registry and field names
289    /// match (`max_dsq_depth`) but the DataFrame column is
290    /// `dsq_depth`; see the triples table on [`METRICS`] for the
291    /// column-level rename rationale.
292    pub max_dsq_depth: u32,
293    /// Stuck-sample count across the run (CPUs whose `rq_clock`
294    /// failed to advance between consecutive samples). Distinct from
295    /// the sched_ext watchdog stall (`SCX_EXIT_ERROR_STALL`):
296    /// "stuck" tracks rq_clock not advancing on a CPU, while a
297    /// watchdog stall describes a runnable task that hasn't been
298    /// scheduled within the watchdog timeout. Registry and field
299    /// names match (`stuck_count`) but the DataFrame column is
300    /// `stuck`; see the triples table on [`METRICS`] for the
301    /// column-level rename rationale.
302    ///
303    /// `f64`, not an integer: a per-run row carries an exact integer
304    /// count, but the cross-run average fold (`super::group`'s
305    /// `group_and_average_by`) stores the fractional mean here so the
306    /// A/B comparison reads the true delta. Rounding the mean to an
307    /// integer would let the up-to-1.0 rounding error defeat the
308    /// `stuck_count` metric's `default_abs` of 1.0 and fabricate
309    /// single-stall regressions from sub-integer differences (e.g. an
310    /// A-side mean of 1.4 vs a B-side mean of 1.6 rounds to 1 vs 2).
311    pub stuck_count: f64,
312    /// Fallback-dispatch count across the run. Carried as-is from
313    /// `MonitorSummary::event_deltas.total_fallback` — an integer
314    /// event count, NOT a rate. Surfaced in [`METRICS`] under
315    /// registry name `total_fallback` (DataFrame column `fallback`);
316    /// see the triples table on [`METRICS`] for the registry / field /
317    /// column rationale.
318    pub fallback_count: i64,
319    /// Keep-last dispatch count across the run. Carried as-is from
320    /// `MonitorSummary::event_deltas.total_dispatch_keep_last` — an
321    /// integer event count, NOT a rate. Surfaced in [`METRICS`] under
322    /// registry name `total_keep_last` (DataFrame column `keep_last`);
323    /// see the triples table on [`METRICS`] for the registry / field /
324    /// column rationale.
325    pub keep_last_count: i64,
326    // Benchmarking fields. The wake-latency (p99 / median / CV) and
327    // run-delay (mean / worst) roll-ups are NO LONGER typed fields: they are
328    // `MetricKind::Distribution`, re-pooled into `ext_metrics` post-merge by
329    // `crate::assert::populate_run_distribution_metrics`; `MetricDef::read`
330    // surfaces them via the ext fallback (their accessors are `|_| None`).
331    pub total_iterations: u64,
332    // worst_wake_latency_tail_ratio is NO LONGER a typed field: it is
333    // `MetricKind::WakeLatencyTailRatio`, re-selected into `ext_metrics`
334    // post-merge by `crate::assert::populate_run_distribution_metrics` (max
335    // over the per-cgroup p99/median ratios, floor-gated below
336    // [`WAKE_LATENCY_TAIL_RATIO_MIN_ITERATIONS`]); `MetricDef::read` surfaces
337    // it via the ext fallback (accessor `|_| None`).
338    // worst_iterations_per_worker / worst_iterations_per_cpu_sec are NO
339    // LONGER typed fields: they are `MetricKind::WorstLowest`, re-selected
340    // into `ext_metrics` post-merge by
341    // `crate::assert::populate_run_distribution_metrics` (lowest-wins over
342    // the per-cgroup counters); `MetricDef::read` surfaces them via the ext
343    // fallback. The `worst_` naming convention is documented on [`METRICS`].
344    // NUMA fields.
345    // Neither NUMA roll-up is a typed GauntletRow column any longer:
346    // worst_page_locality is `MetricKind::WorstLowest` (NumaLocal/NumaTotal) and
347    // worst_cross_node_migration_ratio is `MetricKind::WorstCrossNodeRatio`, both
348    // ext-sourced (re-pooled from the per-phase NUMA carriers by
349    // populate_run_distribution_metrics); `MetricDef::read` surfaces them via the
350    // ext fallback, so no typed columns.
351    /// Extensible metrics populated by scenarios and processed by the
352    /// comparison pipeline. Keyed by metric name; looked up via
353    /// [`metric_def`] when a matching entry exists in [`METRICS`].
354    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
355    pub ext_metrics: BTreeMap<String, f64>,
356    /// The subset of [`Self::ext_metrics`] keys that are Dynamic monotonic
357    /// counters (the level-suffixed `lb_*`/`alb_*` schedstat deltas + any
358    /// `ScalarCounter` watched bpf field). These keys are not in the static
359    /// `METRICS` registry, so the cross-run aggregator (`fold_ext_metrics`)
360    /// consults this set to SUM-fold them instead of averaging — matching the
361    /// registered-Counter cross-run convention. Empty when the run has no
362    /// monitor or no Dynamic counter keys.
363    #[serde(default, skip_serializing_if = "BTreeSet::is_empty")]
364    pub ext_counter_keys: BTreeSet<String>,
365    /// Per-phase metric buckets carried verbatim from the source
366    /// sidecar's [`crate::assert::ScenarioStats::phases`]. Each
367    /// [`crate::assert::PhaseBucket`] surfaces the metric values
368    /// reduced over one scenario phase (BASELINE at
369    /// `step_index = 0`, Step ordinals at `step_index = 1..=N`
370    /// per the 1-indexed phase convention) so the per-phase
371    /// comparison renderer at [`compare_partitions_noise`] can pair
372    /// matched phases across two sidecars by `step_index` and
373    /// emit per-phase spread rows without re-deriving phase
374    /// boundaries.
375    ///
376    /// Empty when the source sidecar had no phase data — single-
377    /// phase scenarios that didn't drive an explicit Step vec,
378    /// or legacy sidecars from before the phase-aware pipeline
379    /// shipped. Per the pre-1.0 disposability contract, the
380    /// expected response to a legacy sidecar is to re-run the
381    /// test and regenerate, NOT to back-fill the field on read.
382    /// `serde(default, skip_serializing_if = "Vec::is_empty")`
383    /// keeps the serialized shape compact: a row with no phase
384    /// data omits the field entirely on the wire rather than
385    /// carrying an empty array.
386    #[serde(default, skip_serializing_if = "Vec::is_empty")]
387    pub phases: Vec<crate::assert::PhaseBucket>,
388    /// Per-test [`crate::test_support::PerfDeltaAssertion`] declarations (owned
389    /// records) carried from the sidecar so the perf-delta noise compare can
390    /// enforce the declared gate. Empty for rows with none; `serde(default)`
391    /// tolerates legacy sidecars (pre-1.0 disposability). NOT a pairing/slicing
392    /// dimension — per-test gate metadata only.
393    #[serde(default, skip_serializing_if = "Vec::is_empty")]
394    pub perf_delta_assertions: Vec<crate::test_support::PerfDeltaAssertionRecord>,
395}
396
397impl GauntletRow {
398    /// Convenience accessor mirroring [`crate::assert::AssertResult::is_pass`]
399    /// so the is_pass / is_fail vocabulary applies uniformly across both
400    /// verdict surfaces. GauntletRow is the sidecar-wire shape; its
401    /// `passed` bool is populated from `AssertResult::is_pass()` at
402    /// sidecar emission time.
403    ///
404    /// Returns true only when the row reached a real Pass — neither
405    /// skipped, inconclusive, nor failed. The triple-conjunct guard
406    /// matches the strict 4-state mutex encoded with three stored
407    /// bits `(passed, skipped, inconclusive)` (Fail is the all-false
408    /// derived state, no dedicated bit), so a manually-constructed
409    /// row that sets `passed = true, skipped = true` (which would
410    /// violate the mutex) still reads as not-pass here.
411    ///
412    /// Part of the `is_pass` / `is_fail` / `is_inconclusive` /
413    /// `is_skip` vocabulary uniform across the verdict surfaces:
414    /// [`crate::assert::AssertResult::is_pass`] /
415    /// [`crate::test_support::SidecarResult::is_pass`] /
416    /// [`crate::assert::Outcome::is_pass`] / `MonitorVerdict::is_pass`
417    /// (in the `monitor` module, which is `pub(crate)`) /
418    /// `Verdict::is_pass` (re-exported at [`crate::assert::Verdict`])
419    /// / `Self::is_pass`.
420    pub fn is_pass(&self) -> bool {
421        self.passed && !self.skipped && !self.inconclusive
422    }
423    /// Convenience accessor mirroring
424    /// [`crate::assert::AssertResult::is_fail`]. True only when the
425    /// row is a real failure — not a skip, not an inconclusive
426    /// (zero-denominator) run. Excludes `inconclusive` so a stats
427    /// gate that counts "real regressions" does not conflate
428    /// inconclusive runs with hard failures.
429    pub fn is_fail(&self) -> bool {
430        !self.passed && !self.skipped && !self.inconclusive
431    }
432    /// Convenience accessor mirroring
433    /// [`crate::assert::AssertResult::is_skip`].
434    pub fn is_skip(&self) -> bool {
435        self.skipped
436    }
437    /// Convenience accessor mirroring
438    /// [`crate::assert::AssertResult::is_inconclusive`]. True when
439    /// the row reflects a zero-denominator ratio gate that could
440    /// not be evaluated.
441    pub fn is_inconclusive(&self) -> bool {
442        self.inconclusive
443    }
444}
445
446/// Typed-field filter set for narrowing `GauntletRow` sets in the
447/// `cargo ktstr perf-delta` pipeline. Every field is `None` /
448/// empty by default; populated fields are AND-combined ACROSS
449/// fields, with field-internal OR/AND semantics described per-field
450/// below. Applied via `apply_row_filters` in `compare_partitions`
451/// before the rows reach `compare_rows_by`.
452///
453/// Match semantics:
454/// - `scheduler` / `topology` / `work_type` — STRICT EQUALITY against
455///   the row's corresponding field. The sibling substring filter on
456///   `compare_rows_by` (`-E`) stays as the only fuzzy-match knob;
457///   typed fields are exact so a `--scheduler scx_rusty` filter does
458///   NOT spuriously match `scx_rusty_alt`.
459/// - `kernels` — repeatable, OR-combined: a row matches iff its
460///   `kernel_version` equals ANY entry in `kernels`. Mirrors the
461///   `--kernel` flag on `cargo ktstr test`/`coverage`/`llvm-cov`
462///   so the same flag name carries the same multi-value semantic
463///   across every subcommand.
464/// - `project_commits` — repeatable, OR-combined: a row matches
465///   iff its `commit` equals ANY entry in `project_commits`. Same
466///   multi-value semantic as `kernels`, applied to the ktstr
467///   project commit recorded by `detect_project_commit` at
468///   sidecar-write time. Surfaced as the `--project-commit` CLI
469///   flag.
470/// - `kernel_commits` — repeatable, OR-combined: a row matches
471///   iff its `kernel_commit` equals ANY entry in `kernel_commits`.
472///   Same multi-value semantic as `project_commits`, applied to
473///   the kernel source-tree commit recorded by
474///   `crate::test_support::sidecar::detect_kernel_commit` at
475///   sidecar-write time. Filters on the kernel HEAD, NOT on the
476///   kernel release version (`kernels` is the version filter).
477/// - `run_sources` — repeatable, OR-combined: a row matches iff
478///   its `run_source` equals ANY entry in `run_sources`. Same
479///   multi-value semantic as `kernels` / `project_commits` /
480///   `kernel_commits`, applied to the run-environment provenance
481///   tag (`"local"`, `"ci"`, `"archive"`) recorded by
482///   `crate::test_support::sidecar::detect_run_source` at
483///   sidecar-write time, or rewritten to `"archive"` at load
484///   time when the consumer pulled the pool from a non-default
485///   `--dir`. Surfaced as the `--run-source` CLI flag.
486/// - A `kernels`-populated filter against a row whose
487///   `kernel_version` is `None` ALWAYS fails (no wildcard semantic)
488///   — the operator wrote specific versions and a `None`-row would
489///   silently dilute the set. The same opt-in policy applies to
490///   `project_commits` against rows with `commit == None`, to
491///   `kernel_commits` against rows with `kernel_commit == None`,
492///   and to `run_sources` against rows with `run_source == None`.
493///
494/// Empty `RowFilter` (every field `None`/empty) is the no-op default
495/// and matches every row. Use [`RowFilter::default()`] to build it.
496#[derive(Clone, Debug, Default)]
497pub struct RowFilter {
498    /// Repeatable kernel-version filter, OR-combined: a row matches
499    /// iff its `GauntletRow::kernel_version` equals ANY entry. Empty
500    /// vec disables the filter ("do not filter on kernel"). A row
501    /// whose `kernel_version` is itself `None` never matches a
502    /// non-empty filter.
503    pub kernels: Vec<String>,
504    /// Repeatable project-commit filter, OR-combined: a row matches
505    /// iff its `GauntletRow::commit` equals ANY entry. Empty vec
506    /// disables the filter ("do not filter on commit"). A row whose
507    /// `commit` is itself `None` never matches a non-empty filter
508    /// — same opt-in semantic as `kernels`.
509    ///
510    /// Field name `project_commits` (renamed from `commits`)
511    /// disambiguates from the sibling `kernel_commits` field — both
512    /// describe commit dimensions, so the prefix makes "which
513    /// repository's commit?" obvious at every call site.
514    pub project_commits: Vec<String>,
515    /// Repeatable kernel-source-commit filter, OR-combined: a row
516    /// matches iff its `GauntletRow::kernel_commit` equals ANY
517    /// entry. Empty vec disables the filter ("do not filter on
518    /// kernel commit"). A row whose `kernel_commit` is itself
519    /// `None` never matches a non-empty filter — same opt-in
520    /// semantic as `project_commits`.
521    ///
522    /// Distinct from `project_commits` (the ktstr framework commit)
523    /// and from `kernels` (the kernel release version): two runs
524    /// with the same `kernel_version` but different `kernel_commit`
525    /// values represent the same release rebuilt from different
526    /// trees (e.g. WIP patches on top, a different remote ref).
527    pub kernel_commits: Vec<String>,
528    /// Repeatable run-environment-source filter, OR-combined: a row
529    /// matches iff its `GauntletRow::run_source` equals ANY entry.
530    /// Empty vec disables the filter ("do not filter on
531    /// run_source"). A row whose `run_source` is itself `None`
532    /// (sidecar pre-dates the field) never matches a non-empty
533    /// filter — same opt-in semantic as `kernels` /
534    /// `project_commits` / `kernel_commits`.
535    /// Typical values: `"local"`, `"ci"`, `"archive"`. The schema
536    /// is open: any string is acceptable so a future producer can
537    /// introduce a new tag without a version bump.
538    ///
539    /// Field name `run_sources` (renamed from `sources`)
540    /// disambiguates from `KernelMetadata.source` /
541    /// [`crate::cache::KernelSource`] — those describe the kernel
542    /// build's input, this describes the run-environment provenance.
543    pub run_sources: Vec<String>,
544    /// Repeatable scheduler-resolution-source filter, OR-combined: a
545    /// row matches iff its `GauntletRow::resolve_source` equals ANY
546    /// entry. Empty vec disables the filter. A row whose
547    /// `resolve_source` is `None` (sidecar pre-dates the field, or a
548    /// skip resolved no binary) never matches a non-empty filter —
549    /// same opt-in semantic as `run_sources`. Values are the
550    /// [`crate::test_support::ResolveSource::as_str`] tags
551    /// (`"auto_built"`, `"env_var"`, `"path"`, ...; historical sidecars
552    /// may also carry retired tags such as `"target_debug"`). Distinct from
553    /// `run_sources` (the run ENVIRONMENT): this is HOW the scheduler
554    /// binary was found. Backs the [`Dimension::ResolveSource`] filter +
555    /// pairing dim (`--resolve-source`).
556    pub resolve_sources: Vec<String>,
557    /// Repeatable cpu-budget filter, OR-combined: a row matches iff its
558    /// `GauntletRow::cpu_budget` (the effective host-CPU budget, as a
559    /// decimal string) equals ANY entry. Empty vec disables the filter.
560    /// Rows with `cpu_budget == None` (skips) are dropped when this filter
561    /// is non-empty, mirroring `kernels` / `run_sources`. Backs the
562    /// [`Dimension::CpuBudget`] filter + pairing dim (`--cpu-budget`).
563    pub cpu_budgets: Vec<String>,
564    /// Repeatable scheduler-name filter, OR-combined: a row matches
565    /// iff its `GauntletRow::scheduler` equals ANY entry. Empty vec
566    /// disables the filter ("do not filter on scheduler"). Strict
567    /// equality on each entry — the substring `-E` filter is the
568    /// only fuzzy-match knob; typed flags exact-match. Mirrors the
569    /// shape of `kernels` / `project_commits` / `kernel_commits` /
570    /// `run_sources` so every typed dimension supports the same
571    /// repeatable OR-combined idiom.
572    pub schedulers: Vec<String>,
573    /// Repeatable topology filter, OR-combined: a row matches iff
574    /// its `GauntletRow::topology` equals ANY entry. The filter
575    /// values are the rendered form (e.g. `"1n2l4c2t"`) that
576    /// `Topology::Display` emits and `cargo ktstr stats list`
577    /// shows. Empty vec disables the filter.
578    pub topologies: Vec<String>,
579    /// Repeatable work-type filter, OR-combined: a row matches iff
580    /// its `GauntletRow::work_type` equals ANY entry. Valid names
581    /// are the PascalCase variants of `WorkType::ALL_NAMES`. Empty
582    /// vec disables the filter.
583    pub work_types: Vec<String>,
584}
585
586impl RowFilter {
587    /// Returns true when every populated filter field matches the
588    /// row. The empty `RowFilter` (default) returns true for every
589    /// row — it's the identity filter.
590    pub fn matches(&self, row: &GauntletRow) -> bool {
591        if !self.kernels.is_empty() {
592            // OR-combined: the row matches iff its kernel version
593            // matches ANY listed kernel. A row with `None`
594            // kernel_version never satisfies a non-empty filter —
595            // same opt-in semantic the original `Option<String>`
596            // field carried.
597            //
598            // Match shape: a filter value with two dot-separated
599            // digit segments (e.g. `6.12`) is a major.minor PREFIX —
600            // the row matches if its `kernel_version` equals
601            // `6.12` exactly, starts with `6.12.` (patch releases
602            // including the `6.12.0-rcN+` kernel banner shape),
603            // or starts with `6.12-` (the no-patch `6.12-rcN`
604            // shape `kernel_path::KernelId::Version` admits). A
605            // filter with three or more segments (e.g. `6.14.2`,
606            // `6.15-rc3`) is strict equality. The two-segment
607            // cutoff matches the shape of `MAJOR.MINOR` versus
608            // `MAJOR.MINOR.PATCH` / `MAJOR.MINOR-rcN` — there is
609            // no shorter form on the sidecar producer side worth
610            // treating as a prefix (`6` alone would match every
611            // 6.x release, which is a less useful cohort than the
612            // per-stable-series narrowing the operator usually
613            // wants).
614            let row_kernel = row.kernel_version.as_deref();
615            let any = self.kernels.iter().any(|want| match row_kernel {
616                Some(rk) => kernel_filter_matches(want, rk),
617                None => false,
618            });
619            if !any {
620                return false;
621            }
622        }
623        if !self.project_commits.is_empty() {
624            // OR-combined match against `GauntletRow::commit`,
625            // mirroring the `kernels` policy: a row whose `commit`
626            // is `None` (the sidecar writer's gix probe failed or
627            // cwd was outside any git repo) never matches a
628            // populated filter, so a `--project-commit` argument is opt-in
629            // to "only rows with this commit" rather than a wildcard.
630            let row_commit = row.commit.as_deref();
631            let any = self
632                .project_commits
633                .iter()
634                .any(|want| row_commit == Some(want.as_str()));
635            if !any {
636                return false;
637            }
638        }
639        if !self.kernel_commits.is_empty() {
640            // OR-combined match against `GauntletRow::kernel_commit`,
641            // mirroring the `project_commits` policy: a row whose
642            // `kernel_commit` is `None` (the sidecar writer's
643            // `detect_kernel_commit` probe failed, or `KTSTR_KERNEL`
644            // pointed at a non-git source) never matches a populated
645            // filter — same opt-in semantic as `--project-commit` /
646            // `--kernel`.
647            let row_kc = row.kernel_commit.as_deref();
648            let any = self
649                .kernel_commits
650                .iter()
651                .any(|want| row_kc == Some(want.as_str()));
652            if !any {
653                return false;
654            }
655        }
656        if !self.run_sources.is_empty() {
657            // OR-combined match against `GauntletRow::run_source`,
658            // mirroring the `kernels` / `project_commits` /
659            // `kernel_commits` opt-in policy: a row whose
660            // `run_source` is `None` (sidecar pre-dates the field)
661            // never matches a populated filter, so a `--run-source`
662            // argument demands a tagged row rather than acting as a
663            // wildcard.
664            let row_run_source = row.run_source.as_deref();
665            let any = self
666                .run_sources
667                .iter()
668                .any(|want| row_run_source == Some(want.as_str()));
669            if !any {
670                return false;
671            }
672        }
673        if !self.resolve_sources.is_empty() {
674            // OR-combined match against `GauntletRow::resolve_source`,
675            // mirroring the `run_sources` opt-in policy: a row whose
676            // `resolve_source` is `None` (sidecar pre-dates the field,
677            // or a skip resolved no binary) never matches a populated
678            // filter, so a `--resolve-source` argument demands a tagged
679            // row rather than acting as a wildcard.
680            let row_resolve_source = row.resolve_source.as_deref();
681            let any = self
682                .resolve_sources
683                .iter()
684                .any(|want| row_resolve_source == Some(want.as_str()));
685            if !any {
686                return false;
687            }
688        }
689        if !self.cpu_budgets.is_empty() {
690            // OR-combined match against `GauntletRow::cpu_budget` rendered
691            // as a decimal string. A row with `cpu_budget == None` (skip)
692            // never matches a populated filter — same opt-in policy as
693            // `run_sources` / `kernels`.
694            let row_budget = row.cpu_budget.map(|n| n.to_string());
695            let any = self
696                .cpu_budgets
697                .iter()
698                .any(|want| row_budget.as_deref() == Some(want.as_str()));
699            if !any {
700                return false;
701            }
702        }
703        if !self.schedulers.is_empty() {
704            // OR-combined match against `GauntletRow::scheduler`
705            // (a `String`, never `None`). Strict equality on each
706            // entry — same shape as the other repeatable typed
707            // filters above.
708            let any = self.schedulers.contains(&row.scheduler);
709            if !any {
710                return false;
711            }
712        }
713        if !self.topologies.is_empty() {
714            // OR-combined match against `GauntletRow::topology`.
715            let any = self.topologies.contains(&row.topology);
716            if !any {
717                return false;
718            }
719        }
720        if !self.work_types.is_empty() {
721            // OR-combined match against `GauntletRow::work_type`.
722            let any = self.work_types.contains(&row.work_type);
723            if !any {
724                return false;
725            }
726        }
727        true
728    }
729}
730
731/// Drop rows from `rows` that do not match every populated filter
732/// field on `filter`. Returns the surviving rows in their original
733/// order. The caller is responsible for any further dedup or
734/// aggregation; this helper preserves duplicates as written.
735///
736/// Used by [`compare_partitions`] before the surviving rows reach
737/// [`compare_rows_by`], so the substring-`-E` filter and the typed
738/// filters compose: typed narrows happen first, substring runs over
739/// the surviving set.
740pub fn apply_row_filters(rows: &[GauntletRow], filter: &RowFilter) -> Vec<GauntletRow> {
741    rows.iter().filter(|r| filter.matches(r)).cloned().collect()
742}
743
744/// Match a single `--kernel` filter value against a row's
745/// `kernel_version`. Major.minor (two-segment) filter values match
746/// any patch release in that series via prefix; longer filter
747/// values use strict equality.
748///
749/// `want` is the user-supplied filter value (e.g. `6.12`,
750/// `6.14.2`, `6.15-rc3`). `row_kernel` is the sidecar-recorded
751/// kernel version (e.g. `6.12.5`). The two-segment cutoff matches
752/// the natural shape of `MAJOR.MINOR` versus
753/// `MAJOR.MINOR.PATCH` / `MAJOR.MINOR-rcN` — `6.12.` is a
754/// stable-series prefix; `6.14.2` is one specific release.
755///
756/// Examples:
757/// - `kernel_filter_matches("6.12", "6.12.5")` → true (prefix)
758/// - `kernel_filter_matches("6.12", "6.12")` → true (exact equal)
759/// - `kernel_filter_matches("6.12", "6.13.0")` → false
760/// - `kernel_filter_matches("6.14", "6.14-rc3")` → true (prefix
761///   admits the `-rcN` pre-release of the same series; per
762///   `kernel_path::decompose_version_for_compare`, `6.14-rc3`
763///   shares the `(major=6, minor=14, patch=0)` tuple with the
764///   `6.14` release, and the operator filtering on the series
765///   wants both)
766/// - `kernel_filter_matches("6.14", "6.14.0-rc3+")` → true
767///   (kernel banner shape — patch=0 plus `-rcN` plus `EXTRAVERSION`)
768/// - `kernel_filter_matches("6.14.2", "6.14.2")` → true
769/// - `kernel_filter_matches("6.14.2", "6.14.20")` → false
770///   (strict equality on three-segment filter — without the
771///   strict path, `6.14.2` would also match `6.14.20`,
772///   `6.14.21`, ..., which is not what the operator asked for)
773pub(crate) fn kernel_filter_matches(want: &str, row_kernel: &str) -> bool {
774    if is_major_minor_prefix(want) {
775        // Three accepted shapes for a major.minor (`MAJOR.MINOR`)
776        // prefix filter, all designed so the prefix is bounded by
777        // a non-digit separator that disambiguates the series:
778        //
779        //   1. Exact equal: `row_kernel == "6.14"`. The row's
780        //      recorded version IS the major.minor string itself
781        //      (no patch, no rc).
782        //   2. Trailing-dot prefix: `row_kernel.starts_with("6.14.")`.
783        //      Covers patch releases (`6.14.0`, `6.14.5`) and
784        //      kernel banner shapes (`6.14.0-rc3+`).
785        //   3. Trailing-dash prefix: `row_kernel.starts_with("6.14-")`.
786        //      Covers the no-patch pre-release shape (`6.14-rc3`).
787        //      Per `kernel_path` (KernelId::Version doc), this is a
788        //      valid emitted shape; per
789        //      `decompose_version_for_compare` it shares the
790        //      `(major, minor, patch=0)` triple with the `6.14`
791        //      release and the operator filtering on the series
792        //      wants both.
793        //
794        // The non-digit separator after `want` (`.` or `-`)
795        // prevents `6.1` from spuriously matching `6.10.0` or
796        // `6.10-rc3` — both fail because the next character after
797        // `6.1` is `0`, which is neither separator. The `6.140`
798        // case is also rejected for the same reason.
799        row_kernel == want
800            || row_kernel.starts_with(&format!("{want}."))
801            || row_kernel.starts_with(&format!("{want}-"))
802    } else {
803        row_kernel == want
804    }
805}
806
807/// Whether a filter value looks like a major.minor PREFIX. Two
808/// non-empty dot-separated digit segments and nothing else
809/// (no `-rcN`, no third dot). Conservative: anything outside the
810/// `MAJOR.MINOR` shape falls through to strict equality so a typo
811/// like `6.14.2.` or `6.14-something` does not silently turn into
812/// a wildcard.
813fn is_major_minor_prefix(s: &str) -> bool {
814    let parts: Vec<&str> = s.split('.').collect();
815    parts.len() == 2
816        && parts
817            .iter()
818            .all(|p| !p.is_empty() && p.bytes().all(|b| b.is_ascii_digit()))
819}