Skip to main content

ftui_runtime/
conformal_predictor.rs

1#![forbid(unsafe_code)]
2
3//! Conformal predictor for frame-time risk (bd-3e1t.3.2).
4//!
5//! Finite-sample upper bounds require exchangeable calibration and future
6//! residuals in the population being calibrated. Rolling adaptive timings and
7//! pooled fallback buckets do not by themselves establish that assumption or
8//! conditional coverage for the requested bucket. Missing ranks are explicit;
9//! a warmup estimate is never reported as a calibrated bound.
10//!
11//! See docs/spec/state-machines.md section 3.13 for the governing spec.
12
13use std::collections::{HashMap, VecDeque};
14use std::fmt;
15
16use ftui_render::diff_strategy::DiffStrategy;
17
18use crate::terminal_writer::ScreenMode;
19
20/// Configuration for conformal frame-time prediction.
21#[derive(Debug, Clone)]
22pub struct ConformalConfig {
23    /// Significance level alpha. Marginal coverage is >= 1 - alpha only when
24    /// calibration and future residuals are exchangeable.
25    /// Default: 0.05.
26    pub alpha: f64,
27
28    /// Minimum samples before calibration, in addition to an attainable rank.
29    /// Default: 20.
30    pub min_samples: usize,
31
32    /// Maximum samples retained per bucket (rolling window).
33    /// Default: 256.
34    pub window_size: usize,
35
36    /// Conservative fallback residual (microseconds) when no calibration exists.
37    /// Default: 10_000.0 (10ms).
38    pub q_default: f64,
39}
40
41impl Default for ConformalConfig {
42    fn default() -> Self {
43        Self {
44            alpha: 0.05,
45            min_samples: 20,
46            window_size: 256,
47            q_default: 10_000.0,
48        }
49    }
50}
51
52/// Invalid conformal calibration configuration.
53#[derive(Debug, Clone, Copy, PartialEq, Eq)]
54pub struct ConformalConfigError(pub &'static str);
55
56impl fmt::Display for ConformalConfigError {
57    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
58        f.write_str(self.0)
59    }
60}
61
62impl std::error::Error for ConformalConfigError {}
63
64impl ConformalConfig {
65    /// Validate without silently replacing an invalid policy with defaults.
66    pub fn validate(&self) -> Result<(), ConformalConfigError> {
67        if !self.alpha.is_finite() || self.alpha <= 0.0 || self.alpha >= 1.0 {
68            return Err(ConformalConfigError(
69                "alpha must be finite and strictly between zero and one",
70            ));
71        }
72        if self.min_samples == 0 || self.window_size == 0 {
73            return Err(ConformalConfigError(
74                "calibration sample and window counts must be positive",
75            ));
76        }
77        if self.min_samples > self.window_size {
78            return Err(ConformalConfigError(
79                "minimum samples must fit in the calibration window",
80            ));
81        }
82        if !self.q_default.is_finite() || self.q_default < 0.0 {
83            return Err(ConformalConfigError(
84                "warmup residual must be finite and nonnegative",
85            ));
86        }
87        Ok(())
88    }
89}
90
91/// Bucket identifier for conformal calibration.
92#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
93pub struct BucketKey {
94    pub mode: ModeBucket,
95    pub diff: DiffBucket,
96    pub size_bucket: u8,
97}
98
99impl BucketKey {
100    /// Create a bucket key from rendering context.
101    pub fn from_context(
102        screen_mode: ScreenMode,
103        diff_strategy: DiffStrategy,
104        cols: u16,
105        rows: u16,
106    ) -> Self {
107        Self {
108            mode: ModeBucket::from_screen_mode(screen_mode),
109            diff: DiffBucket::from(diff_strategy),
110            size_bucket: size_bucket(cols, rows),
111        }
112    }
113}
114
115/// Mode bucket for conformal calibration.
116#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
117pub enum ModeBucket {
118    Inline,
119    InlineAuto,
120    AltScreen,
121}
122
123impl ModeBucket {
124    pub fn as_str(self) -> &'static str {
125        match self {
126            Self::Inline => "inline",
127            Self::InlineAuto => "inline_auto",
128            Self::AltScreen => "altscreen",
129        }
130    }
131
132    pub fn from_screen_mode(mode: ScreenMode) -> Self {
133        match mode {
134            ScreenMode::Inline { .. } => Self::Inline,
135            ScreenMode::InlineAuto { .. } => Self::InlineAuto,
136            ScreenMode::AltScreen => Self::AltScreen,
137        }
138    }
139}
140
141/// Diff strategy bucket for conformal calibration.
142#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
143pub enum DiffBucket {
144    Full,
145    DirtyRows,
146    FullRedraw,
147}
148
149impl DiffBucket {
150    pub fn as_str(self) -> &'static str {
151        match self {
152            Self::Full => "full",
153            Self::DirtyRows => "dirty",
154            Self::FullRedraw => "redraw",
155        }
156    }
157}
158
159impl From<DiffStrategy> for DiffBucket {
160    fn from(strategy: DiffStrategy) -> Self {
161        match strategy {
162            DiffStrategy::Full => Self::Full,
163            DiffStrategy::DirtyRows => Self::DirtyRows,
164            DiffStrategy::FullRedraw => Self::FullRedraw,
165        }
166    }
167}
168
169impl fmt::Display for BucketKey {
170    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
171        write!(
172            f,
173            "{}:{}:{}",
174            self.mode.as_str(),
175            self.diff.as_str(),
176            self.size_bucket
177        )
178    }
179}
180
181/// Whether a finite bound can be used for the requested calibration population.
182#[derive(Debug, Clone, Copy, PartialEq, Eq)]
183pub enum ConformalStatus {
184    /// The selected population has fewer than the configured minimum samples.
185    Warmup,
186    /// A finite order statistic exists; coverage still requires exchangeability.
187    Calibrated,
188    /// The requested order statistic lies beyond the retained residuals.
189    UnattainableRank,
190    /// The baseline or budget is nonfinite or negative.
191    InvalidInput,
192    /// Adding otherwise finite timings exceeded the finite numeric range.
193    ArithmeticOverflow,
194}
195
196impl ConformalStatus {
197    pub const fn as_str(self) -> &'static str {
198        match self {
199            Self::Warmup => "warmup",
200            Self::Calibrated => "calibrated",
201            Self::UnattainableRank => "unattainable_rank",
202            Self::InvalidInput => "invalid_input",
203            Self::ArithmeticOverflow => "arithmetic_overflow",
204        }
205    }
206}
207
208/// Prediction output with explicit unavailable-bound evidence.
209#[derive(Debug, Clone)]
210pub struct ConformalPrediction {
211    /// Finite upper bound, absent during warmup or when no bound is available.
212    pub upper_us: Option<f64>,
213    /// Budget risk. An unavailable post-warmup bound cannot certify low risk.
214    pub risk: bool,
215    /// Requested coverage, present only for a calibrated finite bound.
216    /// This is a marginal guarantee only under exchangeability of the scores.
217    pub confidence: Option<f64>,
218    /// Requested error rate, independently of whether a bound is available.
219    pub alpha: f64,
220    pub status: ConformalStatus,
221    /// One-based rank, including the unavailable n+1 rank.
222    pub required_rank: usize,
223    /// Heuristic used during warmup, without a coverage claim.
224    pub warmup_upper_us: Option<f64>,
225    /// Bucket key used for calibration (may be fallback aggregate).
226    pub bucket: BucketKey,
227    /// Calibration sample count used for the quantile.
228    pub sample_count: usize,
229    /// Available order statistic q_b; no observed maximum substitutes for n+1.
230    pub quantile: Option<f64>,
231    /// Fallback level (0 = exact, 1 = mode+diff, 2 = mode, 3 = global/default).
232    pub fallback_level: u8,
233    /// Rolling window size.
234    pub window_size: usize,
235    /// Total reset count for this predictor.
236    pub reset_count: u64,
237    /// Base prediction f(x_t).
238    pub y_hat: f64,
239    /// Frame budget in microseconds.
240    pub budget_us: f64,
241}
242
243impl ConformalPrediction {
244    /// Format this prediction as a JSONL line for structured logging.
245    #[must_use]
246    pub fn to_jsonl(&self) -> String {
247        let number = finite_json_number;
248        format!(
249            r#"{{"schema":"conformal-v2","upper_us":{},"risk":{},"confidence":{},"alpha":{},"status":"{}","required_rank":{},"warmup_upper_us":{},"bucket":"{}","samples":{},"quantile":{},"fallback_level":{},"window":{},"resets":{},"y_hat":{},"budget_us":{}}}"#,
250            number(self.upper_us, 1),
251            self.risk,
252            number(self.confidence, 17),
253            number(Some(self.alpha), 17),
254            self.status.as_str(),
255            self.required_rank,
256            number(self.warmup_upper_us, 1),
257            self.bucket,
258            self.sample_count,
259            number(self.quantile, 2),
260            self.fallback_level,
261            self.window_size,
262            self.reset_count,
263            number(Some(self.y_hat), 1),
264            number(Some(self.budget_us), 1),
265        )
266    }
267}
268
269pub(crate) fn finite_json_number(value: Option<f64>, precision: usize) -> String {
270    value.filter(|v| v.is_finite()).map_or_else(
271        || "null".to_string(),
272        |value| {
273            // Fixed formatting of MAX produces hundreds of digits that some
274            // JSON parsers round out of range. Tiny policy values must not
275            // round to zero either. Scientific notation preserves both ends.
276            let magnitude = value.abs();
277            if magnitude >= 1.0e16
278                || (magnitude > 0.0 && magnitude < 10.0_f64.powi(-(precision as i32)))
279            {
280                format!("{value:e}")
281            } else {
282                let fixed = format!("{value:.precision$}");
283                if fixed.parse::<f64>() == Ok(value) {
284                    fixed
285                } else {
286                    // Evidence must preserve the bound, not round it to a
287                    // display precision that could fall below an observation.
288                    format!("{value:e}")
289                }
290            }
291        },
292    )
293}
294
295/// Update metadata after observing a frame.
296#[derive(Debug, Clone)]
297pub struct ConformalUpdate {
298    /// Accepted residual (y_t - f(x_t)); absent for invalid observations.
299    pub residual: Option<f64>,
300    /// Bucket updated.
301    pub bucket: BucketKey,
302    /// New sample count in the bucket.
303    pub sample_count: usize,
304}
305
306#[derive(Debug, Default)]
307struct BucketState {
308    residuals: VecDeque<f64>,
309}
310
311impl BucketState {
312    fn push(&mut self, residual: f64, window_size: usize) {
313        self.residuals.push_back(residual);
314        while self.residuals.len() > window_size {
315            self.residuals.pop_front();
316        }
317    }
318}
319
320/// Conformal predictor with bucketed calibration.
321#[derive(Debug)]
322pub struct ConformalPredictor {
323    config: ConformalConfig,
324    buckets: HashMap<BucketKey, BucketState>,
325    reset_count: u64,
326}
327
328impl ConformalPredictor {
329    /// Create a new predictor with the given config.
330    pub fn new(config: ConformalConfig) -> Result<Self, ConformalConfigError> {
331        config.validate()?;
332        Ok(Self {
333            config,
334            buckets: HashMap::new(),
335            reset_count: 0,
336        })
337    }
338
339    /// Access the configuration.
340    pub fn config(&self) -> &ConformalConfig {
341        &self.config
342    }
343
344    /// Number of samples currently stored for a bucket.
345    pub fn bucket_samples(&self, key: BucketKey) -> usize {
346        self.buckets
347            .get(&key)
348            .map(|state| state.residuals.len())
349            .unwrap_or(0)
350    }
351
352    /// Clear calibration for all buckets.
353    pub fn reset_all(&mut self) {
354        self.buckets.clear();
355        self.reset_count += 1;
356    }
357
358    /// Clear calibration for a single bucket.
359    pub fn reset_bucket(&mut self, key: BucketKey) {
360        if let Some(state) = self.buckets.get_mut(&key) {
361            state.residuals.clear();
362            self.reset_count += 1;
363        }
364    }
365
366    /// Observe a realized frame time and update calibration.
367    pub fn observe(&mut self, key: BucketKey, y_hat_us: f64, observed_us: f64) -> ConformalUpdate {
368        let residual = add_up(observed_us, -y_hat_us);
369        if !y_hat_us.is_finite()
370            || y_hat_us < 0.0
371            || !observed_us.is_finite()
372            || observed_us < 0.0
373            || !residual.is_finite()
374        {
375            return ConformalUpdate {
376                residual: None,
377                bucket: key,
378                sample_count: self.bucket_samples(key),
379            };
380        }
381
382        let window_size = self.config.window_size;
383        let state = self.buckets.entry(key).or_default();
384        state.push(residual, window_size);
385        ConformalUpdate {
386            residual: Some(residual),
387            bucket: key,
388            sample_count: state.residuals.len(),
389        }
390    }
391
392    /// Whether a finite bound with enough samples was actually obtained.
393    #[must_use]
394    pub fn is_calibrated(&self, prediction: &ConformalPrediction) -> bool {
395        prediction.status == ConformalStatus::Calibrated
396    }
397
398    pub fn predict(&self, key: BucketKey, y_hat_us: f64, budget_us: f64) -> ConformalPrediction {
399        let span = tracing::info_span!(
400            "conformal.predict",
401            calibration_set_size = tracing::field::Empty,
402            predicted_upper_bound_us = tracing::field::Empty,
403            frame_budget_us = budget_us,
404            coverage_alpha = self.config.alpha,
405            gate_triggered = tracing::field::Empty,
406            bound_status = tracing::field::Empty,
407            required_rank = tracing::field::Empty,
408        );
409        let _guard = span.enter();
410
411        let QuantileDecision {
412            quantile,
413            sample_count,
414            fallback_level,
415            required_rank,
416            heuristic_residual,
417        } = self.quantile_for(key);
418
419        let valid_input =
420            y_hat_us.is_finite() && y_hat_us >= 0.0 && budget_us.is_finite() && budget_us >= 0.0;
421        let mut status = if !valid_input {
422            ConformalStatus::InvalidInput
423        } else if sample_count < self.config.min_samples {
424            ConformalStatus::Warmup
425        } else if quantile.is_none() {
426            ConformalStatus::UnattainableRank
427        } else {
428            ConformalStatus::Calibrated
429        };
430        let mut upper_us = None;
431        let mut warmup_upper_us = None;
432        if matches!(
433            status,
434            ConformalStatus::Calibrated | ConformalStatus::Warmup
435        ) {
436            let residual = quantile.unwrap_or(heuristic_residual).max(0.0);
437            let upper = add_up(y_hat_us, residual);
438            if !upper.is_finite() {
439                status = ConformalStatus::ArithmeticOverflow;
440            } else if status == ConformalStatus::Calibrated {
441                upper_us = Some(upper);
442            } else {
443                warmup_upper_us = Some(upper);
444            }
445        }
446        let risk = upper_us
447            .or(warmup_upper_us)
448            .is_none_or(|upper| upper > budget_us);
449
450        span.record("calibration_set_size", sample_count);
451        if let Some(upper) = upper_us {
452            span.record("predicted_upper_bound_us", upper);
453        }
454        span.record("gate_triggered", risk);
455        span.record("bound_status", status.as_str());
456        span.record("required_rank", required_rank);
457
458        tracing::debug!(
459            bucket = %key,
460            y_hat_us,
461            quantile = ?quantile,
462            status = status.as_str(),
463            required_rank,
464            fallback_level,
465            sample_count,
466            "prediction interval"
467        );
468
469        ConformalPrediction {
470            upper_us,
471            risk,
472            confidence: upper_us.map(|_| 1.0 - self.config.alpha),
473            alpha: self.config.alpha,
474            status,
475            required_rank,
476            warmup_upper_us,
477            bucket: key,
478            sample_count,
479            quantile,
480            fallback_level,
481            window_size: self.config.window_size,
482            reset_count: self.reset_count,
483            y_hat: y_hat_us,
484            budget_us,
485        }
486    }
487
488    fn quantile_for(&self, key: BucketKey) -> QuantileDecision {
489        let min_samples = self.config.min_samples;
490
491        let exact = self.collect_exact(key);
492        if exact.len() >= min_samples {
493            return QuantileDecision::new(self.config.alpha, exact, 0);
494        }
495
496        let mode_diff = self.collect_mode_diff(key.mode, key.diff);
497        if mode_diff.len() >= min_samples {
498            return QuantileDecision::new(self.config.alpha, mode_diff, 1);
499        }
500
501        let mode_only = self.collect_mode(key.mode);
502        if mode_only.len() >= min_samples {
503            return QuantileDecision::new(self.config.alpha, mode_only, 2);
504        }
505
506        let global = self.collect_all();
507        if !global.is_empty() {
508            return QuantileDecision::new(self.config.alpha, global, 3);
509        }
510
511        QuantileDecision {
512            quantile: None,
513            required_rank: 1,
514            heuristic_residual: self.config.q_default,
515            sample_count: 0,
516            fallback_level: 3,
517        }
518    }
519
520    fn collect_exact(&self, key: BucketKey) -> Vec<f64> {
521        self.buckets
522            .get(&key)
523            .map(|state| state.residuals.iter().copied().collect())
524            .unwrap_or_default()
525    }
526
527    fn collect_mode_diff(&self, mode: ModeBucket, diff: DiffBucket) -> Vec<f64> {
528        let mut values = Vec::new();
529        for (key, state) in &self.buckets {
530            if key.mode == mode && key.diff == diff {
531                values.extend(state.residuals.iter().copied());
532            }
533        }
534        values
535    }
536
537    fn collect_mode(&self, mode: ModeBucket) -> Vec<f64> {
538        let mut values = Vec::new();
539        for (key, state) in &self.buckets {
540            if key.mode == mode {
541                values.extend(state.residuals.iter().copied());
542            }
543        }
544        values
545    }
546
547    fn collect_all(&self) -> Vec<f64> {
548        let mut values = Vec::new();
549        for state in self.buckets.values() {
550            values.extend(state.residuals.iter().copied());
551        }
552        values
553    }
554}
555
556#[derive(Debug)]
557struct QuantileDecision {
558    quantile: Option<f64>,
559    required_rank: usize,
560    heuristic_residual: f64,
561    sample_count: usize,
562    fallback_level: u8,
563}
564
565impl QuantileDecision {
566    fn new(alpha: f64, mut residuals: Vec<f64>, fallback_level: u8) -> Self {
567        let quantile = conformal_quantile(alpha, &mut residuals);
568        Self {
569            quantile,
570            required_rank: conformal_rank(alpha, residuals.len()),
571            heuristic_residual: residuals.last().copied().unwrap_or(0.0),
572            sample_count: residuals.len(),
573            fallback_level,
574        }
575    }
576}
577
578/// Least binary64 upper value for a sum of finite binary64 operands.
579///
580/// Magnitude-ordered FastTwoSum recovers the sign of the exact rounding error,
581/// including gradual underflow. Only downward rounding needs the next value;
582/// overflow remains nonfinite so callers report an unavailable bound.
583/// See Rump, Ogita and Oishi, Fast high precision summation, Algorithm 2.5:
584/// <https://www.tuhh.de/ti3/paper/rump/RuOgOi08.pdf>.
585fn add_up(a: f64, b: f64) -> f64 {
586    let sum = a + b;
587    if !sum.is_finite() {
588        return sum;
589    }
590    let (large, small) = if a.abs() >= b.abs() { (a, b) } else { (b, a) };
591    let error = small - (sum - large);
592    if error > 0.0 { sum.next_up() } else { sum }
593}
594
595fn conformal_quantile(alpha: f64, residuals: &mut [f64]) -> Option<f64> {
596    residuals.sort_by(f64::total_cmp);
597    let rank = conformal_rank(alpha, residuals.len());
598    residuals.get(rank - 1).copied()
599}
600
601/// Exact ceil((n+1)*(1-alpha)) for the represented, validated binary64 alpha.
602/// Subtracting alpha from one first can round a missing rank into existence.
603pub(crate) fn conformal_rank(alpha: f64, n: usize) -> usize {
604    let bits = alpha.to_bits();
605    let exponent = ((bits >> 52) & 0x7ff) as u32;
606    let fraction = bits & ((1_u64 << 52) - 1);
607    let significand = if exponent == 0 {
608        fraction
609    } else {
610        fraction | (1_u64 << 52)
611    };
612    let shift = if exponent == 0 { 1074 } else { 1075 - exponent };
613    let count = n as u128 + 1;
614    let product = count * u128::from(significand);
615    let tail_count = if shift >= 128 { 0 } else { product >> shift };
616    // A residual Vec cannot contain usize::MAX elements; rank <= n+1 fits.
617    usize::try_from(count - tail_count).expect("rank fits addressable residual storage")
618}
619
620fn size_bucket(cols: u16, rows: u16) -> u8 {
621    let area = cols as u32 * rows as u32;
622    if area == 0 {
623        return 0;
624    }
625    (31 - area.leading_zeros()) as u8
626}
627
628#[cfg(test)]
629mod tests {
630    use super::*;
631
632    fn test_key(cols: u16, rows: u16) -> BucketKey {
633        BucketKey::from_context(
634            ScreenMode::Inline { ui_height: 4 },
635            DiffStrategy::Full,
636            cols,
637            rows,
638        )
639    }
640
641    #[test]
642    fn quantile_n_plus_1_rule() {
643        let mut predictor = ConformalPredictor::new(ConformalConfig {
644            alpha: 0.2,
645            min_samples: 1,
646            window_size: 10,
647            q_default: 0.0,
648        })
649        .expect("valid config");
650
651        let key = test_key(80, 24);
652        predictor.observe(key, 0.0, 1.0);
653        predictor.observe(key, 0.0, 2.0);
654        predictor.observe(key, 0.0, 3.0);
655
656        let decision = predictor.predict(key, 0.0, 1_000.0);
657        assert_eq!(decision.quantile, None);
658        assert_eq!(decision.required_rank, 4);
659        assert_eq!(decision.status, ConformalStatus::UnattainableRank);
660        predictor.observe(key, 0.0, 4.0);
661        assert_eq!(predictor.predict(key, 0.0, 1_000.0).quantile, Some(4.0));
662    }
663
664    #[test]
665    fn unavailable_99_percent_rank_is_not_calibrated_at_twenty_samples() {
666        let mut predictor = ConformalPredictor::new(ConformalConfig {
667            alpha: 0.01,
668            min_samples: 20,
669            window_size: 256,
670            q_default: 10_000.0,
671        })
672        .expect("valid config");
673        let key = test_key(80, 24);
674        for observed_us in 1..=20 {
675            predictor.observe(key, 0.0, f64::from(observed_us));
676        }
677        let prediction = predictor.predict(key, 0.0, 100.0);
678        assert_eq!(prediction.sample_count, 20);
679        assert_eq!(prediction.status, ConformalStatus::UnattainableRank);
680        assert_eq!(prediction.required_rank, 21);
681        assert_eq!(prediction.upper_us, None);
682        assert_eq!(prediction.quantile, None);
683        assert_eq!(prediction.confidence, None);
684        assert!(prediction.risk);
685        assert!(
686            !predictor.is_calibrated(&prediction),
687            "99% requires the unavailable 21st order statistic; the observed maximum only supports 20/21 marginal coverage"
688        );
689    }
690
691    #[test]
692    fn ranks_match_exhaustive_held_out_position_oracle() {
693        // Independent finite-population oracle: hold out each of n+1 distinct
694        // observations, count coverage for every candidate calibration order
695        // statistic, and select the least rank attaining the requested count.
696        // Dyadic alpha makes the oracle's integer inequality exact.
697        for n in 0..=24 {
698            for alpha_numerator in [1, 2, 31, 128, 256, 512, 768, 1023] {
699                let alpha = f64::from(alpha_numerator) / 1024.0;
700                let oracle = (1..=n).find(|&candidate| {
701                    let covered = (0..=n)
702                        .filter(|&held_out| {
703                            let training: Vec<_> =
704                                (0..=n).filter(|&point| point != held_out).collect();
705                            held_out <= training[candidate - 1]
706                        })
707                        .count();
708                    covered * 1024 >= (n + 1) * (1024 - alpha_numerator as usize)
709                });
710                let mut residuals: Vec<_> = (0..n).rev().map(|i| i as f64).collect();
711                assert_eq!(
712                    conformal_quantile(alpha, &mut residuals),
713                    oracle.map(|rank| (rank - 1) as f64),
714                    "n={n}, alpha={alpha}"
715                );
716                assert_eq!(conformal_rank(alpha, n), oracle.unwrap_or(n + 1));
717            }
718        }
719    }
720
721    #[test]
722    fn attainable_boundaries_respect_adjacent_binary64_values() {
723        for power in 1..=10 {
724            let count = 1_usize << power;
725            let alpha = 1.0 / count as f64;
726            assert_eq!(conformal_rank(alpha.next_down(), count - 1), count);
727            assert_eq!(conformal_rank(alpha, count - 1), count - 1);
728            assert_eq!(conformal_rank(alpha.next_up(), count - 1), count - 1);
729        }
730        assert_eq!(conformal_rank(f64::from_bits(1), 20), 21);
731        assert_eq!(conformal_rank(1.0_f64.next_down(), 20), 1);
732        // Binary64's 1/3 is below the exact rational threshold for n=2.
733        assert_eq!(conformal_rank(1.0 / 3.0, 2), 3);
734        assert_eq!(conformal_rank((1.0_f64 / 3.0).next_up(), 2), 2);
735    }
736
737    #[test]
738    fn invalid_configuration_is_rejected_without_clamping() {
739        for alpha in [
740            f64::NAN,
741            f64::INFINITY,
742            f64::NEG_INFINITY,
743            -1.0,
744            0.0,
745            1.0,
746            2.0,
747        ] {
748            assert!(
749                ConformalPredictor::new(ConformalConfig {
750                    alpha,
751                    ..Default::default()
752                })
753                .is_err()
754            );
755        }
756        for (min_samples, window_size) in [(0, 20), (20, 0), (21, 20)] {
757            assert!(
758                ConformalPredictor::new(ConformalConfig {
759                    min_samples,
760                    window_size,
761                    ..Default::default()
762                })
763                .is_err()
764            );
765        }
766        for q_default in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, -1.0] {
767            assert!(
768                ConformalPredictor::new(ConformalConfig {
769                    q_default,
770                    ..Default::default()
771                })
772                .is_err()
773            );
774        }
775    }
776
777    #[test]
778    fn invalid_inputs_and_overflow_have_valid_nullable_evidence() {
779        let key = test_key(80, 24);
780        let mut predictor = ConformalPredictor::new(ConformalConfig {
781            alpha: 0.5,
782            min_samples: 1,
783            window_size: 2,
784            q_default: 0.0,
785        })
786        .expect("valid config");
787        for invalid in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, -1.0] {
788            for (baseline, observed) in [(invalid, 1.0), (1.0, invalid)] {
789                assert_eq!(predictor.observe(key, baseline, observed).residual, None);
790                assert_eq!(predictor.bucket_samples(key), 0);
791            }
792            for (baseline, budget) in [(invalid, 1.0), (1.0, invalid)] {
793                let prediction = predictor.predict(key, baseline, budget);
794                assert_eq!(prediction.status, ConformalStatus::InvalidInput);
795                assert!(prediction.risk);
796                let row: serde_json::Value = serde_json::from_str(&prediction.to_jsonl())
797                    .expect("valid JSON even for invalid input");
798                assert!(row["upper_us"].is_null());
799                assert!(row["confidence"].is_null());
800            }
801        }
802        predictor.observe(key, 0.0, f64::MAX);
803        let overflow = predictor.predict(key, f64::MAX, f64::MAX);
804        assert_eq!(overflow.status, ConformalStatus::ArithmeticOverflow);
805        assert_eq!(overflow.upper_us, None);
806        assert_eq!(overflow.confidence, None);
807        assert!(overflow.risk);
808        serde_json::from_str::<serde_json::Value>(&overflow.to_jsonl()).expect("finite JSON");
809    }
810
811    #[test]
812    fn evidence_preserves_tiny_alpha_and_finite_extreme_timings() {
813        let predictor = ConformalPredictor::new(ConformalConfig {
814            alpha: f64::from_bits(1),
815            ..Default::default()
816        })
817        .expect("valid subnormal alpha");
818        let prediction = predictor.predict(test_key(80, 24), f64::MAX, f64::MAX);
819        let row: serde_json::Value =
820            serde_json::from_str(&prediction.to_jsonl()).expect("valid extreme JSON");
821        assert_eq!(row["alpha"].as_f64(), Some(f64::from_bits(1)));
822        assert_eq!(row["y_hat"].as_f64(), Some(f64::MAX));
823    }
824
825    #[test]
826    fn tied_observations_remain_below_the_calibrated_bound_after_rounding() {
827        for (baseline, observed) in [
828            (1.005, 10.001),
829            (1.0, 10_000_000_000_000_002.0),
830            (0.0, f64::from_bits(1)),
831            (10.0, 3.0),
832            (f64::MAX, f64::MAX),
833        ] {
834            let mut predictor = ConformalPredictor::new(ConformalConfig {
835                alpha: 0.5,
836                min_samples: 1,
837                window_size: 1,
838                ..Default::default()
839            })
840            .expect("valid config");
841            let key = test_key(80, 24);
842            predictor.observe(key, baseline, observed);
843            let prediction = predictor.predict(key, baseline, f64::MAX);
844            assert_eq!(prediction.status, ConformalStatus::Calibrated);
845            assert!(
846                prediction.upper_us.unwrap() >= observed,
847                "a tied future observation must remain covered: baseline={baseline:?}, observed={observed:?}, prediction={prediction:?}"
848            );
849            let json: serde_json::Value =
850                serde_json::from_str(&prediction.to_jsonl()).expect("actual predictor JSON");
851            assert!(
852                json["upper_us"].as_f64().expect("finite upper") >= observed,
853                "default JSON reader must retain coverage for this regression: {json}"
854            );
855        }
856    }
857
858    #[test]
859    fn seeded_binary64_ties_remain_covered_or_explicitly_unbounded() {
860        let mut seed = 0x5146_7557_554f_4159_u64;
861        let mut next = || {
862            seed ^= seed << 13;
863            seed ^= seed >> 7;
864            seed ^= seed << 17;
865            f64::from_bits(seed & 0x7fff_ffff_ffff_ffff)
866        };
867        let mut checked = 0;
868        for _ in 0..4_000 {
869            let baseline = next();
870            let observed = next();
871            if !baseline.is_finite() || !observed.is_finite() {
872                continue;
873            }
874            let mut predictor = ConformalPredictor::new(ConformalConfig {
875                alpha: 0.5,
876                min_samples: 1,
877                window_size: 1,
878                ..Default::default()
879            })
880            .expect("valid config");
881            let key = test_key(80, 24);
882            assert!(
883                predictor
884                    .observe(key, baseline, observed)
885                    .residual
886                    .is_some()
887            );
888            let prediction = predictor.predict(key, baseline, f64::MAX);
889            if let Some(upper) = prediction.upper_us {
890                assert!(
891                    upper >= observed,
892                    "{baseline:?}, {observed:?}: {prediction:?}"
893                );
894            } else {
895                assert_eq!(prediction.status, ConformalStatus::ArithmeticOverflow);
896                assert!(prediction.risk);
897                assert!(prediction.confidence.is_none());
898            }
899            checked += 1;
900        }
901        assert!(checked > 3_900, "finite input denominator: {checked}");
902    }
903
904    #[test]
905    fn directed_addition_preserves_exact_values_and_rounds_ties_outward() {
906        let half_ulp = 2.0_f64.powi(-53);
907        let tiny = f64::from_bits(1);
908        for (a, b, expected) in [
909            (1.0, half_ulp, 1.0_f64.next_up()),
910            (1.0_f64.next_up(), half_ulp, 1.0 + 2.0_f64.powi(-51)),
911            (-1.0, -half_ulp, -1.0),
912            ((-1.0_f64).next_down(), -half_ulp, (-1.0_f64).next_down()),
913            (f64::MAX, 0.0, f64::MAX),
914            (f64::MAX, -1.0, f64::MAX),
915            (f64::MAX, 1.0, f64::INFINITY),
916            (f64::MAX, -f64::MAX, 0.0),
917            (tiny, 2.0 * tiny, 3.0 * tiny),
918            (f64::MIN_POSITIVE, -tiny, f64::MIN_POSITIVE.next_down()),
919            (1.0, -1.0, 0.0),
920        ] {
921            assert_eq!(add_up(a, b), expected, "{a:?} + {b:?}");
922            assert_eq!(add_up(b, a), expected, "{b:?} + {a:?}");
923        }
924    }
925
926    #[test]
927    fn finite_json_numbers_preserve_fractional_bounds() {
928        for value in [10.001, 10.001_f64.next_up(), 0.995, 1.005] {
929            let json = finite_json_number(Some(value), 1);
930            // Standard binary64 parsing independently checks formatter fidelity;
931            // decoder-specific rounding behavior is a separate concern.
932            assert_eq!(json.parse::<f64>().expect("number"), value, "{json}");
933        }
934    }
935
936    #[test]
937    fn seeded_independent_trials_cover_exchangeable_data_but_not_drift() {
938        // Fresh calibration data AND a fresh held-out point on every trial.
939        // This is a reproducible synthetic experiment, not live timing proof.
940        let mut seed = 0x6a09_e667_f3bc_c909_u64;
941        let mut uniform = || {
942            seed ^= seed << 13;
943            seed ^= seed >> 7;
944            seed ^= seed << 17;
945            (seed >> 11) as f64 / (1_u64 << 53) as f64
946        };
947        let key = test_key(80, 24);
948        let trials = 4000;
949        let mut covered = 0;
950        let mut drift_covered = 0;
951        for _ in 0..trials {
952            let mut predictor = ConformalPredictor::new(ConformalConfig {
953                alpha: 0.125,
954                min_samples: 15,
955                window_size: 31,
956                q_default: 0.0,
957            })
958            .expect("valid config");
959            for _ in 0..31 {
960                predictor.observe(key, 0.0, uniform());
961            }
962            let prediction = predictor.predict(key, 0.0, 2.0);
963            let upper = prediction.upper_us.expect("rank28 is available");
964            let held_out = uniform();
965            covered += usize::from(held_out <= upper);
966            drift_covered += usize::from(held_out + 1.0 <= upper);
967        }
968        let target = 28.0 / 32.0;
969        let mean = covered as f64 / trials as f64;
970        let six_sigma = 6.0 * (target * (1.0 - target) / trials as f64).sqrt();
971        eprintln!(
972            "independent synthetic conformal trials: seed=0x6a09e667f3bcc909 n=31 alpha=0.125 rank=28 trials={trials} covered={covered} coverage={mean} six_sigma={six_sigma} drift_covered={drift_covered}"
973        );
974        assert!(
975            (mean - target).abs() <= six_sigma,
976            "coverage={mean}, expected={target}, six_sigma={six_sigma}, seed=0x6a09e667f3bcc909"
977        );
978        assert_eq!(
979            drift_covered, 0,
980            "a disjoint shifted population violates exchangeability"
981        );
982    }
983
984    #[test]
985    fn fallback_hierarchy_mode_diff() {
986        let mut predictor = ConformalPredictor::new(ConformalConfig {
987            alpha: 0.1,
988            min_samples: 4,
989            window_size: 16,
990            q_default: 0.0,
991        })
992        .expect("valid config");
993
994        let key_a = test_key(80, 24);
995        for value in [1.0, 2.0, 3.0, 4.0] {
996            predictor.observe(key_a, 0.0, value);
997        }
998
999        let key_b = test_key(120, 40);
1000        let decision = predictor.predict(key_b, 0.0, 1_000.0);
1001        assert_eq!(decision.fallback_level, 1);
1002        assert_eq!(decision.sample_count, 4);
1003    }
1004
1005    #[test]
1006    fn fallback_hierarchy_mode_only() {
1007        let mut predictor = ConformalPredictor::new(ConformalConfig {
1008            alpha: 0.1,
1009            min_samples: 3,
1010            window_size: 16,
1011            q_default: 0.0,
1012        })
1013        .expect("valid config");
1014
1015        let key_dirty = BucketKey::from_context(
1016            ScreenMode::Inline { ui_height: 4 },
1017            DiffStrategy::DirtyRows,
1018            80,
1019            24,
1020        );
1021        for value in [10.0, 20.0, 30.0] {
1022            predictor.observe(key_dirty, 0.0, value);
1023        }
1024
1025        let key_full = BucketKey::from_context(
1026            ScreenMode::Inline { ui_height: 4 },
1027            DiffStrategy::Full,
1028            120,
1029            40,
1030        );
1031        let decision = predictor.predict(key_full, 0.0, 1_000.0);
1032        assert_eq!(decision.fallback_level, 2);
1033        assert_eq!(decision.sample_count, 3);
1034    }
1035
1036    #[test]
1037    fn window_enforced() {
1038        let mut predictor = ConformalPredictor::new(ConformalConfig {
1039            alpha: 0.1,
1040            min_samples: 1,
1041            window_size: 3,
1042            q_default: 0.0,
1043        })
1044        .expect("valid config");
1045        let key = test_key(80, 24);
1046        for value in [1.0, 2.0, 3.0, 4.0, 5.0] {
1047            predictor.observe(key, 0.0, value);
1048        }
1049        assert_eq!(predictor.bucket_samples(key), 3);
1050    }
1051
1052    #[test]
1053    fn predict_uses_default_when_empty() {
1054        let predictor = ConformalPredictor::new(ConformalConfig {
1055            alpha: 0.1,
1056            min_samples: 2,
1057            window_size: 4,
1058            q_default: 42.0,
1059        })
1060        .expect("valid config");
1061        let key = test_key(120, 40);
1062        let prediction = predictor.predict(key, 5.0, 10_000.0);
1063        assert_eq!(prediction.quantile, None);
1064        assert_eq!(prediction.upper_us, None);
1065        assert_eq!(prediction.warmup_upper_us, Some(47.0));
1066        assert_eq!(prediction.sample_count, 0);
1067        assert_eq!(prediction.fallback_level, 3);
1068    }
1069
1070    #[test]
1071    fn bucket_isolation_by_size() {
1072        let mut predictor = ConformalPredictor::new(ConformalConfig {
1073            alpha: 0.2,
1074            min_samples: 2,
1075            window_size: 10,
1076            q_default: 0.0,
1077        })
1078        .expect("valid config");
1079
1080        let small = test_key(40, 10);
1081        predictor.observe(small, 0.0, 1.0);
1082        predictor.observe(small, 0.0, 2.0);
1083
1084        let large = test_key(200, 60);
1085        predictor.observe(large, 0.0, 10.0);
1086        predictor.observe(large, 0.0, 12.0);
1087
1088        let prediction = predictor.predict(large, 0.0, 1_000.0);
1089        assert_eq!(prediction.fallback_level, 0);
1090        assert_eq!(prediction.sample_count, 2);
1091        assert_eq!(prediction.quantile, None);
1092        assert_eq!(prediction.required_rank, 3);
1093        for value in [11.0, 9.0] {
1094            predictor.observe(large, 0.0, value);
1095        }
1096        assert_eq!(predictor.predict(large, 0.0, 1_000.0).quantile, Some(12.0));
1097    }
1098
1099    #[test]
1100    fn reset_clears_bucket_and_raises_reset_count() {
1101        let mut predictor = ConformalPredictor::new(ConformalConfig {
1102            alpha: 0.1,
1103            min_samples: 1,
1104            window_size: 8,
1105            q_default: 7.0,
1106        })
1107        .expect("valid config");
1108        let key = test_key(80, 24);
1109        predictor.observe(key, 0.0, 3.0);
1110        assert_eq!(predictor.bucket_samples(key), 1);
1111
1112        predictor.reset_bucket(key);
1113        assert_eq!(predictor.bucket_samples(key), 0);
1114
1115        let prediction = predictor.predict(key, 0.0, 1_000.0);
1116        assert_eq!(prediction.quantile, None);
1117        assert_eq!(prediction.warmup_upper_us, Some(7.0));
1118        assert_eq!(prediction.reset_count, 1);
1119    }
1120
1121    #[test]
1122    fn reset_all_forces_conservative_fallback() {
1123        let mut predictor = ConformalPredictor::new(ConformalConfig {
1124            alpha: 0.1,
1125            min_samples: 1,
1126            window_size: 8,
1127            q_default: 9.0,
1128        })
1129        .expect("valid config");
1130        let key = test_key(80, 24);
1131        predictor.observe(key, 0.0, 2.0);
1132
1133        predictor.reset_all();
1134        let prediction = predictor.predict(key, 0.0, 1_000.0);
1135        assert_eq!(prediction.quantile, None);
1136        assert_eq!(prediction.warmup_upper_us, Some(9.0));
1137        assert_eq!(prediction.sample_count, 0);
1138        assert_eq!(prediction.fallback_level, 3);
1139        assert_eq!(prediction.reset_count, 1);
1140    }
1141
1142    #[test]
1143    fn size_bucket_log2_area() {
1144        let a = size_bucket(8, 8); // area 64 -> log2 = 6
1145        let b = size_bucket(8, 16); // area 128 -> log2 = 7
1146        assert_eq!(a, 6);
1147        assert_eq!(b, 7);
1148    }
1149
1150    // --- size_bucket edge cases ---
1151
1152    #[test]
1153    fn size_bucket_zero_area() {
1154        assert_eq!(size_bucket(0, 0), 0);
1155        assert_eq!(size_bucket(0, 24), 0);
1156        assert_eq!(size_bucket(80, 0), 0);
1157    }
1158
1159    #[test]
1160    fn size_bucket_one_by_one() {
1161        assert_eq!(size_bucket(1, 1), 0); // area 1, log2(1) = 0
1162    }
1163
1164    #[test]
1165    fn size_bucket_typical_terminals() {
1166        let b80 = size_bucket(80, 24); // 1920 -> log2 ~ 10
1167        let b120 = size_bucket(120, 40); // 4800 -> log2 ~ 12
1168        assert_eq!(b80, 10);
1169        assert_eq!(b120, 12);
1170    }
1171
1172    // --- conformal_quantile edge cases ---
1173
1174    #[test]
1175    fn conformal_quantile_empty() {
1176        let mut data: Vec<f64> = vec![];
1177        assert_eq!(conformal_quantile(0.1, &mut data), None);
1178    }
1179
1180    #[test]
1181    fn conformal_quantile_single_element() {
1182        let mut data = vec![42.0];
1183        assert_eq!(conformal_quantile(0.1, &mut data), None);
1184        assert_eq!(conformal_quantile(0.5, &mut data), Some(42.0));
1185    }
1186
1187    #[test]
1188    fn conformal_quantile_sorted_data() {
1189        let mut data = vec![1.0, 2.0, 3.0, 4.0, 5.0];
1190        let q = conformal_quantile(0.5, &mut data);
1191        // (5+1)*0.5 = 3.0 -> ceil = 3 -> idx = 2 -> data[2] = 3.0
1192        assert_eq!(q, Some(3.0));
1193    }
1194
1195    #[test]
1196    fn conformal_quantile_alpha_half() {
1197        let mut data = vec![10.0, 20.0, 30.0, 40.0];
1198        let q = conformal_quantile(0.5, &mut data);
1199        // (4+1)*0.5 = 2.5 -> ceil = 3 -> idx = 2 -> data[2] = 30.0
1200        assert_eq!(q, Some(30.0));
1201    }
1202
1203    // --- ModeBucket / DiffBucket ---
1204
1205    #[test]
1206    fn mode_bucket_as_str_all_variants() {
1207        assert_eq!(ModeBucket::Inline.as_str(), "inline");
1208        assert_eq!(ModeBucket::InlineAuto.as_str(), "inline_auto");
1209        assert_eq!(ModeBucket::AltScreen.as_str(), "altscreen");
1210    }
1211
1212    #[test]
1213    fn diff_bucket_as_str_all_variants() {
1214        assert_eq!(DiffBucket::Full.as_str(), "full");
1215        assert_eq!(DiffBucket::DirtyRows.as_str(), "dirty");
1216        assert_eq!(DiffBucket::FullRedraw.as_str(), "redraw");
1217    }
1218
1219    #[test]
1220    fn diff_bucket_from_strategy() {
1221        assert_eq!(DiffBucket::from(DiffStrategy::Full), DiffBucket::Full);
1222        assert_eq!(
1223            DiffBucket::from(DiffStrategy::DirtyRows),
1224            DiffBucket::DirtyRows
1225        );
1226        assert_eq!(
1227            DiffBucket::from(DiffStrategy::FullRedraw),
1228            DiffBucket::FullRedraw
1229        );
1230    }
1231
1232    // --- BucketKey Display ---
1233
1234    #[test]
1235    fn bucket_key_display_format() {
1236        let key = BucketKey {
1237            mode: ModeBucket::AltScreen,
1238            diff: DiffBucket::DirtyRows,
1239            size_bucket: 12,
1240        };
1241        assert_eq!(format!("{key}"), "altscreen:dirty:12");
1242    }
1243
1244    // --- observe edge cases ---
1245
1246    #[test]
1247    fn observe_nan_residual_not_stored() {
1248        let mut predictor = ConformalPredictor::new(ConformalConfig {
1249            alpha: 0.1,
1250            min_samples: 1,
1251            window_size: 8,
1252            q_default: 5.0,
1253        })
1254        .expect("valid config");
1255        let key = test_key(80, 24);
1256        let update = predictor.observe(key, 0.0, f64::NAN);
1257        assert_eq!(update.residual, None);
1258        assert_eq!(predictor.bucket_samples(key), 0);
1259    }
1260
1261    #[test]
1262    fn observe_infinity_residual_not_stored() {
1263        let mut predictor = ConformalPredictor::new(ConformalConfig {
1264            alpha: 0.1,
1265            min_samples: 1,
1266            window_size: 8,
1267            q_default: 5.0,
1268        })
1269        .expect("valid config");
1270        let key = test_key(80, 24);
1271        predictor.observe(key, 0.0, f64::INFINITY);
1272        assert_eq!(predictor.bucket_samples(key), 0);
1273    }
1274
1275    // --- prediction fields ---
1276
1277    /// The runtime gates only on calibrated predictions: the `q_default`
1278    /// prior and pooled fallbacks below `min_samples` still report `risk`
1279    /// (for evidence) but must not count as a coverage guarantee.
1280    #[test]
1281    fn is_calibrated_requires_min_samples_on_the_level_used() {
1282        let mut predictor = ConformalPredictor::new(ConformalConfig {
1283            alpha: 0.25,
1284            min_samples: 3,
1285            window_size: 8,
1286            q_default: 50_000.0,
1287        })
1288        .expect("valid config");
1289        let key = test_key(80, 24);
1290        let cold = predictor.predict(key, 16_000.0, 16_000.0);
1291        assert!(cold.risk, "q_default prior exceeds the budget");
1292        assert_eq!(cold.sample_count, 0);
1293        assert!(
1294            !predictor.is_calibrated(&cold),
1295            "no samples: not calibrated"
1296        );
1297
1298        predictor.observe(key, 0.0, 10.0);
1299        predictor.observe(key, 0.0, 12.0);
1300        let two = predictor.predict(key, 0.0, 1.0);
1301        assert_eq!(two.sample_count, 2);
1302        assert!(
1303            !predictor.is_calibrated(&two),
1304            "below min_samples: not calibrated"
1305        );
1306
1307        predictor.observe(key, 0.0, 11.0);
1308        let three = predictor.predict(key, 0.0, 1.0);
1309        assert_eq!(three.sample_count, 3);
1310        assert_eq!(three.fallback_level, 0);
1311        assert!(predictor.is_calibrated(&three));
1312        assert!(three.risk);
1313
1314        // Pooled fallback counts too: a different size bucket in the same
1315        // mode/diff class borrows the three residuals above.
1316        let other = predictor.predict(test_key(200, 60), 0.0, 1.0);
1317        assert!(other.fallback_level >= 1);
1318        assert!(predictor.is_calibrated(&other));
1319    }
1320
1321    #[test]
1322    fn prediction_risk_flag() {
1323        let predictor = ConformalPredictor::new(ConformalConfig {
1324            alpha: 0.1,
1325            min_samples: 1,
1326            window_size: 8,
1327            q_default: 50.0,
1328        })
1329        .expect("valid config");
1330        let key = test_key(80, 24);
1331        // No data -> q_default = 50.0, y_hat = 0 -> upper = 50
1332        let p = predictor.predict(key, 0.0, 100.0);
1333        assert!(!p.risk); // 50 <= 100
1334        let p2 = predictor.predict(key, 0.0, 30.0);
1335        assert!(p2.risk); // 50 > 30
1336    }
1337
1338    #[test]
1339    fn prediction_confidence() {
1340        let mut predictor = ConformalPredictor::new(ConformalConfig {
1341            alpha: 0.05,
1342            min_samples: 1,
1343            window_size: 32,
1344            q_default: 0.0,
1345        })
1346        .expect("valid config");
1347        let key = test_key(80, 24);
1348        let p = predictor.predict(key, 0.0, 100.0);
1349        assert_eq!(p.confidence, None);
1350        for _ in 0..20 {
1351            predictor.observe(key, 0.0, 1.0);
1352        }
1353        assert_eq!(predictor.predict(key, 0.0, 100.0).confidence, Some(0.95));
1354    }
1355
1356    // --- global fallback with data ---
1357
1358    #[test]
1359    fn global_fallback_with_data() {
1360        let mut predictor = ConformalPredictor::new(ConformalConfig {
1361            alpha: 0.1,
1362            min_samples: 100, // impossibly high -> always fall through
1363            window_size: 256,
1364            q_default: 999.0,
1365        })
1366        .expect("valid config");
1367        // Use altscreen mode bucket, then query inline
1368        let alt_key = BucketKey::from_context(ScreenMode::AltScreen, DiffStrategy::Full, 80, 24);
1369        predictor.observe(alt_key, 0.0, 5.0);
1370
1371        let inline_key = test_key(80, 24);
1372        let p = predictor.predict(inline_key, 0.0, 1000.0);
1373        // Falls all the way to global (level 3), has 1 sample
1374        assert_eq!(p.fallback_level, 3);
1375        assert_eq!(p.sample_count, 1);
1376        assert_eq!(p.quantile, None);
1377        assert_eq!(p.warmup_upper_us, Some(5.0));
1378    }
1379
1380    // --- ModeBucket from_screen_mode ---
1381
1382    #[test]
1383    fn mode_bucket_from_screen_modes() {
1384        assert_eq!(
1385            ModeBucket::from_screen_mode(ScreenMode::Inline { ui_height: 4 }),
1386            ModeBucket::Inline
1387        );
1388        assert_eq!(
1389            ModeBucket::from_screen_mode(ScreenMode::InlineAuto {
1390                min_height: 4,
1391                max_height: 24
1392            }),
1393            ModeBucket::InlineAuto
1394        );
1395        assert_eq!(
1396            ModeBucket::from_screen_mode(ScreenMode::AltScreen),
1397            ModeBucket::AltScreen
1398        );
1399    }
1400
1401    // --- Config defaults ---
1402
1403    #[test]
1404    fn config_defaults() {
1405        let config = ConformalConfig::default();
1406        assert!((config.alpha - 0.05).abs() < 1e-10);
1407        assert_eq!(config.min_samples, 20);
1408        assert_eq!(config.window_size, 256);
1409        assert!((config.q_default - 10_000.0).abs() < 1e-10);
1410    }
1411
1412    #[test]
1413    fn predictor_config_accessor() {
1414        let config = ConformalConfig {
1415            alpha: 0.2,
1416            min_samples: 5,
1417            window_size: 32,
1418            q_default: 100.0,
1419        };
1420        let predictor = ConformalPredictor::new(config).expect("valid config");
1421        assert!((predictor.config().alpha - 0.2).abs() < 1e-10);
1422        assert_eq!(predictor.config().min_samples, 5);
1423    }
1424
1425    // --- negative residuals ---
1426
1427    #[test]
1428    fn negative_residual_clamped_in_prediction() {
1429        let mut predictor = ConformalPredictor::new(ConformalConfig {
1430            alpha: 0.5,
1431            min_samples: 1,
1432            window_size: 8,
1433            q_default: 0.0,
1434        })
1435        .expect("valid config");
1436        let key = test_key(80, 24);
1437        // observed < y_hat -> negative residual
1438        predictor.observe(key, 10.0, 5.0);
1439        let p = predictor.predict(key, 10.0, 100.0);
1440        // quantile is -5.0, but clamped to 0.0 via .max(0.0)
1441        // so upper_us = 10.0 + 0.0 = 10.0
1442        assert_eq!(p.quantile, Some(-5.0));
1443        assert_eq!(p.upper_us, Some(10.0));
1444    }
1445
1446    // --- ConformalUpdate fields ---
1447
1448    #[test]
1449    fn observe_returns_correct_update() {
1450        let mut predictor = ConformalPredictor::new(ConformalConfig {
1451            alpha: 0.1,
1452            min_samples: 1,
1453            window_size: 8,
1454            q_default: 0.0,
1455        })
1456        .expect("valid config");
1457        let key = test_key(80, 24);
1458        let update = predictor.observe(key, 3.0, 10.0);
1459        assert_eq!(update.residual, Some(7.0));
1460        assert_eq!(update.bucket, key);
1461        assert_eq!(update.sample_count, 1);
1462    }
1463
1464    // --- prediction y_hat and budget fields ---
1465
1466    #[test]
1467    fn prediction_preserves_yhat_and_budget() {
1468        let predictor = ConformalPredictor::new(ConformalConfig::default()).expect("valid config");
1469        let key = test_key(80, 24);
1470        let p = predictor.predict(key, 42.5, 16666.0);
1471        assert!((p.y_hat - 42.5).abs() < 1e-10);
1472        assert!((p.budget_us - 16666.0).abs() < 1e-10);
1473    }
1474
1475    // --- tracing span verification ---
1476
1477    #[test]
1478    fn predict_emits_conformal_predict_span() {
1479        use std::sync::Arc;
1480        use std::sync::atomic::{AtomicBool, Ordering};
1481
1482        struct SpanChecker {
1483            saw_conformal_predict: Arc<AtomicBool>,
1484        }
1485
1486        impl tracing::Subscriber for SpanChecker {
1487            fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
1488                true
1489            }
1490            fn new_span(&self, span: &tracing::span::Attributes<'_>) -> tracing::span::Id {
1491                if span.metadata().name() == "conformal.predict" {
1492                    self.saw_conformal_predict.store(true, Ordering::Relaxed);
1493                }
1494                tracing::span::Id::from_u64(1)
1495            }
1496            fn record(&self, _span: &tracing::span::Id, _values: &tracing::span::Record<'_>) {}
1497            fn record_follows_from(&self, _span: &tracing::span::Id, _follows: &tracing::span::Id) {
1498            }
1499            fn event(&self, _event: &tracing::Event<'_>) {}
1500            fn enter(&self, _span: &tracing::span::Id) {}
1501            fn exit(&self, _span: &tracing::span::Id) {}
1502        }
1503
1504        let saw_it = Arc::new(AtomicBool::new(false));
1505        let subscriber = SpanChecker {
1506            saw_conformal_predict: Arc::clone(&saw_it),
1507        };
1508        let _guard = tracing::subscriber::set_default(subscriber);
1509
1510        let predictor = ConformalPredictor::new(ConformalConfig::default()).expect("valid config");
1511        let key = test_key(80, 24);
1512        let _ = predictor.predict(key, 100.0, 16666.0);
1513
1514        assert!(
1515            saw_it.load(Ordering::Relaxed),
1516            "predict() must emit a 'conformal.predict' tracing span"
1517        );
1518    }
1519
1520    #[test]
1521    fn predict_span_records_gate_triggered_true() {
1522        use std::sync::Arc;
1523        use std::sync::atomic::{AtomicBool, Ordering};
1524
1525        struct GateChecker {
1526            saw_gate_true: Arc<AtomicBool>,
1527        }
1528
1529        struct GateVisitor(Arc<AtomicBool>);
1530
1531        impl tracing::field::Visit for GateVisitor {
1532            fn record_bool(&mut self, field: &tracing::field::Field, value: bool) {
1533                if field.name() == "gate_triggered" && value {
1534                    self.0.store(true, Ordering::Relaxed);
1535                }
1536            }
1537            fn record_debug(&mut self, _field: &tracing::field::Field, _value: &dyn fmt::Debug) {}
1538        }
1539
1540        impl tracing::Subscriber for GateChecker {
1541            fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
1542                true
1543            }
1544            fn new_span(&self, _span: &tracing::span::Attributes<'_>) -> tracing::span::Id {
1545                tracing::span::Id::from_u64(1)
1546            }
1547            fn record(&self, _span: &tracing::span::Id, values: &tracing::span::Record<'_>) {
1548                let mut visitor = GateVisitor(Arc::clone(&self.saw_gate_true));
1549                values.record(&mut visitor);
1550            }
1551            fn record_follows_from(&self, _span: &tracing::span::Id, _follows: &tracing::span::Id) {
1552            }
1553            fn event(&self, _event: &tracing::Event<'_>) {}
1554            fn enter(&self, _span: &tracing::span::Id) {}
1555            fn exit(&self, _span: &tracing::span::Id) {}
1556        }
1557
1558        let saw_gate = Arc::new(AtomicBool::new(false));
1559        let subscriber = GateChecker {
1560            saw_gate_true: Arc::clone(&saw_gate),
1561        };
1562        let _guard = tracing::subscriber::set_default(subscriber);
1563
1564        let predictor = ConformalPredictor::new(ConformalConfig {
1565            alpha: 0.1,
1566            min_samples: 1,
1567            window_size: 8,
1568            q_default: 50_000.0, // large default to guarantee risk
1569        })
1570        .expect("valid config");
1571        let key = test_key(80, 24);
1572        // budget_us = 100 << q_default = 50_000 -> risk = true
1573        let p = predictor.predict(key, 0.0, 100.0);
1574        assert!(p.risk, "prediction should be risky");
1575        assert!(
1576            saw_gate.load(Ordering::Relaxed),
1577            "predict() must record gate_triggered=true when risk"
1578        );
1579    }
1580
1581    // ========================================================================
1582    // bd-1q5.12: Additional unit tests for conformal prediction frame-time gating
1583    // ========================================================================
1584
1585    // --- Calibration with known distributions ---
1586
1587    #[test]
1588    fn calibration_uniform_distribution_quantile() {
1589        // Uniform residuals from 0 to 99. The (1-alpha) quantile should be near
1590        // the top of the distribution.
1591        let mut predictor = ConformalPredictor::new(ConformalConfig {
1592            alpha: 0.05,
1593            min_samples: 1,
1594            window_size: 256,
1595            q_default: 0.0,
1596        })
1597        .expect("valid config");
1598        let key = test_key(80, 24);
1599        for i in 0..100 {
1600            predictor.observe(key, 0.0, i as f64);
1601        }
1602        let p = predictor.predict(key, 0.0, 1_000.0);
1603        // (100+1)*0.95 = 95.95, ceil = 96, idx = 95 -> sorted[95] = 95.0
1604        assert_eq!(p.fallback_level, 0);
1605        assert_eq!(p.sample_count, 100);
1606        assert_eq!(p.quantile, Some(95.0));
1607    }
1608
1609    #[test]
1610    fn calibration_gaussian_like_distribution() {
1611        // Simulate a roughly gaussian-shaped distribution of residuals.
1612        // Use a simple deterministic approximation: residuals centered around 0
1613        // with known spread.
1614        let mut predictor = ConformalPredictor::new(ConformalConfig {
1615            alpha: 0.1,
1616            min_samples: 1,
1617            window_size: 256,
1618            q_default: 0.0,
1619        })
1620        .expect("valid config");
1621        let key = test_key(120, 40);
1622
1623        // Generate 50 residuals that approximate a symmetric distribution
1624        // around 0: [-24.5, -23.5, ..., -0.5, 0.5, ..., 24.5]
1625        for i in 0..50 {
1626            let residual = (i as f64) - 24.5;
1627            predictor.observe(key, 100.0, 100.0 + residual);
1628        }
1629
1630        let p = predictor.predict(key, 100.0, 1_000.0);
1631        // (50+1)*0.9 = 45.9, ceil = 46, idx = 45 -> sorted residual at index 45
1632        // sorted: [-24.5, -23.5, ..., 24.5], index 45 = 20.5
1633        assert_eq!(p.fallback_level, 0);
1634        assert_eq!(p.sample_count, 50);
1635        assert_eq!(p.quantile, Some(20.5));
1636        // upper_us = 100 + max(20.5, 0) = 120.5
1637        assert_eq!(p.upper_us, Some(120.5));
1638    }
1639
1640    #[test]
1641    fn calibration_constant_residuals() {
1642        // All residuals identical -> quantile should be that constant.
1643        let mut predictor = ConformalPredictor::new(ConformalConfig {
1644            alpha: 0.05,
1645            min_samples: 1,
1646            window_size: 256,
1647            q_default: 0.0,
1648        })
1649        .expect("valid config");
1650        let key = test_key(80, 24);
1651        for _ in 0..30 {
1652            predictor.observe(key, 100.0, 105.0); // residual = 5.0
1653        }
1654        let p = predictor.predict(key, 100.0, 1_000.0);
1655        assert_eq!(p.quantile, Some(5.0));
1656        assert_eq!(p.upper_us, Some(105.0));
1657    }
1658
1659    // --- Deterministic order-statistic checks (not statistical coverage evidence) ---
1660
1661    #[test]
1662    fn quantile_covers_expected_fraction_of_uniform_grid() {
1663        // A fixed calibration grid and a finer query grid check indexing only.
1664        // These are not independent draws or a statistical coverage experiment.
1665        let alpha = 0.1;
1666        let n_calibrate = 100;
1667        let n_test = 200;
1668
1669        let mut predictor = ConformalPredictor::new(ConformalConfig {
1670            alpha,
1671            min_samples: 1,
1672            window_size: 256,
1673            q_default: 0.0,
1674        })
1675        .expect("valid config");
1676        let key = test_key(80, 24);
1677
1678        // Calibrate: residuals are 0, 1, 2, ..., 99
1679        for i in 0..n_calibrate {
1680            predictor.observe(key, 0.0, i as f64);
1681        }
1682
1683        // Test coverage: for each "new" sample, check if it falls within the
1684        // prediction interval [0, y_hat + q].
1685        let prediction = predictor.predict(key, 0.0, f64::MAX);
1686        let upper_bound = prediction.upper_us.expect("attainable rank");
1687
1688        let mut covered = 0;
1689        // Test samples: same distribution range [0..200)
1690        for i in 0..n_test {
1691            let new_obs = (i as f64) * (n_calibrate as f64) / (n_test as f64);
1692            if new_obs <= upper_bound {
1693                covered += 1;
1694            }
1695        }
1696
1697        let empirical_coverage = covered as f64 / n_test as f64;
1698        // Coverage should be >= 1 - alpha - epsilon (epsilon accounts for
1699        // finite-sample effects)
1700        let target_coverage = 1.0 - alpha - 0.05; // generous epsilon
1701        assert!(
1702            empirical_coverage >= target_coverage,
1703            "Empirical coverage {empirical_coverage:.3} should be >= {target_coverage:.3}"
1704        );
1705    }
1706
1707    #[test]
1708    fn quantile_covers_expected_fraction_of_calibration_grid() {
1709        // Reusing calibration points checks the order statistic, not coverage
1710        // on future samples or under a distribution shift.
1711        let alpha = 0.05;
1712        let n = 200;
1713
1714        let mut predictor = ConformalPredictor::new(ConformalConfig {
1715            alpha,
1716            min_samples: 1,
1717            window_size: 512,
1718            q_default: 0.0,
1719        })
1720        .expect("valid config");
1721        let key = test_key(80, 24);
1722
1723        // Calibrate with known residuals: 1.0, 2.0, ..., 200.0
1724        for i in 1..=n {
1725            predictor.observe(key, 0.0, i as f64);
1726        }
1727
1728        let p = predictor.predict(key, 0.0, f64::MAX);
1729        // (200+1)*0.95 = 190.95, ceil = 191, idx = 190 -> sorted[190] = 191.0
1730        assert_eq!(p.quantile, Some(191.0));
1731        // At least 95% of calibration samples should be <= upper bound
1732        let upper = p.upper_us.expect("attainable rank");
1733        let covered = (1..=n).filter(|&i| (i as f64) <= upper).count();
1734        let coverage = covered as f64 / n as f64;
1735        assert!(
1736            coverage >= 1.0 - alpha,
1737            "Coverage {coverage:.3} should be >= {:.3}",
1738            1.0 - alpha
1739        );
1740    }
1741
1742    // --- Gate trigger behavior at boundary conditions ---
1743
1744    #[test]
1745    fn gate_trigger_exact_boundary() {
1746        // When upper_us == budget_us, risk should be false (not strictly greater)
1747        let mut predictor = ConformalPredictor::new(ConformalConfig {
1748            alpha: 0.5,
1749            min_samples: 1,
1750            window_size: 8,
1751            q_default: 0.0,
1752        })
1753        .expect("valid config");
1754        let key = test_key(80, 24);
1755        predictor.observe(key, 0.0, 50.0);
1756        // quantile = 50.0, y_hat = 0.0, upper_us = 50.0
1757        let p = predictor.predict(key, 0.0, 50.0);
1758        assert!(
1759            !p.risk,
1760            "upper_us ({:?}) == budget_us ({}) should NOT trigger risk",
1761            p.upper_us, p.budget_us
1762        );
1763    }
1764
1765    #[test]
1766    fn gate_trigger_just_above_boundary() {
1767        // When upper_us is epsilon above budget, risk should be true
1768        let mut predictor = ConformalPredictor::new(ConformalConfig {
1769            alpha: 0.5,
1770            min_samples: 1,
1771            window_size: 8,
1772            q_default: 0.0,
1773        })
1774        .expect("valid config");
1775        let key = test_key(80, 24);
1776        predictor.observe(key, 0.0, 50.0);
1777        // upper_us = 50.0, budget = 49.999
1778        let p = predictor.predict(key, 0.0, 49.999);
1779        assert!(p.risk, "upper_us > budget should trigger risk");
1780    }
1781
1782    #[test]
1783    fn gate_trigger_just_below_boundary() {
1784        // When upper_us is epsilon below budget, risk should be false
1785        let mut predictor = ConformalPredictor::new(ConformalConfig {
1786            alpha: 0.5,
1787            min_samples: 1,
1788            window_size: 8,
1789            q_default: 0.0,
1790        })
1791        .expect("valid config");
1792        let key = test_key(80, 24);
1793        predictor.observe(key, 0.0, 50.0);
1794        // upper_us = 50.0, budget = 50.001
1795        let p = predictor.predict(key, 0.0, 50.001);
1796        assert!(!p.risk, "upper_us < budget should NOT trigger risk");
1797    }
1798
1799    #[test]
1800    fn gate_trigger_zero_budget() {
1801        // Zero budget: any positive prediction should trigger risk
1802        let predictor = ConformalPredictor::new(ConformalConfig {
1803            alpha: 0.1,
1804            min_samples: 1,
1805            window_size: 8,
1806            q_default: 1.0,
1807        })
1808        .expect("valid config");
1809        let key = test_key(80, 24);
1810        let p = predictor.predict(key, 0.0, 0.0);
1811        assert!(p.risk, "positive upper_us with zero budget should be risky");
1812    }
1813
1814    #[test]
1815    fn gate_trigger_very_large_budget() {
1816        // Extremely large budget: should never trigger risk
1817        let predictor = ConformalPredictor::new(ConformalConfig {
1818            alpha: 0.1,
1819            min_samples: 1,
1820            window_size: 8,
1821            q_default: 100_000.0,
1822        })
1823        .expect("valid config");
1824        let key = test_key(80, 24);
1825        let p = predictor.predict(key, 1_000.0, f64::MAX);
1826        assert!(!p.risk, "huge budget should never trigger risk");
1827    }
1828
1829    // --- Alpha parameter sensitivity ---
1830
1831    #[test]
1832    fn alpha_sensitivity_wider_interval_with_lower_alpha() {
1833        let key = test_key(80, 24);
1834
1835        // Calibrate two predictors with different alpha on same data
1836        let mut predictor_tight = ConformalPredictor::new(ConformalConfig {
1837            alpha: 0.5, // 50% coverage -> narrower interval
1838            min_samples: 1,
1839            window_size: 256,
1840            q_default: 0.0,
1841        })
1842        .expect("valid config");
1843
1844        let mut predictor_wide = ConformalPredictor::new(ConformalConfig {
1845            alpha: 0.01, // 99% coverage -> wider interval
1846            min_samples: 1,
1847            window_size: 256,
1848            q_default: 0.0,
1849        })
1850        .expect("valid config");
1851
1852        for i in 0..100 {
1853            let obs = i as f64;
1854            predictor_tight.observe(key, 0.0, obs);
1855            predictor_wide.observe(key, 0.0, obs);
1856        }
1857
1858        let p_tight = predictor_tight.predict(key, 0.0, 10_000.0);
1859        let p_wide = predictor_wide.predict(key, 0.0, 10_000.0);
1860
1861        assert!(
1862            p_wide.quantile.expect("attainable rank") > p_tight.quantile.expect("attainable rank"),
1863            "Lower alpha ({}) should produce wider interval: quantile {:?} vs {:?}",
1864            0.01,
1865            p_wide.quantile,
1866            p_tight.quantile
1867        );
1868        assert!(
1869            p_wide.upper_us.expect("attainable rank") > p_tight.upper_us.expect("attainable rank"),
1870            "Lower alpha should produce higher upper bound"
1871        );
1872    }
1873
1874    #[test]
1875    fn alpha_sensitivity_confidence_reflects_alpha() {
1876        for &alpha in &[0.01, 0.05, 0.1, 0.2, 0.5] {
1877            let mut predictor = ConformalPredictor::new(ConformalConfig {
1878                alpha,
1879                min_samples: 1,
1880                window_size: 128,
1881                q_default: 0.0,
1882            })
1883            .expect("valid config");
1884            let key = test_key(80, 24);
1885            let p = predictor.predict(key, 0.0, 1_000.0);
1886            assert_eq!(p.alpha, alpha);
1887            assert_eq!(p.confidence, None);
1888            for _ in 0..100 {
1889                predictor.observe(key, 0.0, 1.0);
1890            }
1891            let p = predictor.predict(key, 0.0, 1_000.0);
1892            let expected_confidence = 1.0 - alpha;
1893            assert!(
1894                (p.confidence.expect("attainable rank") - expected_confidence).abs() < 1e-10,
1895                "confidence should be 1-alpha for alpha={alpha}"
1896            );
1897        }
1898    }
1899
1900    #[test]
1901    fn alpha_sensitivity_extreme_alpha_zero() {
1902        // Very small alpha requires a rank beyond the available samples.
1903        let mut predictor = ConformalPredictor::new(ConformalConfig {
1904            alpha: 0.001,
1905            min_samples: 1,
1906            window_size: 256,
1907            q_default: 0.0,
1908        })
1909        .expect("valid config");
1910        let key = test_key(80, 24);
1911        for i in 0..100 {
1912            predictor.observe(key, 0.0, i as f64);
1913        }
1914        let p = predictor.predict(key, 0.0, 10_000.0);
1915        assert_eq!(p.required_rank, 101);
1916        assert_eq!(p.quantile, None);
1917        assert_eq!(p.upper_us, None);
1918        assert_eq!(p.status, ConformalStatus::UnattainableRank);
1919    }
1920
1921    #[test]
1922    fn alpha_sensitivity_extreme_alpha_one() {
1923        // alpha near 1 -> coverage near 0% -> picks the smallest residual
1924        let mut predictor = ConformalPredictor::new(ConformalConfig {
1925            alpha: 0.99,
1926            min_samples: 1,
1927            window_size: 256,
1928            q_default: 0.0,
1929        })
1930        .expect("valid config");
1931        let key = test_key(80, 24);
1932        for i in 0..100 {
1933            predictor.observe(key, 0.0, i as f64);
1934        }
1935        let p = predictor.predict(key, 0.0, 10_000.0);
1936        // (100+1)*0.01 = 1.01, ceil=2, idx=1 -> sorted[1]=1
1937        assert_eq!(p.quantile, Some(1.0));
1938    }
1939
1940    // --- Empty/small calibration set handling ---
1941
1942    #[test]
1943    fn empty_calibration_uses_default() {
1944        let predictor = ConformalPredictor::new(ConformalConfig {
1945            alpha: 0.05,
1946            min_samples: 20,
1947            window_size: 256,
1948            q_default: 10_000.0,
1949        })
1950        .expect("valid config");
1951        let key = test_key(80, 24);
1952        let p = predictor.predict(key, 100.0, 16_666.0);
1953        assert_eq!(p.sample_count, 0);
1954        assert_eq!(p.fallback_level, 3);
1955        assert_eq!(p.quantile, None);
1956        assert_eq!(p.upper_us, None);
1957        assert_eq!(p.warmup_upper_us, Some(10_100.0));
1958    }
1959
1960    #[test]
1961    fn one_sample_below_min_samples_uses_fallback() {
1962        // With min_samples=20, 1 sample should fall through to global (level 3)
1963        let mut predictor = ConformalPredictor::new(ConformalConfig {
1964            alpha: 0.05,
1965            min_samples: 20,
1966            window_size: 256,
1967            q_default: 999.0,
1968        })
1969        .expect("valid config");
1970        let key = test_key(80, 24);
1971        predictor.observe(key, 0.0, 5.0);
1972        let p = predictor.predict(key, 0.0, 1_000.0);
1973        // Only 1 sample in exact bucket, 1 in mode+diff, 1 in mode, 1 in global
1974        // Global has data, so uses global fallback (level 3)
1975        assert_eq!(p.fallback_level, 3);
1976        assert_eq!(p.sample_count, 1);
1977    }
1978
1979    #[test]
1980    fn exactly_min_samples_minus_one_uses_fallback() {
1981        let min_samples = 5;
1982        let mut predictor = ConformalPredictor::new(ConformalConfig {
1983            alpha: 0.1,
1984            min_samples,
1985            window_size: 256,
1986            q_default: 999.0,
1987        })
1988        .expect("valid config");
1989        let key = test_key(80, 24);
1990        for i in 0..(min_samples - 1) {
1991            predictor.observe(key, 0.0, (i as f64) * 10.0);
1992        }
1993        let p = predictor.predict(key, 0.0, 1_000.0);
1994        // 4 samples < min_samples=5, so exact bucket not used
1995        // Falls through to mode+diff (4 samples < 5), mode (4 < 5), global (4 > 0)
1996        assert_eq!(p.fallback_level, 3);
1997        assert_eq!(p.sample_count, min_samples - 1);
1998    }
1999
2000    #[test]
2001    fn exactly_min_samples_uses_exact_bucket() {
2002        let min_samples = 5;
2003        let mut predictor = ConformalPredictor::new(ConformalConfig {
2004            alpha: 0.1,
2005            min_samples,
2006            window_size: 256,
2007            q_default: 999.0,
2008        })
2009        .expect("valid config");
2010        let key = test_key(80, 24);
2011        for i in 0..min_samples {
2012            predictor.observe(key, 0.0, (i as f64) * 10.0);
2013        }
2014        let p = predictor.predict(key, 0.0, 1_000.0);
2015        // 5 samples == min_samples=5, exact bucket should be used
2016        assert_eq!(p.fallback_level, 0);
2017        assert_eq!(p.sample_count, min_samples);
2018    }
2019
2020    #[test]
2021    fn min_samples_plus_one_uses_exact_bucket() {
2022        let min_samples = 5;
2023        let mut predictor = ConformalPredictor::new(ConformalConfig {
2024            alpha: 0.1,
2025            min_samples,
2026            window_size: 256,
2027            q_default: 999.0,
2028        })
2029        .expect("valid config");
2030        let key = test_key(80, 24);
2031        for i in 0..=min_samples {
2032            predictor.observe(key, 0.0, (i as f64) * 10.0);
2033        }
2034        let p = predictor.predict(key, 0.0, 1_000.0);
2035        assert_eq!(p.fallback_level, 0);
2036        assert_eq!(p.sample_count, min_samples + 1);
2037    }
2038
2039    #[test]
2040    fn min_samples_one_allows_single_observation() {
2041        // Edge case: min_samples = 1
2042        let mut predictor = ConformalPredictor::new(ConformalConfig {
2043            alpha: 0.1,
2044            min_samples: 1,
2045            window_size: 256,
2046            q_default: 999.0,
2047        })
2048        .expect("valid config");
2049        let key = test_key(80, 24);
2050        predictor.observe(key, 0.0, 42.0);
2051        let p = predictor.predict(key, 0.0, 1_000.0);
2052        assert_eq!(p.fallback_level, 0);
2053        assert_eq!(p.sample_count, 1);
2054        assert_eq!(p.quantile, None);
2055        assert_eq!(p.status, ConformalStatus::UnattainableRank);
2056    }
2057
2058    // --- Tracing span field assertions ---
2059
2060    #[test]
2061    fn predict_span_records_calibration_set_size() {
2062        use std::sync::Arc;
2063        use std::sync::Mutex;
2064
2065        struct FieldRecorder {
2066            calibration_size: Arc<Mutex<Option<u64>>>,
2067        }
2068
2069        struct SizeVisitor(Arc<Mutex<Option<u64>>>);
2070
2071        impl tracing::field::Visit for SizeVisitor {
2072            fn record_u64(&mut self, field: &tracing::field::Field, value: u64) {
2073                if field.name() == "calibration_set_size" {
2074                    *self.0.lock().unwrap() = Some(value);
2075                }
2076            }
2077            fn record_debug(&mut self, _field: &tracing::field::Field, _value: &dyn fmt::Debug) {}
2078        }
2079
2080        impl tracing::Subscriber for FieldRecorder {
2081            fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
2082                true
2083            }
2084            fn new_span(&self, _span: &tracing::span::Attributes<'_>) -> tracing::span::Id {
2085                tracing::span::Id::from_u64(1)
2086            }
2087            fn record(&self, _span: &tracing::span::Id, values: &tracing::span::Record<'_>) {
2088                let mut v = SizeVisitor(Arc::clone(&self.calibration_size));
2089                values.record(&mut v);
2090            }
2091            fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
2092            fn event(&self, _: &tracing::Event<'_>) {}
2093            fn enter(&self, _: &tracing::span::Id) {}
2094            fn exit(&self, _: &tracing::span::Id) {}
2095        }
2096
2097        let size = Arc::new(Mutex::new(None));
2098        let subscriber = FieldRecorder {
2099            calibration_size: Arc::clone(&size),
2100        };
2101        let _guard = tracing::subscriber::set_default(subscriber);
2102
2103        let mut predictor = ConformalPredictor::new(ConformalConfig {
2104            alpha: 0.1,
2105            min_samples: 1,
2106            window_size: 8,
2107            q_default: 0.0,
2108        })
2109        .expect("valid config");
2110        let key = test_key(80, 24);
2111        for i in 0..5 {
2112            predictor.observe(key, 0.0, i as f64);
2113        }
2114        let _ = predictor.predict(key, 0.0, 1_000.0);
2115
2116        let recorded = size.lock().unwrap();
2117        assert_eq!(*recorded, Some(5), "calibration_set_size should be 5");
2118    }
2119
2120    #[test]
2121    fn predict_span_records_predicted_upper_bound() {
2122        use std::sync::Arc;
2123        use std::sync::Mutex;
2124
2125        struct UpperBoundRecorder {
2126            upper_bound: Arc<Mutex<Option<f64>>>,
2127        }
2128
2129        struct UpperVisitor(Arc<Mutex<Option<f64>>>);
2130
2131        impl tracing::field::Visit for UpperVisitor {
2132            fn record_f64(&mut self, field: &tracing::field::Field, value: f64) {
2133                if field.name() == "predicted_upper_bound_us" {
2134                    *self.0.lock().unwrap() = Some(value);
2135                }
2136            }
2137            fn record_debug(&mut self, _: &tracing::field::Field, _: &dyn fmt::Debug) {}
2138        }
2139
2140        impl tracing::Subscriber for UpperBoundRecorder {
2141            fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
2142                true
2143            }
2144            fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
2145                tracing::span::Id::from_u64(1)
2146            }
2147            fn record(&self, _: &tracing::span::Id, values: &tracing::span::Record<'_>) {
2148                let mut v = UpperVisitor(Arc::clone(&self.upper_bound));
2149                values.record(&mut v);
2150            }
2151            fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
2152            fn event(&self, _: &tracing::Event<'_>) {}
2153            fn enter(&self, _: &tracing::span::Id) {}
2154            fn exit(&self, _: &tracing::span::Id) {}
2155        }
2156
2157        let upper = Arc::new(Mutex::new(None));
2158        let subscriber = UpperBoundRecorder {
2159            upper_bound: Arc::clone(&upper),
2160        };
2161        let _guard = tracing::subscriber::set_default(subscriber);
2162
2163        let mut predictor = ConformalPredictor::new(ConformalConfig {
2164            alpha: 0.5,
2165            min_samples: 1,
2166            window_size: 8,
2167            q_default: 42.0,
2168        })
2169        .expect("valid config");
2170        let key = test_key(80, 24);
2171        let p = predictor.predict(key, 10.0, 1_000.0);
2172        assert_eq!(p.upper_us, None);
2173        assert_eq!(
2174            *upper.lock().unwrap(),
2175            None,
2176            "warmup must not emit a calibrated bound"
2177        );
2178        predictor.observe(key, 0.0, 42.0);
2179        let p = predictor.predict(key, 10.0, 1_000.0);
2180        assert_eq!(p.upper_us, Some(52.0));
2181        assert_eq!(*upper.lock().unwrap(), p.upper_us);
2182    }
2183
2184    #[test]
2185    fn predict_span_records_gate_triggered_false() {
2186        use std::sync::Arc;
2187        use std::sync::Mutex;
2188
2189        struct GateFalseChecker {
2190            gate_value: Arc<Mutex<Option<bool>>>,
2191        }
2192
2193        struct GateFalseVisitor(Arc<Mutex<Option<bool>>>);
2194
2195        impl tracing::field::Visit for GateFalseVisitor {
2196            fn record_bool(&mut self, field: &tracing::field::Field, value: bool) {
2197                if field.name() == "gate_triggered" {
2198                    *self.0.lock().unwrap() = Some(value);
2199                }
2200            }
2201            fn record_debug(&mut self, _: &tracing::field::Field, _: &dyn fmt::Debug) {}
2202        }
2203
2204        impl tracing::Subscriber for GateFalseChecker {
2205            fn enabled(&self, _: &tracing::Metadata<'_>) -> bool {
2206                true
2207            }
2208            fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
2209                tracing::span::Id::from_u64(1)
2210            }
2211            fn record(&self, _: &tracing::span::Id, values: &tracing::span::Record<'_>) {
2212                let mut v = GateFalseVisitor(Arc::clone(&self.gate_value));
2213                values.record(&mut v);
2214            }
2215            fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
2216            fn event(&self, _: &tracing::Event<'_>) {}
2217            fn enter(&self, _: &tracing::span::Id) {}
2218            fn exit(&self, _: &tracing::span::Id) {}
2219        }
2220
2221        let gate = Arc::new(Mutex::new(None));
2222        let subscriber = GateFalseChecker {
2223            gate_value: Arc::clone(&gate),
2224        };
2225        let _guard = tracing::subscriber::set_default(subscriber);
2226
2227        let predictor = ConformalPredictor::new(ConformalConfig {
2228            alpha: 0.1,
2229            min_samples: 1,
2230            window_size: 8,
2231            q_default: 1.0,
2232        })
2233        .expect("valid config");
2234        let key = test_key(80, 24);
2235        let p = predictor.predict(key, 0.0, 1_000_000.0);
2236        assert!(!p.risk);
2237
2238        let recorded = gate.lock().unwrap();
2239        assert_eq!(
2240            *recorded,
2241            Some(false),
2242            "gate_triggered should be recorded as false"
2243        );
2244    }
2245
2246    // --- JSONL output ---
2247
2248    #[test]
2249    fn jsonl_output_contains_required_fields() {
2250        let prediction = ConformalPrediction {
2251            upper_us: Some(150.5),
2252            risk: true,
2253            confidence: Some(0.95),
2254            alpha: 0.05,
2255            status: ConformalStatus::Calibrated,
2256            required_rank: 41,
2257            warmup_upper_us: None,
2258            bucket: BucketKey {
2259                mode: ModeBucket::Inline,
2260                diff: DiffBucket::Full,
2261                size_bucket: 10,
2262            },
2263            sample_count: 42,
2264            quantile: Some(50.5),
2265            fallback_level: 0,
2266            window_size: 256,
2267            reset_count: 1,
2268            y_hat: 100.0,
2269            budget_us: 140.0,
2270        };
2271        let jsonl = prediction.to_jsonl();
2272        assert!(jsonl.contains("\"schema\":\"conformal-v2\""));
2273        assert!(jsonl.contains("\"upper_us\":150.5"));
2274        assert!(jsonl.contains("\"risk\":true"));
2275        let parsed: serde_json::Value = serde_json::from_str(&jsonl).expect("valid JSON");
2276        assert_eq!(parsed["confidence"].as_f64(), Some(0.95));
2277        assert!(jsonl.contains("\"bucket\":\"inline:full:10\""));
2278        assert!(jsonl.contains("\"samples\":42"));
2279        assert!(jsonl.contains("\"quantile\":50.50"));
2280        assert!(jsonl.contains("\"fallback_level\":0"));
2281        assert!(jsonl.contains("\"window\":256"));
2282        assert!(jsonl.contains("\"resets\":1"));
2283        assert!(jsonl.contains("\"y_hat\":100.0"));
2284        assert!(jsonl.contains("\"budget_us\":140.0"));
2285    }
2286
2287    // --- Deterministic calibration-grid checks ---
2288
2289    #[test]
2290    fn quantile_grid_fraction_for_multiple_alphas() {
2291        // These reused calibration points check indexing, not coverage of a
2292        // future random observation. Independent experiments are tested below.
2293        for alpha in [0.05, 0.1, 0.2] {
2294            let n_calibrate = 100;
2295            let n_test = 100;
2296
2297            let mut predictor = ConformalPredictor::new(ConformalConfig {
2298                alpha,
2299                min_samples: 1,
2300                window_size: 256,
2301                q_default: 0.0,
2302            })
2303            .expect("valid config");
2304            let key = test_key(80, 24);
2305
2306            // Calibrate with residuals 1.0, 2.0, ..., 100.0
2307            for i in 1..=n_calibrate {
2308                predictor.observe(key, 0.0, i as f64);
2309            }
2310
2311            let p = predictor.predict(key, 0.0, f64::MAX);
2312
2313            // Count how many calibration-like points are covered
2314            let upper = p.upper_us.expect("attainable rank");
2315            let covered = (1..=n_test).filter(|&i| (i as f64) <= upper).count();
2316            let coverage = covered as f64 / n_test as f64;
2317
2318            assert!(
2319                coverage >= 1.0 - alpha - 0.02,
2320                "alpha={alpha}: coverage {coverage:.3} should be >= {:.3}",
2321                1.0 - alpha - 0.02
2322            );
2323        }
2324    }
2325
2326    #[test]
2327    fn property_monotone_quantile_with_more_extreme_data() {
2328        // Adding more extreme residuals should increase the quantile
2329        let key = test_key(80, 24);
2330
2331        let mut predictor = ConformalPredictor::new(ConformalConfig {
2332            alpha: 0.1,
2333            min_samples: 1,
2334            window_size: 256,
2335            q_default: 0.0,
2336        })
2337        .expect("valid config");
2338
2339        // First: moderate residuals
2340        for i in 0..50 {
2341            predictor.observe(key, 0.0, i as f64);
2342        }
2343        let q_moderate = predictor
2344            .predict(key, 0.0, f64::MAX)
2345            .quantile
2346            .expect("attainable rank");
2347
2348        // Add extreme residuals
2349        for _ in 0..50 {
2350            predictor.observe(key, 0.0, 1000.0);
2351        }
2352        let q_extreme = predictor
2353            .predict(key, 0.0, f64::MAX)
2354            .quantile
2355            .expect("attainable rank");
2356
2357        assert!(
2358            q_extreme >= q_moderate,
2359            "Adding extreme data should not decrease quantile: {q_extreme} vs {q_moderate}"
2360        );
2361    }
2362
2363    #[test]
2364    fn property_quantile_bounded_by_max_residual() {
2365        // Only an attainable finite quantile is bounded by the observed max.
2366        let key = test_key(80, 24);
2367        let mut predictor = ConformalPredictor::new(ConformalConfig {
2368            alpha: 0.001, // very high coverage
2369            min_samples: 1,
2370            window_size: 256,
2371            q_default: 0.0,
2372        })
2373        .expect("valid config");
2374
2375        let max_residual = 98.0;
2376        for i in 0..50 {
2377            predictor.observe(key, 0.0, (i as f64) * 2.0); // 0, 2, 4, ..., 98
2378        }
2379
2380        let p = predictor.predict(key, 0.0, f64::MAX);
2381        assert_eq!(p.quantile, None);
2382        assert_eq!(p.status, ConformalStatus::UnattainableRank);
2383        let mut finite_predictor = ConformalPredictor::new(ConformalConfig {
2384            alpha: 0.05,
2385            ..predictor.config().clone()
2386        })
2387        .expect("valid config");
2388        for i in 0..50 {
2389            finite_predictor.observe(key, 0.0, f64::from(i) * 2.0);
2390        }
2391        let quantile = finite_predictor
2392            .predict(key, 0.0, f64::MAX)
2393            .quantile
2394            .expect("attainable rank");
2395        assert!(
2396            quantile <= max_residual,
2397            "quantile {quantile} should be <= max residual {max_residual}"
2398        );
2399    }
2400
2401    #[test]
2402    fn property_window_eviction_changes_quantile() {
2403        // After filling and evicting the window, old extreme values should
2404        // no longer affect the quantile
2405        let key = test_key(80, 24);
2406        let window_size = 10;
2407
2408        let mut predictor = ConformalPredictor::new(ConformalConfig {
2409            alpha: 0.1,
2410            min_samples: 1,
2411            window_size,
2412            q_default: 0.0,
2413        })
2414        .expect("valid config");
2415
2416        // Fill window with large residuals
2417        for _ in 0..window_size {
2418            predictor.observe(key, 0.0, 1000.0);
2419        }
2420        let q_large = predictor
2421            .predict(key, 0.0, f64::MAX)
2422            .quantile
2423            .expect("attainable rank");
2424
2425        // Evict all large residuals with small ones
2426        for _ in 0..window_size {
2427            predictor.observe(key, 0.0, 1.0);
2428        }
2429        let q_small = predictor
2430            .predict(key, 0.0, f64::MAX)
2431            .quantile
2432            .expect("attainable rank");
2433
2434        assert!(
2435            q_small < q_large,
2436            "After eviction, quantile should decrease: {q_small} vs {q_large}"
2437        );
2438    }
2439
2440    // --- Multiple bucket interaction ---
2441
2442    #[test]
2443    fn cross_mode_fallback_does_not_mix_modes() {
2444        // mode_diff fallback only aggregates same mode+diff, not across modes
2445        let mut predictor = ConformalPredictor::new(ConformalConfig {
2446            alpha: 0.1,
2447            min_samples: 5,
2448            window_size: 256,
2449            q_default: 999.0,
2450        })
2451        .expect("valid config");
2452
2453        // Add data to AltScreen mode
2454        let alt_key = BucketKey::from_context(ScreenMode::AltScreen, DiffStrategy::Full, 80, 24);
2455        for i in 0..10 {
2456            predictor.observe(alt_key, 0.0, (i as f64) * 100.0);
2457        }
2458
2459        // Query Inline mode with different size bucket (no exact match)
2460        let inline_key = BucketKey::from_context(
2461            ScreenMode::Inline { ui_height: 4 },
2462            DiffStrategy::Full,
2463            120,
2464            40,
2465        );
2466        let p = predictor.predict(inline_key, 0.0, 1_000_000.0);
2467
2468        // Mode fallback should NOT find inline data, so falls to global
2469        assert_eq!(
2470            p.fallback_level, 3,
2471            "Cross-mode query should fall to global"
2472        );
2473    }
2474
2475    #[test]
2476    fn reset_count_accumulates_across_resets() {
2477        let mut predictor =
2478            ConformalPredictor::new(ConformalConfig::default()).expect("valid config");
2479        let key = test_key(80, 24);
2480
2481        predictor.observe(key, 0.0, 1.0);
2482        predictor.reset_bucket(key);
2483        predictor.observe(key, 0.0, 2.0);
2484        predictor.reset_all();
2485        predictor.observe(key, 0.0, 3.0);
2486        predictor.reset_bucket(key);
2487
2488        let p = predictor.predict(key, 0.0, 1_000.0);
2489        assert_eq!(p.reset_count, 3, "reset_count should accumulate");
2490    }
2491}