ktstr/vmm/
result.rs

1//! Public [`VmResult`] returned from [`super::KtstrVm::run`], plus
2//! the internal [`VmRunState`] passed from `run_vm` to
3//! `collect_results` and the [`KvmStatsTotals`] aggregate of per-vCPU
4//! KVM counters.
5//!
6//! The split keeps the result-shaping types independent of the
7//! orchestration code (which still lives in [`super::KtstrVm`]). Test
8//! code outside `vmm/` constructs `VmResult` literals and reads
9//! `KvmStatsTotals` fields, so both types stay public; `VmRunState`
10//! is `pub(crate)`-only because it's an implementation detail of the
11//! run-then-collect handoff.
12
13use std::collections::HashMap;
14use std::sync::Arc;
15use std::sync::atomic::AtomicBool;
16use std::time::{Duration, Instant};
17
18use super::console;
19use super::host_comms::BulkDrainResult;
20use super::kvm;
21use super::pi_mutex::PiMutex;
22use super::vcpu::WatchpointArm;
23use super::virtio_blk::{VirtioBlkCounters, VirtioBlkCountersSnapshot};
24use super::virtio_net::{VirtioNetCounters, VirtioNetCountersSnapshot};
25use super::wire;
26use crate::monitor;
27
28/// Which watchdog rule (if any) killed the VM — the public mirror of
29/// the watchdog-internal `freeze_coord::KillReasonTag`, rendered as
30/// `cause=` in the deadline-expired stderr dump. `None` on
31/// [`VmResult::watchdog_kill_reason`] means no watchdog kill was
32/// recorded (clean exit, crash, or a timeout path that never stamped a
33/// reason).
34///
35/// The variant IS the mechanism assertion e2e fixtures need: a
36/// wedge-injection fixture proves its tier by matching the reason,
37/// which stays correct at ANY host dilation — unlike a wall-time bound,
38/// which conflates detection latency with host CPU share (an observed
39/// arm64 cell proved Tier-1 firing exactly on its 12 s CPU budget while
40/// taking 83 s of wall at ~14% share).
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub enum WatchdogKillReason {
43    /// Tier-1: max per-vCPU CPU burned past the phase budget with no
44    /// milestone — a spinning wedge.
45    Tier1CpuBudget,
46    /// Tier-2: wall past the phase backstop with live evidence channels
47    /// and no runnable demand — a silent idle wedge.
48    Tier2IdleWedge,
49    /// Tier-3: the hard deadline expired and the deadman was not deferred
50    /// (monitor dead, cell inert past the grace, or the current phase
51    /// exhausted the effective-deadline busiest-vCPU CPU budget).
52    Tier3Deadman,
53    /// An AP set the kill flag (panic-driven), not a watchdog expiry.
54    ApKill,
55    /// A scheduler attach consumed its host-measured service budget, then
56    /// failed to acknowledge the host's generation-tagged cancellation
57    /// within the fail-closed grace.
58    AttachCancelUnacknowledged,
59    /// The host monitor became terminal or was unavailable while a
60    /// scheduler attach attempt still owned the lifecycle watchdog.
61    AttachMonitorUnavailable,
62    /// The guest published scheduler-attach `Finished` but consumed the
63    /// delivered-service grace without completing the FinishedAck/Settled
64    /// rendezvous.
65    AttachFinishUnsettled,
66    /// A finite guest prerequisite consumed its delivered-service budget,
67    /// or the host sensor needed to account that budget became terminal.
68    ReadinessWaitFailed,
69}
70
71/// Final guest lifecycle stage as tracked by the progress ledger —
72/// the public mirror of `monitor::LifecycleStage` (same forward-only
73/// ordinal order, so `Ord` compares boot progress). Snapshotted at
74/// run teardown onto [`VmResult::final_guest_phase`].
75///
76/// Fixtures use this to distinguish "the guest reached the phase under
77/// test and the watchdog misfired" (a real detection regression) from
78/// "the guest never got there" (an environmental non-verdict: an
79/// observed arm64 cell at 0.3% host CPU share sat in `Boot` for 172 s —
80/// nothing phase-dependent can be asserted about a guest that could
81/// not boot).
82#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
83pub enum GuestLifecyclePhase {
84    /// Booting: init up to SYS_RDY.
85    Boot,
86    /// SYS_RDY seen; scheduler attaching.
87    Attach,
88    /// Guest dispatch entering the workload preamble.
89    Dispatch,
90    /// The test body / workload proper.
91    Body,
92    /// Winding down (`ScenarioEnd` / `Exit` / `TestResult` seen).
93    Teardown,
94}
95
96/// Result of a VM execution.
97///
98/// `Clone` is supported, but two field categories have different
99/// Clone semantics that callers must understand:
100///
101/// 1. **Pure-data fields** (the bulk of the struct): primitives,
102///    `String`, `Vec`, `Option<_>`, plus `MonitorReport` /
103///    `BulkDrainResult` / `ProgVerifierStats` / `StimulusEvent` /
104///    `KvmStatsTotals` / `VirtioBlkCountersSnapshot` /
105///    `VirtioNetCountersSnapshot`. Every clone produces an
106///    independent value — mutations to one do not affect the
107///    other. The `virtio_blk_counters` / `virtio_net_counters`
108///    fields are materialized `*CountersSnapshot` types (atomic
109///    loads done at construction time inside
110///    `super::KtstrVm::collect_results`), so clones cannot alias
111///    live device state.
112///
113/// 2. **Arc-shared handles** (`snapshot_bridge`, `stats_client`):
114///    these wrap `Arc<Mutex<…>>` / `Arc<AtomicUsize>` and clone via
115///    shallow refcount bump. Two `VmResult` clones SHARE the
116///    underlying store — calling `snapshot_bridge.drain()` on one
117///    clone empties the data visible to the other. See each
118///    field's own doc for the precise drain / iteration contract.
119///    If you need an independent snapshot view, drain into a local
120///    `Vec` before cloning the `VmResult`.
121///
122/// 3. **The capture-series cache** (`periodic_series_cache`): a
123///    `OnceLock<SampleSeries>` that memoizes the one destructive drain
124///    of the category-2 `snapshot_bridge` (see
125///    [`Self::captures_series`]). Its clone behavior depends on whether
126///    it is populated at clone time:
127///    - **Populated** (any of [`Self::captures_series`] /
128///      [`Self::periodic_series`] / [`Self::phase_buckets`] was already
129///      called): the clone carries an INDEPENDENT copy of the cached
130///      series — category-1 semantics. Both clones return the same
131///      captures without touching the (now-drained) shared bridge.
132///    - **Empty**: the clone shares the category-2 bridge, so the
133///      FIRST `captures_series()` call on EITHER clone performs the
134///      single drain and the other clone — if it later drains the same
135///      shared bridge — sees nothing. To give each clone its own
136///      buckets, call [`Self::captures_series`] (or any accessor that
137///      routes through it) on the original BEFORE cloning.
138#[derive(Debug, Clone)]
139pub struct VmResult {
140    /// Overall success flag: `true` when the test reported a pass AND
141    /// the VM exited cleanly without crash, timeout, or watchdog.
142    pub success: bool,
143    /// Guest vCPU count for this run (topology llcs*cores*threads),
144    /// carried from `KtstrVm` to the sidecar `(vcpus, cpu_budget)` stamp.
145    pub vcpus: u32,
146    /// Effective host-CPU budget the vCPU threads ran on; stamped to the
147    /// sidecar. Normally `KtstrVm::effective_cpu_budget` (the build-time
148    /// plan's CPU count), but the default-overcommit path (host too small
149    /// for a 1:1 pin) overrides it in `run()` with the actual masked
150    /// host-CPU count, since the build-time value assumes 1:1 pinning.
151    /// Below `vcpus` means host overcommit, which confounds the
152    /// guest-scheduler timing metrics.
153    pub cpu_budget: u32,
154    /// How the userspace scheduler binary was resolved for this run —
155    /// the snake_case `crate::test_support::ResolveSource::as_str` tag
156    /// (`"auto_built"`, `"target_debug"`, `"path"`, ...). Stamped by the
157    /// host eval layer (`run_ktstr_test_inner_impl`) AFTER the run,
158    /// alongside `entry_name` / `variant_hash`, then carried to the
159    /// sidecar `resolve_source` stamp the same way `vcpus` / `cpu_budget`
160    /// are. `None` for VmResults built outside the host eval path (the
161    /// freeze coordinator, test fixtures) — those resolve no scheduler
162    /// binary.
163    pub resolve_source: Option<String>,
164    /// True when the `#[ktstr_test(expect_auto_repro)]` attribute set
165    /// `expect_auto_repro = true` on the entry AND the auto-repro
166    /// path fired with a valid repro artifact during the run — the
167    /// signal that the verdict-flip from fail-with-artifact → PASS
168    /// is satisfied.
169    ///
170    /// The eval-layer derives this field AFTER `evaluate_vm_result`
171    /// returns (preserving the original `success` + error chain for
172    /// diagnostic visibility); the eval layer then wraps any
173    /// failure `Err` with the
174    /// `crate::test_support::eval::ExpectAutoReproSatisfied`
175    /// marker, and the dispatch arm
176    /// (`crate::test_support::dispatch::result_to_exit_code`)
177    /// downcasts the marker and routes the verdict to `EXIT_PASS`
178    /// without mutating the original `success` or stripping the
179    /// error chain. Pattern mirrors the `expect_err` matcher
180    /// inversion.
181    ///
182    /// Default `false`. When `expect_auto_repro = false` (the
183    /// macro-attribute default) the eval layer skips the artifact
184    /// probe entirely and leaves the field at `false`, so the
185    /// dispatch arm is never matched and the original verdict
186    /// stands.
187    pub expect_auto_repro_satisfied: bool,
188    /// Guest exit code as surfaced through the SHM ring
189    /// (`MSG_TYPE_EXIT`) or COM2 sentinel.
190    pub exit_code: i32,
191    /// Wall-clock duration of the VM run.
192    pub duration: Duration,
193    /// True when the host hit its watchdog before the guest exited.
194    pub timed_out: bool,
195    /// Which watchdog rule killed the VM (see [`WatchdogKillReason`]).
196    /// `None` when no watchdog kill was recorded — clean exits, but
197    /// also crash paths where the kill flag was never watchdog-set.
198    /// Loaded from the watchdog thread's kill-reason latch after its
199    /// join, so the value is final.
200    pub watchdog_kill_reason: Option<WatchdogKillReason>,
201    /// Final guest lifecycle stage per the progress ledger (see
202    /// [`GuestLifecyclePhase`]). Snapshotted at run teardown; stays
203    /// `Boot` when the guest never advanced (or no dispatch thread
204    /// consumed lifecycle frames — e.g. host-only paths).
205    pub final_guest_phase: GuestLifecyclePhase,
206    /// Final milestone count from the progress ledger (the dump's
207    /// `progress_epoch=` value): lifecycle-stage advances plus other
208    /// dispatch-recorded milestones. `0` means the guest never
209    /// published a milestone the host consumed.
210    pub final_progress_epoch: u64,
211    /// Whether the entry's host-triggered BPF-map-write injections
212    /// (`KtstrTestEntry::bpf_map_write` — e.g. the neg_* fixtures'
213    /// crash flag) were delivered: `None` when no writes were
214    /// configured, `Some(true)` when every queued write landed and the
215    /// guest was signalled, `Some(false)` when the injection thread
216    /// never completed (killed mid-retry — e.g. the run ended while a
217    /// starved guest was still booting/attaching). Fixtures that
218    /// expect an injected bug consult this to distinguish "the bug
219    /// never fired because the injection never landed" (environmental
220    /// under witnessed contention) from a real detection failure.
221    pub bpf_map_writes_delivered: Option<bool>,
222    /// Run-relative instant the periodic-capture prereqs (KASLR publish
223    /// and the map/prog accessors) became ready; `None` when they never
224    /// did. With [`Self::periodic_window_end`] this is the READINESS-VS-WINDOW
225    /// evidence: readiness at/after the window end (or never) makes zero
226    /// captures structurally inevitable at ANY host dilation — the
227    /// capture-starvation gates skip on it instead of a dilation
228    /// threshold (a ~7 s cold accessor build outruns a 4-5 s window at
229    /// D ≈ 1.2, below any honest contention bar).
230    pub periodic_prereqs_ready: Option<Duration>,
231    /// Run-relative instant the periodic capture window ends (the
232    /// workload-end clamp); `None` when the window never resolved —
233    /// which itself means no boundary could ever fire.
234    pub periodic_window_end: Option<Duration>,
235    /// Captured guest stdout (and any non-dmesg serial console content).
236    pub output: String,
237    /// Captured guest stderr (separated from `output` when the guest
238    /// reported them distinctly).
239    pub stderr: String,
240    /// Host-side monitor report: sampled per-CPU state, stuck
241    /// verdicts, and SCX event deltas. `None` when the monitor did
242    /// not run (host-only tests, early VM failure).
243    pub monitor: Option<monitor::MonitorReport>,
244    /// TLV messages drained from the guest after VM exit. Merges
245    /// mid-flight bytes the freeze coordinator pulled off
246    /// virtio-console port 1 during the run with the final port-1
247    /// `port1_tx_buf` flush.
248    pub guest_messages: Option<BulkDrainResult>,
249    /// BPF verifier stats collected from host-side memory reads.
250    pub verifier_stats: Vec<monitor::bpf_prog::ProgVerifierStats>,
251    /// KVM per-vCPU cumulative stats (requires Linux >= 5.14).
252    pub kvm_stats: Option<KvmStatsTotals>,
253    /// Crash message extracted from COM2 output via
254    /// `crate::test_support::extract_panic_message`. The guest
255    /// panic hook in `rust_init/init.rs` writes `PANIC: <info>\n<bt>\n`
256    /// to `/dev/ttyS1` synchronously inside `KVM_RUN`, so the host
257    /// captures the full backtrace in `output` even when the guest
258    /// is wedged. `None` when no `PANIC:`-prefixed line was seen.
259    pub crash_message: Option<String>,
260    /// Wall-clock time from BSP exit to the moment
261    /// `super::KtstrVm::collect_results` finishes assembling
262    /// [`VmResult`].
263    /// Records the host-side cost of every teardown step that runs
264    /// after the guest has stopped advancing: watchdog join, AP joins,
265    /// monitor join, BPF-writer join, SHM drain, exit/crash-message
266    /// extraction, and BPF verifier-stat read. Always `Some(_)` for
267    /// VMs whose `super::KtstrVm::run_vm` returns normally —
268    /// including the host-watchdog timeout path, because
269    /// `run_bsp_loop` exits cleanly with `timed_out = true` and
270    /// `collect_results` still executes, populating the field.
271    /// `None` only when `run_vm` does not complete (a BSP panic
272    /// propagated through `?`, or any pre-BSP setup error that
273    /// returns an `Err` before `VmRunState` is constructed) and on
274    /// the `test_fixture` / skip-sidecar paths that never boot a VM.
275    /// Persisted via
276    /// [`SidecarResult`](crate::test_support::SidecarResult) so stats
277    /// tooling can flag cleanup regressions across runs.
278    pub cleanup_duration: Option<Duration>,
279    /// The cleanup window's OWN dilation evidence: the join/drain
280    /// performer thread's schedstat delta (on-CPU + runnable-wait)
281    /// across exactly the [`Self::cleanup_duration`] window. The
282    /// cleanup-budget gate judges overruns against THIS — the
283    /// per-phase/whole-run witnesses cannot attest the window (the
284    /// monitor that feeds them is itself joined inside it, and join
285    /// wake-latency is a tail phenomenon a whole-run average
286    /// under-attests). `None` when schedstat was unreadable at either
287    /// edge; a `0` on-CPU delta (CONFIG_SCHEDSTATS off) is treated as
288    /// unattested by consumers.
289    pub cleanup_sched_delta: Option<HostVcpuSchedstat>,
290    /// Host-side virtio-blk device counters, snapshotted after the
291    /// guest has exited. `Some(_)` when the builder attached a disk
292    /// via `super::KtstrVmBuilder::disk`; `None` when no disk was
293    /// configured and `super::KtstrVm::init_virtio_blk` returned
294    /// `None`. The device increments its internal `AtomicU64`
295    /// counters from `drain_bracket_impl` (production cfg: on the
296    /// dedicated `ktstr-vblk` worker thread; cfg(test): inline on
297    /// the test thread); by the time `collect_results` constructs
298    /// the [`VmResult`] every vCPU and the worker have joined and
299    /// no further mutation can occur. The snapshot is taken at that
300    /// point — readers see plain `u64` fields holding the final
301    /// cumulative totals; no atomic load is needed on the consumer
302    /// side.
303    ///
304    /// The counter struct exposes nine `AtomicU64` fields, each
305    /// bumped from `drain_bracket_impl` (in `src/vmm/virtio_blk/drain.rs`)
306    /// via the `VirtioBlkCounters::record_*` helpers (defined in
307    /// `src/vmm/virtio_blk/counters.rs`). Per-request
308    /// cumulative counters, per-event cumulative counters, and
309    /// per-request live gauges are kept distinct per the
310    /// counter-taxonomy doc on `VirtioBlkCounters`:
311    ///
312    ///   - `reads_completed` — count of `VIRTIO_BLK_T_IN` requests
313    ///     that returned `S_OK` to the guest. Bumped together with
314    ///     `bytes_read` per `VirtioBlkCounters::record_read`.
315    ///   - `writes_completed` — count of `VIRTIO_BLK_T_OUT` requests
316    ///     that returned `S_OK`. Bumped together with `bytes_written`.
317    ///   - `flushes_completed` — count of `VIRTIO_BLK_T_FLUSH`
318    ///     requests that returned `S_OK` (real `fdatasync` for
319    ///     read-write disks, no-op for `read_only`).
320    ///   - `bytes_read` — total bytes returned to the guest for
321    ///     completed reads.
322    ///   - `bytes_written` — total bytes accepted from the guest for
323    ///     completed writes.
324    ///   - `throttled_count` — cumulative token-bucket **stall events**
325    ///     for the device's lifetime. The chain is rolled back and
326    ///     the worker arms a retry timerfd; the guest does not see
327    ///     `S_IOERR` for a stall (the request is deferred until the
328    ///     bucket refills). This counter is separate from `io_errors`
329    ///     so operators can distinguish "throttle bucket drained,
330    ///     request deferred" from "real IO problem". Per-event (NOT
331    ///     per-request): a single chain that stalls twice produces
332    ///     two bumps.
333    ///   - `io_errors` — every path that reports `S_IOERR`:
334    ///     spec violations, backend `pread`/`pwrite` errors,
335    ///     malformed chains, `add_used` failures.
336    ///     Stalls do not report `S_IOERR`; see `throttled_count`.
337    ///   - `currently_throttled_gauge` — **live gauge**: how many
338    ///     requests are RIGHT NOW waiting for throttle tokens.
339    ///     Increments when a chain transitions into stalled,
340    ///     decrements on retry success or reset. Bounded at 0 or 1
341    ///     on this single-queue device. NOT cumulative — answers
342    ///     "what's stuck now," distinct from `throttled_count`
343    ///     which answers "how many stall events happened over
344    ///     time."
345    ///   - `invalid_avail_idx_count` — cumulative count of
346    ///     `Error::InvalidAvailRingIndex` events observed by
347    ///     `drain_bracket_impl` (avail.idx more than `queue.size`
348    ///     ahead of `next_avail` — a virtio-v1.2 §2.7.13.3
349    ///     avail.idx-distance violation by the guest). Per-event
350    ///     counter; the `queue_poisoned` flag short-circuits
351    ///     subsequent kicks so one guest fault produces exactly
352    ///     one bump regardless of how many notifications follow
353    ///     before reset.
354    ///
355    /// Counters are cumulative for the device's lifetime. A guest
356    /// driver re-bind (writing `STATUS=0` to `VIRTIO_MMIO_STATUS`
357    /// triggers `VirtioBlk::reset`) does NOT zero them — the
358    /// device's internal `AtomicU64` storage persists across reset
359    /// cycles, and the post-exit snapshot captures the final
360    /// cumulative totals spanning the entire device lifetime, not
361    /// just a post-reset fragment.
362    ///
363    /// Reading example:
364    ///
365    /// ```ignore
366    /// let r: VmResult = builder.run()?;
367    /// let c = r.virtio_blk_counters.expect("disk attached");
368    /// assert!(c.reads_completed > 0);
369    /// ```
370    ///
371    /// `#[allow(dead_code)]`: the field is part of the public API
372    /// surface and read by user test code outside `lib.rs`, but the
373    /// lib build doesn't see any in-tree readers because no lib code
374    /// path calls `.virtio_blk_counters` on a `VmResult`. The in-tree
375    /// readers live in unit tests.
376    #[allow(dead_code)]
377    pub virtio_blk_counters: Option<VirtioBlkCountersSnapshot>,
378    /// Host-side virtio-net device counters, snapshotted after the
379    /// guest has exited — the cross-NIC AGGREGATE (field-wise
380    /// saturating sum via `VirtioNetCountersSnapshot::aggregate`) over
381    /// every attached NIC. `Some(_)` when the builder attached one or
382    /// more networks via `super::KtstrVmBuilder::network`; `None` when
383    /// no network was configured (the aggregate over an empty NIC set).
384    /// Each NIC's device increments its own `AtomicU64` counters on the
385    /// vCPU thread inside `process_tx_loopback`; by the time
386    /// `collect_results` constructs the [`VmResult`] every vCPU has
387    /// joined and no further mutation can occur. The per-NIC snapshots
388    /// are summed at that point — readers see plain `u64` fields holding
389    /// the final cumulative totals across all NICs; no atomic load is
390    /// needed on the consumer side. Per-NIC IRQ-delivery observability
391    /// comes from the per-CPU / per-IRQ metrics axis, not these
392    /// device-internal loopback counters.
393    ///
394    /// The counter struct exposes sixteen `AtomicU64` fields, each
395    /// bumped across the TX-drain path rooted at `process_tx_loopback`
396    /// (several are bumped inside the `pop_and_capture_tx` /
397    /// `try_loopback_to_rx` helpers it calls; the three `ctrl_*`
398    /// counters are bumped on the control-vq path, not the TX-drain
399    /// path):
400    ///
401    ///   - `tx_packets` — count of TX chains whose L2 frame was
402    ///     captured (`frame_len = Some`) AND whose TX `add_used`
403    ///     succeeded. Over-size-dropped and malformed chains are still
404    ///     marked used (so the guest doesn't hang) but do NOT advance
405    ///     `tx_packets`; a chain whose `add_used` fails advances
406    ///     `tx_add_used_failures` instead. So `tx_packets` advances per
407    ///     successfully-captured-and-published chain, not per parsed
408    ///     chain.
409    ///   - `tx_bytes` — bytes of L2 frame data captured from
410    ///     successfully parsed TX chains (excludes the 12-byte
411    ///     virtio header).
412    ///   - `rx_packets` / `rx_bytes` — count + bytes of RX chains
413    ///     successfully written and marked used. `rx_packets` and
414    ///     `tx_packets` gate INDEPENDENTLY per chain: `rx_packets`
415    ///     bumps when the loopback delivers — recorded BEFORE the TX
416    ///     `add_used` — while `tx_packets` bumps only when that later
417    ///     TX `add_used` succeeds. So the identity
418    ///     `rx_packets == tx_packets - tx_dropped_no_rx_buffer
419    ///     - tx_dropped_rx_poisoned` holds ONLY when both the RX-side
420    ///     failure counters AND `tx_add_used_failures` are zero:
421    ///     RX-side failures (`rx_add_used_failures`, `rx_chain_invalid`,
422    ///     `rx_write_failed`) make `rx_packets` fall SHORT of
423    ///     `tx_packets - drops`, while a `tx_add_used_failures` on a
424    ///     chain whose RX already delivered makes `rx_packets` EXCEED
425    ///       it. Asymmetric counts surface queue-state breakage on
426    ///       either side.
427    ///   - `tx_dropped_no_rx_buffer` — successfully-captured TX
428    ///     frames the device could not deliver because the RX queue
429    ///     was empty (transient back-pressure event).
430    ///   - `tx_dropped_rx_poisoned` — successfully-captured TX frames
431    ///     dropped because the RX queue was poisoned by a prior guest
432    ///     avail-ring violation (wedged until a virtio reset), as
433    ///     opposed to the transient empty-queue back-pressure counted
434    ///     by `tx_dropped_no_rx_buffer`.
435    ///   - `tx_chain_invalid` / `rx_chain_invalid` — chains rejected
436    ///     for malformed shape (short header, wrong direction,
437    ///     attacker-controlled descriptor address overflow).
438    ///   - `tx_oversize_dropped` — TX chains dropped (not truncated)
439    ///     because the captured post-header frame data exceeded the
440    ///     maximum L2 frame size the guest's `max_mtu` permits.
441    ///   - `rx_write_failed` — RX chain whose shape was valid but
442    ///     whose guest-memory `write_slice` (header or frame) hit
443    ///     an unmapped GPA. Distinct from `rx_chain_invalid` so an
444    ///     operator can tell "guest violated the RX descriptor-
445    ///     direction rule" from "guest posted a buffer at an
446    ///     unmapped GPA"; the two are mutually exclusive per chain.
447    ///   - `tx_add_used_failures` / `rx_add_used_failures` —
448    ///     `add_used` failures, indicating the queue's used-ring
449    ///     address itself is unmapped or otherwise inaccessible.
450    ///     Distinct from the `*_chain_invalid` / `rx_write_failed`
451    ///     counters so an operator can tell "guest sent malformed
452    ///     frame" / "guest's posted buffer GPA was unmapped" from
453    ///     "queue itself is broken".
454    ///   - `invalid_avail_idx_count` — cumulative count of
455    ///     `Error::InvalidAvailRingIndex` events observed by
456    ///     `process_tx_loopback` (avail.idx more than `queue.size`
457    ///     ahead of `next_avail` — virtio-v1.2 §2.7.13.3 violation
458    ///     by the guest). Per-event counter; the per-queue
459    ///     `queue_poisoned` flag short-circuits subsequent kicks
460    ///     so one guest fault produces exactly one bump regardless
461    ///     of how many notifications follow before reset.
462    ///   - `ctrl_mq_set` — cumulative count of successful control-vq
463    ///     `VIRTIO_NET_CTRL_MQ` / `VQ_PAIRS_SET` commands (the device
464    ///     updated `curr_queue_pairs` and wrote `VIRTIO_NET_OK`).
465    ///     Per-event counter.
466    ///   - `ctrl_chain_invalid` — cumulative count of control-vq
467    ///     chains the device could not satisfy: malformed shape (no
468    ///     device-writable status descriptor, too few readable command
469    ///     bytes), an unknown `(class, cmd)`, or a `virtqueue_pairs`
470    ///     outside `[1, queue_pairs]`. Per-event hostile/buggy-guest
471    ///     counter; the control-vq analog of `tx_chain_invalid`.
472    ///   - `ctrl_add_used_failures` — cumulative count of control-vq
473    ///     status-write or `add_used` failures (the status byte's GPA
474    ///     or the used-ring address is unmapped). Queue-state breakage
475    ///     distinct from `ctrl_chain_invalid`; the control-vq analog
476    ///     of `tx_add_used_failures`.
477    ///
478    /// Counters are cumulative for the device's lifetime — a guest
479    /// driver re-bind (writing `STATUS=0`) does NOT zero them.
480    #[allow(dead_code)]
481    pub virtio_net_counters: Option<VirtioNetCountersSnapshot>,
482    /// Snapshot bridge populated by the freeze coordinator over the
483    /// run's lifetime. Every `Op::CaptureSnapshot` and `Op::WatchSnapshot`
484    /// fire stores a `FailureDumpReport` keyed by its tag.
485    ///
486    /// `#[ktstr_test]` test bodies whose scenario fires snapshot
487    /// ops in the guest assert on the captured reports through a
488    /// `post_vm = NAME` attribute. The named callback runs on the
489    /// HOST after `vm.run()` returns (see
490    /// [`crate::test_support::KtstrTestEntry::post_vm`]) and
491    /// receives `&VmResult`; it calls
492    /// [`crate::scenario::snapshot::SnapshotBridge::drain`] on
493    /// this field to take ownership of the stored reports and
494    /// walks them — typically through
495    /// [`crate::scenario::snapshot::Snapshot::new`] for typed
496    /// access to map values, per-CPU entries, and scalar
497    /// variables. Out-of-tree consumers can drain the bridge the
498    /// same way: `VmResult` is in `ktstr::prelude`.
499    ///
500    /// Always present after a successful `run_vm`; `None`-equivalent
501    /// (empty) when the VM crashed before any snapshot fired.
502    ///
503    /// **Drained exactly once, via [`Self::captures_series`]**: the
504    /// bridge yields each capture once, so the host-side consumers
505    /// share a single drain. The first call to
506    /// [`Self::captures_series`] — whether from a `post_vm` callback
507    /// (which runs FIRST, via [`Self::periodic_series`] /
508    /// [`Self::phase_buckets`]) or from the framework's
509    /// `evaluate_vm_result` (which runs AFTER `post_vm` to build
510    /// [`crate::assert::ScenarioStats::phases`]) — drains this bridge
511    /// and memoizes the resulting
512    /// [`crate::scenario::sample::SampleSeries`] on the
513    /// `periodic_series_cache` field; every later call reads the
514    /// cache. That is why a per-phase `post_vm` and the framework's
515    /// `result.stats.phases` build no longer starve each other (a
516    /// `post_vm` that drained the bridge first used to leave
517    /// `stats.phases` empty). Integration tests under `tests/` that
518    /// bypass the series accessors and call
519    /// `result.snapshot_bridge.drain*()` directly (e.g.
520    /// `tests/stats_bridge_e2e.rs`, `tests/temporal_assertions_e2e.rs`)
521    /// are unaffected: the cache is only populated by
522    /// [`Self::captures_series`], which those tests never call, so the
523    /// raw destructive drain still returns the full capture set.
524    pub snapshot_bridge: crate::scenario::snapshot::SnapshotBridge,
525    /// Live scheduler-stats client. `Some(_)` when the run wired the
526    /// virtio-console port-2 stats bridge (the in-tree path always
527    /// does so, but tests that construct a [`VmResult`] manually via
528    /// `Self::test_fixture` leave this `None`). Test code that
529    /// asserts on scheduler-reported metrics calls
530    /// `super::SchedStatsClient::stats` /
531    /// `super::SchedStatsClient::stats_meta` on this handle WHILE
532    /// the guest is alive — calling after VM exit will time out
533    /// because the relay thread has already exited. Cloneable;
534    /// multiple test threads may share the same client.
535    #[allow(dead_code)]
536    pub stats_client: Option<super::SchedStatsClient>,
537    /// Number of periodic snapshot boundaries the freeze
538    /// coordinator actually fired during this run. Includes both
539    /// successful captures and rendezvous-timeout placeholders.
540    /// Tests can assert `result.periodic_fired >= some_lower_bound`
541    /// to guard periodic-capture coverage; mismatches against
542    /// [`Self::periodic_target`] flag missing samples (early VM
543    /// exit, kill-flag stop, abandoned-after-timeouts).
544    pub periodic_fired: u32,
545    /// Periodic captures that landed REAL BPF state — the
546    /// placeholder-excluded subset of [`Self::periodic_fired`]
547    /// (`periodic_fired` counts rendezvous-timeout placeholders as
548    /// fired). Snapshotted from
549    /// [`crate::scenario::snapshot::SnapshotBridge::periodic_real_count`]
550    /// at result-collection time so it is stable regardless of any
551    /// later test-side drain of the bridge. `periodic_real <
552    /// periodic_fired` means the gap is placeholder-only fills (the
553    /// boundary fired but the dump was degraded); the failure-output
554    /// periodic-samples section surfaces this so a "100% fired" run
555    /// whose captures were all placeholders does not read as full
556    /// coverage.
557    pub periodic_real: u32,
558    /// Configured `num_snapshots` count for the entry that drove
559    /// this run (mirrors the `KtstrTestEntry::num_snapshots` field
560    /// the entry was registered with). `0` when periodic capture
561    /// was disabled. Pairs with [`Self::periodic_fired`] so a
562    /// test can compute coverage without re-reading the entry
563    /// table.
564    pub periodic_target: u32,
565    /// Runtime virt-KASLR offset (kernel-image slide). Captured
566    /// from the freeze coordinator's `kern_virt_kaslr` Arc snapshot
567    /// at run-end via `load(Acquire).saturating_sub(1)`. `0` means
568    /// either (a) KASLR was off — test ran with
569    /// `#[ktstr_test(kaslr = false)]` or
570    /// `Scheduler::kargs(&["nokaslr"])`, OR (b) the derivation
571    /// chain (MSR_LSTAR readback in `vmm::x86_64::msr_kaslr` +
572    /// KERN_ADDRS `_text` path in `crate::vmm::freeze_coord::dispatch`) never
573    /// published a non-zero value (early-boot crash, kallsyms masked
574    /// by kptr_restrict, FRED-enabled kernel). E2E test consumers
575    /// distinguish (a) from (b) by reading the test entry's `kaslr`
576    /// attribute alongside this field — see
577    /// [`Self::kaslr_enabled`] for the binary-question companion.
578    pub kern_kaslr_offset: u64,
579    /// Name of the `#[ktstr_test]` fn whose execution produced this
580    /// result. Stamped from
581    /// `crate::test_support::entry::KtstrTestEntry::name` (a
582    /// `&'static str` the macro emits at compile time) in
583    /// `test_support::eval::run_ktstr_test_inner_impl` immediately
584    /// after `super::KtstrVm::run` returns and BEFORE the
585    /// `post_vm` callback dispatch runs.
586    ///
587    /// `Some(_)` for every result that flowed through the real
588    /// `run_ktstr_test_inner_impl` path. `None` for the
589    /// `freeze_coord::collect_results` direct-synthesis path
590    /// (entry-agnostic boundary; entry is not in scope there) and
591    /// for `#[cfg(test)]`-only `Self::test_fixture` callers. The
592    /// path-derivation methods `wprof_pb_path` and
593    /// `repro_wprof_pb_path` (require the `wprof` feature) bail with a loud diagnostic
594    /// on `None` so any `VmResult` reaching the derivation path
595    /// without going through the eval-layer stamping site
596    /// surfaces the misuse rather than producing a garbage-named
597    /// path.
598    ///
599    /// Test authors writing `post_vm` callbacks should derive
600    /// per-test sidecar paths via the helper methods rather than
601    /// hardcoding a `wprof_pb_path("<literal>")` string against
602    /// the fn name — a future rename of the test fn drifts the
603    /// hardcoded literal silently, where the method-form derives
604    /// from this field automatically.
605    pub entry_name: Option<&'static str>,
606    /// The run's variant hash (see `variant_hash_from_parts`),
607    /// stamped alongside [`Self::entry_name`] after `vm.run()` returns.
608    /// The post-VM `failure_dump_path` / `wprof_pb_path` derivations
609    /// embed it as the `-{16-hex}` filename suffix so a gauntlet test's
610    /// per-preset dumps don't clobber and each matches its sidecar's
611    /// variant hash. `0` on a synthesized/fixture result (which has
612    /// `entry_name = None` and thus bails before reading this).
613    pub variant_hash: u64,
614    /// Host-side vCPU scheduling dilation for this run — RAW schedstat
615    /// totals summed over the vCPU host threads (see
616    /// `HostVcpuSchedstat`). Populated by `run_vm` teardown from live
617    /// `/proc/self/task/<tid>/schedstat` entries plus a one-shot self-snapshot
618    /// each AP stores immediately before exit; `None` on hosts without
619    /// `CONFIG_SCHEDSTATS`, on synthesized/fixture results, and whenever no
620    /// vCPU thread was sampled. Consumers call `HostVcpuSchedstat::dilation`
621    /// for the derived `D` ratio. Purely observational — never affects the
622    /// verdict or exit code.
623    pub host_vcpu_schedstat: Option<HostVcpuSchedstat>,
624    /// Per-phase host-contention witness for the "weather witness" latency
625    /// model (see [`ContentionWitness`]): the Body-phase dilation `D` plus
626    /// the Body-phase peak-window CPU-pressure series that bounds `W(L)`.
627    /// Lifecycle events anchor the series and the monitor adds constant-cost
628    /// cgroup-PSI samples on its existing wakes. `None` when neither PSI nor
629    /// vCPU schedstat supplied evidence. Consumed by a LATER seam pass —
630    /// `latency_verdict` — to make latency threshold verdicts tri-state under
631    /// contention; purely observational until then.
632    pub contention_witness: Option<ContentionWitness>,
633    /// Memoized single drain of [`Self::snapshot_bridge`].
634    ///
635    /// The snapshot bridge yields each capture exactly once, but two
636    /// host-side consumers need the captures: a `post_vm` callback
637    /// (which runs first) and the framework's `evaluate_vm_result`
638    /// (which builds [`crate::assert::ScenarioStats::phases`]). Before
639    /// this cache existed, whichever drained first starved the other —
640    /// a per-phase `post_vm` calling [`Self::periodic_series`] left
641    /// `evaluate_vm_result` with an empty bridge, silently emptying
642    /// `result.stats.phases` and the failure-message timeline.
643    ///
644    /// [`Self::captures_series`] performs the one destructive bridge
645    /// drain on first call and stores the resulting full
646    /// [`crate::scenario::sample::SampleSeries`] here; every later call
647    /// — and [`Self::periodic_series`] / [`Self::phase_buckets`] /
648    /// `evaluate_vm_result` — reads the cached series instead of
649    /// re-draining. Lazily populated so a consumer that only touches
650    /// the raw bridge via `snapshot_bridge.drain*()` (e.g. integration
651    /// tests under `tests/`) is unaffected: the cache is never
652    /// initialised on that path.
653    ///
654    /// `pub(crate)` (not `pub`): in-crate constructors
655    /// (`freeze_coord::collect_results`, test fixtures) set it to an
656    /// empty `OnceLock`, but out-of-tree code cannot struct-literal a
657    /// `VmResult` — it flows from `run_vm` — so the cache stays an
658    /// implementation detail behind [`Self::captures_series`].
659    pub(crate) periodic_series_cache: std::sync::OnceLock<crate::scenario::sample::SampleSeries>,
660}
661
662impl VmResult {
663    /// Whether the guest kernel booted with KASLR enabled (= a
664    /// non-zero virt-KASLR offset published into the freeze
665    /// coordinator's `kern_virt_kaslr` Arc). Returns `true` when
666    /// [`Self::kern_kaslr_offset`] is non-zero. The inverse case
667    /// (returns `false`) covers two scenarios: (a) the test
668    /// explicitly opted out via `#[ktstr_test(kaslr = false)]` or
669    /// `Scheduler::kargs(&["nokaslr"])`, OR (b) the derivation
670    /// chain failed to publish a non-zero value (early-boot crash,
671    /// kallsyms masked, kernel built without `CONFIG_RANDOMIZE_BASE`).
672    /// E2E test consumers distinguish (a) from (b) by reading the
673    /// test entry's `kaslr` attribute alongside this method.
674    ///
675    /// Companion to [`Self::kern_kaslr_offset`] — use this when the
676    /// caller cares about the binary "did KASLR happen?" question
677    /// and use the raw field for exact-offset assertions
678    /// (alignment, entropy-range, etc.).
679    pub fn kaslr_enabled(&self) -> bool {
680        self.kern_kaslr_offset != 0
681    }
682
683    /// The full capture series for this run — every snapshot the
684    /// freeze coordinator stored on [`Self::snapshot_bridge`]
685    /// (periodic boundaries AND on-demand `Op::CaptureSnapshot` /
686    /// watchpoint-fire captures), in the order the bridge surfaced.
687    ///
688    /// Performs the bridge's single destructive drain on the first
689    /// call and memoizes the resulting
690    /// [`crate::scenario::sample::SampleSeries`] on the
691    /// `periodic_series_cache` field; every later call — and
692    /// [`Self::periodic_series`] / [`Self::phase_buckets`] and the
693    /// framework's `evaluate_vm_result` — returns the cached series
694    /// without re-draining. This is what lets a `post_vm` callback and
695    /// the framework's [`crate::assert::ScenarioStats::phases`] build
696    /// share one drain instead of starving each other (the bridge
697    /// yields each capture exactly once).
698    ///
699    /// Takes `&self`: the cache uses interior mutability
700    /// ([`std::sync::OnceLock`]) so this composes with the
701    /// `#[ktstr_test(post_vm = ...)]` callback signature
702    /// (`fn(&VmResult) -> Result<()>`).
703    ///
704    /// A consumer that calls `snapshot_bridge.drain*()` directly
705    /// (e.g. integration tests under `tests/`) bypasses this cache. If
706    /// such a raw drain runs BEFORE the first `captures_series()` call
707    /// the cache memoizes an empty series, so prefer this accessor over
708    /// a raw drain on any path that also reaches `evaluate_vm_result`.
709    pub fn captures_series(&self) -> &crate::scenario::sample::SampleSeries {
710        self.periodic_series_cache.get_or_init(|| {
711            crate::scenario::sample::SampleSeries::from_drained_typed(
712                self.snapshot_bridge.drain_ordered_with_stats(),
713                self.monitor.clone(),
714            )
715        })
716    }
717
718    /// The periodic-capture-only view of this run's series: the
719    /// `"periodic_"`-tagged subset of [`Self::captures_series`] — the
720    /// projection the temporal-assertion / per-phase patterns expect
721    /// (on-demand `Op::CaptureSnapshot` and watchpoint-fire captures
722    /// are filtered out as off-cadence outliers, see
723    /// [`crate::scenario::sample::SampleSeries::periodic_only`]).
724    ///
725    /// Reads the shared [`Self::captures_series`] cache (the single
726    /// bridge drain) and returns an owned, periodic-only clone.
727    /// Idempotent: calling it twice — or alongside
728    /// [`Self::phase_buckets`] / `evaluate_vm_result` — no longer
729    /// empties the bridge for the other consumers (the pre-cache
730    /// behavior, which silently starved whichever drained second).
731    ///
732    /// Takes `&self` so it composes with the
733    /// `#[ktstr_test(post_vm = ...)]` callback signature.
734    pub fn periodic_series(&self) -> crate::scenario::sample::SampleSeries {
735        self.captures_series().clone().periodic_only()
736    }
737
738    /// The complete per-phase stimulus timeline for `post_vm`
739    /// callbacks doing per-phase metric assertions: one
740    /// [`crate::timeline::StimulusEvent`] per guest `Stimulus` frame
741    /// (the step-start boundaries, via
742    /// [`crate::timeline::StimulusEvent::from_wire`]) PLUS the
743    /// synthesized terminal scenario-end boundary (from the
744    /// `ScenarioEnd` frame's final cumulative count, via
745    /// [`crate::timeline::StimulusEvent::terminal`]).
746    ///
747    /// Fold THIS through
748    /// [`crate::assert::build_phase_buckets_with_stimulus`] to reproduce the
749    /// same phase windows and boundary telemetry as `evaluate_vm_result`.
750    /// Iteration rates are joined separately from guest CPU-time carriers.
751    ///
752    /// Non-destructive: reads the already-drained `guest_messages` TLV
753    /// log (unlike the bridge-cache accessors [`Self::captures_series`]
754    /// / [`Self::periodic_series`] / [`Self::phase_buckets`], which
755    /// perform the single destructive snapshot-bridge drain), so it may
756    /// be called alongside the bridge drain. CRC-bad / malformed frames
757    /// are skipped.
758    pub fn stimulus_timeline(&self) -> Vec<crate::timeline::StimulusEvent> {
759        let mut out = Vec::new();
760        let Some(bulk) = &self.guest_messages else {
761            return out;
762        };
763        for entry in &bulk.entries {
764            if !entry.crc_ok {
765                continue;
766            }
767            match wire::MsgType::from_wire(entry.msg_type) {
768                Some(wire::MsgType::Stimulus) => {
769                    if let Some(ev) = wire::StimulusEvent::from_payload(&entry.payload) {
770                        out.push(crate::timeline::StimulusEvent::from_wire(&ev));
771                    }
772                }
773                Some(wire::MsgType::StepEnd) => {
774                    // Per-step end-of-hold frame (reuses the StimulusPayload
775                    // body). Retained as raw boundary telemetry.
776                    if let Some(ev) = wire::StimulusEvent::from_payload(&entry.payload) {
777                        out.push(crate::timeline::StimulusEvent::from_step_end(&ev));
778                    }
779                }
780                Some(wire::MsgType::ScenarioEnd) => {
781                    if let Some((elapsed_ms, total_iterations)) =
782                        wire::parse_scenario_end(&entry.payload)
783                    {
784                        out.push(crate::timeline::StimulusEvent::terminal(
785                            elapsed_ms,
786                            total_iterations,
787                        ));
788                    }
789                }
790                _ => {}
791            }
792        }
793        out
794    }
795
796    /// Worker-iteration efficiency (iterations per delivered guest CPU-second)
797    /// for one scenario [`Phase`](crate::assert::Phase).
798    ///
799    /// This is an ergonomic alias for the canonical per-phase
800    /// `iteration_rate`; it is not a second wall-throughput calculation.
801    /// Both the iteration numerator and delivered-CPU denominator come from
802    /// the same guest per-cgroup phase carriers, so host preemption does not
803    /// dilute the result.
804    ///
805    /// `None` when the phase has no guest carrier or its workers accumulated
806    /// no measurable CPU time. A measured zero iteration count over positive
807    /// CPU time returns `Some(0.0)`.
808    pub fn step_throughput(&self, phase: crate::assert::Phase) -> Option<f64> {
809        Self::step_throughput_in(&self.phase_buckets(), phase)
810    }
811
812    /// Ratio `step_throughput(a) / step_throughput(b)` — e.g.
813    /// scheduler-vs-EEVDF iteration efficiency when phase `b` runs on the detached
814    /// kernel default ([`crate::scenario::ops::Op::detach_scheduler`]).
815    /// Builds the canonical phase buckets once. `None` when either phase has
816    /// no measurable rate; a `Some(0.0)` denominator yields `inf` so a stalled
817    /// phase `b` surfaces rather than vanishing to `None`.
818    pub fn throughput_ratio(
819        &self,
820        a: crate::assert::Phase,
821        b: crate::assert::Phase,
822    ) -> Option<f64> {
823        let buckets = self.phase_buckets();
824        let ta = Self::step_throughput_in(&buckets, a)?;
825        let tb = Self::step_throughput_in(&buckets, b)?;
826        Some(ta / tb)
827    }
828
829    /// Shared core for [`Self::step_throughput`] / [`Self::throughput_ratio`]
830    /// over already-built canonical phase buckets.
831    fn step_throughput_in(
832        buckets: &[crate::assert::PhaseBucket],
833        phase: crate::assert::Phase,
834    ) -> Option<f64> {
835        buckets
836            .iter()
837            .find(|b| b.step_index == phase.as_u16())
838            .and_then(|b| b.get("iteration_rate"))
839    }
840
841    /// The guest-side [`crate::assert::AssertResult`] decoded from this
842    /// run's `MSG_TYPE_TEST_RESULT` frame — the verdict the in-VM scenario
843    /// body produced, carrying the per-phase per-cgroup raw telemetry
844    /// carriers in `stats.phases[].per_cgroup`
845    /// ([`crate::assert::PhaseCgroupStats`]: `total_migrations`,
846    /// `run_delays_ns`, `cpus_used`, …) and the per-cgroup reductions in
847    /// `stats.cgroups`.
848    ///
849    /// Non-destructive: reads the already-drained `guest_messages` TLV log
850    /// (the last crc-ok `MSG_TYPE_TEST_RESULT` entry), so it composes with
851    /// the snapshot-bridge accessors and may be called repeatedly. Shares
852    /// the exact decode the eval layer uses
853    /// (`crate::test_support::parse_assert_result_from_drain`).
854    ///
855    /// `Err` when there is no guest verdict to decode — a host-only run, a
856    /// crash before the body emitted its result, or a drain with no
857    /// `MSG_TYPE_TEST_RESULT` frame.
858    ///
859    /// This is the GUEST view: the run-level distribution / `ext_metrics`
860    /// re-pools (`worst_*` wake-latency / run-delay aggregates, pooled
861    /// `iteration_rate`) are applied HOST-side in `evaluate_vm_result`
862    /// AFTER the body returns and are NOT on this value — only
863    /// `stats.phases[].per_cgroup` and the per-cgroup `stats.cgroups`
864    /// reductions are guest-authoritative. For the per-phase per-cgroup view
865    /// aligned to the host capture windows use [`Self::phase_buckets`] (which
866    /// folds these carriers in); for one cgroup in one phase use
867    /// [`Self::phase_cgroup`].
868    pub fn guest_assert_result(&self) -> anyhow::Result<crate::assert::AssertResult> {
869        crate::test_support::parse_assert_result_from_drain(self.guest_messages.as_ref())
870    }
871
872    /// The framework-computed per-phase metric buckets for this run — the
873    /// SAME [`crate::assert::PhaseBucket`] vec the framework folds onto
874    /// [`crate::assert::ScenarioStats::phases`] in `evaluate_vm_result`,
875    /// INCLUDING the per-phase per-cgroup carriers in
876    /// [`crate::assert::PhaseBucket::per_cgroup`].
877    ///
878    /// This is the answer to "my `post_vm` callback wants the per-phase
879    /// metrics the framework already built." It folds the same two sources
880    /// `evaluate_vm_result` does:
881    /// 1. the host-rebuilt buckets from [`Self::periodic_series`] (the
882    ///    periodic-only projection of the shared single drain — on-demand /
883    ///    watchpoint captures are off-cadence outliers excluded from
884    ///    per-phase folds) through
885    ///    [`crate::assert::build_phase_buckets_with_stimulus`] using
886    ///    [`Self::stimulus_timeline`] for the step windows (window + metric
887    ///    folds; `per_cgroup` empty by construction); and
888    /// 2. the guest per-cgroup carriers from [`Self::guest_assert_result`]
889    ///    (`stats.phases[].per_cgroup`), folded in by
890    ///    `crate::assert::fold_guest_per_cgroup_into_host_buckets` keyed by
891    ///    `step_index` (the host window + metrics win; each carrier
892    ///    contributes only its `per_cgroup`, an unmatched carrier surfacing
893    ///    as a `(0,0)`-window orphan bucket).
894    ///
895    /// Production builds `stats.phases` from these same two sources (same
896    /// periodic-only series, same stimulus timeline, same guest carriers) and
897    /// the eval layer's later `populate_run_*` passes write only
898    /// `stats.ext_metrics` / `stats.cgroups`, never `phases[].per_cgroup`, so
899    /// this returns content IDENTICAL to `result.stats.phases` — the
900    /// no-carrier case pinned by
901    /// `phase_buckets_equals_stats_phases_and_post_vm_read_does_not_starve`
902    /// and the with-per-cgroup-carrier case by
903    /// `phase_buckets_equals_stats_phases_with_guest_per_cgroup_carriers`.
904    ///
905    /// Both sources are non-destructive on the snapshot bridge:
906    /// [`Self::periodic_series`] reads the memoized single drain
907    /// ([`Self::captures_series`]) and [`Self::guest_assert_result`] reads the
908    /// already-drained `guest_messages`. A run with no guest verdict
909    /// ([`Self::guest_assert_result`] `Err` — host-only / early crash) folds
910    /// no carriers and returns the host-rebuilt buckets alone (the prior
911    /// behavior).
912    pub fn phase_buckets(&self) -> Vec<crate::assert::PhaseBucket> {
913        let mut buckets = self.phase_buckets_pre_derive();
914        // Derive the per-phase scalars into the now-final (post-fold) buckets so
915        // a per-phase A/B claim reads them via phase_metric / phase_cgroup_metric:
916        // the non-schbench carrier scalars (every cgroup) into each pc.metrics,
917        // and the schbench scalars into pc.metrics + the pooled bucket.metrics.
918        // A no-op only when no phase carries a per-cgroup carrier; must run
919        // post-fold (the merge skips is_derived keys, so an earlier derive would
920        // be dropped).
921        crate::assert::derive_phase_metrics(&mut buckets);
922        buckets
923    }
924
925    /// The pre-`derive_phase_metrics` phase fold: host buckets from
926    /// [`Self::periodic_series`] + [`Self::stimulus_timeline`] with the guest
927    /// per-cgroup carriers folded in, BEFORE the per-phase scalar derivation
928    /// [`Self::phase_buckets`] applies. This is the exact phase state the eval
929    /// layer feeds to [`crate::assert::populate_run_ext_all`].
930    /// [`Self::run_metric`] reuses it, and that helper performs the same
931    /// idempotent phase derivation as the eval path before folding run metrics.
932    /// Non-destructive on the snapshot bridge, like [`Self::phase_buckets`].
933    fn phase_buckets_pre_derive(&self) -> Vec<crate::assert::PhaseBucket> {
934        let host = crate::assert::build_phase_buckets_with_stimulus(
935            &self.periodic_series(),
936            &self.stimulus_timeline(),
937        );
938        match self.guest_assert_result() {
939            Ok(guest) => {
940                crate::assert::fold_guest_per_cgroup_into_host_buckets(host, guest.stats.phases)
941            }
942            Err(_) => host,
943        }
944    }
945
946    /// One phase's per-cgroup telemetry for `cgroup` — the per-phase analog
947    /// of reading `result.stats.cgroups` for a single phase. Reads
948    /// [`Self::phase_buckets`] (which folds the guest per-cgroup carriers
949    /// against the host capture windows) and returns the
950    /// [`crate::assert::PhaseCgroupStats`] keyed by `cgroup` in `phase`.
951    ///
952    /// `None` when `phase` has no bucket (no capture landed in it AND no
953    /// stimulus `StepStart` synthesized one) or the phase carries no carrier
954    /// for `cgroup` (the cgroup ran no workers in that phase, or the run had
955    /// no step-local cgroups). Owned (cloned from the folded bucket) so it
956    /// composes with the `&VmResult` `post_vm` callback signature.
957    pub fn phase_cgroup(
958        &self,
959        phase: crate::assert::Phase,
960        cgroup: &str,
961    ) -> Option<crate::assert::PhaseCgroupStats> {
962        self.phase_buckets()
963            .into_iter()
964            .find(|b| b.step_index == phase.as_u16())
965            .and_then(|b| b.per_cgroup.get(cgroup).cloned())
966    }
967
968    /// One framework-computed per-phase metric for `phase` — the
969    /// general metric-name form of [`Self::step_throughput`] /
970    /// [`Self::throughput_ratio`]. Resolves `metric` (any `impl Into<MetricId>` —
971    /// a typed `BuiltinMetric`, typo-proof, or a dynamic scheduler-runtime
972    /// string) from the folded
973    /// [`Self::phase_buckets`] bucket for `phase`, checking two stores:
974    /// 1. [`crate::assert::PhaseBucket::metrics`] (via
975    ///    [`crate::assert::PhaseBucket::get`]) — the host-folded
976    ///    per-sample / monitor / guest-carrier metrics: per-phase CPU time
977    ///    (`system_time_ns`, `user_time_ns`), scheduling quality
978    ///    (`avg_imbalance_ratio`, `avg_dsq_depth`, ...), and
979    ///    `iteration_rate`.
980    /// 2. failing that, the cross-cgroup phase sum of a per-cgroup Counter
981    ///    ([`crate::assert::PhaseBucket::cgroup_counter_total`]) for the
982    ///    keys whose value lives ONLY in the per-cgroup carriers —
983    ///    `"total_migrations"`, `"total_iterations"`, and
984    ///    `"total_cpu_time_ns"`. These are
985    ///    registered `Counter`s with no per-sample source
986    ///    (`crate::stats::MetricDef::read_sample` returns `None`), so
987    ///    they never reach `metrics`; without this fallback
988    ///    `phase_metric(phase, "total_migrations")` returned a silent
989    ///    `None` even though the value was present per-cgroup.
990    ///
991    /// The wake-latency / run-delay distributions (`MetricKind::Distribution`)
992    /// have no per-phase `metrics` value and no single per-cgroup Counter
993    /// (they re-pool run-level from the per-cgroup raw sample vectors), so
994    /// they are not readable here — read them per-cgroup via
995    /// [`Self::phase_cgroup`].
996    ///
997    /// Reads the SAME buckets [`Self::phase_buckets`] folds onto
998    /// `result.stats.phases`, so a `post_vm` callback can compare any
999    /// metric across two phases (e.g. scheduler-vs-detached-EEVDF
1000    /// `total_migrations` or `system_time_ns`) without re-deriving the
1001    /// buckets — the general form of the scheduler-vs-EEVDF throughput
1002    /// compare.
1003    ///
1004    /// `None` when `phase` has no bucket — no capture landed in it AND no
1005    /// stimulus `StepStart` synthesized one (e.g. `Phase::BASELINE` when
1006    /// the settle window fired no captures, or a `phase` past the last
1007    /// step) — or the bucket carries no reading for `metric` in either
1008    /// store. Sentinel-free, distinct from a real `Some(0.0)`: a
1009    /// per-cgroup counter returns `Some(0.0)` when carriers exist but
1010    /// counted zero, `None` only when the phase has no carrier at all. A
1011    /// started-but-uncaptured step (a `StepStart` with zero captures) DOES
1012    /// produce a synthesized bucket, and `phase_metric` can still return its
1013    /// guest-carrier-derived `iteration_rate`.
1014    ///
1015    /// ```ignore
1016    /// // Typed (typo-proof) is the primary form; a dynamic scheduler-runtime
1017    /// // string is the escape hatch through the SAME call.
1018    /// let p99 = result.phase_metric(Phase::step(0), BuiltinMetric::WakeupP99LatencyUs);
1019    /// let custom = result.phase_metric(Phase::step(0), "scx_layered_layer0_util");
1020    /// ```
1021    pub fn phase_metric(
1022        &self,
1023        phase: crate::assert::Phase,
1024        metric: impl Into<crate::stats::MetricId>,
1025    ) -> Option<f64> {
1026        let metric = metric.into();
1027        self.phase_buckets()
1028            .into_iter()
1029            .find(|b| b.step_index == phase.as_u16())
1030            .and_then(|b| {
1031                b.get(metric.as_str())
1032                    .or_else(|| b.cgroup_counter_total(metric.as_str()))
1033            })
1034    }
1035
1036    /// One run-level extensible ("ext") metric by name — the whole-run analog of
1037    /// [`Self::phase_metric`], for a `post_vm` callback asserting a run-level
1038    /// aggregate (e.g. `avg_irq_util`, `max_cpu_hardirqs`,
1039    /// `worst_p99_wake_latency_us`, `iteration_rate`). SELF-COMPUTES the
1040    /// run-level `ext_metrics` map exactly as the framework's `evaluate_vm_result`
1041    /// does — a [`VmResult`](Self) carries no stored run-level stats (`post_vm`
1042    /// runs BEFORE the host populates them) — by replaying the shared
1043    /// [`crate::assert::populate_run_ext_all`] sequence over
1044    /// [`Self::periodic_series`], the pre-derive phase fold
1045    /// (`phase_buckets_pre_derive`), and the guest per-cgroup `stats.cgroups`.
1046    /// The result is byte-identical to the run-level `ext_metrics` the sidecar
1047    /// records for this run.
1048    ///
1049    /// Resolves the ext-sourced family that
1050    /// [`crate::assert::ScenarioStats::run_metric`] (the post-merge host
1051    /// accessor) resolves — the `read_sample`-wired registry metrics, the
1052    /// phase-only ext metrics (`avg_imbalance_ratio`, `iteration_rate`,
1053    /// `system_time_ns`, `user_time_ns`, the IRQ counters/rates, the per-CPU
1054    /// spatial maxes `max_cpu_hardirqs` / `max_cpu_softirq_net_rx` and their
1055    /// concentrations), the pooled `iteration_rate`, and the run-level
1056    /// `Distribution` / `WorstLowest` / `WakeLatencyTailRatio` / `WorstCrossNodeRatio`
1057    /// re-pools — and for
1058    /// those keys the two accessors return identical values (this one
1059    /// self-computes pre-merge, the other reads the stored post-merge map).
1060    ///
1061    /// ADDITIONALLY resolves the 5 ext-only run-level MONITOR metrics from
1062    /// [`Self::monitor`]'s summary: `avg_nr_running`, `avg_irq_util`,
1063    /// `max_avg_irq_util`, `psi_irq_full_avg10`, `total_irq_pressure_us` (folded
1064    /// via `MonitorSummary::fold_run_level_ext`, shared with the sidecar row).
1065    /// These DIVERGE from [`crate::assert::ScenarioStats::run_metric`], which has
1066    /// no `MonitorReport` to fold and returns `None` for them — the one place the
1067    /// two accessors differ.
1068    ///
1069    /// RESOLVED here None-aware (via the delegated `ScenarioStats::run_metric`
1070    /// typed dispatch): the cross-cgroup metrics `worst_spread`,
1071    /// `worst_migration_ratio`, `worst_gap_ms`, `total_migrations`,
1072    /// `total_iterations`, `worst_page_locality`,
1073    /// `worst_cross_node_migration_ratio`. The dispatch re-derives each from the
1074    /// carriers (the per-cgroup `stats.cgroups` + the per_cgroup-folded
1075    /// `stats.phases` this method builds) — `None` when no carrier measured it,
1076    /// `Some(0.0)` for a measured zero. The 5 non-NUMA metrics are 0.0-sentinel
1077    /// typed struct fields (re-derived because the field cannot carry the
1078    /// measured-vs-unmeasured distinction); the two NUMA roll-ups
1079    /// (`worst_page_locality`, `worst_cross_node_migration_ratio`) have no struct
1080    /// field and re-pool purely from the per-phase NUMA carriers.
1081    ///
1082    /// NOT resolved here:
1083    /// - the typed-backed monitor run-level metrics (`max_imbalance_ratio`,
1084    ///   `max_dsq_depth`, `stuck_count`, `total_fallback`, `total_keep_last`) —
1085    ///   these have typed `GauntletRow` fields (not ext-only); read them
1086    ///   per-phase via [`Self::phase_metric`].
1087    ///
1088    /// Sentinel-free, matching [`Self::phase_metric`]: `None` means the metric is
1089    /// absent from this run (no populator produced it, or a name not in the map);
1090    /// `Some(0.0)` is a real measured zero. Check [`crate::stats::MetricId::def`]
1091    /// on a dynamic key to distinguish an unregistered key from genuinely-absent
1092    /// data (built-in ids always resolve).
1093    ///
1094    /// A host-only run (no guest verdict — [`Self::guest_assert_result`] `Err`)
1095    /// resolves the SampleSeries + phase families but no per-cgroup pooled /
1096    /// distribution keys (no per-cgroup data exists), the same absence
1097    /// [`crate::assert::ScenarioStats::run_metric`] documents.
1098    ///
1099    /// Non-destructive: reads the memoized snapshot-bridge drain
1100    /// ([`Self::periodic_series`] / [`Self::phase_buckets`]) and the
1101    /// already-drained `guest_messages`, so it composes with [`Self::phase_metric`]
1102    /// in one `post_vm` callback.
1103    ///
1104    /// ```ignore
1105    /// let irq = result.run_metric(BuiltinMetric::AvgIrqUtil);
1106    /// let custom = result.run_metric("scx_layered_layer0_util");
1107    /// ```
1108    pub fn run_metric(&self, metric: impl Into<crate::stats::MetricId>) -> Option<f64> {
1109        let metric = metric.into();
1110        let mut stats = crate::assert::ScenarioStats {
1111            phases: self.phase_buckets_pre_derive(),
1112            cgroups: self
1113                .guest_assert_result()
1114                .map(|g| g.stats.cgroups)
1115                .unwrap_or_default(),
1116            ..Default::default()
1117        };
1118        crate::assert::populate_run_ext_all(&mut stats, &self.periodic_series());
1119        // Fold the run-level ext-only monitor metrics (avg_nr_running + the PELT
1120        // IRQ load pair + the PSI-irq pair) from the stored MonitorReport
1121        // summary. populate_run_ext_all can't produce them — they're
1122        // MonitorSummary-sourced, not phase/series-folded — but VmResult holds
1123        // self.monitor, so (unlike ScenarioStats::run_metric, which has no
1124        // monitor) this accessor CAN resolve them. Shared with
1125        // group::sidecar_to_row via fold_run_level_ext.
1126        if let Some(report) = self.monitor.as_ref() {
1127            report.summary.fold_run_level_ext(&mut stats.ext_metrics);
1128        }
1129        // Delegate to ScenarioStats::run_metric: it resolves the typed
1130        // 0.0-sentinel cross-cgroup fields None-aware from the carriers
1131        // (stats.cgroups + the per_cgroup-folded stats.phases, both populated
1132        // above) ahead of the ext lookup — so the typed fields resolve here too,
1133        // matching ScenarioStats::run_metric. The monitor metrics folded into
1134        // stats.ext_metrics above resolve via that method's ext fallback.
1135        stats.run_metric(metric)
1136    }
1137
1138    /// Polarity-aware "is the `candidate` phase better than the `baseline` phase
1139    /// on `metric`?" comparator — the per-phase A/B primitive for "assert
1140    /// scheduler X beats EEVDF across phases" (e.g. an scx Step vs the EEVDF
1141    /// Step after `Op::DetachScheduler`). Resolves both per-phase values via
1142    /// [`Self::phase_metric`] and the metric's polarity via
1143    /// `crate::stats::metric_def`, then returns a
1144    /// [`crate::assert::temporal::BetterThanPhase`] builder whose terminal
1145    /// (`better_than` / `by_at_least`) records the outcome into `verdict`.
1146    /// "Better" is oriented from the registry polarity, so the SAME call works
1147    /// for a LowerBetter latency (`BuiltinMetric::WakeupP99LatencyUs`) and a
1148    /// HigherBetter CPU-normalized throughput
1149    /// (`BuiltinMetric::SchbenchLoopsPerCpuSec`) with no
1150    /// caller-specified direction.
1151    ///
1152    /// A post_vm callback collapses the verdict to its `anyhow::Result` via
1153    /// [`crate::assert::Verdict::into_anyhow_or_log`], which bails on a Fail OR
1154    /// an Inconclusive — so a missing metric (a phase with no schbench carrier),
1155    /// an undirected metric, or a zero-baseline fractional-margin comparison
1156    /// does NOT silently pass.
1157    pub fn better_across_phases<'v>(
1158        &self,
1159        verdict: &'v mut crate::assert::Verdict,
1160        baseline: crate::assert::Phase,
1161        candidate: crate::assert::Phase,
1162        metric: impl Into<crate::stats::MetricId>,
1163    ) -> crate::assert::temporal::BetterThanPhase<'v> {
1164        let metric = metric.into();
1165        crate::assert::temporal::BetterThanPhase::new(
1166            metric.as_str().to_string(),
1167            verdict,
1168            baseline,
1169            candidate,
1170            self.phase_metric(baseline, metric.clone()),
1171            self.phase_metric(candidate, metric.clone()),
1172            metric.def().map(|m| m.polarity),
1173            None, // pooled producer — no per-cgroup scope label
1174        )
1175    }
1176
1177    /// One per-phase, PER-CGROUP derived metric — the per-cgroup analog of
1178    /// [`Self::phase_metric`], answering "metric M of cgroup C in phase P" as
1179    /// readily as the phase aggregate (the N-cgroups-to-N-queryable-sets goal).
1180    /// Resolves `metric` (any `impl Into<MetricId>` — a typed `BuiltinMetric` or
1181    /// a dynamic scheduler-runtime string) from this
1182    /// cgroup's per-phase carrier via [`crate::assert::PhaseCgroupStats::get`] (its
1183    /// derived `metrics` map), falling back to
1184    /// [`crate::assert::PhaseCgroupStats::cgroup_counter`] for the per-cgroup
1185    /// Counters `total_migrations`/`total_iterations`/`total_cpu_time_ns` (carrier
1186    /// fields, not derived) — symmetric with [`Self::phase_metric`]'s
1187    /// `cgroup_counter_total` fallback.
1188    /// `None` when `phase` has no bucket, the bucket has no carrier for `cgroup`, or
1189    /// the carrier carried no finite value for the metric — sentinel-free, distinct
1190    /// from a real `Some(0.0)`.
1191    pub fn phase_cgroup_metric(
1192        &self,
1193        phase: crate::assert::Phase,
1194        cgroup: &str,
1195        metric: impl Into<crate::stats::MetricId>,
1196    ) -> Option<f64> {
1197        let metric = metric.into();
1198        self.phase_cgroup(phase, cgroup).and_then(|pc| {
1199            pc.get(metric.as_str())
1200                .or_else(|| pc.cgroup_counter(metric.as_str()))
1201        })
1202    }
1203
1204    /// Per-cgroup analog of [`Self::better_across_phases`]: "is `metric` of
1205    /// `cgroup` better in the `candidate` phase than the `baseline` phase?",
1206    /// oriented from the registry polarity. Reuses the SAME
1207    /// [`crate::assert::temporal::BetterThanPhase`] comparator/verdict machinery;
1208    /// only value resolution is re-scoped from the pooled aggregate to the named
1209    /// cgroup, so a missing carrier / undirected metric / zero-baseline margin
1210    /// collapses to Inconclusive (not a silent pass), exactly as the pooled form.
1211    pub fn better_across_phases_cgroup<'v>(
1212        &self,
1213        verdict: &'v mut crate::assert::Verdict,
1214        baseline: crate::assert::Phase,
1215        candidate: crate::assert::Phase,
1216        cgroup: &str,
1217        metric: impl Into<crate::stats::MetricId>,
1218    ) -> crate::assert::temporal::BetterThanPhase<'v> {
1219        let metric = metric.into();
1220        crate::assert::temporal::BetterThanPhase::new(
1221            metric.as_str().to_string(),
1222            verdict,
1223            baseline,
1224            candidate,
1225            self.phase_cgroup_metric(baseline, cgroup, metric.clone()),
1226            self.phase_cgroup_metric(candidate, cgroup, metric.clone()),
1227            metric.def().map(|m| m.polarity),
1228            Some(cgroup.to_string()), // per-cgroup scope label for the diagnostics
1229        )
1230    }
1231
1232    /// Minimal "nothing happened" fixture for tests that exercise
1233    /// code consuming a [`VmResult`] without actually booting a VM
1234    /// (the sidecar-write tests in `src/test_support/sidecar.rs`
1235    /// are the primary users). Every field carries the empty /
1236    /// default / `None` value that `run_vm` would produce for a
1237    /// VM that launched, exited cleanly with exit code 0, and
1238    /// produced no telemetry. Tests that need a specific field
1239    /// override it with a struct-update expression:
1240    ///
1241    /// ```ignore
1242    /// let result = VmResult { success: false, ..VmResult::test_fixture() };
1243    /// ```
1244    ///
1245    /// Gated on `#[cfg(test)]` so the symbol does not appear in
1246    /// release builds — production `VmResult` values flow from
1247    /// `run_vm` and never from this fixture. See
1248    /// `sidecar_vm_result_is_test_fixture_boilerplate` in
1249    /// `test_support/sidecar.rs` for the motivating deduplication
1250    /// (7 identical literal constructions collapsed to a single
1251    /// call).
1252    #[cfg(test)]
1253    pub fn test_fixture() -> Self {
1254        Self {
1255            success: true,
1256            vcpus: 1,
1257            cpu_budget: 1,
1258            resolve_source: None,
1259            expect_auto_repro_satisfied: false,
1260            exit_code: 0,
1261            duration: Duration::from_secs(1),
1262            timed_out: false,
1263            watchdog_kill_reason: None,
1264            final_guest_phase: GuestLifecyclePhase::Boot,
1265            final_progress_epoch: 0,
1266            bpf_map_writes_delivered: None,
1267            periodic_prereqs_ready: None,
1268            periodic_window_end: None,
1269            output: String::new(),
1270            stderr: String::new(),
1271            monitor: None,
1272            guest_messages: None,
1273            verifier_stats: Vec::new(),
1274            kvm_stats: None,
1275            crash_message: None,
1276            cleanup_duration: None,
1277            cleanup_sched_delta: None,
1278            virtio_blk_counters: None,
1279            virtio_net_counters: None,
1280            snapshot_bridge: empty_snapshot_bridge_for_tests(),
1281            stats_client: None,
1282            periodic_fired: 0,
1283            periodic_real: 0,
1284            periodic_target: 0,
1285            kern_kaslr_offset: 0,
1286            entry_name: None,
1287            variant_hash: 0,
1288            host_vcpu_schedstat: None,
1289            contention_witness: None,
1290            periodic_series_cache: std::sync::OnceLock::new(),
1291        }
1292    }
1293
1294    /// Per-test sidecar path for the `.wprof.pb` artifact:
1295    /// `{sidecar_dir()}/{entry_name}-{variant_hash:016x}.wprof.pb`.
1296    #[cfg(feature = "wprof")]
1297    pub fn wprof_pb_path(&self) -> anyhow::Result<std::path::PathBuf> {
1298        let name = self.entry_name.ok_or_else(|| {
1299            anyhow::anyhow!(
1300                "VmResult.entry_name is None — wprof_pb_path() requires the \
1301                 macro-stamped entry name set by run_ktstr_test_inner_impl \
1302                 after vm.run() returns. A `None` here means the VmResult \
1303                 was constructed via the freeze_coord::collect_results \
1304                 direct-synthesis path and the eval-layer stamping was \
1305                 bypassed; route the result through run_ktstr_test_inner_impl \
1306                 OR assign entry_name = Some(\"<test-fn-name>\") manually \
1307                 before calling .wprof_pb_path()."
1308            )
1309        })?;
1310        Ok(crate::test_support::sidecar_dir()
1311            .join(format!("{name}-{:016x}.wprof.pb", self.variant_hash)))
1312    }
1313
1314    /// Per-test sidecar path for the `.repro.wprof.pb` artifact.
1315    #[cfg(feature = "wprof")]
1316    pub fn repro_wprof_pb_path(&self) -> anyhow::Result<std::path::PathBuf> {
1317        let name = self.entry_name.ok_or_else(|| {
1318            anyhow::anyhow!(
1319                "VmResult.entry_name is None — repro_wprof_pb_path() \
1320                 requires the macro-stamped entry name set by \
1321                 run_ktstr_test_inner_impl after vm.run() returns. A `None` \
1322                 here means the VmResult was constructed via the \
1323                 freeze_coord::collect_results direct-synthesis path and \
1324                 the eval-layer stamping was bypassed; route the result \
1325                 through run_ktstr_test_inner_impl OR assign entry_name \
1326                 manually before calling."
1327            )
1328        })?;
1329        Ok(crate::test_support::sidecar_dir()
1330            .join(format!("{name}-{:016x}.repro.wprof.pb", self.variant_hash)))
1331    }
1332
1333    /// Per-test failure-dump sidecar path. Derives
1334    /// `{sidecar_dir()}/{entry_name}-{variant_hash:016x}.failure-dump.json`
1335    /// from the macro-stamped [`Self::entry_name`].
1336    ///
1337    /// # Sibling to
1338    /// [`crate::scenario::Ctx::failure_dump_path`]
1339    ///
1340    /// The pre-VM body context carries its own copy of the
1341    /// macro-stamped entry name (stamped at Ctx construction by
1342    /// the dispatch path) and computes the same path string. A
1343    /// test body invocation `ctx.failure_dump_path()` and a
1344    /// post-VM `result.failure_dump_path()` resolve to identical
1345    /// paths because both stamp from the same
1346    /// `entry.name: &'static str` source — proc-macro emission
1347    /// at the `#[ktstr_test]` site. This pair gives post_vm
1348    /// callbacks a symmetric path-derivation surface to the
1349    /// pre-VM body, so a future post_vm hook that wants to
1350    /// inspect or clean up the failure dump uses the same method
1351    /// shape the body uses to look at it.
1352    ///
1353    /// # Errors
1354    ///
1355    /// Returns `Err` when [`Self::entry_name`] is `None`.
1356    pub fn failure_dump_path(&self) -> anyhow::Result<std::path::PathBuf> {
1357        let name = self.entry_name.ok_or_else(|| {
1358            anyhow::anyhow!(
1359                "VmResult.entry_name is None — failure_dump_path() \
1360                 requires the macro-stamped entry name set by \
1361                 run_ktstr_test_inner_impl after vm.run() returns. \
1362                 A `None` here means the VmResult was constructed via \
1363                 the freeze_coord::collect_results direct-synthesis \
1364                 path and the eval-layer stamping was bypassed; route \
1365                 the result through run_ktstr_test_inner_impl OR \
1366                 assign entry_name manually before calling."
1367            )
1368        })?;
1369        Ok(crate::test_support::sidecar_dir().join(format!(
1370            "{name}-{:016x}.failure-dump.json",
1371            self.variant_hash
1372        )))
1373    }
1374
1375    /// Concatenated guest `/dev/kmsg` content forwarded via
1376    /// `crate::send_kmsg`, or empty when no frames arrived (the scenario
1377    /// did not forward, or the VM exited before the forward completed).
1378    /// Lets a post_vm callback read the guest kernel log even at the
1379    /// default `loglevel=0`, where kernel printks never reach the COM1
1380    /// console (and thus not `stderr`). Encapsulates the bulk-port
1381    /// `ShmEntry` + `MsgType::Dmesg` filter inside the crate.
1382    pub fn guest_kmsg(&self) -> String {
1383        let Some(drain) = self.guest_messages.as_ref() else {
1384            return String::new();
1385        };
1386        drain
1387            .entries
1388            .iter()
1389            .filter(|e| {
1390                e.crc_ok
1391                    && !e.payload.is_empty()
1392                    && matches!(
1393                        crate::vmm::wire::MsgType::from_wire(e.msg_type),
1394                        Some(crate::vmm::wire::MsgType::Dmesg)
1395                    )
1396            })
1397            .map(|e| String::from_utf8_lossy(&e.payload).into_owned())
1398            .collect::<Vec<String>>()
1399            .join("\n")
1400    }
1401
1402    /// The scheduler's captured log — its stderr, including any libbpf /
1403    /// BPF-verifier output — extracted from the bulk-port
1404    /// `MSG_TYPE_SCHED_LOG` frames in [`Self::guest_messages`]. Empty when
1405    /// no scheduler log was captured (no scheduler was spawned, or the
1406    /// framed markers never arrived).
1407    ///
1408    /// Mirrors the extraction [`crate::verifier::collect_verifier_output`]
1409    /// performs: concatenate the `SchedLog` chunks, slice the span from the
1410    /// first `SCHED_OUTPUT_START` to the last `SCHED_OUTPUT_END` (spanning
1411    /// any intervening markers when the guest staged more than one log),
1412    /// and fall back to `output` when the bulk-port drain carried no
1413    /// `SchedLog` frames (a kernel without the bulk port). Lets a post_vm
1414    /// callback assert on what the scheduler logged — e.g. a libbpf
1415    /// verifier-reject — without reaching into the crate-internal wire
1416    /// types.
1417    pub fn scheduler_log(&self) -> String {
1418        let merged = crate::verifier::concat_sched_log_chunks(self.guest_messages.as_ref());
1419        let source = if merged.is_empty() {
1420            &self.output
1421        } else {
1422            &merged
1423        };
1424        crate::verifier::parse_sched_output(source)
1425            .unwrap_or("")
1426            .to_string()
1427    }
1428
1429    /// The host watchdog-override readback (`expected_jiffies` =
1430    /// host-written, `observed_jiffies` = read back from guest memory).
1431    /// `None` when the scheduler never attached (no readback recorded).
1432    /// A post_vm callback asserts the two are equal to prove the override
1433    /// landed; the readback is taken eagerly by the monitor (in-DRAM,
1434    /// microseconds), so it is immune to the watchdog-kworker starvation
1435    /// that inflates the kernel-measured stall duration. Encapsulates the
1436    /// `MonitorReport` access (`WatchdogObservation` is re-exported at the
1437    /// crate root for the return type).
1438    pub fn watchdog_observation(&self) -> Option<crate::monitor::WatchdogObservation> {
1439        self.monitor.as_ref().and_then(|m| m.watchdog_observation)
1440    }
1441
1442    /// Assert the primary-VM `.wprof.pb` landed and is shape-valid.
1443    /// Returns `Ok(())` immediately when `self.success` is false.
1444    #[cfg(feature = "wprof")]
1445    pub fn assert_wprof_pb_landed(&self) -> anyhow::Result<()> {
1446        if !self.success {
1447            return Ok(());
1448        }
1449        // Pre-check `entry_name` with a callable-specific diagnostic
1450        // BEFORE delegating to `self.wprof_pb_path()` (which would
1451        // bail with the wprof_pb_path-perspective message). A
1452        // fixture-constructed VmResult hitting this method should
1453        // see a diagnostic naming `assert_wprof_pb_landed` so the
1454        // caller's mental model lines up with the error text.
1455        anyhow::ensure!(
1456            self.entry_name.is_some(),
1457            "VmResult::assert_wprof_pb_landed requires entry_name set by \
1458             run_ktstr_test_inner_impl after vm.run() returns. This \
1459             VmResult was constructed manually (freeze_coord direct \
1460             synthesis path or a test fixture); either route the result \
1461             through run_ktstr_test_inner_impl OR call \
1462             crate::test_support::wprof::assert_wprof_pb_shape with a \
1463             manually-computed path.",
1464        );
1465        let path = self.wprof_pb_path()?;
1466        crate::test_support::wprof::assert_wprof_pb_shape(&path)
1467    }
1468}
1469
1470/// Build an empty `SnapshotBridge` whose capture callback always
1471/// returns `None`. Used by `VmResult::test_fixture` and the legacy
1472/// `VmResult` literal constructions in unit tests so they still
1473/// compile after the snapshot_bridge field landed. Production
1474/// `run_vm` constructs its own bridge whose callback is
1475/// intentionally unused — the freeze coordinator stores reports
1476/// directly via `bridge.store(name, report)`.
1477#[cfg(test)]
1478pub(crate) fn empty_snapshot_bridge_for_tests() -> crate::scenario::snapshot::SnapshotBridge {
1479    let cb: crate::scenario::snapshot::CaptureCallback = std::sync::Arc::new(|_| None);
1480    crate::scenario::snapshot::SnapshotBridge::new(cb)
1481}
1482
1483/// Host-side vCPU scheduling-dilation sample, summed over the run's
1484/// vCPU host threads.
1485///
1486/// Dilation `D = 1 + Σrun_delay / Σon_cpu`, where the two sums are
1487/// taken over each vCPU host thread's `/proc/self/task/<tid>/schedstat`
1488/// (field 1 = time on-CPU ns, field 2 = time runnable-but-not-running
1489/// ns). `D == 1.0` means the vCPU threads always got the CPU the instant
1490/// they were runnable; `D > 1.0` quantifies host-side scheduling delay
1491/// (e.g. `1.03x` = threads waited 3% on top of their run time).
1492///
1493/// Idle-immune: a halted vCPU is blocked (not runnable), so it accrues
1494/// no `run_delay` — halt time never inflates `D`. Measured HOST-side
1495/// deliberately: the guest run-queue's own `run_delay` would measure the
1496/// scheduler under test, which is the thing being evaluated; the host
1497/// thread's schedstat measures the CPU the vCPU thread was starved of by
1498/// the HOST, orthogonal to the guest scheduler.
1499///
1500/// RAW totals are stored (not the ratio) so future consumers can
1501/// recompute or re-aggregate; [`Self::dilation`] derives the ratio.
1502///
1503/// `total_on_cpu_ns == 0` yields `dilation() == None` — this happens
1504/// BOTH when no vCPU thread ran at all AND on a host built without
1505/// `CONFIG_SCHEDSTATS` (every schedstat line reads `"0 0 0"`). `None` is
1506/// thus graceful and distinguishable from a genuine `D == 1.0`.
1507#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1508pub struct HostVcpuSchedstat {
1509    /// Σ schedstat field 1 (time the vCPU threads spent ON-CPU), ns.
1510    pub total_on_cpu_ns: u64,
1511    /// Σ schedstat field 2 (time the vCPU threads spent runnable but
1512    /// not running — host-side scheduling delay), ns.
1513    pub total_run_delay_ns: u64,
1514    /// Number of vCPU host threads that contributed to the sums (a TID
1515    /// still 0 — an AP that never stamped its TID — and an unreadable
1516    /// schedstat are both skipped).
1517    pub sampled_vcpus: u32,
1518}
1519
1520impl HostVcpuSchedstat {
1521    /// Host dilation `D = 1 + Σrun_delay / Σon_cpu`, or `None` when no
1522    /// on-CPU time was sampled (no vCPU ran, or the host lacks
1523    /// `CONFIG_SCHEDSTATS` and every line read `"0 0 0"`). `None` is
1524    /// deliberately distinguishable from a true `D == 1.0` (which needs
1525    /// nonzero on-CPU time with zero run-delay).
1526    pub fn dilation(&self) -> Option<f64> {
1527        (self.total_on_cpu_ns > 0)
1528            .then(|| 1.0 + self.total_run_delay_ns as f64 / self.total_on_cpu_ns as f64)
1529    }
1530
1531    /// Field-wise saturating delta `self - anchor` over the two schedstat
1532    /// sums — the on-CPU / run-delay accrued BETWEEN two cumulative
1533    /// snapshots of the same vCPU threads. `sampled_vcpus` carries `self`'s
1534    /// count (the reading the delta closes at). Saturating so a schedstat
1535    /// that momentarily regressed (a TID that vanished then reappeared, a
1536    /// torn read) contributes 0 rather than wrapping — conservative: a
1537    /// per-phase `D` can only be UNDER-stated by such a clamp, never
1538    /// fabricated. The result's [`Self::dilation`] is the phase-local `D`.
1539    pub fn delta_from(&self, anchor: &HostVcpuSchedstat) -> HostVcpuSchedstat {
1540        HostVcpuSchedstat {
1541            total_on_cpu_ns: self.total_on_cpu_ns.saturating_sub(anchor.total_on_cpu_ns),
1542            total_run_delay_ns: self
1543                .total_run_delay_ns
1544                .saturating_sub(anchor.total_run_delay_ns),
1545            sampled_vcpus: self.sampled_vcpus,
1546        }
1547    }
1548}
1549
1550/// Number of `LifecycleStage` variants (Boot, Attach,
1551/// Dispatch, Body, Teardown) — the length of the per-phase witness array.
1552/// Kept in lock-step with that enum; [`PerPhaseSchedstat::for_stage`] indexes
1553/// by `stage as usize`, so a new stage variant needs this bumped.
1554pub const NUM_LIFECYCLE_STAGES: usize = 5;
1555
1556/// Array index of the BODY stage (the measurement phase) — pinned to the
1557/// enum discriminant so it can never drift from
1558/// `LifecycleStage::Body`.
1559pub const BODY_STAGE_INDEX: usize = crate::monitor::LifecycleStage::Body as usize;
1560
1561/// Per-lifecycle-phase host-dilation witness: normally one
1562/// [`HostVcpuSchedstat`] DELTA per stage, covering the schedstat accrued
1563/// between lifecycle-event boundary snapshots. If the guest-reported
1564/// scenario duration proves queued lifecycle frames did not bracket Body,
1565/// Body instead carries the complete enclosing vCPU-thread lifetime. That
1566/// conservative fallback can overstate Body contention but cannot hide it.
1567/// Indexed by `LifecycleStage` `as usize`.
1568///
1569/// Distinct from the whole-run [`VmResult::host_vcpu_schedstat`] (which is
1570/// the verdict-line `D` over the entire run): normally each phase gets its OWN
1571/// `D` over its OWN span, so the Body phase's dilation — the only phase whose
1572/// contention actually contaminates the workload measurement — is isolated
1573/// from the Boot / Attach / Teardown INFRA phases. The batched-delivery
1574/// fallback deliberately gives up that localization. `Boot`/`Attach` `D` is
1575/// diagnostic; `Body` is the one the latency verdict consumes.
1576///
1577/// The dispatch path takes each boundary snapshot immediately after accepting
1578/// the CRC-valid lifecycle frame. ScenarioEnd's guest duration detects
1579/// start/end frames accepted together after a starved dispatch loop. A wide-VM
1580/// snapshot is a sequential sweep of the vCPU TIDs rather than an atomic
1581/// kernel operation, so its uncertainty is the duration of that rare sweep,
1582/// not the monitor's sampling period.
1583#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1584pub struct PerPhaseSchedstat {
1585    /// Per-stage schedstat delta, indexed by `LifecycleStage as usize`
1586    /// (Boot=0 .. Teardown=4). A stage never entered stays at the
1587    /// `Default` all-zero value (`dilation() == None`).
1588    pub phases: [HostVcpuSchedstat; NUM_LIFECYCLE_STAGES],
1589}
1590
1591impl PerPhaseSchedstat {
1592    /// The Body (measurement) phase's schedstat delta — the phase whose
1593    /// dilation the latency verdict consumes.
1594    pub fn body(&self) -> &HostVcpuSchedstat {
1595        &self.phases[BODY_STAGE_INDEX]
1596    }
1597
1598    /// The Body phase's host dilation `D`, or `None` when no on-CPU time was
1599    /// sampled in the Body span (schedstats off, or the phase never ran).
1600    pub fn body_dilation(&self) -> Option<f64> {
1601        self.body().dilation()
1602    }
1603
1604    /// The schedstat delta for one lifecycle stage (diagnostic access to the
1605    /// Boot/Attach/Dispatch/Teardown phases). `pub(crate)`: takes the
1606    /// crate-internal `LifecycleStage`. `allow(dead_code)`:
1607    /// the diagnostic Boot/Attach `D` readers land with the LATER seam pass;
1608    /// `body()` is the wired accessor.
1609    #[allow(dead_code)]
1610    pub(crate) fn for_stage(&self, stage: crate::monitor::LifecycleStage) -> &HostVcpuSchedstat {
1611        &self.phases[stage as usize]
1612    }
1613}
1614
1615/// Body-phase peak-window contamination series. New witnesses store deltas of
1616/// the ktstr runner cgroup's CPU PSI `some total` clock: time during which at
1617/// least one runnable task in that cgroup was stalled for CPU. This includes a
1618/// delayed vCPU even when its competitor is outside the cgroup, without
1619/// charging pressure in unrelated host cgroups. Each entry has its real
1620/// observation width in [`Self::tick_widths_ns`], allowing the window
1621/// calculation to remain sound when the monitor is starved and wakes much
1622/// later than its nominal cadence.
1623///
1624/// Legacy/deserialized witnesses may have no width vector; those retain the
1625/// fixed-grid `tick_ns` interpretation. Bounded storage: observations are
1626/// nominally 100 ms apart and Body phases run minutes, so a few thousand
1627/// entries is typical; the series is capped at 36,000 intervals and
1628/// `saturated` is set if the cap is hit. When
1629/// `saturated`, the series is a PREFIX of the phase, so `W` computed from it
1630/// is a LOWER bound — a later verdict pass should treat that as reducing
1631/// confidence in a `FailConfirmed` rather than trusting a possibly-short `W`.
1632///
1633/// COVERAGE SOUNDNESS: new witnesses sample the cumulative PSI counter at
1634/// accepted lifecycle boundaries as well as monitor wakes, so the first and
1635/// last samples explicitly close the entire Body span. A starved monitor may
1636/// produce one coarse interval instead of many fine ones, but charging that
1637/// interval's entire delta remains an upper bound for every window it can
1638/// touch. If either boundary sample fails or storage saturates, `complete` is
1639/// false and the seam cannot use the series to confirm a failure.
1640///
1641/// Legacy witnesses have no explicit completeness bit. For them the seam
1642/// retains the old conservative check that the fixed-grid samples span enough
1643/// of Body; an empty or clustered series can only demote a result, never
1644/// produce a false confirmation.
1645#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1646pub struct BodyContentionWindow {
1647    /// Per-observation CPU-contention delta (ns) over the Body phase, in time
1648    /// order. New witnesses use runner-cgroup CPU PSI `some total`; legacy
1649    /// witnesses contain summed vCPU schedstat run-delay.
1650    pub tick_deltas: Vec<u64>,
1651    /// Real wall width (ns) of each corresponding delta interval. Empty on
1652    /// legacy witnesses. When present, length matches `tick_deltas` and the
1653    /// peak-window calculation uses these widths instead of a nominal grid.
1654    #[serde(default)]
1655    pub tick_widths_ns: Vec<u64>,
1656    /// The nominal monitor tick period (ns) the deltas were sampled at
1657    /// (100 ms in production). Used only by legacy witnesses without real
1658    /// interval widths.
1659    pub tick_ns: u64,
1660    /// True when [`Self::tick_deltas`] hit its cap and later Body ticks were
1661    /// dropped — the series is then a prefix and `W` from it is a lower bound.
1662    pub saturated: bool,
1663    /// True when lifecycle-event samples anchored BOTH ends of Body (the
1664    /// start is conservatively pulled back to the preceding lifecycle
1665    /// boundary to cover virtio dispatch lag), making the cumulative interval
1666    /// series complete even if it contains only one coarse interval. A host
1667    /// acceptance span shorter than ScenarioEnd's guest duration invalidates
1668    /// those edge samples; the complete whole-vCPU-lifetime fallback may then
1669    /// restore completeness as one conservative interval. False on legacy
1670    /// sampled witnesses, whose coverage is inferred from their first/last
1671    /// monitor ticks.
1672    #[serde(default)]
1673    pub complete: bool,
1674    /// Complete summed vCPU schedstat run-delay (ns) over the conservative
1675    /// wall span of this series, or (when the preceding lifecycle snapshot
1676    /// raced vCPU startup) the enclosing whole-thread lifetime. When
1677    /// [`Self::schedstat_cap_complete`] is true, `W(L)` is capped by this
1678    /// value: a request cannot absorb more task-specific scheduling delay in
1679    /// one window than all vCPUs accumulated over the enclosing span. This
1680    /// removes unrelated runner-cgroup PSI without under-bounding the target
1681    /// VM's delay.
1682    #[serde(default)]
1683    pub schedstat_cap_ns: u64,
1684    /// True when the closing snapshot sampled the complete live vCPU set and
1685    /// the cap is therefore a sound upper bound. An exact matching opening
1686    /// snapshot produces the tighter Body delta; otherwise the complete
1687    /// whole-thread-life total is used. False for legacy witnesses and
1688    /// partial/failed closing reads, in which case the cap is ignored.
1689    #[serde(default)]
1690    pub schedstat_cap_complete: bool,
1691    /// The wall span (ns) covered by the Body witness. Normally the start is
1692    /// conservatively pinned to the accepted lifecycle boundary preceding
1693    /// Body, covering any time the guest's Body frame waited in virtio
1694    /// dispatch; the end is the first accepted transition after Body. It may
1695    /// therefore include adjacent-stage time, which makes `W` larger and can
1696    /// only bias the verdict toward indeterminate. If that accepted span is
1697    /// shorter than ScenarioEnd's guest duration, the guest duration widens
1698    /// it for the whole-lifetime fallback. `0` when Body was never observed.
1699    pub body_wall_ns: u64,
1700    /// The wall span (ns) the series actually covered. For event-anchored
1701    /// complete witnesses this equals `body_wall_ns`; for legacy witnesses it
1702    /// is the elapsed between the first and last Body monitor tick.
1703    pub body_covered_ns: u64,
1704}
1705
1706/// The event-anchored host-contention witness: per-phase vCPU schedstat
1707/// dilation plus the Body-phase CPU-pressure interval series. The monitor
1708/// contributes constant-cost samples on its existing timer wakes; lifecycle
1709/// dispatch anchors the stage boundaries. Carried on
1710/// [`VmResult::contention_witness`] so a later seam pass can call
1711/// `latency_verdict` to turn a latency threshold into a tri-state,
1712/// contention-aware verdict.
1713///
1714/// `None` on [`VmResult`] when neither vCPU schedstat nor CPU PSI supplied any
1715/// evidence. A present but incomplete Body series is retained for diagnostics
1716/// but cannot confirm a latency failure.
1717#[derive(Debug, Clone, Default, PartialEq, serde::Serialize, serde::Deserialize)]
1718pub struct ContentionWitness {
1719    /// Per-lifecycle-phase host-dilation deltas (Boot..Teardown).
1720    pub per_phase: PerPhaseSchedstat,
1721    /// Body-phase contention intervals for the `W(L)` bound.
1722    pub body_window: BodyContentionWindow,
1723}
1724
1725impl ContentionWitness {
1726    /// The Body-phase host dilation `D` (annotation for the latency verdict);
1727    /// `None` when no Body on-CPU time was sampled.
1728    pub fn body_dilation(&self) -> Option<f64> {
1729        self.per_phase.body_dilation()
1730    }
1731}
1732
1733/// Per-vCPU KVM stats read after VM exit. Each map holds cumulative
1734/// counter values from the VM's lifetime.
1735#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1736pub struct KvmStatsTotals {
1737    /// Per-vCPU stat maps. Index is vCPU id.
1738    pub per_vcpu: Vec<HashMap<String, u64>>,
1739}
1740
1741/// KVM stat names surfaced in sidecar output for scheduler testing.
1742///
1743/// Covers VM exit rate, halt-polling behavior, preemption notifications,
1744/// signal-driven exits, and hypercall counts; all fields scheduler
1745/// authors typically correlate with scx decisions.
1746///
1747/// Per-arch availability: `halt_exits`, `preemption_reported`, and
1748/// `hypercalls` are published by KVM only on x86. On aarch64 the
1749/// kernel does not expose these stats via `KVM_GET_STATS_FD`; they
1750/// are absent from the per-vCPU map and read as `0` from
1751/// [`KvmStatsTotals::sum`] / [`KvmStatsTotals::avg`]. The remaining
1752/// names (`exits`, `halt_successful_poll`, `halt_attempted_poll`,
1753/// `halt_wait_ns`, `signal_exits`) are published on both arches.
1754#[allow(dead_code)]
1755pub const KVM_INTERESTING_STATS: &[&str] = &[
1756    "exits",
1757    "halt_exits",
1758    "halt_successful_poll",
1759    "halt_attempted_poll",
1760    "halt_wait_ns",
1761    "preemption_reported",
1762    "signal_exits",
1763    "hypercalls",
1764];
1765
1766impl KvmStatsTotals {
1767    /// Sum a stat across all vCPUs. Returns 0 BOTH when no vCPU published
1768    /// the stat and when every vCPU measured zero — use [`Self::try_sum`]
1769    /// to distinguish "unpublished" from "measured zero".
1770    pub fn sum(&self, name: &str) -> u64 {
1771        self.try_sum(name).unwrap_or(0)
1772    }
1773
1774    /// Average a stat across all vCPUs (returns 0 if no vCPUs). Same
1775    /// absent-vs-zero ambiguity as [`Self::sum`]; see [`Self::try_avg`].
1776    pub fn avg(&self, name: &str) -> u64 {
1777        self.try_avg(name).unwrap_or(0)
1778    }
1779
1780    /// Sum a stat across all vCPUs, or `None` when NO per-vCPU map
1781    /// published it. Distinguishes an unpublished stat (`None`) from a
1782    /// genuinely-measured zero (`Some(0)`) — the plain [`Self::sum`]
1783    /// collapses both to `0`, so a test reading a counter that the kernel
1784    /// never emitted on this arch cannot tell it apart from a real zero.
1785    pub fn try_sum(&self, name: &str) -> Option<u64> {
1786        let mut acc: Option<u64> = None;
1787        for m in &self.per_vcpu {
1788            if let Some(&v) = m.get(name) {
1789                acc = Some(acc.unwrap_or(0) + v);
1790            }
1791        }
1792        acc
1793    }
1794
1795    /// Average a stat across all vCPUs, or `None` when there are no vCPUs
1796    /// or NO per-vCPU map published the stat. The absent-aware counterpart
1797    /// of [`Self::avg`].
1798    pub fn try_avg(&self, name: &str) -> Option<u64> {
1799        let n = self.per_vcpu.len() as u64;
1800        if n == 0 {
1801            return None;
1802        }
1803        self.try_sum(name).map(|s| s / n)
1804    }
1805}
1806
1807/// State returned by [`super::KtstrVm::run_vm`] after the BSP exits.
1808/// Passed to [`super::KtstrVm::collect_results`] to produce
1809/// [`VmResult`].
1810pub(crate) struct VmRunState {
1811    pub(crate) exit_code: i32,
1812    pub(crate) timed_out: bool,
1813    /// Raw kill-reason byte loaded from the watchdog thread's latch
1814    /// after its join (`freeze_coord::KillReasonTag` layout; 0 =
1815    /// unset). Decoded into [`VmResult::watchdog_kill_reason`] by
1816    /// `collect_results`, which owns the tag type.
1817    pub(crate) watchdog_kill_reason_raw: u8,
1818    /// Raw final lifecycle-stage byte from the progress ledger
1819    /// (`monitor::LifecycleStage` layout). Decoded into
1820    /// [`VmResult::final_guest_phase`] by `collect_results`.
1821    pub(crate) final_guest_phase_raw: u8,
1822    /// Final ledger milestone count → [`VmResult::final_progress_epoch`].
1823    pub(crate) final_progress_epoch: u64,
1824    /// Raw BPF-map-write injection delivery state (0 = none
1825    /// configured, 1 = pending/never delivered, 2 = delivered) —
1826    /// decoded into [`VmResult::bpf_map_writes_delivered`].
1827    pub(crate) bpf_map_write_delivery_raw: u8,
1828    /// Cleanup-window-open schedstat snapshot of the run_vm caller
1829    /// thread (the join/drain performer) — closed by `collect_results`
1830    /// into [`VmResult::cleanup_sched_delta`].
1831    pub(crate) cleanup_sched_t0: Option<HostVcpuSchedstat>,
1832    /// Run-relative ns when the periodic prereqs (kaslr + accessors)
1833    /// became ready (0 = never) → [`VmResult::periodic_prereqs_ready`].
1834    pub(crate) periodic_prereqs_ready_ns_raw: u64,
1835    /// Run-relative ns of the periodic capture-window end (0 = the
1836    /// window never resolved) → [`VmResult::periodic_window_end`].
1837    pub(crate) periodic_window_end_ns_raw: u64,
1838    /// Framework/infrastructure failure raised after the VM had already
1839    /// started. `collect_results` performs the complete teardown first, then
1840    /// returns this as a marker-typed error which cannot be inverted by
1841    /// `expect_err` or classified as a resource skip.
1842    pub(crate) framework_error: Option<String>,
1843    /// Event-anchored per-phase dilation + Body contention intervals,
1844    /// finalized from live proc entries plus one-shot AP exit snapshots.
1845    pub(crate) contention_witness: Option<ContentionWitness>,
1846    /// Armed owner for every AP, monitor, and BPF-map-writer thread which can
1847    /// retain a raw view of guest memory. It moves directly from `run_vm` into
1848    /// this handoff state without a naked-JoinHandle interval. Its Drop runs
1849    /// before `vm` (field declaration order), so an unwind or an abandoned
1850    /// `VmRunState` still bounded-joins all readers before guest memory unmaps.
1851    pub(crate) run_threads: super::freeze_coord::RunVmThreadGuard,
1852    pub(crate) com1: Arc<PiMutex<console::Serial>>,
1853    pub(crate) com2: Arc<PiMutex<console::Serial>>,
1854    pub(crate) kill: Arc<AtomicBool>,
1855    /// Wake fd paired with `kill`. Setters that flip `kill`
1856    /// (`collect_results`, vCPU shutdown classifier, panic hook)
1857    /// also write to this EventFd so any consumer blocked in
1858    /// `epoll_wait` (notably the freeze coordinator and the
1859    /// monitor sampler) wakes within microseconds of the flip
1860    /// rather than waiting up to one full poll interval. The
1861    /// AtomicBool above remains the source of truth — the EventFd
1862    /// is purely a wake signal. EFD_NONBLOCK so a saturated
1863    /// counter never stalls the writer.
1864    pub(crate) kill_evt: Arc<vmm_sys_util::eventfd::EventFd>,
1865    /// Broadcast freeze flag for the failure-dump coordinator. When the
1866    /// coordinator receives a guest-side error-exit signal it sets this
1867    /// to true, kicks every vCPU, waits for all `parked` flags to flip
1868    /// true, and then reads guest BPF map state. Released to false to
1869    /// resume normal execution. Lives alongside `kill` so the same Arc
1870    /// pattern (broadcast + per-vCPU ACK) covers both shutdown and
1871    /// freeze rendezvous.
1872    pub(crate) freeze: Arc<AtomicBool>,
1873    /// Hardware-watchpoint arming state Arc, forwarded so
1874    /// [`super::KtstrVm::collect_results`] can invalidate the
1875    /// `kind_host_ptr` and `request_kva` slots after every vCPU
1876    /// thread joins but BEFORE `vm` drops.
1877    ///
1878    /// Without the invalidation, the slots' published values
1879    /// continue to address (a) a host pointer into `vm.guest_mem`'s
1880    /// mapping that becomes unmapped when `vm` drops and (b) a
1881    /// guest KVA whose translation goes through the same mapping.
1882    /// The freeze coordinator joins before `vm` drops in
1883    /// `run_vm`, and AP threads join inside `collect_results` —
1884    /// but defense-in-depth says we zero the slots once every
1885    /// reader is gone so any future restructuring (a stray Arc
1886    /// clone surviving past teardown, a follow-up that adds a
1887    /// new reader path) cannot trip a use-after-free.
1888    ///
1889    /// Declared before `vm` so the implicit drop order on
1890    /// `VmRunState` teardown drops `watchpoint` first: any Arc
1891    /// clone outliving the struct can no longer dereference its
1892    /// `kind_host_ptr` after `vm.guest_mem` has unmapped, even if
1893    /// a future caller forgets the explicit pre-drop
1894    /// invalidation in `collect_results`.
1895    pub(crate) watchpoint: Arc<WatchpointArm>,
1896    pub(crate) vm: kvm::KtstrKvm,
1897    /// Captured immediately after the BSP exits its run loop. Subtracted
1898    /// from `Instant::now()` in [`super::KtstrVm::collect_results`]
1899    /// right before the [`VmResult`] is returned to populate
1900    /// [`VmResult::cleanup_duration`]. Records the wall-clock cost of
1901    /// every host-side teardown step that runs after the guest has
1902    /// stopped advancing, in execution order: the watchdog-thread join
1903    /// in [`super::KtstrVm::run_vm`], then the AP-thread joins, the
1904    /// monitor-thread join, the BPF-map-writer join, the SHM-ring
1905    /// drain, the post-exit exit-code/crash-message extraction, and
1906    /// finally the BPF verifier-stat read inside
1907    /// [`super::KtstrVm::collect_results`].
1908    pub(crate) cleanup_start: Instant,
1909    /// Cloned counter handle from `KtstrVm::init_virtio_blk`
1910    /// when a disk was attached, captured before the device-arc is
1911    /// dropped so [`super::KtstrVm::collect_results`] can snapshot
1912    /// it into [`VmResult::virtio_blk_counters`]. The device worker
1913    /// bumps these atomics from `drain_bracket_impl` (production cfg:
1914    /// dedicated `ktstr-vblk` thread; cfg(test): inline on the test
1915    /// thread); by the time `collect_results` reads this field every
1916    /// vCPU thread has joined upstream, the worker can receive no
1917    /// further kicks, and the conversion site
1918    /// (`run.virtio_blk_counters.as_deref().map(|c| c.snapshot())`)
1919    /// loads the final cumulative state into a plain-u64 snapshot
1920    /// before storing on the public `VmResult`.
1921    pub(crate) virtio_blk_counters: Option<Arc<VirtioBlkCounters>>,
1922    /// Cloned per-NIC counter handles from the net device init
1923    /// (`init_virtio_net` on aarch64 / `init_virtio_net_pci` on x86_64, both
1924    /// arch-gated), one per attached NIC, captured before the device arcs are
1925    /// dropped so [`super::KtstrVm::collect_results`] can snapshot and aggregate
1926    /// them into [`VmResult::virtio_net_counters`] via
1927    /// [`VirtioNetCountersSnapshot::aggregate`]. Empty when no NIC is attached.
1928    pub(crate) virtio_net_counters: Vec<Arc<VirtioNetCounters>>,
1929    /// Snapshot bridge owning every report captured during the run.
1930    /// The freeze coordinator clones this bridge into its closure
1931    /// state; on every guest-side
1932    /// [`crate::vmm::wire::MSG_TYPE_SNAPSHOT_REQUEST`] frame the
1933    /// coordinator's TOKEN_TX handler decoded with kind
1934    /// [`crate::vmm::wire::SNAPSHOT_KIND_CAPTURE`], the dispatch runs
1935    /// `freeze_and_dispatch(FreezeMode::Capture { gate_on_exit_kind: false })` and stores the resulting
1936    /// `FailureDumpReport` here keyed by the snapshot name. After
1937    /// VM exit, [`super::KtstrVm::collect_results`] forwards the
1938    /// bridge onto [`VmResult::snapshot_bridge`] so the test code
1939    /// can drain captured snapshots and walk them via the
1940    /// [`crate::scenario::snapshot::Snapshot`] accessor surface.
1941    pub(crate) snapshot_bridge: crate::scenario::snapshot::SnapshotBridge,
1942    /// Cached aarch64 TCR_EL1 register, populated lazily by the BSP
1943    /// once the guest kernel programs the MMU. Always `None` on
1944    /// x86_64 (the register does not exist). Threads that construct
1945    /// a `GuestKernel` for page-table walks (monitor, BPF map writer,
1946    /// freeze coordinator, post-exit verifier-stats collector) read
1947    /// this atomic to feed the granule-agnostic walker (4 KB / 16 KB
1948    /// / 64 KB). A 0 reading on aarch64 means "kernel hasn't reached
1949    /// MMU bring-up yet"; the walker's T1SZ=0 gate rejects walks in
1950    /// that state and the affected lookup returns `None` cleanly.
1951    pub(crate) tcr_el1: Option<Arc<std::sync::atomic::AtomicU64>>,
1952    /// Cached BSP CR3 (x86_64) / TTBR1_EL1 (aarch64), populated lazily
1953    /// by the BSP loop after initial page-table setup. Used by
1954    /// post-exit `GuestKernel` constructions to walk the live page
1955    /// tables for `phys_base` resolution. `0` means the cache wasn't
1956    /// populated (early boot crash); the walk fails and `phys_base`
1957    /// falls back to `0`, which produces correct translations on
1958    /// non-KASLR boots.
1959    pub(crate) cr3: Arc<std::sync::atomic::AtomicU64>,
1960    /// Optional preloaded vmlinux bytes for the exceptional
1961    /// `collect_verifier_stats` fallback. Ordinary VM runs leave this `None`:
1962    /// the live prog accessor consumes the shared derived artifacts, and the
1963    /// fallback loads bytes lazily only when it is genuinely needed.
1964    pub(crate) vmlinux_data: Option<Arc<Vec<u8>>>,
1965    /// Pre-built prog accessor from the accessor-init worker.
1966    /// When present, `collect_verifier_stats` skips the ~4s
1967    /// ELF/BTF parse and uses this directly.
1968    pub(crate) prog_accessor: Option<crate::monitor::bpf_prog::GuestMemProgAccessorOwned>,
1969    /// Guest-reported phys_base (biased +1). Used by
1970    /// `collect_verifier_stats` fallback when the pre-built prog
1971    /// accessor is unavailable.
1972    pub(crate) kern_phys_base: u64,
1973    /// Runtime virt-KASLR offset (kernel-image slide), captured from
1974    /// the freeze coordinator's `kern_virt_kaslr` Arc snapshot at run
1975    /// end via `load(Acquire).saturating_sub(1)`. `0` means either
1976    /// (a) KASLR was off (test ran with `#[ktstr_test(kaslr = false)]`
1977    /// or `Scheduler::kargs(&["nokaslr"])`), or (b) the derivation
1978    /// chain (MSR_LSTAR readback at `vmm::x86_64::msr_kaslr` +
1979    /// KERN_ADDRS `_text` path at `crate::vmm::freeze_coord::dispatch`) never
1980    /// published a non-zero value (early-boot crash, kallsyms masked
1981    /// by kptr_restrict, FRED-enabled kernel). E2E test consumers
1982    /// distinguish (a) from (b) by asserting against the test entry's
1983    /// `kaslr` attribute. The companion [`Self::kern_phys_base`]
1984    /// carries the kernel-image physical-randomization slide; together
1985    /// they identify the KASLR-randomized kernel layout.
1986    pub kern_kaslr_offset: u64,
1987    /// Virtio-console device shared with vCPU threads. Carries the
1988    /// port-1 (`ktstr-bulk`) TLV stream from guest to host;
1989    /// `collect_results` calls `drain_bulk()` after the run to feed
1990    /// `parse_tlv_stream` and produce the `BulkDrainResult` that
1991    /// `VmResult.guest_messages` exposes to test verdicts.
1992    pub(crate) virtio_con: Arc<crate::vmm::PiMutex<crate::vmm::virtio_console::VirtioConsole>>,
1993    /// Bulk TLV entries the freeze coordinator parsed from
1994    /// `port1_tx_buf` mid-run. The coord's TOKEN_TX handler reads
1995    /// the device's accumulated bulk bytes, feeds them through
1996    /// [`crate::vmm::bulk::HostAssembler`], and stashes every parsed
1997    /// frame here so [`super::KtstrVm::collect_results`] can merge
1998    /// them into `VmResult::guest_messages` alongside the post-exit
1999    /// `drain_bulk` and the post-mortem SHM CRASH-ring drain.
2000    /// Without this stash every EXIT / TEST / PAYLOAD_METRICS /
2001    /// PROFRAW frame consumed by the coord
2002    /// would vanish — only the leftover bytes that arrived on
2003    /// `port1_tx_buf` after the coord exited would reach the
2004    /// verdict, and a typical run would surface no metrics.
2005    pub(crate) bulk_messages: Arc<std::sync::Mutex<Vec<crate::vmm::wire::ShmEntry>>>,
2006    /// Scheduler-stats client constructed at the top of `run_vm`,
2007    /// or `None` when the run has no scheduler attached
2008    /// (`scheduler_binary` is `None` on the builder). Forwarded
2009    /// to [`VmResult::stats_client`] so test code can issue
2010    /// `request_raw` / typed `stats` / `stats_meta` calls through
2011    /// the run's lifetime. The drainer thread tears down when the
2012    /// last clone of the client drops; `None` here means no
2013    /// drainer was spawned at all, so the run pays no
2014    /// stats-bridge cost.
2015    pub(crate) stats_client: Option<super::SchedStatsClient>,
2016    /// Periodic captures actually fired by the freeze coordinator
2017    /// during the run (success + timeout-placeholder count).
2018    /// Forwarded to [`VmResult::periodic_fired`] from the run-loop's
2019    /// `next_periodic_idx` final value.
2020    pub(crate) periodic_fired: u32,
2021    /// Configured periodic-snapshot target (mirrors
2022    /// `KtstrVm::num_snapshots`). Forwarded to
2023    /// [`VmResult::periodic_target`] so test code can compute
2024    /// coverage as `fired / target`.
2025    pub(crate) periodic_target: u32,
2026    /// Host-side vCPU scheduling-dilation sample, read at `run_vm`
2027    /// teardown from each vCPU thread's `/proc/self/task/<tid>/schedstat`
2028    /// (see [`HostVcpuSchedstat`]). Forwarded verbatim to
2029    /// [`VmResult::host_vcpu_schedstat`]. `None` on hosts without
2030    /// `CONFIG_SCHEDSTATS` or when no vCPU thread was sampled.
2031    pub(crate) host_vcpu_schedstat: Option<HostVcpuSchedstat>,
2032}
2033#[cfg(test)]
2034mod tests {
2035    use super::*;
2036
2037    /// scheduler_log() concatenates the bulk-port SchedLog frames and
2038    /// slices the `SCHED_OUTPUT_START`/`END`-bracketed content (mirroring
2039    /// collect_verifier_output). A CRC-bad frame is dropped; with no valid
2040    /// SchedLog frames and an empty `output`, the log is empty. CI-runnable
2041    /// (no VM) — pins the accessor the demo_verifier post_vm assertions
2042    /// depend on, so a boot-path capture regression is caught even when the
2043    /// host-gated e2e cells skip under resource contention.
2044    #[test]
2045    fn scheduler_log_extracts_bracketed_content_and_drops_crc_bad() {
2046        use crate::vmm::host_comms::BulkDrainResult;
2047        use crate::vmm::wire::{MSG_TYPE_SCHED_LOG, ShmEntry};
2048
2049        let framed = "===SCHED_OUTPUT_START===\n\
2050            libbpf: prog 'ktstr_dispatch': BPF program load failed: -EACCES\n\
2051            -- BEGIN PROG LOAD LOG --\n0: (b7) r0 = 0\n-- END PROG LOAD LOG --\n\
2052            ===SCHED_OUTPUT_END===\n";
2053        let mut result = VmResult::test_fixture();
2054        result.guest_messages = Some(BulkDrainResult {
2055            entries: vec![ShmEntry {
2056                msg_type: MSG_TYPE_SCHED_LOG,
2057                payload: framed.as_bytes().to_vec(),
2058                crc_ok: true,
2059            }],
2060        });
2061        let log = result.scheduler_log();
2062        assert!(
2063            log.contains("-- BEGIN PROG LOAD LOG --"),
2064            "libbpf verifier-reject marker survives extraction: {log}"
2065        );
2066        assert!(
2067            log.contains("BPF program load failed"),
2068            "scheduler stderr content present: {log}"
2069        );
2070        assert!(
2071            !log.contains("SCHED_OUTPUT_START"),
2072            "wire brackets stripped by parse_sched_output: {log}"
2073        );
2074
2075        // A CRC-bad SchedLog frame is dropped; with no valid frames the
2076        // merged stream is empty and `output` (empty here) is the fallback,
2077        // so scheduler_log() is empty.
2078        let mut bad = VmResult::test_fixture();
2079        bad.guest_messages = Some(BulkDrainResult {
2080            entries: vec![ShmEntry {
2081                msg_type: MSG_TYPE_SCHED_LOG,
2082                payload: framed.as_bytes().to_vec(),
2083                crc_ok: false,
2084            }],
2085        });
2086        assert_eq!(bad.scheduler_log(), "", "crc-bad frame dropped -> empty");
2087    }
2088
2089    /// `HostVcpuSchedstat::dilation` = `1 + run_delay/on_cpu`, `None`
2090    /// when no on-CPU time was sampled (idle/no-vCPU or a
2091    /// CONFIG_SCHEDSTATS-off host reading `0 0 0`). Directional endpoints:
2092    /// zero run-delay -> exactly 1.0; run-delay == on-cpu -> 2.0; zero
2093    /// on-cpu -> None (distinguishable from a genuine 1.0).
2094    #[test]
2095    fn host_vcpu_schedstat_dilation_endpoints() {
2096        // R == 0 -> D == 1.0 (always got the CPU when runnable).
2097        let d = HostVcpuSchedstat {
2098            total_on_cpu_ns: 1_000,
2099            total_run_delay_ns: 0,
2100            sampled_vcpus: 1,
2101        }
2102        .dilation();
2103        assert_eq!(d, Some(1.0), "no run delay -> exactly 1.0");
2104        // R == C -> D == 2.0 (waited as long as it ran).
2105        let d = HostVcpuSchedstat {
2106            total_on_cpu_ns: 1_000,
2107            total_run_delay_ns: 1_000,
2108            sampled_vcpus: 2,
2109        }
2110        .dilation();
2111        assert_eq!(d, Some(2.0), "run delay == on-cpu -> 2.0");
2112        // C == 0 -> None (no on-cpu time: idle, no vCPU, or schedstats off).
2113        let d = HostVcpuSchedstat {
2114            total_on_cpu_ns: 0,
2115            total_run_delay_ns: 500,
2116            sampled_vcpus: 0,
2117        }
2118        .dilation();
2119        assert_eq!(d, None, "zero on-cpu -> None, not a synthetic 1.0");
2120    }
2121
2122    /// `step_throughput_in` reads the canonical CPU-denominated
2123    /// `iteration_rate`; it neither reconstructs nor exposes a wall rate.
2124    #[test]
2125    fn step_throughput_in_reads_canonical_iteration_rate() {
2126        use crate::assert::Phase;
2127        let buckets = vec![
2128            crate::assert::PhaseBucket {
2129                step_index: 1,
2130                metrics: [("iteration_rate".to_string(), 5_000.0)]
2131                    .into_iter()
2132                    .collect(),
2133                ..Default::default()
2134            },
2135            crate::assert::PhaseBucket {
2136                step_index: 2,
2137                metrics: [("iteration_rate".to_string(), 0.0)].into_iter().collect(),
2138                ..Default::default()
2139            },
2140            crate::assert::PhaseBucket {
2141                step_index: 3,
2142                ..Default::default()
2143            },
2144        ];
2145        assert_eq!(
2146            VmResult::step_throughput_in(&buckets, Phase::step(0)),
2147            Some(5000.0)
2148        );
2149        assert_eq!(
2150            VmResult::step_throughput_in(&buckets, Phase::step(1)),
2151            Some(0.0),
2152        );
2153        assert_eq!(VmResult::step_throughput_in(&buckets, Phase::step(2)), None);
2154        assert_eq!(
2155            VmResult::step_throughput_in(&buckets, Phase::BASELINE),
2156            None
2157        );
2158        assert_eq!(VmResult::step_throughput_in(&buckets, Phase::step(9)), None);
2159    }
2160
2161    #[test]
2162    fn kvm_stats_try_sum_distinguishes_absent_from_zero() {
2163        let totals = KvmStatsTotals {
2164            per_vcpu: vec![
2165                [("exits".to_string(), 0u64)].into_iter().collect(),
2166                [("exits".to_string(), 0u64)].into_iter().collect(),
2167            ],
2168        };
2169        // "exits" is published as 0 on every vCPU -> a measured zero.
2170        assert_eq!(totals.try_sum("exits"), Some(0));
2171        assert_eq!(totals.try_avg("exits"), Some(0));
2172        // "halt_exits" was never published -> absent, not zero.
2173        assert_eq!(totals.try_sum("halt_exits"), None);
2174        assert_eq!(totals.try_avg("halt_exits"), None);
2175        // sum/avg keep the 0-coercing behavior for both cases.
2176        assert_eq!(totals.sum("exits"), 0);
2177        assert_eq!(totals.sum("halt_exits"), 0);
2178        // No vCPUs at all -> try_avg None (no div-by-zero, no false 0).
2179        let empty = KvmStatsTotals { per_vcpu: vec![] };
2180        assert_eq!(empty.try_sum("exits"), None);
2181        assert_eq!(empty.try_avg("exits"), None);
2182    }
2183
2184    #[test]
2185    fn vm_result_fields_carry_values() {
2186        let r = VmResult {
2187            duration: Duration::from_secs(5),
2188            output: "hello world".into(),
2189            stderr: "boot log".into(),
2190            cleanup_duration: Some(Duration::from_millis(50)),
2191            ..VmResult::test_fixture()
2192        };
2193        assert!(r.success);
2194        assert_eq!(r.exit_code, 0);
2195        assert!(!r.timed_out);
2196        assert_eq!(r.duration, Duration::from_secs(5));
2197        assert_eq!(r.output, "hello world");
2198        assert_eq!(r.stderr, "boot log");
2199        assert!(r.monitor.is_none());
2200        assert!(r.guest_messages.is_none());
2201        assert!(r.stimulus_timeline().is_empty());
2202        assert_eq!(r.cleanup_duration, Some(Duration::from_millis(50)));
2203        assert!(r.virtio_blk_counters.is_none());
2204        // Second construction covers the opposite polarity of
2205        // every boolean/numeric field so no field is silently
2206        // dropped by a future refactor that only exercises the
2207        // success path.
2208        let r2 = VmResult {
2209            success: false,
2210            exit_code: 1,
2211            duration: Duration::from_millis(500),
2212            timed_out: true,
2213            virtio_blk_counters: Some(VirtioBlkCountersSnapshot::default()),
2214            periodic_fired: 3,
2215            periodic_real: 2,
2216            periodic_target: 7,
2217            ..VmResult::test_fixture()
2218        };
2219        assert!(!r2.success);
2220        assert_eq!(r2.exit_code, 1);
2221        assert!(r2.timed_out);
2222        assert_eq!(r2.duration, Duration::from_millis(500));
2223        assert!(r2.cleanup_duration.is_none());
2224        assert_eq!(r2.periodic_fired, 3);
2225        assert_eq!(r2.periodic_target, 7);
2226        // Opposite polarity: counters present. Reads must observe
2227        // the default-zero values for every field — a future field
2228        // added to VirtioBlkCountersSnapshot that doesn't initialise
2229        // to 0 would break the "fresh device reports zero activity"
2230        // contract that VmResult readers rely on. The snapshot was
2231        // taken from the device's atomic counters at collect_results
2232        // time, after every vCPU and worker thread joined; readers
2233        // see plain `u64` field reads with no atomic ordering needed.
2234        let counters = r2.virtio_blk_counters.as_ref().unwrap();
2235        assert_eq!(counters.reads_completed, 0);
2236        assert_eq!(counters.writes_completed, 0);
2237        assert_eq!(counters.flushes_completed, 0);
2238        assert_eq!(counters.bytes_read, 0);
2239        assert_eq!(counters.bytes_written, 0);
2240        assert_eq!(counters.throttled_count, 0);
2241        assert_eq!(counters.io_errors, 0);
2242        assert_eq!(counters.currently_throttled_gauge, 0);
2243        assert_eq!(counters.invalid_avail_idx_count, 0);
2244    }
2245
2246    #[test]
2247    fn vm_result_without_monitor_has_no_samples() {
2248        let r = VmResult {
2249            output: "test output".into(),
2250            ..VmResult::test_fixture()
2251        };
2252        assert!(r.monitor.is_none());
2253        // Output and exit_code must still be accessible.
2254        assert_eq!(r.output, "test output");
2255        assert_eq!(r.exit_code, 0);
2256    }
2257
2258    #[test]
2259    fn vm_result_with_monitor_carries_summary() {
2260        let summary = monitor::MonitorSummary {
2261            prog_stats_deltas: None,
2262            total_samples: 5,
2263            max_imbalance_ratio: 3.5,
2264            max_local_dsq_depth: 10,
2265            stuck_count: 1,
2266            event_deltas: None,
2267            schedstat_deltas: None,
2268            ..Default::default()
2269        };
2270        let report = monitor::MonitorReport {
2271            samples: vec![],
2272            summary: summary.clone(),
2273            ..Default::default()
2274        };
2275        let r = VmResult {
2276            success: false,
2277            exit_code: 1,
2278            duration: Duration::from_millis(500),
2279            timed_out: true,
2280            stderr: "kernel panic".into(),
2281            monitor: Some(report),
2282            ..VmResult::test_fixture()
2283        };
2284        let mon = r.monitor.as_ref().unwrap();
2285        assert_eq!(mon.summary.total_samples, 5);
2286        assert!((mon.summary.max_imbalance_ratio - 3.5).abs() < f64::EPSILON);
2287        assert_eq!(mon.summary.max_local_dsq_depth, 10);
2288        assert!(mon.summary.stuck_count > 0);
2289        assert!(r.timed_out);
2290        assert_eq!(r.exit_code, 1);
2291        assert_eq!(r.stderr, "kernel panic");
2292    }
2293
2294    /// Compile-time pin that `VmResult: Clone`. A future field
2295    /// added with a non-Clone type would break the derive at compile
2296    /// time and break this test's `let _: Self = self_clone(r)` call.
2297    /// Cheap insurance that nobody silently strips the Clone derive
2298    /// or adds a non-Clone field.
2299    #[test]
2300    fn vm_result_is_clone() {
2301        fn self_clone<T: Clone>(t: &T) -> T {
2302            t.clone()
2303        }
2304        let r = VmResult::test_fixture();
2305        let _: VmResult = self_clone(&r);
2306    }
2307
2308    /// Pin the documented aliasing semantic on the Arc-shared
2309    /// `snapshot_bridge` field: clones of `VmResult` share the
2310    /// underlying snapshot store. A future refactor that turned
2311    /// `SnapshotBridge` into a deep-copy struct would break this
2312    /// test — at which point the doc paragraph at the head of
2313    /// `VmResult` must be updated to drop the Arc-shared-handle
2314    /// category. Loud failure on contract drift, not a silent
2315    /// behavior change.
2316    #[test]
2317    fn vm_result_clone_snapshot_bridge_aliases_via_arc() {
2318        let r = VmResult::test_fixture();
2319        let c = r.clone();
2320        // Pre-condition: both bridges start empty.
2321        assert_eq!(r.snapshot_bridge.len(), 0);
2322        assert_eq!(c.snapshot_bridge.len(), 0);
2323        // Store a synthetic report through ONE clone's bridge.
2324        r.snapshot_bridge.store(
2325            "regression_pin",
2326            crate::monitor::dump::FailureDumpReport::default(),
2327        );
2328        // The OTHER clone observes the store — proves the Arc<Mutex<…>>
2329        // is shared, not deep-copied. If this assertion ever fires,
2330        // SnapshotBridge's Clone has changed shape and VmResult's
2331        // doc paragraph must be revisited.
2332        assert_eq!(
2333            r.snapshot_bridge.len(),
2334            c.snapshot_bridge.len(),
2335            "snapshot_bridge clones must observe the same store \
2336             per the VmResult Clone contract (Arc-shared handle)"
2337        );
2338        assert_eq!(c.snapshot_bridge.len(), 1);
2339    }
2340
2341    /// Build a `VmResult` whose snapshot bridge holds `n` periodic
2342    /// captures stamped into Step[0] (`step_index = 1`). No stimulus
2343    /// frames are attached, so `stimulus_timeline()` is empty and the
2344    /// bucketer falls back to each capture's stamped `step_index`.
2345    fn vm_result_with_periodic_captures(n: usize) -> VmResult {
2346        let r = VmResult {
2347            periodic_fired: n as u32,
2348            periodic_target: n as u32,
2349            ..VmResult::test_fixture()
2350        };
2351        for i in 0..n {
2352            r.snapshot_bridge.store_with_stats_and_step(
2353                &format!("periodic_{i}"),
2354                crate::monitor::dump::FailureDumpReport::default(),
2355                None,
2356                Some(i as u64 * 100),
2357                None,
2358                1,
2359            );
2360        }
2361        r
2362    }
2363
2364    /// Regression for the drain-once starvation bug: the snapshot
2365    /// bridge is drained EXACTLY once and the resulting series is
2366    /// shared, so a `post_vm`-style consumer reading the series does
2367    /// not starve a later framework-style consumer. Before
2368    /// [`VmResult::captures_series`], `periodic_series()` drained the
2369    /// bridge directly and a second reader saw an empty bridge — the
2370    /// silent-data-drop this task de-conflicts.
2371    #[test]
2372    fn captures_series_shared_across_consumers() {
2373        let r = vm_result_with_periodic_captures(3);
2374        // First consumer = post_vm style (drains the bridge into the cache).
2375        let post_vm_series = r.periodic_series();
2376        assert_eq!(
2377            post_vm_series.len(),
2378            3,
2379            "post_vm consumer must see all captures"
2380        );
2381        // Second consumer = framework style (reads the cache, no re-drain).
2382        let framework_series = r.captures_series();
2383        assert_eq!(
2384            framework_series.len(),
2385            3,
2386            "framework consumer must NOT see an empty bridge — the single \
2387             cached drain is shared, not re-drained (pre-cache this was 0)"
2388        );
2389        // The raw bridge was consumed exactly once: a direct drain now
2390        // yields nothing because captures_series() took ownership of the
2391        // captures into the cache on first read.
2392        assert_eq!(
2393            r.snapshot_bridge.drain_ordered_with_stats().len(),
2394            0,
2395            "captures_series() performs the single destructive drain"
2396        );
2397    }
2398
2399    /// `phase_buckets()` folds the cached captures into per-phase
2400    /// buckets without the caller draining the bridge — the
2401    /// phase-buckets accessor. Idempotent: a second call returns the same vec from
2402    /// the shared cache.
2403    #[test]
2404    fn phase_buckets_from_cached_captures() {
2405        let r = vm_result_with_periodic_captures(2);
2406        let buckets = r.phase_buckets();
2407        assert!(
2408            !buckets.is_empty(),
2409            "phase_buckets must yield buckets from the cached captures"
2410        );
2411        assert!(
2412            buckets.iter().any(|b| b.step_index >= 1),
2413            "captures stamped step_index=1 must produce a Step bucket, got {:?}",
2414            buckets.iter().map(|b| b.step_index).collect::<Vec<_>>(),
2415        );
2416        assert_eq!(
2417            r.phase_buckets(),
2418            buckets,
2419            "phase_buckets() must be idempotent (shared cache)"
2420        );
2421    }
2422
2423    /// Clone semantics, category 3 (the `periodic_series_cache` field):
2424    /// a clone taken AFTER the cache is populated carries an
2425    /// INDEPENDENT copy, so `phase_buckets()` on both the original and
2426    /// the clone returns identical non-empty buckets without
2427    /// re-touching the (already-drained) shared bridge. Pins the
2428    /// documented safe path.
2429    #[test]
2430    fn vm_result_clone_after_cache_populated_carries_buckets() {
2431        let r = vm_result_with_periodic_captures(2);
2432        // Populate the cache BEFORE cloning (the documented safe path).
2433        let original = r.phase_buckets();
2434        assert!(!original.is_empty());
2435        let c = r.clone();
2436        let cloned = c.phase_buckets();
2437        assert!(!cloned.is_empty());
2438        assert_eq!(
2439            cloned, original,
2440            "a clone taken after cache population must carry the same \
2441             buckets (category-3 independent-once-populated semantics)"
2442        );
2443    }
2444
2445    /// `phase_metric` keys by `Phase` (1-indexed wire `step_index`) and
2446    /// delegates to the matching bucket's `get()`: it returns each
2447    /// present metric's value, `None` for an unknown metric on an
2448    /// existing phase, and `None` for a phase with no bucket. (The
2449    /// Some-value read itself is `PhaseBucket::get`, pinned by its own
2450    /// tests; this pins the phase-keying and the None contract.)
2451    #[test]
2452    fn phase_metric_keys_by_phase_and_delegates_to_bucket_get() {
2453        let r = vm_result_with_periodic_captures(2);
2454        // The captures are stamped step_index=1 -> Phase::step(0).
2455        let p0 = crate::assert::Phase::step(0);
2456        let buckets = r.phase_buckets();
2457        let step0 = buckets
2458            .iter()
2459            .find(|b| b.step_index == p0.as_u16())
2460            .expect("a Step[0] bucket from the stamped captures (keys by step_index)");
2461        // Some-path delegation: for every metric the matching bucket
2462        // carries, phase_metric returns that exact value. The
2463        // default-report fixture may fold no metrics, so this loop can be
2464        // empty — the keying + None assertions below pin the rest.
2465        for (name, val) in &step0.metrics {
2466            assert_eq!(
2467                r.phase_metric(p0, name),
2468                Some(*val),
2469                "phase_metric must return the matching bucket's value for present metric '{name}'",
2470            );
2471        }
2472        // A name absent from the bucket -> None (the bucket is still found).
2473        assert_eq!(
2474            r.phase_metric(p0, "definitely_not_a_registry_metric"),
2475            None,
2476            "an unknown metric name yields None even when the phase has a bucket",
2477        );
2478        // A phase with no bucket -> None (not a panic, not a wrong bucket).
2479        assert_eq!(
2480            r.phase_metric(crate::assert::Phase::step(99), "iteration_rate"),
2481            None,
2482            "a phase with no bucket yields None",
2483        );
2484    }
2485
2486    /// Build a guest `AssertResult` carrying ONE per-phase per-cgroup
2487    /// carrier at `step_index` (the merge-neutral `(u64::MAX, 0)` window
2488    /// `fold_guest_per_cgroup_into_host_buckets` requires) and wrap it in
2489    /// the `MSG_TYPE_TEST_RESULT` TLV a real run leaves on
2490    /// `guest_messages`, so `VmResult::guest_assert_result` decodes it.
2491    fn guest_drain_with_per_cgroup(
2492        step_index: u16,
2493        carriers: &[(&str, u64, u64)],
2494    ) -> crate::vmm::host_comms::BulkDrainResult {
2495        let mut per_cgroup = std::collections::BTreeMap::new();
2496        for &(name, migrations, iters) in carriers {
2497            per_cgroup.insert(
2498                name.to_string(),
2499                crate::assert::PhaseCgroupStats {
2500                    total_migrations: migrations,
2501                    total_iterations: iters,
2502                    ..Default::default()
2503                },
2504            );
2505        }
2506        let mut guest = crate::test_support::test_helpers::build_assert_result(true, vec![]);
2507        guest.stats.phases = vec![crate::assert::PhaseBucket {
2508            step_index,
2509            label: crate::assert::Phase::from(step_index).to_string(),
2510            // Merge-neutral window: fold_guest_per_cgroup_into_host_buckets
2511            // debug_asserts guest carriers carry exactly (u64::MAX, 0).
2512            start_ms: u64::MAX,
2513            end_ms: 0,
2514            sample_count: 0,
2515            metrics: std::collections::BTreeMap::new(),
2516            per_cgroup,
2517        }];
2518        crate::vmm::host_comms::BulkDrainResult {
2519            entries: vec![crate::test_support::test_helpers::assert_result_tlv_entry(
2520                &guest,
2521            )],
2522        }
2523    }
2524
2525    /// `phase_buckets()` folds the guest per-cgroup carriers (parsed from
2526    /// `guest_messages`) into the host buckets keyed by `step_index`, so the
2527    /// returned buckets carry `per_cgroup`; `phase_cgroup` reads one cgroup
2528    /// out of the folded bucket. Pins the guest-carrier fold: the host
2529    /// captures stamp step_index=1 == `Phase::step(0)`, the carrier matches
2530    /// it, and the matched arm unions the carrier's `per_cgroup` into that
2531    /// bucket.
2532    #[test]
2533    fn phase_buckets_folds_guest_per_cgroup_carriers() {
2534        let r = VmResult {
2535            guest_messages: Some(guest_drain_with_per_cgroup(1, &[("cellA", 7, 11)])),
2536            ..vm_result_with_periodic_captures(2)
2537        };
2538        let buckets = r.phase_buckets();
2539        let step0 = buckets
2540            .iter()
2541            .find(|b| b.step_index == crate::assert::Phase::step(0).as_u16())
2542            .expect("host bucket at step_index=1 from the stamped captures");
2543        let cg = step0
2544            .per_cgroup
2545            .get("cellA")
2546            .expect("matched-arm fold must carry the guest carrier's per_cgroup");
2547        assert_eq!(cg.total_migrations, 7);
2548        assert_eq!(cg.total_iterations, 11);
2549        // phase_cgroup is the per-(phase, cgroup) accessor over the same fold.
2550        let via_accessor = r
2551            .phase_cgroup(crate::assert::Phase::step(0), "cellA")
2552            .expect("phase_cgroup must reach the folded carrier");
2553        assert_eq!(via_accessor.total_migrations, 7);
2554        // A cgroup the phase never had -> None (not measured).
2555        assert!(
2556            r.phase_cgroup(crate::assert::Phase::step(0), "nope")
2557                .is_none()
2558        );
2559    }
2560
2561    /// `phase_metric("total_migrations")` resolves the per-phase
2562    /// cross-cgroup SUM via the `cgroup_counter_total` fallback — the key
2563    /// lives ONLY in `per_cgroup` (its `read_sample` is `None`, so
2564    /// `build_phase_buckets` never folds it into `bucket.metrics`, so
2565    /// `get()` misses). Two cgroups in the phase sum: 7 + 3 = 10. Without
2566    /// the `cgroup_counter_total` fallback, `phase_metric` returns a silent
2567    /// `None` for these keys.
2568    #[test]
2569    fn phase_metric_resolves_total_migrations_from_per_cgroup() {
2570        let r = VmResult {
2571            guest_messages: Some(guest_drain_with_per_cgroup(
2572                1,
2573                &[("cellA", 7, 5), ("cellB", 3, 6)],
2574            )),
2575            ..vm_result_with_periodic_captures(2)
2576        };
2577        assert_eq!(
2578            r.phase_metric(crate::assert::Phase::step(0), "total_migrations"),
2579            Some(10.0),
2580            "cross-cgroup sum across per_cgroup carriers (7 + 3)",
2581        );
2582        // The total_iterations arm of cgroup_counter_total resolves too (5 + 6).
2583        assert_eq!(
2584            r.phase_metric(crate::assert::Phase::step(0), "total_iterations"),
2585            Some(11.0),
2586            "cross-cgroup sum of the total_iterations per_cgroup counter (5 + 6)",
2587        );
2588        // A carrier-bearing phase that counted zero is a measured Some(0.0),
2589        // distinct from a phase with no carrier (None).
2590        let r0 = VmResult {
2591            guest_messages: Some(guest_drain_with_per_cgroup(1, &[("cellA", 0, 0)])),
2592            ..vm_result_with_periodic_captures(2)
2593        };
2594        assert_eq!(
2595            r0.phase_metric(crate::assert::Phase::step(0), "total_migrations"),
2596            Some(0.0),
2597            "carriers present but counted zero is a measured Some(0.0)",
2598        );
2599        // No carriers at all (guest_messages with no per_cgroup) -> None.
2600        let r_none = vm_result_with_periodic_captures(2);
2601        assert_eq!(
2602            r_none.phase_metric(crate::assert::Phase::step(0), "total_migrations"),
2603            None,
2604            "no per_cgroup carrier in the phase -> None (not measured)",
2605        );
2606    }
2607
2608    /// A guest carrier whose `step_index` has NO matching host bucket takes
2609    /// the fold's ORPHAN arm: it is appended with its merge-neutral
2610    /// `(u64::MAX, 0)` window normalized to `(0, 0)`, and stays reachable
2611    /// through the public accessors. The host captures stamp step_index=1
2612    /// only, so a step_index=2 carrier is an orphan. Pins that
2613    /// `phase_cgroup` reaches the orphan and the window does not underflow
2614    /// duration consumers (`end_ms - start_ms == 0`, not `0 - u64::MAX`).
2615    #[test]
2616    fn phase_buckets_orphan_carrier_reachable_via_phase_cgroup() {
2617        let r = VmResult {
2618            // step_index 2 == Phase::step(1); no host capture stamps step 2.
2619            guest_messages: Some(guest_drain_with_per_cgroup(2, &[("orphanCell", 4, 0)])),
2620            ..vm_result_with_periodic_captures(2)
2621        };
2622        let buckets = r.phase_buckets();
2623        let orphan = buckets
2624            .iter()
2625            .find(|b| b.step_index == crate::assert::Phase::step(1).as_u16())
2626            .expect("orphan carrier must be appended as its own bucket");
2627        assert_eq!(
2628            (orphan.start_ms, orphan.end_ms),
2629            (0, 0),
2630            "orphan arm normalizes the (u64::MAX, 0) sentinel window to (0, 0)",
2631        );
2632        assert_eq!(
2633            r.phase_cgroup(crate::assert::Phase::step(1), "orphanCell")
2634                .map(|c| c.total_migrations),
2635            Some(4),
2636            "phase_cgroup must reach an orphan carrier",
2637        );
2638    }
2639
2640    /// With no guest verdict (guest_messages None — host-only run / early
2641    /// crash), `guest_assert_result()` is Err and `phase_buckets()` returns
2642    /// the host-rebuilt buckets ALONE: non-empty (captures landed) with every
2643    /// `per_cgroup` empty. Pins the Err arm (the prior behavior) carries the
2644    /// host buckets, no panic.
2645    #[test]
2646    fn phase_buckets_without_guest_verdict_is_host_only() {
2647        let r = vm_result_with_periodic_captures(2);
2648        assert!(
2649            r.guest_assert_result().is_err(),
2650            "test_fixture has no guest verdict"
2651        );
2652        let buckets = r.phase_buckets();
2653        assert!(
2654            !buckets.is_empty(),
2655            "host captures must still yield buckets"
2656        );
2657        assert!(
2658            buckets.iter().all(|b| b.per_cgroup.is_empty()),
2659            "no guest carriers -> every per_cgroup stays empty",
2660        );
2661    }
2662
2663    /// A guest per-cgroup carrier carrying NON-EMPTY sample vectors
2664    /// (run_delays_ns / off_cpu_pcts / wake_latencies_ns) survives the
2665    /// guest->host postcard round-trip (assert_result_tlv_entry encode ->
2666    /// guest_assert_result decode) and the fold verbatim, and the
2667    /// PhaseCgroupStats summary methods reduce them post-decode. The
2668    /// guest_drain_with_per_cgroup helper carries only counters (empty
2669    /// vecs), so this pins the sample-vec wire fidelity that helper does not.
2670    #[test]
2671    fn guest_carrier_sample_vecs_survive_postcard_and_fold() {
2672        let mut pc = std::collections::BTreeMap::new();
2673        pc.insert(
2674            "cellA".to_string(),
2675            crate::assert::PhaseCgroupStats {
2676                total_migrations: 2,
2677                run_delays_ns: vec![10, 20, 30],
2678                off_cpu_pcts: vec![1.5, 2.5],
2679                wake_latencies_ns: vec![100, 200],
2680                wake_sample_total: 2,
2681                ..Default::default()
2682            },
2683        );
2684        let mut guest = crate::test_support::test_helpers::build_assert_result(true, vec![]);
2685        guest.stats.phases = vec![crate::assert::PhaseBucket {
2686            step_index: 1,
2687            label: "Step[0]".to_string(),
2688            start_ms: u64::MAX,
2689            end_ms: 0,
2690            sample_count: 0,
2691            metrics: std::collections::BTreeMap::new(),
2692            per_cgroup: pc,
2693        }];
2694        let r = VmResult {
2695            guest_messages: Some(crate::vmm::host_comms::BulkDrainResult {
2696                entries: vec![crate::test_support::test_helpers::assert_result_tlv_entry(
2697                    &guest,
2698                )],
2699            }),
2700            ..vm_result_with_periodic_captures(2)
2701        };
2702        let cg = r
2703            .phase_cgroup(crate::assert::Phase::step(0), "cellA")
2704            .expect("carrier survives postcard + fold");
2705        // Sample vectors round-trip byte-for-byte through the wire.
2706        assert_eq!(cg.run_delays_ns, vec![10, 20, 30]);
2707        assert_eq!(cg.off_cpu_pcts, vec![1.5, 2.5]);
2708        assert_eq!(cg.wake_latencies_ns, vec![100, 200]);
2709        // And the summary methods reduce the decoded samples (worst = max(ns)/1000).
2710        let (_, worst_us) = cg
2711            .run_delay_summary()
2712            .expect("non-empty run_delays -> Some");
2713        assert_eq!(worst_us, 30.0 / 1000.0);
2714    }
2715
2716    #[cfg(feature = "wprof")]
2717    #[test]
2718    fn vm_result_wprof_pb_path_bails_when_entry_name_none() {
2719        let r = VmResult::test_fixture();
2720        assert!(r.entry_name.is_none());
2721        let err = r.wprof_pb_path().expect_err("None entry_name must Err");
2722        let msg = format!("{err:#}");
2723        assert!(
2724            msg.contains("entry_name"),
2725            "diagnostic must name the missing field: {msg}",
2726        );
2727        assert!(
2728            msg.contains("run_ktstr_test_inner_impl"),
2729            "diagnostic must name the stamping site so the operator \
2730             can trace the missing-stamp path: {msg}",
2731        );
2732    }
2733
2734    #[cfg(feature = "wprof")]
2735    #[test]
2736    fn vm_result_wprof_pb_path_returns_writer_mirror_path() {
2737        let r = VmResult {
2738            entry_name: Some("vm_result_wprof_pb_path_returns_writer_mirror_path_fixture"),
2739            variant_hash: 0xab,
2740            ..VmResult::test_fixture()
2741        };
2742        let path = r.wprof_pb_path().expect("Some entry_name must Ok");
2743        // The path's file_name must exactly match
2744        // `<entry_name>-<variant_hash:016x>.wprof.pb` — the writer uses
2745        // the same variant-keyed pattern (the wprof writer reads this
2746        // very method). A divergence would mean the method derives a
2747        // different path than the writer wrote to, surfacing as ENOENT in
2748        // the post_vm callback.
2749        let file_name = path.file_name().and_then(|n| n.to_str()).unwrap();
2750        assert_eq!(
2751            file_name,
2752            "vm_result_wprof_pb_path_returns_writer_mirror_path_fixture-00000000000000ab.wprof.pb",
2753        );
2754    }
2755
2756    #[cfg(feature = "wprof")]
2757    #[test]
2758    fn vm_result_repro_wprof_pb_path_bails_when_entry_name_none() {
2759        let r = VmResult::test_fixture();
2760        let err = r
2761            .repro_wprof_pb_path()
2762            .expect_err("None entry_name must Err");
2763        let msg = format!("{err:#}");
2764        assert!(msg.contains("entry_name"));
2765        assert!(msg.contains("run_ktstr_test_inner_impl"));
2766    }
2767
2768    #[cfg(feature = "wprof")]
2769    #[test]
2770    fn vm_result_repro_wprof_pb_path_returns_writer_mirror_path() {
2771        let r = VmResult {
2772            entry_name: Some("vm_result_repro_wprof_pb_path_fixture"),
2773            variant_hash: 0xab,
2774            ..VmResult::test_fixture()
2775        };
2776        let path = r.repro_wprof_pb_path().expect("Some entry_name must Ok");
2777        let file_name = path.file_name().and_then(|n| n.to_str()).unwrap();
2778        assert_eq!(
2779            file_name,
2780            "vm_result_repro_wprof_pb_path_fixture-00000000000000ab.repro.wprof.pb"
2781        );
2782    }
2783
2784    #[cfg(feature = "wprof")]
2785    #[test]
2786    fn vm_result_assert_wprof_pb_landed_skips_when_success_false() {
2787        let r = VmResult {
2788            success: false,
2789            ..VmResult::test_fixture()
2790        };
2791        assert!(r.entry_name.is_none());
2792        let result = r.assert_wprof_pb_landed();
2793        assert!(
2794            result.is_ok(),
2795            "assert_wprof_pb_landed must Ok-skip on !success EVEN when \
2796             entry_name is None — the entry_name pre-check is downstream of \
2797             the success short-circuit. Got: {result:?}",
2798        );
2799    }
2800}