ktstr/assert/mod.rs
1//! Pass/fail evaluation of scenario results.
2//!
3//! Key types:
4//! - [`AssertResult`] -- pass/fail status with diagnostics and statistics
5//! - [`Assert`] -- composable assertion config (worker + monitor checks)
6//! - [`ScenarioStats`] / [`CgroupStats`] -- aggregated telemetry
7//! - [`NumaMapsEntry`] -- parsed `/proc/self/numa_maps` VMA entry
8//! - [`Verdict`] -- pointwise-claim accumulator (built via
9//! [`Assert::verdict`] / [`Verdict::new`]; comparators routed through
10//! [`ClaimBuilder`] / [`SetClaim`] / [`SeqClaim`])
11//!
12//! NUMA assertion functions:
13//! - [`parse_numa_maps`] -- parse numa_maps content into per-VMA entries
14//! - [`page_locality`] -- compute page locality fraction from entries
15//! - [`parse_vmstat_numa_pages_migrated`] -- extract vmstat migration counter
16//! - [`assert_page_locality`] / [`assert_cross_node_migration`] -- threshold checks
17//!
18//! Assertion uses a three-layer merge: [`Assert::default_checks()`] ->
19//! `Scheduler.assert` -> per-test `assert`.
20//!
21//! # Statistical conventions
22//!
23//! - **Percentiles / medians**: nearest-rank (see `percentile`),
24//! value at index `ceil(n * p) - 1`. Unlike interpolated
25//! percentiles, every reported p99 is an actual observed sample,
26//! not a synthetic midpoint. Consistent across every
27//! [`CgroupStats`] and [`ScenarioStats`] latency field.
28//! - **CV (coefficient of variation)** is stddev/mean computed over
29//! the pooled latency samples, not as a mean of per-worker CVs —
30//! see [`CgroupStats::wake_latency_cv`] for the masking caveat.
31//!
32//! See the [Checking](https://ktstr.dev/guide/concepts/checking.html)
33//! chapter of the guide.
34
35use crate::workload::WorkerReport;
36use std::cell::RefCell;
37use std::collections::{BTreeMap, BTreeSet};
38
39mod builder;
40mod detail;
41mod phase_build;
42mod plan;
43mod reductions;
44mod run_metrics;
45mod stats_types;
46mod types;
47
48pub use builder::*;
49pub use detail::*;
50pub use phase_build::*;
51pub use plan::*;
52pub use reductions::*;
53pub use run_metrics::*;
54pub use stats_types::*;
55pub use types::*;
56
57pub mod claim;
58pub mod temporal;
59
60pub use claim::{ClaimBuilder, SeqClaim, SetClaim, Verdict};
61pub use temporal::{EachClaim, FracPair, PhaseMapExt, SeriesField};
62
63#[cfg(test)]
64mod tests_assert;
65#[cfg(test)]
66mod tests_benchmarks;
67#[cfg(test)]
68mod tests_common;
69#[cfg(test)]
70mod tests_merge;
71#[cfg(test)]
72mod tests_note;
73#[cfg(test)]
74mod tests_numa;
75#[cfg(test)]
76mod tests_percentile;
77#[cfg(test)]
78mod tests_phase_bucket;
79#[cfg(test)]
80mod tests_plan;
81#[cfg(test)]
82mod tests_sched_died;
83#[cfg(test)]
84mod tests_serde;
85#[cfg(test)]
86mod tests_stats;
87#[cfg(test)]
88mod tests_verdict;
89#[cfg(test)]
90mod tests_worker;