ailloli_ui_bench/
stats.rs

1//! Deterministic sample summaries, robust memory trends, and regression gates.
2//!
3//! Quantiles use nearest rank, variability uses median absolute deviation, and
4//! memory growth uses the pairwise Theil-Sen estimator. All public computations
5//! reject non-finite input instead of relying on partial floating-point order.
6
7use std::collections::BTreeMap;
8
9use serde::Serialize;
10use thiserror::Error;
11
12use crate::log::ParsedRun;
13use crate::model::MetricRole;
14
15/// Deterministic summary of one finite sample series.
16///
17/// # Examples
18///
19/// ```
20/// let summary = ailloli_ui_bench::summarize_samples(&[1.0, 2.0, 3.0])?;
21/// assert_eq!(summary.median, 2.0);
22/// assert_eq!(summary.count, 3);
23/// # Ok::<(), ailloli_ui_bench::StatsError>(())
24/// ```
25#[derive(Debug, Clone, PartialEq, Serialize)]
26pub struct SampleSummary {
27    /// Number of samples summarized.
28    pub count: usize,
29    /// Standard median; even series average the two middle values.
30    pub median: f64,
31    /// Nearest-rank 95th percentile.
32    pub p95: f64,
33    /// Nearest-rank 99th percentile.
34    pub p99: f64,
35    /// Median absolute deviation from [`Self::median`].
36    pub mad: f64,
37    /// Smallest sample.
38    pub min: f64,
39    /// Largest sample.
40    pub max: f64,
41}
42
43/// Maximum accepted RSS growth during a tree virtualization steady-state soak.
44///
45/// Unit: binary MiB per second. The gate fails only when slope is strictly
46/// greater than this limit.
47///
48/// # Examples
49///
50/// ```
51/// assert_eq!(ailloli_ui_bench::MAX_RSS_SLOPE_MIB_PER_SEC, 0.10);
52/// ```
53pub const MAX_RSS_SLOPE_MIB_PER_SEC: f64 = 0.10;
54
55/// Maximum accepted RSS extent after the soak warmup period.
56///
57/// Unit: binary MiB. The gate fails only when extent is strictly greater than
58/// this limit.
59///
60/// # Examples
61///
62/// ```
63/// assert_eq!(ailloli_ui_bench::MAX_RSS_EXTENT_MIB, 32.0);
64/// ```
65pub const MAX_RSS_EXTENT_MIB: f64 = 32.0;
66
67/// Deterministic memory-trend decision for a sampled process.
68///
69/// # Examples
70///
71/// ```
72/// let trend = ailloli_ui_bench::summarize_memory_trend(&[(0.0, 10.0), (1.0, 10.05)])?;
73/// assert_eq!(trend.count, 2);
74/// assert!(!trend.failed());
75/// # Ok::<(), ailloli_ui_bench::StatsError>(())
76/// ```
77#[derive(Debug, Clone, PartialEq, Serialize)]
78pub struct MemoryTrendSummary {
79    /// Number of `(seconds, MiB)` samples.
80    pub count: usize,
81    /// Theil-Sen RSS growth estimate in MiB per second.
82    pub slope_mib_per_sec: f64,
83    /// Minimum observed RSS in MiB.
84    pub min_mib: f64,
85    /// Maximum observed RSS in MiB.
86    pub max_mib: f64,
87    /// `max_mib - min_mib` in MiB.
88    pub extent_mib: f64,
89    /// Locked slope limit in MiB per second.
90    pub slope_limit_mib_per_sec: f64,
91    /// Locked RSS extent limit in MiB.
92    pub extent_limit_mib: f64,
93    /// Whether slope strictly exceeded its limit.
94    pub slope_failed: bool,
95    /// Whether extent strictly exceeded its limit.
96    pub extent_failed: bool,
97}
98
99impl MemoryTrendSummary {
100    /// Returns true when either the robust growth slope or memory extent fails.
101    ///
102    /// # Examples
103    ///
104    /// ```
105    /// let trend = ailloli_ui_bench::summarize_memory_trend(&[(0.0, 10.0), (1.0, 100.0)])?;
106    /// assert!(trend.failed());
107    /// # Ok::<(), ailloli_ui_bench::StatsError>(())
108    /// ```
109    pub const fn failed(&self) -> bool {
110        self.slope_failed || self.extent_failed
111    }
112}
113
114/// Summary of one named metric, including its gate behavior and process count.
115///
116/// # Examples
117///
118/// ```
119/// use ailloli_ui_bench::{MetricRole, MetricSummary, SampleSummary};
120/// let summary = MetricSummary {
121///     role: MetricRole::Diagnostic,
122///     runs: 1,
123///     samples: SampleSummary { count: 1, median: 2.0, p95: 2.0, p99: 2.0,
124///         mad: 0.0, min: 2.0, max: 2.0 },
125/// };
126/// assert_eq!(summary.runs, 1);
127/// ```
128#[derive(Debug, Clone, PartialEq, Serialize)]
129pub struct MetricSummary {
130    /// Shared role carried by every contributing sample.
131    pub role: MetricRole,
132    /// Number of independent run artifacts which contributed samples.
133    pub runs: usize,
134    /// Sample statistics remain flattened for backward-compatible JSON output.
135    #[serde(flatten)]
136    pub samples: SampleSummary,
137}
138
139/// Invalid input for deterministic statistics.
140///
141/// # Examples
142///
143/// ```
144/// assert_eq!(
145///     ailloli_ui_bench::summarize_samples(&[]),
146///     Err(ailloli_ui_bench::StatsError::Empty),
147/// );
148/// ```
149#[derive(Debug, Clone, PartialEq, Eq, Error)]
150#[non_exhaustive]
151pub enum StatsError {
152    #[error("sample series is empty")]
153    /// A summary was requested for no samples.
154    Empty,
155    #[error("sample at index {index} is not finite")]
156    /// A timestamp or value was NaN or infinite.
157    NonFinite {
158        /// Zero-based input index of the invalid pair or value.
159        index: usize,
160    },
161    /// Samples sharing a metric name declared incompatible regression roles.
162    #[error("metric {metric:?} mixes regression roles {first:?} and {second:?}")]
163    MixedMetricRoles {
164        /// Metric whose samples disagree.
165        metric: String,
166        /// Role observed first.
167        first: MetricRole,
168        /// Conflicting later role.
169        second: MetricRole,
170    },
171    #[error("a trend requires at least two samples, got {count}")]
172    /// A trend received fewer than two samples.
173    InsufficientTrendSamples {
174        /// Number of supplied samples.
175        count: usize,
176    },
177    #[error("trend timestamps do not contain two distinct values")]
178    /// Every trend pair had equal timestamps, leaving no defined slope.
179    NoDistinctTrendTimestamps,
180}
181
182/// Computes standard median, nearest-rank p95/p99, and median absolute deviation.
183///
184/// Input order is irrelevant and the input slice is not mutated.
185///
186/// # Errors
187///
188/// Returns [`StatsError::Empty`] for no samples and `NonFinite` at the first
189/// NaN/infinite input index.
190///
191/// # Examples
192///
193/// ```
194/// let summary = ailloli_ui_bench::summarize_samples(&[4.0, 1.0, 3.0, 2.0])?;
195/// assert_eq!(summary.median, 2.5);
196/// assert_eq!(summary.p95, 4.0);
197/// # Ok::<(), ailloli_ui_bench::StatsError>(())
198/// ```
199pub fn summarize_samples(samples: &[f64]) -> Result<SampleSummary, StatsError> {
200    if samples.is_empty() {
201        return Err(StatsError::Empty);
202    }
203    for (index, sample) in samples.iter().enumerate() {
204        if !sample.is_finite() {
205            return Err(StatsError::NonFinite { index });
206        }
207    }
208
209    let mut sorted = samples.to_vec();
210    sorted.sort_by(f64::total_cmp);
211    let median = median_of_sorted(&sorted);
212    let mut deviations = sorted
213        .iter()
214        .map(|sample| (sample - median).abs())
215        .collect::<Vec<_>>();
216    deviations.sort_by(f64::total_cmp);
217
218    Ok(SampleSummary {
219        count: sorted.len(),
220        median,
221        p95: nearest_rank(&sorted, 95, 100),
222        p99: nearest_rank(&sorted, 99, 100),
223        mad: median_of_sorted(&deviations),
224        min: sorted[0],
225        max: sorted[sorted.len() - 1],
226    })
227}
228
229/// Computes the median of a nonempty ascending finite slice.
230///
231/// The caller upholds both preconditions; even lengths average middle values.
232fn median_of_sorted(sorted: &[f64]) -> f64 {
233    let middle = sorted.len() / 2;
234    if sorted.len().is_multiple_of(2) {
235        (sorted[middle - 1] + sorted[middle]) / 2.0
236    } else {
237        sorted[middle]
238    }
239}
240
241/// Selects a bounded nearest-rank quantile from a nonempty sorted slice.
242///
243/// Saturating multiplication and index clamping prevent integer/index overflow.
244fn nearest_rank(sorted: &[f64], numerator: usize, denominator: usize) -> f64 {
245    let rank = sorted
246        .len()
247        .saturating_mul(numerator)
248        .div_ceil(denominator)
249        .max(1);
250    sorted[rank.saturating_sub(1).min(sorted.len() - 1)]
251}
252
253/// Computes the deterministic Theil–Sen slope of `(seconds, value)` samples.
254///
255/// The estimator is the median of every pairwise slope with distinct
256/// timestamps. Input ordering does not affect the result. It is robust to
257/// isolated RSS spikes and is therefore preferable to an endpoint delta for a
258/// long-running memory gate.
259///
260/// Time is in seconds and values use the caller's unit, so the returned slope
261/// is value-units per second. Equal-time pairs are ignored. Memory use is
262/// quadratic in sample count because every distinct-time pair contributes.
263///
264/// # Errors
265///
266/// Returns `InsufficientTrendSamples`, `NonFinite`, or
267/// `NoDistinctTrendTimestamps` for the corresponding invalid inputs.
268///
269/// # Examples
270///
271/// ```
272/// let slope = ailloli_ui_bench::theil_sen_slope(&[(0.0, 10.0), (2.0, 11.0)])?;
273/// assert_eq!(slope, 0.5);
274/// # Ok::<(), ailloli_ui_bench::StatsError>(())
275/// ```
276pub fn theil_sen_slope(samples: &[(f64, f64)]) -> Result<f64, StatsError> {
277    if samples.len() < 2 {
278        return Err(StatsError::InsufficientTrendSamples {
279            count: samples.len(),
280        });
281    }
282    for (index, (timestamp, value)) in samples.iter().copied().enumerate() {
283        if !timestamp.is_finite() || !value.is_finite() {
284            return Err(StatsError::NonFinite { index });
285        }
286    }
287
288    let mut slopes = Vec::with_capacity(samples.len().saturating_mul(samples.len() - 1) / 2);
289    for (left_index, (left_time, left_value)) in samples.iter().copied().enumerate() {
290        for (right_time, right_value) in samples.iter().copied().skip(left_index + 1) {
291            let elapsed = right_time - left_time;
292            if elapsed == 0.0 {
293                continue;
294            }
295            slopes.push((right_value - left_value) / elapsed);
296        }
297    }
298    if slopes.is_empty() {
299        return Err(StatsError::NoDistinctTrendTimestamps);
300    }
301    slopes.sort_by(f64::total_cmp);
302    Ok(median_of_sorted(&slopes))
303}
304
305/// Evaluates the locked tree virtualization RSS slope and extent limits.
306///
307/// Each pair is `(elapsed_seconds, rss_mib)`. Equality at either limit passes;
308/// only strictly larger values fail.
309///
310/// # Errors
311///
312/// Propagates all [`theil_sen_slope`] input errors.
313///
314/// # Examples
315///
316/// ```
317/// let trend = ailloli_ui_bench::summarize_memory_trend(&[(0.0, 100.0), (10.0, 100.5)])?;
318/// assert_eq!(trend.extent_mib, 0.5);
319/// assert!(!trend.failed());
320/// # Ok::<(), ailloli_ui_bench::StatsError>(())
321/// ```
322pub fn summarize_memory_trend(samples: &[(f64, f64)]) -> Result<MemoryTrendSummary, StatsError> {
323    let slope_mib_per_sec = theil_sen_slope(samples)?;
324    let mut min_mib = f64::INFINITY;
325    let mut max_mib = f64::NEG_INFINITY;
326    for (_, value) in samples.iter().copied() {
327        min_mib = min_mib.min(value);
328        max_mib = max_mib.max(value);
329    }
330    let extent_mib = max_mib - min_mib;
331    Ok(MemoryTrendSummary {
332        count: samples.len(),
333        slope_mib_per_sec,
334        min_mib,
335        max_mib,
336        extent_mib,
337        slope_limit_mib_per_sec: MAX_RSS_SLOPE_MIB_PER_SEC,
338        extent_limit_mib: MAX_RSS_EXTENT_MIB,
339        slope_failed: slope_mib_per_sec > MAX_RSS_SLOPE_MIB_PER_SEC,
340        extent_failed: extent_mib > MAX_RSS_EXTENT_MIB,
341    })
342}
343
344/// Whether a comparison represents steady-state or cold-start measurements.
345///
346/// # Examples
347///
348/// ```
349/// use ailloli_ui_bench::ComparisonMode;
350/// assert_ne!(ComparisonMode::SteadyState, ComparisonMode::ColdStart);
351/// ```
352#[derive(Debug, Clone, Copy, PartialEq, Eq)]
353pub enum ComparisonMode {
354    /// Gate median and p95; p99 is diagnostic.
355    SteadyState,
356    /// Gate only the median across independent processes.
357    ColdStart,
358}
359
360/// Regression decision for one metric.
361///
362/// # Examples
363///
364/// ```
365/// use ailloli_ui_bench::{compare_metric, summarize_samples, ComparisonMode};
366/// let baseline = summarize_samples(&[100.0; 30])?;
367/// let candidate = summarize_samples(&[105.0; 30])?;
368/// let comparison = compare_metric("frame_us", baseline, candidate, ComparisonMode::SteadyState);
369/// assert!(!comparison.failed());
370/// # Ok::<(), ailloli_ui_bench::StatsError>(())
371/// ```
372#[derive(Debug, Clone, PartialEq, Serialize)]
373pub struct MetricComparison {
374    /// Stable metric name.
375    pub metric: String,
376    /// Gate policy applied to this metric.
377    pub role: MetricRole,
378    /// Baseline sample statistics.
379    pub baseline: SampleSummary,
380    /// Candidate sample statistics.
381    pub candidate: SampleSummary,
382    /// Inclusive median upper bound for gating performance roles.
383    pub median_limit: f64,
384    /// Inclusive p95 upper bound for steady-state roles only.
385    pub p95_limit: Option<f64>,
386    /// Whether candidate median strictly exceeded its active limit.
387    pub median_regressed: bool,
388    /// Whether candidate p95 strictly exceeded its active limit.
389    pub p95_regressed: bool,
390    /// Whether baseline or candidate correctness samples contained nonzero data.
391    pub correctness_failed: bool,
392}
393
394impl MetricComparison {
395    /// Returns true when this metric fails its configured gate.
396    ///
397    /// # Examples
398    ///
399    /// ```
400    /// use ailloli_ui_bench::{compare_metric, summarize_samples, ComparisonMode};
401    /// let baseline = summarize_samples(&[0.0])?;
402    /// let candidate = summarize_samples(&[1.0])?;
403    /// let comparison = compare_metric(
404    ///     "correctness.lost_wake", baseline, candidate, ComparisonMode::SteadyState,
405    /// );
406    /// assert!(comparison.failed());
407    /// # Ok::<(), ailloli_ui_bench::StatsError>(())
408    /// ```
409    pub fn failed(&self) -> bool {
410        self.median_regressed || self.p95_regressed || self.correctness_failed
411    }
412}
413
414/// Compares two summaries using `baseline + max(10%, 3 * baseline MAD)`.
415///
416/// Names beginning with `correctness.` receive zero-tolerance correctness
417/// semantics. Other names use `mode` to choose median+p95 or median-only gating.
418/// P99 is always diagnostic.
419///
420/// # Examples
421///
422/// ```
423/// use ailloli_ui_bench::{compare_metric, summarize_samples, ComparisonMode};
424/// let baseline = summarize_samples(&[10.0; 30])?;
425/// let candidate = summarize_samples(&[11.0; 30])?;
426/// let result = compare_metric("paint_us", baseline, candidate, ComparisonMode::SteadyState);
427/// assert_eq!(result.median_limit, 11.0);
428/// # Ok::<(), ailloli_ui_bench::StatsError>(())
429/// ```
430pub fn compare_metric(
431    metric: impl Into<String>,
432    baseline: SampleSummary,
433    candidate: SampleSummary,
434    mode: ComparisonMode,
435) -> MetricComparison {
436    let metric = metric.into();
437    let role = if metric.starts_with("correctness.") {
438        MetricRole::Correctness
439    } else {
440        match mode {
441            ComparisonMode::SteadyState => MetricRole::GatingSteady,
442            ComparisonMode::ColdStart => MetricRole::GatingColdStart,
443        }
444    };
445    compare_metric_with_role(metric, baseline, candidate, role)
446}
447
448/// Compares two summaries according to the role carried by the metric.
449///
450/// Diagnostic roles never fail. Correctness requires every baseline and
451/// candidate value to be exactly zero. Performance tolerances use baseline MAD;
452/// equality at a limit passes.
453///
454/// # Examples
455///
456/// ```
457/// use ailloli_ui_bench::{
458///     compare_metric_with_role, summarize_samples, MetricRole,
459/// };
460/// let baseline = summarize_samples(&[1.0])?;
461/// let candidate = summarize_samples(&[1_000.0])?;
462/// let result = compare_metric_with_role("probe", baseline, candidate, MetricRole::Diagnostic);
463/// assert!(!result.failed());
464/// # Ok::<(), ailloli_ui_bench::StatsError>(())
465/// ```
466pub fn compare_metric_with_role(
467    metric: impl Into<String>,
468    baseline: SampleSummary,
469    candidate: SampleSummary,
470    role: MetricRole,
471) -> MetricComparison {
472    let metric = metric.into();
473    let correctness_failed = role == MetricRole::Correctness
474        && (baseline.min != 0.0
475            || baseline.max != 0.0
476            || candidate.min != 0.0
477            || candidate.max != 0.0);
478    let median_tolerance = (baseline.median.abs() * 0.10).max(3.0 * baseline.mad);
479    let median_limit = baseline.median + median_tolerance;
480    let median_regressed = matches!(role, MetricRole::GatingSteady | MetricRole::GatingColdStart)
481        && candidate.median > median_limit;
482    let p95_limit = (role == MetricRole::GatingSteady)
483        .then(|| baseline.p95 + (baseline.p95.abs() * 0.10).max(3.0 * baseline.mad));
484    let p95_regressed = p95_limit.is_some_and(|limit| candidate.p95 > limit);
485
486    MetricComparison {
487        metric,
488        role,
489        baseline,
490        candidate,
491        median_limit,
492        p95_limit,
493        median_regressed,
494        p95_regressed,
495        correctness_failed,
496    }
497}
498
499/// Aggregates all metric samples, roles, and process counts from parsed runs.
500///
501/// Each artifact contributes at most one to `runs` for a metric, regardless of
502/// its sample count. Metrics are returned in name order. Empty metric series are
503/// skipped.
504///
505/// # Errors
506///
507/// Returns [`StatsError::MixedMetricRoles`] when a name carries different roles
508/// within or across runs, and propagates sample-summary errors.
509///
510/// # Examples
511///
512/// ```
513/// use ailloli_ui_bench::{summarize_runs_with_roles, ParsedRun};
514/// let summaries = summarize_runs_with_roles(&[ParsedRun::default()])?;
515/// assert_eq!(summaries["correctness.get_current_texture_err"].runs, 1);
516/// # Ok::<(), ailloli_ui_bench::StatsError>(())
517/// ```
518pub fn summarize_runs_with_roles(
519    runs: &[ParsedRun],
520) -> Result<BTreeMap<String, MetricSummary>, StatsError> {
521    /// Accumulates one metric's consistent role, run count, and raw samples.
522    struct Accumulator {
523        /// Role shared by every accumulated sample.
524        role: MetricRole,
525        /// Independent artifacts that contributed this metric.
526        runs: usize,
527        /// Finite raw values across all contributing artifacts.
528        samples: Vec<f64>,
529    }
530
531    let mut metrics = BTreeMap::<String, Accumulator>::new();
532    for run in runs {
533        for (metric, samples) in run.metric_samples() {
534            let Some(first) = samples.first() else {
535                continue;
536            };
537            if let Some(sample) = samples.iter().find(|sample| sample.role != first.role) {
538                return Err(StatsError::MixedMetricRoles {
539                    metric,
540                    first: first.role,
541                    second: sample.role,
542                });
543            }
544
545            let accumulator = metrics
546                .entry(metric.clone())
547                .or_insert_with(|| Accumulator {
548                    role: first.role,
549                    runs: 0,
550                    samples: Vec::new(),
551                });
552            if accumulator.role != first.role {
553                return Err(StatsError::MixedMetricRoles {
554                    metric,
555                    first: accumulator.role,
556                    second: first.role,
557                });
558            }
559            accumulator.runs = accumulator.runs.saturating_add(1);
560            accumulator
561                .samples
562                .extend(samples.into_iter().map(|sample| sample.value));
563        }
564    }
565    metrics
566        .into_iter()
567        .map(|(metric, accumulator)| {
568            summarize_samples(&accumulator.samples).map(|samples| {
569                (
570                    metric,
571                    MetricSummary {
572                        role: accumulator.role,
573                        runs: accumulator.runs,
574                        samples,
575                    },
576                )
577            })
578        })
579        .collect()
580}
581
582/// Aggregates samples without exposing gate roles to compatibility callers.
583///
584/// # Errors
585///
586/// Propagates all [`summarize_runs_with_roles`] errors.
587///
588/// # Examples
589///
590/// ```
591/// use ailloli_ui_bench::{summarize_runs, ParsedRun};
592/// let summaries = summarize_runs(&[ParsedRun::default()])?;
593/// assert_eq!(summaries["correctness.get_current_texture_err"].median, 0.0);
594/// # Ok::<(), ailloli_ui_bench::StatsError>(())
595/// ```
596pub fn summarize_runs(runs: &[ParsedRun]) -> Result<BTreeMap<String, SampleSummary>, StatsError> {
597    summarize_runs_with_roles(runs).map(|summaries| {
598        summaries
599            .into_iter()
600            .map(|(metric, summary)| (metric, summary.samples))
601            .collect()
602    })
603}
604
605#[cfg(test)]
606/// Verifies quantiles, roles, tolerances, correctness, and robust memory trends.
607mod tests {
608    use super::*;
609
610    #[test]
611    fn even_median_and_nearest_rank_quantiles_are_deterministic() {
612        let summary = summarize_samples(&[4.0, 1.0, 3.0, 2.0]).unwrap();
613        assert_eq!(summary.median, 2.5);
614        assert_eq!(summary.p95, 4.0);
615        assert_eq!(summary.p99, 4.0);
616        assert_eq!(summary.mad, 1.0);
617    }
618
619    #[test]
620    fn rejects_non_finite_samples() {
621        assert_eq!(
622            summarize_samples(&[1.0, f64::NAN]),
623            Err(StatsError::NonFinite { index: 1 })
624        );
625    }
626
627    #[test]
628    fn steady_state_gate_uses_median_and_p95_but_not_p99() {
629        let baseline = summarize_samples(&[100.0; 100]).unwrap();
630        let mut samples = vec![100.0; 94];
631        samples.extend([111.0; 5]);
632        samples.push(10_000.0);
633        let candidate = summarize_samples(&samples).unwrap();
634        let comparison =
635            compare_metric("frame_us", baseline, candidate, ComparisonMode::SteadyState);
636        assert!(!comparison.median_regressed);
637        assert!(comparison.p95_regressed);
638        assert_eq!(comparison.candidate.p99, 111.0);
639    }
640
641    #[test]
642    fn cold_start_only_gates_median() {
643        let baseline = summarize_samples(&[100.0; 5]).unwrap();
644        let candidate = summarize_samples(&[100.0, 100.0, 100.0, 500.0, 500.0]).unwrap();
645        let comparison =
646            compare_metric("startup_us", baseline, candidate, ComparisonMode::ColdStart);
647        assert!(!comparison.failed());
648        assert_eq!(comparison.role, MetricRole::GatingColdStart);
649        assert_eq!(comparison.p95_limit, None);
650    }
651
652    #[test]
653    fn diagnostic_metrics_never_block() {
654        let baseline = summarize_samples(&[1.0]).unwrap();
655        let candidate = summarize_samples(&[1_000_000.0]).unwrap();
656        let comparison = compare_metric_with_role(
657            "renderer.adapter_probe_us",
658            baseline,
659            candidate,
660            MetricRole::Diagnostic,
661        );
662        assert_eq!(comparison.role, MetricRole::Diagnostic);
663        assert!(!comparison.median_regressed);
664        assert!(!comparison.p95_regressed);
665        assert!(!comparison.failed());
666    }
667
668    #[test]
669    fn correctness_metrics_have_zero_tolerance() {
670        let baseline = summarize_samples(&[0.0]).unwrap();
671        let candidate = summarize_samples(&[1.0]).unwrap();
672        let comparison = compare_metric(
673            "correctness.lost_wake",
674            baseline,
675            candidate,
676            ComparisonMode::SteadyState,
677        );
678        assert!(comparison.correctness_failed);
679        assert!(comparison.failed());
680    }
681
682    #[test]
683    fn nonzero_correctness_baseline_cannot_be_used_as_a_gate_reference() {
684        let baseline = summarize_samples(&[1.0]).unwrap();
685        let candidate = summarize_samples(&[0.0]).unwrap();
686        let comparison = compare_metric_with_role(
687            "mailbox_error_count",
688            baseline,
689            candidate,
690            MetricRole::Correctness,
691        );
692        assert!(comparison.correctness_failed);
693        assert!(comparison.failed());
694    }
695
696    #[test]
697    fn correctness_role_does_not_depend_on_metric_name() {
698        let baseline = summarize_samples(&[0.0]).unwrap();
699        let candidate = summarize_samples(&[1.0]).unwrap();
700        let comparison = compare_metric_with_role(
701            "lost_wake_count",
702            baseline,
703            candidate,
704            MetricRole::Correctness,
705        );
706        assert!(comparison.correctness_failed);
707        assert!(comparison.failed());
708    }
709
710    #[test]
711    fn theil_sen_is_order_independent_and_robust_to_one_spike() {
712        let mut samples = (0..181)
713            .map(|second| (f64::from(second), 300.0 + f64::from(second) * 0.05))
714            .collect::<Vec<_>>();
715        samples[90].1 += 128.0;
716        let forward = theil_sen_slope(&samples).unwrap();
717        samples.reverse();
718        let reverse = theil_sen_slope(&samples).unwrap();
719        assert!((forward - 0.05).abs() < 1.0e-9, "slope={forward}");
720        assert_eq!(forward, reverse);
721    }
722
723    #[test]
724    fn memory_trend_gates_the_locked_slope_and_extent() {
725        let stable = (0..181)
726            .map(|second| (f64::from(second), 300.0 + f64::from(second) * 0.05))
727            .collect::<Vec<_>>();
728        let stable = summarize_memory_trend(&stable).unwrap();
729        assert!(!stable.failed());
730        assert!(stable.slope_mib_per_sec <= MAX_RSS_SLOPE_MIB_PER_SEC);
731
732        let leaking = (0..181)
733            .map(|second| (f64::from(second), 300.0 + f64::from(second) * 0.20))
734            .collect::<Vec<_>>();
735        let leaking = summarize_memory_trend(&leaking).unwrap();
736        assert!(leaking.slope_failed);
737        assert!(leaking.extent_failed);
738        assert!(leaking.failed());
739    }
740
741    #[test]
742    fn trend_rejects_non_finite_and_duplicate_only_timestamps() {
743        assert_eq!(
744            theil_sen_slope(&[(0.0, 1.0)]),
745            Err(StatsError::InsufficientTrendSamples { count: 1 })
746        );
747        assert_eq!(
748            theil_sen_slope(&[(1.0, 1.0), (1.0, 2.0)]),
749            Err(StatsError::NoDistinctTrendTimestamps)
750        );
751        assert_eq!(
752            theil_sen_slope(&[(0.0, 1.0), (1.0, f64::NAN)]),
753            Err(StatsError::NonFinite { index: 1 })
754        );
755    }
756}