ktstr/test_support/
dispatch.rs

1//! Process-level dispatch and nextest protocol handling.
2//!
3//! This module owns every code path that runs before (or in lieu of)
4//! the user's `main()`:
5//!
6//! - [`ktstr_test_early_dispatch`]: the `#[ctor]` that fires in every
7//!   ktstr-linked binary. Routes the process to guest init, host-side
8//!   VM launch, guest-side test execution, or nextest protocol handling.
9//! - [`ktstr_main`]: the nextest protocol handler — `--list` returns
10//!   `ktstr/`, `gauntlet/`, and `host/` test names, `--exact` runs a single
11//!   test. The prefix is also a resource-admission identity: `ktstr/` and
12//!   `gauntlet/` boot VMs, while `host/` entries are ordinary host work.
13//! - [`run_ktstr_test`]: programmatic entry point used by library
14//!   consumers and the macro-generated `#[test]` wrappers.
15//! - [`analyze_sidecars`]: collects sidecar JSON from a run directory
16//!   and renders the full gauntlet analysis (rows + verifier + callback
17//!   profile + KVM stats) into a string.
18//!
19//! The heavy lifting lives in sibling submodules: `eval` (host-side
20//! result judgment — `run_ktstr_test_inner` and `evaluate_vm_result`),
21//! `sidecar` (per-run JSON), `probe` (auto-repro + BPF probe pipeline),
22//! `args` (CLI extraction), and the [`crate::vmm`] VM launcher.
23
24use std::path::PathBuf;
25
26use anyhow::{Context, Result};
27
28use crate::assert::AssertResult;
29
30#[cfg(feature = "export")]
31use super::extract_export_output_arg;
32use super::{
33    HostClass, KTSTR_TESTS, KtstrTestEntry, TopoOverride, classify_host_error, collect_sidecars,
34    extract_export_check_test_arg, extract_export_test_arg, extract_shell_test_arg,
35    extract_test_fn_arg, extract_topo_arg, find_test, format_callback_profile, format_kvm_stats,
36    format_verifier_stats, maybe_dispatch_vm_test, parse_topo_string,
37    propagate_rust_env_from_cmdline, record_skip_sidecar, resolve_test_kernel,
38    run_ktstr_test_inner, sidecar_dir, try_flush_profraw,
39};
40
41/// Check if an error is a host topology mismatch (e.g. test requests
42/// 2 LLCs but host has 1, or more CPUs than the host carries).
43///
44/// Walks the FULL error chain via `e.chain().any(...)` so a
45/// [`TopologyInsufficient`] wrapped in `.context(...)` (the
46/// `crate::test_support::eval` `"build ktstr_test VM"` / `"run
47/// ktstr_test VM"` wrappers) is still recognised — mirrors
48/// [`is_resource_contention`]. Replaced a fragile message string-match
49/// (`"need"` + `"LLC"`/`"CPU"`) that would misclassify any unrelated
50/// error happening to contain those words as a topology skip.
51///
52/// [`TopologyInsufficient`]: crate::vmm::host_topology::TopologyInsufficient
53#[doc(hidden)]
54pub fn is_topology_insufficient(e: &anyhow::Error) -> bool {
55    e.chain().any(|cause| {
56        cause
57            .downcast_ref::<crate::vmm::host_topology::TopologyInsufficient>()
58            .is_some()
59    })
60}
61
62/// Check if an `anyhow::Error` carries a [`ResourceContention`].
63///
64/// Walks the FULL error chain via `e.chain().any(...)` so a
65/// `ResourceContention` wrapped in `.context(...)` (e.g. the
66/// `crate::test_support::eval` `"build ktstr_test VM"` and `"run ktstr_test VM"`
67/// wrappers) is still recognised — the macro's match arm depends on
68/// this.
69///
70/// Used by the `#[ktstr_test]` macro expansion to short-circuit on
71/// host-resource contention (LLC slots / CPUs unavailable, KVM fd
72/// budget exhausted, ENOMEM): the macro emits the canonical
73/// `ktstr: SKIP: resource contention: ...` banner and early-returns
74/// so libtest sees pass. The skip sidecar is recorded at every
75/// contention site inside `run_ktstr_test_inner`, so stats tooling
76/// still sees the skip without a panic-driven nextest retry. `pub`
77/// because the macro-generated `#[test]` body in `ktstr-macros`
78/// references it by absolute path; `#[doc(hidden)]` keeps it out
79/// of rustdoc's public surface — it is plumbing, not user API.
80///
81/// [`ResourceContention`]: crate::vmm::host_topology::ResourceContention
82#[doc(hidden)]
83pub fn is_resource_contention(e: &anyhow::Error) -> bool {
84    e.chain().any(|cause| {
85        cause
86            .downcast_ref::<crate::vmm::host_topology::ResourceContention>()
87            .is_some()
88    })
89}
90
91/// Check if an `anyhow::Error` carries a [`PerfModeUnavailable`].
92///
93/// Chain-aware (walks `e.chain()`), like [`is_topology_insufficient`].
94/// A `PerfModeUnavailable` is a HOST-INSUFFICIENCY skip, like RC/TI: the
95/// host fundamentally cannot honor an explicitly-requested perf-mode
96/// guarantee (too few CPUs for an exclusive host LLC + a service CPU).
97/// The VM is never run unisolated (it errors at build), so
98/// `result_to_exit_code` and the macro body route it to a VISIBLE skip
99/// by default, promoted to a FAIL banner under `KTSTR_NO_SKIP_MODE`.
100///
101/// [`PerfModeUnavailable`]: crate::vmm::host_topology::PerfModeUnavailable
102#[doc(hidden)]
103pub fn is_perf_mode_unavailable(e: &anyhow::Error) -> bool {
104    e.chain().any(|cause| {
105        cause
106            .downcast_ref::<crate::vmm::host_topology::PerfModeUnavailable>()
107            .is_some()
108    })
109}
110
111/// Check if an `anyhow::Error` carries a [`CpuBudgetUnsatisfiable`].
112///
113/// Chain-aware. A `CpuBudgetUnsatisfiable` is a HARD ERROR (an operator
114/// `--cpu-cap` number the host cannot satisfy), NOT a skip. (An author's
115/// per-test `cpu_budget` over the allowance skips via `TopologyInsufficient`
116/// instead — see `resolve_cpu_budget` — so it never carries this type.)
117///
118/// [`CpuBudgetUnsatisfiable`]: crate::vmm::host_topology::CpuBudgetUnsatisfiable
119#[doc(hidden)]
120pub fn is_cpu_budget_unsatisfiable(e: &anyhow::Error) -> bool {
121    e.chain().any(|cause| {
122        cause
123            .downcast_ref::<crate::vmm::host_topology::CpuBudgetUnsatisfiable>()
124            .is_some()
125    })
126}
127
128/// Check if an `anyhow::Error` carries a [`TopologyUnrepresentable`].
129///
130/// Chain-aware. A `TopologyUnrepresentable` is a HARD ERROR (a topology no
131/// host can represent under this VMM's static device layout — the aarch64
132/// over-`MAX_VCPUS` GICv3-redistributor case), NOT a skip.
133/// `classify_host_error` classifies it as `HostClass::Fail`, checked above
134/// the RC/TI skip types and handled above the `expect_err` inversion in
135/// both `err_to_exit_code` and the macro body, so a too-wide aarch64
136/// topology can neither masquerade as the expected failure nor be turned
137/// into a silent skip. Distinct from [`is_topology_insufficient`], which
138/// matches the host-DEPENDENT skip type.
139///
140/// [`TopologyUnrepresentable`]: crate::vmm::host_topology::TopologyUnrepresentable
141#[doc(hidden)]
142pub fn is_topology_unrepresentable(e: &anyhow::Error) -> bool {
143    e.chain().any(|cause| {
144        cause
145            .downcast_ref::<crate::vmm::host_topology::TopologyUnrepresentable>()
146            .is_some()
147    })
148}
149
150/// Predicate: walks the [`anyhow::Error`] chain looking for a
151/// [`KernelUnavailable`] cause. Used by `classify_host_error` to classify
152/// a no-kernel host as a skip-class host-insufficiency.
153///
154/// The harness signals "I have no kernel to boot, the binary was
155/// likely invoked outside `cargo ktstr test`" by surfacing
156/// [`KernelUnavailable`] rather than a generic `anyhow::bail!`.
157/// `classify_host_error` maps it to `HostClass::Skip` (the canonical
158/// `ktstr: SKIP: harness not configured: ...` banner), promoted to a FAIL
159/// under `KTSTR_NO_SKIP_MODE` — same shape as the resource-contention skip.
160/// `pub` + `#[doc(hidden)]`: plumbing re-exported from `test_support`
161/// alongside the sibling `is_*` predicates, not user API.
162///
163/// Both consumers route a `KernelUnavailable` through the shared
164/// [`classify_host_error`] (a no-kernel host is a skip-class
165/// host-insufficiency): `err_to_exit_code` and the `#[ktstr_test]` macro
166/// body both SKIP it by default, promoted to a FAIL under
167/// `KTSTR_NO_SKIP_MODE`. Under nextest the plain `#[test]` wrapper is
168/// suppressed, so a VM entry dispatches as `ktstr/{name}` (and a host-only
169/// entry as `host/{name}`) via `run_named_test` → `err_to_exit_code` —
170/// meaning a developer running `cargo nextest run`,
171/// or `cargo ktstr test` without `--kernel`, on a kernel-less host gets a
172/// clean skip rather than a hard fail on every entry. This cannot mask a CI
173/// kernel-build failure: a requested `--kernel` that fails to build bails in
174/// cargo-ktstr (`resolve_kernel_set`) before nextest is spawned, so a
175/// `KernelUnavailable` here only ever means "no kernel was requested".
176/// Pinned by `result_to_exit_code_kernel_unavailable_skips_on_dispatch_path`.
177///
178/// [`classify_host_error`]: crate::test_support::classify_host_error
179///
180/// [`KernelUnavailable`]: crate::test_support::eval::KernelUnavailable
181#[doc(hidden)]
182pub fn is_kernel_unavailable(e: &anyhow::Error) -> bool {
183    e.chain().any(|cause| {
184        cause
185            .downcast_ref::<crate::test_support::eval::KernelUnavailable>()
186            .is_some()
187    })
188}
189
190/// A nextest-safe kernel identifier whose construction is gated
191/// through [`sanitize_kernel_label`] — once a value of this type
192/// exists, the contained string is GUARANTEED to match the
193/// `kernel_[a-z0-9_]+` shape that nextest's test-name parsing
194/// accepts. The wrapped `String` is private so a future caller
195/// cannot bypass [`Self::new`] and stuff a raw label into the
196/// invariant.
197///
198/// Constructed by [`Self::new`] (which always calls
199/// [`sanitize_kernel_label`]). Read access is via
200/// [`Self::as_str`] / `Display` / `AsRef<str>` — both of which
201/// expose the sanitized form unchanged.
202///
203/// `pub(crate)` because every consumer (this module, the
204/// production parser at [`parse_kernel_list`], and the encoder
205/// helpers in `cargo-ktstr` that emit the wire format
206/// `parse_kernel_list` decodes) lives inside the workspace; no external
207/// surface is needed today. If a future external consumer needs
208/// to construct a `SanitizedKernelLabel` directly, expose
209/// `Self::new` as `pub` then — but the private inner stays a
210/// private invariant either way.
211#[derive(Clone, Debug, PartialEq, Eq, Hash)]
212pub(crate) struct SanitizedKernelLabel(String);
213
214impl SanitizedKernelLabel {
215    /// Sanitize `raw` via [`sanitize_kernel_label`] and wrap the
216    /// result in the invariant-preserving newtype. The only path
217    /// that produces a `SanitizedKernelLabel`; bypassing it is
218    /// impossible because the inner field is private to this
219    /// module.
220    pub(crate) fn new(raw: &str) -> Self {
221        Self(sanitize_kernel_label(raw))
222    }
223
224    /// Read access to the sanitized identifier. Returns `&str`
225    /// rather than `&String` so callers can compose with
226    /// `format!` / `starts_with` / `strip_suffix` without
227    /// chaining `.as_str().as_str()`.
228    pub(crate) fn as_str(&self) -> &str {
229        &self.0
230    }
231}
232
233impl std::fmt::Display for SanitizedKernelLabel {
234    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
235        f.write_str(&self.0)
236    }
237}
238
239impl AsRef<str> for SanitizedKernelLabel {
240    fn as_ref(&self) -> &str {
241        &self.0
242    }
243}
244
245// `PartialEq<&str>` and `PartialEq<str>` impls let `assert_eq!`
246// against a string literal stay readable in tests
247// (`assert_eq!(entries[0].sanitized, "kernel_6_14_2")`) without
248// forcing every consumer to chain `.as_str()`. The wrapped
249// `String` is private to this module, so impls comparing
250// against external `&str` values cannot break the
251// "constructor enforces sanitization" invariant — the
252// invariant attaches to value PRODUCTION, not to value
253// COMPARISON.
254impl PartialEq<&str> for SanitizedKernelLabel {
255    fn eq(&self, other: &&str) -> bool {
256        self.0 == *other
257    }
258}
259
260impl PartialEq<str> for SanitizedKernelLabel {
261    fn eq(&self, other: &str) -> bool {
262        self.0 == other
263    }
264}
265
266#[cfg(test)]
267impl SanitizedKernelLabel {
268    /// Test-only escape hatch: wrap a string that's ALREADY in
269    /// the sanitized shape (`kernel_[a-z0-9_]+`) without running
270    /// the sanitizer. Used by unit-test fixtures that hand-roll
271    /// `KernelEntry` values whose `sanitized` field is meant to
272    /// be a literal — running [`Self::new`] on `"kernel_6_14_2"`
273    /// would double-prefix to `"kernel_kernel_6_14_2"`.
274    ///
275    /// Production code must NEVER call this — invariant
276    /// violation here means callers can stuff arbitrary strings
277    /// into the field, defeating the point of the newtype.
278    /// `#[cfg(test)]` enforces that at compile time.
279    pub(crate) fn from_pre_sanitized_for_test(s: &str) -> Self {
280        Self(s.to_string())
281    }
282}
283
284/// One resolved kernel entry from `KTSTR_KERNEL_LIST` (the multi-
285/// kernel fan-out wire format that `cargo ktstr test --kernel A
286/// --kernel B` or `cargo ktstr verifier --kernel A --kernel B`
287/// exports before exec'ing into `cargo nextest`).
288///
289/// `label` is the producer-side label string before
290/// sanitization — e.g. `"6.14.2"` for Version, `"git_tj_sched_ext_for-next"`
291/// for Git, `"6.14.2-tarball-x86_64-kc..."` for CacheKey,
292/// `"path_linux_a3f2b1"` for Path. Preserved so the
293/// [`crate::test_support::dispatch`] verifier sweep filter can
294/// compare against `declare_scheduler!`'s `kernels = [...]`
295/// declarations — specifically, range membership
296/// (`"6.14..6.16"` vs `"6.14.2"`) needs the raw version string
297/// to feed into [`crate::kernel_path::decompose_version_for_compare`],
298/// which the sanitized form has lost (slashes / dots → underscores).
299///
300/// `sanitized` is the nextest-safe identifier appended to test names
301/// so `cargo nextest run -E 'test(kernel_6_14_2)'` filters work
302/// natively. The producer-side encoder in `cargo-ktstr` emits a
303/// semantic, operator-readable label per kernel:
304/// - Version / Range expansion: the version string verbatim
305///   (`6.14.2`, `6.15-rc3`).
306/// - CacheKey: the version prefix for tarballs, a compact
307///   `git_{kind}_{refhash6}` label for content-addressed git entries,
308///   or the legacy ref prefix for older `-git-` keys.
309/// - Git: `git_{owner}_{repo}_{kind}_{ref}` extracted from the URL
310///   (kind = tag/branch/sha).
311/// - Path: `path_{basename}_{hash6}` — basename + 6-char crc32 of
312///   the canonical path, disambiguating two `linux` directories
313///   under different parents.
314///
315/// [`SanitizedKernelLabel::new`] (which calls [`sanitize_kernel_label`])
316/// applies the `kernel_` prefix and `[a-z0-9_]+` normalization
317/// downstream. The newtype on this field makes the invariant
318/// compile-checked: a future caller cannot construct a
319/// `KernelEntry` whose `sanitized` field skipped sanitization.
320///
321/// `kernel_dir` is the canonical absolute path to the kernel-build
322/// directory the per-variant subprocess re-exports as
323/// `KTSTR_KERNEL`.
324#[derive(Clone, Debug)]
325pub(crate) struct KernelEntry {
326    pub(crate) label: String,
327    pub(crate) sanitized: SanitizedKernelLabel,
328    pub(crate) kernel_dir: PathBuf,
329}
330
331/// Parse the multi-kernel wire format `KTSTR_KERNEL_LIST` into a
332/// `Vec<KernelEntry>`. Format: `label1=path1;label2=path2;...`,
333/// semicolon-separated entries, `=` separating label from path. Empty
334/// / unset env returns an empty vec — callers treat that as
335/// "single-kernel mode" and fall through to `KTSTR_KERNEL`.
336///
337/// Malformed entries (missing `=`, empty label, empty path) are
338/// dropped silently — the producer is `cargo ktstr` which encodes
339/// the format under our control, so a malformed entry indicates a
340/// regression in the producer rather than operator input that
341/// deserves a clear error. Silent drop preserves the `len() <= 1` →
342/// "treat as single-kernel" invariant in the readers downstream.
343pub(crate) fn parse_kernel_list(raw: &str) -> Vec<KernelEntry> {
344    raw.split(';')
345        .filter_map(|seg| {
346            let seg = seg.trim();
347            if seg.is_empty() {
348                return None;
349            }
350            let (label, path) = seg.split_once('=')?;
351            let label = label.trim();
352            let path = path.trim();
353            if label.is_empty() || path.is_empty() {
354                return None;
355            }
356            Some(KernelEntry {
357                label: label.to_string(),
358                sanitized: SanitizedKernelLabel::new(label),
359                kernel_dir: PathBuf::from(path),
360            })
361        })
362        .collect()
363}
364
365/// Read [`crate::KTSTR_KERNEL_LIST_ENV`] and parse it into a
366/// `Vec<KernelEntry>`. Empty / unset / malformed → empty vec
367/// (single-kernel mode at the call site).
368pub(crate) fn read_kernel_list() -> Vec<KernelEntry> {
369    std::env::var(crate::KTSTR_KERNEL_LIST_ENV)
370        .ok()
371        .map(|v| parse_kernel_list(&v))
372        .unwrap_or_default()
373}
374
375/// Sanitise a kernel label (the producer-side identity emitted by
376/// `cargo ktstr`'s resolver) into a nextest-safe identifier of the
377/// shape `kernel_[a-z0-9_]+`.
378///
379/// Replaces every `[^A-Za-z0-9]` byte with `_`, lowercases, collapses
380/// runs of `_`, and prefixes with `kernel_`. Empty / pathologically-
381/// short input collapses to `kernel_` alone, which the parser
382/// downstream still recognises as a valid suffix (the empty
383/// `sanitized` marker just won't disambiguate two kernels — but the
384/// producer side guarantees non-empty labels, so the empty case is
385/// defensive only).
386///
387/// Example mappings:
388/// - `6.14.2` → `kernel_6_14_2`
389/// - `6.15-rc3` → `kernel_6_15_rc3`
390/// - `git_tj_sched_ext_for-next` → `kernel_git_tj_sched_ext_for_next`
391/// - `path_linux_a3f2b1` → `kernel_path_linux_a3f2b1`
392pub fn sanitize_kernel_label(raw: &str) -> String {
393    let mut out = String::with_capacity(raw.len() + 7);
394    out.push_str("kernel_");
395    let mut last_underscore = true; // suppress leading `_` after `kernel_`
396    for ch in raw.chars() {
397        let c = ch.to_ascii_lowercase();
398        if c.is_ascii_alphanumeric() {
399            out.push(c);
400            last_underscore = false;
401        } else if !last_underscore {
402            out.push('_');
403            last_underscore = true;
404        }
405    }
406    // Strip a trailing `_` so a label like `for-next-` doesn't
407    // produce a dangling separator.
408    if out.ends_with('_') && out.len() > "kernel_".len() {
409        out.pop();
410    }
411    out
412}
413
414ctor::declarative::ctor! {
415/// Early dispatch for `#[ktstr_test]` test execution.
416///
417/// Runs before `main()` in any binary that links against ktstr.
418///
419/// When running as PID 1 (the binary is `/init` in the VM), calls
420/// `ktstr_guest_init()` which handles the full init lifecycle and never
421/// returns.
422///
423/// - `--ktstr-test-fn=NAME --ktstr-topo=NnNlNcNt`: host-side dispatch —
424///   boots a VM with the specified topology and runs the test inside it.
425/// - `--ktstr-test-fn=NAME` (without `--ktstr-topo`): guest-side dispatch —
426///   runs the test function directly (inside a VM that was already booted).
427/// - nextest protocol (`--list`/`--exact`): intercepted when running
428///   under nextest (`NEXTEST` env var set), delegates to [`ktstr_main`].
429/// - Otherwise: no-op (falls through to the standard test harness).
430///
431/// ctor 1.0 ships both `#[ctor::ctor(...)]` (proc-macro attribute) and
432/// `ctor::declarative::ctor! { ... }` (declarative block). This site
433/// uses the declarative form because it sidesteps the TT-muncher
434/// recursion-limit cost the proc-macro form would impose on the
435/// ktstr_test expansion. The proc-macro form stays reachable via
436/// `crate::__private::ctor::ctor` for downstream consumers that prefer
437/// the attribute-on-fn shape; see `tests/private_module_paths.rs` for
438/// the re-export contract.
439#[doc(hidden)]
440#[ctor(unsafe)]
441pub fn ktstr_test_early_dispatch() {
442    // PID 1: the binary is /init in the VM. Perform full init lifecycle
443    // (mounts, scheduler, test dispatch, reboot). Never returns.
444    if unsafe { libc::getpid() } == 1 {
445        crate::vmm::rust_init::ktstr_guest_init();
446    }
447
448    // Export-self dispatch runs BEFORE host/guest test dispatch.
449    // `cargo ktstr export` is a router that exec's the test binary
450    // with `--ktstr-export-test=NAME`; the binary reads its own
451    // `KTSTR_TESTS` registry, embeds itself via `current_exe`, and
452    // writes the .run file. Running this check first means the
453    // export path never accidentally triggers VM boot if the
454    // operator simultaneously passes `--ktstr-test-fn` (the export
455    // arg wins because export is a one-shot tool, not a test
456    // execution).
457    if let Some(code) = maybe_dispatch_export() {
458        std::process::exit(code);
459    }
460    if let Some(code) = maybe_dispatch_shell_test() {
461        std::process::exit(code);
462    }
463    if let Some(code) = maybe_dispatch_host_test() {
464        std::process::exit(code);
465    }
466    // Propagate RUST_BACKTRACE / RUST_LOG from /proc/cmdline before
467    // `maybe_dispatch_vm_test` runs: ctor context is single-threaded
468    // (`.init_array` runs before any user thread exists), so this
469    // `set_var` is sound and the later guest-side code that spawns
470    // the probe thread observes the correct env.
471    propagate_rust_env_from_cmdline();
472    if let Some(code) = maybe_dispatch_vm_test() {
473        // The LLVM profiling runtime registers its atexit handler via a
474        // .init_array entry (C++ global initializer). Our ctor also lives
475        // in .init_array, and the execution order between them is
476        // non-deterministic. If our ctor runs first, the atexit handler
477        // was never registered, so std::process::exit() won't write the
478        // profraw. Serialize profraw to a buffer and write it to the SHM
479        // ring for host-side extraction.
480        try_flush_profraw();
481        std::process::exit(code);
482    }
483
484    // nextest protocol: intercept --list and --exact when running under
485    // nextest. Under cargo test, fall through to the standard harness
486    // which runs the #[test] wrappers generated by #[ktstr_test].
487    //
488    // Binaries with real #[ktstr_test] entries need the ctor to handle
489    // listing (gauntlet expansion) and dispatch (VM booting). The lib
490    // test binary has only the dummy entry and no gauntlet variants —
491    // skip interception so the standard harness discovers #[cfg(test)]
492    // module #[test] functions (unit tests).
493    //
494    // For `--list`, ktstr_main prints the gauntlet/ktstr names and
495    // RETURNS so the standard libtest harness can print its own list
496    // of `#[test]` items afterward. This makes plain `#[test]`
497    // functions inside a ktstr_test integration-test binary visible
498    // to nextest — without the fall-through, libtest never runs and
499    // those test names are silently dropped from the listing.
500    //
501    // For `--exact`, ktstr_main runs only when the test name starts
502    // with `ktstr/`, `gauntlet/`, or `host/` — names ktstr owns. Other names
503    // (libtest #[test] items, including the per-entry wrappers
504    // emitted by `#[ktstr_test]` itself) fall through to libtest's
505    // dispatch. Without this guard, run_named_test would fail
506    // `find_test` for a plain `#[test]` name and exit 1, blocking
507    // nextest from running it.
508    if std::env::var_os("NEXTEST").is_some() {
509        let has_real_tests = KTSTR_TESTS.iter().any(|e| !is_test_sentinel(e.name));
510        // A binary may carry only `declare_scheduler!` declarations
511        // (no `#[ktstr_test]` entries) — pure verifier-only test
512        // binaries. Without the scheduler check below the listing
513        // branch would never fire for such a binary and the
514        // verifier cells would silently fail to emit under nextest.
515        let has_schedulers = !super::KTSTR_SCHEDULERS.is_empty();
516        if has_real_tests || has_schedulers {
517            let args: Vec<String> = std::env::args().collect();
518            if args.iter().any(|a| a == "--list") {
519                ktstr_list_only();
520                list_verifier_cells_all();
521                list_plain_tests(args.iter().any(|a| a == "--ignored"));
522                std::process::exit(0);
523            } else if let Some(pos) = args.iter().position(|a| a == "--exact")
524                && let Some(name) = args.get(pos + 1)
525                && name.starts_with("verifier/")
526            {
527                // verifier/<sched>/<kernel>/<preset> cells bypass libtest
528                // entirely — the cell handler resolves the scheduler
529                // binary, kernel, and the cell's topology preset, runs
530                // collect_verifier_output, prints the result, and
531                // exits. No #[test] wrapper exists for declared
532                // schedulers (declare_scheduler! only emits a static),
533                // so it runs directly via run_verifier_cell — the same
534                // libtest bypass the ktstr/ branch below uses.
535                let code = run_verifier_cell(name);
536                try_flush_profraw();
537                std::process::exit(code);
538            } else if let Some(pos) = args.iter().position(|a| a == "--exact")
539                && let Some(name) = args.get(pos + 1)
540                && (name.starts_with("ktstr/")
541                    || name.starts_with("gauntlet/")
542                    || name.starts_with("host/"))
543            {
544                let bare = name
545                    .strip_prefix("ktstr/")
546                    .or_else(|| name.strip_prefix("gauntlet/"))
547                    .or_else(|| name.strip_prefix("host/"))
548                    .unwrap_or(name)
549                    .split('/')
550                    .next()
551                    .unwrap_or(name);
552
553                // Reject malformed names like `gauntlet/` (trailing
554                // slash, no test name), `ktstr/`, and `host/` up front, so the
555                // operator sees a clear error instead of an opaque
556                // "unknown test" from the empty bare name.
557                if bare.is_empty() {
558                    eprintln!(
559                        "ktstr: malformed --exact test name {name:?} \
560                         (resolves to an empty bare name after prefix strip)",
561                    );
562                    std::process::exit(1);
563                }
564
565                // Run the entry directly, bypassing libtest — the same
566                // pattern as the verifier/ branch above. The previous
567                // dispatch rewrote argv to the bare name and relied on a
568                // #[test] wrapper (emitted only by the #[ktstr_test]
569                // macro) for libtest to match it; raw
570                // `#[distributed_slice(KTSTR_TESTS)]` registrations have
571                // no wrapper, so libtest matched nothing and printed
572                // "running 0 tests" — a silent trivial-pass. run_named_test
573                // resolves the entry from KTSTR_TESTS by name and boots it
574                // for both registration styles, routing gauntlet/ to
575                // run_gauntlet_test (identical topology) and applying the
576                // host_only / performance_mode / bpf_map_write gates the
577                // wrapper path skipped.
578                let code = run_named_test(name);
579                try_flush_profraw();
580                std::process::exit(code);
581            }
582        }
583    } else {
584        // cargo-test-direct path: the standard rustc test harness
585        // runs only the bare `#[test]` wrappers `#[ktstr_test]`
586        // generates. Gauntlet expansion (topology-preset variants)
587        // lives inside `ktstr_main`'s `--list` + `--exact` handlers
588        // and is reachable ONLY under nextest. Every real ktstr
589        // entry produces topology-preset variants under nextest
590        // (`for_each_gauntlet_variant` iterates
591        // `crate::gauntlet::gauntlet_presets()`). Without nextest those
592        // variants would silently not run — coverage loss with no
593        // error. Emit a one-shot stderr `warning:` diagnostic (see
594        // the `eprintln!` below) when the binary carries any real
595        // entry so the user sees the gap instead of trusting a
596        // false green. Print once per process (cargo test invokes
597        // one test binary per crate; the ctor runs exactly once per
598        // test binary) so there is no need to gate with a
599        // std::sync::Once.
600        //
601        // `KTSTR_CARGO_TEST_MODE=1` opts out of the warning: the
602        // operator deliberately picked the cargo-test-direct path
603        // (e.g. for a single-test debug iteration without the
604        // nextest harness) and accepts that gauntlet variants
605        // won't run. The warning is still emitted under bare
606        // `cargo test` without the env var set so unaware users
607        // see the coverage gap.
608        if !crate::cargo_test_mode::cargo_test_mode_active() {
609            let total = KTSTR_TESTS.len();
610            let real = KTSTR_TESTS
611                .iter()
612                .filter(|e| !is_test_sentinel(e.name))
613                .count();
614            if real > 0 {
615                eprintln!(
616                    "warning: {real} of {total} ktstr test entries registered in this binary \
617                     will not generate their topology-preset gauntlet variants — NEXTEST env \
618                     var is not set and the standard rustc harness does not expand them. Use \
619                     `cargo nextest run` (or `cargo ktstr test`) to exercise the full gauntlet, \
620                     or set KTSTR_CARGO_TEST_MODE=1 to opt into single-variant bare-`cargo test` \
621                     mode without this warning.",
622                );
623            }
624            // Verifier cells are emitted by `list_verifier_cells_all`
625            // which runs ONLY from the NEXTEST listing branch above.
626            // A bare `cargo test` invocation on a binary carrying
627            // `declare_scheduler!` declarations gets zero verifier
628            // coverage — surface the gap with the same opt-out shape
629            // as the gauntlet warning so an unaware operator does not
630            // trust a green run that never reached the verifier.
631            // Eevdf + KernelBuiltin variants don't produce userspace
632            // binaries to verify, so they are excluded from the count
633            // (matching the emission-time filter in
634            // `list_verifier_cells_all`).
635            let verifier_schedulers = super::KTSTR_SCHEDULERS
636                .iter()
637                .filter(|s| {
638                    !matches!(
639                        s.binary,
640                        super::SchedulerSpec::Eevdf | super::SchedulerSpec::KernelBuiltin { .. }
641                    )
642                })
643                .count();
644            if verifier_schedulers > 0 {
645                eprintln!(
646                    "warning: {verifier_schedulers} `declare_scheduler!` declaration(s) in this \
647                     binary will not generate verifier cells — NEXTEST env var is not set and \
648                     verifier cells are emitted only by ktstr's `--list` handler under nextest. \
649                     Use `cargo ktstr verifier` to exercise the verifier sweep, or set \
650                     KTSTR_CARGO_TEST_MODE=1 to acknowledge the verifier-cell-free path without \
651                     this warning.",
652                );
653            }
654        }
655    }
656}
657}
658
659/// Predicate for "this entry is a unit-test sentinel, not a real
660/// `#[ktstr_test]` user entry." The lib-test binary registers a
661/// single sentinel entry (currently `"__unit_test_dummy__"`) so
662/// the dispatch + gauntlet plumbing has something to exercise
663/// under `cargo test --lib`; real user entries look like
664/// `"module::test_name"` or similar PascalCase-with-dots names.
665///
666/// Matching the sentinel by convention (`__` prefix + `__`
667/// suffix + `_test_` or `_dummy_` infix) rather than by literal
668/// equality keeps the filter robust when the sentinel is
669/// renamed, or when future scaffolding adds additional
670/// sentinel-shaped entries (e.g. `__unit_test_panics__`,
671/// `__unit_test_timeout__`). The literal-equality form would
672/// silently admit those future sentinels into the real-entry
673/// population and double-fire the "NEXTEST env var not set"
674/// warning or spuriously enable --list interception.
675fn is_test_sentinel(name: &str) -> bool {
676    // Real user-authored `#[ktstr_test]` entry names
677    // conventionally do not match the `__unit_test_*__` pattern
678    // (Rust's reserved-identifier convention for
679    // language-implementation and framework-internal names).
680    // The `#[ktstr_test]` proc macro does not validate this, so
681    // the predicate admits a real user entry in the unlikely
682    // case someone names one with the `__unit_test_*__` shape —
683    // collision would double-fire the "NEXTEST env var not set"
684    // warning / spuriously enable --list interception, but
685    // that's a diagnostic glitch, not a correctness failure.
686    name.starts_with("__unit_test_") && name.ends_with("__")
687}
688
689/// Export-self dispatch. `--ktstr-export-check-test=NAME` performs only the
690/// cheap registry ownership and static eligibility check;
691/// `--ktstr-export-test=NAME` builds the self-extracting `.run` file embedding
692/// `current_exe()` (this binary). Returns `Some(exit_code)` when either private
693/// discriminator is present and `None` otherwise.
694///
695/// `cargo ktstr export <NAME>` (the cargo-ktstr binary) is a router
696/// that compiles the workspace's tests, locates an eligible owner with the
697/// check-only arg, then exec's that selected binary once with the real export
698/// arg. The test binary embeds ITSELF — without that indirection, cargo-ktstr
699/// would package its own binary, which has no `#[ktstr_test]` registrations
700/// from the user's crate and can't reproduce the test on bare metal.
701///
702/// `--ktstr-export-output=PATH` overrides the default output path
703/// (`<NAME>.run` in the cwd). Both flags are leniently parsed by the
704/// helpers in `args.rs`; an empty NAME (`--ktstr-export-test=`)
705/// surfaces with diagnostic "requires a non-empty test name" and
706/// exit 1 so the router moves on to the next candidate.
707///
708/// # Exit-code contract
709///
710/// During the check-only phase the router discriminates between
711/// "this binary doesn't know the test" (exit 1) and "this binary
712/// has the test but rejects it" (exit 2). When ANY candidate exits
713/// 2, the router surfaces THAT candidate's stderr (the rejection
714/// reason: host_only, bpf_map_write, KernelBuiltin) rather than
715/// the generic "not found in any workspace test binary" message.
716/// Without the differentiation, an operator who exports a
717/// host_only test would see the misleading "not found" diagnostic
718/// even though the test exists.
719///
720/// Stub for the `export`-feature-disabled build. The router probes candidate
721/// test binaries with `--ktstr-export-check-test=NAME`; without this stub a
722/// binary compiled without `export` would fall through to the nextest
723/// harness, which would surface an opaque "unrecognised argument"
724/// error against an arg the operator never typed. The stub turns
725/// that into an actionable diagnostic by detecting the arg and
726/// emitting a build-config hint, then exiting 2 (matches the
727/// "registered but rejected" exit code so the router surfaces
728/// THIS binary's stderr rather than a sibling's "not registered"
729/// fallthrough). Recompile the test binary with the `export`
730/// feature (folded into `cli-bins` in the default feature set)
731/// to enable the real `cargo ktstr export` flow.
732#[cfg(not(feature = "export"))]
733fn maybe_dispatch_export() -> Option<i32> {
734    let args: Vec<String> = std::env::args().collect();
735    let _ = extract_export_check_test_arg(&args).or_else(|| extract_export_test_arg(&args))?;
736    eprintln!(
737        "ktstr export: this test binary was built without the `export` cargo \
738         feature, so `cargo ktstr export <name>` cannot reach the export pipeline \
739         from here. Rebuild with the default feature set (or pass \
740         `--features cli-bins`) and retry."
741    );
742    Some(2)
743}
744
745#[cfg(feature = "export")]
746fn maybe_dispatch_export() -> Option<i32> {
747    let args: Vec<String> = std::env::args().collect();
748    let check_name = extract_export_check_test_arg(&args);
749    let execute_name = extract_export_test_arg(&args);
750    let (name, check_only) = if let Some(name) = check_name {
751        (name, true)
752    } else {
753        (execute_name?, false)
754    };
755    let output = extract_export_output_arg(&args).map(std::path::PathBuf::from);
756
757    // Empty name: surface as a hard error rather than silently succeeding. The
758    // bounded selection protocol relies on the absent-test path returning a
759    // non-zero exit so the next candidate is tried.
760    if name.is_empty() {
761        eprintln!("ktstr export: --ktstr-export-test= requires a non-empty test name");
762        return Some(1);
763    }
764
765    // Look up the test ourselves so we can discriminate "not
766    // registered here" (exit 1, router falls through) from
767    // "registered but rejected" (exit 2, router surfaces this
768    // stderr). `export_test` itself returns anyhow::Error for both
769    // cases, which would conflate them at the exit-code level.
770    let Some(entry) = find_test(name) else {
771        eprintln!("ktstr export: no registered test named '{name}'");
772        return Some(1);
773    };
774
775    if check_only {
776        return match crate::export::validate_export_entry(entry) {
777            Ok(()) => Some(0),
778            Err(error) => {
779                eprintln!("ktstr export: {error:#}");
780                Some(2)
781            }
782        };
783    }
784
785    match crate::export::export_test(name, output) {
786        Ok(()) => Some(0),
787        Err(e) => {
788            eprintln!("ktstr export: {e:#}");
789            // The test exists in this binary but the export pipeline
790            // refused it (host_only / bpf_map_write / KernelBuiltin /
791            // I/O error). Exit 2 so the router prefers this stderr
792            // over a sibling binary's exit-1 "not registered" miss.
793            Some(2)
794        }
795    }
796}
797
798/// Shell-self dispatch: if `--ktstr-shell-test=NAME` is present in
799/// argv, look up `NAME` in the binary's own `KTSTR_TESTS` registry,
800/// serialize its shell-relevant fields to stdout as JSON, and exit.
801/// Returns `Some(exit_code)` when dispatched, `None` when absent.
802///
803/// `cargo ktstr shell --test <NAME>` (the cargo-ktstr binary) is a
804/// router that compiles the workspace's tests, exec's each test
805/// binary with this flag, and consumes the first stdout-JSON it
806/// gets (the router bails on ambiguous names — same `NAME`
807/// registered in two binaries). The router applies the
808/// descriptor's topology / memory / extra_include_files to the
809/// shell VM, then prints a one-line banner to stderr BEFORE VM
810/// boot naming the test + scheduler so the operator can repro the
811/// workload manually. (PS1-in-guest is a follow-up.)
812///
813/// # Stdout contract
814///
815/// The test binary MUST keep stdout silent on this dispatch path —
816/// `tracing` output MUST go to stderr. The router parses the entire
817/// stdout as a JSON descriptor; any prefix like an INFO log line
818/// will fail the parse.
819///
820/// # JSON shape
821///
822/// Serialized from [`crate::test_support::ShellTestDescriptor`] via
823/// `serde_json::to_string` — see that struct for the field-by-field
824/// contract. The struct lives in
825/// `crate::test_support::shell_descriptor` so producer and consumer
826/// share a single definition; adding a field there automatically
827/// propagates to both sides.
828///
829/// `scheduler_kind` discriminates `"eevdf" | "discover" | "path" |
830/// "kernel_builtin"` so the banner can hint at how to repro the
831/// scheduler (Discover/Path = userspace binary at `/bin/<n>`;
832/// KernelBuiltin = no binary, the shell-mode boot runs
833/// `scheduler_enable_cmds` before drop-to-busybox and
834/// `scheduler_disable_cmds` on shell exit; Eevdf = no setup needed).
835///
836/// # Exit-code contract
837///
838/// Matches `maybe_dispatch_export`:
839/// - `0`: test registered, JSON emitted to stdout.
840/// - `1`: test not registered in this binary (router falls
841///   through to the next candidate).
842/// - `2`: registered but rejected for shell mode (currently:
843///   `host_only` — no VM to drop into).
844fn maybe_dispatch_shell_test() -> Option<i32> {
845    let args: Vec<String> = std::env::args().collect();
846    let name = extract_shell_test_arg(&args)?;
847
848    if name.is_empty() {
849        eprintln!("ktstr shell: --ktstr-shell-test= requires a non-empty test name");
850        return Some(1);
851    }
852
853    let entry = match find_test(name) {
854        Some(e) => e,
855        None => {
856            eprintln!("ktstr shell: no registered test named '{name}'");
857            return Some(1);
858        }
859    };
860
861    if entry.host_only {
862        eprintln!(
863            "ktstr shell: test '{name}' has host_only = true; \
864             shell mode requires a guest VM to drop into. \
865             Either run the test directly with `cargo ktstr test {name}` \
866             (host_only tests don't boot a VM) or pick a non-host_only \
867             test for shell mode."
868        );
869        return Some(2);
870    }
871
872    let topo = &entry.topology;
873    let scheduler_kind = crate::test_support::SchedulerKind::from(&entry.scheduler.binary);
874    let (scheduler_enable_cmds, scheduler_disable_cmds) = match &entry.scheduler.binary {
875        crate::test_support::entry::SchedulerSpec::KernelBuiltin { enable, disable } => (
876            enable.iter().copied().map(String::from).collect(),
877            disable.iter().copied().map(String::from).collect(),
878        ),
879        _ => (Vec::new(), Vec::new()),
880    };
881
882    let descriptor = crate::test_support::ShellTestDescriptor {
883        numa_nodes: topo.numa_nodes,
884        llcs: topo.llcs,
885        cores: topo.cores_per_llc,
886        threads: topo.threads_per_core,
887        memory_mib: entry.memory_mib,
888        wprof: entry.wprof,
889        extra_include_files: entry
890            .extra_include_files
891            .iter()
892            .copied()
893            .map(String::from)
894            .collect(),
895        scheduler_name: entry.scheduler.name.to_string(),
896        scheduler_kind,
897        wprof_args: entry.wprof_args.map(String::from),
898        performance_mode: entry.performance_mode,
899        scheduler_enable_cmds,
900        scheduler_disable_cmds,
901    };
902
903    // serde_json::to_string produces RFC-8259-compliant escaping
904    // (`\uXXXX` with 4 hex digits, surrogate pairs for SMP code
905    // points) which Rust's Debug formatter does NOT — Debug uses
906    // `\u{1f4c2}` (braced form) for non-ASCII, breaking
907    // operator-supplied paths with non-ASCII chars (test built
908    // under `/home/<unicode-name>/proj`, `extra_include_files`
909    // listing emoji-named files, etc.). serde_json is already a
910    // workspace dep so adding this call doesn't widen the dep graph.
911    let payload = serde_json::to_string(&descriptor)
912        .expect("ShellTestDescriptor is a plain serde struct with no fallible field types");
913    println!("{payload}");
914    Some(0)
915}
916
917/// Host-side dispatch: if both `--ktstr-test-fn` and `--ktstr-topo` are
918/// present, boot a VM with the specified topology and run the test
919/// inside it. Returns `Some(exit_code)` if dispatched, `None` otherwise.
920fn maybe_dispatch_host_test() -> Option<i32> {
921    let args: Vec<String> = std::env::args().collect();
922    let name = extract_test_fn_arg(&args)?;
923    let topo_str = extract_topo_arg(&args)?;
924
925    let entry = match find_test(name) {
926        Some(e) => e,
927        None => {
928            eprintln!("ktstr_test: unknown test function '{name}'");
929            return Some(1);
930        }
931    };
932
933    let (numa_nodes, llcs, cores, threads) = match parse_topo_string(&topo_str) {
934        Some(t) => t,
935        None => {
936            eprintln!(
937                "ktstr_test: invalid --ktstr-topo format '{topo_str}' (expected NnNlNcNt, e.g. 1n2l4c2t)"
938            );
939            return Some(1);
940        }
941    };
942
943    let cpus = llcs * cores * threads;
944    let memory_mib = super::runtime::derive_test_memory_mib(cpus, entry);
945    let topo = TopoOverride {
946        numa_nodes,
947        llcs,
948        cores,
949        threads,
950        memory_mib,
951    };
952
953    match run_ktstr_test_with_topo(entry, &topo) {
954        Ok(_) => Some(0),
955        Err(e) => {
956            eprintln!("ktstr_test: {e:#}");
957            Some(1)
958        }
959    }
960}
961
962/// Host-side entry point: build a VM, boot it with `--ktstr-test-fn=NAME`,
963/// extract profraw from SHM, and return the test result.
964///
965/// Validates KVM access and auto-discovers a kernel image via
966/// `resolve_test_kernel()` when `KTSTR_TEST_KERNEL` is not set.
967pub fn run_ktstr_test(entry: &KtstrTestEntry) -> Result<AssertResult> {
968    // Directly-constructed entries bypass the proc-macro's
969    // compile-time checks. Call `validate` here so programmatic
970    // consumers (library callers pushing into `KTSTR_TESTS`
971    // dynamically) hit the same bail messages the macro produces at
972    // compile time.
973    entry.validate()?;
974
975    if entry.host_only {
976        return run_host_only_test_inner(entry);
977    }
978    if !entry.bpf_map_write.is_empty()
979        && let Ok(kernel) = resolve_test_kernel()
980        && crate::vmm::find_vmlinux(&kernel).is_none()
981    {
982        anyhow::bail!("vmlinux not found, bpf_map_write requires vmlinux");
983    }
984    run_ktstr_test_inner(entry, None)
985}
986
987/// Like `run_ktstr_test` but with an explicit topology override.
988/// Only consumed inside this module by `maybe_dispatch_host_test`;
989/// kept as a named helper so the `--ktstr-test-fn` + `--ktstr-topo`
990/// dispatch path reads symmetrically with the zero-override
991/// [`run_ktstr_test`] library entry point.
992fn run_ktstr_test_with_topo(entry: &KtstrTestEntry, topo: &TopoOverride) -> Result<AssertResult> {
993    run_ktstr_test_inner(entry, Some(topo))
994}
995
996/// Process exit code for a Pass verdict (and for the Skip path,
997/// which degenerates to Pass because the test never ran).
998///
999/// Defined as a `pub const` so external tooling (CI gates,
1000/// dashboard aggregators, nextest wrappers) can reference the
1001/// exit-code triad by name instead of duplicating the integer
1002/// literals. The trio [`EXIT_PASS`] / [`EXIT_FAIL`] /
1003/// [`EXIT_INCONCLUSIVE`] cover every verdict produced by the
1004/// `Fail > Inconclusive > Pass > Skip` lattice when projected
1005/// to a process exit code.
1006pub const EXIT_PASS: i32 = 0;
1007
1008/// Process exit code for a Fail verdict (or any expect_err
1009/// satisfaction failure).
1010///
1011/// See [`EXIT_PASS`] for the full triad rationale.
1012pub const EXIT_FAIL: i32 = 1;
1013
1014/// Process exit code for an Inconclusive verdict (a
1015/// zero-denominator ratio gate that could not evaluate).
1016///
1017/// Distinct from [`EXIT_PASS`] (which would silently green an
1018/// unevaluated gate) and [`EXIT_FAIL`] (which would conflate
1019/// "could not evaluate" with a real regression). External tooling
1020/// uses this code to triage Inconclusive runs separately — see
1021/// the README "Exit codes" section for the full operator contract.
1022pub const EXIT_INCONCLUSIVE: i32 = 2;
1023
1024/// Run a test result through expect_err logic and return an exit code.
1025///
1026/// Returns [`EXIT_PASS`] on pass, [`EXIT_FAIL`] on failure, and
1027/// [`EXIT_INCONCLUSIVE`] on Inconclusive — the 4-state lattice
1028/// `Fail > Inconclusive > Pass > Skip` projects to 3 distinct exit
1029/// codes (Skip degenerates to [`EXIT_PASS`] because the test never
1030/// ran). A Skip routes through the
1031/// dedicated FIRST match arm (`Ok(r) if r.is_skip()`), ahead of the
1032/// expect_err arm, so an expect_err test that produced no verdict (e.g.
1033/// a `post_vm_skip` on a load-starved placeholder dump) is not inverted
1034/// into a FAIL — a skipped test cannot "produce the expected error."
1035/// [`EXIT_INCONCLUSIVE`] lets
1036/// downstream tooling (CI gates, nextest summary aggregation, the
1037/// operator dashboard) triage zero-denominator runs distinctly from
1038/// real regressions.
1039///
1040/// `ResourceContention` does NOT map to a skip. Queue-based lock
1041/// acquisition waits for authoritative release; the type still
1042/// represents retryable host-resource syscall failures.
1043/// [`classify_host_error`] routes it to [`HostClass::Fail`] →
1044/// [`EXIT_FAIL`], a RETRYABLE failure nextest re-runs. That is the correct mechanism: a
1045/// skip is [`EXIT_PASS`], which nextest never retries, so the old
1046/// skip-on-contention silently dropped suite coverage whenever a
1047/// colocated peer's `LOCK_EX` overlapped the run. Chain-awareness (the
1048/// eval-side `"build ktstr_test VM"` / `"run ktstr_test VM"`
1049/// `.context(...)` wrappers nest the typed error) is handled inside
1050/// `classify_host_error` via the chain-walking `is_*` predicates.
1051fn result_to_exit_code(
1052    result: Result<AssertResult>,
1053    expect_err: bool,
1054    allow_inconclusive: bool,
1055) -> i32 {
1056    let no_skip = std::env::var_os(crate::KTSTR_NO_SKIP_MODE_ENV).is_some();
1057    match result {
1058        Ok(r) => ok_to_exit_code(r, expect_err, allow_inconclusive),
1059        Err(e) => err_to_exit_code(e, expect_err, no_skip),
1060    }
1061}
1062
1063/// Map an `Ok(AssertResult)` verdict to an exit code.
1064///
1065/// The sequential guards preserve the original `match` arm precedence
1066/// (first matching guard wins): `is_skip()` → `expect_err` →
1067/// `is_inconclusive()` → the trailing `EXIT_PASS` (the former
1068/// `Ok(_) => EXIT_PASS` arm). Reordering these would change which
1069/// verdict fires for a result matching more than one guard.
1070fn ok_to_exit_code(r: AssertResult, expect_err: bool, allow_inconclusive: bool) -> i32 {
1071    // A Skip degenerates to EXIT_PASS regardless of expect_err — the
1072    // test never evaluated, so there is no guest failure to "expect"
1073    // (the `Fail > Inconclusive > Pass > Skip` projection). This is the
1074    // `post_vm_skip` / host-incapacity (TopologyInsufficient,
1075    // PerfModeUnavailable) skip channel — NOT ResourceContention, which
1076    // `err_to_exit_code` routes to EXIT_FAIL (retryable). Without this
1077    // guard a post_vm_skip under expect_err
1078    // falls into the `expect_err` guard below and surfaces as "expected
1079    // error but test passed" (EXIT_FAIL) — a load-starvation
1080    // placeholder-dump skip becomes a flaky failure. End-to-end chain:
1081    // a post_vm callback returns Err(post_vm_skip(..)) → the eval gate
1082    // detects the HostSkipRequest marker, reports via report::test_skip,
1083    // and returns Ok(AssertResult::skip) → this guard maps it to
1084    // EXIT_PASS. is_skip() is true only when `outcomes` is non-empty and
1085    // every outcome is Outcome::Skip (assert/plan.rs); the empty-outcomes
1086    // Pass identity has is_skip()==false and falls through to the
1087    // trailing `EXIT_PASS`.
1088    if r.is_skip() {
1089        return EXIT_PASS;
1090    }
1091    if expect_err {
1092        // expect_err inverts on Pass and on Inconclusive: both
1093        // are "not a failure" in the operator's mental model,
1094        // and an expect_err scenario that produces an
1095        // Inconclusive verdict (denominator zero) failed to
1096        // produce the expected failure just like a Pass would.
1097        // Surface the inconclusive as exit code 2 to preserve
1098        // the distinct verdict, but treat it as expect_err
1099        // satisfaction failure (exit 1) — the test author
1100        // wanted a Fail, not "the gate could not run".
1101        //
1102        // `allow_inconclusive` does NOT relax the expect_err
1103        // contract: expect_err demands a real Fail, and an
1104        // Inconclusive verdict does not satisfy that
1105        // regardless of how the test author scopes
1106        // Inconclusive elsewhere. The dominant gate wins;
1107        // `allow_inconclusive` only relaxes the
1108        // EXIT_INCONCLUSIVE projection on the no-expect_err
1109        // path below.
1110        if r.is_inconclusive() {
1111            eprintln!(
1112                "expected error but test produced an Inconclusive verdict — \
1113                 zero-denominator gate could not evaluate; expect_err is \
1114                 unsatisfied"
1115            );
1116            return EXIT_FAIL;
1117        } else {
1118            eprintln!("expected error but test passed");
1119            return EXIT_FAIL;
1120        }
1121    }
1122    if r.is_inconclusive() {
1123        // `allow_inconclusive` opt-in: a test author may have
1124        // declared `#[ktstr_test(allow_inconclusive)]` to
1125        // signal "this test's Inconclusive arm is acceptable —
1126        // don't fail the CI gate." Route to EXIT_PASS in that
1127        // case (Inconclusive is still recorded in the sidecar
1128        // for stats tooling and the operator-facing failure
1129        // dump still renders the diagnostic). When the flag
1130        // is unset (the default) the verdict surfaces as
1131        // EXIT_INCONCLUSIVE so the operator triages it.
1132        if allow_inconclusive {
1133            eprintln!(
1134                "test produced an Inconclusive verdict but \
1135                 `allow_inconclusive` is set — routing to EXIT_PASS \
1136                 for CI gate, sidecar still records Inconclusive"
1137            );
1138            return EXIT_PASS;
1139        } else {
1140            return EXIT_INCONCLUSIVE;
1141        }
1142    }
1143    EXIT_PASS
1144}
1145
1146/// Map an `Err(anyhow::Error)` outcome to an exit code.
1147///
1148/// The sequential guards preserve the original `match` arm precedence
1149/// (first matching guard wins): the host-insufficiency classification
1150/// ([`classify_host_error`], covering kernel-unavailable → perf-mode →
1151/// cpu-budget → topology-unrepresentable → resource-contention →
1152/// topology-insufficient, shared with the `#[ktstr_test]` macro body) runs
1153/// FIRST, then the
1154/// marker-typed guards (`PostVmAssertionFailure` → `SchedulerBuildRefused`
1155/// → `SurvivesStormViolated` → `ExpectAutoReproSatisfied`), then the
1156/// `expect_err` inversion, then
1157/// the catch-all (the former `Err(e) => …` arm) operating on the
1158/// now-owned `e`. Reordering these would change which guard fires for an
1159/// error matching more than one guard. The host-insufficiency guard
1160/// order + per-class skip/fail policy live in `classify_host_error`, not
1161/// here, so this site and the macro cannot drift apart.
1162fn err_to_exit_code(e: anyhow::Error, expect_err: bool, no_skip: bool) -> i32 {
1163    if crate::test_support::is_framework_infrastructure_failure(&e) {
1164        // Framework faults are never resource insufficiency and never an
1165        // expected guest failure. Check the marker before host classification
1166        // so a nested errno or contextual message cannot turn it into a skip.
1167        eprintln!("{e:#}");
1168        return EXIT_FAIL;
1169    }
1170    // Host-insufficiency classification (kernel-unavailable, perf-mode,
1171    // cpu-budget, topology-unrepresentable, resource-contention,
1172    // topology-insufficient) is shared with the `#[ktstr_test]` macro body via
1173    // `classify_host_error` — the single source of truth for the guard
1174    // ORDER and the per-class skip/fail policy. This site renders the
1175    // verdict as an exit code; the macro renders the same `HostClass` as
1176    // libtest control flow. The bare `reason` carries no prefix: the skip
1177    // channel (`report::test_skip`) prepends `ktstr: SKIP:`, the fail
1178    // channel prepends `ktstr: FAIL:`. Placed first so a host-insufficiency
1179    // returns before the marker / expect_err / catch-all arms below — a
1180    // skip is a skip and an unconditional hard fail is a hard fail
1181    // regardless of `expect_err`.
1182    match classify_host_error(&e, no_skip) {
1183        HostClass::Skip { reason } => {
1184            crate::report::test_skip(format_args!("{reason}"));
1185            return EXIT_PASS;
1186        }
1187        HostClass::Fail { reason } => {
1188            eprintln!("ktstr: FAIL: {reason}");
1189            return EXIT_FAIL;
1190        }
1191        HostClass::NotHostClass => {}
1192    }
1193    if e.downcast_ref::<crate::test_support::eval::PostVmAssertionFailure>()
1194        .is_some()
1195    {
1196        // A host-side post_vm / post_vm_unconditional callback
1197        // failed. This is a real regression that must surface
1198        // regardless of expect_err / expect_auto_repro inversion —
1199        // those invert a GUEST-side expected failure, but a
1200        // HOST-side check is always honored. Positioned AFTER the
1201        // resource-contention / topology skip guards (a skip means
1202        // the test never ran, so there was no host-side state to
1203        // assert) but BEFORE the ExpectAutoReproSatisfied and
1204        // expect_err inversion guards so the host-side regression
1205        // wins. `downcast_ref` walks the anyhow context+source
1206        // chain (the marker rides as `.context(...)` from
1207        // run_ktstr_test_inner_impl); a raw `chain().any(is::<C>())`
1208        // would miss it (anyhow boxes context as ContextError<C,E>).
1209        eprintln!("{e:#}");
1210        return EXIT_FAIL;
1211    }
1212    if e.downcast_ref::<crate::test_support::eval::SchedulerBuildRefused>()
1213        .is_some()
1214    {
1215        // A Discover scheduler build FAILED; the resolver never falls back to
1216        // a possibly-stale pre-built binary — a scheduler that cannot be built
1217        // is a failed test. A host-side build-infra fault: always EXIT_FAIL,
1218        // never inverted by expect_err (mirrors PostVmAssertionFailure above):
1219        // an expect_err test must not let a broken build masquerade as the
1220        // guest-side expected failure.
1221        eprintln!("{e:#}");
1222        return EXIT_FAIL;
1223    }
1224    if e.downcast_ref::<crate::test_support::eval::SurvivesStormViolated>()
1225        .is_some()
1226    {
1227        // The marker rides ONLY when `entry.survives_storm` was set AND the
1228        // failure cause was a scheduler death (see
1229        // `render_failure_verdict_message`), so its presence alone proves the
1230        // survival assertion was violated — no `survives_storm` param needed
1231        // (mirrors the marker-presence arms for PostVmAssertionFailure /
1232        // SchedulerBuildRefused / ExpectAutoReproSatisfied below). Force
1233        // EXIT_FAIL with a survival-specific explainer. Positioned AFTER the
1234        // host-insufficiency / PostVmAssertionFailure / SchedulerBuildRefused
1235        // guards (a skip or host-side fault still dominates) but BEFORE the
1236        // ExpectAutoReproSatisfied and expect_err inversion arms so a survival
1237        // violation can never be inverted to PASS (defense-in-depth: the
1238        // validate-time survives_storm/expect_err mutex already forbids that
1239        // pairing). `downcast_ref` walks the anyhow context chain (the marker
1240        // rides as `.context(...)`).
1241        eprintln!(
1242            "ktstr: FAIL: survives_storm asserted but the scheduler did not \
1243             survive the run:\n{e:#}"
1244        );
1245        return EXIT_FAIL;
1246    }
1247    if e.downcast_ref::<crate::test_support::eval::ExpectAutoReproSatisfied>()
1248        .is_some()
1249    {
1250        // `expect_auto_repro = true` was satisfied: the primary
1251        // VM produced a Fail AND the auto-repro VM landed a
1252        // shape-valid `.repro.wprof.pb`. The eval layer attached
1253        // the marker as `anyhow::Context`. `downcast_ref` walks
1254        // the anyhow context+source chain (per anyhow's
1255        // documentation: "For errors with context, this method
1256        // returns true if E matches the type of the context C or
1257        // the type of the error on which the context has been
1258        // attached"). A `chain().any(|c| c.is::<E>())` walk on
1259        // the raw `&dyn StdError` chain would MISS the marker
1260        // because anyhow boxes context as `ContextError<C, E>`
1261        // whose underlying `is::<C>()` check returns false. The
1262        // diagnostic is printed so the operator sees both the
1263        // original failure trail and the inversion notice — the
1264        // verdict flips to PASS without erasing the failure
1265        // detail. Positioned AFTER the ResourceContention /
1266        // TopologyInsufficient guards so a skip-class outcome still
1267        // wins over inversion (a skip is a skip regardless of the
1268        // satisfaction signal). The macro-parse cross-attribute
1269        // check rejects `expect_auto_repro` combined with
1270        // `expect_err`, so the two inversion paths are mutually
1271        // exclusive at the entry layer.
1272        eprintln!("{e:#}");
1273        return EXIT_PASS;
1274    }
1275    if expect_err {
1276        // expect_err inverts a failure into a pass — UNLESS the
1277        // failure carries the
1278        // [`crate::test_support::eval::ScxBpfErrorMatcherMismatch`]
1279        // marker, which signals that the reproducer's scx_bpf_error
1280        // matcher rejected this particular failure. A matcher-
1281        // mismatch failure must surface even when expect_err = true:
1282        // the user authored the matcher to pin THIS specific bug,
1283        // and a different bug firing is itself a regression.
1284        //
1285        // `downcast_ref` walks the anyhow context+source chain
1286        // (anyhow's documented "For errors with context, this
1287        // method returns true if E matches the type of the context
1288        // C or the type of the error on which the context has been
1289        // attached" semantics). A `chain().any(|c| c.is::<E>())`
1290        // walk on the raw `&dyn StdError` chain would MISS the
1291        // marker because anyhow boxes context as
1292        // `ContextError<C, E>` whose underlying `is::<C>()` check
1293        // returns false.
1294        if e.downcast_ref::<crate::test_support::eval::ScxBpfErrorMatcherMismatch>()
1295            .is_some()
1296        {
1297            eprintln!("{e:#}");
1298            return EXIT_FAIL;
1299        } else {
1300            return EXIT_PASS;
1301        }
1302    }
1303    // Catch-all: a non-host-class, non-marker, non-expect_err error is a
1304    // real failure. (A KernelUnavailable does NOT reach here — it is a
1305    // skip-class host-insufficiency handled by the classify_host_error match
1306    // at the top.)
1307    eprintln!("{e:#}");
1308    EXIT_FAIL
1309}
1310
1311/// The final test verdict — the 4-state lattice `Fail > Inconclusive >
1312/// Pass > Skip` that [`result_to_exit_code`] projects to a process exit
1313/// code. Distinct from the exit code because the exit code collapses
1314/// `Skip` into [`EXIT_PASS`]; the sidecar finalize ([`final_outcome`])
1315/// needs all four to set the persisted `passed`/`skipped`/`inconclusive`
1316/// bits to the POST-inversion outcome.
1317#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1318pub(crate) enum Verdict {
1319    Pass,
1320    Fail,
1321    Skip,
1322    Inconclusive,
1323}
1324
1325impl Verdict {
1326    /// Project to the process exit code, matching the
1327    /// `EXIT_PASS`/`EXIT_FAIL`/`EXIT_INCONCLUSIVE` mapping
1328    /// [`result_to_exit_code`] produces (Skip degenerates to
1329    /// [`EXIT_PASS`]). Test-only: the anti-drift truth-table test
1330    /// (`final_outcome_projects_to_result_to_exit_code`) is its sole
1331    /// caller — production reads the [`Verdict`] directly via
1332    /// [`Verdict::sidecar_bits`].
1333    #[cfg(test)]
1334    pub(crate) fn to_exit_code(self) -> i32 {
1335        match self {
1336            Verdict::Pass | Verdict::Skip => EXIT_PASS,
1337            Verdict::Fail => EXIT_FAIL,
1338            Verdict::Inconclusive => EXIT_INCONCLUSIVE,
1339        }
1340    }
1341
1342    /// The persisted-sidecar verdict bits `(passed, skipped,
1343    /// inconclusive)` for this outcome. `Fail` is all-false (the
1344    /// [`crate::test_support::SidecarResult::is_fail`] "none set"
1345    /// encoding). Lets the sidecar finalize record the final verdict
1346    /// without [`crate::test_support::sidecar`] depending on this enum.
1347    pub(crate) fn sidecar_bits(self) -> (bool, bool, bool) {
1348        match self {
1349            Verdict::Pass => (true, false, false),
1350            Verdict::Skip => (false, true, false),
1351            Verdict::Inconclusive => (false, false, true),
1352            Verdict::Fail => (false, false, false),
1353        }
1354    }
1355}
1356
1357/// Classify a test result into the final [`Verdict`] — the same
1358/// classification [`result_to_exit_code`] performs, as a 4-state value
1359/// (it does not collapse `Skip` into `Pass` the way the exit code does)
1360/// and WITHOUT the operator-facing `eprintln` diagnostics.
1361///
1362/// Used to record the FINAL (post-`expect_err` / post-marker) outcome on
1363/// the sidecar so the footer, `stats` analysis, and `replay` reflect the
1364/// test's real pass/fail (matching nextest's exit code) rather than the
1365/// raw scenario verdict written mid-run.
1366///
1367/// MUST stay in lockstep with [`result_to_exit_code`]: the truth-table
1368/// test `final_outcome_projects_to_result_to_exit_code` asserts
1369/// `final_outcome(...).to_exit_code() == result_to_exit_code(...)` over a
1370/// matrix including the marker-carrying error arms, so the two cannot
1371/// drift. The arm order mirrors [`ok_to_exit_code`] / [`err_to_exit_code`]
1372/// first-match precedence exactly.
1373pub(crate) fn final_outcome(
1374    result: &Result<AssertResult>,
1375    expect_err: bool,
1376    allow_inconclusive: bool,
1377) -> Verdict {
1378    let no_skip = std::env::var_os(crate::KTSTR_NO_SKIP_MODE_ENV).is_some();
1379    match result {
1380        Ok(r) => {
1381            if r.is_skip() {
1382                return Verdict::Skip;
1383            }
1384            if expect_err {
1385                // expect_err on an Ok result is always a failure
1386                // (expected an error, got a non-error verdict) — both the
1387                // Pass and Inconclusive arms of ok_to_exit_code map here.
1388                return Verdict::Fail;
1389            }
1390            if r.is_inconclusive() {
1391                return if allow_inconclusive {
1392                    Verdict::Pass
1393                } else {
1394                    Verdict::Inconclusive
1395                };
1396            }
1397            Verdict::Pass
1398        }
1399        Err(e) => {
1400            if crate::test_support::is_framework_infrastructure_failure(e) {
1401                return Verdict::Fail;
1402            }
1403            match classify_host_error(e, no_skip) {
1404                HostClass::Skip { .. } => return Verdict::Skip,
1405                HostClass::Fail { .. } => return Verdict::Fail,
1406                HostClass::NotHostClass => {}
1407            }
1408            if e.downcast_ref::<crate::test_support::eval::PostVmAssertionFailure>()
1409                .is_some()
1410            {
1411                return Verdict::Fail;
1412            }
1413            if e.downcast_ref::<crate::test_support::eval::SchedulerBuildRefused>()
1414                .is_some()
1415            {
1416                return Verdict::Fail;
1417            }
1418            if e.downcast_ref::<crate::test_support::eval::SurvivesStormViolated>()
1419                .is_some()
1420            {
1421                // Lockstep with err_to_exit_code's SurvivesStormViolated arm
1422                // (same position: after SchedulerBuildRefused, before
1423                // ExpectAutoReproSatisfied / expect_err) so the persisted
1424                // sidecar verdict matches the exit code for a survival
1425                // violation — including the defense-in-depth bypass case
1426                // (marker + expect_err) the mutex normally forbids.
1427                return Verdict::Fail;
1428            }
1429            if e.downcast_ref::<crate::test_support::eval::ExpectAutoReproSatisfied>()
1430                .is_some()
1431            {
1432                return Verdict::Pass;
1433            }
1434            if expect_err {
1435                if e.downcast_ref::<crate::test_support::eval::ScxBpfErrorMatcherMismatch>()
1436                    .is_some()
1437                {
1438                    return Verdict::Fail;
1439                }
1440                return Verdict::Pass;
1441            }
1442            Verdict::Fail
1443        }
1444    }
1445}
1446
1447/// Whether a base test entry is "ignored" (skipped by default).
1448///
1449/// Entries declared with `#[ktstr_test(ignore)]` carry `ignored = true` from
1450/// macro codegen. Tests whose names start with `demo_` are also ignored --
1451/// they are demonstration/benchmarking tests that require manual opt-in.
1452fn is_ignored(entry: &KtstrTestEntry) -> bool {
1453    entry.ignored || entry.name.starts_with("demo_")
1454}
1455
1456/// Walk [`KTSTR_TESTS`] once per process and emit a stderr
1457/// `warning:` line for every duplicate `name` found.
1458///
1459/// Two entries with the same name would both match `find_test(name)`
1460/// (which returns the FIRST match), so the second registration is
1461/// silently shadowed — `cargo ktstr` would dispatch the first entry
1462/// and the second entry's body would never run, with no diagnostic
1463/// surfaced. The warning surfaces the collision so an operator can
1464/// rename one of the `#[ktstr_test]` functions; discovery itself
1465/// proceeds (find_test's first-wins behavior continues) so nextest's
1466/// `--list` output still lands in stdout. A panic here would abort
1467/// the whole listing — nextest would see no tests at all rather
1468/// than a partial set with a clear warning. The first-wins
1469/// shadowing remains a real bug, but the diagnostic is louder than
1470/// silence and the tradeoff (operator sees the warning AND a
1471/// usable test list) beats the alternative (operator sees a
1472/// panic backtrace and no test list).
1473///
1474/// `OnceLock<()>` gates the walk to fire EXACTLY ONCE per process:
1475/// every gauntlet variant resolves through `list_tests` (under
1476/// nextest's discovery and budget paths), so without the gate a
1477/// run with N variants would re-walk the slice N times and emit
1478/// the same warning N times. Each duplicate name surfaces exactly
1479/// once via the inner `seen`/`warned` HashSet pair so a
1480/// triple-collision (three entries sharing one name) does not
1481/// double-print the warning.
1482///
1483/// The pure detection logic lives in
1484/// [`warn_duplicate_test_names_inner`] so the duplicate-walker
1485/// is testable without process-wide global state. This wrapper
1486/// only owns the `OnceLock<()>` gate and the
1487/// `(KTSTR_TESTS, stderr)` plumbing.
1488fn warn_duplicate_test_names_once() {
1489    static CHECKED: std::sync::OnceLock<()> = std::sync::OnceLock::new();
1490    CHECKED.get_or_init(|| {
1491        warn_duplicate_test_names_inner(KTSTR_TESTS.iter().map(|e| e.name), &mut std::io::stderr());
1492    });
1493}
1494
1495/// Pure walker behind [`warn_duplicate_test_names_once`]: walks
1496/// the test-name iterator and emits one `warning:` line per
1497/// duplicate name to `sink`. Each duplicate name surfaces
1498/// exactly once (a triple-collision does NOT double-print)
1499/// via the inner `warned` HashSet.
1500///
1501/// Extracted from the OnceLock-gated wrapper so the duplicate
1502/// detection logic is testable without process-wide global
1503/// state — the wrapper handles "fire once per process" via its
1504/// own `OnceLock<()>` gate; this inner is a pure function over
1505/// `(names, sink)`. The wrapper passes
1506/// `KTSTR_TESTS.iter().map(|e| e.name)` as the iterator and
1507/// `std::io::stderr()` as the sink.
1508///
1509/// `Result<(), std::io::Error>` is collapsed to ignore-on-write
1510/// because the production wrapper writes to stderr where IO
1511/// errors are unrecoverable; tests pass a `Vec<u8>` sink which
1512/// never errors. The function name says "warn" — diagnostic
1513/// channel — and matches the wrapper's pre-existing
1514/// `eprintln!` semantics.
1515fn warn_duplicate_test_names_inner<'a, W: std::io::Write>(
1516    names: impl IntoIterator<Item = &'a str>,
1517    sink: &mut W,
1518) {
1519    use std::collections::HashSet;
1520    let names: Vec<&'a str> = names.into_iter().collect();
1521    let mut seen: HashSet<&'a str> = HashSet::with_capacity(names.len());
1522    let mut warned: HashSet<&'a str> = HashSet::new();
1523    for name in names {
1524        if !seen.insert(name) && warned.insert(name) {
1525            let _ = writeln!(
1526                sink,
1527                "warning: ktstr_test: duplicate test name {name:?} registered in KTSTR_TESTS — \
1528                 two `#[ktstr_test]` entries share this name; the SECOND entry is \
1529                 silently shadowed (find_test returns the first registration). \
1530                 rename one of the functions to disambiguate.",
1531            );
1532        }
1533    }
1534}
1535
1536/// Collect test names for nextest discovery (--list --format terse).
1537///
1538/// Nextest calls the binary twice:
1539/// - Without `--ignored`: prints ALL tests (ignored and non-ignored).
1540/// - With `--ignored`: prints ONLY ignored tests.
1541///
1542/// Gauntlet variants are always ignored. Base tests are ignored when their
1543/// registered entry carries `ignored = true` or their name starts with
1544/// `demo_`.
1545///
1546/// When `KTSTR_BUDGET_SECS` is set, applies greedy coverage maximization
1547/// to select the subset of tests that maximizes feature coverage within
1548/// the time budget. Only selected tests are printed.
1549///
1550/// Calls [`warn_duplicate_test_names_once`] on the first invocation per
1551/// process so duplicate registrations surface a stderr `warning:`
1552/// line BEFORE any test name is printed (discovery itself proceeds
1553/// — find_test's first-wins behavior continues, but the operator
1554/// sees which name collided). Subsequent invocations are no-ops via
1555/// the inner `OnceLock` gate.
1556fn list_tests(ignored_only: bool) {
1557    warn_duplicate_test_names_once();
1558    let raw = std::env::var(crate::KTSTR_BUDGET_SECS_ENV).ok();
1559    let budget_secs: Option<f64> = raw.as_deref().and_then(|s| match s.parse::<f64>() {
1560        Ok(v) if v > 0.0 => Some(v),
1561        Ok(v) => {
1562            eprintln!("ktstr_test: KTSTR_BUDGET_SECS={v}: must be positive, ignoring");
1563            None
1564        }
1565        Err(e) => {
1566            eprintln!("ktstr_test: KTSTR_BUDGET_SECS={s:?}: {e}, ignoring");
1567            None
1568        }
1569    });
1570
1571    if let Some(budget) = budget_secs {
1572        list_tests_budget(ignored_only, budget);
1573    } else {
1574        list_tests_all(ignored_only);
1575    }
1576}
1577
1578/// Iterate topology presets that both fit the host capacity and
1579/// match the entry's `TopologyConstraints`. Shared between the
1580/// eager ("print every name") and budgeted ("push a candidate")
1581/// listers in `list_tests_*`.
1582fn for_each_gauntlet_variant<F>(
1583    entry: &KtstrTestEntry,
1584    presets: &[crate::gauntlet::TopoPreset],
1585    host_cpus: u32,
1586    host_llcs: u32,
1587    host_max_cpus_per_llc: u32,
1588    mut visit: F,
1589) where
1590    F: FnMut(&crate::gauntlet::TopoPreset),
1591{
1592    let no_perf_mode = super::runtime::no_perf_mode_for_entry(entry);
1593    for preset in presets {
1594        // Non-uniform presets (per-LLC core counts, e.g. 192cpu-11llc-smt)
1595        // are VERIFIER-ONLY: the gauntlet execution path reconstructs the
1596        // topology from a `TopoOverride` (numa/llcs/cores/threads only),
1597        // which cannot carry `llc_cores`, so a gauntlet variant would boot
1598        // a WRONG uniform shape. The verifier path passes the full
1599        // Topology (with llc_cores) directly, so it is the only path that
1600        // renders these shapes faithfully. Skip them here regardless of
1601        // constraints — this is why 192cpu-11llc-smt's forced overcommit is
1602        // realized only in the verifier battery.
1603        if preset.topology.llc_cores.is_some() {
1604            continue;
1605        }
1606        // No-perf-mode tests run KVM-emulated topology — guest sees the
1607        // declared NUMA / LLC / per-LLC layout regardless of host
1608        // hardware — so the host-side LLC count and per-LLC CPU width
1609        // do not constrain preset eligibility. Only the total-CPU
1610        // budget survives.
1611        let accepted = if no_perf_mode {
1612            entry
1613                .constraints
1614                .accepts_no_perf_mode(&preset.topology, host_cpus)
1615        } else {
1616            entry.constraints.accepts(
1617                &preset.topology,
1618                host_cpus,
1619                host_llcs,
1620                host_max_cpus_per_llc,
1621            )
1622        };
1623        if !accepted {
1624            continue;
1625        }
1626        visit(preset);
1627    }
1628}
1629
1630/// List all tests without budget filtering.
1631///
1632/// When `KTSTR_KERNEL_LIST` carries 2 or more entries, every test
1633/// name carries an extra `/{sanitized_kernel_label}` suffix so each
1634/// (test × kernel) pair becomes a distinct nextest test case;
1635/// nextest's parallelism, retries, and `-E` filtering all apply
1636/// natively. Single-kernel mode (0 or 1 entries) emits the
1637/// `gauntlet/{name}/{preset}` shape with no kernel suffix.
1638///
1639/// `KTSTR_CARGO_TEST_MODE=1` skips gauntlet variant emission and
1640/// the multi-kernel suffix path: each test gets exactly one
1641/// `ktstr/{name}: test` line for VM tests or `host/{name}: test` for
1642/// host-only tests. Bare `cargo test` doesn't have
1643/// access to the cargo-ktstr resolver that produces
1644/// `KTSTR_KERNEL_LIST`, so the multi-kernel branch can't apply
1645/// even if it were enabled — pin both behaviors explicitly so
1646/// the listing matches what the dispatch path will actually run.
1647fn list_tests_all(ignored_only: bool) {
1648    let cargo_test_mode = crate::cargo_test_mode::cargo_test_mode_active();
1649    let presets = crate::gauntlet::gauntlet_presets();
1650    let has_vmlinux = resolve_test_kernel()
1651        .ok()
1652        .and_then(|k| crate::vmm::find_vmlinux(&k))
1653        .is_some();
1654    let (host_cpus, host_llcs, host_max_cpus_per_llc) = super::host_capacity();
1655
1656    let kernel_list = read_kernel_list();
1657    let multi_kernel = kernel_list.len() > 1 && !cargo_test_mode;
1658    // Single-kernel mode (no list, or list has exactly one entry)
1659    // emits one variant per (test × preset) tuple with no kernel
1660    // suffix. Multi-kernel mode iterates every kernel as an outer
1661    // loop and appends `/{sanitized}` per variant. The empty-suffix
1662    // sentinel below is what the single-kernel branch passes to keep
1663    // the print path uniform.
1664    let kernel_suffixes: Vec<&str> = if multi_kernel {
1665        kernel_list.iter().map(|k| k.sanitized.as_str()).collect()
1666    } else {
1667        vec![""]
1668    };
1669
1670    for entry in KTSTR_TESTS.iter() {
1671        // Unit-test sentinel fixtures (`__unit_test_*__`) exist only to be
1672        // dispatched directly by lib unit tests (run_named_test / ELF stamp
1673        // readers). Listing them would boot real VM cells for stub bodies —
1674        // the perf-mode fixtures then face the perf isolation gate on hosts
1675        // where nothing meaningful is being measured.
1676        if is_test_sentinel(entry.name) {
1677            continue;
1678        }
1679        // bpf_map_write tests require vmlinux to resolve BPF map
1680        // addresses. Don't list them when vmlinux is unavailable —
1681        // they cannot run and would produce false PASS results.
1682        if !entry.bpf_map_write.is_empty() && !has_vmlinux {
1683            continue;
1684        }
1685
1686        if !ignored_only || is_ignored(entry) {
1687            if entry.host_only {
1688                println!("host/{}: test", entry.name);
1689            } else {
1690                for suffix in &kernel_suffixes {
1691                    if suffix.is_empty() {
1692                        println!("ktstr/{}: test", entry.name);
1693                    } else {
1694                        println!("ktstr/{}/{suffix}: test", entry.name);
1695                    }
1696                }
1697            }
1698        }
1699
1700        // Host-only tests run on the host without a VM -- gauntlet
1701        // topology variants are meaningless.
1702        if entry.host_only {
1703            continue;
1704        }
1705
1706        // KTSTR_CARGO_TEST_MODE: skip gauntlet expansion. The
1707        // operator picked the bare-`cargo test` path; emit only
1708        // the base name so each `#[ktstr_test]` runs once with its
1709        // declared topology.
1710        if cargo_test_mode {
1711            continue;
1712        }
1713
1714        // Gauntlet variants are always ignored — users opt in with
1715        // --run-ignored. Presets that exceed the host's CPU count or
1716        // LLC count are filtered from the listing entirely.
1717        for_each_gauntlet_variant(
1718            entry,
1719            &presets,
1720            host_cpus,
1721            host_llcs,
1722            host_max_cpus_per_llc,
1723            |preset| {
1724                for suffix in &kernel_suffixes {
1725                    if suffix.is_empty() {
1726                        println!("gauntlet/{}/{}: test", entry.name, preset.name);
1727                    } else {
1728                        println!("gauntlet/{}/{}/{suffix}: test", entry.name, preset.name,);
1729                    }
1730                }
1731            },
1732        );
1733    }
1734}
1735
1736/// True iff the given operator-resolved kernel `entry` matches one
1737/// of the `declared` kernel specs from a scheduler's
1738/// `declare_scheduler!` `kernels = [...]` declaration. Empty
1739/// `declared` accepts every entry (no per-scheduler filter).
1740///
1741/// Match semantics per spec variant (via [`crate::kernel_path::KernelId::parse`]):
1742/// - [`crate::kernel_path::KernelId::Version`]: raw-label string equality OR sanitized-label match
1743///   ([`sanitize_kernel_label`] of the spec string equals the entry's
1744///   sanitized label). Direct match catches the common case where
1745///   the dispatcher resolved `--kernel 6.14.2` and the scheduler
1746///   declared `kernels = ["6.14.2"]`.
1747/// - [`crate::kernel_path::KernelId::Range`]: range-membership check on the entry's raw
1748///   label via [`crate::kernel_path::decompose_version_for_compare`].
1749///   Lets schedulers declaring `kernels = ["6.14..6.16"]` match
1750///   any operator-supplied kernel whose version falls in
1751///   `[6.14, 6.16]` inclusive.
1752/// - [`crate::kernel_path::KernelId::Path`] / [`crate::kernel_path::KernelId::CacheKey`] / [`crate::kernel_path::KernelId::Git`]:
1753///   sanitized-label equality — the producer-side encoder
1754///   (`src/bin/cargo_ktstr/kernel/wire_format.rs`) emits a deterministic
1755///   label per variant (`path_…`, `git_owner_repo_kind_ref`, version
1756///   prefix from cache key), so identical specs on both sides
1757///   produce identical sanitized labels.
1758///
1759/// [`KernelId`]: crate::kernel_path::KernelId
1760#[cfg(test)]
1761fn sched_kernel_filter_accepts(declared: &[&'static str], entry: &KernelEntry) -> bool {
1762    super::entry::verifier_kernel_specs_accept(
1763        declared.iter().copied(),
1764        &entry.label,
1765        entry.sanitized.as_str(),
1766    )
1767}
1768
1769/// Single-spec match helper for [`sched_kernel_filter_accepts`].
1770/// Parses `spec` via [`crate::kernel_path::KernelId::parse`] and
1771/// dispatches on the variant. Pure logic — no network, no FS.
1772#[cfg(test)]
1773fn entry_matches_spec(entry: &KernelEntry, spec: &str) -> bool {
1774    super::entry::verifier_kernel_specs_accept(
1775        std::iter::once(spec),
1776        &entry.label,
1777        entry.sanitized.as_str(),
1778    )
1779}
1780
1781/// Format the `KTSTR_KERNEL_LIST is empty` diagnostic emitted by
1782/// [`run_verifier_cell`] when a verifier cell name reaches the cell
1783/// handler with no kernel-list to look the label up in. Extracted
1784/// from the inline eprintln! so the exact wording can be pinned in
1785/// unit tests without spawning a process.
1786fn format_empty_kernel_list_error(full_name: &str) -> String {
1787    format!(
1788        "ktstr verifier: cell {full_name}: KTSTR_KERNEL_LIST is empty. \
1789         Direct `--exact verifier/...` invocation outside `cargo ktstr verifier` \
1790         is not supported — the dispatcher owns kernel-set resolution. Run \
1791         `cargo ktstr verifier [--kernel SPEC]` instead.",
1792    )
1793}
1794
1795/// Format the "kernel label not in KTSTR_KERNEL_LIST" diagnostic.
1796/// `present` is the slice of sanitized labels actually present in
1797/// the list, in their KTSTR_KERNEL_LIST ordering. Extracted for the
1798/// same reason as [`format_empty_kernel_list_error`].
1799fn format_unknown_kernel_label_error(
1800    full_name: &str,
1801    kernel_label: &str,
1802    sched_name: &str,
1803    present: &[&str],
1804) -> String {
1805    format!(
1806        "ktstr verifier: cell {full_name}: kernel label {kernel_label:?} \
1807         not in KTSTR_KERNEL_LIST. Present labels: [{}]. \
1808         Either add --kernel <SPEC> to the dispatcher invocation so it \
1809         resolves into this label, or remove the matching entry from \
1810         declare_scheduler!(... kernels = [...]) for {sched_name}.",
1811        present.join(", "),
1812    )
1813}
1814
1815/// The set of PACKAGE names in the workspace rooted at `manifest_dir`,
1816/// queried once per dir via `cargo metadata`. [`list_verifier_cells_all`]
1817/// uses it to skip `declare_scheduler!` decls whose `Discover(pkg)` is
1818/// not a real member of the DECLARING crate's workspace — the
1819/// macro-expansion FIXTURES in tests/declare_scheduler.rs register into
1820/// `KTSTR_SCHEDULERS` but name packages that are not members of ktstr's
1821/// own workspace, so their cells must not be emitted.
1822///
1823/// `cargo metadata --no-deps` is the authoritative answer to "which
1824/// packages live in this workspace": it resolves glob members like
1825/// `"scheds/rust/*"` (which scx uses) and package-name≠dir-name renames
1826/// that a hand-parse of `[workspace] members` would miss.
1827///
1828/// Memoized per `manifest_dir` (the value is `Box::leak`ed to `'static`).
1829/// On `cargo metadata` failure the returned set is EMPTY (every
1830/// `Discover` cell in that workspace is then skipped) and a one-time
1831/// warning is emitted to stderr, matching the diagnostic style of the
1832/// surrounding lister code.
1833fn workspace_member_packages(manifest_dir: &str) -> &'static std::collections::HashSet<String> {
1834    use std::collections::HashMap;
1835    use std::sync::Mutex;
1836    use std::sync::OnceLock;
1837    static CACHE: OnceLock<Mutex<HashMap<String, &'static std::collections::HashSet<String>>>> =
1838        OnceLock::new();
1839    let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));
1840    let mut guard = cache.lock().unwrap_or_else(|e| e.into_inner());
1841    if let Some(set) = guard.get(manifest_dir) {
1842        return set;
1843    }
1844    let set: &'static std::collections::HashSet<String> =
1845        Box::leak(Box::new(query_workspace_member_packages(manifest_dir)));
1846    guard.insert(manifest_dir.to_string(), set);
1847    set
1848}
1849
1850/// Run `cargo metadata --no-deps` against `<manifest_dir>/Cargo.toml` and
1851/// collect the `packages[].name` set. Returns an EMPTY set (with a
1852/// one-time stderr warning) when cargo cannot be spawned, exits non-zero,
1853/// or emits JSON the walker cannot parse — every `Discover` cell rooted
1854/// in that workspace is then gated out rather than emitted for a package
1855/// the runtime resolver could not build.
1856fn query_workspace_member_packages(manifest_dir: &str) -> std::collections::HashSet<String> {
1857    let manifest_path = crate::writable_source_path(manifest_dir).join("Cargo.toml");
1858    let output = std::process::Command::new("cargo")
1859        .args(["metadata", "--no-deps", "--format-version", "1"])
1860        .arg("--manifest-path")
1861        .arg(&manifest_path)
1862        .stdout(std::process::Stdio::piped())
1863        .stderr(std::process::Stdio::piped())
1864        .output();
1865    let output = match output {
1866        Ok(o) if o.status.success() => o,
1867        Ok(o) => {
1868            eprintln!(
1869                "ktstr verifier: `cargo metadata` for {} failed ({}); \
1870                 skipping this workspace's Discover schedulers:\n{}",
1871                manifest_path.display(),
1872                o.status,
1873                String::from_utf8_lossy(&o.stderr).trim(),
1874            );
1875            return std::collections::HashSet::new();
1876        }
1877        Err(e) => {
1878            eprintln!(
1879                "ktstr verifier: could not run `cargo metadata` for {} ({e}); \
1880                 skipping this workspace's Discover schedulers",
1881                manifest_path.display(),
1882            );
1883            return std::collections::HashSet::new();
1884        }
1885    };
1886    let Ok(meta) = serde_json::from_slice::<serde_json::Value>(&output.stdout) else {
1887        eprintln!(
1888            "ktstr verifier: `cargo metadata` for {} produced unparsable JSON; \
1889             skipping this workspace's Discover schedulers",
1890            manifest_path.display(),
1891        );
1892        return std::collections::HashSet::new();
1893    };
1894    meta.get("packages")
1895        .and_then(|p| p.as_array())
1896        .into_iter()
1897        .flatten()
1898        .filter_map(|pkg| pkg.get("name").and_then(|n| n.as_str()))
1899        .map(|s| s.to_string())
1900        .collect()
1901}
1902
1903fn claim_verifier_scheduler_name<'a>(
1904    emitted: &mut std::collections::HashSet<&'a str>,
1905    name: &'a str,
1906) -> bool {
1907    emitted.insert(name)
1908}
1909
1910/// Emit `verifier/<sched>/<kernel>/<preset>: test` lines — one per
1911/// (declared scheduler × kernel-list entry × accepted topology preset)
1912/// cell. Mirrors the gauntlet emission pattern in [`list_tests_all`] but
1913/// walks [`super::KTSTR_SCHEDULERS`] instead of [`KTSTR_TESTS`]. The
1914/// verifier sweeps each declared scheduler ACROSS topologies, because
1915/// attach/liveness is topology-dependent (a scheduler can attach on one
1916/// topology and wedge on another). Cells are paired with the
1917/// [`run_verifier_cell`] handler registered in
1918/// [`ktstr_test_early_dispatch`]'s `--exact verifier/...` branch.
1919///
1920/// The matrix dimension is `KTSTR_KERNEL_LIST` (always populated by the
1921/// `cargo ktstr verifier` dispatcher — even with a single
1922/// auto-discovered kernel, the dispatcher synthesizes a one-entry list
1923/// with a derived label). Each scheduler's `declare_scheduler!`
1924/// `kernels = [...]` declaration acts as a per-scheduler filter on the
1925/// matrix — `Version` / `Range` declarations match entries by
1926/// raw-label equality / range membership; `Path` / `CacheKey` / `Git`
1927/// declarations match by sanitized-label equality. An empty
1928/// `kernels = []` declaration accepts every entry in the list.
1929///
1930/// The topology dimension is [`crate::gauntlet::gauntlet_presets`], gated
1931/// per scheduler: the verifier VM always runs no_perf_mode, so a preset
1932/// is emitted only when the scheduler's constraints accept it under
1933/// [`super::TopologyConstraints::accepts_verifier`] — the verifier-only
1934/// gate that ignores DEFAULT caps (so an untouched scheduler reaches the
1935/// beyond-host battery shapes) and imposes NO host-size bound for the
1936/// correctness-only verify cells. A scheduler that accepts no preset
1937/// emits no cell.
1938///
1939/// After structural constraints, the scheduler's
1940/// [`super::Scheduler::verifier_exclude_topologies`] list removes exact
1941/// preset-name matches. This named exception applies only to verifier
1942/// cells; ordinary gauntlet variants are unaffected.
1943///
1944/// Schedulers declared with [`super::SchedulerSpec::Eevdf`] or
1945/// [`super::SchedulerSpec::KernelBuiltin`] are skipped at emission time
1946/// because neither has a userspace binary to load BPF programs from.
1947///
1948/// When [`crate::KTSTR_VERIFIER_SCHEDULER_ENV`] is set (the
1949/// `cargo ktstr verifier --scheduler <NAME>` filter), every declared
1950/// scheduler whose `name` does not equal the value is skipped, so the
1951/// sweep covers one scheduler across topologies instead of the full
1952/// declared-scheduler matrix. A value matching no declared scheduler
1953/// (or a non-BPF one) emits no cell; the dispatcher reports the empty
1954/// result set rather than silently sweeping nothing.
1955///
1956/// Cell names with `/` in `sched.name` or `preset.name` would corrupt
1957/// the splitn-based parse in [`run_verifier_cell`]; the emission elides
1958/// such cells with a stderr warning. When `KTSTR_KERNEL_LIST` is absent
1959/// (direct binary invocation outside the dispatcher), no cells emit.
1960fn list_verifier_cells_all() {
1961    use super::SchedulerSpec;
1962    let cell_ownership = match crate::verifier::verifier_cell_ownership_from_env() {
1963        Ok(ownership) => ownership,
1964        Err(error) => {
1965            eprintln!("ktstr verifier: cannot establish cell ownership while listing: {error:#}");
1966            std::process::exit(1);
1967        }
1968    };
1969    let kernel_list = read_kernel_list();
1970    if kernel_list.is_empty() {
1971        return;
1972    }
1973    let presets = crate::gauntlet::gauntlet_presets();
1974    let mut emitted_scheduler_names = std::collections::HashSet::new();
1975    // No host_capacity() read here: verifier preset selection has no
1976    // host-size bound (see accepts_verifier) — a battery shape lists on
1977    // any host regardless of CPU count.
1978
1979    // `cargo ktstr verifier --scheduler <NAME>` filter (via
1980    // KTSTR_VERIFIER_SCHEDULER): when set, sweep only the named declared
1981    // scheduler across topologies instead of the full declared-scheduler
1982    // matrix. Read once; unset (or non-unicode) leaves the sweep full.
1983    let scheduler_filter = std::env::var(crate::KTSTR_VERIFIER_SCHEDULER_ENV).ok();
1984
1985    for sched in super::KTSTR_SCHEDULERS.iter() {
1986        if let Some(want) = &scheduler_filter
1987            && sched.name != want.as_str()
1988        {
1989            continue;
1990        }
1991        if matches!(
1992            sched.binary,
1993            SchedulerSpec::Eevdf | SchedulerSpec::KernelBuiltin { .. }
1994        ) {
1995            continue;
1996        }
1997        if sched.name.contains('/') {
1998            eprintln!(
1999                "ktstr verifier: scheduler name {:?} contains '/' — skipping cell emission (would corrupt verifier/<sched>/<kernel>/<preset> parse)",
2000                sched.name,
2001            );
2002            continue;
2003        }
2004        // Skip declarations whose binary is not a real, buildable
2005        // scheduler. The invariant is "a cell emits iff the runtime
2006        // resolver can build it": emission checks package membership of
2007        // the DECLARING crate's workspace (via
2008        // [`workspace_member_packages`] keyed on `sched.manifest_dir`),
2009        // and the runtime resolver in `run_verifier_cell_inner` builds in
2010        // that SAME workspace with `cargo build -p <pkg>` run from
2011        // `sched.manifest_dir` — so the two stay in lockstep. The
2012        // macro-expansion FIXTURES in tests/declare_scheduler.rs
2013        // (`binary = "scx-full"`, `"scx-ee"`, …) are declared in ktstr's
2014        // own tests and name packages that are NOT members of ktstr's
2015        // workspace, so they are gated out; emitting their cells would
2016        // make `cargo ktstr verifier --run-ignored` fail on
2017        // `cargo build -p <fixture>` for a nonexistent package. A
2018        // `Discover` of a real workspace member (scx-ktstr) and a `Path`
2019        // that exists still emit.
2020        match sched.binary {
2021            SchedulerSpec::Discover(pkg)
2022                if !workspace_member_packages(sched.manifest_dir).contains(pkg) =>
2023            {
2024                continue;
2025            }
2026            SchedulerSpec::Path(p) if !std::path::Path::new(p).exists() => {
2027                continue;
2028            }
2029            _ => {}
2030        }
2031        let scheduler_json = super::SchedulerJson::from_scheduler(sched);
2032        if !scheduler_json.has_accepted_verifier_cell(
2033            kernel_list
2034                .iter()
2035                .map(|entry| (entry.label.as_str(), entry.sanitized.as_str())),
2036            &presets,
2037        ) {
2038            continue;
2039        }
2040        if let Some(ownership) = &cell_ownership {
2041            match ownership.owns_scheduler(&scheduler_json) {
2042                Ok(true) => {}
2043                Ok(false) => continue,
2044                Err(error) => {
2045                    eprintln!(
2046                        "ktstr verifier: cannot establish cell ownership for scheduler {:?}: \
2047                         {error:#}",
2048                        sched.name,
2049                    );
2050                    std::process::exit(1);
2051                }
2052            }
2053        }
2054        // The parent collapses exact declarations across binaries. Mirror
2055        // that identity rule inside the elected binary too: repeated links of
2056        // the same scheduler static/name still advertise one nextest cell set.
2057        if !claim_verifier_scheduler_name(&mut emitted_scheduler_names, sched.name) {
2058            continue;
2059        }
2060        for kernel_entry in &kernel_list {
2061            if !scheduler_json
2062                .accepts_verifier_kernel(&kernel_entry.label, kernel_entry.sanitized.as_str())
2063            {
2064                continue;
2065            }
2066            // One cell per (scheduler, kernel, topology preset). The
2067            // verifier sweep runs each scheduler's "does it verify,
2068            // attach, AND dispatch" check ACROSS topologies, because
2069            // both vary with topology: attach/liveness (a scheduler can
2070            // attach on one topology and wedge on another — odd LLC
2071            // counts, large CPU counts, SMT) and verified_insns (a
2072            // scheduler that bakes topology-derived config into .rodata
2073            // hands the verifier different known constants, so it
2074            // processes a different instruction count per topology). The
2075            // verifier VM always runs no_perf_mode, so preset eligibility
2076            // uses accepts_verifier: the KVM-emulated topology is gated by
2077            // the scheduler's declared scope, with DEFAULT caps treated as
2078            // "no opinion" and NO host-size bound — the correctness-only
2079            // verify cells tolerate overcommit at any ratio (storm-validated
2080            // + progress-watchdog), so beyond-host shapes always enter.
2081            for preset in presets.iter() {
2082                if preset.name.contains('/') {
2083                    eprintln!(
2084                        "ktstr verifier: preset name {:?} contains '/' — skipping cell (would corrupt parse)",
2085                        preset.name,
2086                    );
2087                    continue;
2088                }
2089                if !scheduler_json.accepts_verifier_preset(preset) {
2090                    continue;
2091                }
2092                println!(
2093                    "verifier/{}/{}/{}: test",
2094                    sched.name, kernel_entry.sanitized, preset.name,
2095                );
2096            }
2097        }
2098    }
2099}
2100
2101/// Apply the verifier-only topology policy for one scheduler/preset
2102/// pair. Kept separate from emission so named exclusions are directly
2103/// unit-testable without capturing a process-wide nextest listing.
2104#[cfg(test)]
2105fn scheduler_accepts_verifier_preset(
2106    sched: &super::Scheduler,
2107    preset: &crate::gauntlet::TopoPreset,
2108) -> bool {
2109    super::SchedulerJson::from_scheduler(sched).accepts_verifier_preset(preset)
2110}
2111
2112/// Whether a verifier-cell error is a typed guest-kernel/topology
2113/// incompatibility. Chain-aware so the collection path may add context
2114/// without turning an unsupported cell back into a scheduler failure.
2115fn is_verifier_topology_unsupported(e: &anyhow::Error) -> bool {
2116    e.chain().any(|cause| {
2117        cause
2118            .downcast_ref::<crate::verifier::VerifierTopologyUnsupported>()
2119            .is_some()
2120    })
2121}
2122
2123/// Parse `verifier/<sched_name>/<kernel_label>/<preset_name>`, look up
2124/// the declared scheduler in [`super::KTSTR_SCHEDULERS`] + the gauntlet
2125/// preset in [`crate::gauntlet::gauntlet_presets`] + the kernel in
2126/// [`KTSTR_KERNEL_LIST_ENV`](crate::KTSTR_KERNEL_LIST_ENV), resolve the
2127/// scheduler binary path per [`super::SchedulerSpec`], boot the verifier
2128/// VM on that topology via [`crate::verifier::collect_verifier_output`],
2129/// and print the rendered output. Returns 0 only when the scheduler
2130/// verified (BPF loaded), turned on (the guest attach gate reached
2131/// sched_ext `enabled`, surfaced via [`crate::verifier::AttachOutcome`]),
2132/// dispatched the injected workload while the scheduler child was live and
2133/// sched_ext remained enabled, survived to ktstr's intentional cleanup kill,
2134/// and published an explicit CRC-valid guest exit frame carrying code 0.
2135/// [`crate::verifier::VerifierVmResult::cell_verdict`] also rejects a
2136/// scheduler-exit frame, a missing terminal frame, a teardown hang
2137/// (`timed_out`), or a malformed cell name.
2138///
2139/// The per-cell kernel directory is resolved by sanitized-label
2140/// lookup in `KTSTR_KERNEL_LIST` — the
2141/// `cargo ktstr verifier` dispatcher always populates the list,
2142/// even with no `--kernel` flag (it synthesizes a single auto-
2143/// discovered entry). There is no single-kernel-mode fallback.
2144/// An unrecognised label or an absent list both surface as an
2145/// exit-1 diagnostic naming the present labels and pointing at
2146/// the dispatcher.
2147///
2148/// Eevdf + KernelBuiltin scheduler variants are filtered out at
2149/// emission time in [`list_verifier_cells_all`], so nextest
2150/// dispatch never reaches the SKIP arms in this function. The
2151/// SKIP arms remain as defense-in-depth for direct
2152/// `--exact verifier/<eevdf>/...` invocation outside nextest
2153/// (the only path that bypasses the emission-time filter); in
2154/// that case they emit a `SKIP` banner + exit 0.
2155fn run_verifier_cell_inner(
2156    full_name: &str,
2157    sched: &super::Scheduler,
2158    out_stats: &mut Vec<crate::verifier::ProgStats>,
2159    out_skipped: &mut bool,
2160) -> i32 {
2161    use super::SchedulerSpec;
2162
2163    let rest = match full_name.strip_prefix("verifier/") {
2164        Some(r) => r,
2165        None => {
2166            eprintln!("ktstr verifier: missing 'verifier/' prefix in {full_name:?}");
2167            return 1;
2168        }
2169    };
2170    let parts: Vec<&str> = rest.splitn(3, '/').collect();
2171    if parts.len() != 3 {
2172        eprintln!(
2173            "ktstr verifier: malformed cell name {full_name:?}; expected verifier/<sched>/<kernel>/<preset>",
2174        );
2175        return 1;
2176    }
2177    let (sched_name, kernel_label, preset_name) = (parts[0], parts[1], parts[2]);
2178
2179    // Emit the cell banner BEFORE every SKIP / FAIL branch so the
2180    // operator always sees which (scheduler, kernel, topology) tuple
2181    // produced the result. Without it an early-exit SKIP / FAIL would
2182    // surface as a bare error line nextest tags with the full cell name
2183    // but no per-axis context.
2184    println!("\n=== {sched_name} | kernel {kernel_label} | topology {preset_name} ===");
2185
2186    // Fail-fast on missing KVM with the canonical actionable error
2187    // (kvm group / kvm-ok hint). Without this preflight the operator
2188    // gets a deep error inside VM bring-up.
2189    if let Err(e) = crate::cli::check_kvm() {
2190        eprintln!("ktstr verifier: cell {full_name}: {e:#}");
2191        return 1;
2192    }
2193
2194    if sched.name != sched_name {
2195        eprintln!(
2196            "ktstr verifier: selected scheduler {:?} does not match cell {full_name:?}",
2197            sched.name,
2198        );
2199        return 1;
2200    }
2201
2202    // Resolve the cell's topology preset by its <preset> name segment.
2203    let preset_list = crate::gauntlet::gauntlet_presets();
2204    let Some(preset) = preset_list.iter().find(|p| p.name == preset_name) else {
2205        eprintln!("ktstr verifier: no gauntlet preset {preset_name:?} (cell {full_name:?})",);
2206        return 1;
2207    };
2208
2209    // Resolve the per-cell kernel directory by looking the cell's
2210    // sanitized label up in `KTSTR_KERNEL_LIST`. The
2211    // `cargo ktstr verifier` dispatcher always populates the list —
2212    // even with no `--kernel` flag it synthesizes a single auto-
2213    // discovered entry — so the lookup is the single source of
2214    // truth and there is no single-kernel-mode fallback that would
2215    // silently run a cell against an unrelated kernel.
2216    //
2217    // An empty list reaching this function means the test binary was
2218    // invoked outside the dispatcher (direct `--exact verifier/...`
2219    // under a hand-spawned nextest, for instance). Error with an
2220    // actionable message rather than fall through to auto-discovery.
2221    let kernel_list = read_kernel_list();
2222    let Some(kernel_entry) = kernel_list
2223        .iter()
2224        .find(|k| k.sanitized.as_str() == kernel_label)
2225    else {
2226        if kernel_list.is_empty() {
2227            eprintln!("{}", format_empty_kernel_list_error(full_name));
2228        } else {
2229            let present: Vec<&str> = kernel_list.iter().map(|k| k.sanitized.as_str()).collect();
2230            eprintln!(
2231                "{}",
2232                format_unknown_kernel_label_error(full_name, kernel_label, sched_name, &present,),
2233            );
2234        }
2235        return 1;
2236    };
2237
2238    let prebuilt = if sched.binary.has_bpf_scheduler() {
2239        match crate::scheduler_artifact::scheduler_artifact_from_env(
2240            Some(sched.name),
2241            &sched.binary,
2242            sched.manifest_dir,
2243        ) {
2244            Ok(path) => path,
2245            Err(e) => {
2246                eprintln!(
2247                    "ktstr verifier: resolve parent-owned scheduler artifact for \
2248                     {sched_name:?}: {e:#}"
2249                );
2250                return 1;
2251            }
2252        }
2253    } else {
2254        None
2255    };
2256    let sched_bin: std::path::PathBuf = if let Some(path) = prebuilt {
2257        path
2258    } else {
2259        match sched.binary {
2260            // A cargo-ktstr parent prebuilds every selected Discover package once
2261            // and exports the same immutable exact-identity manifest used by
2262            // ordinary and coverage tests. A direct/manual cell invocation has no
2263            // manifest and retains on-demand resolution. Once a manifest is
2264            // present, lookup failure is fatal and MUST NOT silently rebuild.
2265            SchedulerSpec::Discover(pkg) => {
2266                match crate::build_and_find_binary(pkg, sched.manifest_dir) {
2267                    Ok(path) => path,
2268                    Err(e) => {
2269                        eprintln!("ktstr verifier: build scheduler {pkg:?}: {e:#}");
2270                        return 1;
2271                    }
2272                }
2273            }
2274            SchedulerSpec::Path(p) => {
2275                let path = std::path::PathBuf::from(p);
2276                if !path.exists() {
2277                    eprintln!("ktstr verifier: scheduler binary not found: {p}");
2278                    return 1;
2279                }
2280                path
2281            }
2282            // Eevdf + KernelBuiltin are filtered at list time in
2283            // list_verifier_cells_all, so nextest dispatch never reaches
2284            // these arms. The SKIP arms remain as defense-in-depth for
2285            // direct `--exact verifier/<eevdf>/...` invocation outside
2286            // nextest.
2287            SchedulerSpec::Eevdf => {
2288                *out_skipped = true;
2289                println!(
2290                    "ktstr verifier: SKIP cell {full_name} (Eevdf has no userspace binary to verify)",
2291                );
2292                return 0;
2293            }
2294            SchedulerSpec::KernelBuiltin { .. } => {
2295                *out_skipped = true;
2296                println!(
2297                    "ktstr verifier: SKIP cell {full_name} (KernelBuiltin has no userspace binary to verify)",
2298                );
2299                return 0;
2300            }
2301        }
2302    };
2303
2304    let ktstr_bin = match std::env::current_exe() {
2305        Ok(p) => p,
2306        Err(e) => {
2307            eprintln!(
2308                "ktstr verifier: locate ktstr binary via current_exe() (required so the \
2309                 verifier VM can boot the same test binary as /init for guest-side dispatch): {e}",
2310            );
2311            return 1;
2312        }
2313    };
2314
2315    // Resolve the kernel-build DIR to the actual bootable image file.
2316    // `collect_verifier_output` -> `KtstrVm::builder().kernel()` loads the
2317    // path verbatim (build() does NOT extract a source tree), so passing
2318    // the raw dir makes the VMM loader read a directory as a bzImage and
2319    // fail with "Unable to read bzImage header". `find_image_in_dir`
2320    // handles both the build-tree (`arch/*/boot/bzImage`) and cache
2321    // (`<dir>/bzImage`) layouts — the same resolution the eval path uses.
2322    let kernel_path = if kernel_entry.kernel_dir.is_file() {
2323        kernel_entry.kernel_dir.clone()
2324    } else {
2325        match crate::kernel_path::find_image_in_dir(&kernel_entry.kernel_dir) {
2326            Some(img) => img,
2327            None => {
2328                eprintln!(
2329                    "ktstr verifier: cell {full_name}: no kernel image \
2330                     (arch/*/boot/bzImage or a cached bzImage) under {} — \
2331                     build the kernel first",
2332                    kernel_entry.kernel_dir.display(),
2333                );
2334                return 1;
2335            }
2336        }
2337    };
2338    // Pass the preset's Topology directly (192cpu-11llc-smt's per-LLC core
2339    // counts must survive into the guest CPUID; the TopologyJson wire
2340    // shape would drop them).
2341    let topology = preset.topology;
2342    let memory_min_mib =
2343        super::runtime::verifier_preset_memory_min_mib(topology.total_cpus(), preset.memory_mib);
2344    let launch = crate::verifier::VerifierSchedulerLaunchPlan::from_scheduler(sched);
2345
2346    // Raw mode is opt-in via the dispatcher's --raw flag, plumbed
2347    // through KTSTR_VERIFIER_RAW_ENV. Presence (any value, including
2348    // empty) enables raw rendering — matches the "set to any value"
2349    // semantics documented on the const and the dispatcher's
2350    // `cmd.env(KTSTR_VERIFIER_RAW_ENV, "1")` setter.
2351    let raw = std::env::var_os(crate::KTSTR_VERIFIER_RAW_ENV).is_some();
2352
2353    match crate::verifier::collect_verifier_output_with_memory_min(
2354        &sched_bin,
2355        &ktstr_bin,
2356        &kernel_path,
2357        &launch,
2358        topology,
2359        memory_min_mib,
2360        preset.forced_cpu_budget,
2361    ) {
2362        Ok(result) => {
2363            let output = crate::verifier::format_verifier_output("verifier", &result, raw);
2364            print!("{output}");
2365            // Propagate the scheduler's captured stderr to the test's
2366            // real stderr (best-effort — whatever streamed before a
2367            // watchdog kill). Emitted BEFORE the `... FAILED:` verdict
2368            // line below so the verdict stays the last thing on stderr.
2369            let sched_stderr = crate::verifier::format_verifier_stderr("verifier", &result, raw);
2370            if !sched_stderr.is_empty() {
2371                eprint!("{sched_stderr}");
2372            }
2373            // PASS requires verify + attach, contemporaneous dispatch
2374            // progress with a live/enabled scheduler, no observed scheduler
2375            // exit, cleanup liveness confirmation, and an explicit terminal
2376            // guest exit 0. `cell_verdict` names the first failing host-side
2377            // gate (timed_out / scheduler-exit → attach → dispatch → terminal
2378            // exit, root cause first).
2379            let code = match result.cell_verdict() {
2380                Ok(()) => 0,
2381                Err(reason) => {
2382                    eprintln!("ktstr verifier: cell {full_name} FAILED: {reason}");
2383                    1
2384                }
2385            };
2386            // Hand the per-program verified_insns out to the record writer
2387            // so the dispatcher can render the instruction-count tables.
2388            // Only this arm produces them; every earlier return (skip,
2389            // kernel resolution error, build failure) leaves them empty.
2390            *out_stats = result.stats;
2391            code
2392        }
2393        Err(e) if is_verifier_topology_unsupported(&e) => {
2394            *out_skipped = true;
2395            println!("ktstr verifier: SKIP cell {full_name} ({e:#})");
2396            0
2397        }
2398        Err(e) => {
2399            eprintln!("ktstr verifier: cell {full_name} FAILED: {e:#}");
2400            1
2401        }
2402    }
2403}
2404
2405/// Check parent-elected ownership before an exact verifier cell can launch or
2406/// write its deterministic record.
2407///
2408/// The environment-absent path preserves direct/manual invocation. Once a
2409/// manifest is present, malformed names and missing local declarations cannot
2410/// establish ownership and fail closed. A non-owner returns `Ok(None)` so the
2411/// wrapper can reject it without entering either the VM path or record writer.
2412fn select_verifier_scheduler_from<'a>(
2413    schedulers: impl IntoIterator<Item = &'a super::Scheduler>,
2414    scheduler_name: &str,
2415    expected: Option<&super::SchedulerJson>,
2416) -> anyhow::Result<&'a super::Scheduler> {
2417    let mut candidates = schedulers
2418        .into_iter()
2419        .filter(|scheduler| scheduler.name == scheduler_name);
2420    let Some(expected) = expected else {
2421        return candidates.next().ok_or_else(|| {
2422            anyhow::anyhow!("no declared scheduler {scheduler_name:?} exists in this test binary")
2423        });
2424    };
2425    candidates
2426        .find(|scheduler| super::SchedulerJson::from_scheduler(scheduler).eq(expected))
2427        .ok_or_else(|| {
2428            anyhow::anyhow!(
2429                "this test binary has no declaration matching the parent-selected full \
2430                 identity for scheduler {scheduler_name:?}: {expected:?}"
2431            )
2432        })
2433}
2434
2435fn select_local_verifier_scheduler(
2436    scheduler_name: &str,
2437    expected: Option<&super::SchedulerJson>,
2438) -> anyhow::Result<&'static super::Scheduler> {
2439    select_verifier_scheduler_from(
2440        super::KTSTR_SCHEDULERS.iter().copied(),
2441        scheduler_name,
2442        expected,
2443    )
2444}
2445
2446fn current_binary_verifier_scheduler(
2447    full_name: &str,
2448) -> anyhow::Result<Option<&'static super::Scheduler>> {
2449    let rest = full_name
2450        .strip_prefix("verifier/")
2451        .ok_or_else(|| anyhow::anyhow!("missing 'verifier/' prefix in cell name {full_name:?}"))?;
2452    let parts = rest.splitn(3, '/').collect::<Vec<_>>();
2453    if parts.len() != 3 {
2454        anyhow::bail!(
2455            "malformed cell name {full_name:?}; expected \
2456             verifier/<sched>/<kernel>/<preset>"
2457        );
2458    }
2459    let scheduler_name = parts[0];
2460    let Some(ownership) = crate::verifier::verifier_cell_ownership_from_env()? else {
2461        return select_local_verifier_scheduler(scheduler_name, None).map(Some);
2462    };
2463    let Some(expected) = ownership.owned_scheduler(scheduler_name)? else {
2464        return Ok(None);
2465    };
2466    select_local_verifier_scheduler(scheduler_name, Some(expected)).map(Some)
2467}
2468
2469/// Run a verifier cell and, when the `cargo ktstr verifier` dispatcher
2470/// set [`crate::KTSTR_VERIFIER_RESULT_DIR_ENV`], record its
2471/// PASS/FAIL/SKIP outcome there so the dispatcher can render the
2472/// run-summary table after nextest returns. Best-effort + env-gated: a direct
2473/// `--exact verifier/...` invocation (env unset) behaves exactly as
2474/// [`run_verifier_cell_inner`], and a record-write failure never changes
2475/// the cell's exit code. A nextest RETRY re-runs this wrapper and
2476/// overwrites the cell's own record (deterministic filename), so the
2477/// final attempt's outcome is the one that lands in the table.
2478fn run_verifier_cell_after_ownership(
2479    full_name: &str,
2480    scheduler: anyhow::Result<Option<&super::Scheduler>>,
2481    execute: impl FnOnce(
2482        &str,
2483        &super::Scheduler,
2484        &mut Vec<crate::verifier::ProgStats>,
2485        &mut bool,
2486    ) -> i32,
2487) -> i32 {
2488    let scheduler = match scheduler {
2489        Ok(Some(scheduler)) => scheduler,
2490        Ok(None) => {
2491            eprintln!("ktstr verifier: refusing non-owner exact-cell dispatch for {full_name:?}");
2492            return 1;
2493        }
2494        Err(error) => {
2495            eprintln!(
2496                "ktstr verifier: cannot establish exact-cell ownership for {full_name:?}: \
2497                 {error:#}"
2498            );
2499            return 1;
2500        }
2501    };
2502    let mut stats = Vec::new();
2503    let mut skipped = false;
2504    let code = execute(full_name, scheduler, &mut stats, &mut skipped);
2505    if let Some(dir) = std::env::var_os(crate::KTSTR_VERIFIER_RESULT_DIR_ENV) {
2506        crate::verifier::write_cell_record(
2507            std::path::Path::new(&dir),
2508            full_name,
2509            code == 0 && !skipped,
2510            skipped,
2511            &stats,
2512        );
2513    }
2514    code
2515}
2516
2517fn run_verifier_cell(full_name: &str) -> i32 {
2518    run_verifier_cell_after_ownership(
2519        full_name,
2520        current_binary_verifier_scheduler(full_name),
2521        run_verifier_cell_inner,
2522    )
2523}
2524
2525/// List tests with budget-based coverage maximization.
2526///
2527/// Collects all eligible tests as candidates, runs greedy selection,
2528/// and prints only the selected subset. Multi-kernel mode adds the
2529/// kernel suffix as a feature dimension so the budget selector
2530/// picks per-kernel coverage; single-kernel mode is unchanged.
2531///
2532/// `KTSTR_CARGO_TEST_MODE=1` is treated identically to
2533/// `list_tests_all`: the budget pipeline runs only over base test
2534/// candidates (no gauntlet-variant candidates, no multi-kernel
2535/// fan-out). The greedy selector still applies — a low budget
2536/// can still trim the base list — but the candidate set is the
2537/// same set that the dispatch path would actually run.
2538fn push_budget_base_candidates(
2539    candidates: &mut Vec<crate::budget::TestCandidate>,
2540    entry: &KtstrTestEntry,
2541    ignored_only: bool,
2542    base_ignored: bool,
2543    base_topo: &crate::vmm::topology::Topology,
2544    kernel_suffixes: &[&str],
2545) {
2546    use crate::budget::{TestCandidate, estimate_duration, extract_features};
2547
2548    if ignored_only && !base_ignored {
2549        return;
2550    }
2551
2552    // Host-only tests never boot a VM, so the kernel never affects what
2553    // runs. Emit one candidate without a kernel suffix even in multi-kernel
2554    // mode; VM tests retain one candidate per selected kernel.
2555    if entry.host_only {
2556        candidates.push(TestCandidate {
2557            name: format!("host/{}: test", entry.name),
2558            features: extract_features(entry, base_topo, false, entry.name),
2559            estimated_secs: estimate_duration(entry, base_topo),
2560        });
2561    } else {
2562        for suffix in kernel_suffixes {
2563            let name = if suffix.is_empty() {
2564                format!("ktstr/{}: test", entry.name)
2565            } else {
2566                format!("ktstr/{}/{suffix}: test", entry.name)
2567            };
2568            candidates.push(TestCandidate {
2569                name,
2570                features: extract_features(entry, base_topo, false, entry.name),
2571                estimated_secs: estimate_duration(entry, base_topo),
2572            });
2573        }
2574    }
2575}
2576
2577fn list_tests_budget(ignored_only: bool, budget_secs: f64) {
2578    use crate::budget::{TestCandidate, estimate_duration, extract_features, select};
2579
2580    let cargo_test_mode = crate::cargo_test_mode::cargo_test_mode_active();
2581    let presets = crate::gauntlet::gauntlet_presets();
2582    let has_vmlinux = resolve_test_kernel()
2583        .ok()
2584        .and_then(|k| crate::vmm::find_vmlinux(&k))
2585        .is_some();
2586    let (host_cpus, host_llcs, host_max_cpus_per_llc) = super::host_capacity();
2587    let mut candidates: Vec<TestCandidate> = Vec::new();
2588
2589    let kernel_list = read_kernel_list();
2590    let multi_kernel = kernel_list.len() > 1 && !cargo_test_mode;
2591    let kernel_suffixes: Vec<&str> = if multi_kernel {
2592        kernel_list.iter().map(|k| k.sanitized.as_str()).collect()
2593    } else {
2594        vec![""]
2595    };
2596
2597    for entry in KTSTR_TESTS.iter() {
2598        // Same sentinel exclusion as `list_tests_all`: fixtures never
2599        // become budget candidates.
2600        if is_test_sentinel(entry.name) {
2601            continue;
2602        }
2603        if !entry.bpf_map_write.is_empty() && !has_vmlinux {
2604            continue;
2605        }
2606
2607        let base_ignored = is_ignored(entry);
2608        let base_topo = entry.topology;
2609
2610        push_budget_base_candidates(
2611            &mut candidates,
2612            entry,
2613            ignored_only,
2614            base_ignored,
2615            &base_topo,
2616            &kernel_suffixes,
2617        );
2618
2619        if entry.host_only {
2620            continue;
2621        }
2622
2623        if cargo_test_mode {
2624            // No gauntlet candidates in cargo-test mode — the
2625            // dispatch path will never execute them and including
2626            // them in the budget candidate set would shift greedy
2627            // selection toward variants that resolve to "no test"
2628            // at run time.
2629            continue;
2630        }
2631
2632        for_each_gauntlet_variant(
2633            entry,
2634            &presets,
2635            host_cpus,
2636            host_llcs,
2637            host_max_cpus_per_llc,
2638            |preset| {
2639                for suffix in &kernel_suffixes {
2640                    let test_name = if suffix.is_empty() {
2641                        format!("gauntlet/{}/{}", entry.name, preset.name)
2642                    } else {
2643                        format!("gauntlet/{}/{}/{suffix}", entry.name, preset.name)
2644                    };
2645                    candidates.push(TestCandidate {
2646                        name: format!("{test_name}: test"),
2647                        features: extract_features(entry, &preset.topology, true, &test_name),
2648                        estimated_secs: estimate_duration(entry, &preset.topology),
2649                    });
2650                }
2651            },
2652        );
2653    }
2654
2655    let selected = select(&candidates, budget_secs);
2656    for &i in &selected {
2657        println!("{}", candidates[i].name);
2658    }
2659
2660    let stats = crate::budget::selection_stats(&candidates, &selected, budget_secs);
2661    eprintln!(
2662        "ktstr budget: {}/{} tests, {:.0}/{:.0}s used, {}/{} configurations covered",
2663        stats.selected,
2664        stats.total,
2665        stats.budget_used,
2666        stats.budget_total,
2667        stats.bits_covered,
2668        stats.bits_possible,
2669    );
2670}
2671
2672/// Strip an optional `/{sanitized_kernel_label}` suffix from `name`,
2673/// look up the matching [`KernelEntry`] in the multi-kernel list,
2674/// and re-export `KTSTR_KERNEL` to that entry's directory. Returns
2675/// the prefix-only name for the dispatch caller.
2676///
2677/// When `KTSTR_KERNEL_LIST` is unset / single-entry, the function
2678/// is a no-op pass-through: returns `(name, None)` and does not
2679/// touch the env. When the list has 2+ entries, the suffix is
2680/// REQUIRED and missing it surfaces as `Err` (the early-dispatch
2681/// caller turns that into exit code 1 with an actionable message)
2682/// — the suffix is part of every test name `--list` emitted, so a
2683/// `--exact` invocation that omits it can only come from operator
2684/// hand-construction or tooling that hasn't been taught the
2685/// multi-kernel naming.
2686fn strip_kernel_suffix<'a>(
2687    name: &'a str,
2688    kernel_list: &'a [KernelEntry],
2689) -> Result<(&'a str, Option<&'a KernelEntry>), String> {
2690    if kernel_list.len() <= 1 {
2691        return Ok((name, None));
2692    }
2693    // Multi-kernel: every test name carries `/kernel_…` as its
2694    // final segment. Iterate the labels rather than splitting on
2695    // `/` — the suffix always has exactly one extra `/` separator
2696    // before `kernel_…`, but the body of the test name CAN contain
2697    // `/` (gauntlet variants already do — `gauntlet/{name}/{preset}`),
2698    // so a naive `rsplit_once('/')` would accidentally peel the
2699    // preset segment instead.
2700    //
2701    // Distinct kernels in the same `KTSTR_KERNEL_LIST` produce
2702    // distinct sanitized labels in practice — the producer emits
2703    // semantic identifiers (version strings, git owner/repo/ref,
2704    // path basename + 6-char hash) that don't share suffixes
2705    // among the resolved set. If a future regression DID produce
2706    // labels where one is a strict suffix of another (e.g.
2707    // `kernel_6_14` vs `kernel_x_kernel_6_14`), the iterate-and-
2708    // first-match below would pick whichever appears first in
2709    // the kernel_list — deterministic but potentially wrong.
2710    // Producer-side regression detection would catch that
2711    // class of collision before it reaches this peeler.
2712    for entry in kernel_list {
2713        let needle = format!("/{}", entry.sanitized);
2714        if let Some(stripped) = name.strip_suffix(&needle) {
2715            return Ok((stripped, Some(entry)));
2716        }
2717    }
2718    Err(format!(
2719        "test name {name:?} has no recognised kernel suffix (KTSTR_KERNEL_LIST \
2720         carries {n} kernels — every test name must end with `/kernel_…`)",
2721        n = kernel_list.len(),
2722    ))
2723}
2724
2725/// Re-export `KTSTR_KERNEL` to the kernel directory carried by a
2726/// resolved [`KernelEntry`]. Called when a multi-kernel `--exact`
2727/// dispatch peels off the per-test kernel suffix.
2728///
2729/// SAFETY: nextest invokes the test binary's `--exact` handler in a
2730/// single-threaded context — there are no other readers of the env
2731/// at this point. The eventual VM-launch site reads `KTSTR_KERNEL`
2732/// via `find_kernel` after this returns; that read is sequenced
2733/// after the write per the program order.
2734fn export_kernel_for_variant(entry: &KernelEntry) {
2735    // SAFETY: see fn-level doc — single-threaded ctor / nextest
2736    // dispatch context.
2737    unsafe { std::env::set_var(crate::KTSTR_KERNEL_ENV, &entry.kernel_dir) };
2738}
2739
2740/// Parse a nextest-style test name and run it.
2741///
2742/// Handles VM base tests (`ktstr/{name}`), host-only tests (`host/{name}`),
2743/// gauntlet variants (`gauntlet/{name}/{preset}`), and bare names (backward
2744/// compatibility).
2745/// When `KTSTR_KERNEL_LIST` carries 2+ kernels,
2746/// VM-bound test names additionally end with
2747/// `/{sanitized_kernel_label}` — that suffix is peeled here and
2748/// the matching kernel directory is re-exported via
2749/// [`crate::KTSTR_KERNEL_ENV`] before the dispatch continues. `host_only`
2750/// tests are short-circuited BEFORE the suffix peel: they never
2751/// boot a VM, so the kernel-suffix listing path emits one
2752/// `host/{name}: test` entry without a kernel suffix regardless
2753/// of the kernel-list cardinality (see `list_tests_all` /
2754/// `list_tests_budget`), and routing them through
2755/// `strip_kernel_suffix` would surface as a "no recognised kernel
2756/// suffix" exit-1 error. Returns an exit code.
2757pub(crate) fn run_named_test(test_name: &str) -> i32 {
2758    let kernel_list = read_kernel_list();
2759
2760    // host_only short-circuit: in multi-kernel mode, host_only tests
2761    // are listed without a `/{sanitized_kernel_label}` suffix (see
2762    // `list_tests_all` / `list_tests_budget`, which emit a single
2763    // `host/{name}: test` line for host_only entries regardless of
2764    // the kernel-list cardinality — a host_only test never boots a
2765    // VM, so the kernel never affects what runs). Calling
2766    // `strip_kernel_suffix` on such a name in multi-kernel mode
2767    // would fail with the "no recognised kernel suffix" error and
2768    // misroute every host_only dispatch to exit 1.
2769    //
2770    // Resolve the host_only check from `find_test` BEFORE the
2771    // suffix peel so the multi-kernel branch only applies to
2772    // VM-bound tests. Single-kernel mode is unaffected — the
2773    // pass-through arm in `strip_kernel_suffix` returns the input
2774    // verbatim either way.
2775    let bare_for_lookup = test_name
2776        .strip_prefix("host/")
2777        .or_else(|| test_name.strip_prefix("ktstr/"))
2778        .unwrap_or(test_name);
2779
2780    if let Some(entry) = find_test(bare_for_lookup)
2781        && entry.host_only
2782    {
2783        return run_host_only_test(entry);
2784    }
2785
2786    let (test_name, kernel_entry) = match strip_kernel_suffix(test_name, &kernel_list) {
2787        Ok(pair) => pair,
2788        Err(e) => {
2789            eprintln!("{e}");
2790            return 1;
2791        }
2792    };
2793    if let Some(entry) = kernel_entry {
2794        export_kernel_for_variant(entry);
2795    }
2796
2797    if let Some(rest) = test_name.strip_prefix("gauntlet/") {
2798        return run_gauntlet_test(rest);
2799    }
2800
2801    let bare_name = test_name
2802        .strip_prefix("host/")
2803        .or_else(|| test_name.strip_prefix("ktstr/"))
2804        .unwrap_or(test_name);
2805    let entry = match find_test(bare_name) {
2806        Some(e) => e,
2807        None => {
2808            eprintln!("unknown test: {test_name}");
2809            return 1;
2810        }
2811    };
2812
2813    // Defense-in-depth: host_only re-check after suffix peel for the
2814    // edge case where the bare_for_lookup pre-strip lookup missed
2815    // (e.g. a future test name shape that doesn't match the
2816    // pre-strip form but does after the suffix peel).
2817    if entry.host_only {
2818        return run_host_only_test(entry);
2819    }
2820
2821    if entry.performance_mode && super::runtime::no_perf_mode_active() {
2822        crate::report::test_skip(format_args!(
2823            "{}: test requires performance_mode but --no-perf-mode or KTSTR_NO_PERF_MODE is active",
2824            bare_name,
2825        ));
2826        // See run_ktstr_test_inner for the sidecar-emission rationale.
2827        // Plain (non-gauntlet) dispatch: no TopoOverride, so the skip
2828        // records entry.topology (declared == booted for a plain test).
2829        record_skip_sidecar(entry, None);
2830        return 0;
2831    }
2832
2833    if super::runtime::perf_only_skips_entry(entry) {
2834        crate::report::test_skip(format_args!(
2835            "{bare_name}: KTSTR_PERF_ONLY is active and this test is not a performance_mode test",
2836        ));
2837        // Skip sidecar so the perf-delta pool records the skip (excluded
2838        // from the A/B compare) rather than a phantom missing result.
2839        record_skip_sidecar(entry, None);
2840        return 0;
2841    }
2842
2843    if !entry.bpf_map_write.is_empty()
2844        && let Ok(kernel) = resolve_test_kernel()
2845        && crate::vmm::find_vmlinux(&kernel).is_none()
2846    {
2847        eprintln!("FAIL: vmlinux not found, bpf_map_write requires vmlinux");
2848        return 1;
2849    }
2850
2851    let result = run_ktstr_test_inner(entry, None);
2852    result_to_exit_code(result, entry.expect_err, entry.allow_inconclusive)
2853}
2854
2855/// Run a host-only test directly without booting a VM.
2856/// Returns an exit code for nextest dispatch.
2857fn run_host_only_test(entry: &KtstrTestEntry) -> i32 {
2858    let result = run_host_only_test_inner(entry);
2859    result_to_exit_code(result, entry.expect_err, entry.allow_inconclusive)
2860}
2861
2862/// Inner host-only dispatch returning `Result<AssertResult>`.
2863///
2864/// Builds a minimal Ctx and calls the test function on the host.
2865/// Used for tests that need host tools (cargo, nested VMs).
2866///
2867/// Topology comes from real-host sysfs (`/sys/devices/system/cpu/`)
2868/// via [`crate::topology::TestTopology::from_system`]; the test's
2869/// declared VM topology is intentionally ignored for host_only
2870/// runs because the test author wrote it for a synthetic VM and
2871/// the host's actual CPU layout is what `WorkSpec::workers_pct` /
2872/// `AffinityIntent::LlcAligned` resolve against. Bails with an
2873/// actionable diagnostic when sysfs CPU enumeration fails — the
2874/// underlying causes are missing `/sys/devices/system/cpu/online`
2875/// (no /sys mount or container masking), unreadable contents (rare
2876/// permissions edge), corrupt sysfs string (kernel/hardware bug),
2877/// or an empty online-CPU set (degenerate cpuset namespace).
2878///
2879/// Cgroup parent defaults to `/sys/fs/cgroup/ktstr`; the operator
2880/// can override via `KTSTR_HOST_CGROUP_PARENT`. The override path
2881/// is validated upfront: it must be non-empty and rooted under
2882/// `/sys/fs/cgroup` so an accidental empty/relative/foreign value
2883/// produces a clear error instead of an opaque cgroupfs failure
2884/// later. Empty-string env value is treated as "unset" and falls
2885/// back to the default.
2886///
2887/// For cgroup-v2 user delegation (Mode B/C: systemd `Delegate=yes`,
2888/// container `nsdelegate`), the operator sets
2889/// `KTSTR_CGROUP_WALK_ROOT` to the delegation boundary so
2890/// [`crate::cgroup::CgroupManager::setup`]'s ancestor
2891/// `subtree_control` walk stops there instead of EACCES-ing at
2892/// `user.slice` / the container root. Defaults to `/sys/fs/cgroup`
2893/// (Mode A: root-owned tree).
2894fn run_host_only_test_inner(entry: &KtstrTestEntry) -> Result<AssertResult> {
2895    let topo = crate::topology::TestTopology::from_system().context(
2896        "host_only requires real-host topology from sysfs; \
2897         the sysfs CPU enumeration at /sys/devices/system/cpu/online \
2898         failed — likely causes: running outside a /sys-mounted \
2899         environment, sysfs contents unreadable (permissions / \
2900         container mask), corrupt online-CPU string, or a degenerate \
2901         cpuset namespace with no online CPUs",
2902    )?;
2903    let cgroup_parent = resolve_host_cgroup_parent()?;
2904    let cgroups = build_host_cgroup_manager(&cgroup_parent)?;
2905    let merged_assert = crate::assert::Assert::default_checks()
2906        .merge(&entry.scheduler.assert)
2907        .merge(&entry.assert);
2908    let ctx = crate::scenario::Ctx::builder(&cgroups, &topo)
2909        .duration(entry.duration)
2910        .settle(std::time::Duration::ZERO)
2911        .assert(merged_assert)
2912        .entry_name(entry.name)
2913        // host_only is host-side with no VM: the resolved topology is
2914        // the declared entry.topology (resolve_vm_topology(entry, None)),
2915        // so compute the variant hash directly rather than threading.
2916        .variant_hash(super::sidecar::variant_hash_from_parts(
2917            entry,
2918            &entry.topology,
2919            &super::args::current_work_type(),
2920        ))
2921        .build();
2922    (entry.func)(&ctx)
2923}
2924
2925/// Default cgroup parent path for `host_only` tests when
2926/// `KTSTR_HOST_CGROUP_PARENT` is unset. Suitable for both root
2927/// (writable directly) and non-root (operator pre-creates
2928/// `/sys/fs/cgroup/ktstr` with appropriate ownership, OR overrides via
2929/// `KTSTR_HOST_CGROUP_PARENT` to point at a path inside a delegated
2930/// subtree) invocations. See [`resolve_host_cgroup_parent`] for the
2931/// env-override path and `build_host_cgroup_manager` for the
2932/// cgroup-v2 Mode B/C delegation wire-up.
2933///
2934/// `pub` so tests can pin against it instead of mirroring
2935/// the literal in their own assertion strings (the
2936/// `resolve_host_cgroup_parent_*` unit tests in `dispatch_tests.rs`
2937/// assert unset/empty env falls back to this const). Treat as the
2938/// canonical default — operators set `KTSTR_HOST_CGROUP_PARENT` to
2939/// override.
2940pub const DEFAULT_HOST_CGROUP_PARENT: &str = "/sys/fs/cgroup/ktstr";
2941
2942/// Resolve the cgroup parent path for `host_only` tests.
2943///
2944/// Reads `KTSTR_HOST_CGROUP_PARENT`. Empty / unset falls back to
2945/// `DEFAULT_HOST_CGROUP_PARENT`. A set value must be rooted under
2946/// `/sys/fs/cgroup` (no relative paths, no random /tmp dirs) so an
2947/// accidental misconfiguration surfaces here rather than as an
2948/// opaque cgroupfs failure inside `CgroupManager::setup`.
2949///
2950/// Non-root callers are admitted: cgroup-v2 user delegation (Mode
2951/// B/C: systemd `Delegate=yes`, container `nsdelegate`) is handled
2952/// by `build_host_cgroup_manager` threading
2953/// [`crate::KTSTR_CGROUP_WALK_ROOT_ENV`] into
2954/// [`crate::cgroup::CgroupManager::with_walk_root`] so the
2955/// `subtree_control` walk bails at the delegation root instead of
2956/// EACCES-ing on `user.slice`.
2957pub fn resolve_host_cgroup_parent() -> Result<String> {
2958    let parent = match std::env::var(crate::KTSTR_HOST_CGROUP_PARENT_ENV) {
2959        Ok(s) if !s.is_empty() => s,
2960        _ => return Ok(DEFAULT_HOST_CGROUP_PARENT.to_string()),
2961    };
2962    if !parent.starts_with("/sys/fs/cgroup") || parent == "/sys/fs/cgroup" {
2963        anyhow::bail!(
2964            "KTSTR_HOST_CGROUP_PARENT={parent:?}: must be rooted under \
2965             /sys/fs/cgroup and name a non-root subdirectory \
2966             (e.g. /sys/fs/cgroup/ktstr or /sys/fs/cgroup/ktstr-foo); \
2967             unset or empty falls back to {DEFAULT_HOST_CGROUP_PARENT}",
2968        );
2969    }
2970    Ok(parent)
2971}
2972
2973/// Build a [`crate::cgroup::CgroupManager`] for a `host_only` test
2974/// run, threading [`crate::KTSTR_CGROUP_WALK_ROOT_ENV`] into
2975/// [`crate::cgroup::CgroupManager::with_walk_root`] when set.
2976///
2977/// The walk root override bounds [`crate::cgroup::CgroupManager::setup`]'s
2978/// ancestor `subtree_control` walk for cgroup-v2 Mode B/C
2979/// delegation: under systemd `Delegate=yes` or a container's
2980/// `nsdelegate`, the operator owns subtree_control writes only
2981/// inside the delegated subtree. Without the override the walk
2982/// starts at `/sys/fs/cgroup` and EACCES-es at `user.slice` or the
2983/// container root.
2984///
2985/// Empty / unset falls through to the default `/sys/fs/cgroup`
2986/// (Mode A: root-owned tree). [`crate::cgroup::CgroupManager::with_walk_root`]
2987/// validates that the chosen walk root is a prefix of `parent` —
2988/// misconfigurations surface as a focused error before the first
2989/// cgroupfs write rather than as an opaque downstream EACCES.
2990///
2991/// Non-root callers with no walk-root override are admitted here — the
2992/// precondition (root, or a cgroup-v2 delegated walk root) is enforced
2993/// lazily at [`crate::cgroup::CgroupManager::setup`], the first real
2994/// cgroup operation. `host_only` tests that never create a cgroup
2995/// (macro-attribute fixtures, host-topology reads, nested-VM verifier
2996/// orchestration) therefore run without root; only a test that actually
2997/// touches a cgroup hits the deferred non-root error.
2998fn build_host_cgroup_manager(cgroup_parent: &str) -> Result<crate::cgroup::CgroupManager> {
2999    let cg = crate::cgroup::CgroupManager::new(cgroup_parent);
3000    match std::env::var(crate::KTSTR_CGROUP_WALK_ROOT_ENV) {
3001        Ok(walk_root) if !walk_root.is_empty() => {
3002            // Defense-in-depth: walk_root must be rooted under
3003            // /sys/fs/cgroup. Mirrors the sibling
3004            // KTSTR_HOST_CGROUP_PARENT_ENV guard above so an operator
3005            // typo surfaces here instead of as a downstream cgroupfs
3006            // fs::write EACCES.
3007            if !walk_root.starts_with("/sys/fs/cgroup") {
3008                anyhow::bail!(
3009                    "{env}={walk_root:?}: walk root must be rooted under /sys/fs/cgroup \
3010                     (e.g. /sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service \
3011                     for a systemd user session); the value supplied is outside the cgroup-v2 \
3012                     mount and would EACCES on the first cgroupfs write",
3013                    env = crate::KTSTR_CGROUP_WALK_ROOT_ENV,
3014                );
3015            }
3016            cg.with_walk_root(&walk_root).with_context(|| {
3017                format!(
3018                    "{env}={walk_root:?}: walk-root override rejected (must be a prefix of \
3019                     KTSTR_HOST_CGROUP_PARENT={cgroup_parent:?})",
3020                    env = crate::KTSTR_CGROUP_WALK_ROOT_ENV,
3021                )
3022            })
3023        }
3024        // No KTSTR_CGROUP_WALK_ROOT override. Return the manager as-is;
3025        // the non-root precondition for managing cgroups under the
3026        // kernel-owned default walk root is checked lazily in
3027        // CgroupManager::setup (first real cgroup use). host_only tests
3028        // that never create a cgroup — macro-attribute fixtures,
3029        // host-topology reads, nested-VM verifier orchestration — must
3030        // not be failed here for a resource they never touch. A
3031        // non-root test that does create a cgroup gets the deferred
3032        // setup error pointing at with_walk_root; the operator on-ramp
3033        // is EITHER to run as root OR to set KTSTR_CGROUP_WALK_ROOT to a
3034        // delegated cgroup-v2 subtree (handled by the arm above).
3035        _ => Ok(cg),
3036    }
3037}
3038
3039/// Run a gauntlet variant test. `rest` is `{name}/{preset}`.
3040pub(crate) fn run_gauntlet_test(rest: &str) -> i32 {
3041    let parts: Vec<&str> = rest.splitn(2, '/').collect();
3042    if parts.len() != 2 {
3043        eprintln!("invalid gauntlet test name: gauntlet/{rest}");
3044        return 1;
3045    }
3046    let (test_name, preset_name) = (parts[0], parts[1]);
3047
3048    let entry = match find_test(test_name) {
3049        Some(e) => e,
3050        None => {
3051            eprintln!("unknown test: {test_name}");
3052            return 1;
3053        }
3054    };
3055
3056    let presets = crate::gauntlet::gauntlet_presets();
3057    let preset = match presets.iter().find(|p| p.name == preset_name) {
3058        Some(p) => p,
3059        None => {
3060            eprintln!("unknown gauntlet preset: {preset_name}");
3061            return 1;
3062        }
3063    };
3064
3065    let t = &preset.topology;
3066    let cpus = t.total_cpus();
3067
3068    let memory_mib = super::runtime::derive_test_memory_mib(cpus, entry);
3069    let topo = TopoOverride {
3070        numa_nodes: t.numa_nodes,
3071        llcs: t.llcs,
3072        cores: t.cores_per_llc,
3073        threads: t.threads_per_core,
3074        memory_mib,
3075    };
3076
3077    if entry.performance_mode && super::runtime::no_perf_mode_active() {
3078        crate::report::test_skip(format_args!(
3079            "{}: test requires performance_mode but --no-perf-mode or KTSTR_NO_PERF_MODE is active",
3080            test_name,
3081        ));
3082        // Gauntlet preset: record the preset's RESOLVED topology
3083        // (Topology::from(&topo)) so this skip shares a variant_hash
3084        // with a run of the same preset and distinguishes other presets.
3085        record_skip_sidecar(entry, Some(&topo));
3086        return 0;
3087    }
3088
3089    if super::runtime::perf_only_skips_entry(entry) {
3090        crate::report::test_skip(format_args!(
3091            "{test_name}: KTSTR_PERF_ONLY is active and this test is not a performance_mode test",
3092        ));
3093        // Gauntlet preset: record the preset's RESOLVED topology so the
3094        // skip shares a variant_hash with a run of the same preset.
3095        record_skip_sidecar(entry, Some(&topo));
3096        return 0;
3097    }
3098
3099    if !entry.bpf_map_write.is_empty()
3100        && let Ok(kernel) = resolve_test_kernel()
3101        && crate::vmm::find_vmlinux(&kernel).is_none()
3102    {
3103        eprintln!("FAIL: vmlinux not found, bpf_map_write requires vmlinux");
3104        return 1;
3105    }
3106
3107    let result = run_ktstr_test_inner(entry, Some(&topo));
3108    result_to_exit_code(result, entry.expect_err, entry.allow_inconclusive)
3109}
3110
3111/// Collect sidecar JSON files and return the full gauntlet analysis.
3112///
3113/// When `dir` is `Some`, reads sidecars from that directory. Otherwise
3114/// uses the default sidecar directory (`KTSTR_SIDECAR_DIR` override, or
3115/// `{CARGO_TARGET_DIR or "target"}/ktstr/{kernel}-{project_commit}/`,
3116/// where `{project_commit}` is the project HEAD short hex with
3117/// `-dirty` when the worktree differs).
3118///
3119/// Returns the concatenated output of `analyze_rows`, verifier stats,
3120/// callback profile, and KVM stats. Returns an empty string when no
3121/// sidecars are found.
3122pub fn analyze_sidecars(dir: Option<&std::path::Path>) -> String {
3123    let default_dir;
3124    let dir = match dir {
3125        Some(d) => d,
3126        None => {
3127            default_dir = sidecar_dir();
3128            &default_dir
3129        }
3130    };
3131    let sidecars = collect_sidecars(dir);
3132    if sidecars.is_empty() {
3133        return String::new();
3134    }
3135    let mut out = String::new();
3136    let rows: Vec<_> = sidecars.iter().map(crate::stats::sidecar_to_row).collect();
3137    if !rows.is_empty() {
3138        out.push_str(&crate::stats::analyze_rows(&rows));
3139    }
3140    let vstats = format_verifier_stats(&sidecars);
3141    if !vstats.is_empty() {
3142        out.push_str(&vstats);
3143    }
3144    let cprofile = format_callback_profile(&sidecars);
3145    if !cprofile.is_empty() {
3146        out.push_str(&cprofile);
3147    }
3148    let kstats = format_kvm_stats(&sidecars);
3149    if !kstats.is_empty() {
3150        out.push_str(&kstats);
3151    }
3152    out
3153}
3154
3155/// Discover plain `#[test]` items by re-invoking the binary without
3156/// NEXTEST, reading libtest's `--list` output, and printing only
3157/// names that don't match any KTSTR_TESTS entry. This lets plain
3158/// tests coexist with `#[ktstr_test]` in the same binary without
3159/// duplicating the ktstr entries.
3160///
3161/// `ignored_only` forwards `--ignored` onto the child `--list` call
3162/// so the echoed plain-test set matches the bucket nextest is
3163/// enumerating (all tests vs the `#[ignore]`-only subset). Omitting
3164/// the flag here lands every plain test in nextest's ignored set and
3165/// silently skips them by default — see the body comment.
3166fn list_plain_tests(ignored_only: bool) {
3167    use std::collections::HashSet;
3168    let ktstr_names: HashSet<&str> = KTSTR_TESTS.iter().map(|e| e.name).collect();
3169
3170    let exe = match std::env::current_exe() {
3171        Ok(p) => p,
3172        Err(_) => return,
3173    };
3174    let mut cmd = std::process::Command::new(exe);
3175    cmd.env_remove("NEXTEST");
3176    // Forward `--ignored` so the plain-test set echoed here matches the
3177    // bucket nextest is asking for. nextest computes its "ignored" set by
3178    // re-running the binary with `--list --ignored`; if this child always
3179    // lists ALL plain `#[test]` (no `--ignored`), every plain test lands
3180    // in nextest's ignored set and is silently skipped by default
3181    // (footgun #2). With the flag forwarded, only real `#[ignore]` plain
3182    // tests are reported under `--ignored`, so non-ignored plain tests run
3183    // by default like any other test.
3184    let mut list_args: Vec<&str> = vec!["--list", "--format", "terse"];
3185    if ignored_only {
3186        list_args.push("--ignored");
3187    }
3188    cmd.args(&list_args);
3189    cmd.stdout(std::process::Stdio::piped());
3190    cmd.stderr(std::process::Stdio::null());
3191    let output = match cmd.output() {
3192        Ok(o) => o,
3193        Err(_) => return,
3194    };
3195    let stdout = String::from_utf8_lossy(&output.stdout);
3196    for line in stdout.lines() {
3197        let name = line.strip_suffix(": test").unwrap_or(line);
3198        if !ktstr_names.contains(name) && !name.is_empty() {
3199            println!("{line}");
3200        }
3201    }
3202}
3203
3204/// `--list` subprotocol: emit ktstr/gauntlet test names without
3205/// exiting so the standard libtest harness can also print its own
3206/// test list afterward. This is what makes plain `#[test]` items
3207/// inside a ktstr_test integration-test binary visible to nextest.
3208///
3209/// Honours `--ignored` the same way [`ktstr_main`] does — when set,
3210/// only the ignored subset (gauntlet variants and `demo_` base
3211/// tests) is printed. Unlike `ktstr_main`, this function returns to
3212/// the caller after listing so the ctor's caller can fall through
3213/// to libtest's `main`.
3214fn ktstr_list_only() {
3215    let args: Vec<String> = std::env::args().collect();
3216    let ignored_only = args.iter().any(|a| a == "--ignored");
3217    list_tests(ignored_only);
3218}
3219
3220/// Nextest protocol handler.
3221///
3222/// Called automatically by [`ktstr_test_early_dispatch`] when running
3223/// under nextest with `--exact <ktstr_or_gauntlet_name>`.
3224/// Not intended for direct use.
3225///
3226/// - `--list --format terse`: output `ktstr/{name}: test\n` for VM base
3227///   tests, `host/{name}: test\n` for host-only tests, and
3228///   `gauntlet/{name}/{preset}: test\n` for gauntlet variants. (Discovery
3229///   uses `ktstr_list_only` instead to allow libtest to print its own list
3230///   afterward; this branch is preserved for direct callers of
3231///   `ktstr_main`.)
3232/// - `--exact NAME --nocapture`: run the named test, exit 0/1.
3233pub fn ktstr_main() -> ! {
3234    let args: Vec<String> = std::env::args().collect();
3235
3236    // Discovery mode: --list --format terse [--ignored]
3237    if args.iter().any(|a| a == "--list") {
3238        let ignored_only = args.iter().any(|a| a == "--ignored");
3239        list_tests(ignored_only);
3240        std::process::exit(0);
3241    }
3242
3243    // Execution mode: --exact NAME [--nocapture] [--ignored] [--bench]
3244    if let Some(pos) = args.iter().position(|a| a == "--exact") {
3245        if let Some(name) = args.get(pos + 1) {
3246            let code = run_named_test(name);
3247            std::process::exit(code);
3248        }
3249        eprintln!("--exact requires a test name");
3250        std::process::exit(1);
3251    }
3252
3253    // Fallback: no recognized arguments.
3254    eprintln!("usage: <binary> --list --format terse [--ignored]");
3255    eprintln!("       <binary> --exact <test_name> --nocapture");
3256    std::process::exit(1)
3257}
3258
3259#[cfg(test)]
3260#[path = "dispatch_tests.rs"]
3261mod tests;