Skip to main content

ftui_widgets/
height_predictor.rs

1//! Bayesian height prediction with conformal bounds for virtualized lists.
2//!
3//! Predicts unseen row heights to pre-allocate scroll space and avoid
4//! scroll jumps when actual heights are measured lazily.
5//!
6//! # Mathematical Model
7//!
8//! ## Bayesian Online Estimation
9//!
10//! Maintains a Normal-Normal conjugate model per item category:
11//!
12//! ```text
13//! Prior:     μ ~ N(μ₀, σ₀²/κ₀)
14//! Likelihood: h_i ~ N(μ, σ²)
15//! Posterior:  μ | data ~ N(μ_n, σ²/κ_n)
16//!
17//! where:
18//!   κ_n = κ₀ + n
19//!   μ_n = (κ₀·μ₀ + n·x̄) / κ_n
20//!   σ²  estimated via running variance (Welford's algorithm)
21//! ```
22//!
23//! ## Conformal Prediction Bounds
24//!
25//! Given a calibration set of (predicted, actual) residuals, the conformal
26//! interval is:
27//!
28//! ```text
29//! [μ_n - q_{1-α/2}, μ_n + q_{1-α/2}]
30//! ```
31//!
32//! where `q` is the empirical quantile of |residuals|. This provides
33//! distribution-free coverage: P(h ∈ interval) ≥ 1 - α.
34//!
35//! # Failure Modes
36//!
37//! | Condition | Behavior | Rationale |
38//! |-----------|----------|-----------|
39//! | No measurements | Return default height | Cold start fallback |
40//! | n = 1 | Wide interval (use prior σ) | Insufficient data |
41//! | All same height | σ → 0, interval collapses | Homogeneous data |
42//! | Actual > bound | Adjust + record violation | Expected at rate α |
43
44use std::collections::VecDeque;
45
46/// Configuration for the height predictor.
47#[derive(Debug, Clone)]
48pub struct PredictorConfig {
49    /// Default height when no data is available.
50    pub default_height: u16,
51    /// Prior strength κ₀ (higher = more trust in default). Default: 2.0.
52    pub prior_strength: f64,
53    /// Prior mean μ₀ (usually same as default_height).
54    pub prior_mean: f64,
55    /// Prior variance estimate. Default: 4.0.
56    pub prior_variance: f64,
57    /// Conformal coverage level (1 - α). Default: 0.90.
58    pub coverage: f64,
59    /// Max calibration residuals to keep. Default: 200.
60    pub calibration_window: usize,
61}
62
63impl Default for PredictorConfig {
64    fn default() -> Self {
65        Self {
66            default_height: 1,
67            prior_strength: 2.0,
68            prior_mean: 1.0,
69            prior_variance: 4.0,
70            coverage: 0.90,
71            calibration_window: 200,
72        }
73    }
74}
75
76/// Running statistics using Welford's online algorithm.
77#[derive(Debug, Clone)]
78struct WelfordStats {
79    n: u64,
80    mean: f64,
81    m2: f64, // Sum of squared deviations
82}
83
84impl WelfordStats {
85    fn new() -> Self {
86        Self {
87            n: 0,
88            mean: 0.0,
89            m2: 0.0,
90        }
91    }
92
93    fn update(&mut self, x: f64) {
94        self.n += 1;
95        let delta = x - self.mean;
96        self.mean += delta / self.n as f64;
97        let delta2 = x - self.mean;
98        self.m2 += delta * delta2;
99    }
100
101    fn variance(&self) -> f64 {
102        if self.n < 2 {
103            return f64::MAX;
104        }
105        self.m2 / (self.n - 1) as f64
106    }
107}
108
109/// Per-category prediction state.
110#[derive(Debug, Clone)]
111struct CategoryState {
112    /// Welford running stats for observed heights.
113    welford: WelfordStats,
114    /// Posterior mean μ_n.
115    posterior_mean: f64,
116    /// Posterior κ_n.
117    posterior_kappa: f64,
118    /// Calibration residuals |predicted - actual|.
119    residuals: VecDeque<f64>,
120}
121
122/// A prediction with conformal bounds.
123#[derive(Debug, Clone, Copy)]
124pub struct HeightPrediction {
125    /// Point prediction (posterior mean, rounded).
126    pub predicted: u16,
127    /// Lower conformal bound.
128    pub lower: u16,
129    /// Upper conformal bound.
130    pub upper: u16,
131    /// Number of observations for this category.
132    pub observations: u64,
133}
134
135/// Observations and interval violations accumulated by a height predictor.
136#[derive(Debug, Clone, Copy, PartialEq)]
137pub struct PredictorStats {
138    /// Total measured heights, across all categories.
139    pub measurements: u64,
140    /// Measurements outside their pre-observation interval, excluding each
141    /// category's first observation.
142    pub violations: u64,
143    /// Violations divided by measurements, or zero before any observation.
144    pub violation_rate: f64,
145    /// Number of registered categories, including the default category zero.
146    pub categories: usize,
147}
148
149/// Bayesian height predictor with conformal bounds.
150#[derive(Debug, Clone)]
151pub struct HeightPredictor {
152    config: PredictorConfig,
153    /// Per-category states. Key is category index (0 = default).
154    categories: Vec<CategoryState>,
155    /// Total measurements across all categories.
156    total_measurements: u64,
157    /// Total bound violations.
158    total_violations: u64,
159}
160
161impl HeightPredictor {
162    /// Create a new predictor with default config.
163    pub fn new(config: PredictorConfig) -> Self {
164        // Start with one default category.
165        let default_cat = CategoryState {
166            welford: WelfordStats::new(),
167            posterior_mean: config.prior_mean,
168            posterior_kappa: config.prior_strength,
169            residuals: VecDeque::new(),
170        };
171        Self {
172            config,
173            categories: vec![default_cat],
174            total_measurements: 0,
175            total_violations: 0,
176        }
177    }
178
179    /// Register a new category. Returns the category id.
180    pub fn register_category(&mut self) -> usize {
181        let id = self.categories.len();
182        self.categories.push(CategoryState {
183            welford: WelfordStats::new(),
184            posterior_mean: self.config.prior_mean,
185            posterior_kappa: self.config.prior_strength,
186            residuals: VecDeque::new(),
187        });
188        id
189    }
190
191    /// Predict height for an item in the given category.
192    pub fn predict(&self, category: usize) -> HeightPrediction {
193        let cat = match self.categories.get(category) {
194            Some(c) => c,
195            None => return self.cold_prediction(),
196        };
197
198        if cat.welford.n == 0 {
199            return self.cold_prediction();
200        }
201
202        let mu = cat.posterior_mean;
203        let predicted = mu.round().max(1.0) as u16;
204
205        // Conformal bounds from calibration residuals.
206        let (lower, upper) = self.conformal_bounds(cat, mu);
207
208        HeightPrediction {
209            predicted,
210            lower,
211            upper,
212            observations: cat.welford.n,
213        }
214    }
215
216    /// Record an actual measured height, updating the model.
217    /// Returns whether the measurement was within the predicted bounds.
218    pub fn observe(&mut self, category: usize, actual_height: u16) -> bool {
219        // Ensure category exists.
220        while self.categories.len() <= category {
221            self.register_category();
222        }
223
224        let prediction = self.predict(category);
225        let within_bounds = actual_height >= prediction.lower && actual_height <= prediction.upper;
226
227        self.total_measurements += 1;
228        if !within_bounds && prediction.observations > 0 {
229            self.total_violations += 1;
230        }
231
232        let cat = &mut self.categories[category];
233        let h = actual_height as f64;
234
235        // Record calibration residual.
236        let residual = (cat.posterior_mean - h).abs();
237        cat.residuals.push_back(residual);
238        if cat.residuals.len() > self.config.calibration_window {
239            cat.residuals.pop_front();
240        }
241
242        // Update Welford stats.
243        cat.welford.update(h);
244
245        // Update posterior: μ_n = (κ₀·μ₀ + n·x̄) / κ_n
246        let n = cat.welford.n as f64;
247        let kappa_0 = self.config.prior_strength;
248        let mu_0 = self.config.prior_mean;
249        cat.posterior_kappa = kappa_0 + n;
250        cat.posterior_mean = (kappa_0 * mu_0 + n * cat.welford.mean) / cat.posterior_kappa;
251
252        within_bounds
253    }
254
255    /// Cold-start prediction when no data is available.
256    fn cold_prediction(&self) -> HeightPrediction {
257        let d = self.config.default_height;
258        let margin = (self.config.prior_variance.sqrt() * 2.0).ceil() as u16;
259        HeightPrediction {
260            predicted: d,
261            lower: d.saturating_sub(margin),
262            upper: d.saturating_add(margin),
263            observations: 0,
264        }
265    }
266
267    /// Compute conformal bounds from calibration residuals.
268    fn conformal_bounds(&self, cat: &CategoryState, mu: f64) -> (u16, u16) {
269        if cat.residuals.is_empty() {
270            // Fallback: use prior variance.
271            let margin = (self.config.prior_variance.sqrt() * 2.0).ceil() as u16;
272            let predicted = mu.round().max(1.0) as u16;
273            return (
274                predicted.saturating_sub(margin),
275                predicted.saturating_add(margin),
276            );
277        }
278
279        // Sort residuals to find quantile.
280        let mut sorted: Vec<f64> = cat.residuals.iter().copied().collect();
281        sorted.sort_unstable_by(f64::total_cmp);
282
283        let alpha = 1.0 - self.config.coverage;
284        let n = sorted.len() as f64;
285        let quantile_idx = ((1.0 - alpha) * (n + 1.0)).ceil() as usize;
286        let quantile_idx = quantile_idx.min(sorted.len()).saturating_sub(1);
287        let q = sorted[quantile_idx];
288
289        let lower = (mu - q).max(1.0).floor() as u16;
290        let upper = (mu + q).ceil().max(1.0) as u16;
291
292        (lower, upper)
293    }
294
295    /// Get the posterior mean for a category.
296    pub fn posterior_mean(&self, category: usize) -> f64 {
297        self.categories
298            .get(category)
299            .map(|c| c.posterior_mean)
300            .unwrap_or(self.config.prior_mean)
301    }
302
303    /// Get the posterior variance for a category.
304    pub fn posterior_variance(&self, category: usize) -> f64 {
305        self.categories
306            .get(category)
307            .map(|c| {
308                let sigma_sq = if c.welford.n < 2 {
309                    self.config.prior_variance
310                } else {
311                    c.welford.variance()
312                };
313                sigma_sq / c.posterior_kappa
314            })
315            .unwrap_or(self.config.prior_variance)
316    }
317
318    /// Total measurements observed.
319    pub fn total_measurements(&self) -> u64 {
320        self.total_measurements
321    }
322
323    /// Snapshot the predictor's observed statistics.
324    #[must_use]
325    pub fn stats(&self) -> PredictorStats {
326        PredictorStats {
327            measurements: self.total_measurements,
328            violations: self.total_violations,
329            violation_rate: self.violation_rate(),
330            categories: self.categories.len(),
331        }
332    }
333
334    /// Total bound violations.
335    pub fn total_violations(&self) -> u64 {
336        self.total_violations
337    }
338
339    /// Empirical violation rate.
340    pub fn violation_rate(&self) -> f64 {
341        if self.total_measurements == 0 {
342            return 0.0;
343        }
344        self.total_violations as f64 / self.total_measurements as f64
345    }
346
347    /// Number of categories.
348    pub fn category_count(&self) -> usize {
349        self.categories.len()
350    }
351
352    /// Number of observations for a category.
353    pub fn category_observations(&self, category: usize) -> u64 {
354        self.categories
355            .get(category)
356            .map(|c| c.welford.n)
357            .unwrap_or(0)
358    }
359}
360
361impl Default for HeightPredictor {
362    fn default() -> Self {
363        Self::new(PredictorConfig::default())
364    }
365}
366
367#[cfg(test)]
368mod tests {
369    use super::*;
370
371    // ─── Posterior update tests ────────────────────────────────────
372
373    #[test]
374    fn unit_posterior_update() {
375        let config = PredictorConfig {
376            prior_mean: 2.0,
377            prior_strength: 1.0,
378            prior_variance: 4.0,
379            ..Default::default()
380        };
381        let mut pred = HeightPredictor::new(config);
382
383        // Prior: μ=2.0, κ=1.
384        assert!((pred.posterior_mean(0) - 2.0).abs() < 1e-10);
385
386        // Observe height 4.
387        pred.observe(0, 4);
388        // κ_1 = 1 + 1 = 2, μ_1 = (1*2 + 1*4) / 2 = 3.0
389        assert!((pred.posterior_mean(0) - 3.0).abs() < 1e-10);
390
391        // Observe another height 4.
392        pred.observe(0, 4);
393        // κ_2 = 1 + 2 = 3, x̄ = 4, μ_2 = (1*2 + 2*4) / 3 = 10/3 ≈ 3.333
394        assert!((pred.posterior_mean(0) - 10.0 / 3.0).abs() < 1e-10);
395    }
396
397    #[test]
398    fn unit_posterior_variance_decreases() {
399        let mut pred = HeightPredictor::new(PredictorConfig {
400            prior_variance: 4.0,
401            ..Default::default()
402        });
403
404        let var_0 = pred.posterior_variance(0);
405        assert!(var_0 > 0.0, "prior variance should be positive");
406
407        // Feed noisy data so Welford variance is non-zero.
408        for i in 0..10 {
409            pred.observe(0, if i % 2 == 0 { 2 } else { 4 });
410        }
411        let var_10 = pred.posterior_variance(0);
412
413        for i in 0..90 {
414            pred.observe(0, if i % 2 == 0 { 2 } else { 4 });
415        }
416        let var_100 = pred.posterior_variance(0);
417
418        // With noisy data, posterior variance σ²/κ_n decreases as κ_n grows.
419        assert!(
420            var_10 < var_0,
421            "variance should decrease: {var_10} >= {var_0}"
422        );
423        assert!(
424            var_100 < var_10,
425            "variance should decrease: {var_100} >= {var_10}"
426        );
427    }
428
429    // ─── Conformal bounds tests ───────────────────────────────────
430
431    #[test]
432    fn unit_conformal_bounds() {
433        let config = PredictorConfig {
434            coverage: 0.90,
435            prior_mean: 3.0,
436            prior_strength: 1.0,
437            ..Default::default()
438        };
439        let mut pred = HeightPredictor::new(config);
440
441        // Feed consistent data.
442        for _ in 0..50 {
443            pred.observe(0, 3);
444        }
445
446        let p = pred.predict(0);
447        // With all observations at 3, residuals should be near 0.
448        // Bounds should be tight around 3.
449        assert_eq!(p.predicted, 3);
450        assert!(p.lower <= 3);
451        assert!(p.upper >= 3);
452    }
453
454    #[test]
455    fn conformal_bounds_widen_with_noise() {
456        let config = PredictorConfig {
457            coverage: 0.90,
458            prior_mean: 5.0,
459            prior_strength: 1.0,
460            ..Default::default()
461        };
462        let mut pred = HeightPredictor::new(config);
463
464        // Consistent data → tight bounds.
465        for _ in 0..50 {
466            pred.observe(0, 5);
467        }
468        let tight = pred.predict(0);
469
470        // Reset with noisy data.
471        let mut pred2 = HeightPredictor::new(PredictorConfig {
472            coverage: 0.90,
473            prior_mean: 5.0,
474            prior_strength: 1.0,
475            ..Default::default()
476        });
477        let mut seed: u64 = 0xABCD_1234_5678_9ABC;
478        for _ in 0..50 {
479            seed = seed
480                .wrapping_mul(6364136223846793005)
481                .wrapping_add(1442695040888963407);
482            let h = 3 + (seed >> 62) as u16; // heights 3..6
483            pred2.observe(0, h);
484        }
485        let wide = pred2.predict(0);
486
487        assert!(
488            (wide.upper - wide.lower) >= (tight.upper - tight.lower),
489            "noisy data should produce wider bounds"
490        );
491    }
492
493    // ─── Coverage property test ───────────────────────────────────
494
495    #[test]
496    fn property_coverage() {
497        let alpha = 0.10;
498        let config = PredictorConfig {
499            coverage: 1.0 - alpha,
500            prior_mean: 3.0,
501            prior_strength: 2.0,
502            prior_variance: 4.0,
503            calibration_window: 100,
504            ..Default::default()
505        };
506        let mut pred = HeightPredictor::new(config);
507
508        // Warm up with calibration data.
509        let mut seed: u64 = 0xDEAD_BEEF_CAFE_0001;
510        for _ in 0..100 {
511            seed = seed
512                .wrapping_mul(6364136223846793005)
513                .wrapping_add(1442695040888963407);
514            let h = 2 + (seed >> 62) as u16; // heights 2..5
515            pred.observe(0, h);
516        }
517
518        // Now check coverage on new data.
519        let mut violations = 0u32;
520        let test_n = 200;
521        for _ in 0..test_n {
522            seed = seed
523                .wrapping_mul(6364136223846793005)
524                .wrapping_add(1442695040888963407);
525            let h = 2 + (seed >> 62) as u16;
526            let within = pred.observe(0, h);
527            if !within {
528                violations += 1;
529            }
530        }
531
532        let viol_rate = violations as f64 / test_n as f64;
533        // Empirical violation rate should be approximately ≤ α.
534        // Allow generous tolerance for finite sample + discrete heights.
535        assert!(
536            viol_rate <= alpha + 0.15,
537            "violation rate {viol_rate} exceeds α + tolerance ({alpha} + 0.15)"
538        );
539    }
540
541    // ─── Scroll stability test ────────────────────────────────────
542
543    #[test]
544    fn e2e_scroll_stability() {
545        let mut pred = HeightPredictor::new(PredictorConfig {
546            prior_mean: 1.0,
547            prior_strength: 2.0,
548            default_height: 1,
549            coverage: 0.90,
550            ..Default::default()
551        });
552
553        // All items are height 1 (most common TUI case).
554        let mut corrections = 0u32;
555        for _ in 0..500 {
556            let within = pred.observe(0, 1);
557            if !within {
558                corrections += 1;
559            }
560        }
561
562        // With homogeneous heights, should converge quickly with zero corrections
563        // after warmup.
564        let p = pred.predict(0);
565        assert_eq!(p.predicted, 1);
566        assert!(corrections < 10, "too many corrections: {corrections}");
567    }
568
569    // ─── Multiple categories ──────────────────────────────────────
570
571    #[test]
572    fn categories_are_independent() {
573        let mut pred = HeightPredictor::default();
574        let cat_a = 0;
575        let cat_b = pred.register_category();
576
577        // Feed different data to each.
578        for _ in 0..20 {
579            pred.observe(cat_a, 1);
580            pred.observe(cat_b, 5);
581        }
582
583        let pa = pred.predict(cat_a);
584        let pb = pred.predict(cat_b);
585
586        assert_eq!(pa.predicted, 1);
587        assert!(pb.predicted >= 4 && pb.predicted <= 5);
588    }
589
590    // ─── Cold start ───────────────────────────────────────────────
591
592    #[test]
593    fn cold_prediction_uses_default() {
594        let pred = HeightPredictor::new(PredictorConfig {
595            default_height: 2,
596            prior_variance: 1.0,
597            ..Default::default()
598        });
599        let p = pred.predict(0);
600        assert_eq!(p.predicted, 2);
601        assert_eq!(p.observations, 0);
602    }
603
604    // ─── Determinism ──────────────────────────────────────────────
605
606    #[test]
607    fn deterministic_under_same_observations() {
608        let run = || {
609            let mut pred = HeightPredictor::default();
610            let observations = [1, 2, 1, 3, 1, 2, 1, 1, 4, 1];
611            for &h in &observations {
612                pred.observe(0, h);
613            }
614            (pred.predict(0).predicted, pred.posterior_mean(0))
615        };
616
617        let (p1, m1) = run();
618        let (p2, m2) = run();
619        assert_eq!(p1, p2);
620        assert!((m1 - m2).abs() < 1e-15);
621    }
622
623    // ─── Performance ──────────────────────────────────────────────
624
625    #[test]
626    fn perf_prediction_overhead() {
627        let mut pred = HeightPredictor::default();
628
629        // Warm up.
630        for _ in 0..100 {
631            pred.observe(0, 2);
632        }
633
634        let start = std::time::Instant::now();
635        let mut _sink = 0u16;
636        for _ in 0..100_000 {
637            _sink = _sink.wrapping_add(pred.predict(0).predicted);
638        }
639        let elapsed = start.elapsed();
640        let per_prediction = elapsed / 100_000;
641
642        // Must be < 5μs per prediction (generous for debug builds).
643        assert!(
644            per_prediction < std::time::Duration::from_micros(5),
645            "prediction too slow: {per_prediction:?}"
646        );
647    }
648
649    // ─── Violation tracking ───────────────────────────────────────
650
651    #[test]
652    fn violation_tracking() {
653        let mut pred = HeightPredictor::new(PredictorConfig {
654            prior_mean: 5.0,
655            prior_strength: 100.0, // strong prior
656            default_height: 5,
657            coverage: 0.95,
658            ..Default::default()
659        });
660
661        // Warm up with height=5.
662        for _ in 0..50 {
663            pred.observe(0, 5);
664        }
665
666        // Sudden jump to height=20 should violate bounds.
667        let within = pred.observe(0, 20);
668        assert!(!within, "extreme outlier should violate bounds");
669        assert!(pred.total_violations() > 0);
670    }
671
672    // ── PredictorConfig defaults ─────────────────────────────────
673
674    #[test]
675    fn config_default_values() {
676        let config = PredictorConfig::default();
677        assert_eq!(config.default_height, 1);
678        assert!((config.prior_strength - 2.0).abs() < f64::EPSILON);
679        assert!((config.prior_mean - 1.0).abs() < f64::EPSILON);
680        assert!((config.prior_variance - 4.0).abs() < f64::EPSILON);
681        assert!((config.coverage - 0.90).abs() < f64::EPSILON);
682        assert_eq!(config.calibration_window, 200);
683    }
684
685    // ── HeightPredictor::default ─────────────────────────────────
686
687    #[test]
688    fn default_predictor_has_one_category() {
689        let pred = HeightPredictor::default();
690        assert_eq!(pred.category_count(), 1);
691        assert_eq!(pred.total_measurements(), 0);
692        assert_eq!(pred.total_violations(), 0);
693        assert!((pred.violation_rate() - 0.0).abs() < f64::EPSILON);
694        assert_eq!(
695            pred.stats(),
696            PredictorStats {
697                measurements: 0,
698                violations: 0,
699                violation_rate: 0.0,
700                categories: 1,
701            }
702        );
703    }
704
705    // ── Predict unknown category ─────────────────────────────────
706
707    #[test]
708    fn predict_unknown_category_returns_cold() {
709        let pred = HeightPredictor::default();
710        let p = pred.predict(999);
711        assert_eq!(p.predicted, pred.config.default_height);
712        assert_eq!(p.observations, 0);
713    }
714
715    // ── Observe auto-creates categories ──────────────────────────
716
717    #[test]
718    fn observe_auto_creates_categories() {
719        let mut pred = HeightPredictor::default();
720        assert_eq!(pred.category_count(), 1);
721        pred.observe(3, 5);
722        // Should auto-create categories 1, 2, 3
723        assert_eq!(pred.category_count(), 4);
724        assert_eq!(pred.category_observations(3), 1);
725    }
726
727    // ── Violation rate ───────────────────────────────────────────
728
729    #[test]
730    fn violation_rate_empty() {
731        let pred = HeightPredictor::default();
732        assert!((pred.violation_rate() - 0.0).abs() < f64::EPSILON);
733    }
734
735    #[test]
736    fn violation_rate_computation() {
737        let mut pred = HeightPredictor::new(PredictorConfig {
738            prior_mean: 5.0,
739            prior_strength: 100.0,
740            default_height: 5,
741            coverage: 0.95,
742            ..Default::default()
743        });
744        // Warm up so bounds are tight
745        for _ in 0..50 {
746            pred.observe(0, 5);
747        }
748        // 10 normal observations
749        for _ in 0..10 {
750            pred.observe(0, 5);
751        }
752        let before_violations = pred.total_violations();
753        // 1 extreme outlier
754        pred.observe(0, 100);
755        let after_violations = pred.total_violations();
756        assert!(after_violations > before_violations);
757        assert!(pred.violation_rate() > 0.0);
758    }
759
760    // ── Category accessors ───────────────────────────────────────
761
762    #[test]
763    fn category_observations_returns_zero_for_unknown() {
764        let pred = HeightPredictor::default();
765        assert_eq!(pred.category_observations(999), 0);
766    }
767
768    #[test]
769    fn category_observations_tracks_counts() {
770        let mut pred = HeightPredictor::default();
771        pred.observe(0, 3);
772        pred.observe(0, 4);
773        pred.observe(0, 5);
774        assert_eq!(pred.category_observations(0), 3);
775    }
776
777    // ── Posterior accessors with unknown category ─────────────────
778
779    #[test]
780    fn posterior_mean_unknown_returns_prior() {
781        let pred = HeightPredictor::default();
782        assert!((pred.posterior_mean(999) - pred.config.prior_mean).abs() < f64::EPSILON);
783    }
784
785    #[test]
786    fn posterior_variance_unknown_returns_prior() {
787        let pred = HeightPredictor::default();
788        assert!((pred.posterior_variance(999) - pred.config.prior_variance).abs() < f64::EPSILON);
789    }
790
791    // ── Register category ────────────────────────────────────────
792
793    #[test]
794    fn register_category_returns_sequential_ids() {
795        let mut pred = HeightPredictor::default();
796        let id1 = pred.register_category();
797        let id2 = pred.register_category();
798        assert_eq!(id1, 1);
799        assert_eq!(id2, 2);
800        assert_eq!(pred.category_count(), 3);
801    }
802
803    // ── Observe returns within_bounds ─────────────────────────────
804
805    #[test]
806    fn observe_returns_true_for_consistent_data() {
807        let mut pred = HeightPredictor::new(PredictorConfig {
808            prior_mean: 3.0,
809            prior_strength: 1.0,
810            ..Default::default()
811        });
812        // Warm up
813        for _ in 0..20 {
814            pred.observe(0, 3);
815        }
816        // Same value should be within bounds
817        assert!(pred.observe(0, 3));
818    }
819
820    // ── Total measurements ───────────────────────────────────────
821
822    #[test]
823    fn total_measurements_increments() {
824        let mut pred = HeightPredictor::default();
825        for i in 0..7 {
826            pred.observe(0, (i + 1) as u16);
827        }
828        assert_eq!(pred.total_measurements(), 7);
829    }
830
831    // ── HeightPrediction bounds ordering ─────────────────────────
832
833    #[test]
834    fn prediction_lower_le_predicted_le_upper() {
835        let mut pred = HeightPredictor::default();
836        for _ in 0..30 {
837            pred.observe(0, 3);
838        }
839        let p = pred.predict(0);
840        assert!(p.lower <= p.predicted);
841        assert!(p.predicted <= p.upper);
842    }
843
844    // ── Edge-case tests (bd-l9r1a) ──────────────────────────
845
846    #[test]
847    fn observe_height_zero() {
848        let mut pred = HeightPredictor::default();
849        pred.observe(0, 0);
850        let p = pred.predict(0);
851        // predicted is max(mu.round(), 1.0) so at least 1
852        assert!(p.predicted >= 1);
853    }
854
855    #[test]
856    fn observe_height_max_u16() {
857        let mut pred = HeightPredictor::default();
858        pred.observe(0, u16::MAX);
859        let p = pred.predict(0);
860        assert!(p.predicted > 0);
861        assert!(p.observations == 1);
862    }
863
864    #[test]
865    fn cold_prediction_zero_variance() {
866        let pred = HeightPredictor::new(PredictorConfig {
867            default_height: 5,
868            prior_variance: 0.0,
869            ..Default::default()
870        });
871        let p = pred.predict(0);
872        assert_eq!(p.predicted, 5);
873        // margin = ceil(sqrt(0.0) * 2.0) = 0
874        assert_eq!(p.lower, 5);
875        assert_eq!(p.upper, 5);
876    }
877
878    #[test]
879    fn cold_prediction_large_variance() {
880        let pred = HeightPredictor::new(PredictorConfig {
881            default_height: 1,
882            prior_variance: 10000.0,
883            ..Default::default()
884        });
885        let p = pred.predict(0);
886        assert_eq!(p.predicted, 1);
887        // margin = ceil(sqrt(10000) * 2) = ceil(200) = 200
888        assert_eq!(p.lower, 0); // 1.saturating_sub(200) = 0
889    }
890
891    #[test]
892    fn coverage_zero() {
893        let mut pred = HeightPredictor::new(PredictorConfig {
894            coverage: 0.0,
895            prior_mean: 3.0,
896            prior_strength: 1.0,
897            ..Default::default()
898        });
899        for _ in 0..20 {
900            pred.observe(0, 3);
901        }
902        // alpha = 1.0, quantile_idx → 0
903        let p = pred.predict(0);
904        assert!(p.predicted > 0);
905    }
906
907    #[test]
908    fn coverage_one() {
909        let mut pred = HeightPredictor::new(PredictorConfig {
910            coverage: 1.0,
911            prior_mean: 3.0,
912            prior_strength: 1.0,
913            ..Default::default()
914        });
915        for _ in 0..20 {
916            pred.observe(0, 3);
917        }
918        for _ in 0..5 {
919            pred.observe(0, 10);
920        }
921        // alpha = 0.0, quantile_idx → max residual
922        let p = pred.predict(0);
923        assert!(p.lower <= p.predicted);
924        assert!(p.predicted <= p.upper);
925    }
926
927    #[test]
928    fn calibration_window_one() {
929        let mut pred = HeightPredictor::new(PredictorConfig {
930            calibration_window: 1,
931            prior_mean: 3.0,
932            prior_strength: 1.0,
933            ..Default::default()
934        });
935        for _ in 0..10 {
936            pred.observe(0, 3);
937        }
938        let p = pred.predict(0);
939        assert!(p.predicted > 0);
940        assert!(p.lower <= p.predicted);
941    }
942
943    #[test]
944    fn single_observation_uses_wide_bounds() {
945        let mut pred = HeightPredictor::new(PredictorConfig {
946            prior_mean: 5.0,
947            prior_strength: 1.0,
948            prior_variance: 4.0,
949            ..Default::default()
950        });
951        pred.observe(0, 5);
952        let p = pred.predict(0);
953        assert_eq!(p.observations, 1);
954        // With only 1 residual, bounds come from that single residual
955        assert!(p.lower <= p.predicted);
956        assert!(p.predicted <= p.upper);
957    }
958
959    #[test]
960    fn predictor_config_clone_and_debug() {
961        let config = PredictorConfig::default();
962        let cloned = config.clone();
963        assert_eq!(cloned.default_height, config.default_height);
964        let dbg = format!("{:?}", config);
965        assert!(dbg.contains("PredictorConfig"));
966    }
967
968    #[test]
969    fn height_prediction_copy_and_debug() {
970        let p = HeightPrediction {
971            predicted: 3,
972            lower: 1,
973            upper: 5,
974            observations: 10,
975        };
976        let p2 = p; // Copy
977        assert_eq!(p.predicted, p2.predicted);
978        assert_eq!(p.lower, p2.lower);
979        assert_eq!(p.upper, p2.upper);
980        assert_eq!(p.observations, p2.observations);
981        let dbg = format!("{:?}", p);
982        assert!(dbg.contains("HeightPrediction"));
983    }
984
985    #[test]
986    fn height_prediction_clone() {
987        fn assert_clone<T: Clone>() {}
988        assert_clone::<HeightPrediction>();
989        let p = HeightPrediction {
990            predicted: 2,
991            lower: 1,
992            upper: 4,
993            observations: 5,
994        };
995        let cloned = p; // Copy implies Clone; clippy forbids clone_on_copy
996        assert_eq!(cloned.predicted, 2);
997    }
998
999    #[test]
1000    fn predictor_clone_independence() {
1001        let mut pred = HeightPredictor::default();
1002        pred.observe(0, 5);
1003        pred.observe(0, 5);
1004        let mut cloned = pred.clone();
1005        cloned.observe(0, 100);
1006        // Original should be unaffected
1007        assert_eq!(pred.total_measurements(), 2);
1008        assert_eq!(cloned.total_measurements(), 3);
1009    }
1010
1011    #[test]
1012    fn predictor_debug() {
1013        let pred = HeightPredictor::default();
1014        let dbg = format!("{:?}", pred);
1015        assert!(dbg.contains("HeightPredictor"));
1016    }
1017
1018    #[test]
1019    fn posterior_variance_with_two_identical_observations() {
1020        let mut pred = HeightPredictor::new(PredictorConfig {
1021            prior_variance: 4.0,
1022            prior_strength: 1.0,
1023            ..Default::default()
1024        });
1025        pred.observe(0, 3);
1026        pred.observe(0, 3);
1027        // Welford variance with identical values = 0, κ_n = 3
1028        // posterior_variance = 0 / 3 = 0
1029        let var = pred.posterior_variance(0);
1030        assert!(var.abs() < 1e-10, "identical obs should give ~0 variance");
1031    }
1032
1033    #[test]
1034    fn posterior_variance_with_one_observation_uses_prior() {
1035        let mut pred = HeightPredictor::new(PredictorConfig {
1036            prior_variance: 4.0,
1037            prior_strength: 2.0,
1038            ..Default::default()
1039        });
1040        pred.observe(0, 3);
1041        // n=1, so welford.variance() returns f64::MAX → uses prior_variance
1042        // But wait: code checks n < 2, uses prior_variance = 4.0
1043        // posterior_variance = 4.0 / (2.0 + 1) = 4/3
1044        let var = pred.posterior_variance(0);
1045        assert!((var - 4.0 / 3.0).abs() < 1e-10);
1046    }
1047
1048    #[test]
1049    fn observe_returns_false_for_first_cold_outlier() {
1050        let mut pred = HeightPredictor::new(PredictorConfig {
1051            default_height: 1,
1052            prior_mean: 1.0,
1053            prior_strength: 2.0,
1054            prior_variance: 0.25,
1055            ..Default::default()
1056        });
1057        // Cold prediction: predicted=1, margin=ceil(sqrt(0.25)*2)=ceil(1.0)=1
1058        // bounds: [0, 2]
1059        // First observation is cold (observations=0), so violation not counted
1060        let within = pred.observe(0, 100);
1061        // Cold start: prediction.observations == 0, so violation is NOT counted
1062        assert!(within || pred.total_violations() == 0);
1063    }
1064
1065    #[test]
1066    fn all_same_height_converges_exactly() {
1067        let mut pred = HeightPredictor::new(PredictorConfig {
1068            prior_mean: 3.0,
1069            prior_strength: 1.0,
1070            ..Default::default()
1071        });
1072        for _ in 0..100 {
1073            pred.observe(0, 3);
1074        }
1075        let p = pred.predict(0);
1076        assert_eq!(p.predicted, 3);
1077        // With all identical observations, bounds should collapse
1078        assert_eq!(p.lower, 3);
1079        assert_eq!(p.upper, 3);
1080    }
1081
1082    #[test]
1083    fn many_categories_auto_created() {
1084        let mut pred = HeightPredictor::default();
1085        pred.observe(10, 5);
1086        // Categories 0..=10 should exist now
1087        assert_eq!(pred.category_count(), 11);
1088        // Intermediate categories have no observations
1089        assert_eq!(pred.category_observations(5), 0);
1090        assert_eq!(pred.category_observations(10), 1);
1091    }
1092
1093    #[test]
1094    fn prediction_bounds_ordering_after_mixed_data() {
1095        let mut pred = HeightPredictor::default();
1096        for h in [1, 2, 5, 10, 1, 3, 7, 2, 4, 6] {
1097            pred.observe(0, h);
1098        }
1099        let p = pred.predict(0);
1100        assert!(
1101            p.lower <= p.predicted,
1102            "lower={} > predicted={}",
1103            p.lower,
1104            p.predicted
1105        );
1106        assert!(
1107            p.predicted <= p.upper,
1108            "predicted={} > upper={}",
1109            p.predicted,
1110            p.upper
1111        );
1112    }
1113}