ktstr/test_support/
runtime.rs

1//! Runtime configuration primitives shared by `eval` and `probe`.
2//!
3//! `eval` calls `probe::attempt_auto_repro` from its failure path,
4//! so items shared between the two siblings live here to avoid a
5//! circular import chain. All items are `pub(crate)` and remain
6//! internal to `test_support`.
7
8use std::os::unix::fs::PermissionsExt;
9use std::path::{Path, PathBuf};
10use std::sync::OnceLock;
11use std::time::Duration;
12
13use super::entry::KtstrTestEntry;
14
15/// Stable PathBuf for the process-owned config scratch directory.
16///
17/// Populated once by [`scratch_dir`] on first access. Kept in a
18/// separate `OnceLock` from the `TempDir` itself so the `atexit`
19/// cleanup handler can read the path through `extern "C"` without
20/// involving the `tempfile::TempDir` value (whose `Drop` would
21/// otherwise never run — see the "leak bound" note on
22/// [`scratch_dir`]).
23static SCRATCH_PATH: OnceLock<PathBuf> = OnceLock::new();
24
25/// Process-owned scratch directory for all inline-config tempfile
26/// writes — both [`config_content_parts`] (in-VM eval path) and
27/// [`crate::export::export_test`]'s `config_content_addition`
28/// (host-side .run packaging path).
29///
30/// Created lazily on first access via `tempfile::Builder` with
31/// explicit `0o700` mode (overrides the crate default of umask-
32/// restricted `0o777`-via-`mkdir(2)`, which on a standard
33/// `umask=0o022` host yields `0o755` and would expose directory
34/// listings + filename predictability to other uids). The
35/// directory is a random-suffixed subdirectory of
36/// `std::env::temp_dir()`, owned by the current uid.
37///
38/// Both call sites share this single directory because the
39/// security and leak-bound properties are identical for both
40/// purposes, and a single `OnceLock` + single `atexit` handler is
41/// simpler than maintaining parallel scratch dirs that diverge
42/// silently. Filenames are independently prefixed at each call
43/// site (`ktstr-config-{hash:016x}.json` for the eval path,
44/// `ktstr-export-config-{hash:016x}-{basename}` for the export
45/// path) so the two purposes can be visually distinguished inside
46/// the same directory.
47///
48/// Two properties matter:
49///
50/// 1. **Symlink defense.** /tmp is sticky-bit world-writable, so an
51///    attacker can pre-plant a symlink at the predictable content-
52///    addressed path and have us write to wherever it points. A
53///    per-process 0o700 subdirectory blocks every cross-uid access
54///    mode (read, list, write, traverse); only our process can
55///    create or replace files inside it, which eliminates the
56///    symlink-attack surface for the tempfile-write path.
57///
58/// 2. **Leak bound.** Rust does NOT run `Drop` impls on values
59///    stored in `static` slots at process exit — so the
60///    `tempfile::TempDir`'s built-in cleanup would never fire here.
61///    Instead, the path is registered with `libc::atexit`
62///    (POSIX-spec process-exit handler) so a clean exit
63///    (`exit(3)`, fall-off-`main`) triggers
64///    [`std::fs::remove_dir_all`] on the directory. Crash, abort,
65///    SIGKILL, or panic-`abort` skip the atexit handler and leak
66///    the directory; the residual is bounded by the number of
67///    such ungraceful exits and the directory contents are
68///    text-sized config files. The tempdir's random suffix
69///    prevents collisions across runs, so accumulated leak dirs
70///    don't interfere with future runs.
71pub(crate) fn scratch_dir() -> &'static Path {
72    SCRATCH_PATH
73        .get_or_init(|| {
74            let td = tempfile::Builder::new()
75                .prefix("ktstr-config-")
76                .permissions(std::fs::Permissions::from_mode(0o700))
77                .tempdir()
78                .expect("create ktstr config scratch directory");
79            // `keep()` consumes the TempDir without running its
80            // Drop's cleanup (it flips the cleanup flag and returns
81            // the bare PathBuf we own). The atexit registration
82            // below takes over cleanup responsibility.
83            let path = td.keep();
84            // SAFETY: `cleanup_scratch_dir` has the required
85            // `extern "C" fn()` signature that `libc::atexit`
86            // accepts. The `unsafe` block here is required because
87            // `libc::atexit` itself is an `unsafe extern "C"` FFI
88            // call (the callback signature itself is plain
89            // `extern "C" fn()`, not `unsafe`). Registering more
90            // than once is the caller's responsibility;
91            // `OnceLock::get_or_init` guarantees this runs exactly
92            // once per process.
93            let rc = unsafe { libc::atexit(cleanup_scratch_dir) };
94            assert_eq!(
95                rc, 0,
96                "libc::atexit registration for ktstr config scratch dir failed"
97            );
98            path
99        })
100        .as_path()
101}
102
103/// Process-exit handler registered via `libc::atexit` by
104/// [`scratch_dir`] on first init. Removes the scratch directory and
105/// every config file inside it. Errors are ignored — by the time
106/// this runs the process is exiting and there is nowhere to surface
107/// a failure (no `eprintln!` ordering guarantees from inside an
108/// atexit handler, and panicking would be unsound across the C ABI
109/// boundary).
110extern "C" fn cleanup_scratch_dir() {
111    if let Some(path) = SCRATCH_PATH.get() {
112        let _ = std::fs::remove_dir_all(path);
113    }
114}
115
116/// True when `RUST_BACKTRACE` is set to `"1"` or `"full"`.
117///
118/// Controls whether the full guest kernel console is appended to the
119/// `--- diagnostics ---` section of a failed test, and whether
120/// auto-repro forwards the repro VM's COM1/COM2 output to the host
121/// terminal in real time. The scheduler-log and sched_ext-dump
122/// sections of a failure are always emitted regardless of this flag.
123pub(crate) fn verbose() -> bool {
124    std::env::var("RUST_BACKTRACE")
125        .map(|v| v == "1" || v == "full")
126        .unwrap_or(false)
127}
128
129/// True when `KTSTR_NO_PERF_MODE` is set to a NON-EMPTY value.
130///
131/// Centralises the perf-mode-disabled check used by the dispatch
132/// gauntlet routes (`run_named_test`, `run_gauntlet_test`, and the
133/// verifier-cell listing route `list_verifier_cells_all`, all in
134/// `super::dispatch`) and the eval entry path
135/// (`super::eval::run_ktstr_test_inner_impl`). All four sites
136/// previously called `std::env::var("KTSTR_NO_PERF_MODE").is_ok()`
137/// directly, which returned true for `KTSTR_NO_PERF_MODE=` (empty
138/// string set, e.g. via `unset`/`set` interplay in CI shells, or a
139/// `--env KTSTR_NO_PERF_MODE` Docker pass-through with no value) —
140/// silently skipping every `performance_mode` test. Requiring a
141/// non-empty value matches operator intent ("set it to something to
142/// disable perf mode") and rejects the empty-string accident.
143///
144/// `cargo ktstr test --no-perf-mode` exports `KTSTR_NO_PERF_MODE=1`
145/// (a non-empty value), so the existing CLI surface is unaffected.
146pub(crate) fn no_perf_mode_active() -> bool {
147    std::env::var(crate::KTSTR_NO_PERF_MODE_ENV)
148        .map(|v| !v.is_empty())
149        .unwrap_or(false)
150}
151
152/// True when `KTSTR_BYPASS_LLC_LOCKS` is set to a NON-EMPTY value.
153///
154/// Centralises the bypass check used at 7 reader sites:
155/// `vmm/builder.rs:1199`, `cli/kernel_build/build.rs:102` +
156/// `:488` (the latter the inverse `!bypass_llc_locks_active()`
157/// form), `bin/cargo_ktstr/kernel/mod.rs:720`,
158/// `bin/cargo_ktstr/misc/shell.rs:181`, and `bin/ktstr.rs:652` +
159/// `:1267`. All sites previously spelled the same
160/// `.ok().is_some_and(|v| !v.is_empty())` inline; centralising
161/// eliminates the drift hazard and matches the
162/// `no_perf_mode_active` shape so the empty-string contract is
163/// uniformly enforced.
164///
165/// Set via `--bypass-llc-locks` CLI flag or
166/// `KTSTR_BYPASS_LLC_LOCKS=1` direct export. Empty
167/// (`KTSTR_BYPASS_LLC_LOCKS=` from a Docker `--env` pass-through
168/// without value) does NOT activate per the empty-as-unset
169/// contract — preventing a stray export from silently disabling
170/// LLC flock contention enforcement in CI.
171pub fn bypass_llc_locks_active() -> bool {
172    std::env::var(crate::KTSTR_BYPASS_LLC_LOCKS_ENV)
173        .ok()
174        .is_some_and(|v| !v.is_empty())
175}
176
177/// Effective no-perf-mode for a given test entry. The env override
178/// `KTSTR_NO_PERF_MODE` and the per-entry [`KtstrTestEntry::no_perf_mode`]
179/// attribute are OR'd: either source forces the no-perf path
180/// (cpuset/LLC locking still applies, but vCPU pinning, hugepages,
181/// NUMA mbind, RT scheduling, and KVM exit suppression are all
182/// skipped). The env override is the operator-level switch; the
183/// per-entry attribute lets a test author opt the test out
184/// permanently — e.g. tests that exercise wild virtual topologies
185/// the host hardware can't possibly satisfy under perf-mode pinning.
186pub(crate) fn no_perf_mode_for_entry(entry: &KtstrTestEntry) -> bool {
187    no_perf_mode_active() || entry.no_perf_mode
188}
189
190/// True when `KTSTR_PERF_ONLY` is set to a NON-EMPTY value.
191///
192/// Mirrors [`no_perf_mode_active`]'s empty-as-unset contract (see
193/// [`crate::KTSTR_PERF_ONLY_ENV`]): any non-empty value restricts the
194/// run to `performance_mode` tests, an empty value does not.
195/// Consulted at the dispatch named/gauntlet routes and the eval entry
196/// to skip non-perf entries before VM boot. Set by the mergebase
197/// perf-delta subcommand.
198pub(crate) fn perf_only_active() -> bool {
199    std::env::var(crate::KTSTR_PERF_ONLY_ENV)
200        .map(|v| !v.is_empty())
201        .unwrap_or(false)
202}
203
204/// Whether `perf_only_active()` requires SKIPPING this entry: perf-only
205/// mode is on and the entry is not a `performance_mode` test. A
206/// `performance_mode` entry is always kept (it is the selection
207/// target); every other entry is skipped so a perf-delta run measures
208/// only the perf-configured tests.
209pub(crate) fn perf_only_skips_entry(entry: &KtstrTestEntry) -> bool {
210    perf_only_active() && !entry.performance_mode
211}
212
213/// Derive initramfs archive path, host path, and guest path from a
214/// scheduler's static `config_file`. This scheduler-only projection is shared
215/// by ordinary test VMs and generated verifier cells so both launch the same
216/// declaration instead of silently dropping the verifier's config.
217pub(crate) fn scheduler_config_file_parts(
218    scheduler: &super::entry::Scheduler,
219) -> Option<(String, PathBuf, String)> {
220    let config_path = scheduler.config_file?;
221    let file_name = Path::new(config_path)
222        .file_name()
223        .and_then(|n| n.to_str())
224        .expect("config_file must have a valid filename");
225    let archive_path = format!("include-files/{file_name}");
226    let guest_path = format!("/include-files/{file_name}");
227    Some((archive_path, PathBuf::from(config_path), guest_path))
228}
229
230/// Entry-shaped compatibility wrapper for the ordinary test launch paths.
231pub(crate) fn config_file_parts(entry: &KtstrTestEntry) -> Option<(String, PathBuf, String)> {
232    scheduler_config_file_parts(entry.scheduler)
233}
234
235/// Stable u64 hash of arbitrary string content.
236///
237/// Used by the config-content tempfile path code, but suitable for
238/// any content-addressed naming site that needs determinism across
239/// rustc bumps.
240///
241/// Uses `siphasher::sip::SipHasher13::new_with_keys(0, 0)` rather
242/// than `std::collections::hash_map::DefaultHasher` because the std
243/// algorithm is explicitly unspecified across rustc versions (see
244/// workspace `Cargo.toml` for the dep-line rationale). The explicit
245/// `new_with_keys(0, 0)` form matches the project's other
246/// stable-hash sites (`src/test_support/sidecar/mod.rs`, `build.rs`)
247/// so a future audit of zero-keyed SipHasher13 callers finds every
248/// instance via one grep. Same content always produces the same u64
249/// across toolchain upgrades, so cached artifacts stay reproducible
250/// across machines and rustc bumps.
251pub(crate) fn content_hash(content: &str) -> u64 {
252    use std::hash::{Hash, Hasher};
253    let mut hasher = siphasher::sip::SipHasher13::new_with_keys(0, 0);
254    content.hash(&mut hasher);
255    hasher.finish()
256}
257
258/// Resolve inline config content into a temp file on disk, returning
259/// `(archive_path, host_path, guest_path, sched_args)` where
260/// `sched_args` are the CLI args derived from the scheduler's
261/// `config_file_def` arg template. Returns `None` when the entry has
262/// no `config_content`.
263pub(crate) fn config_content_parts(
264    entry: &KtstrTestEntry,
265) -> Option<(String, PathBuf, String, Vec<String>)> {
266    use std::io::Write as _;
267    let content = entry.config_content?;
268    let (arg_template, guest_path) = entry.scheduler.config_file_def?;
269    let archive_path = guest_path.trim_start_matches('/').to_string();
270    let hash = content_hash(content);
271    let dir = scratch_dir();
272    // Write to a uniquely-named scratch file, then atomic-rename to the
273    // canonical content-addressed path:
274    //   - Scratch acquisition via `NamedTempFile::new_in` uses
275    //     `mkstemp(3)` semantics: random suffix, opened O_EXCL so no
276    //     pre-existing file can be subverted as the write target.
277    //   - The atomic `persist` rename is the cross-thread / cross-process
278    //     race fix. Two writers of the same content race their renames
279    //     to the canonical path; the last writer wins, but since `hash`
280    //     is content-addressed both wrote byte-identical content, so the
281    //     winner's bytes match the loser's. No torn writes are possible
282    //     because `rename(2)` is atomic at the inode level — readers
283    //     either see the old inode or the new one, never a partial blend.
284    //   - On panic between `new_in` and `persist`, NamedTempFile's `Drop`
285    //     unlinks the scratch file. No `/tmp` leak from in-process aborts.
286    let canonical = dir.join(format!("ktstr-config-{hash:016x}.json"));
287    let mut scratch =
288        tempfile::NamedTempFile::new_in(dir).expect("create ktstr config scratch file");
289    scratch
290        .as_file_mut()
291        .write_all(content.as_bytes())
292        .expect("write ktstr config content to scratch");
293    scratch
294        .persist(&canonical)
295        .expect("atomic-rename ktstr config scratch to canonical path");
296    let expanded = arg_template.replace("{file}", guest_path);
297    let sched_args: Vec<String> = expanded.split_whitespace().map(|s| s.to_string()).collect();
298    Some((archive_path, canonical, guest_path.to_string(), sched_args))
299}
300
301/// Build the shared `cmdline=` string appended to every ktstr_test
302/// guest boot. Per-scheduler sysctls, per-scheduler kargs,
303/// `RUST_BACKTRACE` / `RUST_LOG` propagation, and the host-resolved
304/// `KTSTR_SIDECAR_DIR` so the guest's `sidecar_dir()` returns the
305/// SAME path the host's freeze coordinator writes to. Without that
306/// propagation, host and guest each compute the run directory
307/// independently — the host walks `gix::discover` from a real
308/// workspace cwd and produces `{kernel}-{commit}` whereas the
309/// guest's cwd is `/` (no git repo, no kernel env), yielding the
310/// `unknown-unknown` fallback. Anything the two VM-launch sites
311/// (`run_ktstr_test_inner` and `attempt_auto_repro`) previously
312/// re-implemented side-by-side lives here.
313/// Ordered guest-kernel cmdline tokens owned by a scheduler declaration.
314///
315/// Keep this projection independent of `KtstrTestEntry`: generated verifier
316/// cells have a scheduler but no test entry, and booting them without these
317/// tokens can change scheduler startup, BPF rodata, and verifier instruction
318/// counts. Sysctls precede raw kargs exactly as on the ordinary test path.
319pub(crate) fn scheduler_cmdline_tokens(scheduler: &super::entry::Scheduler) -> Vec<String> {
320    let mut parts = Vec::new();
321    for s in scheduler.sysctls {
322        parts.push(format!("sysctl.{}={}", s.key(), s.value()));
323    }
324    for &karg in scheduler.kargs {
325        parts.push(karg.to_string());
326    }
327    parts
328}
329
330fn build_cmdline_extra_with_probe_dump_gate(
331    entry: &KtstrTestEntry,
332    include_probe_dump_gate: bool,
333) -> String {
334    let mut parts = scheduler_cmdline_tokens(entry.scheduler);
335    // Framework-owned readiness authority. Scheduler kargs are otherwise
336    // passed through verbatim, but they may neither arm nor disarm this
337    // watchdog-accounting protocol: only the typed test-entry field decides
338    // whether the primary VM emits the exact `=1` token. This also prevents
339    // auto-repro from inheriting a raw scheduler-provided gate.
340    parts.retain(|part| {
341        part != "KTSTR_AWAIT_PROBE_DUMP_READY" && !part.starts_with("KTSTR_AWAIT_PROBE_DUMP_READY=")
342    });
343    // Per-test KASLR opt-out (see `KtstrTestEntry.kaslr` doc). The base
344    // cmdline `base_guest_cmdline` at `src/vmm/setup/mod.rs` does NOT
345    // inject `nokaslr` by default — KASLR is on. A test that needs determinism sets `kaslr = false` in
346    // its `#[ktstr_test]` attribute; that lands the token here, where it
347    // composes with any operator-supplied `Scheduler::kargs(&["nokaslr"])`
348    // above (kernel parses the flag as a bool; duplicates are harmless).
349    // Mirrored guest-side by `vmm::rust_init::create_cgroup_parent_from_sched_args`
350    // and `monitor::symbols::resolve_page_offset`, both of which handle the
351    // `nokaslr` case via the live-publisher fall back to `DEFAULT_PAGE_OFFSET`.
352    if !entry.kaslr {
353        parts.push("nokaslr".to_string());
354    }
355    // Periodic-capture window anchoring: a run that declares periodic
356    // captures gates its FIRST ScenarioStart (which opens the capture
357    // window) on the host's periodic-prereqs-ready signal, so the
358    // window opens over the live workload with the full declared
359    // duration instead of racing the KASLR publish (see
360    // `vmm::rust_init` Phase 5 and `SIGNAL_PERIODIC_READY`). Only
361    // periodic runs pay the wait; non-periodic runs never see the flag.
362    if entry.num_snapshots > 0 {
363        parts.push("KTSTR_AWAIT_PERIODIC_READY=1".to_string());
364    }
365    // Diagnostic scheduler-start gate: only explicitly opted-in tests
366    // pay the host's full probe-counter decode and guest wait. The
367    // host publishes the matching edge only after the exact dump
368    // reader succeeds, so scheduler-relative fault timers start with
369    // the diagnostic substrate already readable.
370    if include_probe_dump_gate && entry.probe_dump_ready_gate {
371        parts.push("KTSTR_AWAIT_PROBE_DUMP_READY=1".to_string());
372    }
373    if let Ok(bt) = std::env::var("RUST_BACKTRACE") {
374        parts.push(format!("RUST_BACKTRACE={bt}"));
375    }
376    if let Ok(log) = std::env::var("RUST_LOG") {
377        parts.push(format!("RUST_LOG={log}"));
378    }
379    // Propagate the host-resolved sidecar dir so the guest scenario
380    // computes the same path the host's freeze coordinator wrote to
381    // (e.g. when a test reads `sidecar_dir().join("foo.json")` from
382    // inside the guest, the path matches the host's writer site).
383    // The host resolves via the OnceLock-cached project commit walk
384    // from the workspace cwd; the guest's cwd is `/` and would
385    // otherwise fall back to `unknown-unknown`. Sidecar dir paths
386    // are filesystem-safe ASCII (kernel version + 7-char hex
387    // commit, optional `-dirty` suffix), so the cmdline-as-token
388    // shape is sound — no escaping needed for whitespace.
389    //
390    // Absolutize via `current_dir().join()` when the resolved path
391    // is relative (the default-branch shape:
392    // `target/ktstr/{kernel}-{commit}` against the host cwd). The
393    // guest's cwd is `/`, so a relative token would resolve there
394    // instead of at the host's workspace root — the propagation
395    // must carry the FULL absolute path so the guest's
396    // `sidecar_dir()` reports the same string the host's writer
397    // site used. Falls back to the raw resolved path when the cwd
398    // probe fails (extremely rare; happens only when the process's
399    // cwd was rmdir'd while alive — a metadata probe has no
400    // recourse, leave the path as-is).
401    let resolved = super::sidecar::sidecar_dir();
402    let absolute = if resolved.is_absolute() {
403        resolved
404    } else {
405        std::env::current_dir()
406            .map(|cwd| cwd.join(&resolved))
407            .unwrap_or(resolved)
408    };
409    if let Some(s) = absolute.to_str() {
410        parts.push(format!("KTSTR_SIDECAR_DIR={s}"));
411    }
412    parts.join(" ")
413}
414
415/// Build the primary VM's cmdline additions.
416///
417/// An explicitly opted-in primary carries the probe-dump readiness gate. Its
418/// guest args also carry the matching minimal probe request; see
419/// `append_primary_probe_dump_arg`.
420pub(crate) fn build_cmdline_extra(entry: &KtstrTestEntry) -> String {
421    build_cmdline_extra_with_probe_dump_gate(entry, true)
422}
423
424/// Build an auto-repro VM's cmdline additions without primary-only launch
425/// gates.
426///
427/// Stall auto-repro intentionally skips probe attachment, so inheriting a
428/// primary cell's probe-dump gate would make guest init wait for an edge the
429/// host can never publish.
430pub(crate) fn build_auto_repro_cmdline_extra(entry: &KtstrTestEntry) -> String {
431    build_cmdline_extra_with_probe_dump_gate(entry, false)
432}
433
434#[cfg(feature = "wprof")]
435pub(crate) fn attach_wprof_if_requested(
436    builder: crate::vmm::KtstrVmBuilder,
437    entry: &KtstrTestEntry,
438    label: &'static str,
439) -> anyhow::Result<crate::vmm::KtstrVmBuilder> {
440    if !entry.wprof {
441        return Ok(builder);
442    }
443    let mut config = crate::vmm::wprof::WprofConfig::from_env().map_err(|e| {
444        anyhow::anyhow!(
445            "ktstr_test: {label}: wprof requested by \
446             #[ktstr_test(wprof)] but WprofConfig::from_env failed: \
447             {e:#}. Ensure cargo-ktstr's install_env exported \
448             KTSTR_WPROF_PATH and the path is readable."
449        )
450    })?;
451    if let Some(custom_args) = entry.wprof_args {
452        config.args = custom_args.split_whitespace().map(String::from).collect();
453    }
454    Ok(builder.wprof(Some(config)))
455}
456
457/// Per-cpu memory-scaling core shared by every VM sizing site.
458///
459/// Returns `(cpus * 64).max(256)` — 64 MiB per vCPU, floored at
460/// 256 MiB. 64 MiB/cpu matches `derive_test_memory_mib`'s established
461/// scaling (it was cut from 256 to 64 MiB/cpu when the compressed
462/// initramfs landed and dropped peak guest memory; commit 5b6063a0);
463/// no per-cpu budget beyond that heuristic is documented.
464///
465/// The returned value is a LOWER BOUND: every call site feeds it to
466/// `.memory_deferred_min(mib)`, which raises the actual allocation to
467/// fit the real initramfs, so the final boot memory may exceed this.
468pub(crate) fn cpu_scaled_memory_mib(cpus: u32) -> u32 {
469    checked_cpu_scaled_memory_mib(cpus)
470        .expect("validated live topology overflows the 64 MiB/vCPU memory floor")
471}
472
473/// Fallible scalar form used when decoding topology dimensions from an ELF.
474pub(crate) fn checked_cpu_scaled_memory_mib(cpus: u32) -> Option<u32> {
475    cpus.checked_mul(64).map(|scaled| scaled.max(256))
476}
477
478/// Memory floor for one verifier topology preset.
479///
480/// Verifier VMs use deferred sizing, so the actual initramfs budget may raise
481/// this floor. The preset budget caps only the topology-derived CPU scaling:
482/// a 252-vCPU synthetic topology must not advertise 16 GiB merely because it
483/// has many vCPUs when the preset explicitly budgets 4 GiB. Small presets keep
484/// the ordinary 64 MiB/vCPU floor.
485pub(crate) fn verifier_preset_memory_min_mib(cpus: u32, preset_memory_mib: usize) -> u32 {
486    checked_verifier_preset_memory_min_mib(cpus, preset_memory_mib)
487        .expect("validated live verifier topology overflows the 64 MiB/vCPU memory floor")
488}
489
490/// Fallible verifier-memory projection for topology data decoded from an ELF.
491pub(crate) fn checked_verifier_preset_memory_min_mib(
492    cpus: u32,
493    preset_memory_mib: usize,
494) -> Option<u32> {
495    let preset_cap = u32::try_from(preset_memory_mib).unwrap_or(u32::MAX);
496    checked_cpu_scaled_memory_mib(cpus).map(|scaled| scaled.min(preset_cap))
497}
498
499/// wprof BPF ringbuf sizing baked into `WprofConfig::default_args`.
500///
501/// wprof allocates `WPROF_DEFAULT_RINGBUF_CNT` BPF ring buffers, each
502/// `--ringbuf-size` KiB rounded up to a power-of-two byte size; the
503/// tracer faults the whole arena in on capture, so guest RAM must
504/// cover it. These two constants are the single source of truth:
505/// `crate::vmm::wprof::WprofConfig::default_args` renders them into
506/// the `--ringbuf-size=`/`--ringbuf-cnt=` flags AND
507/// [`WPROF_MIN_MEMORY_MIB`] derives the guest-memory floor from them,
508/// so changing the sizing here moves the flags and the floor together.
509///
510/// The default is deliberately minimal — a single 16 MiB ring buffer,
511/// which is wprof's own per-buffer default (`DEFAULT_RINGBUF_SZ`) and
512/// comfortably holds the short sched-event captures ktstr's wprof
513/// tests run. ktstr only tests that wprof writes valid data
514/// end-to-end; oversizing merely inflates the per-cell fault-in cost.
515/// Larger captures pass their own `#[ktstr_test(wprof_args = "...")]`
516/// and, if the resulting arena exceeds the guest's normal memory,
517/// their own `memory_mib`.
518pub(crate) const WPROF_DEFAULT_RINGBUF_SIZE_KB: u32 = 16 * 1024;
519pub(crate) const WPROF_DEFAULT_RINGBUF_CNT: u32 = 1;
520
521/// Guest-memory floor (MiB) for a stamped wprof attachment, derived
522/// from the default ringbuf arena above.
523///
524/// Always compiled because the cargo-ktstr admission runner reads a
525/// stamped wprof bit from an ELF built with a different feature set
526/// than its own, so this projection cannot be `wprof`-gated. The
527/// public wprof API remains feature-gated and aliases this value.
528///
529/// At the minimal default the arena (16 MiB) sits below the universal
530/// 256 MiB memory floor from [`cpu_scaled_memory_mib`], so this floor
531/// is subsumed and never bumps a real VM; it re-engages only if the
532/// default ringbuf sizing above ever grows the arena past that floor.
533pub(crate) const WPROF_MIN_MEMORY_MIB: u32 = {
534    let per_rb_bytes = wprof_next_pow2_u64(WPROF_DEFAULT_RINGBUF_SIZE_KB as u64 * 1024);
535    let arena_bytes = per_rb_bytes * WPROF_DEFAULT_RINGBUF_CNT as u64;
536    (arena_bytes / (1024 * 1024)) as u32
537};
538
539/// Round `n` up to the next power of two, mirroring wprof's
540/// `round_pow_of_2` on the ringbuf byte size. `const fn` so the
541/// memory floor is a compile-time constant.
542const fn wprof_next_pow2_u64(n: u64) -> u64 {
543    let mut p: u64 = 1;
544    while p < n {
545        p <<= 1;
546    }
547    p
548}
549
550/// Apply the feature-independent memory floor encoded by a stamped wprof bit.
551pub(crate) fn apply_wprof_memory_floor(raw_mib: u32, wprof: bool) -> u32 {
552    if wprof && raw_mib < WPROF_MIN_MEMORY_MIB {
553        WPROF_MIN_MEMORY_MIB
554    } else {
555        raw_mib
556    }
557}
558
559/// Compute the exact deferred-memory floor from admission-stamp scalars.
560///
561/// This is the process-independent core of [`derive_test_memory_mib`].  The
562/// pre-exec target runner has only the final ELF stamp, not a live
563/// [`KtstrTestEntry`], and must publish the same lower bound before it starts
564/// the heavyweight test process. Keeping the scalar projection here prevents
565/// admission and VM construction from acquiring different memory weights.
566pub(crate) fn derive_test_memory_min_mib(cpus: u32, declared_memory_mib: u32, wprof: bool) -> u32 {
567    checked_derive_test_memory_min_mib(cpus, declared_memory_mib, wprof)
568        .expect("validated live topology overflows the 64 MiB/vCPU memory floor")
569}
570
571/// Fallible admission-memory projection for topology data decoded from an ELF.
572pub(crate) fn checked_derive_test_memory_min_mib(
573    cpus: u32,
574    declared_memory_mib: u32,
575    wprof: bool,
576) -> Option<u32> {
577    let raw = checked_cpu_scaled_memory_mib(cpus)?.max(declared_memory_mib);
578    Some(apply_wprof_memory_floor(raw, wprof))
579}
580
581/// Derive the test VM's memory floor from a CPU count + entry.
582///
583/// Returns `max(cpu_scaled_memory_mib(cpus), entry.memory_mib)`. When
584/// `entry.wprof` is true, bumps to the feature-independent stamped wprof
585/// memory floor if below it. The tracer attachment itself remains gated by
586/// the `wprof` feature.
587///
588/// The returned value is the LOWER BOUND on guest memory; the
589/// VM builder ultimately uses `.memory_deferred_min(mib)` which
590/// also accounts for the initramfs size, so the final boot memory
591/// may exceed this value.
592pub(crate) fn derive_test_memory_mib(cpus: u32, entry: &KtstrTestEntry) -> u32 {
593    let memory_min_mib = derive_test_memory_min_mib(cpus, entry.memory_mib, entry.wprof);
594    #[cfg(feature = "wprof")]
595    {
596        use crate::vmm::wprof::WPROF_MIN_MEMORY_MIB;
597        let raw = cpu_scaled_memory_mib(cpus).max(entry.memory_mib);
598        if memory_min_mib != raw {
599            tracing::info!(
600                test = %entry.name,
601                requested_mib = raw,
602                floored_mib = WPROF_MIN_MEMORY_MIB,
603                "wprof enabled; memory_mib floored to \
604                 WPROF_MIN_MEMORY_MIB"
605            );
606        }
607    }
608    memory_min_mib
609}
610
611/// Resolve the VM topology and memory size from an optional
612/// TopoOverride.
613///
614/// Returns `(topology, memory_mib)` where `topology` is the
615/// `vmm::topology::Topology` passed to the VM builder and `memory_mib`
616/// is the LOWER BOUND on guest memory (the builder's
617/// `.memory_deferred_min(mib)` may raise the actual allocation
618/// to fit the initramfs). When `topo` is `Some`, both come from
619/// the override and the memory is honored verbatim (per the
620/// override-is-verbatim contract — see `topo.rs:42-44`). When
621/// `topo` is `None`, the topology comes from `entry.topology` and
622/// memory is derived by [`derive_test_memory_mib`]. Shared with
623/// `attempt_auto_repro` so the repro VM always sizes memory the
624/// same way as the first VM — reproducibility requires identical
625/// topology, including the wprof floor when applicable.
626///
627/// When the `wprof` feature is enabled and `entry.wprof` is true,
628/// a TopoOverride with memory_mib below the wprof floor triggers
629/// a warn-level log but is still honored verbatim.
630pub(crate) fn resolve_vm_topology(
631    entry: &KtstrTestEntry,
632    topo: Option<&super::topo::TopoOverride>,
633) -> (crate::vmm::topology::Topology, u32) {
634    match topo {
635        Some(t) => {
636            #[cfg(feature = "wprof")]
637            if entry.wprof && t.memory_mib < crate::vmm::wprof::WPROF_MIN_MEMORY_MIB {
638                tracing::warn!(
639                    test = %entry.name,
640                    override_mib = t.memory_mib,
641                    wprof_min_mib = crate::vmm::wprof::WPROF_MIN_MEMORY_MIB,
642                    "wprof enabled with TopoOverride.memory_mib below \
643                     WPROF_MIN_MEMORY_MIB; honoring the override per the \
644                     override-is-verbatim contract, but wprof may OOM-kill \
645                     mid-run"
646                );
647            }
648            (crate::vmm::topology::Topology::from(t), t.memory_mib)
649        }
650        None => {
651            let cpus = entry.topology.total_cpus();
652            let mem = derive_test_memory_mib(cpus, entry);
653            (entry.topology, mem)
654        }
655    }
656}
657
658/// Append per-scheduler `sched_args` entries shared by both VM-launch
659/// paths: `--config <guest_path>` if the scheduler declared one, the
660/// cgroup-parent switch, the scheduler's own fixed args, and
661/// per-entry extra args. Active-flag dispatch and probe-specific args
662/// remain at the call site because they differ between the paths.
663///
664/// The caller owns the `include_files` binding on the builder;
665/// `config_file_parts` and the guest-path push are returned separately
666/// so the caller decides whether to attach include files (production
667/// does, probe-only repro pipelines that already pass `include_files`
668/// can skip it).
669/// Concrete absolute-path example used by the panic messages that
670/// reject malformed `--cell-parent-cgroup` values — names the
671/// scheduler's declared default when one exists, falls back to a
672/// canonical `/ktstr` literal otherwise. The operator gets a
673/// copy-pasteable shape regardless of whether the scheduler is
674/// cell-aware. Centralised so both rejection arms (Value-invalid and
675/// MissingValue) display the same example.
676fn cgroup_parent_example(entry: &KtstrTestEntry) -> String {
677    entry
678        .scheduler
679        .cgroup_parent
680        .map(|p| p.as_str().to_string())
681        .unwrap_or_else(|| "/ktstr".to_string())
682}
683
684pub(crate) fn append_base_sched_args(entry: &KtstrTestEntry, args: &mut Vec<String>) {
685    // Fail-fast on a malformed user-supplied `--cell-parent-cgroup`
686    // value before the auto-inject branch. The host-side consumer
687    // `resolve_cgroup_root` (defined in `test_support::args`, used by
688    // the probe/setup path at `probe.rs::build_dispatch_ctx_parts`)
689    // interpolates the value into a
690    // `/sys/fs/cgroup{path}` literal and hands the result to
691    // `CgroupManager::new`, which has NO host-root guard — any path
692    // that doesn't start with `/` lands inside the host cgroup root
693    // (e.g. `""` → `/sys/fs/cgroup`, `"my_test"` →
694    // `/sys/fs/cgroupmy_test`) and corrupts unrelated cgroup state
695    // when subsequent `cgroups.setup(...)` calls run. The guest-side
696    // sibling `vmm::rust_init::create_cgroup_parent_from_sched_args`
697    // happens to be safe-by-coincidence for the empty case because
698    // `enable_subtree_controllers_to` early-returns when leaf equals
699    // the cgroup root — but probe.rs has no such gate, so the host
700    // fail-fast is what actually protects against corruption.
701    //
702    // The check is universal — independent of whether the scheduler
703    // declares a default `cgroup_parent` — because both routes
704    // (`extra_sched_args` from the test author, `sched_args` from
705    // the scheduler def) flow through the same parse + chain below,
706    // and the corruption risk is identical regardless of who
707    // supplied the bad value. Operator sees the message at test
708    // setup time, before any cgroup ops run.
709    match super::args::parse_cell_parent_cgroup(
710        entry
711            .scheduler
712            .sched_args
713            .iter()
714            .chain(entry.extra_sched_args.iter())
715            .copied(),
716    ) {
717        super::args::CellParentCgroupArg::Value(path)
718            if !super::args::cell_parent_path_is_valid(path) =>
719        {
720            let example = cgroup_parent_example(entry);
721            let mut fixes = format!(
722                "supply an absolute path under `/` with at least one non-`.`/`..` \
723                 segment (e.g. `{example}`) for the per-test cgroup root"
724            );
725            if let Some(default) = entry.scheduler.cgroup_parent {
726                fixes.push_str(&format!(
727                    " or omit the flag entirely (the framework will auto-inject \
728                     the scheduler's default `cgroup_parent = {default}`)"
729                ));
730            }
731            panic!(
732                "test `{}` supplies `--cell-parent-cgroup` with a value `{:?}` \
733                 (via `extra_sched_args` on the test or `sched_args` in the \
734                 scheduler def) that does not start with `/`, is `/` alone, or \
735                 contains `.`/`..` segments that normalize back to the host \
736                 cgroup root; {fixes}. Empty, bare `/`, relative, or paths \
737                 like `/.`, `/foo/..`, `/./bar/..` all resolve to a path \
738                 equal to or inside `/sys/fs/cgroup` (e.g. empty → \
739                 `/sys/fs/cgroup`, `/` → `/sys/fs/cgroup/`, `/.` → \
740                 `/sys/fs/cgroup` after canonicalization) and corrupt \
741                 unrelated cgroup state when the probe-side `CgroupManager` \
742                 operates on the resolved path. This gate mirrors the \
743                 const-eval check in `CgroupPath::new` so runtime values \
744                 share the validation contract that compile-time \
745                 declarations already pass.",
746                entry.name, path,
747            );
748        }
749        super::args::CellParentCgroupArg::MissingValue => {
750            let example = cgroup_parent_example(entry);
751            let mut fixes = format!(
752                "either remove the bare `--cell-parent-cgroup` and let the \
753                 framework auto-inject the scheduler's default (when one is \
754                 declared), or supply a value (e.g. `--cell-parent-cgroup={example}` \
755                 in combined form, or `--cell-parent-cgroup` followed by an \
756                 absolute path in two-token form)"
757            );
758            if entry.scheduler.cgroup_parent.is_none() {
759                fixes.push_str(
760                    "; the scheduler in this test declares no default \
761                     `cgroup_parent`, so an absolute-path value is required",
762                );
763            }
764            panic!(
765                "test `{}` supplies a bare `--cell-parent-cgroup` (via \
766                 `extra_sched_args` on the test or `sched_args` in the \
767                 scheduler def) with no following value; {fixes}. The \
768                 framework intercepts this here because letting it through \
769                 would silently combine with the framework's auto-inject \
770                 (when a default exists) and trip clap's `cannot be used \
771                 multiple times` diagnostic — a confusing error that buries \
772                 the actual missing-value mistake.",
773                entry.name,
774            );
775        }
776        super::args::CellParentCgroupArg::Value(_) => {
777            // User-supplied valid path — flows through the
778            // `args.extend(...)` calls below. Skip the auto-inject so
779            // clap doesn't reject the duplicate flag with `cannot be
780            // used multiple times`.
781        }
782        super::args::CellParentCgroupArg::Absent => {
783            // `cgroup_parent` controls the cgroup root where the
784            // framework places test cgroups (`resolve_cgroup_root`
785            // returns `/sys/fs/cgroup{cgroup_parent}` for guest
786            // CgroupManager). It does NOT auto-inject
787            // `--cell-parent-cgroup` into the scheduler's argv —
788            // cell-aware schedulers (scx_mitosis et al.) interpret
789            // that flag by enabling userspace_managed_cell_mode and
790            // starting an inotify-driven CellManager that can
791            // interfere with the host-side periodic-capture
792            // pipeline. If a scheduler genuinely needs
793            // `--cell-parent-cgroup`, the scheduler declaration's
794            // own `sched_args` array (or the per-test
795            // `extra_sched_args`) must include it explicitly. The
796            // guest-side `create_cgroup_parent_from_sched_args`
797            // mkdir + subtree-controller setup still fires when
798            // `--cell-parent-cgroup` is present in `/sched_args` —
799            // it's gated on the flag's presence, not on whether the
800            // framework injected it vs. the user added it manually.
801        }
802    }
803    args.extend(entry.scheduler.sched_args.iter().map(|s| s.to_string()));
804    args.extend(entry.extra_sched_args.iter().map(|s| s.to_string()));
805}
806
807/// Retry budget for the guest's `vmm::rust_init::send_sys_rdy_with_retry`
808/// loop. Boot-to-readiness wall time is a fixed base PLUS per-vCPU
809/// work: the virtio-console multiport handshake (DEVICE_READY →
810/// PORT_ADD → PORT_READY → PORT_OPEN per `drivers/char/virtio_console.c`)
811/// issues per-CPU work whose wall time grows roughly linearly with
812/// topology size, on top of a fixed device-enumeration / first-CPU
813/// cost. The budget is therefore ADDITIVE — `BASE_MS + vcpus *
814/// PER_VCPU_MS` — not `max(BASE, scaled)`.
815///
816/// The earlier `max` form left the per-vCPU term dead below ~67 vCPUs
817/// (since `vcpus * 150` only clears the 10 s floor at 67 vCPUs), so a
818/// 64-vCPU VM got the same 10 s budget as a 1-vCPU VM. Under host
819/// contention a 64-vCPU handshake was observed at ~10 s and timed out
820/// by ~8 ms — the disk-template gauntlet flake. The additive base
821/// gives every topology ~10 s of fixed headroom on top of its linear
822/// per-vCPU term (64 vCPUs → 19.6 s), so a slow handshake under load
823/// no longer races the floor.
824///
825/// Capped at 90 s as a sanity bound on a genuinely-stuck boot's
826/// guest-side retry loop — NOT to protect the host watchdog. The
827/// watchdog deadline IS derived from this budget ([`vm_boot_headroom`]
828/// feeds [`vm_timeout_from_entry`]), so the budget can never "blow" a
829/// deadline it defines; the old 30 s cap's stated rationale was
830/// inverted. That 30 s cap truncated the additive term above
831/// ~133 vCPUs — a 256-vCPU guest wants `10_000 + 256×150 = 48_400` ms
832/// but was clamped to 30_000 ms, starving the widest topologies of
833/// boot budget exactly where overcommit makes the boot slowest (the
834/// wide-SMP boot-timeout class). 90 s admits the full additive budget
835/// up to the 512-vCPU `MAX_VCPUS` (`10_000 + 512×150 = 86_800` ms);
836/// only pathological counts above 533 vCPUs clip.
837///
838/// The const-fn signature lets both the host (`vm_boot_headroom`,
839/// `vm_timeout_from_entry`) and the guest (`vmm::rust_init`) compute
840/// the same budget without trans-VM coordination — the guest reads
841/// its own vCPU count from `/sys/devices/system/cpu/online`. The guest
842/// uses this UN-scaled budget (it cannot read host overcommit); on an
843/// oversubscribed boot its `send_sys_rdy_with_retry` loop may exhaust
844/// and WARN, but that is non-fatal (the host monitor's `data_valid`
845/// gate keeps reads safe). The host's [`vm_timeout_from_entry`] is the
846/// Tier-3 dead-man deadline this budget feeds; it multiplies the
847/// headroom by a flat [`DEADMAN_HEADROOM_MULT`] and no longer scales by
848/// the host overcommit ratio — the progress watchdog's Tier-1/2 rules,
849/// not the wall deadline, now absorb an oversubscribed host.
850pub(crate) const fn sys_rdy_budget_ms(vcpus: u32) -> u64 {
851    const BASE_MS: u64 = 10_000;
852    const CAP_MS: u64 = 90_000;
853    const PER_VCPU_MS: u64 = 150;
854    let scaled = (vcpus as u64).saturating_mul(PER_VCPU_MS);
855    let total = BASE_MS.saturating_add(scaled);
856    if total > CAP_MS { CAP_MS } else { total }
857}
858
859/// Headroom for kernel init, scheduler attach, and BPF verifier time
860/// — the post-sys_rdy phase of guest startup. Distinct from
861/// [`sys_rdy_budget_ms`]'s base + per-vCPU budget (the pre-sys_rdy
862/// virtio-console handshake budget); the two add together to form
863/// the full [`vm_boot_headroom`].
864const KERNEL_INIT_HEADROOM_MS: u64 = 10_000;
865
866/// The authoritative boot allowance in milliseconds. Kept as a const
867/// integer helper so the wall-clock VM deadline and the progress
868/// watchdog's Boot CPU budget consume the same contract instead of
869/// maintaining independently calibrated width formulas.
870pub(crate) const fn vm_boot_headroom_ms(vcpus: u32) -> u64 {
871    KERNEL_INIT_HEADROOM_MS.saturating_add(sys_rdy_budget_ms(vcpus))
872}
873
874/// Total boot headroom: covers kernel init + scheduler attach + BPF
875/// verifier time ([`KERNEL_INIT_HEADROOM_MS`]) plus the guest's scaled
876/// `send_sys_rdy` retry loop ([`sys_rdy_budget_ms`]) before the
877/// workload phase begins. Scales with vCPU count so the host timeout
878/// doesn't fire while the guest is still inside its sys_rdy budget.
879pub(crate) fn vm_boot_headroom(vcpus: u32) -> Duration {
880    Duration::from_millis(vm_boot_headroom_ms(vcpus))
881}
882
883/// Per-phase CPU-time budget (nanoseconds) charged against a single
884/// lifecycle phase before the progress watchdog's Tier-1 rule
885/// (`vmm::freeze_coord::watchdog_step`) treats "CPU burned without
886/// progress" as a wedge. `phase` is the [`crate::monitor::LifecycleStage`]
887/// discriminant (Boot=0, Attach=1, Dispatch=2, Body=3, Teardown=4);
888/// this fn is deliberately phrased over the raw `u8` so it carries no
889/// dependency on that enum and stays testable in isolation.
890///
891/// Tier-1's evidence is the MAX per-vCPU CPU burned in-phase (the monitor's
892/// `max_vcpu_cpu_in_phase_ns`), not the SUM across vCPUs. A spinning wedge
893/// is one (or a few) hot thread(s), so the sound budget is what a SINGLE
894/// vCPU may legitimately burn in the phase — a per-vCPU-linear budget
895/// against a summed evidence was the wide-SMP false-kill bug (256 idle
896/// vCPUs summed ~141 s of diffuse background burn and crossed a 64 s
897/// budget with zero wedge).
898///
899/// Boot is the deliberate exception to otherwise width-independent
900/// per-vCPU budgets. The BSP serially enumerates and initializes every AP,
901/// so the busiest-vCPU signal contains legitimate O(vCPU-count) work even
902/// though the signal itself is a MAX rather than a SUM. Its budget reuses
903/// [`vm_boot_headroom_ms`], the existing semantic allowance that already
904/// governs kernel init, scheduler attach, BPF verification, and the
905/// vCPU-scaled sys-rdy handshake. This keeps one source of truth for a
906/// healthy boot instead of fitting another base-plus-slope formula to
907/// whichever wide distro image happened to fail last. The pthread
908/// currency widening is applied by the watchdog on top.
909///
910/// Every other phase stays flat because its legitimate busiest-vCPU work
911/// does not scale with guest width:
912///   - Attach (35 s): single-threaded BPF load + verifier time dominates
913///     and lands on one vCPU; host-side cold-BTF/vmlinux waits accrue NO
914///     guest CPU (the guest is blocked, not spinning), so even a cold
915///     parse under host-compile contention leaves the max per-vCPU burn
916///     well under this.
917///   - Dispatch (8 s): the probe's first-dispatch warm-up on the busiest
918///     worker vCPU; 8 s is generous for a single vCPU reaching first
919///     dispatch.
920///   - Body (`u64::MAX`): the workload phase has no CPU-time budget — a
921///     body test is *supposed* to burn CPU, so Tier-1 is structurally
922///     disabled here via this sentinel (the watchdog never charges a CPU
923///     budget it can exceed). Body wedges are caught by the existing
924///     deadline logic, not Tier-1.
925///   - Teardown (8 s): unwind / dump / VM-exit on the busiest vCPU.
926///
927/// Unknown phases (>4) return `u64::MAX` — an id this fn does not model
928/// must never be killed on a CPU budget it cannot justify. The pthread
929/// currency's 3/2 widening (`widen_budget_for_currency`) still applies on
930/// top of these in the watchdog.
931pub(crate) const fn phase_cpu_budget_ns(phase: u8, vcpus: u32) -> u64 {
932    const S_TO_NS: u64 = 1_000_000_000;
933    match phase {
934        // Boot: share the authoritative boot-headroom contract.
935        0 => vm_boot_headroom_ms(vcpus).saturating_mul(1_000_000),
936        // Attach
937        1 => 35u64.saturating_mul(S_TO_NS),
938        // Dispatch
939        2 => 8u64.saturating_mul(S_TO_NS),
940        // Body — Tier-1 off (see doc).
941        3 => u64::MAX,
942        // Teardown
943        4 => 8u64.saturating_mul(S_TO_NS),
944        // Unknown phase → never kill.
945        _ => u64::MAX,
946    }
947}
948
949/// Per-phase WALL-time backstop (nanoseconds) for the progress
950/// watchdog's Tier-2 rule (`vmm::freeze_coord::watchdog_step`): the
951/// fully-quiesced idle-wedge case where a phase has made no progress for
952/// this long *and* the guest shows no runnable demand. Distinct from the
953/// CPU budget above — this is wall clock, so it fires when a phase is
954/// stuck making no forward progress regardless of whether CPU is being
955/// burned (a spinning wedge is Tier-1's; a *silent* wedge is Tier-2's).
956///
957/// Each backstop is set STRICTLY ABOVE the existing wall budget that
958/// governs the same phase, so Tier-2 is a last-resort backstop that only
959/// fires after the phase's own in-band deadline has already had its
960/// chance — never a competing, earlier kill:
961///   - Boot: at least 45s and always 5s above
962///     [`vm_boot_headroom_ms`]. A genuinely silent boot (no epochs,
963///     no demand) past this is wedged, not merely slow.
964///   - Attach 40s: above [`COLD_BTF_PHASE1_BUDGET`] (30s) — the host's
965///     own cold-BTF accessor-build deadline — plus slack, so a slow but
966///     live BTF parse is never mistaken for a silent attach wedge.
967///   - Dispatch 35s: above the guest probe's `DISPATCH_DEADLINE_CAP`
968///     (30s, `vmm::rust_init::verifier_workload`), so the probe verdict
969///     — not Tier-2 — decides a live-but-slow dispatch.
970///   - Teardown 15s: a short backstop; teardown that makes no progress
971///     for this long with no demand is stuck unwinding.
972///   - Body (`u64::MAX`): the workload phase has no wall backstop —
973///     Tier-2 is structurally off for Body via this sentinel (a body
974///     test may legitimately sit quiescent; its deadline is the
975///     authoritative bound).
976///
977/// Unknown phases (>4) return `u64::MAX` — never kill on a wall backstop
978/// this fn does not model.
979pub(crate) const fn phase_wall_backstop_ns(phase: u8, vcpus: u32) -> u64 {
980    const S_TO_NS: u64 = 1_000_000_000;
981    const MS_TO_NS: u64 = 1_000_000;
982    let s = match phase {
983        // Boot is width-sensitive. Preserve the historical 45s floor for
984        // small guests while keeping Tier-2 strictly after the authoritative
985        // boot allowance for wide guests.
986        0 => {
987            let scaled_ms = vm_boot_headroom_ms(vcpus).saturating_add(5_000);
988            let backstop_ms = if scaled_ms > 45_000 {
989                scaled_ms
990            } else {
991                45_000
992            };
993            return backstop_ms.saturating_mul(MS_TO_NS);
994        }
995        // Attach — > COLD_BTF_PHASE1_BUDGET (30s).
996        1 => 40u64,
997        // Dispatch — > guest DISPATCH_DEADLINE_CAP (30s).
998        2 => 35u64,
999        // Body — Tier-2 off (see doc).
1000        3 => return u64::MAX,
1001        // Teardown
1002        4 => 15u64,
1003        // Unknown phase → never kill.
1004        _ => return u64::MAX,
1005    };
1006    s.saturating_mul(S_TO_NS)
1007}
1008
1009/// Worst-case host-side latency the guest's `wait_for_map_write` latch
1010/// blocks on before a `bpf_map_write` test's workload runs: the host
1011/// builds the BPF-map accessor (ELF + BTF parse + symbol HashMap, ~4 s
1012/// on a debug vmlinux per the freeze-coord accessor-init comment) in a
1013/// retry loop bounded by a 30 s `phase1_deadline`. Under heavy `-j16`
1014/// host-compile contention the parse scales and a cold vmlinux read adds
1015/// seconds, so the latch can block up to that deadline. Added to the
1016/// workload budget for any entry declaring a `bpf_map_write` — a
1017/// framework cost every such test pays, not a per-test concern the
1018/// author must remember to budget for.
1019const COLD_BTF_PHASE1_BUDGET: Duration = Duration::from_secs(30);
1020
1021/// Oversubscription ratio at or beyond which a default/no-perf (auto)
1022/// overcommit is SKIPPED rather than booted. Above it the host
1023/// time-slices the vCPU threads so heavily the boot cannot make forward
1024/// progress, so the dispatch
1025/// (`run_ktstr_test_inner_impl`) skips with a "host topology
1026/// insufficient" signal instead of hard-failing. Set above the 4× the
1027/// `cpu_budget` overcommit tests deliberately exercise (those carry an
1028/// explicit `cpu_budget`, so they are NOT auto-collapse and never skip
1029/// on this ratio) and far above the ~1.3× a 256-vCPU guest hits on a
1030/// 192-CPU CI runner — which therefore RUNS and validates wide-SMP boot
1031/// rather than skipping, so the boot invariant is never masked.
1032pub(crate) const OVERCOMMIT_SKIP_RATIO: f64 = 6.0;
1033
1034/// Flat multiplier on the vCPU-scaled [`vm_boot_headroom`] term of the
1035/// Tier-3 dead-man deadline ([`vm_timeout_from_entry`] and
1036/// [`verifier_vm_timeout`]). The approved ~2.5x rounded up to an
1037/// integer — integer math, and the extra generosity is free here.
1038///
1039/// This is NOT a timeout bump. The progress watchdog's Tier-1
1040/// (CPU-burned-without-progress) and Tier-2 (silent idle-wedge) rules in
1041/// `vmm::freeze_coord::watchdog_step` are the primary hang
1042/// detectors for INFRA phases: a wedge dies on those tiers inside a bounded
1043/// per-phase budget no matter how loose this deadline is. Tier-3 owns the
1044/// remaining degradation paths: dead monitoring, an inert cell, and an
1045/// active Body livelock after it burns the whole effective-deadline
1046/// busiest-vCPU budget. The CPU backstop, like Tier-1, stretches with host
1047/// starvation; no wall-clock oversub multiplier is needed. A flat generous
1048/// headroom factor therefore suffices for the deadline itself.
1049const DEADMAN_HEADROOM_MULT: u32 = 3;
1050
1051/// Stricter skip ratio for the `expect_auto_repro` chain. That inversion
1052/// boots a SECOND wide-SMP VM which must replay the forced failure and land
1053/// a shape-valid `.repro.wprof.pb` — a far more fragile path under host
1054/// time-slicing than a single boot: the repro VM's system-wide wprof
1055/// capture over hundreds of vCPUs stops reliably producing a transportable
1056/// trace once the host oversubscribes (the boots themselves still finish
1057/// inside the Tier-3 dead-man deadline; the trace transport is what breaks).
1058/// So this chain auto-skips well below the generic [`OVERCOMMIT_SKIP_RATIO`],
1059/// while single-VM wide-SMP BOOT tests keep running (and validating boot) up
1060/// to the generic cap. Tuned to sit between the ~1.3x a 256-vCPU guest hits
1061/// on the 192-CPU wide-SMP design-target runner (which still RUNS the
1062/// auto-repro hop, so it is validated there) and the ~2.7x of a 96-CPU host
1063/// (which skips cleanly instead of hard-failing — the "overcommit OR
1064/// auto-skip, never hard-fail" contract).
1065pub(crate) const EXPECT_AUTO_REPRO_SKIP_RATIO: f64 = 2.0;
1066
1067/// Host overcommit ratio for a `vcpus`-wide guest given the host's
1068/// allowed-CPU count and the test's optional explicit `cpu_budget`:
1069/// vCPUs divided by the host CPUs the vCPU threads actually land on.
1070/// With an explicit `cpu_budget` the threads collapse onto
1071/// `min(cpu_budget, allowed)` (the per-test cap); without one the
1072/// default/no-perf path collapses onto the whole allowed cpuset
1073/// (`no_perf_cpu_budget`'s `(vcpus + 1).min(allowed)` clamp when
1074/// `allowed < vcpus + 1`, else a fitting 1:1 pin). Under
1075/// `KTSTR_CARGO_TEST_MODE` the planner ignores the explicit budget and
1076/// masks to the full allowed cpuset, so with a `cpu_budget` the
1077/// returned ratio is an UPPER bound there (CI runs `cargo ktstr test`
1078/// with that mode OFF, where the budget IS enforced and the ratio is
1079/// exact). Floored at 1.0 (a fitting host is never under-subscribed) and
1080/// divide-by-zero-guarded (an unenumerable cpuset yields 1.0).
1081///
1082/// Feeds only the boot-or-skip gate ([`overcommit_skip_reason`]) and the
1083/// operator overcommit warning — NOT the Tier-3 dead-man deadline, which
1084/// no longer scales with this ratio (the progress watchdog's Tier-1/2
1085/// rules absorb a loaded host). Pure over `(vcpus, allowed_cpus,
1086/// cpu_budget)` so the skip boundary is unit-testable without reading the
1087/// host cpuset.
1088pub(crate) fn overcommit_ratio(vcpus: u32, allowed_cpus: usize, cpu_budget: Option<u32>) -> f64 {
1089    let allowed = allowed_cpus.max(1);
1090    let effective = match cpu_budget {
1091        Some(b) => (b as usize).min(allowed),
1092        None => allowed,
1093    }
1094    .max(1);
1095    (vcpus as f64 / effective as f64).max(1.0)
1096}
1097
1098/// Reason to auto-skip an over-oversubscribed default/no-perf run, or
1099/// `None` to run it. The default/no-perf path collapses the vCPU threads
1100/// onto the allowed cpuset (`build_overcommit_run_locks` /
1101/// `no_perf_cpu_budget`); at or beyond [`OVERCOMMIT_SKIP_RATIO`] the host
1102/// time-slices so hard the boot cannot make forward progress, so the
1103/// dispatch
1104/// (`run_ktstr_test_inner_impl`) skips with this reason — the "overcommit
1105/// OR auto-skip, never hard-fail" contract. Returns `None` (runs) for:
1106/// the fitting / mildly-oversubscribed case (< the ratio, e.g. a 256-vCPU
1107/// guest at ~1.3x on a 192-CPU CI runner, so wide-SMP boot is VALIDATED
1108/// there, never masked); an explicit `cpu_budget` (a deliberate
1109/// oversubscription opt-in for contention testing always runs, its deeper
1110/// ratio being the author's choice); and an empty (unenumerable) cpuset
1111/// (no ratio is computable, so the overcommit warning is the sole
1112/// signal). Pure over `(vcpus, allowed_cpus, cpu_budget)` so the skip
1113/// boundary is unit-testable without booting a VM.
1114pub(crate) fn overcommit_skip_reason(
1115    vcpus: u32,
1116    allowed_cpus: usize,
1117    cpu_budget: Option<u32>,
1118    expect_auto_repro: bool,
1119) -> Option<String> {
1120    if cpu_budget.is_some() || allowed_cpus == 0 {
1121        return None;
1122    }
1123    let oversub = overcommit_ratio(vcpus, allowed_cpus, None);
1124    // The two-VM expect_auto_repro inversion uses a much stricter cap
1125    // ([`EXPECT_AUTO_REPRO_SKIP_RATIO`]) than a single-VM boot test: its
1126    // repro-VM wprof-trace transport is fragile under time-slicing, so it
1127    // skips at an oversubscription a boot-only wide-SMP test still runs at.
1128    let skip_ratio = if expect_auto_repro {
1129        EXPECT_AUTO_REPRO_SKIP_RATIO
1130    } else {
1131        OVERCOMMIT_SKIP_RATIO
1132    };
1133    if oversub < skip_ratio {
1134        return None;
1135    }
1136    let chain = if expect_auto_repro {
1137        " for the expect_auto_repro inversion chain"
1138    } else {
1139        ""
1140    };
1141    Some(format!(
1142        "host topology insufficient: {vcpus} vCPUs auto-collapse onto \
1143         {allowed_cpus} allowed host CPUs = {oversub:.1}x oversubscription \
1144         (>= {skip_ratio:.0}x skip cap{chain}); widen the process cpuset \
1145         or shrink the guest topology"
1146    ))
1147}
1148
1149/// Derive the host-side VM timeout from the test entry's watchdog and
1150/// duration. This is the watchdog's TIER-3 dead-man's switch — the
1151/// generous wall-clock backstop, NOT the primary hang detector. The
1152/// primary detectors are the progress watchdog's Tier-1
1153/// (CPU-burned-without-progress) and Tier-2 (silent idle-wedge) rules in
1154/// `vmm::freeze_coord::watchdog_step`: a wedge dies on those
1155/// tiers inside a bounded per-phase budget. Tier-3 also owns a dead
1156/// monitor, an inert cell, and an active Body livelock after it consumes
1157/// the whole effective-deadline busiest-vCPU CPU budget; that last bound
1158/// remains dilation-immune because a starved cell accrues CPU slowly.
1159///
1160/// Shape: `base + vm_boot_headroom(booted_vcpus) * DEADMAN_HEADROOM_MULT`.
1161/// The vCPU-scaled boot headroom covers a slow boot on a large topology;
1162/// the flat [`DEADMAN_HEADROOM_MULT`] makes it generous. This is NOT a
1163/// timeout bump and does NOT scale with the host overcommit ratio — the
1164/// old oversub multiplier existed to stop wall-clock false-timeouts on a
1165/// loaded host, a job Tier-1/2 now own, so a flat generous factor
1166/// replaces it (and the overcommit-scaling machinery is retired from this
1167/// path). `base` is the guest's own workload/watchdog budget:
1168/// [`COLD_BTF_PHASE1_BUDGET`] is added when the entry declares a
1169/// `bpf_map_write` (the guest blocks on the host's cold-BTF accessor
1170/// build before the workload starts), and
1171/// [`crate::vmm::freeze_coord::WPROF_SHIP_GRACE`] when it declares
1172/// `wprof` (a crashing scheduler's late Phase-5 trace ship is held for
1173/// that window before teardown). The soft (reset) deadline rides this
1174/// Tier-3 value via `max(reset, hard_deadline)`.
1175///
1176/// `booted_vcpus` is the vCPU count of the topology the VM actually
1177/// boots (`resolve_vm_topology(entry, topo).0.total_cpus()`), NOT the
1178/// declared `entry.topology`: under a `TopoOverride` (gauntlet preset /
1179/// `--ktstr-topo`) they diverge, and the vCPU-scaled boot headroom must
1180/// scale to the topology that boots — otherwise the deadline is sized for
1181/// a smaller-than-booted preset.
1182pub(crate) fn vm_timeout_from_entry(
1183    entry: &super::entry::KtstrTestEntry,
1184    booted_vcpus: u32,
1185) -> Duration {
1186    let mut base = entry
1187        .watchdog_timeout
1188        .max(entry.duration)
1189        .max(Duration::from_secs(1));
1190    if !entry.bpf_map_write.is_empty() {
1191        base += COLD_BTF_PHASE1_BUDGET;
1192    }
1193    // A wprof entry's scheduler may crash; on an error-class exit the
1194    // freeze coordinator holds the VM open up to `WPROF_SHIP_GRACE` for
1195    // the guest's late Phase-5 wprof trace ship before killing. Add that
1196    // window to the host budget so a late crash's full ship grace fits
1197    // inside the watchdog deadline (mirrors COLD_BTF_PHASE1_BUDGET).
1198    if entry.wprof {
1199        base += crate::vmm::freeze_coord::WPROF_SHIP_GRACE;
1200    }
1201    base + vm_boot_headroom(booted_vcpus) * DEADMAN_HEADROOM_MULT
1202}
1203
1204/// Base host-side budget for a verifier sweep cell's guest lifecycle
1205/// past boot: scheduler spawn, BPF load/verify, attach gate, the
1206/// dispatch probe, and teardown. The boot phase is budgeted
1207/// separately by the vCPU-scaled dead-man headroom in
1208/// [`verifier_vm_timeout`], mirroring [`vm_timeout_from_entry`]'s
1209/// base-vs-headroom split.
1210pub(crate) const VERIFIER_BASE_TIMEOUT: Duration = Duration::from_secs(120);
1211
1212/// Post-attach budget for a verifier cell, wired into the builder's
1213/// `workload_duration` so the watchdog's scheduler-attach reset arms:
1214/// a cell whose boot ate most of the deadline still gets this much
1215/// wall time AFTER attach for the dispatch probe + teardown (the
1216/// reset is extend-only — `max(reset, hard_deadline)`). Sized above
1217/// the guest probe's `DISPATCH_DEADLINE_CAP` (30s, see
1218/// `vmm::rust_init::verifier_workload`) plus teardown/dump slack.
1219/// Before this, verifier cells passed no `workload_duration` at all,
1220/// which made the attach-reset dead code on the sweep path — the
1221/// watchdog dump always read `reset_armed_by=none`.
1222pub(crate) const VERIFIER_WORKLOAD_BUDGET: Duration = Duration::from_secs(60);
1223
1224/// Host-side VM timeout for a verifier sweep cell: the flat
1225/// [`VERIFIER_BASE_TIMEOUT`] plus the same vCPU-scaled dead-man boot
1226/// headroom the `#[ktstr_test]` path gets from [`vm_timeout_from_entry`]
1227/// — its Tier-3 backstop, not the primary hang detector (Tier-1/2 in
1228/// `vmm::freeze_coord::watchdog_step` own that). The sweep
1229/// previously hard-coded 120s with no headroom at all, so a
1230/// wide-topology cell (128 vCPUs) that boots fine but slowly under CI
1231/// concurrency was killed mid-attach — reported by the scx verifier
1232/// sweep as a VM timeout (now worded "hung with no confirmed scheduler
1233/// attach" for that shape).
1234pub(crate) fn verifier_vm_timeout(booted_vcpus: u32) -> Duration {
1235    VERIFIER_BASE_TIMEOUT + vm_boot_headroom(booted_vcpus) * DEADMAN_HEADROOM_MULT
1236}
1237
1238/// Configure the ktstr_test VM builder prefix shared by the main
1239/// test path ([`super::eval::run_ktstr_test_inner`]) and the
1240/// auto-repro path ([`super::probe::attempt_auto_repro`]).
1241///
1242/// Applies, in order: kernel, init binary, topology, memory floor,
1243/// guest cmdline, SHM size, guest argv, host-side timeout, perf-mode
1244/// disable flag, optional scheduler binary, every queued BPF map
1245/// write, and the scheduler watchdog timeout.
1246///
1247/// The caller owns the divergent tail. `run_ktstr_test_inner`
1248/// additionally wires `performance_mode`,
1249/// `sched_enable_cmds`/`sched_disable_cmds` for kernel-built
1250/// schedulers, and `monitor_thresholds`. `attempt_auto_repro`
1251/// additionally wires `include_files` plus base `sched_args`.
1252#[allow(clippy::too_many_arguments)]
1253pub(crate) fn build_vm_builder_base(
1254    entry: &KtstrTestEntry,
1255    kernel: &Path,
1256    ktstr_bin: &Path,
1257    scheduler: Option<&Path>,
1258    staged_schedulers: &[(String, std::path::PathBuf, Vec<String>)],
1259    vm_topology: crate::vmm::topology::Topology,
1260    memory_mib: u32,
1261    cmdline_extra: &str,
1262    guest_args: &[String],
1263    no_perf_mode: bool,
1264) -> crate::vmm::KtstrVmBuilder {
1265    // The base builder deliberately does NOT set
1266    // `failure_dump_path` — the per-VM target is caller-specific
1267    // (primary vs auto-repro). Stale-file pre-clear lives at the
1268    // dispatch sites (`test_support::eval` for primary;
1269    // `test_support::probe::attempt_auto_repro` for repro), not
1270    // inside the setter or this base call. The setter is pure
1271    // (no FS side effects); placing the pre-clear in the dispatch
1272    // layer prevents the auto-repro path's reuse of this base
1273    // builder from accidentally erasing the primary dump that
1274    // just landed.
1275    let mut builder = crate::vmm::KtstrVm::builder()
1276        .kernel(kernel)
1277        // Prebuilt distro kernels ship virtio as modules; embed the
1278        // ordered boot-module set from the cache entry beside the image
1279        // (empty for built kernels — a no-op).
1280        .kernel_modules(crate::cache::boot_modules_for_image(kernel))
1281        .initrd_compression(crate::cache::initrd_compression_for_image(kernel))
1282        .init_binary(ktstr_bin)
1283        .topology(vm_topology)
1284        .memory_deferred_min(memory_mib)
1285        .cmdline(cmdline_extra)
1286        .run_args(guest_args)
1287        .timeout(vm_timeout_from_entry(entry, vm_topology.total_cpus()))
1288        .workload_duration(entry.duration)
1289        .no_perf_mode(no_perf_mode);
1290
1291    // Per-test no-perf CPU budget override (#[ktstr_test(cpu_budget = N)]).
1292    // None leaves the builder's auto-size (vCPU count plus one service CPU,
1293    // clamped to the allowed cpuset) in place; only the no-perf path consumes it.
1294    if let Some(budget) = entry.cpu_budget {
1295        builder = builder.cpu_budget(budget);
1296    }
1297
1298    if let Some(sched_path) = scheduler {
1299        builder = builder.scheduler_binary(sched_path);
1300    }
1301
1302    // Push each pre-resolved staged scheduler into the builder's
1303    // staging set. Caller is responsible for running each entry
1304    // through resolve_scheduler so this fn stays
1305    // infallible (sibling to the boot-time `scheduler: Option<&Path>`
1306    // shape which is also caller-resolved). KernelBuiltin / Eevdf
1307    // staged entries (no binary to resolve) are skipped at the
1308    // caller side; only resolved (name, host_binary, sched_args)
1309    // tuples reach this loop.
1310    for (name, host_path, sched_args) in staged_schedulers {
1311        builder = builder.staged_scheduler(name.clone(), host_path.clone(), sched_args.clone());
1312    }
1313
1314    // Opt-in jemalloc-probe wiring. An integration test that needs
1315    // the probe (see `tests/jemalloc_probe_tests.rs`) sets
1316    // `KTSTR_JEMALLOC_PROBE_BINARY` to the absolute host path of
1317    // `ktstr-jemalloc-probe` via `#[ctor]` before the test harness
1318    // dispatches. When set, the probe is packed into every VM's
1319    // base initramfs; the init binary stays stripped because the
1320    // paired alloc-worker carries DWARF. Absent env var = existing
1321    // behavior (no probe).
1322    //
1323    // Required ctor shape in a new test file that needs the probe
1324    // in the guest — paste verbatim, adjust the two binary names.
1325    // Either ctor form works (ktstr re-exports both): the proc-macro
1326    // attribute shown below, or the declarative
1327    // `::ktstr::__private::ctor::declarative::ctor! { ... }` block
1328    // form (ktstr's own in-tree sites use the declarative form per
1329    // src/test_support/dispatch.rs).
1330    //
1331    // ```ignore
1332    // #[::ktstr::__private::ctor::ctor(unsafe, crate_path = ::ktstr::__private::ctor)]
1333    // fn set_probe_binary_env_var() {
1334    //     // SAFETY: ctor runs before any `#[ktstr_test]` thread or
1335    //     // probe thread spawns; glibc's `__environ` mutation is
1336    //     // single-threaded here.
1337    //     unsafe {
1338    //         std::env::set_var(
1339    //             ::ktstr::KTSTR_JEMALLOC_PROBE_BINARY_ENV,
1340    //             env!("CARGO_BIN_EXE_ktstr-jemalloc-probe"),
1341    //         );
1342    //         std::env::set_var(
1343    //             ::ktstr::KTSTR_JEMALLOC_ALLOC_WORKER_BINARY_ENV,
1344    //             env!("CARGO_BIN_EXE_ktstr-jemalloc-alloc-worker"),
1345    //         );
1346    //     }
1347    // }
1348    // ```
1349    //
1350    // Declarative-form equivalent (no `crate_path = ` plumbing required
1351    // because the macro_rules! expansion resolves paths via `$crate`):
1352    //
1353    // ```ignore
1354    // ::ktstr::__private::ctor::declarative::ctor! {
1355    // #[ctor(unsafe)]
1356    // fn set_probe_binary_env_var() {
1357    //     // SAFETY: same as proc-macro form above.
1358    //     unsafe {
1359    //         std::env::set_var(
1360    //             ::ktstr::KTSTR_JEMALLOC_PROBE_BINARY_ENV,
1361    //             env!("CARGO_BIN_EXE_ktstr-jemalloc-probe"),
1362    //         );
1363    //         std::env::set_var(
1364    //             ::ktstr::KTSTR_JEMALLOC_ALLOC_WORKER_BINARY_ENV,
1365    //             env!("CARGO_BIN_EXE_ktstr-jemalloc-alloc-worker"),
1366    //         );
1367    //     }
1368    // }
1369    // }
1370    // ```
1371    //
1372    // The `crate_path = ::ktstr::__private::ctor` argument is
1373    // non-negotiable: `#[ctor::ctor(unsafe)]` without the
1374    // re-export path panics at compile time because the `ctor`
1375    // crate is not listed in the test crate's direct deps. ktstr
1376    // re-exports `ctor` under `__private::ctor` exactly so test
1377    // authors do not need to add it themselves. ctor 1.0 also
1378    // mandates the `unsafe` marker as the first attribute
1379    // argument; bare `#[ctor::ctor]` no longer compiles.
1380    if let Ok(probe_path) = std::env::var(crate::KTSTR_JEMALLOC_PROBE_BINARY_ENV)
1381        && !probe_path.is_empty()
1382    {
1383        // Pack the probe binary into the guest initramfs at
1384        // `/bin/ktstr-jemalloc-probe`. Closed-loop probe tests run
1385        // the probe via `--pid <alloc_worker_pid>` against the
1386        // paired `ktstr-jemalloc-alloc-worker` target; DWARF comes
1387        // from the worker's own ELF, not the init's.
1388        builder = builder.jemalloc_probe_binary(std::path::PathBuf::from(probe_path));
1389    }
1390    if let Ok(worker_path) = std::env::var(crate::KTSTR_JEMALLOC_ALLOC_WORKER_BINARY_ENV)
1391        && !worker_path.is_empty()
1392    {
1393        // Pack the jemalloc-alloc-worker binary alongside the
1394        // probe. Only the cross-process closed-loop test sets
1395        // this; scheduler-only tests leave the env var unset and
1396        // skip the wiring.
1397        builder = builder.jemalloc_alloc_worker_binary(std::path::PathBuf::from(worker_path));
1398    }
1399
1400    for bpf_write in entry.bpf_map_write {
1401        builder = builder.bpf_map_write(
1402            bpf_write.map_name_suffix(),
1403            bpf_write.field(),
1404            bpf_write.value(),
1405        );
1406    }
1407
1408    for watch in entry.watch_bpf_maps {
1409        builder = builder.watch_bpf_map(
1410            watch.map_name_suffix(),
1411            watch.field(),
1412            watch.agg(),
1413            watch.label(),
1414        );
1415    }
1416
1417    if let Some(disk_cfg) = entry.disk.clone() {
1418        builder = builder.disk(disk_cfg);
1419    }
1420
1421    for net_cfg in entry.networks {
1422        builder = builder.network(*net_cfg);
1423    }
1424
1425    builder = builder.num_snapshots(entry.num_snapshots);
1426
1427    if let Some(root) = entry.workload_root_cgroup {
1428        builder = builder.workload_root_cgroup(root.as_str().to_string());
1429    }
1430    if let Some(parent) = entry.scheduler.cgroup_parent {
1431        builder = builder.scheduler_cgroup_parent(parent.as_str().to_string());
1432    }
1433
1434    builder.watchdog_timeout(entry.watchdog_timeout)
1435}
1436
1437#[cfg(test)]
1438mod tests {
1439    use super::super::entry::Scheduler;
1440    use super::super::test_helpers::{EnvVarGuard, lock_env};
1441    use super::*;
1442
1443    #[test]
1444    fn vm_timeout_from_entry_adds_cold_btf_budget_for_bpf_map_write() {
1445        use super::super::entry::{BpfMapWrite, KtstrTestEntry};
1446        static W: BpfMapWrite = BpfMapWrite::new(".bss", "crash", 0);
1447        static WS: &[&BpfMapWrite] = &[&W];
1448        let no_write = KtstrTestEntry {
1449            name: "no_write",
1450            ..KtstrTestEntry::DEFAULT
1451        };
1452        let with_write = KtstrTestEntry {
1453            name: "with_write",
1454            bpf_map_write: WS,
1455            ..KtstrTestEntry::DEFAULT
1456        };
1457        // The cold-BTF phase-1 budget is added to the workload base only
1458        // when the entry declares a host-side bpf_map_write; the delta
1459        // between an otherwise-identical pair is exactly that budget.
1460        assert_eq!(
1461            vm_timeout_from_entry(&with_write, with_write.topology.total_cpus()),
1462            vm_timeout_from_entry(&no_write, no_write.topology.total_cpus())
1463                + COLD_BTF_PHASE1_BUDGET,
1464            "bpf_map_write entries get the cold-BTF phase-1 budget added",
1465        );
1466    }
1467
1468    #[test]
1469    fn no_perf_mode_active_true_when_env_set_to_value() {
1470        let _l = lock_env();
1471        let _g = EnvVarGuard::set(crate::KTSTR_NO_PERF_MODE_ENV, "1");
1472        assert!(no_perf_mode_active());
1473    }
1474
1475    #[test]
1476    fn no_perf_mode_active_false_when_env_unset() {
1477        let _l = lock_env();
1478        let _g = EnvVarGuard::remove(crate::KTSTR_NO_PERF_MODE_ENV);
1479        assert!(!no_perf_mode_active());
1480    }
1481
1482    /// Regression pin: empty-string-as-unset contract. Before the
1483    /// env-var-sweep cleanup, the bare `is_ok()` reader returned
1484    /// true on
1485    /// `KTSTR_NO_PERF_MODE=` (set but empty — e.g. Docker
1486    /// `--env KTSTR_NO_PERF_MODE` pass-through fired without a
1487    /// value), silently flipping perf-mode OFF for every
1488    /// `performance_mode` test. The fix at L146 treats
1489    /// empty-as-unset; this test pins that contract for ALL
1490    /// consumer sites (shell-mode VM at lib.rs, verifier at
1491    /// verifier.rs, dispatch + eval) since they all route
1492    /// through this helper.
1493    #[test]
1494    fn no_perf_mode_active_false_when_env_set_to_empty_string() {
1495        let _l = lock_env();
1496        let _g = EnvVarGuard::set(crate::KTSTR_NO_PERF_MODE_ENV, "");
1497        assert!(
1498            !no_perf_mode_active(),
1499            "empty-string env must be treated as UNSET — a regression \
1500             here flips perf-mode for every consumer that routes \
1501             through no_perf_mode_active",
1502        );
1503    }
1504
1505    #[test]
1506    fn perf_only_active_true_when_env_set_to_value() {
1507        let _l = lock_env();
1508        let _g = EnvVarGuard::set(crate::KTSTR_PERF_ONLY_ENV, "1");
1509        assert!(perf_only_active());
1510    }
1511
1512    #[test]
1513    fn perf_only_active_false_when_env_unset() {
1514        let _l = lock_env();
1515        let _g = EnvVarGuard::remove(crate::KTSTR_PERF_ONLY_ENV);
1516        assert!(!perf_only_active());
1517    }
1518
1519    /// Empty-as-unset contract (mirrors `no_perf_mode_active`): a
1520    /// `KTSTR_PERF_ONLY=` pass-through must NOT silently skip every
1521    /// non-perf test.
1522    #[test]
1523    fn perf_only_active_false_when_env_set_to_empty_string() {
1524        let _l = lock_env();
1525        let _g = EnvVarGuard::set(crate::KTSTR_PERF_ONLY_ENV, "");
1526        assert!(
1527            !perf_only_active(),
1528            "empty-string env must be treated as UNSET",
1529        );
1530    }
1531
1532    /// Selection logic: with perf-only active, a non-performance_mode
1533    /// entry is skipped while a performance_mode entry is kept. When
1534    /// perf-only is inactive, neither is skipped.
1535    #[test]
1536    fn perf_only_skips_entry_keeps_perf_skips_others() {
1537        use super::super::entry::KtstrTestEntry;
1538        let perf = KtstrTestEntry {
1539            name: "perf",
1540            performance_mode: true,
1541            ..KtstrTestEntry::DEFAULT
1542        };
1543        let plain = KtstrTestEntry {
1544            name: "plain",
1545            performance_mode: false,
1546            ..KtstrTestEntry::DEFAULT
1547        };
1548
1549        let _l = lock_env();
1550        {
1551            let _g = EnvVarGuard::set(crate::KTSTR_PERF_ONLY_ENV, "1");
1552            assert!(
1553                !perf_only_skips_entry(&perf),
1554                "a performance_mode test is the selection target, never skipped",
1555            );
1556            assert!(
1557                perf_only_skips_entry(&plain),
1558                "a non-performance_mode test must be skipped under perf-only",
1559            );
1560        }
1561        let _g = EnvVarGuard::remove(crate::KTSTR_PERF_ONLY_ENV);
1562        assert!(!perf_only_skips_entry(&perf));
1563        assert!(
1564            !perf_only_skips_entry(&plain),
1565            "perf-only inactive => nothing is skipped on this axis",
1566        );
1567    }
1568
1569    #[test]
1570    fn bypass_llc_locks_active_true_when_env_set_to_value() {
1571        let _l = lock_env();
1572        let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "1");
1573        assert!(bypass_llc_locks_active());
1574    }
1575
1576    #[test]
1577    fn bypass_llc_locks_active_false_when_env_unset() {
1578        let _l = lock_env();
1579        let _g = EnvVarGuard::remove(crate::KTSTR_BYPASS_LLC_LOCKS_ENV);
1580        assert!(!bypass_llc_locks_active());
1581    }
1582
1583    /// Regression pin: empty-string-as-unset contract for
1584    /// KTSTR_BYPASS_LLC_LOCKS. A bare `KTSTR_BYPASS_LLC_LOCKS=`
1585    /// (CI shell / Docker `--env` pass-through without value)
1586    /// must NOT activate the bypass. The helper enforces this
1587    /// uniformly for all 7 reader sites (vmm/builder.rs,
1588    /// cli/kernel_build/build.rs ×2, bin/ktstr.rs ×2,
1589    /// bin/cargo_ktstr/{kernel/mod, misc/shell}) — a regression
1590    /// here flips the contention contract for every caller.
1591    #[test]
1592    fn bypass_llc_locks_active_false_when_env_set_to_empty_string() {
1593        let _l = lock_env();
1594        let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "");
1595        assert!(
1596            !bypass_llc_locks_active(),
1597            "empty-string env must be treated as UNSET per the contract \
1598             shared with no_perf_mode_active — a regression here flips \
1599             LLC flock contention enforcement for every reader",
1600        );
1601    }
1602
1603    #[test]
1604    fn config_file_parts_nested_path() {
1605        static SCHED: Scheduler = Scheduler::named("cfg").config_file("configs/my_sched.toml");
1606        let entry = KtstrTestEntry {
1607            name: "cfg_test",
1608            scheduler: &SCHED,
1609            ..KtstrTestEntry::DEFAULT
1610        };
1611        let (archive, host, guest) = config_file_parts(&entry).unwrap();
1612        assert_eq!(archive, "include-files/my_sched.toml");
1613        assert_eq!(host, PathBuf::from("configs/my_sched.toml"));
1614        assert_eq!(guest, "/include-files/my_sched.toml");
1615    }
1616
1617    #[test]
1618    fn config_file_parts_bare_filename() {
1619        static SCHED: Scheduler = Scheduler::named("cfg").config_file("config.toml");
1620        let entry = KtstrTestEntry {
1621            name: "cfg_bare",
1622            scheduler: &SCHED,
1623            ..KtstrTestEntry::DEFAULT
1624        };
1625        let (archive, host, guest) = config_file_parts(&entry).unwrap();
1626        assert_eq!(archive, "include-files/config.toml");
1627        assert_eq!(host, PathBuf::from("config.toml"));
1628        assert_eq!(guest, "/include-files/config.toml");
1629    }
1630
1631    #[test]
1632    fn config_file_parts_none_when_unset() {
1633        let entry = KtstrTestEntry {
1634            name: "no_cfg",
1635            ..KtstrTestEntry::DEFAULT
1636        };
1637        assert!(config_file_parts(&entry).is_none());
1638    }
1639
1640    // -- build_cmdline_extra --
1641
1642    use super::super::entry::{KtstrTestEntry, Sysctl};
1643
1644    #[test]
1645    fn build_cmdline_extra_default_is_sidecar_only() {
1646        let _lock = lock_env();
1647        // Make sure the env does not inject spurious RUST_BACKTRACE /
1648        // RUST_LOG entries that would break the default assertion.
1649        let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1650        let _env_log = EnvVarGuard::remove("RUST_LOG");
1651        // Pin KTSTR_SIDECAR_DIR so the propagation token shape is
1652        // stable across tests; without the override, the call falls
1653        // through to the `{kernel}-{commit}` resolver whose output
1654        // depends on the test process's git state.
1655        let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1656
1657        let entry = KtstrTestEntry {
1658            name: "cmdline_test",
1659            ..KtstrTestEntry::DEFAULT
1660        };
1661        let out = build_cmdline_extra(&entry);
1662        assert_eq!(out, "KTSTR_SIDECAR_DIR=/tmp/ktstr-test");
1663    }
1664
1665    #[test]
1666    fn build_cmdline_extra_appends_sysctls_kargs() {
1667        let _lock = lock_env();
1668        let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1669        let _env_log = EnvVarGuard::remove("RUST_LOG");
1670        let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1671
1672        static SYSCTLS: &[Sysctl] = &[Sysctl::new("kernel.foo", "1")];
1673        static SCHED: Scheduler = Scheduler::named("s").sysctls(SYSCTLS).kargs(&["quiet"]);
1674        let entry = KtstrTestEntry {
1675            name: "cmd",
1676            scheduler: &SCHED,
1677            ..KtstrTestEntry::DEFAULT
1678        };
1679        let out = build_cmdline_extra(&entry);
1680        assert_eq!(
1681            out,
1682            "sysctl.kernel.foo=1 quiet KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1683        );
1684    }
1685
1686    #[test]
1687    fn build_cmdline_extra_emits_probe_dump_gate_only_when_opted_in() {
1688        let _lock = lock_env();
1689        let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1690        let _env_log = EnvVarGuard::remove("RUST_LOG");
1691        let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1692
1693        let default = KtstrTestEntry {
1694            name: "probe_dump_gate_default",
1695            ..KtstrTestEntry::DEFAULT
1696        };
1697        assert!(
1698            !build_cmdline_extra(&default).contains("KTSTR_AWAIT_PROBE_DUMP_READY"),
1699            "the default path must not pay the probe-dump readiness gate"
1700        );
1701
1702        let opted_in = KtstrTestEntry {
1703            name: "probe_dump_gate_enabled",
1704            probe_dump_ready_gate: true,
1705            ..KtstrTestEntry::DEFAULT
1706        };
1707        assert_eq!(
1708            build_cmdline_extra(&opted_in),
1709            "KTSTR_AWAIT_PROBE_DUMP_READY=1 KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1710        );
1711    }
1712
1713    #[test]
1714    fn build_auto_repro_cmdline_extra_omits_primary_probe_dump_gate() {
1715        let _lock = lock_env();
1716        let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1717        let _env_log = EnvVarGuard::remove("RUST_LOG");
1718        let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1719
1720        let opted_in = KtstrTestEntry {
1721            name: "probe_dump_gate_auto_repro",
1722            probe_dump_ready_gate: true,
1723            ..KtstrTestEntry::DEFAULT
1724        };
1725        assert_eq!(
1726            build_auto_repro_cmdline_extra(&opted_in),
1727            "KTSTR_SIDECAR_DIR=/tmp/ktstr-test",
1728            "auto-repro must not inherit the primary-only probe-dump gate"
1729        );
1730    }
1731
1732    #[test]
1733    fn scheduler_kargs_cannot_forge_or_disable_probe_dump_gate() {
1734        let _lock = lock_env();
1735        let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1736        let _env_log = EnvVarGuard::remove("RUST_LOG");
1737        let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1738
1739        static SCHED: Scheduler = Scheduler::named("probe-gate-kargs").kargs(&[
1740            "quiet",
1741            "KTSTR_AWAIT_PROBE_DUMP_READY=0",
1742            "KTSTR_AWAIT_PROBE_DUMP_READY=1",
1743        ]);
1744        let disabled = KtstrTestEntry {
1745            name: "probe_gate_kargs_disabled",
1746            scheduler: &SCHED,
1747            ..KtstrTestEntry::DEFAULT
1748        };
1749        assert_eq!(
1750            build_cmdline_extra(&disabled),
1751            "quiet KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1752        );
1753
1754        let enabled = KtstrTestEntry {
1755            name: "probe_gate_kargs_enabled",
1756            scheduler: &SCHED,
1757            probe_dump_ready_gate: true,
1758            ..KtstrTestEntry::DEFAULT
1759        };
1760        let primary = build_cmdline_extra(&enabled);
1761        assert_eq!(
1762            primary,
1763            "quiet KTSTR_AWAIT_PROBE_DUMP_READY=1 KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1764        );
1765        assert_eq!(
1766            primary
1767                .split_ascii_whitespace()
1768                .filter(|token| *token == "KTSTR_AWAIT_PROBE_DUMP_READY=1")
1769                .count(),
1770            1
1771        );
1772        assert_eq!(
1773            build_auto_repro_cmdline_extra(&enabled),
1774            "quiet KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1775        );
1776    }
1777
1778    #[test]
1779    fn build_cmdline_extra_propagates_rust_env() {
1780        let _lock = lock_env();
1781        let _env_bt = EnvVarGuard::set("RUST_BACKTRACE", "1");
1782        let _env_log = EnvVarGuard::set("RUST_LOG", "debug");
1783        let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1784
1785        let entry = KtstrTestEntry {
1786            name: "cmd",
1787            ..KtstrTestEntry::DEFAULT
1788        };
1789        let out = build_cmdline_extra(&entry);
1790        assert!(
1791            out.contains("RUST_BACKTRACE=1"),
1792            "expected RUST_BACKTRACE propagation: {out}"
1793        );
1794        assert!(
1795            out.contains("RUST_LOG=debug"),
1796            "expected RUST_LOG propagation: {out}"
1797        );
1798        assert!(
1799            out.contains("KTSTR_SIDECAR_DIR=/tmp/ktstr-test"),
1800            "expected KTSTR_SIDECAR_DIR propagation: {out}"
1801        );
1802    }
1803
1804    #[test]
1805    fn build_cmdline_extra_propagates_sidecar_dir() {
1806        let _lock = lock_env();
1807        let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1808        let _env_log = EnvVarGuard::remove("RUST_LOG");
1809        // Explicit override path proves the token shape is exactly
1810        // `KTSTR_SIDECAR_DIR=<path>` and uses the override verbatim
1811        // (host's `sidecar_dir()` honours the env var as the
1812        // operator-chosen override slot).
1813        let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/explicit/sidecar/dir");
1814
1815        let entry = KtstrTestEntry {
1816            name: "cmd",
1817            ..KtstrTestEntry::DEFAULT
1818        };
1819        let out = build_cmdline_extra(&entry);
1820        assert_eq!(out, "KTSTR_SIDECAR_DIR=/explicit/sidecar/dir");
1821    }
1822
1823    // -- resolve_vm_topology --
1824
1825    #[test]
1826    fn resolve_vm_topology_override_is_verbatim() {
1827        let entry = KtstrTestEntry {
1828            name: "topo_test",
1829            ..KtstrTestEntry::DEFAULT
1830        };
1831        let over = super::super::topo::TopoOverride {
1832            numa_nodes: 2,
1833            llcs: 4,
1834            cores: 8,
1835            threads: 2,
1836            memory_mib: 4096,
1837        };
1838        let (topo, mem) = resolve_vm_topology(&entry, Some(&over));
1839        assert_eq!(mem, 4096);
1840        assert_eq!(topo.llcs, 4);
1841        assert_eq!(topo.cores_per_llc, 8);
1842        assert_eq!(topo.threads_per_core, 2);
1843        assert_eq!(topo.numa_nodes, 2);
1844    }
1845
1846    #[test]
1847    fn resolve_vm_topology_default_memory_can_stay_below_two_gib() {
1848        // The default topology has two vCPUs, so cpu scaling yields
1849        // 128 MiB and the framework-wide 256-MiB floor wins. This
1850        // specifically guards against restoring a stale multi-GiB
1851        // entry default that would defeat deferred payload sizing.
1852        let entry = KtstrTestEntry {
1853            name: "tiny",
1854            ..KtstrTestEntry::DEFAULT
1855        };
1856        let (_topo, mem) = resolve_vm_topology(&entry, None);
1857        assert_eq!(mem, 256, "memory floor = 256 MiB, got {mem}");
1858        assert!(mem < 2048, "default memory must not pin every VM at 2 GiB");
1859    }
1860
1861    #[test]
1862    fn resolve_vm_topology_none_honors_entry_memory_mib() {
1863        // Entry with explicit memory_mib above the cpu*64 and 256 floors.
1864        let entry = KtstrTestEntry {
1865            name: "mem",
1866            memory_mib: 1536,
1867            ..KtstrTestEntry::DEFAULT
1868        };
1869        let (_topo, mem) = resolve_vm_topology(&entry, None);
1870        assert_eq!(
1871            mem, 1536,
1872            "a real explicit override must win even when it is not the old 2-GiB default"
1873        );
1874    }
1875
1876    #[cfg(feature = "wprof")]
1877    #[test]
1878    fn resolve_vm_topology_wprof_does_not_oversize_at_minimal_default() {
1879        // wprof=true with the minimal default arena must NOT oversize:
1880        // the derived wprof floor (16 MiB) is below the entry's own
1881        // memory, so the entry-derived path sizes the VM exactly like
1882        // the same non-wprof entry. Guards against restoring a
1883        // multi-GiB wprof floor that pinned every wprof cell high.
1884        let entry = KtstrTestEntry {
1885            name: "wprof_minimal",
1886            memory_mib: 512,
1887            wprof: true,
1888            ..KtstrTestEntry::DEFAULT
1889        };
1890        // Compile-time invariant: at the minimal default the wprof
1891        // floor stays at/under the universal 256 MiB floor, so it is
1892        // subsumed and cannot oversize a VM.
1893        const { assert!(crate::vmm::wprof::WPROF_MIN_MEMORY_MIB <= 256) };
1894        let (_topo, mem) = resolve_vm_topology(&entry, None);
1895        assert_eq!(
1896            mem, 512,
1897            "wprof must not oversize past the entry's own 512 MiB; got {mem}"
1898        );
1899    }
1900
1901    #[cfg(feature = "wprof")]
1902    #[test]
1903    fn resolve_vm_topology_wprof_no_bump_when_already_above_floor() {
1904        // Entry already above the wprof floor — must be honored unchanged.
1905        let entry = KtstrTestEntry {
1906            name: "wprof_high",
1907            memory_mib: 8192,
1908            wprof: true,
1909            ..KtstrTestEntry::DEFAULT
1910        };
1911        let (_topo, mem) = resolve_vm_topology(&entry, None);
1912        assert_eq!(
1913            mem, 8192,
1914            "memory_mib above WPROF_MIN_MEMORY_MIB must be honored \
1915             unchanged, got {mem}"
1916        );
1917    }
1918
1919    #[test]
1920    fn resolve_vm_topology_wprof_disabled_does_not_floor() {
1921        // wprof=false: the wprof floor must NOT apply, even when
1922        // entry.memory_mib falls below WPROF_MIN_MEMORY_MIB. Only
1923        // the universal 256 floor + cpu*64 derivation apply.
1924        let entry = KtstrTestEntry {
1925            name: "no_wprof",
1926            memory_mib: 512,
1927            wprof: false,
1928            ..KtstrTestEntry::DEFAULT
1929        };
1930        let (_topo, mem) = resolve_vm_topology(&entry, None);
1931        assert_eq!(
1932            mem, 512,
1933            "wprof=false must not invoke the WPROF_MIN_MEMORY_MIB \
1934             floor, got {mem}"
1935        );
1936    }
1937
1938    #[test]
1939    fn derive_test_memory_mib_baseline_without_wprof() {
1940        let entry = KtstrTestEntry {
1941            name: "baseline",
1942            ..KtstrTestEntry::DEFAULT
1943        };
1944        let mem = derive_test_memory_mib(2, &entry);
1945        assert_eq!(mem, 256, "2 cpus * 64 = 128, floor 256 wins");
1946        assert_eq!(
1947            derive_test_memory_min_mib(2, entry.memory_mib, entry.wprof),
1948            mem,
1949            "the admission-stamp scalar projection must equal entry-based VM sizing",
1950        );
1951    }
1952
1953    #[test]
1954    fn cpu_scaled_memory_mib_scales_and_floors() {
1955        // Shared scaling core used by both derive_test_memory_mib and
1956        // the verifier cell. Below the crossover (256/64 = 4 cpus) the
1957        // 256 MiB floor wins; at/above it the 64 MiB/cpu term wins.
1958        assert_eq!(cpu_scaled_memory_mib(1), 256, "1 cpu * 64 = 64, floor 256");
1959        assert_eq!(cpu_scaled_memory_mib(4), 256, "4 cpus * 64 = 256, tie");
1960        assert_eq!(cpu_scaled_memory_mib(8), 512, "8 cpus * 64 = 512 wins");
1961        assert_eq!(cpu_scaled_memory_mib(16), 1024, "16 cpus * 64 = 1024 wins");
1962    }
1963
1964    #[test]
1965    fn stamped_wprof_memory_floor_is_feature_independent() {
1966        // The floor is applied by value, not by cfg!(feature = "wprof"):
1967        // a below-floor raw is bumped, an at/above-floor raw passes
1968        // through — identically whether or not the reader binary was
1969        // built with wprof.
1970        assert_eq!(
1971            apply_wprof_memory_floor(WPROF_MIN_MEMORY_MIB - 1, true),
1972            WPROF_MIN_MEMORY_MIB,
1973            "a raw below the derived floor must be bumped up to it",
1974        );
1975        assert_eq!(
1976            apply_wprof_memory_floor(WPROF_MIN_MEMORY_MIB, true),
1977            WPROF_MIN_MEMORY_MIB,
1978            "a raw at the floor passes through (strict-less-than)",
1979        );
1980        assert_eq!(apply_wprof_memory_floor(4096, true), 4096);
1981        assert_eq!(apply_wprof_memory_floor(4096, false), 4096);
1982        // At the minimal default arena the floor (16 MiB) is far below
1983        // the universal 256 MiB floor, so admission sizing is dominated
1984        // by the latter regardless of the wprof bit — the whole point
1985        // of the minimal default is that wprof no longer oversizes.
1986        assert_eq!(derive_test_memory_min_mib(2, 768, true), 768);
1987        assert_eq!(derive_test_memory_min_mib(2, 768, false), 768);
1988    }
1989
1990    #[test]
1991    fn checked_admission_memory_scaling_rejects_overflow() {
1992        assert_eq!(checked_cpu_scaled_memory_mib(u32::MAX), None);
1993        assert_eq!(
1994            checked_derive_test_memory_min_mib(u32::MAX, 256, false),
1995            None
1996        );
1997        assert_eq!(checked_verifier_preset_memory_min_mib(u32::MAX, 4096), None);
1998    }
1999
2000    #[test]
2001    fn verifier_preset_memory_caps_synthetic_cpu_scaling() {
2002        assert_eq!(verifier_preset_memory_min_mib(4, 2048), 256);
2003        assert_eq!(verifier_preset_memory_min_mib(32, 2048), 2048);
2004        assert_eq!(verifier_preset_memory_min_mib(64, 2048), 2048);
2005        assert_eq!(verifier_preset_memory_min_mib(252, 4096), 4096);
2006    }
2007
2008    #[test]
2009    fn cpu_scaled_memory_mib_backs_derive_test_memory_mib() {
2010        // The entry-aware wrapper must reduce to the shared core when no
2011        // per-entry override raises it — the invariant that lets the
2012        // direct verifier API reuse cpu_scaled_memory_mib directly.
2013        let entry = KtstrTestEntry {
2014            name: "shared",
2015            ..KtstrTestEntry::DEFAULT
2016        };
2017        for cpus in [1u32, 4, 8, 32] {
2018            assert_eq!(
2019                derive_test_memory_mib(cpus, &entry),
2020                cpu_scaled_memory_mib(cpus),
2021                "derive_test_memory_mib must equal the shared core for \
2022                 {cpus} cpus when the entry uses the framework minimum"
2023            );
2024        }
2025    }
2026
2027    #[cfg(feature = "wprof")]
2028    #[test]
2029    fn resolve_vm_topology_wprof_universal_floor_dominates_tiny_arena() {
2030        // With the minimal default arena the wprof floor is far below
2031        // the universal 256 MiB floor, so the latter dominates even
2032        // when the entry declares exactly WPROF_MIN_MEMORY_MIB. The
2033        // strict-less-than direction of the floor condition itself is
2034        // pinned directly in `stamped_wprof_memory_floor_is_feature_independent`.
2035        let entry = KtstrTestEntry {
2036            name: "wprof_exact",
2037            memory_mib: crate::vmm::wprof::WPROF_MIN_MEMORY_MIB,
2038            wprof: true,
2039            ..KtstrTestEntry::DEFAULT
2040        };
2041        let (_topo, mem) = resolve_vm_topology(&entry, None);
2042        assert_eq!(
2043            mem, 256,
2044            "universal 256 MiB floor dominates the tiny wprof arena; got {mem}"
2045        );
2046    }
2047
2048    #[cfg(feature = "wprof")]
2049    #[test]
2050    fn resolve_vm_topology_wprof_zero_entry_memory_mib_uses_universal_floor() {
2051        // Edge case: entry.memory_mib=0 with wprof=true. The raw
2052        // derivation `max(cpus*64, 256, 0)` resolves to 256 on the
2053        // default 1-CPU topology; the minimal wprof arena is below
2054        // that, so the universal 256 MiB floor is what the VM gets.
2055        let entry = KtstrTestEntry {
2056            name: "wprof_zero_mib",
2057            memory_mib: 0,
2058            wprof: true,
2059            ..KtstrTestEntry::DEFAULT
2060        };
2061        let (_topo, mem) = resolve_vm_topology(&entry, None);
2062        assert_eq!(
2063            mem, 256,
2064            "entry.memory_mib=0 with wprof=true resolves to the \
2065             universal 256 MiB floor; got {mem}"
2066        );
2067    }
2068
2069    #[cfg(feature = "wprof")]
2070    #[test]
2071    fn derive_test_memory_mib_helper_applies_wprof_floor() {
2072        // Direct test of the derivation helper used by BOTH
2073        // resolve_vm_topology AND the dispatch.rs sites that
2074        // construct TopoOverride from CLI / preset topology
2075        // (run_ktstr_test_with_topo_str, run_gauntlet_test).
2076        // Pins that the helper applies the wprof floor — a
2077        // regression that re-inlined the formula at the dispatch
2078        // sites without the wprof check would silently bypass
2079        // the floor when `cargo ktstr test --ktstr-topo` runs
2080        // against a wprof-tagged test.
2081        let entry = KtstrTestEntry {
2082            name: "helper",
2083            memory_mib: 0,
2084            wprof: true,
2085            ..KtstrTestEntry::DEFAULT
2086        };
2087        let mem = derive_test_memory_mib(2, &entry);
2088        assert_eq!(
2089            mem, 256,
2090            "helper applies the wprof floor (16 MiB) but it is subsumed \
2091             by the universal 256 MiB floor for a 2-cpu VM; got {mem}"
2092        );
2093        assert_eq!(
2094            derive_test_memory_min_mib(2, entry.memory_mib, entry.wprof),
2095            mem,
2096            "pre-exec admission must apply the same wprof floor as VM sizing",
2097        );
2098
2099        // wprof=false: derivation returns the raw formula
2100        // without any floor.
2101        let entry_no_wprof = KtstrTestEntry {
2102            wprof: false,
2103            ..entry
2104        };
2105        let mem = derive_test_memory_mib(2, &entry_no_wprof);
2106        assert_eq!(
2107            mem, 256,
2108            "helper with wprof=false must NOT apply the floor; \
2109             expected max(2*64, 256, 0)=256, got {mem}"
2110        );
2111    }
2112
2113    #[cfg(feature = "wprof")]
2114    #[test]
2115    fn resolve_vm_topology_override_with_wprof_honors_override_verbatim() {
2116        // The override-is-verbatim contract: a TopoOverride with
2117        // memory_mib below WPROF_MIN_MEMORY_MIB is honored as the
2118        // operator's explicit choice. A warn-level log fires (not
2119        // verified in this unit test — tracing capture is out of
2120        // scope here) but the boot memory matches the override.
2121        let entry = KtstrTestEntry {
2122            name: "override_wprof",
2123            wprof: true,
2124            ..KtstrTestEntry::DEFAULT
2125        };
2126        let over = super::super::topo::TopoOverride {
2127            numa_nodes: 1,
2128            llcs: 1,
2129            cores: 1,
2130            threads: 1,
2131            memory_mib: 512,
2132        };
2133        let (_topo, mem) = resolve_vm_topology(&entry, Some(&over));
2134        assert_eq!(
2135            mem, 512,
2136            "TopoOverride.memory_mib must be honored verbatim even \
2137             with wprof enabled, got {mem}"
2138        );
2139    }
2140
2141    // -- append_base_sched_args --
2142
2143    #[test]
2144    fn append_base_sched_args_empty_when_none_set() {
2145        let entry = KtstrTestEntry {
2146            name: "nosched",
2147            ..KtstrTestEntry::DEFAULT
2148        };
2149        let mut args = Vec::new();
2150        append_base_sched_args(&entry, &mut args);
2151        assert!(args.is_empty(), "no sched args expected: {args:?}");
2152    }
2153
2154    /// `cgroup_parent` does NOT auto-inject `--cell-parent-cgroup`
2155    /// into the scheduler argv — the two concerns are decoupled.
2156    /// The scheduler-def `sched_args` and the per-test
2157    /// `extra_sched_args` flow through unchanged; the `cgroup_parent`
2158    /// setting controls the framework's cgroup root but never
2159    /// modifies the scheduler's CLI invocation.
2160    #[test]
2161    fn append_base_sched_args_does_not_auto_inject_cell_parent_cgroup() {
2162        static SCHED: Scheduler = Scheduler::named("s")
2163            .cgroup_parent("/sys/fs/cgroup/ktstr")
2164            .sched_args(&["-v", "--flag"]);
2165        let entry = KtstrTestEntry {
2166            name: "sched",
2167            scheduler: &SCHED,
2168            extra_sched_args: &["--extra"],
2169            ..KtstrTestEntry::DEFAULT
2170        };
2171        let mut args = Vec::new();
2172        append_base_sched_args(&entry, &mut args);
2173        assert_eq!(
2174            args,
2175            vec![
2176                "-v".to_string(),
2177                "--flag".to_string(),
2178                "--extra".to_string(),
2179            ],
2180            "cgroup_parent must not auto-inject --cell-parent-cgroup; \
2181             only sched_args + extra_sched_args reach the scheduler"
2182        );
2183    }
2184
2185    /// User-passed `--cell-parent-cgroup /user` via `extra_sched_args`
2186    /// suppresses the auto-inject so clap inside the scheduler binary
2187    /// doesn't reject the duplicate.
2188    #[test]
2189    fn append_base_sched_args_dedupes_extra_split_form() {
2190        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2191        let entry = KtstrTestEntry {
2192            name: "sched",
2193            scheduler: &SCHED,
2194            extra_sched_args: &["--cell-parent-cgroup", "/user"],
2195            ..KtstrTestEntry::DEFAULT
2196        };
2197        let mut args = Vec::new();
2198        append_base_sched_args(&entry, &mut args);
2199        assert_eq!(
2200            args,
2201            vec!["--cell-parent-cgroup".to_string(), "/user".to_string()],
2202            "auto-inject must be skipped when extra_sched_args carries \
2203             --cell-parent-cgroup in two-token form"
2204        );
2205    }
2206
2207    /// Combined form (`--cell-parent-cgroup=/user`) must also suppress
2208    /// the auto-inject.
2209    #[test]
2210    fn append_base_sched_args_dedupes_extra_combined_form() {
2211        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2212        let entry = KtstrTestEntry {
2213            name: "sched",
2214            scheduler: &SCHED,
2215            extra_sched_args: &["--cell-parent-cgroup=/user"],
2216            ..KtstrTestEntry::DEFAULT
2217        };
2218        let mut args = Vec::new();
2219        append_base_sched_args(&entry, &mut args);
2220        assert_eq!(
2221            args,
2222            vec!["--cell-parent-cgroup=/user".to_string()],
2223            "auto-inject must be skipped when extra_sched_args carries \
2224             --cell-parent-cgroup in combined `=` form"
2225        );
2226    }
2227
2228    /// Scheduler-def `sched_args` carrying `--cell-parent-cgroup`
2229    /// also suppresses the auto-inject.
2230    #[test]
2231    fn append_base_sched_args_dedupes_scheduler_sched_args() {
2232        static SCHED: Scheduler = Scheduler::named("s")
2233            .cgroup_parent("/sys/fs/cgroup/ktstr")
2234            .sched_args(&["--cell-parent-cgroup", "/user"]);
2235        let entry = KtstrTestEntry {
2236            name: "sched",
2237            scheduler: &SCHED,
2238            ..KtstrTestEntry::DEFAULT
2239        };
2240        let mut args = Vec::new();
2241        append_base_sched_args(&entry, &mut args);
2242        assert_eq!(
2243            args,
2244            vec!["--cell-parent-cgroup".to_string(), "/user".to_string()],
2245            "auto-inject must be skipped when scheduler.sched_args carries \
2246             --cell-parent-cgroup"
2247        );
2248    }
2249
2250    /// Scheduler-def `sched_args` carrying the combined `=` form also
2251    /// suppresses the auto-inject — completes the {source × form}
2252    /// 2×2 matrix.
2253    #[test]
2254    fn append_base_sched_args_dedupes_scheduler_sched_args_combined_form() {
2255        static SCHED: Scheduler = Scheduler::named("s")
2256            .cgroup_parent("/sys/fs/cgroup/ktstr")
2257            .sched_args(&["--cell-parent-cgroup=/user"]);
2258        let entry = KtstrTestEntry {
2259            name: "sched",
2260            scheduler: &SCHED,
2261            ..KtstrTestEntry::DEFAULT
2262        };
2263        let mut args = Vec::new();
2264        append_base_sched_args(&entry, &mut args);
2265        assert_eq!(
2266            args,
2267            vec!["--cell-parent-cgroup=/user".to_string()],
2268            "auto-inject must be skipped when scheduler.sched_args carries \
2269             --cell-parent-cgroup in combined `=` form"
2270        );
2271    }
2272
2273    /// When BOTH scheduler.sched_args AND extra_sched_args carry
2274    /// `--cell-parent-cgroup`, the framework's auto-inject is
2275    /// suppressed (`.any()` short-circuits on first match) but the
2276    /// user's duplicates flow through unchanged. The framework does
2277    /// not dedupe user-supplied duplicates — clap inside the
2278    /// scheduler binary will reject them with "cannot be used
2279    /// multiple times", as it should. Pin: the framework correctly
2280    /// avoids ADDING a third copy.
2281    #[test]
2282    fn append_base_sched_args_does_not_dedupe_user_dupes() {
2283        static SCHED: Scheduler = Scheduler::named("s")
2284            .cgroup_parent("/sys/fs/cgroup/ktstr")
2285            .sched_args(&["--cell-parent-cgroup", "/sched"]);
2286        let entry = KtstrTestEntry {
2287            name: "sched",
2288            scheduler: &SCHED,
2289            extra_sched_args: &["--cell-parent-cgroup", "/extra"],
2290            ..KtstrTestEntry::DEFAULT
2291        };
2292        let mut args = Vec::new();
2293        append_base_sched_args(&entry, &mut args);
2294        assert_eq!(
2295            args,
2296            vec![
2297                "--cell-parent-cgroup".to_string(),
2298                "/sched".to_string(),
2299                "--cell-parent-cgroup".to_string(),
2300                "/extra".to_string(),
2301            ],
2302            "framework auto-inject is suppressed; both user-supplied \
2303             entries flow through unchanged (user owns the dup)"
2304        );
2305    }
2306
2307    /// Empty combined value (`--cell-parent-cgroup=`) is rejected at
2308    /// the framework gate with an actionable panic that names the
2309    /// offending test and points the operator at the right fix.
2310    /// Empty values would resolve to `/sys/fs/cgroup` (the host
2311    /// cgroup root) downstream — guaranteed to corrupt unrelated
2312    /// cgroup state — so the framework rejects rather than letting
2313    /// clap surface a generic "value required" error after the
2314    /// cgroup hierarchy has already been built.
2315    #[test]
2316    #[should_panic(expected = "that does not start with `/`")]
2317    fn append_base_sched_args_panics_on_empty_combined_value_via_extra() {
2318        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2319        let entry = KtstrTestEntry {
2320            name: "sched",
2321            scheduler: &SCHED,
2322            extra_sched_args: &["--cell-parent-cgroup="],
2323            ..KtstrTestEntry::DEFAULT
2324        };
2325        let mut args = Vec::new();
2326        append_base_sched_args(&entry, &mut args);
2327    }
2328
2329    /// Two-token form with an empty value as the second token
2330    /// (`["--cell-parent-cgroup", ""]`) is rejected by the same gate.
2331    /// Covers the second route into `parse_cell_parent_cgroup` so a
2332    /// future refactor that switches the empty-detection logic on
2333    /// only one form gets caught.
2334    #[test]
2335    #[should_panic(expected = "that does not start with `/`")]
2336    fn append_base_sched_args_panics_on_empty_two_token_value_via_extra() {
2337        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2338        let entry = KtstrTestEntry {
2339            name: "sched_two_token",
2340            scheduler: &SCHED,
2341            extra_sched_args: &["--cell-parent-cgroup", ""],
2342            ..KtstrTestEntry::DEFAULT
2343        };
2344        let mut args = Vec::new();
2345        append_base_sched_args(&entry, &mut args);
2346    }
2347
2348    /// Bad value via the scheduler-def's own `sched_args` rather than
2349    /// the test's `extra_sched_args` — the chain at the parser site
2350    /// covers both sources, so the gate fires regardless of origin.
2351    /// Pins both the combined form and the scheduler origin.
2352    #[test]
2353    #[should_panic(expected = "that does not start with `/`")]
2354    fn append_base_sched_args_panics_on_empty_combined_value_via_scheduler_sched_args() {
2355        static SCHED: Scheduler = Scheduler::named("s")
2356            .cgroup_parent("/sys/fs/cgroup/ktstr")
2357            .sched_args(&["--cell-parent-cgroup="]);
2358        let entry = KtstrTestEntry {
2359            name: "sched_in_def",
2360            scheduler: &SCHED,
2361            ..KtstrTestEntry::DEFAULT
2362        };
2363        let mut args = Vec::new();
2364        append_base_sched_args(&entry, &mut args);
2365    }
2366
2367    /// Two-token form via the scheduler-def origin — completes the
2368    /// 2-source × 2-form matrix together with the three siblings.
2369    #[test]
2370    #[should_panic(expected = "that does not start with `/`")]
2371    fn append_base_sched_args_panics_on_empty_two_token_value_via_scheduler_sched_args() {
2372        static SCHED: Scheduler = Scheduler::named("s")
2373            .cgroup_parent("/sys/fs/cgroup/ktstr")
2374            .sched_args(&["--cell-parent-cgroup", ""]);
2375        let entry = KtstrTestEntry {
2376            name: "sched_in_def_two_token",
2377            scheduler: &SCHED,
2378            ..KtstrTestEntry::DEFAULT
2379        };
2380        let mut args = Vec::new();
2381        append_base_sched_args(&entry, &mut args);
2382    }
2383
2384    /// Empty-value gate fires even when the scheduler-def has no
2385    /// `cgroup_parent` default. Without the universal gate the empty
2386    /// value would slip through and corrupt unrelated host cgroup
2387    /// state at the downstream `resolve_cgroup_root` interpolation.
2388    #[test]
2389    #[should_panic(expected = "that does not start with `/`")]
2390    fn append_base_sched_args_panics_on_empty_combined_value_no_scheduler_cgroup_parent() {
2391        static SCHED: Scheduler = Scheduler::named("s");
2392        let entry = KtstrTestEntry {
2393            name: "no_default_cgroup",
2394            scheduler: &SCHED,
2395            extra_sched_args: &["--cell-parent-cgroup="],
2396            ..KtstrTestEntry::DEFAULT
2397        };
2398        let mut args = Vec::new();
2399        append_base_sched_args(&entry, &mut args);
2400    }
2401
2402    /// Two-token form, no scheduler default — completes the
2403    /// no-default matrix together with the combined-form sibling.
2404    #[test]
2405    #[should_panic(expected = "that does not start with `/`")]
2406    fn append_base_sched_args_panics_on_empty_two_token_value_no_scheduler_cgroup_parent() {
2407        static SCHED: Scheduler = Scheduler::named("s");
2408        let entry = KtstrTestEntry {
2409            name: "no_default_cgroup_two_token",
2410            scheduler: &SCHED,
2411            extra_sched_args: &["--cell-parent-cgroup", ""],
2412            ..KtstrTestEntry::DEFAULT
2413        };
2414        let mut args = Vec::new();
2415        append_base_sched_args(&entry, &mut args);
2416    }
2417
2418    /// Relative path (no leading `/`) is rejected by the same gate.
2419    /// Pins the broader contract (the message explicitly promises
2420    /// "absolute path under `/`"); empty is just one case of
2421    /// non-absolute.
2422    #[test]
2423    #[should_panic(expected = "that does not start with `/`")]
2424    fn append_base_sched_args_panics_on_relative_path_value() {
2425        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2426        let entry = KtstrTestEntry {
2427            name: "relative_path",
2428            scheduler: &SCHED,
2429            extra_sched_args: &["--cell-parent-cgroup=my_test"],
2430            ..KtstrTestEntry::DEFAULT
2431        };
2432        let mut args = Vec::new();
2433        append_base_sched_args(&entry, &mut args);
2434    }
2435
2436    /// Two-token form of the relative-path case. Closes the matrix
2437    /// gap: combined-form was pinned by the sibling above but a
2438    /// future refactor that split path validation between the
2439    /// combined and two-token branches could regress one form
2440    /// without test catching.
2441    #[test]
2442    #[should_panic(expected = "that does not start with `/`")]
2443    fn append_base_sched_args_panics_on_relative_path_value_two_token() {
2444        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2445        let entry = KtstrTestEntry {
2446            name: "relative_path_two_token",
2447            scheduler: &SCHED,
2448            extra_sched_args: &["--cell-parent-cgroup", "my_test"],
2449            ..KtstrTestEntry::DEFAULT
2450        };
2451        let mut args = Vec::new();
2452        append_base_sched_args(&entry, &mut args);
2453    }
2454
2455    /// `/.` is absolute and has more than one character, so a naive
2456    /// `starts_with('/') && len > 1` check passes — but the kernel
2457    /// canonicalizes `/sys/fs/cgroup/.` back to `/sys/fs/cgroup`
2458    /// (host cgroup root), corrupting unrelated cgroup state.
2459    /// `Path::components` strips the trailing `.`, yielding `[RootDir]`
2460    /// — the validator rejects via the "has no Normal component"
2461    /// check, not the CurDir arm (see `cell_parent_path_is_valid`).
2462    #[test]
2463    #[should_panic(expected = "contains `.`/`..` segments")]
2464    fn append_base_sched_args_panics_on_dot_normalizing_to_root() {
2465        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2466        let entry = KtstrTestEntry {
2467            name: "dot_normalize",
2468            scheduler: &SCHED,
2469            extra_sched_args: &["--cell-parent-cgroup=/."],
2470            ..KtstrTestEntry::DEFAULT
2471        };
2472        let mut args = Vec::new();
2473        append_base_sched_args(&entry, &mut args);
2474    }
2475
2476    /// `/foo/..` canonicalizes back to `/` → `/sys/fs/cgroup`. Same
2477    /// host-root corruption risk as the empty/bare-slash cases. The
2478    /// component-based gate rejects any `..` (ParentDir) segment.
2479    #[test]
2480    #[should_panic(expected = "contains `.`/`..` segments")]
2481    fn append_base_sched_args_panics_on_parent_dir_normalizing_to_root() {
2482        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2483        let entry = KtstrTestEntry {
2484            name: "parent_dir_normalize",
2485            scheduler: &SCHED,
2486            extra_sched_args: &["--cell-parent-cgroup=/foo/.."],
2487            ..KtstrTestEntry::DEFAULT
2488        };
2489        let mut args = Vec::new();
2490        append_base_sched_args(&entry, &mut args);
2491    }
2492
2493    /// Mixed `/./bar/..` — both kinds of normalizing segment in one
2494    /// path. `Path::components` strips the leading `/.`, yielding
2495    /// `[RootDir, Normal("bar"), ParentDir]`; the validator reaches
2496    /// the `ParentDir` and rejects via that arm. The `/.` never
2497    /// surfaces as a CurDir component.
2498    #[test]
2499    #[should_panic(expected = "contains `.`/`..` segments")]
2500    fn append_base_sched_args_panics_on_mixed_normalize_segments() {
2501        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2502        let entry = KtstrTestEntry {
2503            name: "mixed_normalize",
2504            scheduler: &SCHED,
2505            extra_sched_args: &["--cell-parent-cgroup=/./bar/.."],
2506            ..KtstrTestEntry::DEFAULT
2507        };
2508        let mut args = Vec::new();
2509        append_base_sched_args(&entry, &mut args);
2510    }
2511
2512    /// `/foo/./bar` is ACCEPTED — `Path::components` normalizes away
2513    /// every `CurDir` segment (see `cell_parent_path_is_valid` for
2514    /// the full per-position behavior); the canonical form
2515    /// `/foo/bar` is a real non-root path. Pin the accept path so a
2516    /// future refactor to a stricter `.contains("/./")` text check
2517    /// is caught. Also assert the user value flows through verbatim
2518    /// — a regression that canonicalized the path before forwarding
2519    /// would silently rewrite `/foo/./bar` to `/foo/bar`.
2520    #[test]
2521    fn append_base_sched_args_accepts_embedded_dot_segment() {
2522        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2523        let entry = KtstrTestEntry {
2524            name: "embedded_dot_ok",
2525            scheduler: &SCHED,
2526            extra_sched_args: &["--cell-parent-cgroup=/foo/./bar"],
2527            ..KtstrTestEntry::DEFAULT
2528        };
2529        let mut args = Vec::new();
2530        append_base_sched_args(&entry, &mut args);
2531        assert!(
2532            args.iter().any(|a| a == "--cell-parent-cgroup=/foo/./bar"),
2533            "user value must pass through verbatim (no canonicalization); args: {args:?}",
2534        );
2535    }
2536
2537    /// Bare `/..` is the most damaging path-normalize edge:
2538    /// downstream interpolation `/sys/fs/cgroup/..` canonicalizes to
2539    /// `/sys/fs` — escapes the cgroup hierarchy entirely. The
2540    /// component walk hits `ParentDir` immediately after `RootDir`
2541    /// (no Normal segment between them) and rejects via the
2542    /// ParentDir arm.
2543    #[test]
2544    #[should_panic(expected = "contains `.`/`..` segments")]
2545    fn append_base_sched_args_panics_on_bare_parent_dir() {
2546        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2547        let entry = KtstrTestEntry {
2548            name: "bare_parent_dir",
2549            scheduler: &SCHED,
2550            extra_sched_args: &["--cell-parent-cgroup=/.."],
2551            ..KtstrTestEntry::DEFAULT
2552        };
2553        let mut args = Vec::new();
2554        append_base_sched_args(&entry, &mut args);
2555    }
2556
2557    /// Mid-path `/foo/../bar` — ParentDir sits BETWEEN Normal
2558    /// segments. Different shape from `/foo/..` (trailing
2559    /// ParentDir): a regression that bailed only on
2560    /// `path.ends_with("/..")` would slip this past. Downstream
2561    /// interpolation `/sys/fs/cgroup/foo/../bar` canonicalizes to
2562    /// `/sys/fs/cgroup/bar` — an unintended sibling directory the
2563    /// test author didn't ask for. Component walk catches ParentDir
2564    /// in any position.
2565    #[test]
2566    #[should_panic(expected = "contains `.`/`..` segments")]
2567    fn append_base_sched_args_panics_on_mid_path_parent_dir() {
2568        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2569        let entry = KtstrTestEntry {
2570            name: "mid_path_parent_dir",
2571            scheduler: &SCHED,
2572            extra_sched_args: &["--cell-parent-cgroup=/foo/../bar"],
2573            ..KtstrTestEntry::DEFAULT
2574        };
2575        let mut args = Vec::new();
2576        append_base_sched_args(&entry, &mut args);
2577    }
2578
2579    /// Bare `/` slips a naive `starts_with('/')` check but resolves
2580    /// downstream to `/sys/fs/cgroup/` — semantically the host cgroup
2581    /// root, same corruption risk as the empty case. The gate mirrors
2582    /// `CgroupPath::new`'s const-eval contract (rejects both
2583    /// no-leading-slash AND `"/"` alone) so runtime values share the
2584    /// same validation as compile-time declarations.
2585    #[test]
2586    #[should_panic(expected = "is `/` alone")]
2587    fn append_base_sched_args_panics_on_bare_slash_value() {
2588        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2589        let entry = KtstrTestEntry {
2590            name: "bare_slash",
2591            scheduler: &SCHED,
2592            extra_sched_args: &["--cell-parent-cgroup=/"],
2593            ..KtstrTestEntry::DEFAULT
2594        };
2595        let mut args = Vec::new();
2596        append_base_sched_args(&entry, &mut args);
2597    }
2598
2599    /// Combined-form empty value via scheduler-def `sched_args`
2600    /// when the scheduler also has NO `cgroup_parent` default. Closes
2601    /// the matrix intersection: a future refactor that gates the
2602    /// scheduler-def-source check on `cgroup_parent.is_some()` would
2603    /// pass the other 6 empty tests but regress this cell.
2604    #[test]
2605    #[should_panic(expected = "that does not start with `/`")]
2606    fn append_base_sched_args_panics_on_empty_combined_value_in_scheduler_sched_args_no_default() {
2607        static SCHED: Scheduler = Scheduler::named("s").sched_args(&["--cell-parent-cgroup="]);
2608        let entry = KtstrTestEntry {
2609            name: "scheduler_def_origin_no_default",
2610            scheduler: &SCHED,
2611            ..KtstrTestEntry::DEFAULT
2612        };
2613        let mut args = Vec::new();
2614        append_base_sched_args(&entry, &mut args);
2615    }
2616
2617    /// Two-token-form sibling of the above — completes the
2618    /// 2-form coverage for the scheduler-def-origin × no-default
2619    /// intersection.
2620    #[test]
2621    #[should_panic(expected = "that does not start with `/`")]
2622    fn append_base_sched_args_panics_on_empty_two_token_value_in_scheduler_sched_args_no_default() {
2623        static SCHED: Scheduler = Scheduler::named("s").sched_args(&["--cell-parent-cgroup", ""]);
2624        let entry = KtstrTestEntry {
2625            name: "scheduler_def_origin_two_token_no_default",
2626            scheduler: &SCHED,
2627            ..KtstrTestEntry::DEFAULT
2628        };
2629        let mut args = Vec::new();
2630        append_base_sched_args(&entry, &mut args);
2631    }
2632
2633    /// Bare `--cell-parent-cgroup` flag with no following token
2634    /// (two-token form, trailing in argv) is rejected at the
2635    /// framework gate via the `CellParentCgroupArg::MissingValue`
2636    /// arm. Previously this shape parsed as "absent", triggered the
2637    /// auto-inject, and produced two copies of the flag in the final
2638    /// argv that clap then rejected with a confused "cannot be used
2639    /// multiple times" diagnostic. The gate intercepts here so the
2640    /// operator gets a "missing value" message anchored to their
2641    /// declaration.
2642    #[test]
2643    #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2644    fn append_base_sched_args_panics_on_missing_value_via_extra() {
2645        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2646        let entry = KtstrTestEntry {
2647            name: "missing_value_extra",
2648            scheduler: &SCHED,
2649            extra_sched_args: &["--cell-parent-cgroup"],
2650            ..KtstrTestEntry::DEFAULT
2651        };
2652        let mut args = Vec::new();
2653        append_base_sched_args(&entry, &mut args);
2654    }
2655
2656    /// Bare flag preceded by an unrelated trailing token still trips
2657    /// the MissingValue arm — the parser walks the chain in order,
2658    /// hits the bare flag, and `iter.next()` returns None at end of
2659    /// stream regardless of which unrelated tokens came before it.
2660    #[test]
2661    #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2662    fn append_base_sched_args_panics_on_missing_value_after_other_flag() {
2663        static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2664        let entry = KtstrTestEntry {
2665            name: "missing_value_after_other",
2666            scheduler: &SCHED,
2667            extra_sched_args: &["--other-flag", "--cell-parent-cgroup"],
2668            ..KtstrTestEntry::DEFAULT
2669        };
2670        let mut args = Vec::new();
2671        append_base_sched_args(&entry, &mut args);
2672    }
2673
2674    /// Bare flag in the scheduler-def's `sched_args` also trips
2675    /// MissingValue — the parser chains both sources and the
2676    /// universal gate handles them identically.
2677    #[test]
2678    #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2679    fn append_base_sched_args_panics_on_missing_value_in_scheduler_sched_args() {
2680        static SCHED: Scheduler = Scheduler::named("s")
2681            .cgroup_parent("/sys/fs/cgroup/ktstr")
2682            .sched_args(&["--cell-parent-cgroup"]);
2683        let entry = KtstrTestEntry {
2684            name: "missing_value_scheduler_def",
2685            scheduler: &SCHED,
2686            ..KtstrTestEntry::DEFAULT
2687        };
2688        let mut args = Vec::new();
2689        append_base_sched_args(&entry, &mut args);
2690    }
2691
2692    /// Bare flag with no scheduler default `cgroup_parent`. The
2693    /// universal gate must still fire — the panic message in this
2694    /// case omits the "let the framework auto-inject" suggestion
2695    /// (no default to inject) and adds a hint that an absolute path
2696    /// is required for cell-aware schedulers without a declared
2697    /// default.
2698    #[test]
2699    #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2700    fn append_base_sched_args_panics_on_missing_value_no_scheduler_cgroup_parent() {
2701        static SCHED: Scheduler = Scheduler::named("s");
2702        let entry = KtstrTestEntry {
2703            name: "missing_value_no_default",
2704            scheduler: &SCHED,
2705            extra_sched_args: &["--cell-parent-cgroup"],
2706            ..KtstrTestEntry::DEFAULT
2707        };
2708        let mut args = Vec::new();
2709        append_base_sched_args(&entry, &mut args);
2710    }
2711
2712    /// Bare flag via scheduler-def `sched_args` with no default
2713    /// `cgroup_parent`. Closes the matrix intersection: a future
2714    /// refactor that gated the MissingValue check on
2715    /// `cgroup_parent.is_some()` (mirroring an earlier regression
2716    /// fixed for Value-invalid) would pass the other 4 MissingValue
2717    /// tests but regress this cell.
2718    #[test]
2719    #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2720    fn append_base_sched_args_panics_on_missing_value_in_scheduler_sched_args_no_default() {
2721        static SCHED: Scheduler = Scheduler::named("s").sched_args(&["--cell-parent-cgroup"]);
2722        let entry = KtstrTestEntry {
2723            name: "missing_value_scheduler_def_no_default",
2724            scheduler: &SCHED,
2725            ..KtstrTestEntry::DEFAULT
2726        };
2727        let mut args = Vec::new();
2728        append_base_sched_args(&entry, &mut args);
2729    }
2730
2731    /// Bare flag after another flag, with no scheduler default.
2732    /// Completes the after-other-flag × default matrix together with
2733    /// the sibling test that has a default.
2734    #[test]
2735    #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2736    fn append_base_sched_args_panics_on_missing_value_after_other_flag_no_default() {
2737        static SCHED: Scheduler = Scheduler::named("s");
2738        let entry = KtstrTestEntry {
2739            name: "missing_value_after_other_no_default",
2740            scheduler: &SCHED,
2741            extra_sched_args: &["--other-flag", "--cell-parent-cgroup"],
2742            ..KtstrTestEntry::DEFAULT
2743        };
2744        let mut args = Vec::new();
2745        append_base_sched_args(&entry, &mut args);
2746    }
2747
2748    // -- build_vm_builder_base --
2749
2750    /// Kernel-path surfaces in the builder's "kernel not found" error.
2751    /// Proves the `kernel()` setter is wired through the helper.
2752    #[test]
2753    fn build_vm_builder_base_propagates_kernel_path() {
2754        // build()'s no-perf path reads KTSTR_BYPASS_LLC_LOCKS + KTSTR_CPU_CAP
2755        // before the validation checks. Under the shared env lock, pin
2756        // bypass=1 + cpu_cap unset so build() short-circuits the slot/LLC
2757        // acquire path (no acquire_llc_plan contention; cpu_cap=None avoids
2758        // the bypass+cpu_cap bail), leaving the asserted error the only outcome.
2759        let _l = lock_env();
2760        let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "1");
2761        let _c = EnvVarGuard::remove(crate::KTSTR_CPU_CAP_ENV);
2762        let entry = KtstrTestEntry {
2763            name: "vmb_kernel_path",
2764            ..KtstrTestEntry::DEFAULT
2765        };
2766        let exe = crate::resolve_current_exe().unwrap();
2767        let missing_kernel =
2768            PathBuf::from("/nonexistent/build_vm_builder_base_test_kernel.bzImage");
2769        let result = build_vm_builder_base(
2770            &entry,
2771            &missing_kernel,
2772            &exe,
2773            None,
2774            &[],
2775            crate::vmm::topology::Topology::new(1, 1, 1, 1),
2776            256,
2777            "",
2778            &["run".to_string()],
2779            true,
2780        )
2781        .build();
2782        // `KtstrVm` does not implement Debug, so `.unwrap_err()` is not
2783        // available — collapse Ok into a panic to extract the error by hand.
2784        let err = match result {
2785            Ok(_) => panic!("builder.build() unexpectedly succeeded for missing kernel"),
2786            Err(e) => e,
2787        };
2788        let msg = format!("{err}");
2789        assert!(
2790            msg.contains("kernel not found"),
2791            "expected kernel not found error, got: {msg}",
2792        );
2793        assert!(
2794            msg.contains("build_vm_builder_base_test_kernel"),
2795            "expected the fake kernel path to appear in the error, got: {msg}",
2796        );
2797    }
2798
2799    /// A zero-`llcs` topology is forwarded to the builder and surfaces
2800    /// as a validation error. Proves `topology()` is wired through.
2801    #[test]
2802    fn build_vm_builder_base_propagates_topology_validation() {
2803        // See build_vm_builder_base_propagates_kernel_path: pin bypass=1 +
2804        // cpu_cap unset under the shared env lock so build() short-circuits
2805        // the no-perf slot/LLC path and the asserted error is deterministic.
2806        let _l = lock_env();
2807        let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "1");
2808        let _c = EnvVarGuard::remove(crate::KTSTR_CPU_CAP_ENV);
2809        let entry = KtstrTestEntry {
2810            name: "vmb_topology",
2811            ..KtstrTestEntry::DEFAULT
2812        };
2813        let exe = crate::resolve_current_exe().unwrap();
2814        let bad_topology = crate::vmm::topology::Topology {
2815            llcs: 0,
2816            cores_per_llc: 1,
2817            threads_per_core: 1,
2818            numa_nodes: 1,
2819            nodes: None,
2820            distances: None,
2821            llc_cores: None,
2822        };
2823        let result = build_vm_builder_base(
2824            &entry,
2825            &exe,
2826            &exe,
2827            None,
2828            &[],
2829            bad_topology,
2830            256,
2831            "",
2832            &["run".to_string()],
2833            true,
2834        )
2835        .build();
2836        let err = match result {
2837            Ok(_) => panic!("builder.build() unexpectedly succeeded for zero-llcs topology"),
2838            Err(e) => e,
2839        };
2840        let msg = format!("{err}");
2841        assert!(
2842            msg.contains("llcs must be > 0"),
2843            "expected topology validation error, got: {msg}",
2844        );
2845    }
2846
2847    /// An optional scheduler binary is attached when `Some(path)`
2848    /// is supplied, surfacing as a "scheduler binary not found"
2849    /// error when the path is missing.
2850    #[test]
2851    fn build_vm_builder_base_propagates_scheduler_binary() {
2852        // See build_vm_builder_base_propagates_kernel_path: pin bypass=1 +
2853        // cpu_cap unset under the shared env lock so build() short-circuits
2854        // the no-perf slot/LLC path and the asserted error is deterministic.
2855        let _l = lock_env();
2856        let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "1");
2857        let _c = EnvVarGuard::remove(crate::KTSTR_CPU_CAP_ENV);
2858        let entry = KtstrTestEntry {
2859            name: "vmb_scheduler",
2860            ..KtstrTestEntry::DEFAULT
2861        };
2862        let exe = crate::resolve_current_exe().unwrap();
2863        let missing_scheduler = PathBuf::from("/nonexistent/build_vm_builder_base_test_scheduler");
2864        let result = build_vm_builder_base(
2865            &entry,
2866            &exe,
2867            &exe,
2868            Some(&missing_scheduler),
2869            &[],
2870            crate::vmm::topology::Topology::new(1, 1, 1, 1),
2871            256,
2872            "",
2873            &["run".to_string()],
2874            true,
2875        )
2876        .build();
2877        let err = match result {
2878            Ok(_) => panic!("builder.build() unexpectedly succeeded for missing scheduler"),
2879            Err(e) => e,
2880        };
2881        let msg = format!("{err}");
2882        assert!(
2883            msg.contains("scheduler binary not found"),
2884            "expected scheduler binary error, got: {msg}",
2885        );
2886        assert!(
2887            msg.contains("build_vm_builder_base_test_scheduler"),
2888            "expected the fake scheduler path to appear, got: {msg}",
2889        );
2890    }
2891
2892    // -- vm_timeout_from_entry tests --
2893
2894    // The Tier-3 dead-man deadline is `base + vm_boot_headroom(vcpus) *
2895    // DEADMAN_HEADROOM_MULT`; the headroom no longer scales by the host
2896    // overcommit ratio, so these are host-cpuset-independent (no pin).
2897
2898    #[test]
2899    fn vm_timeout_from_entry_uses_watchdog_when_largest() {
2900        // DEFAULT topology = 2 vCPUs → vm_boot_headroom(2) = 20.3 s ×3 =
2901        // 60.9 s. base = max(60s, 30s, 1s) = 60s → 120.9 s.
2902        let entry = KtstrTestEntry {
2903            name: "wdog",
2904            watchdog_timeout: Duration::from_secs(60),
2905            duration: Duration::from_secs(30),
2906            ..KtstrTestEntry::DEFAULT
2907        };
2908        assert_eq!(
2909            vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2910            Duration::from_millis(120_900)
2911        );
2912    }
2913
2914    #[test]
2915    fn vm_timeout_from_entry_uses_duration_when_largest() {
2916        let entry = KtstrTestEntry {
2917            name: "dur",
2918            watchdog_timeout: Duration::from_secs(5),
2919            duration: Duration::from_secs(120),
2920            ..KtstrTestEntry::DEFAULT
2921        };
2922        // base = max(5s, 120s, 1s) = 120s; headroom(2)×3 = 60.9 s.
2923        assert_eq!(
2924            vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2925            Duration::from_millis(180_900)
2926        );
2927    }
2928
2929    #[test]
2930    fn vm_timeout_from_entry_floor_when_both_small() {
2931        // base floors at 1 s; headroom(2)×3 = 60.9 s → 61.9 s.
2932        let entry = KtstrTestEntry {
2933            name: "tiny",
2934            watchdog_timeout: Duration::from_millis(10),
2935            duration: Duration::from_millis(50),
2936            ..KtstrTestEntry::DEFAULT
2937        };
2938        assert_eq!(
2939            vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2940            Duration::from_millis(61_900)
2941        );
2942    }
2943
2944    #[test]
2945    fn vm_timeout_from_default_entry() {
2946        // DEFAULT watchdog = 5 s, duration = 12 s → base = 12 s.
2947        // headroom(2)×3 = 60.9 s → 72.9 s total.
2948        let entry = KtstrTestEntry {
2949            name: "default",
2950            ..KtstrTestEntry::DEFAULT
2951        };
2952        assert_eq!(
2953            vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2954            Duration::from_millis(72_900)
2955        );
2956    }
2957
2958    #[test]
2959    fn vm_timeout_from_entry_scales_headroom_with_topology() {
2960        // A reported case: numa=1, llcs=7, cores=9, threads=2 → 126 vCPUs.
2961        // vm_boot_headroom(126) = 38.9 s ×3 = 116.7 s. base = max(5 s
2962        // watchdog, 12 s duration, 1 s) = 12 s → total = 128.7 s.
2963        // Pins the `entry.topology.total_cpus()` → `vm_boot_headroom`
2964        // wiring; the flat ×3 headroom is host-cpuset-independent.
2965        let entry = KtstrTestEntry {
2966            name: "large_topo",
2967            topology: crate::vmm::topology::Topology {
2968                llcs: 7,
2969                cores_per_llc: 9,
2970                threads_per_core: 2,
2971                numa_nodes: 1,
2972                nodes: None,
2973                distances: None,
2974                llc_cores: None,
2975            },
2976            ..KtstrTestEntry::DEFAULT
2977        };
2978        assert_eq!(
2979            vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2980            Duration::from_millis(128_700)
2981        );
2982    }
2983
2984    #[test]
2985    fn vm_timeout_from_entry_scales_on_booted_not_declared_vcpus() {
2986        // Under a TopoOverride the VM boots a different vCPU count than
2987        // entry.topology declares; the boot-headroom deadline must scale
2988        // to the BOOTED count passed in, not entry.topology. A default
2989        // 2-vCPU entry "booted" at 126 vCPUs must get the 126-vCPU
2990        // headroom (128.7 s, matching the declared-126 case above), not
2991        // the declared 2-vCPU headroom (72.9 s). The declared-vs-booted
2992        // gap is otherwise untested — every other vm_timeout test passes
2993        // entry.topology.total_cpus() (declared == booted).
2994        let entry = KtstrTestEntry {
2995            name: "booted_override",
2996            ..KtstrTestEntry::DEFAULT
2997        };
2998        assert_eq!(
2999            vm_timeout_from_entry(&entry, 126),
3000            Duration::from_millis(128_700),
3001        );
3002        assert_eq!(
3003            vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
3004            Duration::from_millis(72_900),
3005        );
3006        assert_ne!(
3007            vm_timeout_from_entry(&entry, 126),
3008            vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
3009            "the deadline must key on the booted count, not the declared entry.topology",
3010        );
3011    }
3012
3013    // -- overcommit_ratio / oversub-scaled vm_timeout --
3014
3015    #[test]
3016    fn overcommit_ratio_floors_at_one_for_fitting_host() {
3017        // vCPUs <= allowed → not oversubscribed → 1.0 (never < 1).
3018        assert_eq!(overcommit_ratio(8, 192, None), 1.0);
3019        assert_eq!(overcommit_ratio(192, 192, None), 1.0);
3020    }
3021
3022    #[test]
3023    fn overcommit_ratio_auto_collapse_uses_allowed_cpuset() {
3024        // No explicit cpu_budget: the vCPU threads collapse onto the
3025        // whole allowed cpuset. 256 vCPUs on 192 allowed = the CI
3026        // wide-SMP case (~1.33x).
3027        let r = overcommit_ratio(256, 192, None);
3028        assert!((r - 256.0 / 192.0).abs() < 1e-9, "got {r}");
3029    }
3030
3031    #[test]
3032    fn overcommit_ratio_explicit_budget_collapses_onto_min_budget_allowed() {
3033        // Explicit cpu_budget caps the host CPUs the vCPU threads land
3034        // on (the deliberate _overcommit test): 256 / min(64, 192) = 4x.
3035        assert_eq!(overcommit_ratio(256, 192, Some(64)), 4.0);
3036        // A budget wider than the allowed set clamps to allowed.
3037        let r = overcommit_ratio(256, 192, Some(1000));
3038        assert!((r - 256.0 / 192.0).abs() < 1e-9, "got {r}");
3039    }
3040
3041    #[test]
3042    fn overcommit_ratio_guards_empty_cpuset() {
3043        // An unenumerable cpuset (allowed_cpus = 0) must not divide by
3044        // zero — treat it as a 1-CPU host.
3045        assert_eq!(overcommit_ratio(8, 0, None), 8.0);
3046    }
3047
3048    #[test]
3049    fn overcommit_skip_reason_skips_severe_auto_collapse() {
3050        // 256 vCPUs auto-collapse onto 8 host CPUs = 32x ≥ 6x → skip.
3051        // (boot-only path: expect_auto_repro = false.)
3052        let r = overcommit_skip_reason(256, 8, None, false);
3053        assert!(
3054            r.as_deref()
3055                .is_some_and(|m| m.contains("host topology insufficient")),
3056            "32x auto-collapse must skip with the typed reason, got {r:?}",
3057        );
3058    }
3059
3060    #[test]
3061    fn overcommit_skip_reason_runs_ci_wide_smp_ratio() {
3062        // 256 vCPUs on a 192-CPU CI runner = 1.33x < 6x → RUNS (None),
3063        // so wide-SMP boot is validated there, never masked.
3064        assert_eq!(overcommit_skip_reason(256, 192, None, false), None);
3065    }
3066
3067    #[test]
3068    fn overcommit_skip_reason_never_skips_explicit_budget() {
3069        // An explicit cpu_budget is a deliberate oversubscription opt-in
3070        // (contention testing): even 256 vCPUs on 8 host CPUs runs.
3071        assert_eq!(overcommit_skip_reason(256, 8, Some(4), false), None);
3072    }
3073
3074    #[test]
3075    fn overcommit_skip_reason_runs_on_empty_cpuset() {
3076        // An unenumerable cpuset (allowed = 0) cannot compute a ratio →
3077        // does not skip; the overcommit warning is the sole signal there.
3078        assert_eq!(overcommit_skip_reason(256, 0, None, false), None);
3079    }
3080
3081    #[test]
3082    fn overcommit_skip_reason_boundary_is_inclusive_at_cap() {
3083        // ≥ cap skips, just-below runs. 48 vCPUs on 8 = exactly 6.0x → skip;
3084        // 47 on 8 = 5.875x < 6.0 → run. (boot-only path.)
3085        assert!(overcommit_skip_reason(48, 8, None, false).is_some());
3086        assert_eq!(overcommit_skip_reason(47, 8, None, false), None);
3087    }
3088
3089    #[test]
3090    fn overcommit_skip_reason_expect_auto_repro_uses_stricter_cap() {
3091        // The expect_auto_repro inversion chain skips at a much lower
3092        // ratio (EXPECT_AUTO_REPRO_SKIP_RATIO = 2.0x) than a boot-only
3093        // wide test. Pins the failing CI case: 256 vCPUs on a 96-CPU host
3094        // = 2.67x.
3095        //   - 2.67x WITH expect_auto_repro -> SKIP (the two-VM wprof chain
3096        //     cannot run cleanly under that time-slicing).
3097        let skip = overcommit_skip_reason(256, 96, None, true);
3098        assert!(
3099            skip.as_deref().is_some_and(
3100                |m| m.contains("host topology insufficient") && m.contains("expect_auto_repro")
3101            ),
3102            "2.67x with expect_auto_repro must skip naming the chain, got {skip:?}",
3103        );
3104        //   - same 2.67x WITHOUT expect_auto_repro -> RUNS (a single-VM
3105        //     wide-SMP boot test still validates boot at 2.67x < 6.0x).
3106        assert_eq!(overcommit_skip_reason(256, 96, None, false), None);
3107        //   - the 192-CPU design-target runner (256/192 = 1.33x) RUNS the
3108        //     auto-repro hop even with expect_auto_repro (1.33x < 2.0x), so
3109        //     the >255 inversion is still validated there.
3110        assert_eq!(overcommit_skip_reason(256, 192, None, true), None);
3111        //   - an explicit cpu_budget stays a deliberate opt-in: no skip
3112        //     even with expect_auto_repro.
3113        assert_eq!(overcommit_skip_reason(256, 8, Some(4), true), None);
3114        //   - boundary: exactly 2.0x with expect_auto_repro skips (>= is
3115        //     inclusive); just below runs.
3116        assert!(overcommit_skip_reason(16, 8, None, true).is_some());
3117        assert_eq!(overcommit_skip_reason(15, 8, None, true), None);
3118    }
3119
3120    #[test]
3121    fn vm_timeout_headroom_is_flat_deadman_mult() {
3122        // Tier-3 dead-man: the headroom term is a FLAT
3123        // vm_boot_headroom(vcpus) × DEADMAN_HEADROOM_MULT, with NO host
3124        // overcommit scaling. 256 vCPUs (16 LLCs × 16 cores):
3125        // vm_boot_headroom(256) = 58.4 s ×3 = 175.2 s; base = max(5 s
3126        // watchdog, 12 s duration, 1 s) = 12 s → 187.2 s. The old path
3127        // multiplied this headroom by the host overcommit ratio; it no
3128        // longer does (Tier-1/2 absorb a loaded host), so the value is
3129        // independent of the host cpuset.
3130        let entry = KtstrTestEntry {
3131            name: "flat",
3132            topology: crate::vmm::topology::Topology {
3133                llcs: 16,
3134                cores_per_llc: 16,
3135                threads_per_core: 1,
3136                numa_nodes: 1,
3137                nodes: None,
3138                distances: None,
3139                llc_cores: None,
3140            },
3141            ..KtstrTestEntry::DEFAULT
3142        };
3143        // 12_000 + 58_400 × 3 = 187_200 ms.
3144        assert_eq!(
3145            vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
3146            Duration::from_millis(187_200)
3147        );
3148    }
3149
3150    #[test]
3151    fn vm_timeout_headroom_does_not_scale_with_overcommit() {
3152        // The deadline reads no host cpuset: the headroom above `base` is
3153        // EXACTLY vm_boot_headroom(vcpus) × DEADMAN_HEADROOM_MULT for any
3154        // vcpu count, so an oversubscribed host cannot lengthen it. Pins
3155        // the structural shape (base = 12 s = max(5 s wdog, 12 s dur, 1 s)
3156        // for a DEFAULT entry).
3157        let entry = KtstrTestEntry {
3158            name: "no_oversub",
3159            ..KtstrTestEntry::DEFAULT
3160        };
3161        let base = Duration::from_secs(12);
3162        for vcpus in [2u32, 64, 128, 256] {
3163            assert_eq!(
3164                vm_timeout_from_entry(&entry, vcpus) - base,
3165                vm_boot_headroom(vcpus) * DEADMAN_HEADROOM_MULT,
3166                "headroom must be the flat dead-man term at {vcpus} vCPUs",
3167            );
3168        }
3169    }
3170
3171    #[test]
3172    fn verifier_vm_timeout_is_flat_deadman() {
3173        // Verifier Tier-3 dead-man: VERIFIER_BASE_TIMEOUT (120 s) plus a
3174        // FLAT vm_boot_headroom(vcpus) × DEADMAN_HEADROOM_MULT, no host
3175        // overcommit scaling. 128 vCPUs: vm_boot_headroom(128) = 10 s
3176        // kernel init + (10_000 + 128×150 = 29_200 ms) sys_rdy = 39.2 s
3177        // ×3 = 117.6 s → 237.6 s. The old flat 120 s left ZERO boot
3178        // headroom for exactly this shape — the mid-attach VM-timeout
3179        // class from the scx verifier sweep.
3180        assert_eq!(verifier_vm_timeout(128), Duration::from_millis(237_600));
3181        // Structural: the headroom above the base is exactly the flat
3182        // dead-man term for any vcpu count (no cpuset read).
3183        for vcpus in [2u32, 128, 256] {
3184            assert_eq!(
3185                verifier_vm_timeout(vcpus) - VERIFIER_BASE_TIMEOUT,
3186                vm_boot_headroom(vcpus) * DEADMAN_HEADROOM_MULT,
3187            );
3188        }
3189        // The worst-case verifier deadline (widest realistic 256-vCPU
3190        // preset) plus the extend-only attach-reset extension must still
3191        // fit the 240s x 2 = 480s nextest verifier override.
3192        assert!(
3193            verifier_vm_timeout(256) + VERIFIER_WORKLOAD_BUDGET < Duration::from_secs(480),
3194            "worst-case verifier deadline (incl. attach-reset extension) \
3195             must fit the 240s x 2 nextest override",
3196        );
3197    }
3198
3199    // -- sys_rdy_budget_ms / vm_boot_headroom --
3200
3201    #[test]
3202    fn sys_rdy_budget_ms_base_plus_linear_per_vcpu() {
3203        // Additive: 10_000 ms base + vcpus × 150. Every topology gets
3204        // the base PLUS its per-vCPU term — no dead floor below 67
3205        // vCPUs (the bug that gave a 64-vCPU VM the same 10 s as a
3206        // 1-vCPU VM).
3207        assert_eq!(sys_rdy_budget_ms(1), 10_150);
3208        assert_eq!(sys_rdy_budget_ms(32), 14_800);
3209        assert_eq!(sys_rdy_budget_ms(66), 19_900);
3210    }
3211
3212    #[test]
3213    fn sys_rdy_budget_ms_scales_linearly_in_band() {
3214        // 10_000 ms base + vcpus × 150, in the band below the 90 s cap.
3215        assert_eq!(sys_rdy_budget_ms(67), 20_050);
3216        // The 126-vCPU case lands at 28.9 s.
3217        assert_eq!(sys_rdy_budget_ms(126), 28_900);
3218        // 256-vCPU wide-SMP gets its FULL additive budget (48.4 s) — the
3219        // case the old 30 s cap truncated to 30 s, starving the boot.
3220        assert_eq!(sys_rdy_budget_ms(256), 48_400);
3221    }
3222
3223    #[test]
3224    fn sys_rdy_budget_ms_caps_at_ninety_seconds() {
3225        // The 512-vCPU MAX_VCPUS topology gets its full additive budget
3226        // (10_000 + 512×150 = 86_800 ms), comfortably under the cap.
3227        assert_eq!(sys_rdy_budget_ms(512), 86_800);
3228        // 533 vCPUs is the last under the 90 s cap (10_000 + 533×150 =
3229        // 89_950); 534 is the first clipped (10_000 + 534×150 = 90_100
3230        // → 90_000). Only pathological >533-vCPU counts clip.
3231        assert_eq!(sys_rdy_budget_ms(533), 89_950);
3232        assert_eq!(sys_rdy_budget_ms(534), 90_000);
3233        assert_eq!(sys_rdy_budget_ms(u32::MAX), 90_000);
3234    }
3235
3236    #[test]
3237    fn sys_rdy_budget_ms_zero_returns_base() {
3238        // Guest fallback when /sys/devices/system/cpu/online is missing:
3239        // 0 vCPUs → the bare 10_000 ms base (no per-vCPU term).
3240        assert_eq!(sys_rdy_budget_ms(0), 10_000);
3241    }
3242
3243    #[test]
3244    fn vm_boot_headroom_is_ten_plus_sys_rdy_budget() {
3245        // KERNEL_INIT_HEADROOM (10 s) + sys_rdy_budget_ms(vcpus).
3246        assert_eq!(vm_boot_headroom(1), Duration::from_millis(20_150));
3247        assert_eq!(vm_boot_headroom(126), Duration::from_millis(38_900));
3248        // 256-vCPU wide-SMP: 10 s + 48.4 s = 58.4 s. Host overcommit
3249        // does not change this flat deadman component.
3250        assert_eq!(vm_boot_headroom(256), Duration::from_millis(58_400));
3251        // 512-vCPU MAX_VCPUS budget (86.8 s) → 96.8 s headroom, uncapped
3252        // under the 90 s ceiling.
3253        assert_eq!(vm_boot_headroom(512), Duration::from_millis(96_800));
3254    }
3255
3256    // -- phase_cpu_budget_ns / phase_wall_backstop_ns --
3257
3258    #[test]
3259    fn phase_cpu_budget_ns_boot_reuses_vm_boot_headroom() {
3260        const S: u64 = 1_000_000_000;
3261        // Boot consumes the same allowance as the VM deadline. The
3262        // remaining phases stay flat against max-per-vCPU evidence.
3263        assert_eq!(phase_cpu_budget_ns(0, 1), 20_150_000_000);
3264        assert_eq!(phase_cpu_budget_ns(0, 240), 56 * S);
3265        assert_eq!(
3266            phase_cpu_budget_ns(0, 240),
3267            vm_boot_headroom(240).as_nanos() as u64,
3268        );
3269        assert_eq!(phase_cpu_budget_ns(1, 1), 35 * S);
3270        assert_eq!(phase_cpu_budget_ns(1, 240), 35 * S);
3271        assert_eq!(phase_cpu_budget_ns(2, 1), 8 * S);
3272        assert_eq!(phase_cpu_budget_ns(2, 240), 8 * S);
3273        assert_eq!(phase_cpu_budget_ns(4, 1), 8 * S);
3274        assert_eq!(phase_cpu_budget_ns(4, 240), 8 * S);
3275    }
3276
3277    #[test]
3278    fn phase_cpu_budget_ns_body_and_unknown_are_sentinel() {
3279        // Body (3): Tier-1 structurally off — the sentinel makes any
3280        // `cpu > budget` comparison unsatisfiable.
3281        assert_eq!(phase_cpu_budget_ns(3, 240), u64::MAX);
3282        // Unknown phase ids never carry a killable budget.
3283        assert_eq!(phase_cpu_budget_ns(5, 240), u64::MAX);
3284        assert_eq!(phase_cpu_budget_ns(u8::MAX, 240), u64::MAX);
3285    }
3286
3287    #[test]
3288    fn phase_wall_backstop_ns_values_sit_above_in_band_deadlines() {
3289        const S: u64 = 1_000_000_000;
3290        assert_eq!(phase_wall_backstop_ns(0, 1), 45 * S);
3291        assert_eq!(phase_wall_backstop_ns(0, 240), 61 * S);
3292        assert_eq!(phase_wall_backstop_ns(0, 512), 101_800_000_000);
3293        for vcpus in [1, 240, 512] {
3294            assert!(
3295                phase_wall_backstop_ns(0, vcpus) > vm_boot_headroom(vcpus).as_nanos() as u64,
3296                "Boot Tier-2 must sit after the authoritative allowance at {vcpus} vCPUs",
3297            );
3298        }
3299        // Attach backstop must clear the host cold-BTF phase-1 budget.
3300        assert_eq!(phase_wall_backstop_ns(1, 1), 40 * S);
3301        assert!(phase_wall_backstop_ns(1, 512) > COLD_BTF_PHASE1_BUDGET.as_nanos() as u64);
3302        // Dispatch backstop must clear the guest probe's 30s cap.
3303        assert_eq!(phase_wall_backstop_ns(2, 1), 35 * S);
3304        assert_eq!(phase_wall_backstop_ns(4, 1), 15 * S);
3305    }
3306
3307    #[test]
3308    fn phase_wall_backstop_ns_body_and_unknown_are_sentinel() {
3309        // Body (3) and unknown ids: Tier-2 structurally off.
3310        assert_eq!(phase_wall_backstop_ns(3, 240), u64::MAX);
3311        assert_eq!(phase_wall_backstop_ns(5, 240), u64::MAX);
3312        assert_eq!(phase_wall_backstop_ns(u8::MAX, 240), u64::MAX);
3313    }
3314
3315    /// Two calls to `content_hash` with the same input must return
3316    /// the same u64. Pins the within-process determinism invariant
3317    /// against a future regression that swaps in a per-call-seeded
3318    /// hasher — e.g. `std::hash::RandomState::new().build_hasher()`,
3319    /// which increments its keys per call within a process, or any
3320    /// time/thread-id-seeded scheme. Note: swapping to std's
3321    /// `DefaultHasher::new()` would NOT regress this test —
3322    /// `DefaultHasher` is itself `SipHasher13::new_with_keys(0, 0)`
3323    /// and therefore deterministic; the cross-rustc-version
3324    /// stability regression class is caught by the value-pin
3325    /// follow-up, not this assertion.
3326    #[test]
3327    fn content_hash_is_deterministic_across_calls() {
3328        let input = "scheduler config payload";
3329        assert_eq!(content_hash(input), content_hash(input));
3330    }
3331
3332    /// Distinct inputs must produce distinct hashes. Catches a trivial
3333    /// regression (constant-returning hasher) that the determinism
3334    /// test alone would silently accept.
3335    #[test]
3336    fn content_hash_differs_for_distinct_inputs() {
3337        assert_ne!(content_hash("alpha"), content_hash("beta"));
3338    }
3339
3340    /// Cross-toolchain stability pin: every `content_hash` output must
3341    /// equal the SipHasher13(keys=0,0) value emitted at commit time.
3342    /// Pins the algorithm choice — a future swap to a different
3343    /// stable hasher (e.g. xxhash, fxhash) would silently regenerate
3344    /// every content-addressed cache filename on disk, breaking cache
3345    /// hit rates without surfacing as a failed test. The companion
3346    /// `content_hash_is_deterministic_across_calls` pin guards
3347    /// within-process determinism; this pin guards cross-process /
3348    /// cross-toolchain / cross-machine stability.
3349    #[test]
3350    fn content_hash_value_pin() {
3351        // SipHasher13(keys=0,0) over the four corpora below. If any
3352        // assertion fails, the algorithm or its seeding changed —
3353        // STOP. `content_hash` names the inline-config tempfile in
3354        // `config_content_parts` at src/test_support/runtime.rs and
3355        // the export-config tempfile in `export.rs`; flipping the
3356        // hashes silently regenerates those filenames on every
3357        // process, breaking any future scheme that tries to dedup
3358        // across runs and breaking intra-run reproducibility if a
3359        // caller comes to depend on stable byte equality across
3360        // identical inputs. Update only after intentional algorithm
3361        // migration. The four corpora — empty + two short ASCII +
3362        // one realistic config payload — span the cases the
3363        // algorithm needs to handle correctly.
3364        assert_eq!(content_hash(""), 0x30406ea523c53def);
3365        assert_eq!(content_hash("alpha"), 0x3c87f3c3317bd39a);
3366        assert_eq!(content_hash("beta"), 0xbb8fd2aa1487d7ac);
3367        assert_eq!(content_hash("scheduler config payload"), 0xc678971ba48d5f80);
3368    }
3369
3370    /// Per-content-hash inline-config files MUST land inside the
3371    /// per-process `scratch_dir()` subtree, NOT bare
3372    /// `std::env::temp_dir()`. The 0o700 process-owned subdirectory
3373    /// blocks the cross-uid symlink-replacement attack on
3374    /// predictable content-addressed filenames in shared `/tmp`. A
3375    /// future "simplification" that reverts the path to bare
3376    /// `std::env::temp_dir().join(...)` silently restores the
3377    /// attack surface; this test fails loudly first.
3378    #[test]
3379    fn config_content_parts_writes_inside_process_scratch_dir() {
3380        use crate::assert::Assert;
3381        use crate::scenario::Ctx;
3382        use crate::test_support::entry::{
3383            KtstrTestEntry, Scheduler, SchedulerSpec, TopologyConstraints,
3384        };
3385        use crate::vmm::topology::Topology;
3386
3387        static SCHED: Scheduler = Scheduler {
3388            name: "config_parts_test_sched",
3389            binary: SchedulerSpec::Discover("nope"),
3390            sysctls: &[],
3391            kargs: &[],
3392            assert: Assert::NO_OVERRIDES,
3393            cgroup_parent: None,
3394            sched_args: &[],
3395            topology: Topology {
3396                llcs: 1,
3397                cores_per_llc: 1,
3398                threads_per_core: 1,
3399                numa_nodes: 1,
3400                nodes: None,
3401                distances: None,
3402                llc_cores: None,
3403            },
3404            constraints: TopologyConstraints::DEFAULT,
3405            config_file: None,
3406            config_file_def: Some(("--config={file}", "/include-files/p.json")),
3407            kernels: &[],
3408            verifier_exclude_topologies: &[],
3409            manifest_dir: env!("CARGO_MANIFEST_DIR"),
3410        };
3411        fn func(_: &Ctx) -> anyhow::Result<crate::assert::AssertResult> {
3412            Ok(crate::assert::AssertResult::pass())
3413        }
3414        let entry = KtstrTestEntry {
3415            name: "scratch_dir_path_test",
3416            func,
3417            scheduler: &SCHED,
3418            config_content: Some("{\"sentinel\":42}"),
3419            ..KtstrTestEntry::DEFAULT
3420        };
3421        let (_, host_path, _, _) =
3422            config_content_parts(&entry).expect("config_content_parts returns Some");
3423        assert!(
3424            host_path.starts_with(scratch_dir()),
3425            "config tempfile must live inside the process-owned scratch dir, \
3426             not bare std::env::temp_dir(): got host_path={host_path:?}, \
3427             scratch_dir={:?}",
3428            scratch_dir()
3429        );
3430    }
3431
3432    /// Two same-content calls produce the SAME canonical path
3433    /// (content-addressed naming idempotence). Callers using the
3434    /// returned PathBuf for downstream dedup decisions rely on this
3435    /// — a regression that breaks the content-hash → path mapping
3436    /// would silently spam the scratch dir with per-call distinct
3437    /// names instead of reusing the canonical entry.
3438    #[test]
3439    fn config_content_parts_same_content_same_canonical_path() {
3440        use crate::assert::Assert;
3441        use crate::scenario::Ctx;
3442        use crate::test_support::entry::{
3443            KtstrTestEntry, Scheduler, SchedulerSpec, TopologyConstraints,
3444        };
3445        use crate::vmm::topology::Topology;
3446
3447        static SCHED: Scheduler = Scheduler {
3448            name: "config_parts_idempotent_sched",
3449            binary: SchedulerSpec::Discover("nope"),
3450            sysctls: &[],
3451            kargs: &[],
3452            assert: Assert::NO_OVERRIDES,
3453            cgroup_parent: None,
3454            sched_args: &[],
3455            topology: Topology {
3456                llcs: 1,
3457                cores_per_llc: 1,
3458                threads_per_core: 1,
3459                numa_nodes: 1,
3460                nodes: None,
3461                distances: None,
3462                llc_cores: None,
3463            },
3464            constraints: TopologyConstraints::DEFAULT,
3465            config_file: None,
3466            config_file_def: Some(("--config={file}", "/include-files/p.json")),
3467            kernels: &[],
3468            verifier_exclude_topologies: &[],
3469            manifest_dir: env!("CARGO_MANIFEST_DIR"),
3470        };
3471        fn func(_: &Ctx) -> anyhow::Result<crate::assert::AssertResult> {
3472            Ok(crate::assert::AssertResult::pass())
3473        }
3474        let entry = KtstrTestEntry {
3475            name: "idempotent_path_test",
3476            func,
3477            scheduler: &SCHED,
3478            config_content: Some("{\"idempotent\":true}"),
3479            ..KtstrTestEntry::DEFAULT
3480        };
3481        let (_, p1, _, _) = config_content_parts(&entry).expect("first call returns Some");
3482        let (_, p2, _, _) = config_content_parts(&entry).expect("second call returns Some");
3483        assert_eq!(
3484            p1, p2,
3485            "same content_content -> same canonical path; content-addressed naming \
3486             must be idempotent across calls"
3487        );
3488        // The filename component encodes the content hash via the
3489        // `ktstr-config-{hash:016x}.json` template; verify the prefix
3490        // so a future filename-template change is caught.
3491        let name = p1.file_name().and_then(|n| n.to_str()).unwrap_or("");
3492        assert!(
3493            name.starts_with("ktstr-config-") && name.ends_with(".json"),
3494            "canonical filename must follow `ktstr-config-{{hash}}.json` template, got: {name}"
3495        );
3496    }
3497}