Skip to main content

ftui_render/
diff_strategy.rs

1#![forbid(unsafe_code)]
2
3//! Bayesian Diff Strategy Selection.
4//!
5//! This module provides an adaptive strategy selector for buffer diffing,
6//! choosing between full diff, dirty-row diff, or full redraw based on
7//! expected cost using a Bayesian change-rate model.
8//!
9//! # Cost Model
10//!
11//! We model the cost of each strategy as:
12//!
13//! ```text
14//! Cost = c_scan × cells_scanned + c_emit × cells_emitted + c_overhead
15//! ```
16//!
17//! Where:
18//! - `c_scan` = cost per cell comparison (memory load + compare)
19//! - `c_emit` = cost per changed cell emitted (ANSI escape + write)
20//! - `c_overhead` = fixed overhead per frame
21//!
22//! ## Strategy Costs
23//!
24//! Let:
25//! - `N = width × height` (total cells)
26//! - `D` = number of dirty rows
27//! - `W` = width (cells per row)
28//! - `p` = change rate (fraction of cells changed)
29//!
30//! ### Full Diff (`compute`)
31//!
32//! Scans all rows with row-skip fast path for unchanged rows:
33//!
34//! ```text
35//! Cost_full = c_row × H + c_scan × D × W + c_emit × (p × N)
36//! ```
37//!
38//! where `c_row` is the cost of the row-equality fast path check.
39//!
40//! ### Dirty-Row Diff (`compute_dirty`)
41//!
42//! Scans only rows marked dirty. When available, use a scan-cell estimate
43//! (e.g., dirty-span coverage) to refine the scan cost:
44//!
45//! ```text
46//! Cost_dirty = c_scan × ScanCells + c_emit × (p × N)
47//! ```
48//!
49//! Where `ScanCells` defaults to `D × W` when no estimate is provided.
50//!
51//! ### Full Redraw
52//!
53//! No diff computation; emit all cells:
54//!
55//! ```text
56//! Cost_redraw = c_emit × N
57//! ```
58//!
59//! # Bayesian Change-Rate Posterior
60//!
61//! We maintain a Beta prior/posterior over the change rate `p`:
62//!
63//! ```text
64//! p ~ Beta(α, β)
65//!
66//! Prior: α₀ = 1, β₀ = 19  (`E[p]` = 0.05, expecting ~5% change rate)
67//!
68//! Update per frame:
69//!   α ← α + N_changed
70//!   β ← β + (N_scanned - N_changed)
71//!
72//! Posterior mean: `E[p]` = α / (α + β)
73//! Posterior variance: `Var[p]` = αβ / ((α+β)² × (α+β+1))
74//! ```
75//!
76//! # Decision Rule
77//!
78//! Select strategy with minimum expected cost:
79//!
80//! ```text
81//! strategy = argmin { E[Cost_full], E[Cost_dirty], E[Cost_redraw] }
82//! ```
83//!
84//! Using `E[p]` from the posterior to compute expected costs.
85//!
86//! ## Conservative Mode
87//!
88//! For worst-case scenarios, use the upper 95th percentile of `p`:
89//!
90//! ```text
91//! p_95 = quantile(Beta(α, β), 0.95)
92//! ```
93//!
94//! This provides a more conservative estimate when the posterior variance
95//! is high (early frames, unstable UI).
96//!
97//! # Decay / Forgetting
98//!
99//! To adapt to changing workloads, we apply exponential decay:
100//!
101//! ```text
102//! α ← α × decay + N_changed
103//! β ← β × decay + (N_scanned - N_changed)
104//! ```
105//!
106//! where `decay ∈ (0, 1)` (default 0.95). This weights recent frames more
107//! heavily, allowing the posterior to track non-stationary change patterns.
108//!
109//! # Invariants
110//!
111//! 1. **Deterministic**: Same inputs → same strategy selection
112//! 2. **O(1) update**: Posterior update is constant time per frame
113//! 3. **Bounded posterior**: α, β ∈ [ε, MAX] to avoid numerical issues
114//! 4. **Monotonic dirty tracking**: Dirty rows are a superset of changed rows
115//!
116//! # Failure Modes
117//!
118//! | Condition | Behavior | Rationale |
119//! |-----------|----------|-----------|
120//! | α, β → 0 | Clamp to ε = 1e-6 | Avoid degenerate Beta |
121//! | α, β → ∞ | Cap at MAX = 1e6 | Prevent overflow |
122//! | D = 0 (no dirty) | Use dirty-row diff | O(height) check, optimal |
123//! | D = H (all dirty) | Full diff if p low, redraw if p high | Cost-based decision |
124//! | Dimension mismatch | Full redraw | Buffer resize scenario |
125
126use std::fmt;
127
128// =============================================================================
129// Configuration
130// =============================================================================
131
132/// Configuration for the diff strategy selector.
133#[derive(Debug, Clone)]
134pub struct DiffStrategyConfig {
135    /// Cost weight for cell scanning (relative units).
136    /// Default: 1.0
137    pub c_scan: f64,
138
139    /// Cost weight for cell emission (relative units).
140    /// Typically higher than c_scan since it involves I/O.
141    /// Default: 6.0
142    pub c_emit: f64,
143
144    /// Cost weight for row-equality fast path check.
145    /// Lower than full scan since it uses SIMD.
146    /// Default: 0.1
147    pub c_row: f64,
148
149    /// Prior α for Beta distribution (pseudo-count for "changed").
150    /// Default: 1.0 (uninformative prior weighted toward low change)
151    pub prior_alpha: f64,
152
153    /// Prior β for Beta distribution (pseudo-count for "unchanged").
154    /// Default: 19.0 (prior `E[p]` = 0.05)
155    pub prior_beta: f64,
156
157    /// Decay factor for exponential forgetting.
158    /// Range: (0, 1], where 1.0 means no decay.
159    /// Default: 0.95
160    pub decay: f64,
161
162    /// Whether to use conservative (upper quantile) estimates.
163    /// Default: false
164    pub conservative: bool,
165
166    /// Quantile for conservative mode (0.0 to 1.0).
167    /// Default: 0.95
168    pub conservative_quantile: f64,
169
170    /// Minimum cells changed to update posterior.
171    /// Prevents noise from near-zero observations.
172    /// Default: 1 (so `observe(0, 0)` is a no-op, pausing decay on empty frames)
173    pub min_observation_cells: usize,
174
175    /// Hysteresis ratio required to switch strategies.
176    ///
177    /// A value of 0.05 means the new strategy must be at least 5% cheaper
178    /// than the previous strategy to trigger a switch.
179    ///
180    /// Default: 0.05
181    pub hysteresis_ratio: f64,
182
183    /// Variance threshold for uncertainty guard.
184    ///
185    /// When posterior variance exceeds this threshold, the selector
186    /// uses conservative quantiles and avoids FullRedraw.
187    ///
188    /// Default: 0.002
189    pub uncertainty_guard_variance: f64,
190}
191
192impl Default for DiffStrategyConfig {
193    fn default() -> Self {
194        Self {
195            // Calibrated 2026-02-03 from `perf_diff_microbench`:
196            // scan cost ~0.008us/cell, emit cost ~0.05us/change -> ~6x ratio.
197            // Reproduce: `cargo test -p ftui-render diff::tests::perf_diff_microbench -- --nocapture`.
198            c_scan: 1.0,
199            c_emit: 6.0,
200            c_row: 0.1,
201            prior_alpha: 1.0,
202            prior_beta: 19.0,
203            decay: 0.95,
204            conservative: false,
205            conservative_quantile: 0.95,
206            min_observation_cells: 1,
207            hysteresis_ratio: 0.05,
208            uncertainty_guard_variance: 0.002,
209        }
210    }
211}
212
213impl DiffStrategyConfig {
214    fn sanitized(&self) -> Self {
215        const EPS: f64 = 1e-6;
216        let mut config = self.clone();
217        config.c_scan = normalize_cost(config.c_scan, 1.0);
218        config.c_emit = normalize_cost(config.c_emit, 6.0);
219        config.c_row = normalize_cost(config.c_row, 0.1);
220        config.prior_alpha = normalize_positive(config.prior_alpha, 1.0);
221        config.prior_beta = normalize_positive(config.prior_beta, 19.0);
222        config.decay = normalize_decay(config.decay);
223        config.conservative_quantile = if config.conservative_quantile.is_nan() {
224            EPS
225        } else {
226            config.conservative_quantile.clamp(EPS, 1.0 - EPS)
227        };
228        config.hysteresis_ratio = normalize_ratio(config.hysteresis_ratio, 0.05);
229        config.uncertainty_guard_variance =
230            normalize_cost(config.uncertainty_guard_variance, 0.002);
231        config
232    }
233}
234
235fn normalize_positive(value: f64, fallback: f64) -> f64 {
236    if value.is_finite() && value > 0.0 {
237        value
238    } else {
239        fallback
240    }
241}
242
243fn normalize_cost(value: f64, fallback: f64) -> f64 {
244    if value.is_finite() && value >= 0.0 {
245        value
246    } else {
247        fallback
248    }
249}
250
251fn normalize_decay(value: f64) -> f64 {
252    if value.is_finite() && value > 0.0 {
253        value.min(1.0)
254    } else {
255        1.0
256    }
257}
258
259fn normalize_ratio(value: f64, fallback: f64) -> f64 {
260    if value.is_finite() {
261        value.clamp(0.0, 1.0)
262    } else {
263        fallback
264    }
265}
266
267// =============================================================================
268// Change-Rate Estimator (Beta-Binomial)
269// =============================================================================
270
271/// Beta-Binomial estimator for change-rate `p`.
272///
273/// Maintains a Beta posterior with exponential decay and deterministic updates.
274#[derive(Debug, Clone)]
275pub struct ChangeRateEstimator {
276    prior_alpha: f64,
277    prior_beta: f64,
278    alpha: f64,
279    beta: f64,
280    decay: f64,
281    min_observation_cells: usize,
282}
283
284impl ChangeRateEstimator {
285    /// Create a new estimator with the given priors and decay.
286    pub fn new(
287        prior_alpha: f64,
288        prior_beta: f64,
289        decay: f64,
290        min_observation_cells: usize,
291    ) -> Self {
292        Self {
293            prior_alpha,
294            prior_beta,
295            alpha: prior_alpha,
296            beta: prior_beta,
297            decay,
298            min_observation_cells,
299        }
300    }
301
302    /// Reset the posterior to the prior.
303    pub fn reset(&mut self) {
304        self.alpha = self.prior_alpha;
305        self.beta = self.prior_beta;
306    }
307
308    /// Posterior parameters (α, β).
309    pub fn posterior_params(&self) -> (f64, f64) {
310        (self.alpha, self.beta)
311    }
312
313    /// Posterior mean `E[p]`.
314    pub fn mean(&self) -> f64 {
315        self.alpha / (self.alpha + self.beta)
316    }
317
318    /// Posterior variance `Var[p]`.
319    pub fn variance(&self) -> f64 {
320        let sum = self.alpha + self.beta;
321        (self.alpha * self.beta) / (sum * sum * (sum + 1.0))
322    }
323
324    /// Observe an update with scanned and changed cells.
325    pub fn observe(&mut self, cells_scanned: usize, cells_changed: usize) {
326        if cells_scanned < self.min_observation_cells {
327            return;
328        }
329
330        let cells_changed = cells_changed.min(cells_scanned);
331        self.alpha *= self.decay;
332        self.beta *= self.decay;
333
334        self.alpha += cells_changed as f64;
335        self.beta += (cells_scanned.saturating_sub(cells_changed)) as f64;
336
337        const EPS: f64 = 1e-6;
338        const MAX: f64 = 1e6;
339        self.alpha = self.alpha.clamp(EPS, MAX);
340        self.beta = self.beta.clamp(EPS, MAX);
341    }
342
343    /// Upper quantile of the Beta distribution using normal approximation.
344    pub fn upper_quantile(&self, q: f64) -> f64 {
345        let q = q.clamp(1e-6, 1.0 - 1e-6);
346        let mean = self.mean();
347        let var = self.variance();
348        let std = var.sqrt();
349
350        // Standard normal quantile approximation (Abramowitz & Stegun 26.2.23)
351        let z = if q >= 0.5 {
352            let t = (-2.0 * (1.0 - q).ln()).sqrt();
353            t - (2.515517 + 0.802853 * t + 0.010328 * t * t)
354                / (1.0 + 1.432788 * t + 0.189269 * t * t + 0.001308 * t * t * t)
355        } else {
356            let t = (-2.0 * q.ln()).sqrt();
357            -(t - (2.515517 + 0.802853 * t + 0.010328 * t * t)
358                / (1.0 + 1.432788 * t + 0.189269 * t * t + 0.001308 * t * t * t))
359        };
360
361        (mean + z * std).clamp(0.0, 1.0)
362    }
363}
364
365// =============================================================================
366// Strategy Enum
367// =============================================================================
368
369/// The diff strategy to use for the current frame.
370#[derive(Debug, Clone, Copy, PartialEq, Eq)]
371pub enum DiffStrategy {
372    /// Use `BufferDiff::compute` (full row-major scan with row-skip).
373    Full,
374    /// Use `BufferDiff::compute_dirty` (scan only dirty rows).
375    DirtyRows,
376    /// Skip diff entirely; emit all cells.
377    FullRedraw,
378}
379
380impl fmt::Display for DiffStrategy {
381    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
382        match self {
383            Self::Full => write!(f, "Full"),
384            Self::DirtyRows => write!(f, "DirtyRows"),
385            Self::FullRedraw => write!(f, "FullRedraw"),
386        }
387    }
388}
389
390// =============================================================================
391// Regime Classification
392// =============================================================================
393
394/// Sparse dirty ratio threshold: dirty rows/tiles with ratio below this are Sparse.
395pub const SPARSE_DIRTY_RATIO_THRESHOLD: f64 = 0.25;
396
397/// Dense dirty ratio threshold: diff operations with ratio below this are Dense.
398pub const DENSE_DIRTY_RATIO_THRESHOLD: f64 = 0.60;
399
400/// Regime classification for diff strategy decisions.
401#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
402pub enum DiffRegime {
403    /// Low change rate, sparse updates (dirty-rows/tiles with ratio < 0.25).
404    #[default]
405    Sparse,
406    /// Moderate change rate, dense compare (full compare with ratio < 0.6).
407    Dense,
408    /// High change rate or forced full redraw.
409    Redraw,
410}
411
412impl DiffRegime {
413    /// Regime name as a static string for JSONL output.
414    #[inline]
415    #[must_use]
416    pub const fn as_str(self) -> &'static str {
417        match self {
418            Self::Sparse => "sparse",
419            Self::Dense => "dense",
420            Self::Redraw => "redraw",
421        }
422    }
423
424    /// Classify the diff regime based on strategy and dirty cell ratio.
425    #[must_use]
426    pub fn classify(strategy: DiffStrategy, dirty_cell_ratio: f64) -> Self {
427        match strategy {
428            DiffStrategy::FullRedraw => Self::Redraw,
429            DiffStrategy::DirtyRows => {
430                if dirty_cell_ratio < SPARSE_DIRTY_RATIO_THRESHOLD {
431                    Self::Sparse
432                } else if dirty_cell_ratio < DENSE_DIRTY_RATIO_THRESHOLD {
433                    Self::Dense
434                } else {
435                    Self::Redraw
436                }
437            }
438            DiffStrategy::Full => {
439                if dirty_cell_ratio < DENSE_DIRTY_RATIO_THRESHOLD {
440                    Self::Dense
441                } else {
442                    Self::Redraw
443                }
444            }
445        }
446    }
447}
448
449impl fmt::Display for DiffRegime {
450    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
451        f.write_str(self.as_str())
452    }
453}
454
455// =============================================================================
456// Decision Evidence (Explainability)
457// =============================================================================
458
459/// Evidence supporting a strategy decision.
460///
461/// Provides explainability for the selection, showing expected costs
462/// and the posterior state that led to the decision.
463#[derive(Debug, Clone)]
464pub struct StrategyEvidence {
465    /// The selected strategy.
466    pub strategy: DiffStrategy,
467
468    /// Expected cost of Full strategy.
469    pub cost_full: f64,
470
471    /// Expected cost of DirtyRows strategy.
472    pub cost_dirty: f64,
473
474    /// Expected cost of FullRedraw strategy.
475    pub cost_redraw: f64,
476
477    /// Posterior mean of change rate p.
478    pub posterior_mean: f64,
479
480    /// Posterior variance of change rate p.
481    pub posterior_variance: f64,
482
483    /// Current posterior α.
484    pub alpha: f64,
485
486    /// Current posterior β.
487    pub beta: f64,
488
489    /// Number of dirty rows observed.
490    pub dirty_rows: usize,
491
492    /// Total rows (height).
493    pub total_rows: usize,
494
495    /// Total cells (width × height).
496    pub total_cells: usize,
497
498    /// Guard reason, if any.
499    pub guard_reason: &'static str,
500
501    /// Whether hysteresis prevented a switch.
502    pub hysteresis_applied: bool,
503
504    /// Hysteresis ratio used for the decision.
505    pub hysteresis_ratio: f64,
506}
507
508impl StrategyEvidence {
509    /// Format this evidence entry as a JSONL line for structured logging.
510    #[must_use]
511    pub fn to_jsonl(&self) -> String {
512        format!(
513            r#"{{"schema":"diff-strategy-v1","strategy":"{}","cost_full":{:.2},"cost_dirty":{:.2},"cost_redraw":{:.2},"posterior_mean":{:.6},"posterior_var":{:.8},"alpha":{:.4},"beta":{:.4},"dirty_rows":{},"total_rows":{},"total_cells":{},"guard":"{}","hysteresis":{},"hysteresis_ratio":{:.4}}}"#,
514            self.strategy,
515            self.cost_full,
516            self.cost_dirty,
517            self.cost_redraw,
518            self.posterior_mean,
519            self.posterior_variance,
520            self.alpha,
521            self.beta,
522            self.dirty_rows,
523            self.total_rows,
524            self.total_cells,
525            self.guard_reason,
526            self.hysteresis_applied,
527            self.hysteresis_ratio,
528        )
529    }
530}
531
532impl fmt::Display for StrategyEvidence {
533    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
534        writeln!(f, "Strategy: {}", self.strategy)?;
535        writeln!(
536            f,
537            "Costs: Full={:.2}, Dirty={:.2}, Redraw={:.2}",
538            self.cost_full, self.cost_dirty, self.cost_redraw
539        )?;
540        writeln!(
541            f,
542            "Posterior: p~Beta({:.2},{:.2}), E[p]={:.4}, Var[p]={:.6}",
543            self.alpha, self.beta, self.posterior_mean, self.posterior_variance
544        )?;
545        writeln!(
546            f,
547            "Dirty: {}/{} rows, {} total cells",
548            self.dirty_rows, self.total_rows, self.total_cells
549        )?;
550        writeln!(
551            f,
552            "Guard: {}, Hysteresis: {} (ratio {:.3})",
553            self.guard_reason, self.hysteresis_applied, self.hysteresis_ratio
554        )
555    }
556}
557
558// =============================================================================
559// Strategy Selector
560// =============================================================================
561
562/// Bayesian diff strategy selector.
563///
564/// Maintains a Beta posterior over the change rate and selects the
565/// strategy with minimum expected cost each frame.
566#[derive(Debug, Clone)]
567pub struct DiffStrategySelector {
568    config: DiffStrategyConfig,
569    estimator: ChangeRateEstimator,
570
571    /// Frame counter for diagnostics.
572    frame_count: u64,
573
574    /// Last decision evidence (for logging/debugging).
575    last_evidence: Option<StrategyEvidence>,
576}
577
578impl DiffStrategySelector {
579    /// Create a new selector with the given configuration.
580    pub fn new(config: DiffStrategyConfig) -> Self {
581        let config = config.sanitized();
582        let estimator = ChangeRateEstimator::new(
583            config.prior_alpha,
584            config.prior_beta,
585            config.decay,
586            config.min_observation_cells,
587        );
588        Self {
589            config,
590            estimator,
591            frame_count: 0,
592            last_evidence: None,
593        }
594    }
595
596    /// Create a selector with default configuration.
597    pub fn with_defaults() -> Self {
598        Self::new(DiffStrategyConfig::default())
599    }
600
601    /// Get the current configuration.
602    #[must_use]
603    pub fn config(&self) -> &DiffStrategyConfig {
604        &self.config
605    }
606
607    /// Get the current posterior parameters.
608    #[must_use]
609    pub fn posterior_params(&self) -> (f64, f64) {
610        self.estimator.posterior_params()
611    }
612
613    /// Get the posterior mean `E[p]`.
614    #[must_use]
615    pub fn posterior_mean(&self) -> f64 {
616        self.estimator.mean()
617    }
618
619    /// Get the posterior variance `Var[p]`.
620    #[must_use]
621    pub fn posterior_variance(&self) -> f64 {
622        self.estimator.variance()
623    }
624
625    /// Get the last decision evidence.
626    #[must_use]
627    pub fn last_evidence(&self) -> Option<&StrategyEvidence> {
628        self.last_evidence.as_ref()
629    }
630
631    /// Get frame count.
632    pub fn frame_count(&self) -> u64 {
633        self.frame_count
634    }
635
636    /// Override the last decision's selected strategy and guard reason.
637    ///
638    /// Used when higher-level feature flags or probes force a different strategy
639    /// than the Bayesian selector chose.
640    pub fn override_last_strategy(&mut self, strategy: DiffStrategy, reason: &'static str) {
641        if let Some(evidence) = self.last_evidence.as_mut() {
642            evidence.strategy = strategy;
643            evidence.guard_reason = reason;
644            evidence.hysteresis_applied = false;
645        }
646    }
647
648    /// Select the optimal strategy for the current frame.
649    ///
650    /// # Arguments
651    ///
652    /// * `width` - Buffer width in cells
653    /// * `height` - Buffer height in rows
654    /// * `dirty_rows` - Number of rows marked dirty
655    ///
656    /// # Returns
657    ///
658    /// The optimal `DiffStrategy` and stores evidence for later inspection.
659    pub fn select(&mut self, width: u16, height: u16, dirty_rows: usize) -> DiffStrategy {
660        let scan_cells = dirty_rows.saturating_mul(width as usize);
661        self.select_with_scan_estimate(width, height, dirty_rows, scan_cells)
662    }
663
664    /// Select the optimal strategy using a scan-cell estimate for DirtyRows.
665    ///
666    /// `dirty_scan_cells` should approximate the number of cells scanned when
667    /// using DirtyRows (e.g., dirty-span coverage). If unknown, pass
668    /// `dirty_rows × width`.
669    pub fn select_with_scan_estimate(
670        &mut self,
671        width: u16,
672        height: u16,
673        dirty_rows: usize,
674        dirty_scan_cells: usize,
675    ) -> DiffStrategy {
676        self.frame_count += 1;
677
678        let w = width as f64;
679        let h = height as f64;
680        let d = dirty_rows as f64;
681        let n = w * h;
682        let scan_cells =
683            dirty_scan_cells.min((width as usize).saturating_mul(height as usize)) as f64;
684
685        // Get expected change rate
686        let uncertainty_guard = self.config.uncertainty_guard_variance > 0.0
687            && self.posterior_variance() > self.config.uncertainty_guard_variance;
688        let mut guard_reason = if dirty_rows == 0 {
689            "zero_dirty_rows"
690        } else {
691            "none"
692        };
693        let mut p = if self.config.conservative || uncertainty_guard {
694            self.upper_quantile(self.config.conservative_quantile)
695        } else {
696            self.posterior_mean()
697        };
698        if dirty_rows == 0 {
699            p = 0.0;
700        }
701
702        // Compute expected costs.
703        //
704        // The posterior p is trained by observe() as changes-per-SCANNED-cell
705        // (DirtyRows observations scan the dirty region, not the screen), so
706        // the expected-emission term must multiply p by each path's own
707        // scanned-cell count, never by total cells. Using p·N here inflated
708        // the emit estimate by N/scanned for concentrated workloads (e.g. a
709        // half-screen log pane rewriting its rows had density ≈ 1.0 within
710        // its 6000 scanned cells; p·N priced 12000 emitted cells) and locked
711        // the selector into FullRedraw at 2x wire bytes, with the periodic
712        // probe re-observing density ≈ 1.0 and flipping straight back.
713        // Changes can only occur inside the scanned/dirty region (dirty rows
714        // ⊇ changed rows), so p·scanned is both consistent with training and
715        // a sound upper bound on emitted cells.
716        let cost_full = self.config.c_row * h
717            + self.config.c_scan * d * w
718            + self.config.c_emit * p * (d * w).min(n);
719
720        let cost_dirty = self.config.c_scan * scan_cells + self.config.c_emit * p * scan_cells;
721
722        let cost_redraw = self.config.c_emit * n;
723
724        // Select argmin
725        let mut strategy = if cost_dirty <= cost_full && cost_dirty <= cost_redraw {
726            DiffStrategy::DirtyRows
727        } else if cost_full <= cost_redraw {
728            DiffStrategy::Full
729        } else {
730            DiffStrategy::FullRedraw
731        };
732
733        if uncertainty_guard {
734            if guard_reason == "none" {
735                guard_reason = "uncertainty_variance";
736            }
737            if strategy == DiffStrategy::FullRedraw {
738                strategy = if cost_dirty <= cost_full {
739                    DiffStrategy::DirtyRows
740                } else {
741                    DiffStrategy::Full
742                };
743            }
744        }
745
746        let mut hysteresis_applied = false;
747        if let Some(prev) = self.last_evidence.as_ref().map(|e| e.strategy)
748            && prev != strategy
749        {
750            let prev_cost = cost_for_strategy(prev, cost_full, cost_dirty, cost_redraw);
751            let new_cost = cost_for_strategy(strategy, cost_full, cost_dirty, cost_redraw);
752            let ratio = self.config.hysteresis_ratio;
753            if ratio > 0.0
754                && prev_cost.is_finite()
755                && prev_cost > 0.0
756                && new_cost >= prev_cost * (1.0 - ratio)
757                && !(uncertainty_guard && prev == DiffStrategy::FullRedraw)
758            {
759                strategy = prev;
760                hysteresis_applied = true;
761            }
762        }
763
764        // Store evidence
765        let (alpha, beta) = self.estimator.posterior_params();
766        self.last_evidence = Some(StrategyEvidence {
767            strategy,
768            cost_full,
769            cost_dirty,
770            cost_redraw,
771            posterior_mean: self.posterior_mean(),
772            posterior_variance: self.posterior_variance(),
773            alpha,
774            beta,
775            dirty_rows,
776            total_rows: height as usize,
777            total_cells: (width as usize) * (height as usize),
778            guard_reason,
779            hysteresis_applied,
780            hysteresis_ratio: self.config.hysteresis_ratio,
781        });
782
783        strategy
784    }
785
786    /// Update the posterior with observed change rate.
787    ///
788    /// # Arguments
789    ///
790    /// * `cells_scanned` - Number of cells that were scanned for differences
791    /// * `cells_changed` - Number of cells that actually changed
792    pub fn observe(&mut self, cells_scanned: usize, cells_changed: usize) {
793        self.estimator.observe(cells_scanned, cells_changed);
794    }
795
796    /// Reset the posterior to priors.
797    pub fn reset(&mut self) {
798        self.estimator.reset();
799        self.frame_count = 0;
800        self.last_evidence = None;
801    }
802
803    /// Compute the upper quantile of the Beta distribution.
804    ///
805    /// Uses the normal approximation for computational efficiency:
806    /// `p_q ≈ μ + z_q × σ` where z_q is the standard normal quantile.
807    fn upper_quantile(&self, q: f64) -> f64 {
808        self.estimator.upper_quantile(q)
809    }
810}
811
812#[inline]
813fn cost_for_strategy(
814    strategy: DiffStrategy,
815    cost_full: f64,
816    cost_dirty: f64,
817    cost_redraw: f64,
818) -> f64 {
819    match strategy {
820        DiffStrategy::Full => cost_full,
821        DiffStrategy::DirtyRows => cost_dirty,
822        DiffStrategy::FullRedraw => cost_redraw,
823    }
824}
825
826impl Default for DiffStrategySelector {
827    fn default() -> Self {
828        Self::with_defaults()
829    }
830}
831
832// =============================================================================
833// Tests
834// =============================================================================
835
836#[cfg(test)]
837mod tests {
838    use super::*;
839
840    fn strategy_costs(
841        config: &DiffStrategyConfig,
842        width: u16,
843        height: u16,
844        dirty_rows: usize,
845        p_actual: f64,
846    ) -> (f64, f64, f64) {
847        let w = width as f64;
848        let h = height as f64;
849        let d = dirty_rows as f64;
850        let n = w * h;
851        let p = p_actual.clamp(0.0, 1.0);
852
853        let cost_full = config.c_row * h + config.c_scan * d * w + config.c_emit * p * n;
854        let cost_dirty = config.c_scan * d * w + config.c_emit * p * n;
855        let cost_redraw = config.c_emit * n;
856
857        (cost_full, cost_dirty, cost_redraw)
858    }
859
860    #[test]
861    fn test_default_config() {
862        let config = DiffStrategyConfig::default();
863        assert!((config.c_scan - 1.0).abs() < 1e-9);
864        assert!((config.c_emit - 6.0).abs() < 1e-9);
865        assert!((config.prior_alpha - 1.0).abs() < 1e-9);
866        assert!((config.prior_beta - 19.0).abs() < 1e-9);
867        assert!((config.hysteresis_ratio - 0.05).abs() < 1e-9);
868        assert!((config.uncertainty_guard_variance - 0.002).abs() < 1e-9);
869        assert_eq!(config.min_observation_cells, 1);
870    }
871
872    #[test]
873    fn diff_regime_classify_thresholds() {
874        // FullRedraw is always Redraw regardless of ratio
875        assert_eq!(
876            DiffRegime::classify(DiffStrategy::FullRedraw, 0.0),
877            DiffRegime::Redraw
878        );
879        assert_eq!(
880            DiffRegime::classify(DiffStrategy::FullRedraw, 0.1),
881            DiffRegime::Redraw
882        );
883        assert_eq!(
884            DiffRegime::classify(DiffStrategy::FullRedraw, 0.5),
885            DiffRegime::Redraw
886        );
887        assert_eq!(
888            DiffRegime::classify(DiffStrategy::FullRedraw, 0.9),
889            DiffRegime::Redraw
890        );
891
892        // DirtyRows:
893        // ratio < 0.25 -> Sparse
894        assert_eq!(
895            DiffRegime::classify(DiffStrategy::DirtyRows, 0.0),
896            DiffRegime::Sparse
897        );
898        assert_eq!(
899            DiffRegime::classify(DiffStrategy::DirtyRows, 0.1),
900            DiffRegime::Sparse
901        );
902        assert_eq!(
903            DiffRegime::classify(DiffStrategy::DirtyRows, 0.249),
904            DiffRegime::Sparse
905        );
906        // 0.25 <= ratio < 0.6 -> Dense
907        assert_eq!(
908            DiffRegime::classify(DiffStrategy::DirtyRows, 0.25),
909            DiffRegime::Dense
910        );
911        assert_eq!(
912            DiffRegime::classify(DiffStrategy::DirtyRows, 0.4),
913            DiffRegime::Dense
914        );
915        assert_eq!(
916            DiffRegime::classify(DiffStrategy::DirtyRows, 0.599),
917            DiffRegime::Dense
918        );
919        // ratio >= 0.6 -> Redraw
920        assert_eq!(
921            DiffRegime::classify(DiffStrategy::DirtyRows, 0.6),
922            DiffRegime::Redraw
923        );
924        assert_eq!(
925            DiffRegime::classify(DiffStrategy::DirtyRows, 0.8),
926            DiffRegime::Redraw
927        );
928        assert_eq!(
929            DiffRegime::classify(DiffStrategy::DirtyRows, 1.0),
930            DiffRegime::Redraw
931        );
932
933        // Full:
934        // ratio < 0.6 -> Dense
935        assert_eq!(
936            DiffRegime::classify(DiffStrategy::Full, 0.0),
937            DiffRegime::Dense
938        );
939        assert_eq!(
940            DiffRegime::classify(DiffStrategy::Full, 0.1),
941            DiffRegime::Dense
942        );
943        assert_eq!(
944            DiffRegime::classify(DiffStrategy::Full, 0.25),
945            DiffRegime::Dense
946        );
947        assert_eq!(
948            DiffRegime::classify(DiffStrategy::Full, 0.599),
949            DiffRegime::Dense
950        );
951        // ratio >= 0.6 -> Redraw
952        assert_eq!(
953            DiffRegime::classify(DiffStrategy::Full, 0.6),
954            DiffRegime::Redraw
955        );
956        assert_eq!(
957            DiffRegime::classify(DiffStrategy::Full, 0.8),
958            DiffRegime::Redraw
959        );
960        assert_eq!(
961            DiffRegime::classify(DiffStrategy::Full, 1.0),
962            DiffRegime::Redraw
963        );
964
965        // String representations and Display
966        assert_eq!(DiffRegime::Sparse.as_str(), "sparse");
967        assert_eq!(DiffRegime::Dense.as_str(), "dense");
968        assert_eq!(DiffRegime::Redraw.as_str(), "redraw");
969        assert_eq!(format!("{}", DiffRegime::Sparse), "sparse");
970        assert_eq!(format!("{}", DiffRegime::Dense), "dense");
971        assert_eq!(format!("{}", DiffRegime::Redraw), "redraw");
972    }
973
974    #[test]
975    fn test_decay_paused_on_empty_observation() {
976        let mut selector = DiffStrategySelector::with_defaults();
977        let initial_mean = selector.posterior_mean();
978
979        // Observe empty frames (e.g. idle)
980        for _ in 0..100 {
981            selector.observe(0, 0);
982        }
983
984        // Mean should not change (decay shouldn't happen)
985        assert!((selector.posterior_mean() - initial_mean).abs() < 1e-9);
986    }
987
988    #[test]
989    fn estimator_initializes_from_priors() {
990        let estimator = ChangeRateEstimator::new(2.0, 8.0, 0.9, 0);
991        let (alpha, beta) = estimator.posterior_params();
992        assert!((alpha - 2.0).abs() < 1e-9);
993        assert!((beta - 8.0).abs() < 1e-9);
994        assert!((estimator.mean() - 0.2).abs() < 1e-9);
995    }
996
997    #[test]
998    fn estimator_updates_with_decay() {
999        let mut estimator = ChangeRateEstimator::new(1.0, 9.0, 0.5, 0);
1000        estimator.observe(100, 10);
1001        let (alpha, beta) = estimator.posterior_params();
1002        assert!((alpha - (0.5 + 10.0)).abs() < 1e-9);
1003        assert!((beta - (4.5 + 90.0)).abs() < 1e-9);
1004    }
1005
1006    #[test]
1007    fn estimator_clamps_bounds() {
1008        let mut estimator = ChangeRateEstimator::new(1.0, 1.0, 1.0, 0);
1009        for _ in 0..1000 {
1010            estimator.observe(1_000_000, 1_000_000);
1011        }
1012        let (alpha, beta) = estimator.posterior_params();
1013        assert!(alpha <= 1e6);
1014        assert!(beta >= 1e-6);
1015    }
1016
1017    #[test]
1018    fn test_posterior_mean_initial() {
1019        let selector = DiffStrategySelector::with_defaults();
1020        // `E[p]` = α / (α + β) = 1 / 20 = 0.05
1021        assert!((selector.posterior_mean() - 0.05).abs() < 1e-9);
1022    }
1023
1024    #[test]
1025    fn test_posterior_update() {
1026        let mut selector = DiffStrategySelector::with_defaults();
1027
1028        // Observe 10% change rate (10 changed out of 100)
1029        selector.observe(100, 10);
1030
1031        // After update (with decay=0.95):
1032        // α = 0.95 * 1 + 10 = 10.95
1033        // β = 0.95 * 19 + 90 = 108.05
1034        // `E[p]` = 10.95 / 119.0 ≈ 0.092
1035        let mean = selector.posterior_mean();
1036        assert!(
1037            mean > 0.05,
1038            "Mean should increase after observing 10% change"
1039        );
1040        assert!(mean < 0.15, "Mean should not be too high");
1041    }
1042
1043    #[test]
1044    fn test_select_dirty_rows_when_few_dirty() {
1045        let mut selector = DiffStrategySelector::with_defaults();
1046
1047        // With default config and low expected p, dirty rows should win
1048        // when few rows are dirty
1049        let strategy = selector.select(80, 24, 2); // Only 2 dirty rows
1050        assert_eq!(strategy, DiffStrategy::DirtyRows);
1051    }
1052
1053    #[test]
1054    fn test_select_dirty_rows_when_no_dirty() {
1055        let mut selector = DiffStrategySelector::with_defaults();
1056
1057        let strategy = selector.select(80, 24, 0);
1058        assert_eq!(strategy, DiffStrategy::DirtyRows);
1059
1060        let evidence = selector.last_evidence().expect("evidence stored");
1061        assert_eq!(evidence.guard_reason, "zero_dirty_rows");
1062    }
1063
1064    #[test]
1065    fn test_select_dirty_rows_with_single_dirty_row_large_screen() {
1066        let mut selector = DiffStrategySelector::with_defaults();
1067
1068        // Single-row changes on large screens should still favor DirtyRows.
1069        let strategy = selector.select(200, 60, 1);
1070        assert_eq!(strategy, DiffStrategy::DirtyRows);
1071    }
1072
1073    #[test]
1074    fn test_select_full_redraw_when_high_change() {
1075        let config = DiffStrategyConfig {
1076            prior_alpha: 9.0, // High prior change rate
1077            prior_beta: 1.0,  // `E[p]` = 0.9
1078            ..Default::default()
1079        };
1080
1081        let mut selector = DiffStrategySelector::new(config);
1082        let strategy = selector.select(80, 24, 24); // All rows dirty
1083
1084        // With 90% expected change rate and all rows dirty,
1085        // full redraw might win depending on cost ratios
1086        // This test just verifies the selection doesn't panic
1087        assert!(matches!(
1088            strategy,
1089            DiffStrategy::Full | DiffStrategy::DirtyRows | DiffStrategy::FullRedraw
1090        ));
1091    }
1092
1093    #[test]
1094    fn test_evidence_stored() {
1095        let mut selector = DiffStrategySelector::with_defaults();
1096        selector.select(80, 24, 5);
1097
1098        let evidence = selector.last_evidence().expect("Evidence should be stored");
1099        assert_eq!(evidence.total_rows, 24);
1100        assert_eq!(evidence.total_cells, 80 * 24);
1101        assert_eq!(evidence.dirty_rows, 5);
1102    }
1103
1104    #[test]
1105    fn test_posterior_clamping() {
1106        let mut selector = DiffStrategySelector::with_defaults();
1107
1108        // Extreme observation
1109        for _ in 0..1000 {
1110            selector.observe(1_000_000, 1_000_000);
1111        }
1112
1113        let (alpha, beta) = selector.posterior_params();
1114        assert!(alpha <= 1e6, "Alpha should be clamped");
1115        assert!(beta >= 1e-6, "Beta should be clamped");
1116    }
1117
1118    #[test]
1119    fn conservative_quantile_extremes_are_safe() {
1120        let config = DiffStrategyConfig {
1121            conservative: true,
1122            conservative_quantile: 1.0,
1123            ..Default::default()
1124        };
1125        let mut selector = DiffStrategySelector::new(config);
1126
1127        let strategy = selector.select(80, 24, 0);
1128        let evidence = selector.last_evidence().expect("evidence should exist");
1129
1130        assert_eq!(strategy, evidence.strategy);
1131        assert!(evidence.cost_full.is_finite());
1132        assert!(evidence.cost_dirty.is_finite());
1133        assert!(evidence.cost_redraw.is_finite());
1134    }
1135
1136    #[test]
1137    fn sanitize_config_clamps_invalid_values() {
1138        let config = DiffStrategyConfig {
1139            c_scan: -1.0,
1140            c_emit: f64::NAN,
1141            c_row: f64::INFINITY,
1142            prior_alpha: 0.0,
1143            prior_beta: -3.0,
1144            decay: -1.0,
1145            conservative: true,
1146            conservative_quantile: 2.0,
1147            min_observation_cells: 0,
1148            hysteresis_ratio: -1.0,
1149            uncertainty_guard_variance: -1.0,
1150        };
1151        let selector = DiffStrategySelector::new(config);
1152        let sanitized = selector.config();
1153
1154        assert!(sanitized.c_scan >= 0.0);
1155        assert!(sanitized.c_emit.is_finite());
1156        assert!(sanitized.c_row.is_finite());
1157        assert!(sanitized.prior_alpha > 0.0);
1158        assert!(sanitized.prior_beta > 0.0);
1159        assert!((0.0..=1.0).contains(&sanitized.decay));
1160        assert!((0.0..=1.0).contains(&sanitized.conservative_quantile));
1161        assert!((0.0..=1.0).contains(&sanitized.hysteresis_ratio));
1162        assert!(sanitized.uncertainty_guard_variance >= 0.0);
1163    }
1164
1165    #[test]
1166    fn hysteresis_can_freeze_strategy_switching() {
1167        let config = DiffStrategyConfig {
1168            hysteresis_ratio: 1.0,
1169            uncertainty_guard_variance: 0.0,
1170            ..Default::default()
1171        };
1172        let mut selector = DiffStrategySelector::new(config);
1173
1174        let first = selector.select(80, 24, 1);
1175        let second = selector.select(80, 24, 24);
1176
1177        assert_eq!(
1178            first, second,
1179            "With hysteresis_ratio=1.0, selector should keep prior strategy"
1180        );
1181    }
1182
1183    #[test]
1184    fn uncertainty_guard_avoids_full_redraw() {
1185        let config = DiffStrategyConfig {
1186            c_scan: 10.0,
1187            c_emit: 1.0,
1188            uncertainty_guard_variance: 1e-6,
1189            ..Default::default()
1190        };
1191        let mut selector = DiffStrategySelector::new(config);
1192
1193        let strategy = selector.select(80, 24, 24);
1194        assert_ne!(
1195            strategy,
1196            DiffStrategy::FullRedraw,
1197            "Uncertainty guard should avoid FullRedraw under high variance"
1198        );
1199    }
1200
1201    #[test]
1202    fn concentrated_half_screen_workload_stays_dirty_rows() {
1203        // Regression: p is trained as changes-per-SCANNED-cell, but the emit
1204        // term used p * total_cells. A half-screen pane rewriting all its
1205        // rows (density within the dirty region ~= 1.0) priced 2x the real
1206        // emission and locked the selector into FullRedraw at double the
1207        // wire bytes — sticky, because the periodic probe re-observed
1208        // density ~= 1.0 and flipped straight back.
1209        let mut sel = DiffStrategySelector::new(DiffStrategyConfig::default());
1210
1211        // Steady workload: 200x60 terminal, 30 fully-changing rows/frame.
1212        for _ in 0..10 {
1213            let strategy = sel.select_with_scan_estimate(200, 60, 30, 6000);
1214            assert_ne!(
1215                strategy,
1216                DiffStrategy::FullRedraw,
1217                "half-screen concentrated workload must not full-redraw                  (6000 scanned + 6000 emitted < 12000 emitted)"
1218            );
1219            sel.observe(6000, 6000);
1220        }
1221    }
1222
1223    #[test]
1224    fn selector_regret_bounded_across_regimes() {
1225        let mut selector = DiffStrategySelector::with_defaults();
1226        let config = selector.config().clone();
1227        let width = 200u16;
1228        let height = 60u16;
1229        let total_cells = width as usize * height as usize;
1230
1231        let regimes = [
1232            (100usize, 2usize, 0.02f64),
1233            (100usize, 12usize, 0.12f64),
1234            (100usize, height as usize, 0.6f64),
1235        ];
1236
1237        let mut selector_total = 0.0f64;
1238        let mut fixed_full_total = 0.0f64;
1239        let mut fixed_dirty_total = 0.0f64;
1240        let mut fixed_redraw_total = 0.0f64;
1241
1242        for (frames, dirty_rows, p_actual) in regimes {
1243            for _ in 0..frames {
1244                let strategy = selector.select(width, height, dirty_rows);
1245                let (cost_full, cost_dirty, cost_redraw) =
1246                    strategy_costs(&config, width, height, dirty_rows, p_actual);
1247                fixed_full_total += cost_full;
1248                fixed_dirty_total += cost_dirty;
1249                fixed_redraw_total += cost_redraw;
1250
1251                let chosen_cost = match strategy {
1252                    DiffStrategy::Full => cost_full,
1253                    DiffStrategy::DirtyRows => cost_dirty,
1254                    DiffStrategy::FullRedraw => cost_redraw,
1255                };
1256                selector_total += chosen_cost;
1257
1258                let changed = ((p_actual * total_cells as f64).round() as usize).min(total_cells);
1259                let scanned = match strategy {
1260                    DiffStrategy::Full => total_cells,
1261                    DiffStrategy::DirtyRows => dirty_rows.saturating_mul(width as usize),
1262                    DiffStrategy::FullRedraw => 0,
1263                };
1264                if strategy != DiffStrategy::FullRedraw {
1265                    selector.observe(scanned, changed);
1266                }
1267            }
1268        }
1269
1270        let best_fixed = fixed_full_total
1271            .min(fixed_dirty_total)
1272            .min(fixed_redraw_total);
1273        let regret = if best_fixed > 0.0 {
1274            (selector_total - best_fixed) / best_fixed
1275        } else {
1276            0.0
1277        };
1278        let evidence = selector
1279            .last_evidence()
1280            .map(ToString::to_string)
1281            .unwrap_or_else(|| "no evidence".to_string());
1282
1283        assert!(
1284            regret <= 0.05,
1285            "Selector regret too high: {:.4} (selector {:.2}, best_fixed {:.2})\n{}",
1286            regret,
1287            selector_total,
1288            best_fixed,
1289            evidence
1290        );
1291    }
1292
1293    #[test]
1294    fn selector_switching_is_stable_under_constant_load() {
1295        let mut selector = DiffStrategySelector::with_defaults();
1296        let config = selector.config().clone();
1297        let width = 200u16;
1298        let height = 60u16;
1299        let dirty_rows = 2usize;
1300        let p_actual = 0.02f64;
1301        let total_cells = width as usize * height as usize;
1302
1303        let mut switches = 0usize;
1304        let mut last = None;
1305
1306        for _ in 0..200 {
1307            let strategy = selector.select(width, height, dirty_rows);
1308            if let Some(prev) = last
1309                && prev != strategy
1310            {
1311                switches = switches.saturating_add(1);
1312            }
1313            last = Some(strategy);
1314
1315            let changed = ((p_actual * total_cells as f64).round() as usize).min(total_cells);
1316            let scanned = match strategy {
1317                DiffStrategy::Full => total_cells,
1318                DiffStrategy::DirtyRows => dirty_rows.saturating_mul(width as usize),
1319                DiffStrategy::FullRedraw => 0,
1320            };
1321            if strategy != DiffStrategy::FullRedraw {
1322                selector.observe(scanned, changed);
1323            }
1324
1325            let _ = strategy_costs(&config, width, height, dirty_rows, p_actual);
1326        }
1327
1328        let evidence = selector
1329            .last_evidence()
1330            .map(ToString::to_string)
1331            .unwrap_or_else(|| "no evidence".to_string());
1332        assert!(
1333            switches <= 40,
1334            "Selector switched too often under stable regime: {switches}\n{evidence}"
1335        );
1336    }
1337
1338    #[test]
1339    fn test_reset() {
1340        let mut selector = DiffStrategySelector::with_defaults();
1341        selector.observe(100, 50);
1342        selector.select(80, 24, 10);
1343
1344        selector.reset();
1345
1346        assert!((selector.posterior_mean() - 0.05).abs() < 1e-9);
1347        assert_eq!(selector.frame_count(), 0);
1348        assert!(selector.last_evidence().is_none());
1349    }
1350
1351    #[test]
1352    fn test_deterministic() {
1353        let mut sel1 = DiffStrategySelector::with_defaults();
1354        let mut sel2 = DiffStrategySelector::with_defaults();
1355
1356        // Same inputs should produce same outputs
1357        sel1.observe(100, 10);
1358        sel2.observe(100, 10);
1359
1360        let s1 = sel1.select(80, 24, 5);
1361        let s2 = sel2.select(80, 24, 5);
1362
1363        assert_eq!(s1, s2);
1364        assert!((sel1.posterior_mean() - sel2.posterior_mean()).abs() < 1e-12);
1365    }
1366
1367    #[test]
1368    fn test_upper_quantile_reasonable() {
1369        let selector = DiffStrategySelector::with_defaults();
1370        let mean = selector.posterior_mean();
1371        let q95 = selector.upper_quantile(0.95);
1372
1373        assert!(q95 > mean, "95th percentile should be above mean");
1374        assert!(q95 <= 1.0, "Quantile should be bounded by 1.0");
1375    }
1376
1377    // Property test: posterior mean is always in [0, 1]
1378    #[test]
1379    fn prop_posterior_mean_bounded() {
1380        let mut selector = DiffStrategySelector::with_defaults();
1381
1382        for scanned in [1, 10, 100, 1000, 10000] {
1383            for changed in [0, 1, scanned / 10, scanned / 2, scanned] {
1384                selector.observe(scanned, changed);
1385                let mean = selector.posterior_mean();
1386                assert!((0.0..=1.0).contains(&mean), "Mean out of bounds: {mean}");
1387            }
1388        }
1389    }
1390
1391    // Property test: variance is always non-negative
1392    #[test]
1393    fn prop_variance_non_negative() {
1394        let mut selector = DiffStrategySelector::with_defaults();
1395
1396        for _ in 0..100 {
1397            selector.observe(100, 5);
1398            assert!(selector.posterior_variance() >= 0.0);
1399        }
1400    }
1401
1402    // --- DiffStrategy enum ---
1403
1404    #[test]
1405    fn diff_strategy_display() {
1406        assert_eq!(format!("{}", DiffStrategy::Full), "Full");
1407        assert_eq!(format!("{}", DiffStrategy::DirtyRows), "DirtyRows");
1408        assert_eq!(format!("{}", DiffStrategy::FullRedraw), "FullRedraw");
1409    }
1410
1411    #[test]
1412    fn diff_strategy_debug() {
1413        let dbg = format!("{:?}", DiffStrategy::Full);
1414        assert!(dbg.contains("Full"));
1415    }
1416
1417    #[test]
1418    fn diff_strategy_clone_and_eq() {
1419        let a = DiffStrategy::DirtyRows;
1420        let b = a;
1421        assert_eq!(a, b);
1422        assert_ne!(a, DiffStrategy::Full);
1423    }
1424
1425    // --- StrategyEvidence ---
1426
1427    #[test]
1428    fn strategy_evidence_display_contains_all_sections() {
1429        let mut selector = DiffStrategySelector::with_defaults();
1430        selector.select(80, 24, 5);
1431        let ev = selector.last_evidence().unwrap();
1432        let display = format!("{ev}");
1433        assert!(display.contains("Strategy:"));
1434        assert!(display.contains("Costs:"));
1435        assert!(display.contains("Posterior:"));
1436        assert!(display.contains("Dirty:"));
1437        assert!(display.contains("Guard:"));
1438        assert!(display.contains("Hysteresis:"));
1439    }
1440
1441    #[test]
1442    fn strategy_evidence_clone() {
1443        let mut selector = DiffStrategySelector::with_defaults();
1444        selector.select(80, 24, 3);
1445        let ev = selector.last_evidence().unwrap().clone();
1446        assert_eq!(ev.dirty_rows, 3);
1447        assert_eq!(ev.total_rows, 24);
1448        assert_eq!(ev.total_cells, 80 * 24);
1449    }
1450
1451    #[test]
1452    fn strategy_evidence_debug() {
1453        let mut selector = DiffStrategySelector::with_defaults();
1454        selector.select(80, 24, 2);
1455        let ev = selector.last_evidence().unwrap();
1456        let dbg = format!("{ev:?}");
1457        assert!(dbg.contains("StrategyEvidence"));
1458        assert!(dbg.contains("cost_full"));
1459    }
1460
1461    // --- Config ---
1462
1463    #[test]
1464    fn config_default_all_fields() {
1465        let c = DiffStrategyConfig::default();
1466        assert!((c.c_row - 0.1).abs() < 1e-9);
1467        assert!((c.decay - 0.95).abs() < 1e-9);
1468        assert!(!c.conservative);
1469        assert!((c.conservative_quantile - 0.95).abs() < 1e-9);
1470
1471        // The README's "Bayesian Diff Strategy Selection" section quotes these
1472        // by value: the Beta prior as "α₀ = 1, β₀ = 19 → E[p] = 5%", and the
1473        // cost model in terms of c_scan and c_emit. They were true but
1474        // unguarded, which is how a documented constant drifts without anyone
1475        // noticing. Changing one here means changing that section too.
1476        assert!((c.prior_alpha - 1.0).abs() < 1e-9);
1477        assert!((c.prior_beta - 19.0).abs() < 1e-9);
1478        let prior_mean = c.prior_alpha / (c.prior_alpha + c.prior_beta);
1479        assert!(
1480            (prior_mean - 0.05).abs() < 1e-9,
1481            "prior E[p] is {prior_mean}, README says 5%"
1482        );
1483        assert!((c.c_scan - 1.0).abs() < 1e-9);
1484        assert!((c.c_emit - 6.0).abs() < 1e-9);
1485    }
1486
1487    #[test]
1488    fn config_clone_and_debug() {
1489        let c = DiffStrategyConfig::default();
1490        let c2 = c.clone();
1491        assert!((c2.c_scan - c.c_scan).abs() < 1e-9);
1492        let dbg = format!("{c:?}");
1493        assert!(dbg.contains("DiffStrategyConfig"));
1494        assert!(dbg.contains("c_scan"));
1495    }
1496
1497    // --- Selector construction ---
1498
1499    #[test]
1500    fn selector_default_equals_with_defaults() {
1501        let s1 = DiffStrategySelector::default();
1502        let s2 = DiffStrategySelector::with_defaults();
1503        assert!((s1.posterior_mean() - s2.posterior_mean()).abs() < 1e-12);
1504        assert_eq!(s1.frame_count(), s2.frame_count());
1505    }
1506
1507    #[test]
1508    fn selector_config_accessor() {
1509        let config = DiffStrategyConfig {
1510            c_scan: 2.0,
1511            ..Default::default()
1512        };
1513        let selector = DiffStrategySelector::new(config);
1514        assert!((selector.config().c_scan - 2.0).abs() < 1e-9);
1515    }
1516
1517    // --- frame_count ---
1518
1519    #[test]
1520    fn frame_count_increments_per_select() {
1521        let mut selector = DiffStrategySelector::with_defaults();
1522        assert_eq!(selector.frame_count(), 0);
1523        selector.select(80, 24, 1);
1524        assert_eq!(selector.frame_count(), 1);
1525        selector.select(80, 24, 1);
1526        assert_eq!(selector.frame_count(), 2);
1527        for _ in 0..10 {
1528            selector.select(80, 24, 1);
1529        }
1530        assert_eq!(selector.frame_count(), 12);
1531    }
1532
1533    #[test]
1534    fn frame_count_not_affected_by_observe() {
1535        let mut selector = DiffStrategySelector::with_defaults();
1536        selector.observe(100, 10);
1537        assert_eq!(selector.frame_count(), 0);
1538    }
1539
1540    // --- override_last_strategy ---
1541
1542    #[test]
1543    fn override_last_strategy_changes_evidence() {
1544        let mut selector = DiffStrategySelector::with_defaults();
1545        selector.select(80, 24, 2);
1546        let original = selector.last_evidence().unwrap().strategy;
1547
1548        let override_to = if original == DiffStrategy::Full {
1549            DiffStrategy::FullRedraw
1550        } else {
1551            DiffStrategy::Full
1552        };
1553        selector.override_last_strategy(override_to, "test_override");
1554
1555        let ev = selector.last_evidence().unwrap();
1556        assert_eq!(ev.strategy, override_to);
1557        assert_eq!(ev.guard_reason, "test_override");
1558        assert!(!ev.hysteresis_applied);
1559    }
1560
1561    #[test]
1562    fn override_last_strategy_noop_when_no_evidence() {
1563        let mut selector = DiffStrategySelector::with_defaults();
1564        // No select() called yet, so no evidence.
1565        selector.override_last_strategy(DiffStrategy::Full, "noop");
1566        assert!(selector.last_evidence().is_none());
1567    }
1568
1569    // --- select_with_scan_estimate ---
1570
1571    #[test]
1572    fn select_with_scan_estimate_custom_cells() {
1573        let mut selector = DiffStrategySelector::with_defaults();
1574        // Provide a very small scan estimate to make DirtyRows cheaper.
1575        let strategy = selector.select_with_scan_estimate(80, 24, 10, 10);
1576        assert_eq!(strategy, DiffStrategy::DirtyRows);
1577    }
1578
1579    #[test]
1580    fn select_with_scan_estimate_clamped_to_total() {
1581        let mut selector = DiffStrategySelector::with_defaults();
1582        // Provide scan_cells > total cells — should be clamped.
1583        let strategy = selector.select_with_scan_estimate(80, 24, 5, 1_000_000);
1584        // Should not panic, strategy is valid.
1585        assert!(matches!(
1586            strategy,
1587            DiffStrategy::Full | DiffStrategy::DirtyRows | DiffStrategy::FullRedraw
1588        ));
1589    }
1590
1591    // --- Estimator ---
1592
1593    #[test]
1594    fn estimator_reset_restores_priors() {
1595        let mut est = ChangeRateEstimator::new(2.0, 8.0, 0.9, 0);
1596        est.observe(100, 50);
1597        assert!((est.mean() - 0.2).abs() > 0.01, "Mean should have changed");
1598
1599        est.reset();
1600        let (alpha, beta) = est.posterior_params();
1601        assert!((alpha - 2.0).abs() < 1e-9);
1602        assert!((beta - 8.0).abs() < 1e-9);
1603        assert!((est.mean() - 0.2).abs() < 1e-9);
1604    }
1605
1606    #[test]
1607    fn estimator_clone() {
1608        let est1 = ChangeRateEstimator::new(1.0, 9.0, 0.95, 0);
1609        let est2 = est1.clone();
1610        assert!((est2.mean() - est1.mean()).abs() < 1e-12);
1611    }
1612
1613    #[test]
1614    fn estimator_debug() {
1615        let est = ChangeRateEstimator::new(1.0, 19.0, 0.95, 0);
1616        let dbg = format!("{est:?}");
1617        assert!(dbg.contains("ChangeRateEstimator"));
1618    }
1619
1620    #[test]
1621    fn estimator_min_observation_cells_filters() {
1622        let mut est = ChangeRateEstimator::new(1.0, 19.0, 0.95, 50);
1623        let initial_mean = est.mean();
1624        // Observe fewer than min_observation_cells — should be no-op.
1625        est.observe(49, 25);
1626        assert!(
1627            (est.mean() - initial_mean).abs() < 1e-12,
1628            "Observation below min should be ignored"
1629        );
1630        // Observe exactly min_observation_cells — should update.
1631        est.observe(50, 25);
1632        assert!(
1633            (est.mean() - initial_mean).abs() > 0.01,
1634            "Observation at min should be accepted"
1635        );
1636    }
1637
1638    #[test]
1639    fn estimator_changed_exceeds_scanned_is_clamped() {
1640        let mut est = ChangeRateEstimator::new(1.0, 19.0, 0.95, 0);
1641        // changed > scanned should be clamped to scanned.
1642        est.observe(10, 100);
1643        let mean = est.mean();
1644        // With all cells changed, mean should be high.
1645        assert!(mean > 0.3, "Mean should be high when all cells changed");
1646    }
1647
1648    #[test]
1649    fn estimator_variance_decreases_with_data() {
1650        let mut est = ChangeRateEstimator::new(1.0, 19.0, 1.0, 0);
1651        let v0 = est.variance();
1652        for _ in 0..50 {
1653            est.observe(100, 5);
1654        }
1655        let v1 = est.variance();
1656        assert!(
1657            v1 < v0,
1658            "Variance should decrease with more data: before={v0:.6}, after={v1:.6}"
1659        );
1660    }
1661
1662    #[test]
1663    fn estimator_upper_quantile_at_50_pct_near_mean() {
1664        let est = ChangeRateEstimator::new(1.0, 19.0, 1.0, 0);
1665        let mean = est.mean();
1666        let q50 = est.upper_quantile(0.5);
1667        assert!(
1668            (q50 - mean).abs() < 0.05,
1669            "50th percentile should be near mean: q50={q50:.4}, mean={mean:.4}"
1670        );
1671    }
1672
1673    #[test]
1674    fn estimator_upper_quantile_monotonic() {
1675        let est = ChangeRateEstimator::new(5.0, 15.0, 1.0, 0);
1676        let q25 = est.upper_quantile(0.25);
1677        let q50 = est.upper_quantile(0.5);
1678        let q75 = est.upper_quantile(0.75);
1679        let q95 = est.upper_quantile(0.95);
1680        assert!(q25 <= q50, "q25={q25:.4} should <= q50={q50:.4}");
1681        assert!(q50 <= q75, "q50={q50:.4} should <= q75={q75:.4}");
1682        assert!(q75 <= q95, "q75={q75:.4} should <= q95={q95:.4}");
1683    }
1684
1685    // --- Normalization helpers ---
1686
1687    #[test]
1688    fn normalize_positive_rejects_zero_and_negative() {
1689        assert!((normalize_positive(0.0, 5.0) - 5.0).abs() < 1e-9);
1690        assert!((normalize_positive(-1.0, 5.0) - 5.0).abs() < 1e-9);
1691        assert!((normalize_positive(f64::NAN, 5.0) - 5.0).abs() < 1e-9);
1692        assert!((normalize_positive(3.0, 5.0) - 3.0).abs() < 1e-9);
1693    }
1694
1695    #[test]
1696    fn normalize_cost_accepts_zero() {
1697        assert!((normalize_cost(0.0, 5.0) - 0.0).abs() < 1e-9);
1698        assert!((normalize_cost(-1.0, 5.0) - 5.0).abs() < 1e-9);
1699        assert!((normalize_cost(f64::NAN, 5.0) - 5.0).abs() < 1e-9);
1700    }
1701
1702    #[test]
1703    fn normalize_decay_clamps_to_one() {
1704        assert!((normalize_decay(1.5) - 1.0).abs() < 1e-9);
1705        assert!((normalize_decay(0.5) - 0.5).abs() < 1e-9);
1706        assert!((normalize_decay(-1.0) - 1.0).abs() < 1e-9);
1707        assert!((normalize_decay(0.0) - 1.0).abs() < 1e-9);
1708        assert!((normalize_decay(f64::NAN) - 1.0).abs() < 1e-9);
1709    }
1710
1711    #[test]
1712    fn normalize_ratio_clamps_to_unit() {
1713        assert!((normalize_ratio(0.5, 0.1) - 0.5).abs() < 1e-9);
1714        assert!((normalize_ratio(-1.0, 0.1) - 0.0).abs() < 1e-9);
1715        assert!((normalize_ratio(2.0, 0.1) - 1.0).abs() < 1e-9);
1716        assert!((normalize_ratio(f64::NAN, 0.1) - 0.1).abs() < 1e-9);
1717    }
1718
1719    // --- cost_for_strategy helper ---
1720
1721    #[test]
1722    fn cost_for_strategy_returns_correct_values() {
1723        assert!((cost_for_strategy(DiffStrategy::Full, 1.0, 2.0, 3.0) - 1.0).abs() < 1e-9);
1724        assert!((cost_for_strategy(DiffStrategy::DirtyRows, 1.0, 2.0, 3.0) - 2.0).abs() < 1e-9);
1725        assert!((cost_for_strategy(DiffStrategy::FullRedraw, 1.0, 2.0, 3.0) - 3.0).abs() < 1e-9);
1726    }
1727
1728    // --- Small / edge-case buffers ---
1729
1730    #[test]
1731    fn select_1x1_buffer() {
1732        let mut selector = DiffStrategySelector::with_defaults();
1733        let strategy = selector.select(1, 1, 1);
1734        assert!(matches!(
1735            strategy,
1736            DiffStrategy::Full | DiffStrategy::DirtyRows | DiffStrategy::FullRedraw
1737        ));
1738    }
1739
1740    #[test]
1741    fn select_zero_width() {
1742        let mut selector = DiffStrategySelector::with_defaults();
1743        let strategy = selector.select(0, 24, 0);
1744        // Zero-width buffer → zero cells → DirtyRows should be cheapest.
1745        assert!(matches!(
1746            strategy,
1747            DiffStrategy::Full | DiffStrategy::DirtyRows | DiffStrategy::FullRedraw
1748        ));
1749    }
1750
1751    #[test]
1752    fn select_zero_height() {
1753        let mut selector = DiffStrategySelector::with_defaults();
1754        let strategy = selector.select(80, 0, 0);
1755        assert!(matches!(
1756            strategy,
1757            DiffStrategy::Full | DiffStrategy::DirtyRows | DiffStrategy::FullRedraw
1758        ));
1759    }
1760
1761    // --- All-dirty vs no-dirty ---
1762
1763    #[test]
1764    fn all_dirty_vs_no_dirty_different_evidence() {
1765        let mut sel1 = DiffStrategySelector::with_defaults();
1766        let mut sel2 = DiffStrategySelector::with_defaults();
1767
1768        sel1.select(80, 24, 0);
1769        sel2.select(80, 24, 24);
1770
1771        let ev1 = sel1.last_evidence().unwrap();
1772        let ev2 = sel2.last_evidence().unwrap();
1773
1774        assert_eq!(ev1.dirty_rows, 0);
1775        assert_eq!(ev2.dirty_rows, 24);
1776        // No-dirty should have zero p estimate.
1777        assert!(
1778            ev1.cost_dirty <= ev1.cost_full,
1779            "DirtyRows should be cheap with no dirty rows"
1780        );
1781    }
1782
1783    // --- Decay = 1.0 (no decay) ---
1784
1785    #[test]
1786    fn no_decay_accumulates_all_evidence() {
1787        let config = DiffStrategyConfig {
1788            decay: 1.0,
1789            ..Default::default()
1790        };
1791        let mut selector = DiffStrategySelector::new(config);
1792
1793        // Observe 100% change rate many times.
1794        for _ in 0..100 {
1795            selector.observe(100, 100);
1796        }
1797        let mean = selector.posterior_mean();
1798        // With no decay and all-changed, mean should be near 1.0.
1799        assert!(
1800            mean > 0.9,
1801            "No-decay all-changed mean should be near 1.0: {mean:.4}"
1802        );
1803    }
1804
1805    // --- Evidence costs are finite ---
1806
1807    #[test]
1808    fn evidence_costs_always_finite() {
1809        let mut selector = DiffStrategySelector::with_defaults();
1810        for dirty in [0, 1, 12, 24] {
1811            selector.select(80, 24, dirty);
1812            let ev = selector.last_evidence().unwrap();
1813            assert!(ev.cost_full.is_finite(), "cost_full should be finite");
1814            assert!(ev.cost_dirty.is_finite(), "cost_dirty should be finite");
1815            assert!(ev.cost_redraw.is_finite(), "cost_redraw should be finite");
1816        }
1817    }
1818
1819    // --- Evidence posterior matches selector ---
1820
1821    #[test]
1822    fn evidence_posterior_matches_selector() {
1823        let mut selector = DiffStrategySelector::with_defaults();
1824        selector.observe(100, 10);
1825        selector.select(80, 24, 5);
1826        let ev = selector.last_evidence().unwrap();
1827        assert!((ev.posterior_mean - selector.posterior_mean()).abs() < 1e-12);
1828        assert!((ev.posterior_variance - selector.posterior_variance()).abs() < 1e-12);
1829        let (alpha, beta) = selector.posterior_params();
1830        assert!((ev.alpha - alpha).abs() < 1e-12);
1831        assert!((ev.beta - beta).abs() < 1e-12);
1832    }
1833
1834    // --- Selector clone ---
1835
1836    #[test]
1837    fn selector_clone() {
1838        let mut selector = DiffStrategySelector::with_defaults();
1839        selector.observe(100, 10);
1840        selector.select(80, 24, 5);
1841        let clone = selector.clone();
1842        assert!((clone.posterior_mean() - selector.posterior_mean()).abs() < 1e-12);
1843        assert_eq!(clone.frame_count(), selector.frame_count());
1844    }
1845
1846    // --- Selector debug ---
1847
1848    #[test]
1849    fn selector_debug() {
1850        let selector = DiffStrategySelector::with_defaults();
1851        let dbg = format!("{selector:?}");
1852        assert!(dbg.contains("DiffStrategySelector"));
1853        assert!(dbg.contains("frame_count"));
1854    }
1855
1856    // --- Hysteresis not applied on first select ---
1857
1858    #[test]
1859    fn hysteresis_not_applied_on_first_select() {
1860        let config = DiffStrategyConfig {
1861            hysteresis_ratio: 1.0,
1862            ..Default::default()
1863        };
1864        let mut selector = DiffStrategySelector::new(config);
1865        selector.select(80, 24, 5);
1866        let ev = selector.last_evidence().unwrap();
1867        assert!(
1868            !ev.hysteresis_applied,
1869            "First select should not apply hysteresis"
1870        );
1871    }
1872
1873    // --- Conservative mode uses upper quantile ---
1874
1875    #[test]
1876    fn conservative_mode_higher_p_estimate() {
1877        let mut conservative = DiffStrategySelector::new(DiffStrategyConfig {
1878            conservative: true,
1879            ..Default::default()
1880        });
1881        let mut normal = DiffStrategySelector::with_defaults();
1882
1883        // Same observations.
1884        for _ in 0..20 {
1885            conservative.observe(100, 5);
1886            normal.observe(100, 5);
1887        }
1888
1889        conservative.select(80, 24, 12);
1890        normal.select(80, 24, 12);
1891
1892        let ev_cons = conservative.last_evidence().unwrap();
1893        let ev_norm = normal.last_evidence().unwrap();
1894
1895        // Conservative mode uses upper quantile of p, so cost_dirty (which
1896        // includes p * N * c_emit) should be >= normal mode's cost_dirty.
1897        assert!(
1898            ev_cons.cost_dirty >= ev_norm.cost_dirty - 1e-6,
1899            "Conservative costs should be >= normal costs"
1900        );
1901    }
1902
1903    // -----------------------------------------------------------------------
1904    // Edge-case tests (bd-2az7m)
1905    // -----------------------------------------------------------------------
1906
1907    mod edge_case_tests {
1908        use super::super::*;
1909        use super::strategy_costs;
1910
1911        // --- ChangeRateEstimator edge cases ---
1912
1913        #[test]
1914        fn estimator_observe_zero_scanned_with_min_one() {
1915            // Default min_observation_cells=1, so scanned=0 is filtered out
1916            let mut est = ChangeRateEstimator::new(1.0, 19.0, 0.95, 1);
1917            let initial = est.mean();
1918            est.observe(0, 0);
1919            assert!(
1920                (est.mean() - initial).abs() < 1e-12,
1921                "Zero scanned should be filtered: mean changed"
1922            );
1923        }
1924
1925        #[test]
1926        fn estimator_observe_all_unchanged() {
1927            let mut est = ChangeRateEstimator::new(1.0, 19.0, 0.95, 0);
1928            for _ in 0..100 {
1929                est.observe(1000, 0);
1930            }
1931            // With 100% unchanged observations, mean should be very low
1932            assert!(
1933                est.mean() < 0.01,
1934                "All-unchanged observations should drive mean near zero: {}",
1935                est.mean()
1936            );
1937        }
1938
1939        #[test]
1940        fn estimator_observe_all_changed() {
1941            let mut est = ChangeRateEstimator::new(1.0, 19.0, 0.95, 0);
1942            for _ in 0..100 {
1943                est.observe(1000, 1000);
1944            }
1945            // With 100% changed observations, mean should be very high
1946            assert!(
1947                est.mean() > 0.99,
1948                "All-changed observations should drive mean near 1.0: {}",
1949                est.mean()
1950            );
1951        }
1952
1953        #[test]
1954        fn estimator_rapid_decay_forgets_quickly() {
1955            let mut est = ChangeRateEstimator::new(1.0, 19.0, 0.1, 0);
1956            // Observe high change rate
1957            for _ in 0..50 {
1958                est.observe(100, 90);
1959            }
1960            let high_mean = est.mean();
1961
1962            // Now observe low change rate — with decay=0.1, should adapt fast
1963            for _ in 0..10 {
1964                est.observe(100, 1);
1965            }
1966            let low_mean = est.mean();
1967
1968            assert!(
1969                low_mean < high_mean * 0.5,
1970                "Rapid decay should forget quickly: high={high_mean:.4}, low={low_mean:.4}"
1971            );
1972        }
1973
1974        #[test]
1975        fn estimator_alternating_observations() {
1976            let mut est = ChangeRateEstimator::new(1.0, 19.0, 0.95, 0);
1977            for i in 0..100 {
1978                if i % 2 == 0 {
1979                    est.observe(100, 100); // All changed
1980                } else {
1981                    est.observe(100, 0); // Nothing changed
1982                }
1983            }
1984            // Mean should settle around 0.5
1985            let mean = est.mean();
1986            assert!(
1987                mean > 0.3 && mean < 0.7,
1988                "Alternating observations should settle near 0.5: {mean:.4}"
1989            );
1990        }
1991
1992        #[test]
1993        fn estimator_upper_quantile_at_extreme_low() {
1994            let est = ChangeRateEstimator::new(1.0, 19.0, 1.0, 0);
1995            let q01 = est.upper_quantile(0.01);
1996            assert!(
1997                q01 >= 0.0,
1998                "Lower quantile should be non-negative: {q01:.4}"
1999            );
2000            assert!(
2001                q01 < est.mean(),
2002                "1st percentile should be below mean: q01={q01:.4}, mean={:.4}",
2003                est.mean()
2004            );
2005        }
2006
2007        #[test]
2008        fn estimator_upper_quantile_at_extreme_high() {
2009            let est = ChangeRateEstimator::new(1.0, 19.0, 1.0, 0);
2010            let q99 = est.upper_quantile(0.99);
2011            assert!(q99 <= 1.0, "Upper quantile should be <= 1.0: {q99:.4}");
2012            assert!(
2013                q99 > est.mean(),
2014                "99th percentile should be above mean: q99={q99:.4}, mean={:.4}",
2015                est.mean()
2016            );
2017        }
2018
2019        #[test]
2020        fn estimator_upper_quantile_tight_posterior() {
2021            // With lots of data, posterior is tight → quantiles near mean
2022            let mut est = ChangeRateEstimator::new(1.0, 19.0, 1.0, 0);
2023            for _ in 0..10000 {
2024                est.observe(100, 5);
2025            }
2026            let mean = est.mean();
2027            let q95 = est.upper_quantile(0.95);
2028            assert!(
2029                (q95 - mean).abs() < 0.01,
2030                "Tight posterior should have quantile near mean: q95={q95:.4}, mean={mean:.4}"
2031            );
2032        }
2033
2034        #[test]
2035        fn estimator_upper_quantile_clamped_output() {
2036            // Even with extreme inputs, output should be in [0, 1]
2037            let est = ChangeRateEstimator::new(1e-6, 1e-6, 1.0, 0);
2038            for q in [0.01, 0.1, 0.5, 0.9, 0.99] {
2039                let val = est.upper_quantile(q);
2040                assert!(
2041                    (0.0..=1.0).contains(&val),
2042                    "Quantile({q}) = {val} should be in [0,1]"
2043                );
2044            }
2045        }
2046
2047        #[test]
2048        fn estimator_variance_formula_correct() {
2049            let est = ChangeRateEstimator::new(3.0, 7.0, 1.0, 0);
2050            let (a, b) = est.posterior_params();
2051            let expected_var = (a * b) / ((a + b).powi(2) * (a + b + 1.0));
2052            assert!(
2053                (est.variance() - expected_var).abs() < 1e-12,
2054                "Variance formula: got {}, expected {}",
2055                est.variance(),
2056                expected_var
2057            );
2058        }
2059
2060        #[test]
2061        fn estimator_mean_formula_correct() {
2062            let est = ChangeRateEstimator::new(3.0, 7.0, 1.0, 0);
2063            let (a, b) = est.posterior_params();
2064            let expected_mean = a / (a + b);
2065            assert!(
2066                (est.mean() - expected_mean).abs() < 1e-12,
2067                "Mean formula: got {}, expected {}",
2068                est.mean(),
2069                expected_mean
2070            );
2071        }
2072
2073        // --- DiffStrategySelector edge cases ---
2074
2075        #[test]
2076        fn select_dirty_rows_exceeds_height() {
2077            let mut selector = DiffStrategySelector::with_defaults();
2078            // dirty_rows > height shouldn't panic
2079            let strategy = selector.select(80, 24, 100);
2080            assert!(matches!(
2081                strategy,
2082                DiffStrategy::Full | DiffStrategy::DirtyRows | DiffStrategy::FullRedraw
2083            ));
2084        }
2085
2086        #[test]
2087        fn select_large_dimensions() {
2088            let mut selector = DiffStrategySelector::with_defaults();
2089            // u16::MAX width and height
2090            let strategy = selector.select(u16::MAX, u16::MAX, 1);
2091            assert!(matches!(
2092                strategy,
2093                DiffStrategy::Full | DiffStrategy::DirtyRows | DiffStrategy::FullRedraw
2094            ));
2095            let ev = selector.last_evidence().unwrap();
2096            assert!(ev.cost_full.is_finite());
2097            assert!(ev.cost_dirty.is_finite());
2098            assert!(ev.cost_redraw.is_finite());
2099        }
2100
2101        #[test]
2102        fn multiple_selects_without_observe() {
2103            let mut selector = DiffStrategySelector::with_defaults();
2104            let initial_mean = selector.posterior_mean();
2105
2106            for _ in 0..50 {
2107                selector.select(80, 24, 5);
2108            }
2109
2110            // Posterior should not change without observations
2111            assert!(
2112                (selector.posterior_mean() - initial_mean).abs() < 1e-12,
2113                "Mean should not change without observations"
2114            );
2115            assert_eq!(selector.frame_count(), 50);
2116        }
2117
2118        #[test]
2119        fn conservative_with_zero_dirty_rows() {
2120            let mut selector = DiffStrategySelector::new(DiffStrategyConfig {
2121                conservative: true,
2122                ..Default::default()
2123            });
2124            let strategy = selector.select(80, 24, 0);
2125            assert_eq!(strategy, DiffStrategy::DirtyRows);
2126            let ev = selector.last_evidence().unwrap();
2127            assert_eq!(ev.guard_reason, "zero_dirty_rows");
2128        }
2129
2130        #[test]
2131        fn uncertainty_guard_with_fullredraw_hysteresis() {
2132            // When uncertainty guard is active and previous strategy was FullRedraw,
2133            // hysteresis should NOT prevent switching away from FullRedraw
2134            let mut selector = DiffStrategySelector::new(DiffStrategyConfig {
2135                c_scan: 10.0,
2136                c_emit: 1.0,
2137                uncertainty_guard_variance: 1e-6,
2138                hysteresis_ratio: 0.99, // Very high hysteresis
2139                ..Default::default()
2140            });
2141
2142            // First select — likely FullRedraw since c_scan is high
2143            selector.select(80, 24, 24);
2144
2145            // Second select — uncertainty guard should override hysteresis for FullRedraw
2146            let strategy = selector.select(80, 24, 24);
2147            // Under uncertainty guard, FullRedraw is avoided
2148            assert_ne!(
2149                strategy,
2150                DiffStrategy::FullRedraw,
2151                "Uncertainty guard should override hysteresis for FullRedraw"
2152            );
2153        }
2154
2155        #[test]
2156        fn select_with_scan_estimate_zero_cells() {
2157            let mut selector = DiffStrategySelector::with_defaults();
2158            // Zero scan cells makes DirtyRows very cheap
2159            let strategy = selector.select_with_scan_estimate(80, 24, 5, 0);
2160            assert_eq!(strategy, DiffStrategy::DirtyRows);
2161        }
2162
2163        #[test]
2164        fn hysteresis_prevents_switch_near_boundary() {
2165            let config = DiffStrategyConfig {
2166                hysteresis_ratio: 0.5, // 50% — very sticky
2167                uncertainty_guard_variance: 0.0,
2168                ..Default::default()
2169            };
2170            let mut selector = DiffStrategySelector::new(config);
2171
2172            // First select establishes a strategy
2173            let first = selector.select(80, 24, 5);
2174
2175            // Second select with slightly different params — hysteresis should hold
2176            let second = selector.select(80, 24, 6);
2177            assert_eq!(
2178                first, second,
2179                "High hysteresis should prevent switching on small changes"
2180            );
2181        }
2182
2183        #[test]
2184        fn reset_clears_frame_count_and_evidence() {
2185            let mut selector = DiffStrategySelector::with_defaults();
2186            selector.observe(100, 10);
2187            selector.select(80, 24, 5);
2188            selector.select(80, 24, 5);
2189
2190            assert_eq!(selector.frame_count(), 2);
2191            assert!(selector.last_evidence().is_some());
2192
2193            selector.reset();
2194
2195            assert_eq!(selector.frame_count(), 0);
2196            assert!(selector.last_evidence().is_none());
2197            assert!(
2198                (selector.posterior_mean() - 0.05).abs() < 1e-9,
2199                "Reset should restore prior mean"
2200            );
2201        }
2202
2203        #[test]
2204        fn posterior_variance_after_reset() {
2205            let mut selector = DiffStrategySelector::with_defaults();
2206            let initial_var = selector.posterior_variance();
2207
2208            selector.observe(100, 10);
2209            assert!(selector.posterior_variance() != initial_var);
2210
2211            selector.reset();
2212            assert!(
2213                (selector.posterior_variance() - initial_var).abs() < 1e-12,
2214                "Reset should restore prior variance"
2215            );
2216        }
2217
2218        // --- Normalization edge cases ---
2219
2220        #[test]
2221        fn normalize_positive_rejects_infinity() {
2222            assert!(
2223                (normalize_positive(f64::INFINITY, 5.0) - 5.0).abs() < 1e-9,
2224                "Infinity should be rejected"
2225            );
2226            assert!(
2227                (normalize_positive(f64::NEG_INFINITY, 5.0) - 5.0).abs() < 1e-9,
2228                "Negative infinity should be rejected"
2229            );
2230        }
2231
2232        #[test]
2233        fn normalize_cost_rejects_neg_infinity() {
2234            assert!(
2235                (normalize_cost(f64::NEG_INFINITY, 5.0) - 5.0).abs() < 1e-9,
2236                "Negative infinity should be rejected"
2237            );
2238        }
2239
2240        #[test]
2241        fn normalize_cost_accepts_positive_infinity() {
2242            // Positive infinity is not finite, so should be rejected
2243            assert!(
2244                (normalize_cost(f64::INFINITY, 5.0) - 5.0).abs() < 1e-9,
2245                "Positive infinity should be rejected"
2246            );
2247        }
2248
2249        #[test]
2250        fn normalize_ratio_rejects_infinity() {
2251            assert!(
2252                (normalize_ratio(f64::INFINITY, 0.1) - 0.1).abs() < 1e-9,
2253                "Infinity should use fallback"
2254            );
2255            assert!(
2256                (normalize_ratio(f64::NEG_INFINITY, 0.1) - 0.1).abs() < 1e-9,
2257                "Negative infinity should use fallback"
2258            );
2259        }
2260
2261        #[test]
2262        fn normalize_decay_rejects_neg_infinity() {
2263            assert!(
2264                (normalize_decay(f64::NEG_INFINITY) - 1.0).abs() < 1e-9,
2265                "Negative infinity should use fallback"
2266            );
2267        }
2268
2269        // --- Strategy cost ordering edge cases ---
2270
2271        #[test]
2272        fn cost_redraw_independent_of_dirty_rows() {
2273            let mut sel1 = DiffStrategySelector::with_defaults();
2274            let mut sel2 = DiffStrategySelector::with_defaults();
2275
2276            sel1.select(80, 24, 0);
2277            sel2.select(80, 24, 24);
2278
2279            let ev1 = sel1.last_evidence().unwrap();
2280            let ev2 = sel2.last_evidence().unwrap();
2281
2282            // FullRedraw cost = c_emit * N, independent of dirty rows
2283            assert!(
2284                (ev1.cost_redraw - ev2.cost_redraw).abs() < 1e-6,
2285                "FullRedraw cost should not depend on dirty rows"
2286            );
2287        }
2288
2289        #[test]
2290        fn cost_full_increases_with_dirty_rows() {
2291            let config = DiffStrategyConfig::default();
2292            // With more dirty rows, Full cost increases (more scan cost)
2293            let (cost_full_2, _, _) = strategy_costs(&config, 80, 24, 2, 0.05);
2294            let (cost_full_20, _, _) = strategy_costs(&config, 80, 24, 20, 0.05);
2295            assert!(
2296                cost_full_20 > cost_full_2,
2297                "More dirty rows should increase Full cost: 2={cost_full_2:.2}, 20={cost_full_20:.2}"
2298            );
2299        }
2300
2301        #[test]
2302        fn cost_dirty_increases_with_dirty_rows() {
2303            let config = DiffStrategyConfig::default();
2304            let (_, cost_dirty_2, _) = strategy_costs(&config, 80, 24, 2, 0.05);
2305            let (_, cost_dirty_20, _) = strategy_costs(&config, 80, 24, 20, 0.05);
2306            assert!(
2307                cost_dirty_20 > cost_dirty_2,
2308                "More dirty rows should increase DirtyRows cost"
2309            );
2310        }
2311
2312        // --- Strategy evidence field completeness ---
2313
2314        #[test]
2315        fn evidence_all_fields_populated() {
2316            let mut selector = DiffStrategySelector::with_defaults();
2317            selector.observe(100, 10);
2318            selector.select(200, 60, 15);
2319
2320            let ev = selector.last_evidence().unwrap();
2321            assert_eq!(ev.total_rows, 60);
2322            assert_eq!(ev.total_cells, 200 * 60);
2323            assert_eq!(ev.dirty_rows, 15);
2324            assert!(ev.cost_full >= 0.0);
2325            assert!(ev.cost_dirty >= 0.0);
2326            assert!(ev.cost_redraw >= 0.0);
2327            assert!((0.0..=1.0).contains(&ev.posterior_mean));
2328            assert!(ev.posterior_variance >= 0.0);
2329            assert!(ev.alpha > 0.0);
2330            assert!(ev.beta > 0.0);
2331            assert!(!ev.guard_reason.is_empty());
2332            assert!(ev.hysteresis_ratio >= 0.0);
2333        }
2334
2335        #[test]
2336        fn evidence_display_format() {
2337            let mut selector = DiffStrategySelector::with_defaults();
2338            selector.select(80, 24, 5);
2339            let ev = selector.last_evidence().unwrap();
2340            let display = format!("{ev}");
2341
2342            // Should contain key sections
2343            assert!(display.contains("Strategy:"));
2344            assert!(display.contains("Costs:"));
2345            assert!(display.contains("Posterior:"));
2346            assert!(display.contains("Dirty:"));
2347            assert!(display.contains("Guard:"));
2348        }
2349
2350        // --- DiffStrategy enum completeness ---
2351
2352        #[test]
2353        fn diff_strategy_all_variants_distinct() {
2354            let variants = [
2355                DiffStrategy::Full,
2356                DiffStrategy::DirtyRows,
2357                DiffStrategy::FullRedraw,
2358            ];
2359            for (i, a) in variants.iter().enumerate() {
2360                for (j, b) in variants.iter().enumerate() {
2361                    if i == j {
2362                        assert_eq!(a, b);
2363                    } else {
2364                        assert_ne!(a, b);
2365                    }
2366                }
2367            }
2368        }
2369
2370        #[test]
2371        fn diff_strategy_copy() {
2372            let a = DiffStrategy::DirtyRows;
2373            let b = a; // Copy
2374            let _c = a; // Still valid — a was copied, not moved
2375            assert_eq!(a, b);
2376        }
2377
2378        // --- Selector with custom priors ---
2379
2380        #[test]
2381        fn custom_prior_high_alpha_favors_dirty_rows_less() {
2382            // High prior alpha → expect more changes → Full/FullRedraw more likely
2383            let mut selector = DiffStrategySelector::new(DiffStrategyConfig {
2384                prior_alpha: 50.0,
2385                prior_beta: 1.0, // `E[p]` ≈ 0.98
2386                ..Default::default()
2387            });
2388            selector.select(80, 24, 24);
2389            let ev = selector.last_evidence().unwrap();
2390            // With p≈0.98 and all dirty, FullRedraw should be competitive
2391            assert!(
2392                ev.cost_redraw <= ev.cost_full * 1.5,
2393                "High change rate should make redraw competitive"
2394            );
2395        }
2396
2397        #[test]
2398        fn custom_prior_high_beta_favors_dirty_rows() {
2399            // High prior beta → expect few changes → DirtyRows efficient
2400            let mut selector = DiffStrategySelector::new(DiffStrategyConfig {
2401                prior_alpha: 1.0,
2402                prior_beta: 1000.0, // `E[p]` ≈ 0.001
2403                ..Default::default()
2404            });
2405            let strategy = selector.select(80, 24, 5);
2406            assert_eq!(
2407                strategy,
2408                DiffStrategy::DirtyRows,
2409                "Very low expected change rate should favor DirtyRows"
2410            );
2411        }
2412
2413        // --- Decay boundary behavior ---
2414
2415        #[test]
2416        fn decay_zero_sanitizes_to_one() {
2417            // decay=0 is invalid (non-positive), sanitized() should set it to 1.0
2418            let config = DiffStrategyConfig {
2419                decay: 0.0,
2420                ..Default::default()
2421            };
2422            let selector = DiffStrategySelector::new(config);
2423            // With decay=1.0 (sanitized from 0.0), accumulation should work
2424            assert!(
2425                (selector.config().decay - 1.0).abs() < 1e-9,
2426                "Decay=0.0 should be sanitized to 1.0"
2427            );
2428        }
2429
2430        #[test]
2431        fn decay_one_no_forgetting() {
2432            let mut est = ChangeRateEstimator::new(1.0, 19.0, 1.0, 0);
2433            est.observe(100, 10);
2434            let (a1, b1) = est.posterior_params();
2435            // With decay=1.0: alpha = 1.0*1.0 + 10 = 11.0, beta = 1.0*19.0 + 90 = 109.0
2436            assert!(
2437                (a1 - 11.0).abs() < 1e-9,
2438                "No-decay alpha: expected 11.0, got {a1}"
2439            );
2440            assert!(
2441                (b1 - 109.0).abs() < 1e-9,
2442                "No-decay beta: expected 109.0, got {b1}"
2443            );
2444        }
2445
2446        // --- Selector determinism across multiple frames ---
2447
2448        #[test]
2449        fn determinism_across_long_trace() {
2450            let trace: Vec<(u16, u16, usize, usize, usize)> = (0..200)
2451                .map(|i| {
2452                    let dirty = (i * 3 % 24) + 1;
2453                    let scanned = 80 * dirty;
2454                    let changed = (i * 7 % scanned.max(1)).max(1);
2455                    (80u16, 24u16, dirty, scanned, changed)
2456                })
2457                .collect();
2458
2459            let mut sel1 = DiffStrategySelector::with_defaults();
2460            let mut sel2 = DiffStrategySelector::with_defaults();
2461
2462            for (w, h, dirty, scanned, changed) in &trace {
2463                let s1 = sel1.select(*w, *h, *dirty);
2464                let s2 = sel2.select(*w, *h, *dirty);
2465                assert_eq!(s1, s2, "Determinism violated");
2466
2467                sel1.observe(*scanned, *changed);
2468                sel2.observe(*scanned, *changed);
2469
2470                assert!(
2471                    (sel1.posterior_mean() - sel2.posterior_mean()).abs() < 1e-12,
2472                    "Posterior diverged"
2473                );
2474            }
2475        }
2476
2477        // --- Override edge cases ---
2478
2479        #[test]
2480        fn override_changes_strategy_and_clears_hysteresis() {
2481            let mut selector = DiffStrategySelector::with_defaults();
2482            selector.select(80, 24, 5);
2483
2484            let original = selector.last_evidence().unwrap().strategy;
2485            let target = if original == DiffStrategy::FullRedraw {
2486                DiffStrategy::Full
2487            } else {
2488                DiffStrategy::FullRedraw
2489            };
2490
2491            selector.override_last_strategy(target, "forced_override");
2492            let ev = selector.last_evidence().unwrap();
2493
2494            assert_eq!(ev.strategy, target, "Override should change strategy");
2495            assert_eq!(ev.guard_reason, "forced_override");
2496            assert!(!ev.hysteresis_applied, "Override should clear hysteresis");
2497        }
2498
2499        // --- Config sanitization edge cases ---
2500
2501        #[test]
2502        fn sanitize_preserves_valid_config() {
2503            let config = DiffStrategyConfig {
2504                c_scan: 2.0,
2505                c_emit: 8.0,
2506                c_row: 0.5,
2507                prior_alpha: 3.0,
2508                prior_beta: 17.0,
2509                decay: 0.9,
2510                conservative: true,
2511                conservative_quantile: 0.9,
2512                min_observation_cells: 5,
2513                hysteresis_ratio: 0.1,
2514                uncertainty_guard_variance: 0.005,
2515            };
2516            let selector = DiffStrategySelector::new(config);
2517            let c = selector.config();
2518            assert!((c.c_scan - 2.0).abs() < 1e-9);
2519            assert!((c.c_emit - 8.0).abs() < 1e-9);
2520            assert!((c.c_row - 0.5).abs() < 1e-9);
2521            assert!((c.prior_alpha - 3.0).abs() < 1e-9);
2522            assert!((c.prior_beta - 17.0).abs() < 1e-9);
2523            assert!((c.decay - 0.9).abs() < 1e-9);
2524            assert!(c.conservative);
2525            assert!((c.conservative_quantile - 0.9).abs() < 1e-9);
2526            assert_eq!(c.min_observation_cells, 5);
2527            assert!((c.hysteresis_ratio - 0.1).abs() < 1e-9);
2528        }
2529
2530        #[test]
2531        fn sanitize_all_nan_uses_defaults() {
2532            let config = DiffStrategyConfig {
2533                c_scan: f64::NAN,
2534                c_emit: f64::NAN,
2535                c_row: f64::NAN,
2536                prior_alpha: f64::NAN,
2537                prior_beta: f64::NAN,
2538                decay: f64::NAN,
2539                conservative: false,
2540                conservative_quantile: f64::NAN,
2541                min_observation_cells: 0,
2542                hysteresis_ratio: f64::NAN,
2543                uncertainty_guard_variance: f64::NAN,
2544            };
2545            let selector = DiffStrategySelector::new(config);
2546            let c = selector.config();
2547            // All should be sanitized to defaults
2548            assert!((c.c_scan - 1.0).abs() < 1e-9);
2549            assert!((c.c_emit - 6.0).abs() < 1e-9);
2550            assert!((c.c_row - 0.1).abs() < 1e-9);
2551            assert!((c.prior_alpha - 1.0).abs() < 1e-9);
2552            assert!((c.prior_beta - 19.0).abs() < 1e-9);
2553            assert!((c.decay - 1.0).abs() < 1e-9);
2554            assert!((c.hysteresis_ratio - 0.05).abs() < 1e-9);
2555            assert!((c.uncertainty_guard_variance - 0.002).abs() < 1e-9);
2556        }
2557
2558        // --- Cost model correctness ---
2559
2560        #[test]
2561        fn zero_change_rate_costs() {
2562            let config = DiffStrategyConfig::default();
2563            let (cost_full, cost_dirty, cost_redraw) = strategy_costs(&config, 80, 24, 5, 0.0);
2564            // With p=0: Full = c_row*H + c_scan*D*W, Dirty = c_scan*D*W, Redraw = c_emit*N
2565            let expected_full = config.c_row * 24.0 + config.c_scan * 5.0 * 80.0;
2566            let expected_dirty = config.c_scan * 5.0 * 80.0;
2567            let expected_redraw = config.c_emit * 80.0 * 24.0;
2568
2569            assert!((cost_full - expected_full).abs() < 1e-6);
2570            assert!((cost_dirty - expected_dirty).abs() < 1e-6);
2571            assert!((cost_redraw - expected_redraw).abs() < 1e-6);
2572        }
2573
2574        #[test]
2575        fn full_change_rate_costs() {
2576            let config = DiffStrategyConfig::default();
2577            let (cost_full, cost_dirty, cost_redraw) = strategy_costs(&config, 80, 24, 24, 1.0);
2578            // With p=1.0 and all dirty: Full and Dirty both include c_emit*N
2579            // Redraw = c_emit*N, which should be cheapest since no scan cost
2580            assert!(
2581                cost_redraw <= cost_full,
2582                "At p=1.0, redraw should be <= full"
2583            );
2584            assert!(
2585                cost_redraw <= cost_dirty,
2586                "At p=1.0, redraw should be <= dirty"
2587            );
2588        }
2589    }
2590}