ktstr/assert/
builder.rs

1use super::*;
2
3/// Unified assertion configuration. Carries both worker checks and
4/// monitor thresholds as a single composable type. Each `Option` field
5/// acts as an override — `None` means "inherit from parent layer".
6///
7/// Construct via [`Assert::NO_OVERRIDES`] (preferred const baseline)
8/// or [`Assert::default_checks`] (currently aliases NO_OVERRIDES);
9/// chain builder methods on either base (all builders are `const fn`
10/// except [`Assert::expect_scx_bpf_error_matches`], which compiles a
11/// regex at construction). Use the resulting `Assert` value as the
12/// `assert` field of a [`Scheduler`](crate::test_support::Scheduler)
13/// declared via [`declare_scheduler!`](crate::declare_scheduler) — the
14/// macro accepts `assert = Assert::NO_OVERRIDES.foo()`-style chains
15/// at the scheduler level. The `#[ktstr_test]` proc macro does NOT
16/// accept an `assert = …` attribute on test entries; per-field
17/// attribute shortcuts (`max_gap_ms = N`, `not_stuck = true`, …)
18/// compose into the equivalent struct literal at expansion time.
19///
20/// Merge order: `Assert::default_checks()` -> `Scheduler.assert` -> per-test `assert`.
21/// `default_checks()` is `NO_OVERRIDES` — all assertions are opt-in.
22///
23/// ```
24/// # use ktstr::assert::Assert;
25/// // Scheduler opts into imbalance checking.
26/// let sched_assert = Assert::NO_OVERRIDES.max_imbalance_ratio(5.0);
27///
28/// // Merge: defaults <- scheduler <- test.
29/// let merged = Assert::default_checks()
30///     .merge(&sched_assert)
31///     .merge(&Assert::NO_OVERRIDES.max_gap_ms(5000));
32///
33/// assert_eq!(merged.not_stuck, None);              // not opted in
34/// assert_eq!(merged.max_imbalance_ratio, Some(5.0)); // from sched
35/// assert_eq!(merged.max_gap_ms, Some(5000));         // from test
36/// ```
37///
38/// # Serde roundtrip — covers the 20 threshold/check fields only
39///
40/// The serde derive at the struct level covers the 20 threshold +
41/// flag fields (every `Option<bool/u64/f64/u32/usize>` plus the bare
42/// `enforce_monitor_thresholds: bool`). The two reproducer-matcher
43/// fields ([`Self::expect_scx_bpf_error_contains`] and
44/// [`Self::expect_scx_bpf_error_matches`]) carry `#[serde(skip)]`
45/// because their `&'static str` shape cannot round-trip through a
46/// borrowed deserializer — see each field's doc for the rationale.
47/// Sidecar consumers comparing
48/// threshold config across runs treat reproducer matcher strings as
49/// part of the test identity (encoded by name in the sidecar key),
50/// not part of the threshold payload, so the skip is operationally
51/// transparent today.
52#[must_use = "builder methods return a new Assert; discard means config is lost"]
53#[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
54pub struct Assert {
55    // Worker checks
56    /// Enable zero-work, fairness-spread, and stuck-gap checks across
57    /// worker reports. `Some(true)` enables, `Some(false)` explicitly
58    /// disables (overriding any enabling merge from a lower layer),
59    /// `None` inherits from the merge parent.
60    pub not_stuck: Option<bool>,
61    /// Enable per-worker CPU isolation checks (ensure workers remain
62    /// within their assigned cpuset). Same tri-state semantics as
63    /// `not_stuck`.
64    pub isolation: Option<bool>,
65    /// Max per-worker progress gap in milliseconds of worker CPU-TIME:
66    /// fails if any worker consumed more than this much
67    /// `CLOCK_THREAD_CPUTIME_ID` between 1024-work-unit progress
68    /// checkpoints (compute-without-progress — a livelock or a
69    /// pathologically expensive iteration). CPU-denominated, so the gate
70    /// is dilation-safe: host preemption and guest run-queue wait accrue
71    /// no CPU. A BLOCKED or starved-runnable worker likewise accrues no
72    /// CPU — blocked-stuck detection is the cell watchdog's domain. The
73    /// historical wall-clock gap rides in the failure message (and
74    /// `WorkerReport::max_gap_wall_ms`) as evidence.
75    pub max_gap_ms: Option<u64>,
76    /// Max per-cgroup fairness spread as a percentage. Fails if the
77    /// range between the most- and least-served workers exceeds this
78    /// fraction of their mean.
79    pub max_spread_pct: Option<f64>,
80
81    // Throughput checks
82    /// Max coefficient of variation for work_units/cpu_time across workers.
83    /// Catches placement unfairness where some workers get less CPU than others.
84    pub max_throughput_cv: Option<f64>,
85    /// Minimum work_units per CPU-second. Catches cases where all workers
86    /// are equally slow (CV passes but absolute throughput is too low).
87    pub min_work_rate: Option<f64>,
88
89    // Benchmarking checks
90    /// Max p99 wake latency in NANOSECONDS. Fails if the pooled
91    /// p99 across every worker's `wake_latencies_ns` exceeds this.
92    ///
93    /// # Unit-name gotcha
94    ///
95    /// The threshold is `_ns`, but the paired reporting field on
96    /// [`CgroupStats::p99_wake_latency_us`] and the re-pooled run-level
97    /// `worst_p99_wake_latency_us` ext metric (a `MetricKind::Distribution`)
98    /// are MICROSECONDS. The two surfaces are intentionally split:
99    ///   - the threshold uses NS for precision (typical scheduler
100    ///     wake latencies are single-digit µs, so sub-µs resolution
101    ///     matters for regression gates);
102    ///   - the reporting fields use US for readability in
103    ///     `perf-delta` / dashboard output.
104    ///
105    /// Both are computed from the same underlying
106    /// [`WorkerReport::wake_latencies_ns`] samples — see
107    /// [`assert_benchmarks`] for the threshold path and
108    /// [`assert_not_stuck`] for the reporting path. A bare
109    /// comparison of `max_p99_wake_latency_ns` against
110    /// `CgroupStats::p99_wake_latency_us` is a unit-mismatch bug;
111    /// `assert_benchmarks` never does this — it consumes the raw
112    /// `wake_latencies_ns` directly — and
113    /// `assert_p99_ns_threshold_compares_against_ns_latencies` pins
114    /// that contract.
115    pub max_p99_wake_latency_ns: Option<u64>,
116    /// Max wake latency coefficient of variation. Fails if CV exceeds this.
117    pub max_wake_latency_cv: Option<f64>,
118    /// Minimum iterations per CPU-second (`iterations / cpu_time_sec`)
119    /// per worker. Fails if any worker is below. CPU-denominated so the
120    /// floor is intrinsically dilation-safe — host preemption inflates
121    /// wall time but not CPU time — measuring the workload, not the
122    /// host. In performance mode (wall ≈ CPU) it matches the historical
123    /// wall-rate number; a worker that spent zero CPU time rates 0 and
124    /// fails any positive floor. See [`assert_benchmarks`].
125    pub min_iteration_rate: Option<f64>,
126    /// Max migration ratio (migrations/iterations). Fails if any cgroup exceeds this.
127    pub max_migration_ratio: Option<f64>,
128
129    // Monitor checks
130    /// Max `nr_running` / LLC imbalance ratio observed by the monitor.
131    /// Fails if the worst sample's imbalance exceeds this.
132    pub max_imbalance_ratio: Option<f64>,
133    /// Max local DSQ depth observed by the monitor. Fails if any
134    /// sampled CPU's local DSQ grew beyond this.
135    pub max_local_dsq_depth: Option<u32>,
136    /// Treat an rq_clock-stuck verdict from the monitor as a hard failure. Same
137    /// tri-state semantics as `not_stuck`.
138    pub fail_on_rq_clock_stuck: Option<bool>,
139    /// Minimum number of consecutive samples that must exceed the
140    /// monitor threshold before a verdict is raised. Smooths out
141    /// single-sample spikes.
142    pub sustained_samples: Option<usize>,
143    /// Max `select_cpu_fallback` activity per average delivered vCPU
144    /// CPU-second. Fails if a sustained monitor interval exceeds this rate.
145    pub max_fallback_rate: Option<f64>,
146    /// Max `keep_last` activity per average delivered vCPU CPU-second.
147    /// Fails if a sustained monitor interval exceeds this rate.
148    pub max_keep_last_rate: Option<f64>,
149    /// Promote monitor threshold violations from report-only to
150    /// pass/fail. When `false` (the default), the monitor still walks
151    /// every sample and records every violation in the verdict's
152    /// `details`, but the verdict's `passed` stays `true`. Tests that
153    /// want monitor violations to fail the run call
154    /// [`Self::with_monitor_defaults`], which populates each monitor
155    /// threshold from `MonitorThresholds::new()`
156    /// and sets this flag to `true`.
157    pub enforce_monitor_thresholds: bool,
158
159    // NUMA checks
160    /// Minimum fraction of pages on the expected NUMA node(s) (0.0-1.0).
161    /// Expected nodes are derived from the worker's
162    /// [`MemPolicy`](crate::workload::MemPolicy) at evaluation time.
163    /// Fails if the observed locality fraction falls below this.
164    pub min_page_locality: Option<f64>,
165    /// Maximum ratio of NUMA-node-migrated pages to total allocated
166    /// pages (0.0-1.0). Distinct from [`max_migration_ratio`](Self::max_migration_ratio)
167    /// which measures CPU migrations per iteration. Fails if the
168    /// observed migration ratio exceeds this.
169    pub max_cross_node_migration_ratio: Option<f64>,
170    /// Maximum fraction of pages on slow-tier (memory-only) NUMA nodes
171    /// (0.0-1.0). For CXL memory tiering tests: fails if more than
172    /// this fraction of pages land on memory-only nodes. Requires
173    /// `slow_tier_nodes` to be set at evaluation time.
174    pub max_slow_tier_ratio: Option<f64>,
175
176    /// Reproducer-mode literal-substring matcher for the captured
177    /// `scx_bpf_error` text. When `Some(literal)`, the eval pipeline
178    /// scans the combined scheduler log + sched_ext dump for a
179    /// substring match against `literal` and fails the test if the
180    /// substring is absent.
181    ///
182    /// Use this for the common case of pinning an exact error
183    /// fragment like `apply_cell_config returned -EINVAL` without
184    /// having to escape regex metacharacters. For pattern matching
185    /// with anchors / character classes / wildcards, use
186    /// [`Self::expect_scx_bpf_error_matches`] instead — the two
187    /// fields are orthogonal and can both be set (both must match).
188    ///
189    /// Requires the entry's `expect_err = true` — a reproducer
190    /// matcher only fires on expected-error tests; setting this on
191    /// a passing test would assert "the test passed AND contained
192    /// this error text," which is contradictory. The eval-time
193    /// validation rejects that combination with a clear diagnostic.
194    ///
195    /// Stored as `&'static str` so the const-fn `Self::merge`
196    /// composes without cloning. Empty strings are rejected at
197    /// evaluation (an empty literal would silently match every
198    /// message and turn this assertion into a no-op).
199    /// `#[serde(skip)]` because the field's `&'static str` shape
200    /// cannot round-trip through a borrowed deserializer (no source-
201    /// string lifetime to bind to). Reproducer matcher strings are
202    /// test-author static literals carried in the test definition
203    /// itself, not per-run data the sidecar needs to roundtrip — so
204    /// skipping them on the wire keeps the JSON shape clean without
205    /// losing any sidecar-consumer functionality. Skipped fields
206    /// default to `None` on deserialize per `Option::default()`.
207    ///
208    /// The `Option<Cow<'static, str>>` alternative that WOULD
209    /// roundtrip is rejected because it cascade-breaks
210    /// `Scheduler::assert`'s const-fn (`Cow` has a heap destructor,
211    /// which breaks the const-fn assignment path used by
212    /// `declare_scheduler!` macro statics). A future decomposition
213    /// into a `ReproducerMatchers` sub-config could revisit this if
214    /// sidecar-loaded test definitions ever need the strings to
215    /// survive end-to-end.
216    #[serde(skip)]
217    pub expect_scx_bpf_error_contains: Option<&'static str>,
218
219    /// Reproducer-mode regex matcher for the captured `scx_bpf_error`
220    /// text. When `Some(pattern)`, the eval pipeline compiles the
221    /// pattern via the `regex` crate, scans the combined scheduler
222    /// log + sched_ext dump, and fails the test if the regex does
223    /// not match anywhere in the corpus.
224    ///
225    /// The pattern is a full regex — special characters
226    /// (`. * + ? ( ) [ ] { } | ^ $ \`) carry their regex meaning.
227    /// For literal-substring matching, prefer
228    /// [`Self::expect_scx_bpf_error_contains`] to avoid escape
229    /// footguns. The captured corpus is the multi-line concatenation
230    /// of the scheduler log and `--- sched_ext dump ---`; the regex
231    /// crate's default flags apply: `^` and `$` anchor to the start /
232    /// end of the WHOLE corpus (not individual lines), and `.` does
233    /// NOT cross `\n`. Opt in to line-level anchoring with `(?m)`
234    /// (e.g. `(?m)^apply_cell_config$`) and to newline-spanning
235    /// `.` with `(?s)`. A bare `apply_cell_config` matches the
236    /// token anywhere in the corpus.
237    ///
238    /// Requires the entry's `expect_err = true` — same rationale
239    /// as [`Self::expect_scx_bpf_error_contains`]. Patterns are
240    /// validated at construction: empty literals, invalid regex
241    /// syntax, and any pattern satisfying `is_match("")` all
242    /// panic via the [`Self::expect_scx_bpf_error_matches`]
243    /// builder. The `is_match("")` predicate catches two
244    /// no-op classes with one check: patterns that match every
245    /// position (e.g. `a?`, `.*`, `(?:)`) trivially pass against
246    /// any corpus, and patterns that match only the empty string
247    /// (e.g. `^$`) trivially fail against any non-empty corpus —
248    /// real captured scheduler-output corpora are non-empty, so
249    /// both classes are equally no-op pins. Bare `\b` (word
250    /// boundary) slips the gate because the empty string
251    /// contains no word characters; see the builder docstring
252    /// for the operator-direction.
253    /// `#[serde(skip)]` for the same reason as
254    /// [`Self::expect_scx_bpf_error_contains`] above: `&'static str`
255    /// doesn't roundtrip + the matcher pattern is test-definition
256    /// data, not sidecar-roundtrip data. Skipped fields default to
257    /// `None` on deserialize.
258    #[serde(skip)]
259    pub expect_scx_bpf_error_matches: Option<&'static str>,
260}
261
262impl Assert {
263    /// Human-readable multi-line dump of every threshold field. Each
264    /// field renders as `  name: value` (`none` when the option is
265    /// `None`, i.e. inherited or unset). Used by
266    /// `cargo ktstr show-thresholds <test>` to expose the resolved
267    /// merged `Assert` (`default_checks().merge(&entry.scheduler.assert).
268    /// merge(&entry.assert)`) without forcing the operator to read
269    /// the Debug impl or source. Output is a sequence of indented
270    /// `row` lines ending with a newline; the caller owns any
271    /// outer section header (the `show-thresholds` CLI already
272    /// prints `Test: ...` / `Scheduler: ...` / `Resolved assertion
273    /// thresholds:` lines above the threshold block, and
274    /// `format_human` emits no outer header of its own so it does
275    /// not duplicate that banner).
276    pub fn format_human(&self) -> String {
277        use std::fmt::Write;
278        let mut out = String::new();
279        fn row<T: std::fmt::Display>(out: &mut String, name: &str, v: &Option<T>) {
280            match v {
281                Some(x) => writeln!(out, "  {name:<38}: {x}").unwrap(),
282                None => writeln!(out, "  {name:<38}: none").unwrap(),
283            }
284        }
285        row(&mut out, "not_stuck", &self.not_stuck);
286        row(&mut out, "isolation", &self.isolation);
287        row(&mut out, "max_gap_ms", &self.max_gap_ms);
288        row(&mut out, "max_spread_pct", &self.max_spread_pct);
289        row(&mut out, "max_throughput_cv", &self.max_throughput_cv);
290        row(&mut out, "min_work_rate", &self.min_work_rate);
291        row(
292            &mut out,
293            "max_p99_wake_latency_ns",
294            &self.max_p99_wake_latency_ns,
295        );
296        row(&mut out, "max_wake_latency_cv", &self.max_wake_latency_cv);
297        row(&mut out, "min_iteration_rate", &self.min_iteration_rate);
298        row(&mut out, "max_migration_ratio", &self.max_migration_ratio);
299        row(&mut out, "max_imbalance_ratio", &self.max_imbalance_ratio);
300        row(&mut out, "max_local_dsq_depth", &self.max_local_dsq_depth);
301        row(
302            &mut out,
303            "fail_on_rq_clock_stuck",
304            &self.fail_on_rq_clock_stuck,
305        );
306        row(&mut out, "sustained_samples", &self.sustained_samples);
307        row(&mut out, "max_fallback_rate", &self.max_fallback_rate);
308        row(&mut out, "max_keep_last_rate", &self.max_keep_last_rate);
309        row(&mut out, "min_page_locality", &self.min_page_locality);
310        row(
311            &mut out,
312            "max_cross_node_migration_ratio",
313            &self.max_cross_node_migration_ratio,
314        );
315        row(&mut out, "max_slow_tier_ratio", &self.max_slow_tier_ratio);
316        row(
317            &mut out,
318            "expect_scx_bpf_error_contains",
319            &self.expect_scx_bpf_error_contains,
320        );
321        row(
322            &mut out,
323            "expect_scx_bpf_error_matches",
324            &self.expect_scx_bpf_error_matches,
325        );
326        out
327    }
328
329    /// Identity element for [`Assert::merge`]: every Option field is
330    /// `None` and `enforce_monitor_thresholds` is `false`, so neither
331    /// side of a merge with `NO_OVERRIDES` is altered.
332    /// Identical to the value returned by [`Self::default_checks`] —
333    /// the const is for spread-into-struct-literal composition, the
334    /// const fn is the method-style entry point.
335    pub const NO_OVERRIDES: Assert = Assert {
336        not_stuck: None,
337        isolation: None,
338        max_gap_ms: None,
339        max_spread_pct: None,
340        max_throughput_cv: None,
341        min_work_rate: None,
342        max_p99_wake_latency_ns: None,
343        max_wake_latency_cv: None,
344        min_iteration_rate: None,
345        max_migration_ratio: None,
346        max_imbalance_ratio: None,
347        max_local_dsq_depth: None,
348        fail_on_rq_clock_stuck: None,
349        sustained_samples: None,
350        max_fallback_rate: None,
351        max_keep_last_rate: None,
352        enforce_monitor_thresholds: false,
353        min_page_locality: None,
354        max_cross_node_migration_ratio: None,
355        max_slow_tier_ratio: None,
356        expect_scx_bpf_error_contains: None,
357        expect_scx_bpf_error_matches: None,
358    };
359
360    /// Baseline of the runtime merge chain
361    /// `default_checks().merge(&scheduler.assert).merge(&entry.assert)`.
362    ///
363    /// All checks are off by default — tests opt in to the assertions
364    /// they care about via scheduler-level or per-test `Assert`
365    /// overrides.
366    ///
367    /// For spread-into-struct-literal composition
368    /// (`Assert { not_stuck: Some(true), ..Assert::NO_OVERRIDES }`)
369    /// use the equivalent const [`Self::NO_OVERRIDES`]; this const fn
370    /// is the method-style entry point that pairs with `.verdict()`
371    /// and the builder setters.
372    pub const fn default_checks() -> Assert {
373        Self::NO_OVERRIDES
374    }
375
376    /// Build a fresh [`Verdict`] under this `Assert`'s threshold
377    /// config. The returned accumulator carries no claim records; call
378    /// the typed `claim_<field>` methods generated by
379    /// [`#[derive(Claim)]`](ktstr_macros::Claim) on stats structs as
380    /// `stats.claim_<field>(&mut verdict)`, or use the
381    /// [`claim!`](crate::claim) macro on a local/expression, then
382    /// call [`Verdict::into_result`] to produce the final
383    /// [`AssertResult`].
384    ///
385    /// This is the entry point of the pointwise-claim API. The
386    /// `Assert` itself remains pure threshold config and stays
387    /// `Copy`; per-test claims accumulate on the returned `Verdict`,
388    /// which owns its own buffers (details, stats).
389    ///
390    /// ```
391    /// # use ktstr::assert::Assert;
392    /// let r = Assert::default_checks().verdict().into_result();
393    /// assert!(r.is_pass(), "no claims means passing verdict");
394    /// ```
395    pub fn verdict(self) -> Verdict {
396        Verdict::with_assert(self)
397    }
398
399    pub const fn check_not_stuck(mut self) -> Self {
400        self.not_stuck = Some(true);
401        self
402    }
403
404    pub const fn check_isolation(mut self) -> Self {
405        self.isolation = Some(true);
406        self
407    }
408
409    pub const fn max_gap_ms(mut self, ms: u64) -> Self {
410        self.max_gap_ms = Some(ms);
411        self
412    }
413
414    pub const fn max_spread_pct(mut self, pct: f64) -> Self {
415        self.max_spread_pct = Some(pct);
416        self
417    }
418
419    pub const fn max_throughput_cv(mut self, v: f64) -> Self {
420        self.max_throughput_cv = Some(v);
421        self
422    }
423
424    pub const fn min_work_rate(mut self, v: f64) -> Self {
425        self.min_work_rate = Some(v);
426        self
427    }
428
429    pub const fn max_p99_wake_latency_ns(mut self, v: u64) -> Self {
430        self.max_p99_wake_latency_ns = Some(v);
431        self
432    }
433
434    pub const fn max_wake_latency_cv(mut self, v: f64) -> Self {
435        self.max_wake_latency_cv = Some(v);
436        self
437    }
438
439    pub const fn min_iteration_rate(mut self, v: f64) -> Self {
440        self.min_iteration_rate = Some(v);
441        self
442    }
443
444    pub const fn max_migration_ratio(mut self, v: f64) -> Self {
445        self.max_migration_ratio = Some(v);
446        self
447    }
448
449    pub const fn max_imbalance_ratio(mut self, v: f64) -> Self {
450        self.max_imbalance_ratio = Some(v);
451        self
452    }
453
454    pub const fn max_local_dsq_depth(mut self, v: u32) -> Self {
455        self.max_local_dsq_depth = Some(v);
456        self
457    }
458
459    /// Control whether a monitor rq_clock-stuck verdict fails the assertion.
460    pub const fn fail_on_rq_clock_stuck(mut self, v: bool) -> Self {
461        self.fail_on_rq_clock_stuck = Some(v);
462        self
463    }
464
465    /// Set the number of consecutive over-threshold samples required
466    /// before the monitor raises a verdict.
467    pub const fn sustained_samples(mut self, v: usize) -> Self {
468        self.sustained_samples = Some(v);
469        self
470    }
471
472    pub const fn max_fallback_rate(mut self, v: f64) -> Self {
473        self.max_fallback_rate = Some(v);
474        self
475    }
476
477    pub const fn max_keep_last_rate(mut self, v: f64) -> Self {
478        self.max_keep_last_rate = Some(v);
479        self
480    }
481
482    pub const fn min_page_locality(mut self, v: f64) -> Self {
483        self.min_page_locality = Some(v);
484        self
485    }
486
487    pub const fn max_cross_node_migration_ratio(mut self, v: f64) -> Self {
488        self.max_cross_node_migration_ratio = Some(v);
489        self
490    }
491
492    pub const fn max_slow_tier_ratio(mut self, v: f64) -> Self {
493        self.max_slow_tier_ratio = Some(v);
494        self
495    }
496
497    /// True when any worker-level check field is `Some`. A pure query on
498    /// the configured checks — it no longer gates per-cgroup telemetry
499    /// (telemetry is built unconditionally per handle in
500    /// [`crate::scenario`]'s collect path; worker-check assertions are the
501    /// only opt-in part). Retained as public API for callers composing an
502    /// `Assert` who need to know whether any worker check is set.
503    pub const fn has_worker_checks(&self) -> bool {
504        self.not_stuck.is_some()
505            || self.isolation.is_some()
506            || self.max_gap_ms.is_some()
507            || self.max_spread_pct.is_some()
508            || self.max_throughput_cv.is_some()
509            || self.min_work_rate.is_some()
510            || self.max_p99_wake_latency_ns.is_some()
511            || self.max_wake_latency_cv.is_some()
512            || self.min_iteration_rate.is_some()
513            || self.max_migration_ratio.is_some()
514            || self.min_page_locality.is_some()
515            || self.max_cross_node_migration_ratio.is_some()
516            || self.max_slow_tier_ratio.is_some()
517    }
518
519    /// Merge `other` on top of `self`. Each `Some` field in `other`
520    /// overrides the corresponding field in `self`; `None` fields
521    /// inherit from `self`.
522    ///
523    /// [`Assert::NO_OVERRIDES`] is the two-sided identity:
524    /// `x.merge(&NO_OVERRIDES)` and `NO_OVERRIDES.merge(&x)` both yield
525    /// `x`. The runtime composes scheduler- and test-level overrides as
526    /// `Assert::default_checks().merge(&scheduler.assert).merge(&test.assert)`,
527    /// so a `NO_OVERRIDES` at either override layer leaves the defaults
528    /// untouched -- which means "no override," not "no checks."
529    pub const fn merge(&self, other: &Assert) -> Assert {
530        // `Option::or` is not yet const-stable, so each field expands
531        // a match rather than calling `other.x.or(self.x)`. Keep it
532        // this way until `const fn` can call `Option::or`; at that
533        // point the 21 match blocks collapse to 21 `.or()` calls.
534        Assert {
535            not_stuck: match other.not_stuck {
536                Some(v) => Some(v),
537                None => self.not_stuck,
538            },
539            isolation: match other.isolation {
540                Some(v) => Some(v),
541                None => self.isolation,
542            },
543            max_gap_ms: match other.max_gap_ms {
544                Some(v) => Some(v),
545                None => self.max_gap_ms,
546            },
547            max_spread_pct: match other.max_spread_pct {
548                Some(v) => Some(v),
549                None => self.max_spread_pct,
550            },
551            max_throughput_cv: match other.max_throughput_cv {
552                Some(v) => Some(v),
553                None => self.max_throughput_cv,
554            },
555            min_work_rate: match other.min_work_rate {
556                Some(v) => Some(v),
557                None => self.min_work_rate,
558            },
559            max_p99_wake_latency_ns: match other.max_p99_wake_latency_ns {
560                Some(v) => Some(v),
561                None => self.max_p99_wake_latency_ns,
562            },
563            max_wake_latency_cv: match other.max_wake_latency_cv {
564                Some(v) => Some(v),
565                None => self.max_wake_latency_cv,
566            },
567            min_iteration_rate: match other.min_iteration_rate {
568                Some(v) => Some(v),
569                None => self.min_iteration_rate,
570            },
571            max_migration_ratio: match other.max_migration_ratio {
572                Some(v) => Some(v),
573                None => self.max_migration_ratio,
574            },
575            max_imbalance_ratio: match other.max_imbalance_ratio {
576                Some(v) => Some(v),
577                None => self.max_imbalance_ratio,
578            },
579            max_local_dsq_depth: match other.max_local_dsq_depth {
580                Some(v) => Some(v),
581                None => self.max_local_dsq_depth,
582            },
583            fail_on_rq_clock_stuck: match other.fail_on_rq_clock_stuck {
584                Some(v) => Some(v),
585                None => self.fail_on_rq_clock_stuck,
586            },
587            sustained_samples: match other.sustained_samples {
588                Some(v) => Some(v),
589                None => self.sustained_samples,
590            },
591            max_fallback_rate: match other.max_fallback_rate {
592                Some(v) => Some(v),
593                None => self.max_fallback_rate,
594            },
595            max_keep_last_rate: match other.max_keep_last_rate {
596                Some(v) => Some(v),
597                None => self.max_keep_last_rate,
598            },
599            enforce_monitor_thresholds: self.enforce_monitor_thresholds
600                || other.enforce_monitor_thresholds,
601            min_page_locality: match other.min_page_locality {
602                Some(v) => Some(v),
603                None => self.min_page_locality,
604            },
605            max_cross_node_migration_ratio: match other.max_cross_node_migration_ratio {
606                Some(v) => Some(v),
607                None => self.max_cross_node_migration_ratio,
608            },
609            max_slow_tier_ratio: match other.max_slow_tier_ratio {
610                Some(v) => Some(v),
611                None => self.max_slow_tier_ratio,
612            },
613            expect_scx_bpf_error_contains: match other.expect_scx_bpf_error_contains {
614                Some(v) => Some(v),
615                None => self.expect_scx_bpf_error_contains,
616            },
617            expect_scx_bpf_error_matches: match other.expect_scx_bpf_error_matches {
618                Some(v) => Some(v),
619                None => self.expect_scx_bpf_error_matches,
620            },
621        }
622    }
623
624    /// Extract an `AssertPlan` for worker-side checks.
625    pub(crate) fn worker_plan(&self) -> AssertPlan {
626        AssertPlan {
627            not_stuck: self.not_stuck.unwrap_or(false),
628            isolation: self.isolation.unwrap_or(false),
629            max_gap_ms: self.max_gap_ms,
630            max_spread_pct: self.max_spread_pct,
631            max_throughput_cv: self.max_throughput_cv,
632            min_work_rate: self.min_work_rate,
633            max_p99_wake_latency_ns: self.max_p99_wake_latency_ns,
634            max_wake_latency_cv: self.max_wake_latency_cv,
635            min_iteration_rate: self.min_iteration_rate,
636            max_migration_ratio: self.max_migration_ratio,
637            min_page_locality: self.min_page_locality,
638            max_cross_node_migration_ratio: self.max_cross_node_migration_ratio,
639            max_slow_tier_ratio: self.max_slow_tier_ratio,
640        }
641    }
642
643    /// Run the configured worker checks against one cgroup's reports.
644    ///
645    /// `cpuset` is the CPU set for isolation checks. `numa_nodes` is
646    /// the NUMA node IDs covered by the cpuset (for page locality and
647    /// slow-tier checks). Derive via
648    /// [`TestTopology::numa_nodes_for_cpuset`](crate::topology::TestTopology::numa_nodes_for_cpuset).
649    pub fn assert_cgroup(
650        &self,
651        reports: &[crate::workload::WorkerReport],
652        cpuset: Option<&BTreeSet<usize>>,
653    ) -> AssertResult {
654        self.worker_plan().assert_cgroup(reports, cpuset, None)
655    }
656
657    /// Run worker checks with explicit NUMA node set for page locality.
658    pub fn assert_cgroup_with_numa(
659        &self,
660        reports: &[crate::workload::WorkerReport],
661        cpuset: Option<&BTreeSet<usize>>,
662        numa_nodes: Option<&BTreeSet<usize>>,
663    ) -> AssertResult {
664        self.worker_plan()
665            .assert_cgroup(reports, cpuset, numa_nodes)
666    }
667
668    /// Run NUMA page locality check.
669    ///
670    /// `observed` is the fraction of pages on expected nodes (0.0-1.0).
671    /// `total_pages` and `local_pages` are for diagnostics.
672    pub fn assert_page_locality(
673        &self,
674        observed: f64,
675        total_pages: u64,
676        local_pages: u64,
677    ) -> AssertResult {
678        assert_page_locality(observed, self.min_page_locality, total_pages, local_pages)
679    }
680
681    /// Run cross-node migration ratio check.
682    ///
683    /// `migrated_pages` is the `/proc/vmstat` `numa_pages_migrated` delta.
684    /// `total_pages` is total allocated pages from numa_maps.
685    pub fn assert_cross_node_migration(
686        &self,
687        migrated_pages: u64,
688        total_pages: u64,
689    ) -> AssertResult {
690        assert_cross_node_migration(
691            migrated_pages,
692            total_pages,
693            self.max_cross_node_migration_ratio,
694        )
695    }
696
697    /// Extract `MonitorThresholds` for monitor-side evaluation.
698    pub(crate) fn has_monitor_thresholds(&self) -> bool {
699        self.max_imbalance_ratio.is_some()
700            || self.max_local_dsq_depth.is_some()
701            || self.fail_on_rq_clock_stuck.is_some()
702            || self.sustained_samples.is_some()
703            || self.max_fallback_rate.is_some()
704            || self.max_keep_last_rate.is_some()
705    }
706
707    pub(crate) fn monitor_thresholds(&self) -> crate::monitor::MonitorThresholds {
708        use crate::monitor::MonitorThresholds;
709        let d = MonitorThresholds::new();
710        MonitorThresholds {
711            max_imbalance_ratio: self.max_imbalance_ratio.unwrap_or(d.max_imbalance_ratio),
712            max_local_dsq_depth: self.max_local_dsq_depth.unwrap_or(d.max_local_dsq_depth),
713            fail_on_rq_clock_stuck: self
714                .fail_on_rq_clock_stuck
715                .unwrap_or(d.fail_on_rq_clock_stuck),
716            sustained_samples: self.sustained_samples.unwrap_or(d.sustained_samples),
717            max_fallback_rate: self.max_fallback_rate.unwrap_or(d.max_fallback_rate),
718            max_keep_last_rate: self.max_keep_last_rate.unwrap_or(d.max_keep_last_rate),
719            enforce: self.enforce_monitor_thresholds,
720        }
721    }
722
723    /// Opt into pass/fail enforcement for monitor thresholds. Without
724    /// this call, monitor violations are reported in the verdict's
725    /// `details` but do not fail the test. With it, any monitor
726    /// threshold violation fails the test.
727    ///
728    /// Also populates any unset monitor-threshold field with the
729    /// canonical default from `MonitorThresholds::new()`
730    /// — so a test that only cares about `max_keep_last_rate` can chain
731    /// `.max_keep_last_rate(N).with_monitor_defaults()` and get the
732    /// other five enforced at their canonical defaults.
733    pub const fn with_monitor_defaults(mut self) -> Self {
734        use crate::monitor::MonitorThresholds;
735        let d = MonitorThresholds::new();
736        if self.max_imbalance_ratio.is_none() {
737            self.max_imbalance_ratio = Some(d.max_imbalance_ratio);
738        }
739        if self.max_local_dsq_depth.is_none() {
740            self.max_local_dsq_depth = Some(d.max_local_dsq_depth);
741        }
742        if self.fail_on_rq_clock_stuck.is_none() {
743            self.fail_on_rq_clock_stuck = Some(d.fail_on_rq_clock_stuck);
744        }
745        if self.sustained_samples.is_none() {
746            self.sustained_samples = Some(d.sustained_samples);
747        }
748        if self.max_fallback_rate.is_none() {
749            self.max_fallback_rate = Some(d.max_fallback_rate);
750        }
751        if self.max_keep_last_rate.is_none() {
752            self.max_keep_last_rate = Some(d.max_keep_last_rate);
753        }
754        self.enforce_monitor_thresholds = true;
755        self
756    }
757
758    /// Const-fn builder for [`Self::expect_scx_bpf_error_contains`].
759    /// Chains with the other const-fn setters so a scheduler-def or
760    /// per-test assertion block can compose
761    /// `Assert::NO_OVERRIDES.expect_scx_bpf_error_contains(...).check_not_stuck()`.
762    ///
763    /// Empty strings panic at construction (an empty literal would
764    /// silently match every message and turn this assertion into a
765    /// no-op); pass a non-empty fragment that should appear in the
766    /// expected `scx_bpf_error` message.
767    ///
768    /// # Panics
769    /// When `literal` is empty.
770    #[must_use = "builder methods consume self; bind the result"]
771    pub const fn expect_scx_bpf_error_contains(mut self, literal: &'static str) -> Self {
772        assert!(
773            !literal.is_empty(),
774            "Assert::expect_scx_bpf_error_contains: literal must be non-empty",
775        );
776        self.expect_scx_bpf_error_contains = Some(literal);
777        self
778    }
779
780    /// Builder for [`Self::expect_scx_bpf_error_matches`]. The
781    /// pattern is a regex; special characters retain their regex
782    /// meaning. For literal-substring matching, prefer
783    /// [`Self::expect_scx_bpf_error_contains`] to avoid escape
784    /// footguns.
785    ///
786    /// Validates the pattern at construction: rejects empty
787    /// patterns, rejects invalid regex syntax, and rejects any
788    /// pattern that satisfies `is_match("")`. The empty-string
789    /// match predicate catches two related no-op classes:
790    /// patterns that match every position (e.g. `a?`, `.*`,
791    /// `(?:)`) trivially pass against any corpus, and patterns
792    /// that match only the empty string (e.g. `^$`) trivially
793    /// fail against any non-empty corpus — every real captured
794    /// scheduler-output corpus is non-empty, so the latter is
795    /// equally a no-op pin in practice. Both are useless;
796    /// `is_match("")` catches both with one check.
797    ///
798    /// Bare `\b` (word boundary) slips this gate because the
799    /// empty string contains no word characters, so `\b` finds
800    /// no transition and `is_match("")` returns false; yet `\b`
801    /// matches the first word boundary in any real corpus,
802    /// turning a bare-`\b` pin into a vacuous "any non-empty
803    /// log passes" assertion. Use a substring of the expected
804    /// error text rather than a standalone boundary assertion.
805    /// All other documented assertions (`\A`, `\z`, `^`, `$`,
806    /// `\B`) match the empty string at position 0 and ARE
807    /// caught by the gate.
808    ///
809    /// Unlike the sibling [`Self::expect_scx_bpf_error_contains`]
810    /// (which is `const fn`), this builder is non-const because
811    /// the construction-time regex compilation requires heap
812    /// allocation. Callers needing a const builder for a regex
813    /// matcher must build the `Assert` via struct literal —
814    /// the evaluator's defense-in-depth catches invalid syntax
815    /// reached via that bypass at first evaluation, but the
816    /// vacuous-pattern gate only fires on the builder path.
817    ///
818    /// # Panics
819    /// When `pattern` is empty, is invalid regex syntax, or
820    /// matches the empty string.
821    #[must_use = "builder methods consume self; bind the result"]
822    pub fn expect_scx_bpf_error_matches(mut self, pattern: &'static str) -> Self {
823        assert!(
824            !pattern.is_empty(),
825            "Assert::expect_scx_bpf_error_matches: pattern must be non-empty",
826        );
827        let compiled = regex::Regex::new(pattern).unwrap_or_else(|e| {
828            panic!(
829                "Assert::expect_scx_bpf_error_matches: pattern {pattern:?} is not valid regex: {e}",
830            )
831        });
832        assert!(
833            !compiled.is_match(""),
834            "Assert::expect_scx_bpf_error_matches: pattern {pattern:?} matches the empty \
835             string (e.g. `a?`, `.*`, `(?:)`, `^$`); such patterns vacuously match any \
836             corpus and turn the matcher into a no-op — use a meaningful pattern that \
837             requires at least one character",
838        );
839        self.expect_scx_bpf_error_matches = Some(pattern);
840        self
841    }
842
843    /// Evaluate the reproducer-mode `scx_bpf_error` matchers against
844    /// the captured text corpus. Returns an empty Vec when no matcher
845    /// is configured or when every configured matcher matches; returns
846    /// a non-empty Vec of `AssertDetail` entries on failure.
847    ///
848    /// Each configured matcher contributes at most one detail. Both
849    /// fields can be set simultaneously (`AND` semantics — both must
850    /// match).
851    ///
852    /// Preconditions enforced by the evaluator:
853    /// 1. `expect_err = true` must be set when either matcher is
854    ///    configured. Setting the matcher on a passing-test contract
855    ///    is a misuse — surfaced with an `expect_err = true` reminder
856    ///    diagnostic.
857    /// 2. The regex pattern in
858    ///    [`Self::expect_scx_bpf_error_matches`] must compile via
859    ///    the `regex` crate. Invalid syntax surfaces as a diagnostic
860    ///    naming the pattern and the compile error.
861    ///
862    /// `captured_text` is the concatenation of the raw scheduler-log
863    /// stream (the bulk-port merged `SchedLog` frames, or the test
864    /// process `output` fallback when no frames arrived) and the
865    /// `--- sched_ext dump ---` extract — both surfaces where
866    /// `scx_bpf_error` printk lands. The matcher sees the WHOLE
867    /// stream, not the marker-extracted section; lines outside the
868    /// `SCHED_OUTPUT_START..SCHED_OUTPUT_END` markers are included.
869    pub fn evaluate_scx_bpf_error_match(
870        &self,
871        captured_text: &str,
872        expect_err: bool,
873    ) -> Vec<AssertDetail> {
874        let mut details = Vec::new();
875        if self.expect_scx_bpf_error_contains.is_none()
876            && self.expect_scx_bpf_error_matches.is_none()
877        {
878            return details;
879        }
880        if !expect_err {
881            details.push(AssertDetail::new(
882                DetailKind::Other,
883                "expect_scx_bpf_error_contains or expect_scx_bpf_error_matches \
884                 requires expect_err = true on the test entry — the matcher narrows \
885                 which failure counts as the expected bug, and only applies to \
886                 expected-error tests; set #[ktstr_test(expect_err = true, ...)] or \
887                 drop the matcher",
888            ));
889            return details;
890        }
891        // Truncate at a UTF-8 char boundary at or below 400 bytes so
892        // the excerpt length stays within the "up to 400 bytes follow:"
893        // budget. `chars().take(400)` would count codepoints instead,
894        // and a multi-byte corpus would exceed the byte budget — the
895        // boundary walk steps back to the nearest char start.
896        let excerpt = || -> &str {
897            let len = captured_text.len();
898            if len <= 400 {
899                captured_text
900            } else {
901                let mut end = 400;
902                while end > 0 && !captured_text.is_char_boundary(end) {
903                    end -= 1;
904                }
905                &captured_text[..end]
906            }
907        };
908        if let Some(literal) = self.expect_scx_bpf_error_contains
909            && !captured_text.contains(literal)
910        {
911            details.push(AssertDetail::new(
912                DetailKind::Other,
913                format!(
914                    "expect_scx_bpf_error_contains({literal:?}): substring not found \
915                     in the scheduler log + sched_ext dump corpus (the expected bug \
916                     did not fire, or its message text changed). Captured corpus \
917                     {} bytes; up to 400 bytes follow:\n{}",
918                    captured_text.len(),
919                    excerpt(),
920                ),
921            ));
922        }
923        if let Some(pattern) = self.expect_scx_bpf_error_matches {
924            match regex::Regex::new(pattern) {
925                Ok(re) => {
926                    if !re.is_match(captured_text) {
927                        details.push(AssertDetail::new(
928                            DetailKind::Other,
929                            format!(
930                                "expect_scx_bpf_error_matches({pattern:?}): regex did \
931                                 not match the scheduler log + sched_ext dump corpus \
932                                 (the expected bug did not fire, or its message text \
933                                 changed). Captured corpus {} bytes; up to 400 bytes \
934                                 follow:\n{}",
935                                captured_text.len(),
936                                excerpt(),
937                            ),
938                        ));
939                    }
940                }
941                Err(e) => {
942                    details.push(AssertDetail::new(
943                        DetailKind::Other,
944                        format!(
945                            "expect_scx_bpf_error_matches({pattern:?}): regex \
946                             compilation failed: {e}. Fix the pattern at the test \
947                             declaration site — the matcher cannot evaluate against an \
948                             invalid pattern",
949                        ),
950                    ));
951                }
952            }
953        }
954        details
955    }
956}