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 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
578fn 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
601pub(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 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 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 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 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 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); let b = size_bucket(8, 16); assert_eq!(a, 6);
1147 assert_eq!(b, 7);
1148 }
1149
1150 #[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); }
1163
1164 #[test]
1165 fn size_bucket_typical_terminals() {
1166 let b80 = size_bucket(80, 24); let b120 = size_bucket(120, 40); assert_eq!(b80, 10);
1169 assert_eq!(b120, 12);
1170 }
1171
1172 #[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 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 assert_eq!(q, Some(30.0));
1201 }
1202
1203 #[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 #[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 #[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 #[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 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 let p = predictor.predict(key, 0.0, 100.0);
1333 assert!(!p.risk); let p2 = predictor.predict(key, 0.0, 30.0);
1335 assert!(p2.risk); }
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 #[test]
1359 fn global_fallback_with_data() {
1360 let mut predictor = ConformalPredictor::new(ConformalConfig {
1361 alpha: 0.1,
1362 min_samples: 100, window_size: 256,
1364 q_default: 999.0,
1365 })
1366 .expect("valid config");
1367 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 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 #[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 #[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 #[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 predictor.observe(key, 10.0, 5.0);
1439 let p = predictor.predict(key, 10.0, 100.0);
1440 assert_eq!(p.quantile, Some(-5.0));
1443 assert_eq!(p.upper_us, Some(10.0));
1444 }
1445
1446 #[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 #[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 #[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, })
1570 .expect("valid config");
1571 let key = test_key(80, 24);
1572 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 #[test]
1588 fn calibration_uniform_distribution_quantile() {
1589 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 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 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 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 assert_eq!(p.fallback_level, 0);
1634 assert_eq!(p.sample_count, 50);
1635 assert_eq!(p.quantile, Some(20.5));
1636 assert_eq!(p.upper_us, Some(120.5));
1638 }
1639
1640 #[test]
1641 fn calibration_constant_residuals() {
1642 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); }
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 #[test]
1662 fn quantile_covers_expected_fraction_of_uniform_grid() {
1663 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 for i in 0..n_calibrate {
1680 predictor.observe(key, 0.0, i as f64);
1681 }
1682
1683 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 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 let target_coverage = 1.0 - alpha - 0.05; 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 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 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 assert_eq!(p.quantile, Some(191.0));
1731 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 #[test]
1745 fn gate_trigger_exact_boundary() {
1746 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 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 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 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 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 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 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 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 #[test]
1832 fn alpha_sensitivity_wider_interval_with_lower_alpha() {
1833 let key = test_key(80, 24);
1834
1835 let mut predictor_tight = ConformalPredictor::new(ConformalConfig {
1837 alpha: 0.5, 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, 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 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 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 assert_eq!(p.quantile, Some(1.0));
1938 }
1939
1940 #[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 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 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 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 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 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 #[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 #[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 #[test]
2290 fn quantile_grid_fraction_for_multiple_alphas() {
2291 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 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 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 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 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 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 let key = test_key(80, 24);
2367 let mut predictor = ConformalPredictor::new(ConformalConfig {
2368 alpha: 0.001, 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); }
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 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 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 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 #[test]
2443 fn cross_mode_fallback_does_not_mix_modes() {
2444 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 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 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 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
2492 #[test]
2501 fn default_config_matches_the_documented_values() {
2502 let config = ConformalConfig::default();
2503 assert!(
2504 (config.alpha - 0.05).abs() < f64::EPSILON,
2505 "README documents alpha = 0.05, found {}",
2506 config.alpha
2507 );
2508 assert_eq!(config.min_samples, 20, "README documents min_samples = 20");
2509 assert_eq!(config.window_size, 256, "README documents window 256");
2510 assert!(
2512 (config.q_default - 10_000.0).abs() < f64::EPSILON,
2513 "README documents q_default = 10 ms, found {} us",
2514 config.q_default
2515 );
2516 }
2517}