1#![forbid(unsafe_code)]
2
3use std::collections::{HashMap, VecDeque};
14use std::fmt;
15
16use ftui_render::diff_strategy::DiffStrategy;
17
18use crate::terminal_writer::ScreenMode;
19
20#[derive(Debug, Clone)]
22pub struct ConformalConfig {
23 pub alpha: f64,
27
28 pub min_samples: usize,
31
32 pub window_size: usize,
35
36 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#[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 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#[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 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#[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#[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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
183pub enum ConformalStatus {
184 Warmup,
186 Calibrated,
188 UnattainableRank,
190 InvalidInput,
192 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#[derive(Debug, Clone)]
210pub struct ConformalPrediction {
211 pub upper_us: Option<f64>,
213 pub risk: bool,
215 pub confidence: Option<f64>,
218 pub alpha: f64,
220 pub status: ConformalStatus,
221 pub required_rank: usize,
223 pub warmup_upper_us: Option<f64>,
225 pub bucket: BucketKey,
227 pub sample_count: usize,
229 pub quantile: Option<f64>,
231 pub fallback_level: u8,
233 pub window_size: usize,
235 pub reset_count: u64,
237 pub y_hat: f64,
239 pub budget_us: f64,
241}
242
243impl ConformalPrediction {
244 #[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 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 format!("{value:e}")
289 }
290 }
291 },
292 )
293}
294
295#[derive(Debug, Clone)]
297pub struct ConformalUpdate {
298 pub residual: Option<f64>,
300 pub bucket: BucketKey,
302 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#[derive(Debug)]
322pub struct ConformalPredictor {
323 config: ConformalConfig,
324 buckets: HashMap<BucketKey, BucketState>,
325 reset_count: u64,
326}
327
328impl ConformalPredictor {
329 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 pub fn config(&self) -> &ConformalConfig {
341 &self.config
342 }
343
344 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 pub fn reset_all(&mut self) {
354 self.buckets.clear();
355 self.reset_count += 1;
356 }
357
358 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 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 #[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 target: crate::telemetry_schema::TARGET_RUNTIME,
460 bucket = %key,
461 y_hat_us,
462 quantile = ?quantile,
463 status = status.as_str(),
464 required_rank,
465 fallback_level,
466 sample_count,
467 "prediction interval"
468 );
469
470 ConformalPrediction {
471 upper_us,
472 risk,
473 confidence: upper_us.map(|_| 1.0 - self.config.alpha),
474 alpha: self.config.alpha,
475 status,
476 required_rank,
477 warmup_upper_us,
478 bucket: key,
479 sample_count,
480 quantile,
481 fallback_level,
482 window_size: self.config.window_size,
483 reset_count: self.reset_count,
484 y_hat: y_hat_us,
485 budget_us,
486 }
487 }
488
489 fn quantile_for(&self, key: BucketKey) -> QuantileDecision {
490 let min_samples = self.config.min_samples;
491
492 if let Some(state) = self.buckets.get(&key)
493 && state.residuals.len() >= min_samples
494 {
495 let len = state.residuals.len();
496 if len <= 256 {
497 let mut buf = [0.0f64; 256];
498 let (a, b) = state.residuals.as_slices();
499 buf[..a.len()].copy_from_slice(a);
500 buf[a.len()..len].copy_from_slice(b);
501 return QuantileDecision::from_slice(self.config.alpha, &mut buf[..len], 0);
502 }
503 let exact: Vec<f64> = state.residuals.iter().copied().collect();
504 return QuantileDecision::new(self.config.alpha, exact, 0);
505 }
506
507 let mode_diff = self.collect_mode_diff(key.mode, key.diff);
508 if mode_diff.len() >= min_samples {
509 return QuantileDecision::new(self.config.alpha, mode_diff, 1);
510 }
511
512 let mode_only = self.collect_mode(key.mode);
513 if mode_only.len() >= min_samples {
514 return QuantileDecision::new(self.config.alpha, mode_only, 2);
515 }
516
517 let global = self.collect_all();
518 if !global.is_empty() {
519 return QuantileDecision::new(self.config.alpha, global, 3);
520 }
521
522 QuantileDecision {
523 quantile: None,
524 required_rank: 1,
525 heuristic_residual: self.config.q_default,
526 sample_count: 0,
527 fallback_level: 3,
528 }
529 }
530
531 fn collect_mode_diff(&self, mode: ModeBucket, diff: DiffBucket) -> Vec<f64> {
532 let mut values = Vec::new();
533 for (key, state) in &self.buckets {
534 if key.mode == mode && key.diff == diff {
535 values.extend(state.residuals.iter().copied());
536 }
537 }
538 values
539 }
540
541 fn collect_mode(&self, mode: ModeBucket) -> Vec<f64> {
542 let mut values = Vec::new();
543 for (key, state) in &self.buckets {
544 if key.mode == mode {
545 values.extend(state.residuals.iter().copied());
546 }
547 }
548 values
549 }
550
551 fn collect_all(&self) -> Vec<f64> {
552 let mut values = Vec::new();
553 for state in self.buckets.values() {
554 values.extend(state.residuals.iter().copied());
555 }
556 values
557 }
558}
559
560#[derive(Debug)]
561struct QuantileDecision {
562 quantile: Option<f64>,
563 required_rank: usize,
564 heuristic_residual: f64,
565 sample_count: usize,
566 fallback_level: u8,
567}
568
569impl QuantileDecision {
570 fn from_slice(alpha: f64, residuals: &mut [f64], fallback_level: u8) -> Self {
571 let sample_count = residuals.len();
572 let required_rank = conformal_rank(alpha, sample_count);
573 let quantile = conformal_quantile(alpha, residuals);
574 let heuristic_residual = quantile.unwrap_or_else(|| {
575 residuals
576 .iter()
577 .copied()
578 .max_by(f64::total_cmp)
579 .unwrap_or(0.0)
580 });
581 Self {
582 quantile,
583 required_rank,
584 heuristic_residual,
585 sample_count,
586 fallback_level,
587 }
588 }
589
590 fn new(alpha: f64, mut residuals: Vec<f64>, fallback_level: u8) -> Self {
591 Self::from_slice(alpha, &mut residuals, fallback_level)
592 }
593}
594
595fn add_up(a: f64, b: f64) -> f64 {
603 let sum = a + b;
604 if !sum.is_finite() {
605 return sum;
606 }
607 let (large, small) = if a.abs() >= b.abs() { (a, b) } else { (b, a) };
608 let error = small - (sum - large);
609 if error > 0.0 { sum.next_up() } else { sum }
610}
611
612fn conformal_quantile(alpha: f64, residuals: &mut [f64]) -> Option<f64> {
613 let rank = conformal_rank(alpha, residuals.len());
614 if rank == 0 || rank > residuals.len() {
615 return None;
616 }
617 let (_, &mut q, _) = residuals.select_nth_unstable_by(rank - 1, f64::total_cmp);
618 Some(q)
619}
620
621pub(crate) fn conformal_rank(alpha: f64, n: usize) -> usize {
624 let bits = alpha.to_bits();
625 let exponent = ((bits >> 52) & 0x7ff) as u32;
626 let fraction = bits & ((1_u64 << 52) - 1);
627 let significand = if exponent == 0 {
628 fraction
629 } else {
630 fraction | (1_u64 << 52)
631 };
632 let shift = if exponent == 0 { 1074 } else { 1075 - exponent };
633 let count = n as u128 + 1;
634 let product = count * u128::from(significand);
635 let tail_count = if shift >= 128 { 0 } else { product >> shift };
636 usize::try_from(count - tail_count).expect("rank fits addressable residual storage")
638}
639
640fn size_bucket(cols: u16, rows: u16) -> u8 {
641 let area = cols as u32 * rows as u32;
642 if area == 0 {
643 return 0;
644 }
645 (31 - area.leading_zeros()) as u8
646}
647
648#[cfg(test)]
649mod tests {
650 use super::*;
651
652 fn test_key(cols: u16, rows: u16) -> BucketKey {
653 BucketKey::from_context(
654 ScreenMode::Inline { ui_height: 4 },
655 DiffStrategy::Full,
656 cols,
657 rows,
658 )
659 }
660
661 #[test]
662 fn quantile_n_plus_1_rule() {
663 let mut predictor = ConformalPredictor::new(ConformalConfig {
664 alpha: 0.2,
665 min_samples: 1,
666 window_size: 10,
667 q_default: 0.0,
668 })
669 .expect("valid config");
670
671 let key = test_key(80, 24);
672 predictor.observe(key, 0.0, 1.0);
673 predictor.observe(key, 0.0, 2.0);
674 predictor.observe(key, 0.0, 3.0);
675
676 let decision = predictor.predict(key, 0.0, 1_000.0);
677 assert_eq!(decision.quantile, None);
678 assert_eq!(decision.required_rank, 4);
679 assert_eq!(decision.status, ConformalStatus::UnattainableRank);
680 predictor.observe(key, 0.0, 4.0);
681 assert_eq!(predictor.predict(key, 0.0, 1_000.0).quantile, Some(4.0));
682 }
683
684 #[test]
685 fn unavailable_99_percent_rank_is_not_calibrated_at_twenty_samples() {
686 let mut predictor = ConformalPredictor::new(ConformalConfig {
687 alpha: 0.01,
688 min_samples: 20,
689 window_size: 256,
690 q_default: 10_000.0,
691 })
692 .expect("valid config");
693 let key = test_key(80, 24);
694 for observed_us in 1..=20 {
695 predictor.observe(key, 0.0, f64::from(observed_us));
696 }
697 let prediction = predictor.predict(key, 0.0, 100.0);
698 assert_eq!(prediction.sample_count, 20);
699 assert_eq!(prediction.status, ConformalStatus::UnattainableRank);
700 assert_eq!(prediction.required_rank, 21);
701 assert_eq!(prediction.upper_us, None);
702 assert_eq!(prediction.quantile, None);
703 assert_eq!(prediction.confidence, None);
704 assert!(prediction.risk);
705 assert!(
706 !predictor.is_calibrated(&prediction),
707 "99% requires the unavailable 21st order statistic; the observed maximum only supports 20/21 marginal coverage"
708 );
709 }
710
711 #[test]
712 fn ranks_match_exhaustive_held_out_position_oracle() {
713 for n in 0..=24 {
718 for alpha_numerator in [1, 2, 31, 128, 256, 512, 768, 1023] {
719 let alpha = f64::from(alpha_numerator) / 1024.0;
720 let oracle = (1..=n).find(|&candidate| {
721 let covered = (0..=n)
722 .filter(|&held_out| {
723 let training: Vec<_> =
724 (0..=n).filter(|&point| point != held_out).collect();
725 held_out <= training[candidate - 1]
726 })
727 .count();
728 covered * 1024 >= (n + 1) * (1024 - alpha_numerator as usize)
729 });
730 let mut residuals: Vec<_> = (0..n).rev().map(|i| i as f64).collect();
731 assert_eq!(
732 conformal_quantile(alpha, &mut residuals),
733 oracle.map(|rank| (rank - 1) as f64),
734 "n={n}, alpha={alpha}"
735 );
736 assert_eq!(conformal_rank(alpha, n), oracle.unwrap_or(n + 1));
737 }
738 }
739 }
740
741 #[test]
742 fn attainable_boundaries_respect_adjacent_binary64_values() {
743 for power in 1..=10 {
744 let count = 1_usize << power;
745 let alpha = 1.0 / count as f64;
746 assert_eq!(conformal_rank(alpha.next_down(), count - 1), count);
747 assert_eq!(conformal_rank(alpha, count - 1), count - 1);
748 assert_eq!(conformal_rank(alpha.next_up(), count - 1), count - 1);
749 }
750 assert_eq!(conformal_rank(f64::from_bits(1), 20), 21);
751 assert_eq!(conformal_rank(1.0_f64.next_down(), 20), 1);
752 assert_eq!(conformal_rank(1.0 / 3.0, 2), 3);
754 assert_eq!(conformal_rank((1.0_f64 / 3.0).next_up(), 2), 2);
755 }
756
757 #[test]
758 fn invalid_configuration_is_rejected_without_clamping() {
759 for alpha in [
760 f64::NAN,
761 f64::INFINITY,
762 f64::NEG_INFINITY,
763 -1.0,
764 0.0,
765 1.0,
766 2.0,
767 ] {
768 assert!(
769 ConformalPredictor::new(ConformalConfig {
770 alpha,
771 ..Default::default()
772 })
773 .is_err()
774 );
775 }
776 for (min_samples, window_size) in [(0, 20), (20, 0), (21, 20)] {
777 assert!(
778 ConformalPredictor::new(ConformalConfig {
779 min_samples,
780 window_size,
781 ..Default::default()
782 })
783 .is_err()
784 );
785 }
786 for q_default in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, -1.0] {
787 assert!(
788 ConformalPredictor::new(ConformalConfig {
789 q_default,
790 ..Default::default()
791 })
792 .is_err()
793 );
794 }
795 }
796
797 #[test]
798 fn invalid_inputs_and_overflow_have_valid_nullable_evidence() {
799 let key = test_key(80, 24);
800 let mut predictor = ConformalPredictor::new(ConformalConfig {
801 alpha: 0.5,
802 min_samples: 1,
803 window_size: 2,
804 q_default: 0.0,
805 })
806 .expect("valid config");
807 for invalid in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, -1.0] {
808 for (baseline, observed) in [(invalid, 1.0), (1.0, invalid)] {
809 assert_eq!(predictor.observe(key, baseline, observed).residual, None);
810 assert_eq!(predictor.bucket_samples(key), 0);
811 }
812 for (baseline, budget) in [(invalid, 1.0), (1.0, invalid)] {
813 let prediction = predictor.predict(key, baseline, budget);
814 assert_eq!(prediction.status, ConformalStatus::InvalidInput);
815 assert!(prediction.risk);
816 let row: serde_json::Value = serde_json::from_str(&prediction.to_jsonl())
817 .expect("valid JSON even for invalid input");
818 assert!(row["upper_us"].is_null());
819 assert!(row["confidence"].is_null());
820 }
821 }
822 predictor.observe(key, 0.0, f64::MAX);
823 let overflow = predictor.predict(key, f64::MAX, f64::MAX);
824 assert_eq!(overflow.status, ConformalStatus::ArithmeticOverflow);
825 assert_eq!(overflow.upper_us, None);
826 assert_eq!(overflow.confidence, None);
827 assert!(overflow.risk);
828 serde_json::from_str::<serde_json::Value>(&overflow.to_jsonl()).expect("finite JSON");
829 }
830
831 #[test]
832 fn evidence_preserves_tiny_alpha_and_finite_extreme_timings() {
833 let predictor = ConformalPredictor::new(ConformalConfig {
834 alpha: f64::from_bits(1),
835 ..Default::default()
836 })
837 .expect("valid subnormal alpha");
838 let prediction = predictor.predict(test_key(80, 24), f64::MAX, f64::MAX);
839 let row: serde_json::Value =
840 serde_json::from_str(&prediction.to_jsonl()).expect("valid extreme JSON");
841 assert_eq!(row["alpha"].as_f64(), Some(f64::from_bits(1)));
842 assert_eq!(row["y_hat"].as_f64(), Some(f64::MAX));
843 }
844
845 #[test]
846 fn tied_observations_remain_below_the_calibrated_bound_after_rounding() {
847 for (baseline, observed) in [
848 (1.005, 10.001),
849 (1.0, 10_000_000_000_000_002.0),
850 (0.0, f64::from_bits(1)),
851 (10.0, 3.0),
852 (f64::MAX, f64::MAX),
853 ] {
854 let mut predictor = ConformalPredictor::new(ConformalConfig {
855 alpha: 0.5,
856 min_samples: 1,
857 window_size: 1,
858 ..Default::default()
859 })
860 .expect("valid config");
861 let key = test_key(80, 24);
862 predictor.observe(key, baseline, observed);
863 let prediction = predictor.predict(key, baseline, f64::MAX);
864 assert_eq!(prediction.status, ConformalStatus::Calibrated);
865 assert!(
866 prediction.upper_us.unwrap() >= observed,
867 "a tied future observation must remain covered: baseline={baseline:?}, observed={observed:?}, prediction={prediction:?}"
868 );
869 let json: serde_json::Value =
870 serde_json::from_str(&prediction.to_jsonl()).expect("actual predictor JSON");
871 assert!(
872 json["upper_us"].as_f64().expect("finite upper") >= observed,
873 "default JSON reader must retain coverage for this regression: {json}"
874 );
875 }
876 }
877
878 #[test]
879 fn seeded_binary64_ties_remain_covered_or_explicitly_unbounded() {
880 let mut seed = 0x5146_7557_554f_4159_u64;
881 let mut next = || {
882 seed ^= seed << 13;
883 seed ^= seed >> 7;
884 seed ^= seed << 17;
885 f64::from_bits(seed & 0x7fff_ffff_ffff_ffff)
886 };
887 let mut checked = 0;
888 for _ in 0..4_000 {
889 let baseline = next();
890 let observed = next();
891 if !baseline.is_finite() || !observed.is_finite() {
892 continue;
893 }
894 let mut predictor = ConformalPredictor::new(ConformalConfig {
895 alpha: 0.5,
896 min_samples: 1,
897 window_size: 1,
898 ..Default::default()
899 })
900 .expect("valid config");
901 let key = test_key(80, 24);
902 assert!(
903 predictor
904 .observe(key, baseline, observed)
905 .residual
906 .is_some()
907 );
908 let prediction = predictor.predict(key, baseline, f64::MAX);
909 if let Some(upper) = prediction.upper_us {
910 assert!(
911 upper >= observed,
912 "{baseline:?}, {observed:?}: {prediction:?}"
913 );
914 } else {
915 assert_eq!(prediction.status, ConformalStatus::ArithmeticOverflow);
916 assert!(prediction.risk);
917 assert!(prediction.confidence.is_none());
918 }
919 checked += 1;
920 }
921 assert!(checked > 3_900, "finite input denominator: {checked}");
922 }
923
924 #[test]
925 fn directed_addition_preserves_exact_values_and_rounds_ties_outward() {
926 let half_ulp = 2.0_f64.powi(-53);
927 let tiny = f64::from_bits(1);
928 for (a, b, expected) in [
929 (1.0, half_ulp, 1.0_f64.next_up()),
930 (1.0_f64.next_up(), half_ulp, 1.0 + 2.0_f64.powi(-51)),
931 (-1.0, -half_ulp, -1.0),
932 ((-1.0_f64).next_down(), -half_ulp, (-1.0_f64).next_down()),
933 (f64::MAX, 0.0, f64::MAX),
934 (f64::MAX, -1.0, f64::MAX),
935 (f64::MAX, 1.0, f64::INFINITY),
936 (f64::MAX, -f64::MAX, 0.0),
937 (tiny, 2.0 * tiny, 3.0 * tiny),
938 (f64::MIN_POSITIVE, -tiny, f64::MIN_POSITIVE.next_down()),
939 (1.0, -1.0, 0.0),
940 ] {
941 assert_eq!(add_up(a, b), expected, "{a:?} + {b:?}");
942 assert_eq!(add_up(b, a), expected, "{b:?} + {a:?}");
943 }
944 }
945
946 #[test]
947 fn finite_json_numbers_preserve_fractional_bounds() {
948 for value in [10.001, 10.001_f64.next_up(), 0.995, 1.005] {
949 let json = finite_json_number(Some(value), 1);
950 assert_eq!(json.parse::<f64>().expect("number"), value, "{json}");
953 }
954 }
955
956 #[test]
957 fn seeded_independent_trials_cover_exchangeable_data_but_not_drift() {
958 let mut seed = 0x6a09_e667_f3bc_c909_u64;
961 let mut uniform = || {
962 seed ^= seed << 13;
963 seed ^= seed >> 7;
964 seed ^= seed << 17;
965 (seed >> 11) as f64 / (1_u64 << 53) as f64
966 };
967 let key = test_key(80, 24);
968 let trials = 4000;
969 let mut covered = 0;
970 let mut drift_covered = 0;
971 for _ in 0..trials {
972 let mut predictor = ConformalPredictor::new(ConformalConfig {
973 alpha: 0.125,
974 min_samples: 15,
975 window_size: 31,
976 q_default: 0.0,
977 })
978 .expect("valid config");
979 for _ in 0..31 {
980 predictor.observe(key, 0.0, uniform());
981 }
982 let prediction = predictor.predict(key, 0.0, 2.0);
983 let upper = prediction.upper_us.expect("rank28 is available");
984 let held_out = uniform();
985 covered += usize::from(held_out <= upper);
986 drift_covered += usize::from(held_out + 1.0 <= upper);
987 }
988 let target = 28.0 / 32.0;
989 let mean = covered as f64 / trials as f64;
990 let six_sigma = 6.0 * (target * (1.0 - target) / trials as f64).sqrt();
991 eprintln!(
992 "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}"
993 );
994 assert!(
995 (mean - target).abs() <= six_sigma,
996 "coverage={mean}, expected={target}, six_sigma={six_sigma}, seed=0x6a09e667f3bcc909"
997 );
998 assert_eq!(
999 drift_covered, 0,
1000 "a disjoint shifted population violates exchangeability"
1001 );
1002 }
1003
1004 #[test]
1005 fn fallback_hierarchy_mode_diff() {
1006 let mut predictor = ConformalPredictor::new(ConformalConfig {
1007 alpha: 0.1,
1008 min_samples: 4,
1009 window_size: 16,
1010 q_default: 0.0,
1011 })
1012 .expect("valid config");
1013
1014 let key_a = test_key(80, 24);
1015 for value in [1.0, 2.0, 3.0, 4.0] {
1016 predictor.observe(key_a, 0.0, value);
1017 }
1018
1019 let key_b = test_key(120, 40);
1020 let decision = predictor.predict(key_b, 0.0, 1_000.0);
1021 assert_eq!(decision.fallback_level, 1);
1022 assert_eq!(decision.sample_count, 4);
1023 }
1024
1025 #[test]
1026 fn fallback_hierarchy_mode_only() {
1027 let mut predictor = ConformalPredictor::new(ConformalConfig {
1028 alpha: 0.1,
1029 min_samples: 3,
1030 window_size: 16,
1031 q_default: 0.0,
1032 })
1033 .expect("valid config");
1034
1035 let key_dirty = BucketKey::from_context(
1036 ScreenMode::Inline { ui_height: 4 },
1037 DiffStrategy::DirtyRows,
1038 80,
1039 24,
1040 );
1041 for value in [10.0, 20.0, 30.0] {
1042 predictor.observe(key_dirty, 0.0, value);
1043 }
1044
1045 let key_full = BucketKey::from_context(
1046 ScreenMode::Inline { ui_height: 4 },
1047 DiffStrategy::Full,
1048 120,
1049 40,
1050 );
1051 let decision = predictor.predict(key_full, 0.0, 1_000.0);
1052 assert_eq!(decision.fallback_level, 2);
1053 assert_eq!(decision.sample_count, 3);
1054 }
1055
1056 #[test]
1057 fn window_enforced() {
1058 let mut predictor = ConformalPredictor::new(ConformalConfig {
1059 alpha: 0.1,
1060 min_samples: 1,
1061 window_size: 3,
1062 q_default: 0.0,
1063 })
1064 .expect("valid config");
1065 let key = test_key(80, 24);
1066 for value in [1.0, 2.0, 3.0, 4.0, 5.0] {
1067 predictor.observe(key, 0.0, value);
1068 }
1069 assert_eq!(predictor.bucket_samples(key), 3);
1070 }
1071
1072 #[test]
1073 fn predict_uses_default_when_empty() {
1074 let predictor = ConformalPredictor::new(ConformalConfig {
1075 alpha: 0.1,
1076 min_samples: 2,
1077 window_size: 4,
1078 q_default: 42.0,
1079 })
1080 .expect("valid config");
1081 let key = test_key(120, 40);
1082 let prediction = predictor.predict(key, 5.0, 10_000.0);
1083 assert_eq!(prediction.quantile, None);
1084 assert_eq!(prediction.upper_us, None);
1085 assert_eq!(prediction.warmup_upper_us, Some(47.0));
1086 assert_eq!(prediction.sample_count, 0);
1087 assert_eq!(prediction.fallback_level, 3);
1088 }
1089
1090 #[test]
1091 fn bucket_isolation_by_size() {
1092 let mut predictor = ConformalPredictor::new(ConformalConfig {
1093 alpha: 0.2,
1094 min_samples: 2,
1095 window_size: 10,
1096 q_default: 0.0,
1097 })
1098 .expect("valid config");
1099
1100 let small = test_key(40, 10);
1101 predictor.observe(small, 0.0, 1.0);
1102 predictor.observe(small, 0.0, 2.0);
1103
1104 let large = test_key(200, 60);
1105 predictor.observe(large, 0.0, 10.0);
1106 predictor.observe(large, 0.0, 12.0);
1107
1108 let prediction = predictor.predict(large, 0.0, 1_000.0);
1109 assert_eq!(prediction.fallback_level, 0);
1110 assert_eq!(prediction.sample_count, 2);
1111 assert_eq!(prediction.quantile, None);
1112 assert_eq!(prediction.required_rank, 3);
1113 for value in [11.0, 9.0] {
1114 predictor.observe(large, 0.0, value);
1115 }
1116 assert_eq!(predictor.predict(large, 0.0, 1_000.0).quantile, Some(12.0));
1117 }
1118
1119 #[test]
1120 fn reset_clears_bucket_and_raises_reset_count() {
1121 let mut predictor = ConformalPredictor::new(ConformalConfig {
1122 alpha: 0.1,
1123 min_samples: 1,
1124 window_size: 8,
1125 q_default: 7.0,
1126 })
1127 .expect("valid config");
1128 let key = test_key(80, 24);
1129 predictor.observe(key, 0.0, 3.0);
1130 assert_eq!(predictor.bucket_samples(key), 1);
1131
1132 predictor.reset_bucket(key);
1133 assert_eq!(predictor.bucket_samples(key), 0);
1134
1135 let prediction = predictor.predict(key, 0.0, 1_000.0);
1136 assert_eq!(prediction.quantile, None);
1137 assert_eq!(prediction.warmup_upper_us, Some(7.0));
1138 assert_eq!(prediction.reset_count, 1);
1139 }
1140
1141 #[test]
1142 fn reset_all_forces_conservative_fallback() {
1143 let mut predictor = ConformalPredictor::new(ConformalConfig {
1144 alpha: 0.1,
1145 min_samples: 1,
1146 window_size: 8,
1147 q_default: 9.0,
1148 })
1149 .expect("valid config");
1150 let key = test_key(80, 24);
1151 predictor.observe(key, 0.0, 2.0);
1152
1153 predictor.reset_all();
1154 let prediction = predictor.predict(key, 0.0, 1_000.0);
1155 assert_eq!(prediction.quantile, None);
1156 assert_eq!(prediction.warmup_upper_us, Some(9.0));
1157 assert_eq!(prediction.sample_count, 0);
1158 assert_eq!(prediction.fallback_level, 3);
1159 assert_eq!(prediction.reset_count, 1);
1160 }
1161
1162 #[test]
1163 fn size_bucket_log2_area() {
1164 let a = size_bucket(8, 8); let b = size_bucket(8, 16); assert_eq!(a, 6);
1167 assert_eq!(b, 7);
1168 }
1169
1170 #[test]
1173 fn size_bucket_zero_area() {
1174 assert_eq!(size_bucket(0, 0), 0);
1175 assert_eq!(size_bucket(0, 24), 0);
1176 assert_eq!(size_bucket(80, 0), 0);
1177 }
1178
1179 #[test]
1180 fn size_bucket_one_by_one() {
1181 assert_eq!(size_bucket(1, 1), 0); }
1183
1184 #[test]
1185 fn size_bucket_typical_terminals() {
1186 let b80 = size_bucket(80, 24); let b120 = size_bucket(120, 40); assert_eq!(b80, 10);
1189 assert_eq!(b120, 12);
1190 }
1191
1192 #[test]
1195 fn conformal_quantile_empty() {
1196 let mut data: Vec<f64> = vec![];
1197 assert_eq!(conformal_quantile(0.1, &mut data), None);
1198 }
1199
1200 #[test]
1201 fn conformal_quantile_single_element() {
1202 let mut data = vec![42.0];
1203 assert_eq!(conformal_quantile(0.1, &mut data), None);
1204 assert_eq!(conformal_quantile(0.5, &mut data), Some(42.0));
1205 }
1206
1207 #[test]
1208 fn conformal_quantile_sorted_data() {
1209 let mut data = vec![1.0, 2.0, 3.0, 4.0, 5.0];
1210 let q = conformal_quantile(0.5, &mut data);
1211 assert_eq!(q, Some(3.0));
1213 }
1214
1215 #[test]
1216 fn conformal_quantile_alpha_half() {
1217 let mut data = vec![10.0, 20.0, 30.0, 40.0];
1218 let q = conformal_quantile(0.5, &mut data);
1219 assert_eq!(q, Some(30.0));
1221 }
1222
1223 #[test]
1226 fn mode_bucket_as_str_all_variants() {
1227 assert_eq!(ModeBucket::Inline.as_str(), "inline");
1228 assert_eq!(ModeBucket::InlineAuto.as_str(), "inline_auto");
1229 assert_eq!(ModeBucket::AltScreen.as_str(), "altscreen");
1230 }
1231
1232 #[test]
1233 fn diff_bucket_as_str_all_variants() {
1234 assert_eq!(DiffBucket::Full.as_str(), "full");
1235 assert_eq!(DiffBucket::DirtyRows.as_str(), "dirty");
1236 assert_eq!(DiffBucket::FullRedraw.as_str(), "redraw");
1237 }
1238
1239 #[test]
1240 fn diff_bucket_from_strategy() {
1241 assert_eq!(DiffBucket::from(DiffStrategy::Full), DiffBucket::Full);
1242 assert_eq!(
1243 DiffBucket::from(DiffStrategy::DirtyRows),
1244 DiffBucket::DirtyRows
1245 );
1246 assert_eq!(
1247 DiffBucket::from(DiffStrategy::FullRedraw),
1248 DiffBucket::FullRedraw
1249 );
1250 }
1251
1252 #[test]
1255 fn bucket_key_display_format() {
1256 let key = BucketKey {
1257 mode: ModeBucket::AltScreen,
1258 diff: DiffBucket::DirtyRows,
1259 size_bucket: 12,
1260 };
1261 assert_eq!(format!("{key}"), "altscreen:dirty:12");
1262 }
1263
1264 #[test]
1267 fn observe_nan_residual_not_stored() {
1268 let mut predictor = ConformalPredictor::new(ConformalConfig {
1269 alpha: 0.1,
1270 min_samples: 1,
1271 window_size: 8,
1272 q_default: 5.0,
1273 })
1274 .expect("valid config");
1275 let key = test_key(80, 24);
1276 let update = predictor.observe(key, 0.0, f64::NAN);
1277 assert_eq!(update.residual, None);
1278 assert_eq!(predictor.bucket_samples(key), 0);
1279 }
1280
1281 #[test]
1282 fn observe_infinity_residual_not_stored() {
1283 let mut predictor = ConformalPredictor::new(ConformalConfig {
1284 alpha: 0.1,
1285 min_samples: 1,
1286 window_size: 8,
1287 q_default: 5.0,
1288 })
1289 .expect("valid config");
1290 let key = test_key(80, 24);
1291 predictor.observe(key, 0.0, f64::INFINITY);
1292 assert_eq!(predictor.bucket_samples(key), 0);
1293 }
1294
1295 #[test]
1301 fn is_calibrated_requires_min_samples_on_the_level_used() {
1302 let mut predictor = ConformalPredictor::new(ConformalConfig {
1303 alpha: 0.25,
1304 min_samples: 3,
1305 window_size: 8,
1306 q_default: 50_000.0,
1307 })
1308 .expect("valid config");
1309 let key = test_key(80, 24);
1310 let cold = predictor.predict(key, 16_000.0, 16_000.0);
1311 assert!(cold.risk, "q_default prior exceeds the budget");
1312 assert_eq!(cold.sample_count, 0);
1313 assert!(
1314 !predictor.is_calibrated(&cold),
1315 "no samples: not calibrated"
1316 );
1317
1318 predictor.observe(key, 0.0, 10.0);
1319 predictor.observe(key, 0.0, 12.0);
1320 let two = predictor.predict(key, 0.0, 1.0);
1321 assert_eq!(two.sample_count, 2);
1322 assert!(
1323 !predictor.is_calibrated(&two),
1324 "below min_samples: not calibrated"
1325 );
1326
1327 predictor.observe(key, 0.0, 11.0);
1328 let three = predictor.predict(key, 0.0, 1.0);
1329 assert_eq!(three.sample_count, 3);
1330 assert_eq!(three.fallback_level, 0);
1331 assert!(predictor.is_calibrated(&three));
1332 assert!(three.risk);
1333
1334 let other = predictor.predict(test_key(200, 60), 0.0, 1.0);
1337 assert!(other.fallback_level >= 1);
1338 assert!(predictor.is_calibrated(&other));
1339 }
1340
1341 #[test]
1342 fn prediction_risk_flag() {
1343 let predictor = ConformalPredictor::new(ConformalConfig {
1344 alpha: 0.1,
1345 min_samples: 1,
1346 window_size: 8,
1347 q_default: 50.0,
1348 })
1349 .expect("valid config");
1350 let key = test_key(80, 24);
1351 let p = predictor.predict(key, 0.0, 100.0);
1353 assert!(!p.risk); let p2 = predictor.predict(key, 0.0, 30.0);
1355 assert!(p2.risk); }
1357
1358 #[test]
1359 fn prediction_confidence() {
1360 let mut predictor = ConformalPredictor::new(ConformalConfig {
1361 alpha: 0.05,
1362 min_samples: 1,
1363 window_size: 32,
1364 q_default: 0.0,
1365 })
1366 .expect("valid config");
1367 let key = test_key(80, 24);
1368 let p = predictor.predict(key, 0.0, 100.0);
1369 assert_eq!(p.confidence, None);
1370 for _ in 0..20 {
1371 predictor.observe(key, 0.0, 1.0);
1372 }
1373 assert_eq!(predictor.predict(key, 0.0, 100.0).confidence, Some(0.95));
1374 }
1375
1376 #[test]
1379 fn global_fallback_with_data() {
1380 let mut predictor = ConformalPredictor::new(ConformalConfig {
1381 alpha: 0.1,
1382 min_samples: 100, window_size: 256,
1384 q_default: 999.0,
1385 })
1386 .expect("valid config");
1387 let alt_key = BucketKey::from_context(ScreenMode::AltScreen, DiffStrategy::Full, 80, 24);
1389 predictor.observe(alt_key, 0.0, 5.0);
1390
1391 let inline_key = test_key(80, 24);
1392 let p = predictor.predict(inline_key, 0.0, 1000.0);
1393 assert_eq!(p.fallback_level, 3);
1395 assert_eq!(p.sample_count, 1);
1396 assert_eq!(p.quantile, None);
1397 assert_eq!(p.warmup_upper_us, Some(5.0));
1398 }
1399
1400 #[test]
1403 fn mode_bucket_from_screen_modes() {
1404 assert_eq!(
1405 ModeBucket::from_screen_mode(ScreenMode::Inline { ui_height: 4 }),
1406 ModeBucket::Inline
1407 );
1408 assert_eq!(
1409 ModeBucket::from_screen_mode(ScreenMode::InlineAuto {
1410 min_height: 4,
1411 max_height: 24
1412 }),
1413 ModeBucket::InlineAuto
1414 );
1415 assert_eq!(
1416 ModeBucket::from_screen_mode(ScreenMode::AltScreen),
1417 ModeBucket::AltScreen
1418 );
1419 }
1420
1421 #[test]
1424 fn config_defaults() {
1425 let config = ConformalConfig::default();
1426 assert!((config.alpha - 0.05).abs() < 1e-10);
1427 assert_eq!(config.min_samples, 20);
1428 assert_eq!(config.window_size, 256);
1429 assert!((config.q_default - 10_000.0).abs() < 1e-10);
1430 }
1431
1432 #[test]
1433 fn predictor_config_accessor() {
1434 let config = ConformalConfig {
1435 alpha: 0.2,
1436 min_samples: 5,
1437 window_size: 32,
1438 q_default: 100.0,
1439 };
1440 let predictor = ConformalPredictor::new(config).expect("valid config");
1441 assert!((predictor.config().alpha - 0.2).abs() < 1e-10);
1442 assert_eq!(predictor.config().min_samples, 5);
1443 }
1444
1445 #[test]
1448 fn negative_residual_clamped_in_prediction() {
1449 let mut predictor = ConformalPredictor::new(ConformalConfig {
1450 alpha: 0.5,
1451 min_samples: 1,
1452 window_size: 8,
1453 q_default: 0.0,
1454 })
1455 .expect("valid config");
1456 let key = test_key(80, 24);
1457 predictor.observe(key, 10.0, 5.0);
1459 let p = predictor.predict(key, 10.0, 100.0);
1460 assert_eq!(p.quantile, Some(-5.0));
1463 assert_eq!(p.upper_us, Some(10.0));
1464 }
1465
1466 #[test]
1469 fn observe_returns_correct_update() {
1470 let mut predictor = ConformalPredictor::new(ConformalConfig {
1471 alpha: 0.1,
1472 min_samples: 1,
1473 window_size: 8,
1474 q_default: 0.0,
1475 })
1476 .expect("valid config");
1477 let key = test_key(80, 24);
1478 let update = predictor.observe(key, 3.0, 10.0);
1479 assert_eq!(update.residual, Some(7.0));
1480 assert_eq!(update.bucket, key);
1481 assert_eq!(update.sample_count, 1);
1482 }
1483
1484 #[test]
1487 fn prediction_preserves_yhat_and_budget() {
1488 let predictor = ConformalPredictor::new(ConformalConfig::default()).expect("valid config");
1489 let key = test_key(80, 24);
1490 let p = predictor.predict(key, 42.5, 16666.0);
1491 assert!((p.y_hat - 42.5).abs() < 1e-10);
1492 assert!((p.budget_us - 16666.0).abs() < 1e-10);
1493 }
1494
1495 #[test]
1498 fn predict_emits_conformal_predict_span() {
1499 use std::sync::Arc;
1500 use std::sync::atomic::{AtomicBool, Ordering};
1501
1502 struct SpanChecker {
1503 saw_conformal_predict: Arc<AtomicBool>,
1504 }
1505
1506 impl tracing::Subscriber for SpanChecker {
1507 fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
1508 true
1509 }
1510 fn new_span(&self, span: &tracing::span::Attributes<'_>) -> tracing::span::Id {
1511 if span.metadata().name() == "conformal.predict" {
1512 self.saw_conformal_predict.store(true, Ordering::Relaxed);
1513 }
1514 tracing::span::Id::from_u64(1)
1515 }
1516 fn record(&self, _span: &tracing::span::Id, _values: &tracing::span::Record<'_>) {}
1517 fn record_follows_from(&self, _span: &tracing::span::Id, _follows: &tracing::span::Id) {
1518 }
1519 fn event(&self, _event: &tracing::Event<'_>) {}
1520 fn enter(&self, _span: &tracing::span::Id) {}
1521 fn exit(&self, _span: &tracing::span::Id) {}
1522 }
1523
1524 let saw_it = Arc::new(AtomicBool::new(false));
1525 let subscriber = SpanChecker {
1526 saw_conformal_predict: Arc::clone(&saw_it),
1527 };
1528 let _guard = tracing::subscriber::set_default(subscriber);
1529
1530 let predictor = ConformalPredictor::new(ConformalConfig::default()).expect("valid config");
1531 let key = test_key(80, 24);
1532 let _ = predictor.predict(key, 100.0, 16666.0);
1533
1534 assert!(
1535 saw_it.load(Ordering::Relaxed),
1536 "predict() must emit a 'conformal.predict' tracing span"
1537 );
1538 }
1539
1540 #[test]
1541 fn predict_span_records_gate_triggered_true() {
1542 use std::sync::Arc;
1543 use std::sync::atomic::{AtomicBool, Ordering};
1544
1545 struct GateChecker {
1546 saw_gate_true: Arc<AtomicBool>,
1547 }
1548
1549 struct GateVisitor(Arc<AtomicBool>);
1550
1551 impl tracing::field::Visit for GateVisitor {
1552 fn record_bool(&mut self, field: &tracing::field::Field, value: bool) {
1553 if field.name() == "gate_triggered" && value {
1554 self.0.store(true, Ordering::Relaxed);
1555 }
1556 }
1557 fn record_debug(&mut self, _field: &tracing::field::Field, _value: &dyn fmt::Debug) {}
1558 }
1559
1560 impl tracing::Subscriber for GateChecker {
1561 fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
1562 true
1563 }
1564 fn new_span(&self, _span: &tracing::span::Attributes<'_>) -> tracing::span::Id {
1565 tracing::span::Id::from_u64(1)
1566 }
1567 fn record(&self, _span: &tracing::span::Id, values: &tracing::span::Record<'_>) {
1568 let mut visitor = GateVisitor(Arc::clone(&self.saw_gate_true));
1569 values.record(&mut visitor);
1570 }
1571 fn record_follows_from(&self, _span: &tracing::span::Id, _follows: &tracing::span::Id) {
1572 }
1573 fn event(&self, _event: &tracing::Event<'_>) {}
1574 fn enter(&self, _span: &tracing::span::Id) {}
1575 fn exit(&self, _span: &tracing::span::Id) {}
1576 }
1577
1578 let saw_gate = Arc::new(AtomicBool::new(false));
1579 let subscriber = GateChecker {
1580 saw_gate_true: Arc::clone(&saw_gate),
1581 };
1582 let _guard = tracing::subscriber::set_default(subscriber);
1583
1584 let predictor = ConformalPredictor::new(ConformalConfig {
1585 alpha: 0.1,
1586 min_samples: 1,
1587 window_size: 8,
1588 q_default: 50_000.0, })
1590 .expect("valid config");
1591 let key = test_key(80, 24);
1592 let p = predictor.predict(key, 0.0, 100.0);
1594 assert!(p.risk, "prediction should be risky");
1595 assert!(
1596 saw_gate.load(Ordering::Relaxed),
1597 "predict() must record gate_triggered=true when risk"
1598 );
1599 }
1600
1601 #[test]
1608 fn calibration_uniform_distribution_quantile() {
1609 let mut predictor = ConformalPredictor::new(ConformalConfig {
1612 alpha: 0.05,
1613 min_samples: 1,
1614 window_size: 256,
1615 q_default: 0.0,
1616 })
1617 .expect("valid config");
1618 let key = test_key(80, 24);
1619 for i in 0..100 {
1620 predictor.observe(key, 0.0, i as f64);
1621 }
1622 let p = predictor.predict(key, 0.0, 1_000.0);
1623 assert_eq!(p.fallback_level, 0);
1625 assert_eq!(p.sample_count, 100);
1626 assert_eq!(p.quantile, Some(95.0));
1627 }
1628
1629 #[test]
1630 fn calibration_gaussian_like_distribution() {
1631 let mut predictor = ConformalPredictor::new(ConformalConfig {
1635 alpha: 0.1,
1636 min_samples: 1,
1637 window_size: 256,
1638 q_default: 0.0,
1639 })
1640 .expect("valid config");
1641 let key = test_key(120, 40);
1642
1643 for i in 0..50 {
1646 let residual = (i as f64) - 24.5;
1647 predictor.observe(key, 100.0, 100.0 + residual);
1648 }
1649
1650 let p = predictor.predict(key, 100.0, 1_000.0);
1651 assert_eq!(p.fallback_level, 0);
1654 assert_eq!(p.sample_count, 50);
1655 assert_eq!(p.quantile, Some(20.5));
1656 assert_eq!(p.upper_us, Some(120.5));
1658 }
1659
1660 #[test]
1661 fn calibration_constant_residuals() {
1662 let mut predictor = ConformalPredictor::new(ConformalConfig {
1664 alpha: 0.05,
1665 min_samples: 1,
1666 window_size: 256,
1667 q_default: 0.0,
1668 })
1669 .expect("valid config");
1670 let key = test_key(80, 24);
1671 for _ in 0..30 {
1672 predictor.observe(key, 100.0, 105.0); }
1674 let p = predictor.predict(key, 100.0, 1_000.0);
1675 assert_eq!(p.quantile, Some(5.0));
1676 assert_eq!(p.upper_us, Some(105.0));
1677 }
1678
1679 #[test]
1682 fn quantile_covers_expected_fraction_of_uniform_grid() {
1683 let alpha = 0.1;
1686 let n_calibrate = 100;
1687 let n_test = 200;
1688
1689 let mut predictor = ConformalPredictor::new(ConformalConfig {
1690 alpha,
1691 min_samples: 1,
1692 window_size: 256,
1693 q_default: 0.0,
1694 })
1695 .expect("valid config");
1696 let key = test_key(80, 24);
1697
1698 for i in 0..n_calibrate {
1700 predictor.observe(key, 0.0, i as f64);
1701 }
1702
1703 let prediction = predictor.predict(key, 0.0, f64::MAX);
1706 let upper_bound = prediction.upper_us.expect("attainable rank");
1707
1708 let mut covered = 0;
1709 for i in 0..n_test {
1711 let new_obs = (i as f64) * (n_calibrate as f64) / (n_test as f64);
1712 if new_obs <= upper_bound {
1713 covered += 1;
1714 }
1715 }
1716
1717 let empirical_coverage = covered as f64 / n_test as f64;
1718 let target_coverage = 1.0 - alpha - 0.05; assert!(
1722 empirical_coverage >= target_coverage,
1723 "Empirical coverage {empirical_coverage:.3} should be >= {target_coverage:.3}"
1724 );
1725 }
1726
1727 #[test]
1728 fn quantile_covers_expected_fraction_of_calibration_grid() {
1729 let alpha = 0.05;
1732 let n = 200;
1733
1734 let mut predictor = ConformalPredictor::new(ConformalConfig {
1735 alpha,
1736 min_samples: 1,
1737 window_size: 512,
1738 q_default: 0.0,
1739 })
1740 .expect("valid config");
1741 let key = test_key(80, 24);
1742
1743 for i in 1..=n {
1745 predictor.observe(key, 0.0, i as f64);
1746 }
1747
1748 let p = predictor.predict(key, 0.0, f64::MAX);
1749 assert_eq!(p.quantile, Some(191.0));
1751 let upper = p.upper_us.expect("attainable rank");
1753 let covered = (1..=n).filter(|&i| (i as f64) <= upper).count();
1754 let coverage = covered as f64 / n as f64;
1755 assert!(
1756 coverage >= 1.0 - alpha,
1757 "Coverage {coverage:.3} should be >= {:.3}",
1758 1.0 - alpha
1759 );
1760 }
1761
1762 #[test]
1765 fn gate_trigger_exact_boundary() {
1766 let mut predictor = ConformalPredictor::new(ConformalConfig {
1768 alpha: 0.5,
1769 min_samples: 1,
1770 window_size: 8,
1771 q_default: 0.0,
1772 })
1773 .expect("valid config");
1774 let key = test_key(80, 24);
1775 predictor.observe(key, 0.0, 50.0);
1776 let p = predictor.predict(key, 0.0, 50.0);
1778 assert!(
1779 !p.risk,
1780 "upper_us ({:?}) == budget_us ({}) should NOT trigger risk",
1781 p.upper_us, p.budget_us
1782 );
1783 }
1784
1785 #[test]
1786 fn gate_trigger_just_above_boundary() {
1787 let mut predictor = ConformalPredictor::new(ConformalConfig {
1789 alpha: 0.5,
1790 min_samples: 1,
1791 window_size: 8,
1792 q_default: 0.0,
1793 })
1794 .expect("valid config");
1795 let key = test_key(80, 24);
1796 predictor.observe(key, 0.0, 50.0);
1797 let p = predictor.predict(key, 0.0, 49.999);
1799 assert!(p.risk, "upper_us > budget should trigger risk");
1800 }
1801
1802 #[test]
1803 fn gate_trigger_just_below_boundary() {
1804 let mut predictor = ConformalPredictor::new(ConformalConfig {
1806 alpha: 0.5,
1807 min_samples: 1,
1808 window_size: 8,
1809 q_default: 0.0,
1810 })
1811 .expect("valid config");
1812 let key = test_key(80, 24);
1813 predictor.observe(key, 0.0, 50.0);
1814 let p = predictor.predict(key, 0.0, 50.001);
1816 assert!(!p.risk, "upper_us < budget should NOT trigger risk");
1817 }
1818
1819 #[test]
1820 fn gate_trigger_zero_budget() {
1821 let predictor = ConformalPredictor::new(ConformalConfig {
1823 alpha: 0.1,
1824 min_samples: 1,
1825 window_size: 8,
1826 q_default: 1.0,
1827 })
1828 .expect("valid config");
1829 let key = test_key(80, 24);
1830 let p = predictor.predict(key, 0.0, 0.0);
1831 assert!(p.risk, "positive upper_us with zero budget should be risky");
1832 }
1833
1834 #[test]
1835 fn gate_trigger_very_large_budget() {
1836 let predictor = ConformalPredictor::new(ConformalConfig {
1838 alpha: 0.1,
1839 min_samples: 1,
1840 window_size: 8,
1841 q_default: 100_000.0,
1842 })
1843 .expect("valid config");
1844 let key = test_key(80, 24);
1845 let p = predictor.predict(key, 1_000.0, f64::MAX);
1846 assert!(!p.risk, "huge budget should never trigger risk");
1847 }
1848
1849 #[test]
1852 fn alpha_sensitivity_wider_interval_with_lower_alpha() {
1853 let key = test_key(80, 24);
1854
1855 let mut predictor_tight = ConformalPredictor::new(ConformalConfig {
1857 alpha: 0.5, min_samples: 1,
1859 window_size: 256,
1860 q_default: 0.0,
1861 })
1862 .expect("valid config");
1863
1864 let mut predictor_wide = ConformalPredictor::new(ConformalConfig {
1865 alpha: 0.01, min_samples: 1,
1867 window_size: 256,
1868 q_default: 0.0,
1869 })
1870 .expect("valid config");
1871
1872 for i in 0..100 {
1873 let obs = i as f64;
1874 predictor_tight.observe(key, 0.0, obs);
1875 predictor_wide.observe(key, 0.0, obs);
1876 }
1877
1878 let p_tight = predictor_tight.predict(key, 0.0, 10_000.0);
1879 let p_wide = predictor_wide.predict(key, 0.0, 10_000.0);
1880
1881 assert!(
1882 p_wide.quantile.expect("attainable rank") > p_tight.quantile.expect("attainable rank"),
1883 "Lower alpha ({}) should produce wider interval: quantile {:?} vs {:?}",
1884 0.01,
1885 p_wide.quantile,
1886 p_tight.quantile
1887 );
1888 assert!(
1889 p_wide.upper_us.expect("attainable rank") > p_tight.upper_us.expect("attainable rank"),
1890 "Lower alpha should produce higher upper bound"
1891 );
1892 }
1893
1894 #[test]
1895 fn alpha_sensitivity_confidence_reflects_alpha() {
1896 for &alpha in &[0.01, 0.05, 0.1, 0.2, 0.5] {
1897 let mut predictor = ConformalPredictor::new(ConformalConfig {
1898 alpha,
1899 min_samples: 1,
1900 window_size: 128,
1901 q_default: 0.0,
1902 })
1903 .expect("valid config");
1904 let key = test_key(80, 24);
1905 let p = predictor.predict(key, 0.0, 1_000.0);
1906 assert_eq!(p.alpha, alpha);
1907 assert_eq!(p.confidence, None);
1908 for _ in 0..100 {
1909 predictor.observe(key, 0.0, 1.0);
1910 }
1911 let p = predictor.predict(key, 0.0, 1_000.0);
1912 let expected_confidence = 1.0 - alpha;
1913 assert!(
1914 (p.confidence.expect("attainable rank") - expected_confidence).abs() < 1e-10,
1915 "confidence should be 1-alpha for alpha={alpha}"
1916 );
1917 }
1918 }
1919
1920 #[test]
1921 fn alpha_sensitivity_extreme_alpha_zero() {
1922 let mut predictor = ConformalPredictor::new(ConformalConfig {
1924 alpha: 0.001,
1925 min_samples: 1,
1926 window_size: 256,
1927 q_default: 0.0,
1928 })
1929 .expect("valid config");
1930 let key = test_key(80, 24);
1931 for i in 0..100 {
1932 predictor.observe(key, 0.0, i as f64);
1933 }
1934 let p = predictor.predict(key, 0.0, 10_000.0);
1935 assert_eq!(p.required_rank, 101);
1936 assert_eq!(p.quantile, None);
1937 assert_eq!(p.upper_us, None);
1938 assert_eq!(p.status, ConformalStatus::UnattainableRank);
1939 }
1940
1941 #[test]
1942 fn alpha_sensitivity_extreme_alpha_one() {
1943 let mut predictor = ConformalPredictor::new(ConformalConfig {
1945 alpha: 0.99,
1946 min_samples: 1,
1947 window_size: 256,
1948 q_default: 0.0,
1949 })
1950 .expect("valid config");
1951 let key = test_key(80, 24);
1952 for i in 0..100 {
1953 predictor.observe(key, 0.0, i as f64);
1954 }
1955 let p = predictor.predict(key, 0.0, 10_000.0);
1956 assert_eq!(p.quantile, Some(1.0));
1958 }
1959
1960 #[test]
1963 fn empty_calibration_uses_default() {
1964 let predictor = ConformalPredictor::new(ConformalConfig {
1965 alpha: 0.05,
1966 min_samples: 20,
1967 window_size: 256,
1968 q_default: 10_000.0,
1969 })
1970 .expect("valid config");
1971 let key = test_key(80, 24);
1972 let p = predictor.predict(key, 100.0, 16_666.0);
1973 assert_eq!(p.sample_count, 0);
1974 assert_eq!(p.fallback_level, 3);
1975 assert_eq!(p.quantile, None);
1976 assert_eq!(p.upper_us, None);
1977 assert_eq!(p.warmup_upper_us, Some(10_100.0));
1978 }
1979
1980 #[test]
1981 fn one_sample_below_min_samples_uses_fallback() {
1982 let mut predictor = ConformalPredictor::new(ConformalConfig {
1984 alpha: 0.05,
1985 min_samples: 20,
1986 window_size: 256,
1987 q_default: 999.0,
1988 })
1989 .expect("valid config");
1990 let key = test_key(80, 24);
1991 predictor.observe(key, 0.0, 5.0);
1992 let p = predictor.predict(key, 0.0, 1_000.0);
1993 assert_eq!(p.fallback_level, 3);
1996 assert_eq!(p.sample_count, 1);
1997 }
1998
1999 #[test]
2000 fn exactly_min_samples_minus_one_uses_fallback() {
2001 let min_samples = 5;
2002 let mut predictor = ConformalPredictor::new(ConformalConfig {
2003 alpha: 0.1,
2004 min_samples,
2005 window_size: 256,
2006 q_default: 999.0,
2007 })
2008 .expect("valid config");
2009 let key = test_key(80, 24);
2010 for i in 0..(min_samples - 1) {
2011 predictor.observe(key, 0.0, (i as f64) * 10.0);
2012 }
2013 let p = predictor.predict(key, 0.0, 1_000.0);
2014 assert_eq!(p.fallback_level, 3);
2017 assert_eq!(p.sample_count, min_samples - 1);
2018 }
2019
2020 #[test]
2021 fn exactly_min_samples_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);
2037 assert_eq!(p.sample_count, min_samples);
2038 }
2039
2040 #[test]
2041 fn min_samples_plus_one_uses_exact_bucket() {
2042 let min_samples = 5;
2043 let mut predictor = ConformalPredictor::new(ConformalConfig {
2044 alpha: 0.1,
2045 min_samples,
2046 window_size: 256,
2047 q_default: 999.0,
2048 })
2049 .expect("valid config");
2050 let key = test_key(80, 24);
2051 for i in 0..=min_samples {
2052 predictor.observe(key, 0.0, (i as f64) * 10.0);
2053 }
2054 let p = predictor.predict(key, 0.0, 1_000.0);
2055 assert_eq!(p.fallback_level, 0);
2056 assert_eq!(p.sample_count, min_samples + 1);
2057 }
2058
2059 #[test]
2060 fn min_samples_one_allows_single_observation() {
2061 let mut predictor = ConformalPredictor::new(ConformalConfig {
2063 alpha: 0.1,
2064 min_samples: 1,
2065 window_size: 256,
2066 q_default: 999.0,
2067 })
2068 .expect("valid config");
2069 let key = test_key(80, 24);
2070 predictor.observe(key, 0.0, 42.0);
2071 let p = predictor.predict(key, 0.0, 1_000.0);
2072 assert_eq!(p.fallback_level, 0);
2073 assert_eq!(p.sample_count, 1);
2074 assert_eq!(p.quantile, None);
2075 assert_eq!(p.status, ConformalStatus::UnattainableRank);
2076 }
2077
2078 #[test]
2081 fn predict_span_records_calibration_set_size() {
2082 use std::sync::Arc;
2083 use std::sync::Mutex;
2084
2085 struct FieldRecorder {
2086 calibration_size: Arc<Mutex<Option<u64>>>,
2087 }
2088
2089 struct SizeVisitor(Arc<Mutex<Option<u64>>>);
2090
2091 impl tracing::field::Visit for SizeVisitor {
2092 fn record_u64(&mut self, field: &tracing::field::Field, value: u64) {
2093 if field.name() == "calibration_set_size" {
2094 *self.0.lock().unwrap() = Some(value);
2095 }
2096 }
2097 fn record_debug(&mut self, _field: &tracing::field::Field, _value: &dyn fmt::Debug) {}
2098 }
2099
2100 impl tracing::Subscriber for FieldRecorder {
2101 fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
2102 true
2103 }
2104 fn new_span(&self, _span: &tracing::span::Attributes<'_>) -> tracing::span::Id {
2105 tracing::span::Id::from_u64(1)
2106 }
2107 fn record(&self, _span: &tracing::span::Id, values: &tracing::span::Record<'_>) {
2108 let mut v = SizeVisitor(Arc::clone(&self.calibration_size));
2109 values.record(&mut v);
2110 }
2111 fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
2112 fn event(&self, _: &tracing::Event<'_>) {}
2113 fn enter(&self, _: &tracing::span::Id) {}
2114 fn exit(&self, _: &tracing::span::Id) {}
2115 }
2116
2117 let size = Arc::new(Mutex::new(None));
2118 let subscriber = FieldRecorder {
2119 calibration_size: Arc::clone(&size),
2120 };
2121 let _guard = tracing::subscriber::set_default(subscriber);
2122
2123 let mut predictor = ConformalPredictor::new(ConformalConfig {
2124 alpha: 0.1,
2125 min_samples: 1,
2126 window_size: 8,
2127 q_default: 0.0,
2128 })
2129 .expect("valid config");
2130 let key = test_key(80, 24);
2131 for i in 0..5 {
2132 predictor.observe(key, 0.0, i as f64);
2133 }
2134 let _ = predictor.predict(key, 0.0, 1_000.0);
2135
2136 let recorded = size.lock().unwrap();
2137 assert_eq!(*recorded, Some(5), "calibration_set_size should be 5");
2138 }
2139
2140 #[test]
2141 fn predict_span_records_predicted_upper_bound() {
2142 use std::sync::Arc;
2143 use std::sync::Mutex;
2144
2145 struct UpperBoundRecorder {
2146 upper_bound: Arc<Mutex<Option<f64>>>,
2147 }
2148
2149 struct UpperVisitor(Arc<Mutex<Option<f64>>>);
2150
2151 impl tracing::field::Visit for UpperVisitor {
2152 fn record_f64(&mut self, field: &tracing::field::Field, value: f64) {
2153 if field.name() == "predicted_upper_bound_us" {
2154 *self.0.lock().unwrap() = Some(value);
2155 }
2156 }
2157 fn record_debug(&mut self, _: &tracing::field::Field, _: &dyn fmt::Debug) {}
2158 }
2159
2160 impl tracing::Subscriber for UpperBoundRecorder {
2161 fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
2162 true
2163 }
2164 fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
2165 tracing::span::Id::from_u64(1)
2166 }
2167 fn record(&self, _: &tracing::span::Id, values: &tracing::span::Record<'_>) {
2168 let mut v = UpperVisitor(Arc::clone(&self.upper_bound));
2169 values.record(&mut v);
2170 }
2171 fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
2172 fn event(&self, _: &tracing::Event<'_>) {}
2173 fn enter(&self, _: &tracing::span::Id) {}
2174 fn exit(&self, _: &tracing::span::Id) {}
2175 }
2176
2177 let upper = Arc::new(Mutex::new(None));
2178 let subscriber = UpperBoundRecorder {
2179 upper_bound: Arc::clone(&upper),
2180 };
2181 let _guard = tracing::subscriber::set_default(subscriber);
2182
2183 let mut predictor = ConformalPredictor::new(ConformalConfig {
2184 alpha: 0.5,
2185 min_samples: 1,
2186 window_size: 8,
2187 q_default: 42.0,
2188 })
2189 .expect("valid config");
2190 let key = test_key(80, 24);
2191 let p = predictor.predict(key, 10.0, 1_000.0);
2192 assert_eq!(p.upper_us, None);
2193 assert_eq!(
2194 *upper.lock().unwrap(),
2195 None,
2196 "warmup must not emit a calibrated bound"
2197 );
2198 predictor.observe(key, 0.0, 42.0);
2199 let p = predictor.predict(key, 10.0, 1_000.0);
2200 assert_eq!(p.upper_us, Some(52.0));
2201 assert_eq!(*upper.lock().unwrap(), p.upper_us);
2202 }
2203
2204 #[test]
2205 fn predict_span_records_gate_triggered_false() {
2206 use std::sync::Arc;
2207 use std::sync::Mutex;
2208
2209 struct GateFalseChecker {
2210 gate_value: Arc<Mutex<Option<bool>>>,
2211 }
2212
2213 struct GateFalseVisitor(Arc<Mutex<Option<bool>>>);
2214
2215 impl tracing::field::Visit for GateFalseVisitor {
2216 fn record_bool(&mut self, field: &tracing::field::Field, value: bool) {
2217 if field.name() == "gate_triggered" {
2218 *self.0.lock().unwrap() = Some(value);
2219 }
2220 }
2221 fn record_debug(&mut self, _: &tracing::field::Field, _: &dyn fmt::Debug) {}
2222 }
2223
2224 impl tracing::Subscriber for GateFalseChecker {
2225 fn enabled(&self, _: &tracing::Metadata<'_>) -> bool {
2226 true
2227 }
2228 fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
2229 tracing::span::Id::from_u64(1)
2230 }
2231 fn record(&self, _: &tracing::span::Id, values: &tracing::span::Record<'_>) {
2232 let mut v = GateFalseVisitor(Arc::clone(&self.gate_value));
2233 values.record(&mut v);
2234 }
2235 fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
2236 fn event(&self, _: &tracing::Event<'_>) {}
2237 fn enter(&self, _: &tracing::span::Id) {}
2238 fn exit(&self, _: &tracing::span::Id) {}
2239 }
2240
2241 let gate = Arc::new(Mutex::new(None));
2242 let subscriber = GateFalseChecker {
2243 gate_value: Arc::clone(&gate),
2244 };
2245 let _guard = tracing::subscriber::set_default(subscriber);
2246
2247 let predictor = ConformalPredictor::new(ConformalConfig {
2248 alpha: 0.1,
2249 min_samples: 1,
2250 window_size: 8,
2251 q_default: 1.0,
2252 })
2253 .expect("valid config");
2254 let key = test_key(80, 24);
2255 let p = predictor.predict(key, 0.0, 1_000_000.0);
2256 assert!(!p.risk);
2257
2258 let recorded = gate.lock().unwrap();
2259 assert_eq!(
2260 *recorded,
2261 Some(false),
2262 "gate_triggered should be recorded as false"
2263 );
2264 }
2265
2266 #[test]
2269 fn jsonl_output_contains_required_fields() {
2270 let prediction = ConformalPrediction {
2271 upper_us: Some(150.5),
2272 risk: true,
2273 confidence: Some(0.95),
2274 alpha: 0.05,
2275 status: ConformalStatus::Calibrated,
2276 required_rank: 41,
2277 warmup_upper_us: None,
2278 bucket: BucketKey {
2279 mode: ModeBucket::Inline,
2280 diff: DiffBucket::Full,
2281 size_bucket: 10,
2282 },
2283 sample_count: 42,
2284 quantile: Some(50.5),
2285 fallback_level: 0,
2286 window_size: 256,
2287 reset_count: 1,
2288 y_hat: 100.0,
2289 budget_us: 140.0,
2290 };
2291 let jsonl = prediction.to_jsonl();
2292 assert!(jsonl.contains("\"schema\":\"conformal-v2\""));
2293 assert!(jsonl.contains("\"upper_us\":150.5"));
2294 assert!(jsonl.contains("\"risk\":true"));
2295 let parsed: serde_json::Value = serde_json::from_str(&jsonl).expect("valid JSON");
2296 assert_eq!(parsed["confidence"].as_f64(), Some(0.95));
2297 assert!(jsonl.contains("\"bucket\":\"inline:full:10\""));
2298 assert!(jsonl.contains("\"samples\":42"));
2299 assert!(jsonl.contains("\"quantile\":50.50"));
2300 assert!(jsonl.contains("\"fallback_level\":0"));
2301 assert!(jsonl.contains("\"window\":256"));
2302 assert!(jsonl.contains("\"resets\":1"));
2303 assert!(jsonl.contains("\"y_hat\":100.0"));
2304 assert!(jsonl.contains("\"budget_us\":140.0"));
2305 }
2306
2307 #[test]
2310 fn quantile_grid_fraction_for_multiple_alphas() {
2311 for alpha in [0.05, 0.1, 0.2] {
2314 let n_calibrate = 100;
2315 let n_test = 100;
2316
2317 let mut predictor = ConformalPredictor::new(ConformalConfig {
2318 alpha,
2319 min_samples: 1,
2320 window_size: 256,
2321 q_default: 0.0,
2322 })
2323 .expect("valid config");
2324 let key = test_key(80, 24);
2325
2326 for i in 1..=n_calibrate {
2328 predictor.observe(key, 0.0, i as f64);
2329 }
2330
2331 let p = predictor.predict(key, 0.0, f64::MAX);
2332
2333 let upper = p.upper_us.expect("attainable rank");
2335 let covered = (1..=n_test).filter(|&i| (i as f64) <= upper).count();
2336 let coverage = covered as f64 / n_test as f64;
2337
2338 assert!(
2339 coverage >= 1.0 - alpha - 0.02,
2340 "alpha={alpha}: coverage {coverage:.3} should be >= {:.3}",
2341 1.0 - alpha - 0.02
2342 );
2343 }
2344 }
2345
2346 #[test]
2347 fn property_monotone_quantile_with_more_extreme_data() {
2348 let key = test_key(80, 24);
2350
2351 let mut predictor = ConformalPredictor::new(ConformalConfig {
2352 alpha: 0.1,
2353 min_samples: 1,
2354 window_size: 256,
2355 q_default: 0.0,
2356 })
2357 .expect("valid config");
2358
2359 for i in 0..50 {
2361 predictor.observe(key, 0.0, i as f64);
2362 }
2363 let q_moderate = predictor
2364 .predict(key, 0.0, f64::MAX)
2365 .quantile
2366 .expect("attainable rank");
2367
2368 for _ in 0..50 {
2370 predictor.observe(key, 0.0, 1000.0);
2371 }
2372 let q_extreme = predictor
2373 .predict(key, 0.0, f64::MAX)
2374 .quantile
2375 .expect("attainable rank");
2376
2377 assert!(
2378 q_extreme >= q_moderate,
2379 "Adding extreme data should not decrease quantile: {q_extreme} vs {q_moderate}"
2380 );
2381 }
2382
2383 #[test]
2384 fn property_quantile_bounded_by_max_residual() {
2385 let key = test_key(80, 24);
2387 let mut predictor = ConformalPredictor::new(ConformalConfig {
2388 alpha: 0.001, min_samples: 1,
2390 window_size: 256,
2391 q_default: 0.0,
2392 })
2393 .expect("valid config");
2394
2395 let max_residual = 98.0;
2396 for i in 0..50 {
2397 predictor.observe(key, 0.0, (i as f64) * 2.0); }
2399
2400 let p = predictor.predict(key, 0.0, f64::MAX);
2401 assert_eq!(p.quantile, None);
2402 assert_eq!(p.status, ConformalStatus::UnattainableRank);
2403 let mut finite_predictor = ConformalPredictor::new(ConformalConfig {
2404 alpha: 0.05,
2405 ..predictor.config().clone()
2406 })
2407 .expect("valid config");
2408 for i in 0..50 {
2409 finite_predictor.observe(key, 0.0, f64::from(i) * 2.0);
2410 }
2411 let quantile = finite_predictor
2412 .predict(key, 0.0, f64::MAX)
2413 .quantile
2414 .expect("attainable rank");
2415 assert!(
2416 quantile <= max_residual,
2417 "quantile {quantile} should be <= max residual {max_residual}"
2418 );
2419 }
2420
2421 #[test]
2422 fn property_window_eviction_changes_quantile() {
2423 let key = test_key(80, 24);
2426 let window_size = 10;
2427
2428 let mut predictor = ConformalPredictor::new(ConformalConfig {
2429 alpha: 0.1,
2430 min_samples: 1,
2431 window_size,
2432 q_default: 0.0,
2433 })
2434 .expect("valid config");
2435
2436 for _ in 0..window_size {
2438 predictor.observe(key, 0.0, 1000.0);
2439 }
2440 let q_large = predictor
2441 .predict(key, 0.0, f64::MAX)
2442 .quantile
2443 .expect("attainable rank");
2444
2445 for _ in 0..window_size {
2447 predictor.observe(key, 0.0, 1.0);
2448 }
2449 let q_small = predictor
2450 .predict(key, 0.0, f64::MAX)
2451 .quantile
2452 .expect("attainable rank");
2453
2454 assert!(
2455 q_small < q_large,
2456 "After eviction, quantile should decrease: {q_small} vs {q_large}"
2457 );
2458 }
2459
2460 #[test]
2463 fn cross_mode_fallback_does_not_mix_modes() {
2464 let mut predictor = ConformalPredictor::new(ConformalConfig {
2466 alpha: 0.1,
2467 min_samples: 5,
2468 window_size: 256,
2469 q_default: 999.0,
2470 })
2471 .expect("valid config");
2472
2473 let alt_key = BucketKey::from_context(ScreenMode::AltScreen, DiffStrategy::Full, 80, 24);
2475 for i in 0..10 {
2476 predictor.observe(alt_key, 0.0, (i as f64) * 100.0);
2477 }
2478
2479 let inline_key = BucketKey::from_context(
2481 ScreenMode::Inline { ui_height: 4 },
2482 DiffStrategy::Full,
2483 120,
2484 40,
2485 );
2486 let p = predictor.predict(inline_key, 0.0, 1_000_000.0);
2487
2488 assert_eq!(
2490 p.fallback_level, 3,
2491 "Cross-mode query should fall to global"
2492 );
2493 }
2494
2495 #[test]
2496 fn reset_count_accumulates_across_resets() {
2497 let mut predictor =
2498 ConformalPredictor::new(ConformalConfig::default()).expect("valid config");
2499 let key = test_key(80, 24);
2500
2501 predictor.observe(key, 0.0, 1.0);
2502 predictor.reset_bucket(key);
2503 predictor.observe(key, 0.0, 2.0);
2504 predictor.reset_all();
2505 predictor.observe(key, 0.0, 3.0);
2506 predictor.reset_bucket(key);
2507
2508 let p = predictor.predict(key, 0.0, 1_000.0);
2509 assert_eq!(p.reset_count, 3, "reset_count should accumulate");
2510 }
2511
2512 #[test]
2521 fn default_config_matches_the_documented_values() {
2522 let config = ConformalConfig::default();
2523 assert!(
2524 (config.alpha - 0.05).abs() < f64::EPSILON,
2525 "README documents alpha = 0.05, found {}",
2526 config.alpha
2527 );
2528 assert_eq!(config.min_samples, 20, "README documents min_samples = 20");
2529 assert_eq!(config.window_size, 256, "README documents window 256");
2530 assert!(
2532 (config.q_default - 10_000.0).abs() < f64::EPSILON,
2533 "README documents q_default = 10 ms, found {} us",
2534 config.q_default
2535 );
2536 }
2537
2538 mod property_tests {
2539 use super::*;
2540 use proptest::prelude::*;
2541
2542 proptest! {
2543 #[test]
2544 fn proptest_coverage_at_least_one_minus_alpha_on_stationary_residuals(
2545 y_hat in 0.0f64..10_000.0,
2546 residuals in prop::collection::vec(-500.0f64..50_000.0, 25..60),
2547 alpha in prop::sample::select(vec![0.05f64, 0.10, 0.20, 0.25]),
2548 ) {
2549 let key = test_key(80, 24);
2550 let defaults = ConformalConfig::default();
2551 let min_samples = defaults.min_samples;
2552 let n_total = residuals.len();
2553 prop_assume!(n_total > min_samples);
2554
2555 let mut covered = 0usize;
2560 for held_out_idx in 0..n_total {
2561 let mut predictor = ConformalPredictor::new(ConformalConfig {
2562 alpha,
2563 min_samples,
2564 window_size: defaults.window_size,
2565 q_default: defaults.q_default,
2566 })
2567 .expect("valid config");
2568
2569 for (idx, &r) in residuals.iter().enumerate() {
2570 if idx != held_out_idx {
2571 let obs = (y_hat + r).max(0.0);
2572 predictor.observe(key, y_hat, obs);
2573 }
2574 }
2575
2576 let prediction = predictor.predict(key, y_hat, 16_666.0);
2577 prop_assert_eq!(prediction.status, ConformalStatus::Calibrated);
2578 prop_assert_eq!(prediction.fallback_level, 0);
2579 let upper = prediction.upper_us.expect("calibrated upper bound");
2580 let held_out_obs = (y_hat + residuals[held_out_idx]).max(0.0);
2581 if held_out_obs <= upper {
2582 covered += 1;
2583 }
2584 }
2585
2586 let coverage = covered as f64 / n_total as f64;
2587 prop_assert!(
2588 coverage + 1e-12 >= 1.0 - alpha,
2589 "empirical coverage {coverage:.4} ({covered}/{n_total}) < 1 - alpha ({:.4})",
2590 1.0 - alpha
2591 );
2592
2593 let mut rolling = ConformalPredictor::new(ConformalConfig {
2597 alpha,
2598 min_samples,
2599 window_size: defaults.window_size,
2600 q_default: defaults.q_default,
2601 })
2602 .expect("valid config");
2603
2604 for (step, &r) in residuals.iter().enumerate() {
2605 let pred = rolling.predict(key, y_hat, 16_666.0);
2606 if step < min_samples {
2607 prop_assert_eq!(pred.status, ConformalStatus::Warmup);
2608 prop_assert_eq!(pred.fallback_level, 3);
2609 prop_assert!(!rolling.is_calibrated(&pred));
2610 } else {
2611 prop_assert_eq!(pred.status, ConformalStatus::Calibrated);
2612 prop_assert_eq!(pred.fallback_level, 0);
2613 prop_assert!(rolling.is_calibrated(&pred));
2614 }
2615 rolling.observe(key, y_hat, (y_hat + r).max(0.0));
2616 }
2617 }
2618 }
2619 }
2620}