Module temporal 

Temporal-assertion patterns over a periodic SampleSeries.

SeriesField<T> is a per-sample column extracted from the series via SampleSeries::bpf or SampleSeries::stats (or the typed bpf_map / stats_path projectors). It carries a parallel (tag, elapsed_ms, SnapshotResult<T>) triple per sample so any failure-path message can name the offending tag and timestamp without re-walking the source data.

The seven built-in patterns are:

1. nondecreasing — counter monotonicity (v[i] <= v[i+1]).
2. strictly_increasing — strict counter monotonicity (v[i] < v[i+1]).
3. rate_within(lo, hi) — bounded delta-per-millisecond between consecutive samples.
4. steady_within(warmup, tolerance) — post-warmup samples stay inside [mean·(1-tol), mean·(1+tol)].
5. converges_to(target, tol, deadline_ms) — three consecutive samples land inside [target-tol, target+tol] at or before deadline_ms.
6. always_true — boolean invariant at every sample (SeriesField<bool> only).
7. ratio_within(other, lo, hi) — cross-field correlation between two same-length series.

Per-sample scalar checks bypass the temporal patterns via SeriesField::each, which yields an EachClaim supporting at_least / at_most / between. All patterns route through Verdict and tag failures with DetailKind::Temporal.

Structs

BetterThanPhase

Cross-phase “is the candidate phase better than the baseline phase on this metric?” comparator, returned by crate::vmm::VmResult::better_across_phases (pooled aggregate) and crate::vmm::VmResult::better_across_phases_cgroup (one named cgroup). The polarity-aware sibling of CrossPhaseRatio: it reads two PER-PHASE scalars (via phase_metric / phase_cgroup_metric, not a sampled series) and orients “better” from the metric’s registry-declared polarity, so the same call expresses “scheduler beats EEVDF” for a LowerBetter latency AND a HigherBetter throughput without the test author naming a direction. A missing/undirected/zero-baseline comparison is Inconclusive (never a silent pass); a non-finite value is a Fail.

ClaimBetter

Direct-claim “is this candidate better than this baseline on a registered metric?” comparator, returned by Verdict::claim_better. The polarity-aware sibling of crate::vmm::VmResult::better_across_phases for the case where the test already HOLDS two scalar values (not two phases): it orients “better” from the metric’s registry-declared polarity, so the SAME call expresses “candidate beats baseline” for a LowerBetter latency AND a HigherBetter throughput without the test author naming a direction. A metric with no lower/higher-better polarity (TargetValue / Unknown / Informational / an unregistered or typo’d name) is INCONCLUSIVE (never a silent pass); a non-finite endpoint is a Fail.

CrossPhaseRatio

Cross-phase ratio builder returned by SeriesField::ratio_across_phases and PhaseMapExt::ratio_across_phases. Carries the resolved (earlier, later) values and a caller-supplied label so the terminal comparator chain (at_most) can format both values and the ratio into a single failure-or-note message. Mirrors the EachClaim shape (mutable verdict borrow held through the chain).

EachClaim

Per-sample scalar claim builder returned by SeriesField::each. Provides at_least / at_most / between — comparators that apply to every (successfully projected) sample independently. Per-sample errors from the projection (missing field, type mismatch) are routed through the verdict as failures so coverage gaps are never silent.

SeriesField

Per-sample column extracted from a SampleSeries. Each slot is a SnapshotResult<T> so a missing or type-mismatched field does NOT abort the whole projection — it surfaces at the temporal-assertion site as a per-sample error the caller decides how to handle.

Traits

FracPair

Per-phase “share of total” reducer. Specialized for the dominant counter shape (BTreeMap<Phase, u64>) because u64: Into<f64> is intentionally absent (cast is lossy) — a generic PhaseMapExt method with an Into<f64> bound would reject every counter-delta map test authors actually reach for.

PhaseMapExt

Extension trait that lets a pre-reduced per-phase map (typically the output of SeriesField::counter_delta_per_phase, SeriesField::last_per_phase, or SeriesField::first_per_phase) compose with the cross-phase comparator chain SeriesField::ratio_across_phases exposes — without re-projecting the per-phase values back through a synthetic SeriesField.

Type Aliases

ByPhasePartition

Return shape of SeriesField::by_phase: a BTreeMap keyed by Phase carrying the samples whose source row had a stamped step_index, plus a separate none_bucket for unstamped / fixture samples.

SampleTriple

Per-sample triple (tag, elapsed_ms, &value) yielded by SeriesField::iter_full and stored in the per-phase buckets returned by SeriesField::by_phase.