Skip to main content

ftui_render/
alloc_budget.rs

1#![forbid(unsafe_code)]
2
3//! Allocation budget: sequential leak detection using CUSUM + e-process.
4//!
5//! Tracks allocation counts (or bytes) per frame as a time series and
6//! detects sustained drift (allocation leaks or regressions) with formal,
7//! anytime-valid guarantees.
8//!
9//! # Detectors
10//!
11//! 1. **CUSUM** — Cumulative Sum control chart for fast mean-shift detection.
12//!    Sensitive to small, sustained drifts. Signals when the cumulative
13//!    deviation from the reference mean exceeds a threshold.
14//!
15//! 2. **E-process** — Anytime-valid sequential test (test martingale).
16//!    Provides a p-value-like guarantee that holds under optional stopping:
17//!    `P(E_t ever exceeds 1/α | H₀) ≤ α` (Ville's inequality).
18//!
19//! # Usage
20//!
21//! ```
22//! use ftui_render::alloc_budget::{AllocLeakDetector, LeakDetectorConfig};
23//!
24//! let config = LeakDetectorConfig::default();
25//! let mut detector = AllocLeakDetector::new(config);
26//!
27//! // Feed allocation counts per frame.
28//! for count in [100, 102, 98, 105, 101] {
29//!     let alert = detector.observe(count as f64);
30//!     assert!(!alert.triggered);
31//! }
32//! ```
33//!
34//! # Evidence Ledger
35//!
36//! Every observation produces an [`EvidenceEntry`] recording the residual,
37//! CUSUM state, and e-process value. This ledger is inspectable for
38//! diagnostics and can be serialised to JSONL.
39//!
40//! # Failure Modes
41//!
42//! - **False positive**: bounded by α (default 0.05). Under H₀ (no leak),
43//!   the e-process triggers with probability ≤ α across all stopping times.
44//! - **Detection delay**: CUSUM detects a shift of δ within approximately
45//!   `h / δ` frames (where h is the threshold). E-process provides
46//!   complementary evidence with stronger guarantees.
47
48// =========================================================================
49// Configuration
50// =========================================================================
51
52/// Configuration for the allocation leak detector.
53#[derive(Debug, Clone)]
54pub struct LeakDetectorConfig {
55    /// False positive rate bound for the e-process (default: 0.05).
56    pub alpha: f64,
57    /// Betting fraction λ for the e-process likelihood ratio.
58    /// Controls sensitivity vs. evidence accumulation speed.
59    /// Recommended: 0.1–0.5 (default: 0.2).
60    pub lambda: f64,
61    /// CUSUM threshold h. Higher = fewer false positives, slower detection.
62    /// Rule of thumb: h ≈ 8 with k=0.5 gives two-sided ARL₀ ≈ 2000 (default: 8.0).
63    pub cusum_threshold: f64,
64    /// CUSUM reference value k (allowance). Typically δ/2 where δ is the
65    /// minimum shift to detect. (default: 0.5).
66    pub cusum_allowance: f64,
67    /// Number of warmup frames to estimate baseline mean and σ (default: 30).
68    pub warmup_frames: usize,
69    /// EMA decay for running σ estimate (default: 0.95).
70    pub sigma_decay: f64,
71    /// Minimum σ floor to prevent division by zero (default: 1.0).
72    pub sigma_floor: f64,
73}
74
75impl Default for LeakDetectorConfig {
76    fn default() -> Self {
77        Self {
78            alpha: 0.05,
79            lambda: 0.2,
80            cusum_threshold: 8.0,
81            cusum_allowance: 0.5,
82            warmup_frames: 30,
83            sigma_decay: 0.95,
84            sigma_floor: 1.0,
85        }
86    }
87}
88
89// =========================================================================
90// Evidence ledger
91// =========================================================================
92
93/// A single observation's evidence record.
94#[derive(Debug, Clone)]
95pub struct EvidenceEntry {
96    /// Frame index (0-based).
97    pub frame: usize,
98    /// Raw observation value.
99    pub value: f64,
100    /// Standardised residual: (value - mean) / σ.
101    pub residual: f64,
102    /// CUSUM upper statistic S⁺.
103    pub cusum_upper: f64,
104    /// CUSUM lower statistic S⁻.
105    pub cusum_lower: f64,
106    /// E-process value (wealth / evidence).
107    pub e_value: f64,
108    /// Running mean estimate.
109    pub mean_estimate: f64,
110    /// Running σ estimate.
111    pub sigma_estimate: f64,
112}
113
114impl EvidenceEntry {
115    /// Serialise to a JSONL line.
116    pub fn to_jsonl(&self) -> String {
117        format!(
118            r#"{{"frame":{},"value":{:.2},"residual":{:.4},"cusum_upper":{:.4},"cusum_lower":{:.4},"e_value":{:.6},"mean":{:.2},"sigma":{:.4}}}"#,
119            self.frame,
120            self.value,
121            self.residual,
122            self.cusum_upper,
123            self.cusum_lower,
124            self.e_value,
125            self.mean_estimate,
126            self.sigma_estimate,
127        )
128    }
129}
130
131// =========================================================================
132// Alert
133// =========================================================================
134
135/// Result of a single observation.
136#[derive(Debug, Clone)]
137pub struct LeakAlert {
138    /// Whether the detector triggered an alert.
139    pub triggered: bool,
140    /// Which detector(s) triggered.
141    pub cusum_triggered: bool,
142    /// Whether the e-process crossed the threshold.
143    pub eprocess_triggered: bool,
144    /// Current e-process value.
145    pub e_value: f64,
146    /// Current CUSUM upper statistic.
147    pub cusum_upper: f64,
148    /// Current CUSUM lower statistic.
149    pub cusum_lower: f64,
150    /// Frame index.
151    pub frame: usize,
152}
153
154impl LeakAlert {
155    fn no_alert(frame: usize, e_value: f64, cusum_upper: f64, cusum_lower: f64) -> Self {
156        Self {
157            triggered: false,
158            cusum_triggered: false,
159            eprocess_triggered: false,
160            e_value,
161            cusum_upper,
162            cusum_lower,
163            frame,
164        }
165    }
166}
167
168// =========================================================================
169// Detector
170// =========================================================================
171
172/// Sequential allocation leak detector combining CUSUM and e-process.
173///
174/// Feed per-frame allocation counts via `observe`. The detector maintains
175/// running estimates of the baseline mean and standard deviation, then
176/// applies both CUSUM and an e-process test to the standardised residuals.
177///
178/// An alert triggers when *either* detector fires. The evidence ledger
179/// records all intermediate state for post-mortem diagnostics.
180#[derive(Debug, Clone)]
181pub struct AllocLeakDetector {
182    config: LeakDetectorConfig,
183    /// Running mean (Welford online).
184    mean: f64,
185    /// Running M2 for variance (Welford).
186    m2: f64,
187    /// Running σ estimate (EMA-smoothed).
188    sigma_ema: f64,
189    /// CUSUM upper statistic S⁺ (detects upward shift).
190    cusum_upper: f64,
191    /// CUSUM lower statistic S⁻ (detects downward shift).
192    cusum_lower: f64,
193    /// E-process value (wealth).
194    e_value: f64,
195    /// Total frames observed.
196    frames: usize,
197    /// Evidence ledger (all observations).
198    ledger: Vec<EvidenceEntry>,
199}
200
201impl AllocLeakDetector {
202    /// Create a new detector with the given configuration.
203    #[must_use]
204    pub fn new(config: LeakDetectorConfig) -> Self {
205        Self {
206            config,
207            mean: 0.0,
208            m2: 0.0,
209            sigma_ema: 0.0,
210            cusum_upper: 0.0,
211            cusum_lower: 0.0,
212            e_value: 1.0,
213            frames: 0,
214            ledger: Vec::new(),
215        }
216    }
217
218    /// Observe a new allocation count (or byte total) for this frame.
219    ///
220    /// Returns a [`LeakAlert`] indicating whether the detector triggered.
221    pub fn observe(&mut self, value: f64) -> LeakAlert {
222        self.observe_inner(value, true)
223    }
224
225    /// Observe without retaining a per-frame ledger entry.
226    ///
227    /// Long-running runtimes export their own snapshots and must not accumulate
228    /// an unbounded diagnostic history inside the detector.
229    pub fn observe_unrecorded(&mut self, value: f64) -> LeakAlert {
230        self.observe_inner(value, false)
231    }
232
233    fn observe_inner(&mut self, value: f64, record: bool) -> LeakAlert {
234        self.frames += 1;
235        let n = self.frames;
236
237        // --- Welford online mean/variance ---
238        let delta = value - self.mean;
239        self.mean += delta / n as f64;
240        let delta2 = value - self.mean;
241        self.m2 += delta * delta2;
242
243        let welford_sigma = if n > 1 {
244            (self.m2 / (n - 1) as f64).sqrt()
245        } else {
246            0.0
247        };
248
249        // EMA-smoothed σ (more responsive to recent changes).
250        if n == 1 {
251            self.sigma_ema = welford_sigma.max(self.config.sigma_floor);
252        } else {
253            self.sigma_ema = self.config.sigma_decay * self.sigma_ema
254                + (1.0 - self.config.sigma_decay) * welford_sigma;
255        }
256        let sigma = self.sigma_ema.max(self.config.sigma_floor);
257
258        // Standardised residual.
259        let residual = delta / sigma;
260
261        // During warmup, only accumulate stats.
262        if n <= self.config.warmup_frames {
263            let entry = EvidenceEntry {
264                frame: n,
265                value,
266                residual,
267                cusum_upper: 0.0,
268                cusum_lower: 0.0,
269                e_value: 1.0,
270                mean_estimate: self.mean,
271                sigma_estimate: sigma,
272            };
273            if record {
274                self.ledger.push(entry);
275            }
276            return LeakAlert::no_alert(n, 1.0, 0.0, 0.0);
277        }
278
279        // --- CUSUM (two-sided) ---
280        // S⁺ detects upward mean shift (leak/regression).
281        // S⁻ detects downward mean shift (improvement/fix).
282        self.cusum_upper = (self.cusum_upper + residual - self.config.cusum_allowance).max(0.0);
283        self.cusum_lower = (self.cusum_lower - residual - self.config.cusum_allowance).max(0.0);
284
285        let cusum_triggered = self.cusum_upper > self.config.cusum_threshold
286            || self.cusum_lower > self.config.cusum_threshold;
287
288        // --- E-process (sub-Gaussian likelihood ratio) ---
289        // E_t = E_{t-1} × exp(λ r_t − λ² / 2)
290        // where r_t is the standardised residual.
291        let lambda = self.config.lambda;
292        let log_factor = lambda * residual - (lambda * lambda) / 2.0;
293        // Clamp to prevent overflow.
294        let log_factor = if log_factor.is_nan() { 0.0 } else { log_factor };
295        let factor = log_factor.clamp(-10.0, 10.0).exp();
296        self.e_value = (self.e_value * factor).min(f64::MAX);
297
298        let threshold = 1.0 / self.config.alpha;
299        let eprocess_triggered = self.e_value >= threshold;
300
301        let triggered = cusum_triggered || eprocess_triggered;
302
303        let entry = EvidenceEntry {
304            frame: n,
305            value,
306            residual,
307            cusum_upper: self.cusum_upper,
308            cusum_lower: self.cusum_lower,
309            e_value: self.e_value,
310            mean_estimate: self.mean,
311            sigma_estimate: sigma,
312        };
313        if record {
314            self.ledger.push(entry);
315        }
316
317        LeakAlert {
318            triggered,
319            cusum_triggered,
320            eprocess_triggered,
321            e_value: self.e_value,
322            cusum_upper: self.cusum_upper,
323            cusum_lower: self.cusum_lower,
324            frame: n,
325        }
326    }
327
328    /// Current e-process value (evidence against H₀).
329    #[must_use]
330    pub fn e_value(&self) -> f64 {
331        self.e_value
332    }
333
334    /// Current CUSUM upper statistic.
335    #[must_use]
336    pub fn cusum_upper(&self) -> f64 {
337        self.cusum_upper
338    }
339
340    /// Current CUSUM lower statistic.
341    #[must_use]
342    pub fn cusum_lower(&self) -> f64 {
343        self.cusum_lower
344    }
345
346    /// Current mean estimate.
347    #[must_use]
348    pub fn mean(&self) -> f64 {
349        self.mean
350    }
351
352    /// Current σ estimate.
353    #[must_use]
354    pub fn sigma(&self) -> f64 {
355        self.sigma_ema.max(self.config.sigma_floor)
356    }
357
358    /// Total frames observed.
359    #[must_use]
360    pub fn frames(&self) -> usize {
361        self.frames
362    }
363
364    /// Access the full evidence ledger.
365    #[must_use]
366    pub fn ledger(&self) -> &[EvidenceEntry] {
367        &self.ledger
368    }
369
370    /// E-process threshold (1/α).
371    #[must_use]
372    pub fn threshold(&self) -> f64 {
373        1.0 / self.config.alpha
374    }
375
376    /// CUSUM threshold for either directional statistic.
377    #[must_use]
378    pub fn cusum_threshold(&self) -> f64 {
379        self.config.cusum_threshold
380    }
381
382    /// Reset detector state (preserves config).
383    pub fn reset(&mut self) {
384        self.mean = 0.0;
385        self.m2 = 0.0;
386        self.sigma_ema = 0.0;
387        self.cusum_upper = 0.0;
388        self.cusum_lower = 0.0;
389        self.e_value = 1.0;
390        self.frames = 0;
391        self.ledger.clear();
392    }
393}
394
395// =========================================================================
396// Tests
397// =========================================================================
398
399#[cfg(test)]
400mod tests {
401    use super::*;
402
403    #[test]
404    fn unrecorded_observations_match_recorded_without_growing_ledger() {
405        let mut recorded = default_detector();
406        let mut unrecorded = default_detector();
407        for i in 0..4000 {
408            let value = if i < 200 { 1024.0 } else { i as f64 * 1024.0 };
409            let expected = recorded.observe(value);
410            let actual = unrecorded.observe_unrecorded(value);
411            assert_eq!(actual.triggered, expected.triggered);
412            assert_eq!(actual.e_value, expected.e_value);
413            assert_eq!(actual.cusum_upper, expected.cusum_upper);
414            assert_eq!(actual.cusum_lower, expected.cusum_lower);
415            assert!(actual.e_value.is_finite());
416            assert!(unrecorded.ledger().is_empty());
417        }
418        assert_eq!(recorded.ledger().len(), 4000);
419        assert_eq!(unrecorded.frames(), 4000);
420    }
421
422    fn default_detector() -> AllocLeakDetector {
423        AllocLeakDetector::new(LeakDetectorConfig::default())
424    }
425
426    fn detector_with(alpha: f64, lambda: f64, warmup: usize) -> AllocLeakDetector {
427        AllocLeakDetector::new(LeakDetectorConfig {
428            alpha,
429            lambda,
430            warmup_frames: warmup,
431            ..LeakDetectorConfig::default()
432        })
433    }
434
435    /// Deterministic LCG for reproducible tests.
436    struct Lcg(u64);
437    impl Lcg {
438        fn new(seed: u64) -> Self {
439            Self(seed)
440        }
441        fn next_u64(&mut self) -> u64 {
442            self.0 = self
443                .0
444                .wrapping_mul(6_364_136_223_846_793_005)
445                .wrapping_add(1);
446            self.0
447        }
448        /// Pseudo-normal via CLT (sum of 12 uniforms − 6).
449        fn next_normal(&mut self, mean: f64, std: f64) -> f64 {
450            let sum: f64 = (0..12)
451                .map(|_| (self.next_u64() as f64) / (u64::MAX as f64))
452                .sum();
453            mean + std * (sum - 6.0)
454        }
455    }
456
457    // --- Basic functionality ---
458
459    #[test]
460    fn new_detector_starts_clean() {
461        let d = default_detector();
462        assert_eq!(d.frames(), 0);
463        assert!((d.e_value() - 1.0).abs() < f64::EPSILON);
464        assert_eq!(d.cusum_upper(), 0.0);
465        assert_eq!(d.cusum_lower(), 0.0);
466        assert!(d.ledger().is_empty());
467    }
468
469    #[test]
470    fn warmup_does_not_trigger() {
471        let mut d = default_detector();
472        for i in 0..30 {
473            let alert = d.observe(100.0 + (i as f64) * 0.5);
474            assert!(
475                !alert.triggered,
476                "Should not trigger during warmup (frame {})",
477                i + 1
478            );
479        }
480        assert_eq!(d.frames(), 30);
481    }
482
483    #[test]
484    fn stable_run_no_alert() {
485        let mut rng = Lcg::new(0xCAFE);
486        let mut d = default_detector();
487
488        for _ in 0..500 {
489            let v = rng.next_normal(100.0, 5.0);
490            let alert = d.observe(v);
491            assert!(
492                !alert.triggered,
493                "Stable run should not trigger: frame={}, e={:.4}, cusum_up={:.4}",
494                alert.frame, alert.e_value, alert.cusum_upper,
495            );
496        }
497    }
498
499    // --- CUSUM detection ---
500
501    #[test]
502    fn unit_cusum_detects_shift() {
503        let mut d = detector_with(0.05, 0.2, 20);
504
505        // 20 warmup frames at baseline 100.
506        for _ in 0..20 {
507            d.observe(100.0);
508        }
509
510        // Inject a sustained upward shift of +10.
511        let mut detected = false;
512        for i in 0..200 {
513            let alert = d.observe(110.0);
514            if alert.cusum_triggered {
515                detected = true;
516                assert!(
517                    i < 50,
518                    "CUSUM should detect shift within 50 frames, took {}",
519                    i
520                );
521                break;
522            }
523        }
524        assert!(detected, "CUSUM failed to detect +10 mean shift");
525    }
526
527    #[test]
528    fn cusum_detects_downward_shift() {
529        let mut d = detector_with(0.05, 0.2, 20);
530
531        for _ in 0..20 {
532            d.observe(100.0);
533        }
534
535        let mut detected = false;
536        for i in 0..200 {
537            let alert = d.observe(90.0);
538            if alert.cusum_lower > d.config.cusum_threshold {
539                detected = true;
540                assert!(
541                    i < 50,
542                    "CUSUM should detect downward shift within 50 frames"
543                );
544                break;
545            }
546        }
547        assert!(detected, "CUSUM failed to detect -10 mean shift");
548    }
549
550    // --- E-process detection ---
551
552    #[test]
553    fn unit_eprocess_threshold() {
554        let mut d = detector_with(0.05, 0.3, 10);
555
556        // 10 warmup frames at baseline.
557        for _ in 0..10 {
558            d.observe(100.0);
559        }
560
561        // Sustained leak: allocations grow by 20%.
562        let mut detected = false;
563        for i in 0..300 {
564            let alert = d.observe(120.0);
565            if alert.eprocess_triggered {
566                detected = true;
567                assert!(
568                    alert.e_value >= d.threshold(),
569                    "E-value {:.2} should exceed threshold {:.2}",
570                    alert.e_value,
571                    d.threshold()
572                );
573                assert!(
574                    i < 150,
575                    "E-process should detect within 150 frames, took {}",
576                    i
577                );
578                break;
579            }
580        }
581        assert!(detected, "E-process failed to detect sustained leak");
582    }
583
584    #[test]
585    fn eprocess_value_bounded_under_null() {
586        let mut rng = Lcg::new(0xBEEF);
587        let mut d = detector_with(0.05, 0.2, 20);
588
589        // Long stable run.
590        for _ in 0..1000 {
591            let v = rng.next_normal(100.0, 5.0);
592            d.observe(v);
593        }
594
595        // E-value should stay bounded (not explode) under H₀.
596        assert!(
597            d.e_value() < 100.0,
598            "E-value should stay bounded under null: got {:.2}",
599            d.e_value()
600        );
601    }
602
603    // --- False positive rate ---
604
605    #[test]
606    fn property_fpr_control() {
607        // Run many independent stable sequences. FPR should be ≤ α + tolerance.
608        let alpha = 0.10; // Higher α for tractable test.
609        let n_runs = 200;
610        let frames_per_run = 200;
611
612        let mut false_positives = 0;
613        let mut rng = Lcg::new(0xAAAA);
614
615        for _ in 0..n_runs {
616            let mut d = detector_with(alpha, 0.2, 20);
617            let mut triggered = false;
618
619            for _ in 0..frames_per_run {
620                let v = rng.next_normal(100.0, 5.0);
621                let alert = d.observe(v);
622                if alert.eprocess_triggered {
623                    triggered = true;
624                    break;
625                }
626            }
627            if triggered {
628                false_positives += 1;
629            }
630        }
631
632        let fpr = false_positives as f64 / n_runs as f64;
633        // Allow generous tolerance: FPR ≤ α + 0.10 (account for CLT-based pseudo-normal).
634        assert!(
635            fpr <= alpha + 0.10,
636            "Empirical FPR {:.3} exceeds α + tolerance ({:.3})",
637            fpr,
638            alpha + 0.10,
639        );
640    }
641
642    // --- Evidence ledger ---
643
644    #[test]
645    fn ledger_records_all_frames() {
646        let mut d = default_detector();
647        for i in 0..50 {
648            d.observe(100.0 + i as f64);
649        }
650        assert_eq!(d.ledger().len(), 50);
651        assert_eq!(d.ledger()[0].frame, 1);
652        assert_eq!(d.ledger()[49].frame, 50);
653    }
654
655    #[test]
656    fn ledger_jsonl_valid() {
657        let mut d = default_detector();
658        for _ in 0..40 {
659            d.observe(100.0);
660        }
661
662        for entry in d.ledger() {
663            let line = entry.to_jsonl();
664            assert!(
665                line.starts_with('{') && line.ends_with('}'),
666                "Bad JSONL: {}",
667                line
668            );
669            assert!(line.contains("\"frame\":"));
670            assert!(line.contains("\"value\":"));
671            assert!(line.contains("\"residual\":"));
672            assert!(line.contains("\"cusum_upper\":"));
673            assert!(line.contains("\"e_value\":"));
674        }
675    }
676
677    #[test]
678    fn ledger_residuals_sum_near_zero_under_null() {
679        let mut rng = Lcg::new(0x1234);
680        let mut d = detector_with(0.05, 0.2, 20);
681
682        for _ in 0..500 {
683            d.observe(rng.next_normal(100.0, 5.0));
684        }
685
686        // Post-warmup residuals should approximately sum to zero.
687        let post_warmup: Vec<f64> = d.ledger()[20..].iter().map(|e| e.residual).collect();
688        let mean_residual: f64 = post_warmup.iter().sum::<f64>() / post_warmup.len() as f64;
689        assert!(
690            mean_residual.abs() < 0.5,
691            "Mean residual should be near zero: got {:.4}",
692            mean_residual
693        );
694    }
695
696    // --- Reset ---
697
698    #[test]
699    fn reset_clears_state() {
700        let mut d = default_detector();
701        for _ in 0..100 {
702            d.observe(100.0);
703        }
704        d.reset();
705        assert_eq!(d.frames(), 0);
706        assert!((d.e_value() - 1.0).abs() < f64::EPSILON);
707        assert_eq!(d.cusum_upper(), 0.0);
708        assert!(d.ledger().is_empty());
709    }
710
711    // --- E2E: synthetic leak injection ---
712
713    #[test]
714    fn e2e_synthetic_leak_detected() {
715        let mut rng = Lcg::new(0x5678);
716        let mut d = default_detector();
717
718        // Phase 1: 50 stable frames.
719        for _ in 0..50 {
720            d.observe(rng.next_normal(100.0, 3.0));
721        }
722        assert!(!d.ledger().last().unwrap().e_value.is_nan());
723
724        // Phase 2: inject leak (gradual increase of 0.5 per frame).
725        let mut detected_frame = None;
726        for i in 0..200 {
727            let leak = 0.5 * i as f64;
728            let v = rng.next_normal(100.0 + leak, 3.0);
729            let alert = d.observe(v);
730            if alert.triggered && detected_frame.is_none() {
731                detected_frame = Some(alert.frame);
732            }
733        }
734
735        assert!(
736            detected_frame.is_some(),
737            "Detector should catch gradual leak"
738        );
739
740        // Generate JSONL summary.
741        let last = d.ledger().last().unwrap();
742        let summary = format!(
743            r#"{{"test":"e2e_synthetic_leak","detected_frame":{},"total_frames":{},"final_e_value":{:.4},"final_cusum_upper":{:.4}}}"#,
744            detected_frame.unwrap(),
745            d.frames(),
746            last.e_value,
747            last.cusum_upper,
748        );
749        assert!(summary.contains("\"detected_frame\":"));
750    }
751
752    #[test]
753    fn e2e_stable_run_no_alerts() {
754        let mut rng = Lcg::new(0x9999);
755        let mut d = default_detector();
756
757        let mut any_alert = false;
758        for _ in 0..500 {
759            let v = rng.next_normal(200.0, 10.0);
760            let alert = d.observe(v);
761            if alert.triggered {
762                any_alert = true;
763            }
764        }
765
766        assert!(!any_alert, "Stable run should produce no alerts");
767
768        // E-value should stay bounded.
769        let max_e = d.ledger().iter().map(|e| e.e_value).fold(0.0f64, f64::max);
770        assert!(
771            max_e < d.threshold(),
772            "Max e-value {:.4} should stay below threshold {:.4}",
773            max_e,
774            d.threshold()
775        );
776    }
777
778    // --- Edge cases ---
779
780    #[test]
781    fn constant_input_no_trigger() {
782        let mut d = default_detector();
783        for _ in 0..200 {
784            let alert = d.observe(42.0);
785            assert!(
786                !alert.triggered,
787                "Constant input should never trigger: frame={}",
788                alert.frame
789            );
790        }
791    }
792
793    #[test]
794    fn zero_input_no_panic() {
795        let mut d = default_detector();
796        for _ in 0..50 {
797            let alert = d.observe(0.0);
798            assert!(!alert.e_value.is_nan(), "E-value should not be NaN");
799        }
800    }
801
802    #[test]
803    fn single_observation() {
804        let mut d = default_detector();
805        let alert = d.observe(100.0);
806        assert!(!alert.triggered);
807        assert_eq!(d.frames(), 1);
808    }
809
810    #[test]
811    fn sigma_floor_prevents_explosion() {
812        let config = LeakDetectorConfig {
813            sigma_floor: 1.0,
814            warmup_frames: 5,
815            ..LeakDetectorConfig::default()
816        };
817        let mut d = AllocLeakDetector::new(config);
818
819        // Constant input → Welford σ = 0, but floor should prevent issues.
820        for _ in 0..50 {
821            let alert = d.observe(100.0);
822            assert!(!alert.e_value.is_nan());
823            assert!(!alert.e_value.is_infinite());
824        }
825    }
826
827    #[test]
828    fn detection_speed_proportional_to_shift() {
829        // Larger shifts should be detected faster.
830        let detect_at = |shift: f64| -> usize {
831            let mut d = detector_with(0.05, 0.2, 20);
832            for _ in 0..20 {
833                d.observe(100.0);
834            }
835            for i in 0..500 {
836                let alert = d.observe(100.0 + shift);
837                if alert.triggered {
838                    return i;
839                }
840            }
841            500
842        };
843
844        let small_shift = detect_at(5.0);
845        let large_shift = detect_at(20.0);
846
847        assert!(
848            large_shift <= small_shift,
849            "Large shift ({}) should detect no later than small shift ({})",
850            large_shift,
851            small_shift
852        );
853    }
854
855    // --- Config defaults ---
856
857    #[test]
858    fn config_default_field_values() {
859        let c = LeakDetectorConfig::default();
860        assert!((c.alpha - 0.05).abs() < f64::EPSILON);
861        assert!((c.lambda - 0.2).abs() < f64::EPSILON);
862        assert!((c.cusum_threshold - 8.0).abs() < f64::EPSILON);
863        assert!((c.cusum_allowance - 0.5).abs() < f64::EPSILON);
864        assert_eq!(c.warmup_frames, 30);
865        assert!((c.sigma_decay - 0.95).abs() < f64::EPSILON);
866        assert!((c.sigma_floor - 1.0).abs() < f64::EPSILON);
867    }
868
869    #[test]
870    fn config_clone_is_independent() {
871        let c1 = LeakDetectorConfig::default();
872        let c2 = c1.clone();
873        // Clone should have the same values as the original.
874        assert!((c2.alpha - c1.alpha).abs() < f64::EPSILON);
875        assert!((c2.lambda - c1.lambda).abs() < f64::EPSILON);
876        assert_eq!(c2.warmup_frames, c1.warmup_frames);
877    }
878
879    #[test]
880    fn config_debug_contains_fields() {
881        let c = LeakDetectorConfig::default();
882        let dbg = format!("{c:?}");
883        assert!(dbg.contains("alpha"));
884        assert!(dbg.contains("lambda"));
885        assert!(dbg.contains("cusum_threshold"));
886    }
887
888    // --- Accessor methods ---
889
890    #[test]
891    fn mean_tracks_input() {
892        let mut d = default_detector();
893        d.observe(10.0);
894        assert!((d.mean() - 10.0).abs() < f64::EPSILON);
895        d.observe(20.0);
896        assert!((d.mean() - 15.0).abs() < f64::EPSILON);
897        d.observe(30.0);
898        assert!((d.mean() - 20.0).abs() < f64::EPSILON);
899    }
900
901    #[test]
902    fn sigma_respects_floor() {
903        let config = LeakDetectorConfig {
904            sigma_floor: 5.0,
905            ..LeakDetectorConfig::default()
906        };
907        let mut d = AllocLeakDetector::new(config);
908        // Constant input → Welford σ = 0, but sigma() should return floor.
909        d.observe(100.0);
910        assert!(d.sigma() >= 5.0, "sigma should be at least the floor");
911    }
912
913    #[test]
914    fn threshold_is_inverse_alpha() {
915        let d = detector_with(0.05, 0.2, 20);
916        assert!((d.threshold() - 20.0).abs() < f64::EPSILON);
917
918        let d2 = detector_with(0.10, 0.2, 20);
919        assert!((d2.threshold() - 10.0).abs() < f64::EPSILON);
920
921        let d3 = detector_with(0.01, 0.2, 20);
922        assert!((d3.threshold() - 100.0).abs() < f64::EPSILON);
923    }
924
925    #[test]
926    fn frames_increments_per_observe() {
927        let mut d = default_detector();
928        assert_eq!(d.frames(), 0);
929        d.observe(1.0);
930        assert_eq!(d.frames(), 1);
931        d.observe(2.0);
932        assert_eq!(d.frames(), 2);
933        for _ in 0..98 {
934            d.observe(3.0);
935        }
936        assert_eq!(d.frames(), 100);
937    }
938
939    #[test]
940    fn cusum_lower_accessor_matches_alert() {
941        let mut d = detector_with(0.05, 0.2, 5);
942        for _ in 0..5 {
943            d.observe(100.0);
944        }
945        let alert = d.observe(50.0); // big downward shift
946        assert!((d.cusum_lower() - alert.cusum_lower).abs() < f64::EPSILON);
947    }
948
949    // --- Reset and reuse ---
950
951    #[test]
952    fn reset_then_reuse_works() {
953        let mut d = default_detector();
954        for _ in 0..50 {
955            d.observe(100.0);
956        }
957        d.reset();
958
959        // After reset, detector should behave like new.
960        assert_eq!(d.frames(), 0);
961        assert!((d.mean() - 0.0).abs() < f64::EPSILON);
962        assert!(d.ledger().is_empty());
963
964        // Feed new data — should work correctly.
965        for _ in 0..50 {
966            let alert = d.observe(200.0);
967            assert!(!alert.triggered);
968        }
969        assert_eq!(d.frames(), 50);
970        assert!((d.mean() - 200.0).abs() < 1.0);
971    }
972
973    #[test]
974    fn reset_clears_cusum_lower() {
975        let mut d = default_detector();
976        for _ in 0..50 {
977            d.observe(100.0);
978        }
979        // Force cusum_lower to rise with downward shift.
980        for _ in 0..20 {
981            d.observe(50.0);
982        }
983        assert!(d.cusum_lower() > 0.0, "cusum_lower should have risen");
984        d.reset();
985        assert_eq!(d.cusum_lower(), 0.0);
986    }
987
988    // --- EvidenceEntry ---
989
990    #[test]
991    fn evidence_entry_clone_is_independent() {
992        let e1 = EvidenceEntry {
993            frame: 1,
994            value: 100.0,
995            residual: 0.5,
996            cusum_upper: 1.0,
997            cusum_lower: 0.0,
998            e_value: 1.2,
999            mean_estimate: 99.0,
1000            sigma_estimate: 5.0,
1001        };
1002        let e2 = e1.clone();
1003        assert_eq!(e2.frame, 1);
1004        assert!((e2.value - 100.0).abs() < f64::EPSILON);
1005        assert!((e2.residual - 0.5).abs() < f64::EPSILON);
1006    }
1007
1008    #[test]
1009    fn evidence_entry_debug_format() {
1010        let e = EvidenceEntry {
1011            frame: 42,
1012            value: 100.0,
1013            residual: 0.123,
1014            cusum_upper: 2.5,
1015            cusum_lower: 0.1,
1016            e_value: 1.5,
1017            mean_estimate: 99.5,
1018            sigma_estimate: 3.0,
1019        };
1020        let dbg = format!("{e:?}");
1021        assert!(dbg.contains("frame: 42"));
1022        assert!(dbg.contains("100.0"));
1023    }
1024
1025    #[test]
1026    fn jsonl_field_values_accurate() {
1027        let e = EvidenceEntry {
1028            frame: 7,
1029            value: 123.45,
1030            residual: -0.5678,
1031            cusum_upper: 3.25,
1032            cusum_lower: 0.0,
1033            e_value: 2.75,
1034            mean_estimate: 120.00,
1035            sigma_estimate: 4.5678,
1036        };
1037        let line = e.to_jsonl();
1038        assert!(line.contains("\"frame\":7"));
1039        assert!(line.contains("\"value\":123.45"));
1040        assert!(line.contains("\"residual\":-0.5678"));
1041        assert!(line.contains("\"cusum_upper\":3.2500"));
1042        assert!(line.contains("\"cusum_lower\":0.0000"));
1043        assert!(line.contains("\"mean\":120.00"));
1044        assert!(line.contains("\"sigma\":4.5678"));
1045    }
1046
1047    #[test]
1048    fn jsonl_contains_e_value_key() {
1049        let e = EvidenceEntry {
1050            frame: 1,
1051            value: 0.0,
1052            residual: 0.0,
1053            cusum_upper: 0.0,
1054            cusum_lower: 0.0,
1055            e_value: 1.0,
1056            mean_estimate: 0.0,
1057            sigma_estimate: 1.0,
1058        };
1059        let line = e.to_jsonl();
1060        assert!(line.contains("\"e_value\":1.000000"));
1061    }
1062
1063    // --- LeakAlert ---
1064
1065    #[test]
1066    fn leak_alert_no_alert_fields() {
1067        let alert = LeakAlert::no_alert(42, 1.5, 3.0, 0.5);
1068        assert!(!alert.triggered);
1069        assert!(!alert.cusum_triggered);
1070        assert!(!alert.eprocess_triggered);
1071        assert_eq!(alert.frame, 42);
1072        assert!((alert.e_value - 1.5).abs() < f64::EPSILON);
1073        assert!((alert.cusum_upper - 3.0).abs() < f64::EPSILON);
1074        assert!((alert.cusum_lower - 0.5).abs() < f64::EPSILON);
1075    }
1076
1077    #[test]
1078    fn leak_alert_clone() {
1079        let a1 = LeakAlert::no_alert(1, 2.0, 3.0, 4.0);
1080        let a2 = a1.clone();
1081        assert_eq!(a2.frame, 1);
1082        assert!(!a2.triggered);
1083    }
1084
1085    #[test]
1086    fn leak_alert_debug() {
1087        let a = LeakAlert::no_alert(10, 1.0, 0.0, 0.0);
1088        let dbg = format!("{a:?}");
1089        assert!(dbg.contains("triggered: false"));
1090        assert!(dbg.contains("frame: 10"));
1091    }
1092
1093    // --- Warmup boundary ---
1094
1095    #[test]
1096    fn warmup_boundary_exact() {
1097        let mut d = detector_with(0.05, 0.2, 5);
1098        // Frames 1..=5 are warmup — cusum/eprocess should be inert.
1099        for i in 1..=5 {
1100            let alert = d.observe(100.0);
1101            assert!(!alert.triggered, "warmup frame {i} should not trigger");
1102            assert!((alert.cusum_upper - 0.0).abs() < f64::EPSILON);
1103            assert!((alert.e_value - 1.0).abs() < f64::EPSILON);
1104        }
1105        // Frame 6 is the first post-warmup frame — detectors start running.
1106        let alert = d.observe(100.0);
1107        assert_eq!(alert.frame, 6);
1108        // Cusum/eprocess should now be active (though may still be near 0 for stable input).
1109        assert!(!alert.triggered);
1110    }
1111
1112    #[test]
1113    fn warmup_zero_frames() {
1114        let mut d = detector_with(0.05, 0.2, 0);
1115        // With warmup_frames=0, first observation should go through full detector.
1116        let alert = d.observe(100.0);
1117        assert_eq!(alert.frame, 1);
1118        // E-value and cusum should be computed (not the warmup defaults).
1119        assert!(!alert.e_value.is_nan());
1120    }
1121
1122    // --- Warmup ledger entries ---
1123
1124    #[test]
1125    fn warmup_ledger_entries_have_zero_cusum() {
1126        let mut d = detector_with(0.05, 0.2, 10);
1127        for _ in 0..10 {
1128            d.observe(100.0);
1129        }
1130        for entry in d.ledger() {
1131            assert!((entry.cusum_upper - 0.0).abs() < f64::EPSILON);
1132            assert!((entry.cusum_lower - 0.0).abs() < f64::EPSILON);
1133            assert!((entry.e_value - 1.0).abs() < f64::EPSILON);
1134        }
1135    }
1136
1137    // --- NaN / Infinity handling ---
1138
1139    #[test]
1140    fn nan_input_does_not_panic() {
1141        let mut d = default_detector();
1142        for _ in 0..10 {
1143            d.observe(100.0);
1144        }
1145        // NaN input should not panic.
1146        let _alert = d.observe(f64::NAN);
1147        assert_eq!(d.frames(), 11);
1148    }
1149
1150    #[test]
1151    fn infinity_input_does_not_panic() {
1152        let mut d = default_detector();
1153        for _ in 0..10 {
1154            d.observe(100.0);
1155        }
1156        let _alert = d.observe(f64::INFINITY);
1157        assert_eq!(d.frames(), 11);
1158    }
1159
1160    #[test]
1161    fn negative_infinity_input_does_not_panic() {
1162        let mut d = default_detector();
1163        for _ in 0..10 {
1164            d.observe(100.0);
1165        }
1166        let _alert = d.observe(f64::NEG_INFINITY);
1167        assert_eq!(d.frames(), 11);
1168    }
1169
1170    // --- Oscillating input ---
1171
1172    #[test]
1173    fn oscillating_values_no_trigger() {
1174        let mut d = default_detector();
1175        // Alternating high/low with mean ~100, should not trigger.
1176        for i in 0..300 {
1177            let v = if i % 2 == 0 { 105.0 } else { 95.0 };
1178            let alert = d.observe(v);
1179            assert!(
1180                !alert.triggered,
1181                "Oscillating input should not trigger: frame={}",
1182                alert.frame
1183            );
1184        }
1185    }
1186
1187    // --- Very large values ---
1188
1189    #[test]
1190    fn very_large_values_no_panic() {
1191        let mut d = default_detector();
1192        for _ in 0..50 {
1193            d.observe(1e15);
1194        }
1195        assert_eq!(d.frames(), 50);
1196        assert!(!d.mean().is_nan());
1197    }
1198
1199    #[test]
1200    fn very_small_values_no_panic() {
1201        let mut d = default_detector();
1202        for _ in 0..50 {
1203            d.observe(1e-15);
1204        }
1205        assert_eq!(d.frames(), 50);
1206        assert!(!d.mean().is_nan());
1207    }
1208
1209    // --- Both detectors trigger ---
1210
1211    #[test]
1212    fn both_detectors_can_trigger_simultaneously() {
1213        let mut d = detector_with(0.05, 0.5, 5);
1214        for _ in 0..5 {
1215            d.observe(100.0);
1216        }
1217        // Massive shift should trigger both.
1218        let mut both_triggered = false;
1219        for _ in 0..500 {
1220            let alert = d.observe(200.0);
1221            if alert.cusum_triggered && alert.eprocess_triggered {
1222                both_triggered = true;
1223                assert!(alert.triggered);
1224                break;
1225            }
1226        }
1227        assert!(
1228            both_triggered,
1229            "Both detectors should trigger on massive shift"
1230        );
1231    }
1232
1233    // --- CUSUM resets toward zero after shift disappears ---
1234
1235    #[test]
1236    fn cusum_recovers_after_transient_spike() {
1237        let mut d = detector_with(0.05, 0.2, 10);
1238        for _ in 0..10 {
1239            d.observe(100.0);
1240        }
1241        // Brief spike.
1242        for _ in 0..3 {
1243            d.observe(120.0);
1244        }
1245        let spike_cusum = d.cusum_upper();
1246        // Return to baseline — cusum should decrease.
1247        for _ in 0..50 {
1248            d.observe(100.0);
1249        }
1250        assert!(
1251            d.cusum_upper() < spike_cusum,
1252            "CUSUM should decrease after return to baseline"
1253        );
1254    }
1255
1256    // --- E-process accumulates under H1 ---
1257
1258    #[test]
1259    fn eprocess_grows_under_sustained_shift() {
1260        let mut d = detector_with(0.05, 0.2, 10);
1261        for _ in 0..10 {
1262            d.observe(100.0);
1263        }
1264        let e_before = d.e_value();
1265        // Sustained upward shift.
1266        for _ in 0..50 {
1267            d.observe(115.0);
1268        }
1269        assert!(
1270            d.e_value() > e_before,
1271            "E-process should grow under sustained shift"
1272        );
1273    }
1274
1275    // --- Ledger entry field accuracy ---
1276
1277    #[test]
1278    fn ledger_entry_mean_estimate_converges() {
1279        let mut d = default_detector();
1280        for _ in 0..200 {
1281            d.observe(50.0);
1282        }
1283        let last = d.ledger().last().unwrap();
1284        assert!(
1285            (last.mean_estimate - 50.0).abs() < 0.01,
1286            "Mean estimate should converge to 50.0, got {:.4}",
1287            last.mean_estimate
1288        );
1289    }
1290
1291    #[test]
1292    fn ledger_entry_sigma_estimate_is_positive() {
1293        let mut rng = Lcg::new(0xDEAD);
1294        let mut d = default_detector();
1295        for _ in 0..100 {
1296            d.observe(rng.next_normal(100.0, 5.0));
1297        }
1298        for entry in d.ledger() {
1299            assert!(
1300                entry.sigma_estimate > 0.0,
1301                "Sigma estimate should be positive at frame {}",
1302                entry.frame
1303            );
1304        }
1305    }
1306
1307    #[test]
1308    fn ledger_entries_have_sequential_frames() {
1309        let mut d = default_detector();
1310        for _ in 0..50 {
1311            d.observe(100.0);
1312        }
1313        for (i, entry) in d.ledger().iter().enumerate() {
1314            assert_eq!(entry.frame, i + 1, "Frame should be sequential");
1315        }
1316    }
1317
1318    // --- Lcg reproducibility ---
1319
1320    #[test]
1321    fn lcg_is_deterministic() {
1322        let mut rng1 = Lcg::new(42);
1323        let mut rng2 = Lcg::new(42);
1324        for _ in 0..100 {
1325            assert_eq!(rng1.next_u64(), rng2.next_u64());
1326        }
1327    }
1328
1329    #[test]
1330    fn lcg_different_seeds_differ() {
1331        let mut rng1 = Lcg::new(1);
1332        let mut rng2 = Lcg::new(2);
1333        let v1 = rng1.next_u64();
1334        let v2 = rng2.next_u64();
1335        assert_ne!(v1, v2);
1336    }
1337
1338    #[test]
1339    fn lcg_next_normal_centered() {
1340        let mut rng = Lcg::new(0xFACE);
1341        let mut sum = 0.0;
1342        let n = 10_000;
1343        for _ in 0..n {
1344            sum += rng.next_normal(50.0, 10.0);
1345        }
1346        let mean = sum / n as f64;
1347        assert!(
1348            (mean - 50.0).abs() < 1.0,
1349            "CLT-based normal mean should be near 50.0, got {mean:.2}"
1350        );
1351    }
1352
1353    // --- Negative values ---
1354
1355    #[test]
1356    fn negative_observations_work() {
1357        let mut d = default_detector();
1358        for _ in 0..50 {
1359            d.observe(-100.0);
1360        }
1361        assert!((d.mean() - (-100.0)).abs() < 0.01);
1362        assert_eq!(d.frames(), 50);
1363    }
1364
1365    // --- AllocLeakDetector Debug ---
1366
1367    #[test]
1368    fn detector_debug_format() {
1369        let d = default_detector();
1370        let dbg = format!("{d:?}");
1371        assert!(dbg.contains("AllocLeakDetector"));
1372        assert!(dbg.contains("mean"));
1373        assert!(dbg.contains("e_value"));
1374    }
1375
1376    // --- E-value starts at 1.0 ---
1377
1378    #[test]
1379    fn evalue_starts_at_one_and_stays_during_warmup() {
1380        let mut d = detector_with(0.05, 0.2, 10);
1381        assert!((d.e_value() - 1.0).abs() < f64::EPSILON);
1382        for _ in 0..10 {
1383            d.observe(100.0);
1384        }
1385        // E-value should still be 1.0 after warmup (not updated during warmup).
1386        assert!((d.e_value() - 1.0).abs() < f64::EPSILON);
1387    }
1388
1389    // --- Custom config combinations ---
1390
1391    #[test]
1392    fn high_alpha_triggers_more_easily() {
1393        // α=0.5 → threshold=2.0 (very low), should trigger quickly.
1394        let mut d = detector_with(0.5, 0.3, 5);
1395        for _ in 0..5 {
1396            d.observe(100.0);
1397        }
1398        let mut triggered = false;
1399        for _ in 0..100 {
1400            let alert = d.observe(110.0);
1401            if alert.eprocess_triggered {
1402                triggered = true;
1403                break;
1404            }
1405        }
1406        assert!(
1407            triggered,
1408            "High alpha (low threshold) should trigger on small shift"
1409        );
1410    }
1411
1412    #[test]
1413    fn small_lambda_accumulates_slower() {
1414        // Compare detection speed with different lambda values.
1415        let detect_frames = |lambda: f64| -> usize {
1416            let mut d = detector_with(0.05, lambda, 10);
1417            for _ in 0..10 {
1418                d.observe(100.0);
1419            }
1420            for i in 0..500 {
1421                let alert = d.observe(115.0);
1422                if alert.eprocess_triggered {
1423                    return i;
1424                }
1425            }
1426            500
1427        };
1428        let fast = detect_frames(0.4);
1429        let slow = detect_frames(0.1);
1430        // Smaller lambda should generally detect slower or equal.
1431        assert!(
1432            fast <= slow + 20,
1433            "Higher lambda should detect at least comparably fast: fast={fast}, slow={slow}"
1434        );
1435    }
1436
1437    // --- Welford mean correctness ---
1438
1439    #[test]
1440    fn welford_mean_matches_exact_mean() {
1441        let mut d = default_detector();
1442        let values = [10.0, 20.0, 30.0, 40.0, 50.0];
1443        for &v in &values {
1444            d.observe(v);
1445        }
1446        let expected = values.iter().sum::<f64>() / values.len() as f64;
1447        assert!(
1448            (d.mean() - expected).abs() < 1e-10,
1449            "Welford mean {:.4} should match exact mean {:.4}",
1450            d.mean(),
1451            expected
1452        );
1453    }
1454}