Skip to main content

ftui_runtime/
resize_coalescer.rs

1//! Adaptive resize stream coalescer.
2//!
3//! This module implements the resize coalescing behavior specified in
4//! `docs/spec/resize-scheduler.md`. It provides:
5//!
6//! - **Latest-wins semantics**: Only the final size in a burst is rendered
7//! - **Bounded latency**: Hard deadline guarantees render within max wait
8//! - **Regime awareness**: Adapts behavior between steady and burst modes
9//! - **Decision logging**: JSONL-compatible evidence for each decision
10//!
11//! # Usage
12//!
13//! ```ignore
14//! use ftui_runtime::resize_coalescer::{ResizeCoalescer, CoalescerConfig};
15//!
16//! let config = CoalescerConfig::default();
17//! let mut coalescer = ResizeCoalescer::new(config, (80, 24));
18//!
19//! // On resize event
20//! let action = coalescer.handle_resize(100, 40);
21//!
22//! // On tick (called each frame)
23//! let action = coalescer.tick();
24//! ```
25//!
26//! # Regime Detection
27//!
28//! The coalescer uses a simplified regime model with two states:
29//! - **Steady**: Single resize or slow sequence — prioritize responsiveness
30//! - **Burst**: Rapid resize events — prioritize coalescing to reduce work
31//!
32//! Regime transitions are detected via event rate tracking with hysteresis.
33//!
34//! # Invariants
35//!
36//! - **Latest-wins**: the final resize in a burst is never dropped.
37//! - **Bounded latency**: pending resizes apply within `hard_deadline_ms`.
38//! - **Deterministic**: identical event sequences yield identical decisions.
39//!
40//! # Failure Modes
41//!
42//! | Condition | Behavior | Rationale |
43//! |-----------|----------|-----------|
44//! | `hard_deadline_ms = 0` | Apply immediately | Avoids zero-latency stall |
45//! | `rate_window_size < 2` | `event_rate = 0` | No divide-by-zero in rate |
46//! | No pending size | Return `None` | Avoids spurious applies |
47//!
48//! # Decision Rule (Explainable)
49//!
50//! 1) If `time_since_render ≥ hard_deadline_ms`, **apply** (forced).
51//! 2) If `dt ≥ delay_ms`, **apply** when in **Steady** (or when BOCPD is
52//!    enabled). (`delay_ms` = steady/burst delay, or BOCPD posterior-interpolated
53//!    delay when enabled.)
54//! 3) If `event_rate ≥ burst_enter_rate`, switch to **Burst**.
55//! 4) If in **Burst** and `event_rate < burst_exit_rate` for `cooldown_frames`,
56//!    switch to **Steady**.
57//! 5) Otherwise, **coalesce** and optionally show a placeholder.
58
59#![forbid(unsafe_code)]
60
61use std::collections::VecDeque;
62use web_time::{Duration, Instant};
63
64use crate::bocpd::{BocpdConfig, BocpdDetector, BocpdRegime};
65use crate::evidence_sink::{EVIDENCE_SCHEMA_VERSION, EvidenceSink};
66use crate::terminal_writer::ScreenMode;
67
68/// FNV-1a 64-bit offset basis.
69/// Bound on retained cycle-time samples: percentiles are computed over the
70/// most recent window, and unbounded retention (one sample per applied
71/// resize) is a slow leak in long-lived sessions.
72const MAX_CYCLE_TIME_SAMPLES: usize = 1024;
73
74/// Bound on retained regime-transition evidence entries (one per regime
75/// flip, otherwise never truncated by the runtime).
76const MAX_TRANSITION_LOGS: usize = 256;
77
78const FNV_OFFSET_BASIS: u64 = 0xcbf29ce484222325;
79/// FNV-1a 64-bit prime.
80const FNV_PRIME: u64 = 0x100000001b3;
81
82fn fnv_hash_bytes(hash: &mut u64, bytes: &[u8]) {
83    for byte in bytes {
84        *hash ^= *byte as u64;
85        *hash = hash.wrapping_mul(FNV_PRIME);
86    }
87}
88
89#[inline]
90fn duration_since_or_zero(now: Instant, earlier: Instant) -> Duration {
91    now.saturating_duration_since(earlier)
92}
93
94fn default_resize_run_id() -> String {
95    format!("resize-{}", std::process::id())
96}
97
98fn screen_mode_str(mode: ScreenMode) -> &'static str {
99    match mode {
100        ScreenMode::Inline { .. } => "inline",
101        ScreenMode::InlineAuto { .. } => "inline_auto",
102        ScreenMode::AltScreen => "altscreen",
103    }
104}
105
106#[inline]
107fn json_escape(value: &str) -> String {
108    let mut out = String::with_capacity(value.len());
109    for ch in value.chars() {
110        match ch {
111            '"' => out.push_str("\\\""),
112            '\\' => out.push_str("\\\\"),
113            '\n' => out.push_str("\\n"),
114            '\r' => out.push_str("\\r"),
115            '\t' => out.push_str("\\t"),
116            c if c.is_control() => {
117                use std::fmt::Write as _;
118                let _ = write!(out, "\\u{:04X}", c as u32);
119            }
120            _ => out.push(ch),
121        }
122    }
123    out
124}
125
126fn evidence_prefix(
127    run_id: &str,
128    screen_mode: ScreenMode,
129    cols: u16,
130    rows: u16,
131    event_idx: u64,
132) -> String {
133    format!(
134        r#""schema_version":"{}","run_id":"{}","event_idx":{},"screen_mode":"{}","cols":{},"rows":{}"#,
135        EVIDENCE_SCHEMA_VERSION,
136        json_escape(run_id),
137        event_idx,
138        screen_mode_str(screen_mode),
139        cols,
140        rows,
141    )
142}
143
144/// Configuration for the resize coalescer.
145#[derive(Debug, Clone)]
146pub struct CoalescerConfig {
147    /// Maximum coalesce delay in steady regime (ms).
148    /// In steady state, we want quick response.
149    pub steady_delay_ms: u64,
150
151    /// Maximum coalesce delay in burst regime (ms).
152    /// During bursts, we coalesce more aggressively.
153    pub burst_delay_ms: u64,
154
155    /// Hard deadline — always render within this time (ms).
156    /// Guarantees bounded worst-case latency.
157    pub hard_deadline_ms: u64,
158
159    /// Event rate threshold to enter burst mode (events/second).
160    pub burst_enter_rate: f64,
161
162    /// Event rate threshold to exit burst mode (events/second).
163    /// Lower than enter_rate for hysteresis.
164    pub burst_exit_rate: f64,
165
166    /// Number of frames to hold in burst mode after rate drops.
167    pub cooldown_frames: u32,
168
169    /// Window size for rate calculation (number of events).
170    pub rate_window_size: usize,
171
172    /// Enable decision logging (JSONL format).
173    pub enable_logging: bool,
174
175    /// Enable BOCPD (Bayesian Online Change-Point Detection) for regime detection.
176    ///
177    /// When enabled (the default), the coalescer uses a Bayesian posterior over
178    /// run-lengths to detect regime changes (steady vs burst) instead of the
179    /// rate threshold heuristic. BOCPD provides:
180    /// - Principled uncertainty quantification via P(burst)
181    /// - Automatic adaptation without hand-tuned thresholds
182    /// - Evidence logging for decision explainability
183    ///
184    /// When disabled ([`Self::without_bocpd`]), the rate threshold heuristic
185    /// (`burst_enter_rate` / `burst_exit_rate`) is the only detector.
186    pub enable_bocpd: bool,
187
188    /// Let the rate heuristic decide when the BOCPD posterior is undefined.
189    ///
190    /// The posterior needs an inter-arrival observation, and it clamps
191    /// observations to `[min_observation_ms, max_observation_ms]`. With this
192    /// flag (the default) the first event of a session, an event whose
193    /// inter-arrival lies outside that range, and a non-finite posterior are
194    /// decided by the heuristic instead of a clamped or empty posterior. The
195    /// detector that made each decision is recorded as `detector` on the
196    /// `decision` and `regime_transition` evidence rows.
197    pub heuristic_fallback: bool,
198
199    /// BOCPD configuration; `None` means [`BocpdConfig::default`].
200    pub bocpd_config: Option<BocpdConfig>,
201}
202
203impl Default for CoalescerConfig {
204    fn default() -> Self {
205        Self {
206            steady_delay_ms: 16, // ~60fps responsiveness
207            burst_delay_ms: 40,  // Aggressive coalescing
208            hard_deadline_ms: 100,
209            burst_enter_rate: 10.0, // 10 events/sec to enter burst
210            burst_exit_rate: 5.0,   // 5 events/sec to exit burst
211            cooldown_frames: 3,
212            rate_window_size: 8,
213            enable_logging: false,
214            enable_bocpd: true,
215            heuristic_fallback: true,
216            bocpd_config: None,
217        }
218    }
219}
220
221impl CoalescerConfig {
222    /// Enable or disable decision logging.
223    #[must_use]
224    pub fn with_logging(mut self, enabled: bool) -> Self {
225        self.enable_logging = enabled;
226        self
227    }
228
229    /// Enable BOCPD-based regime detection with default configuration.
230    #[must_use]
231    pub fn with_bocpd(mut self) -> Self {
232        self.enable_bocpd = true;
233        self.bocpd_config = Some(BocpdConfig::default());
234        self
235    }
236
237    /// Enable BOCPD-based regime detection with custom configuration.
238    #[must_use]
239    pub fn with_bocpd_config(mut self, config: BocpdConfig) -> Self {
240        self.enable_bocpd = true;
241        self.bocpd_config = Some(config);
242        self
243    }
244
245    /// Disable BOCPD: the rate threshold heuristic becomes the only regime
246    /// detector (no `BocpdDetector` is built).
247    #[must_use]
248    pub fn without_bocpd(mut self) -> Self {
249        self.enable_bocpd = false;
250        self.bocpd_config = None;
251        self
252    }
253
254    /// Set whether the heuristic decides while the BOCPD posterior is
255    /// undefined (see [`Self::heuristic_fallback`]).
256    #[must_use]
257    pub fn with_heuristic_fallback(mut self, enabled: bool) -> Self {
258        self.heuristic_fallback = enabled;
259        self
260    }
261
262    /// Serialize configuration to JSONL format.
263    #[must_use]
264    pub fn to_jsonl(
265        &self,
266        run_id: &str,
267        screen_mode: ScreenMode,
268        cols: u16,
269        rows: u16,
270        event_idx: u64,
271    ) -> String {
272        let prefix = evidence_prefix(run_id, screen_mode, cols, rows, event_idx);
273        format!(
274            r#"{{{prefix},"event":"config","steady_delay_ms":{},"burst_delay_ms":{},"hard_deadline_ms":{},"burst_enter_rate":{:.3},"burst_exit_rate":{:.3},"cooldown_frames":{},"rate_window_size":{},"logging_enabled":{},"enable_bocpd":{},"heuristic_fallback":{}}}"#,
275            self.steady_delay_ms,
276            self.burst_delay_ms,
277            self.hard_deadline_ms,
278            self.burst_enter_rate,
279            self.burst_exit_rate,
280            self.cooldown_frames,
281            self.rate_window_size,
282            self.enable_logging,
283            self.enable_bocpd,
284            self.heuristic_fallback
285        )
286    }
287}
288
289/// Which detector made a regime decision.
290///
291/// BOCPD is the default detector; the rate heuristic decides when BOCPD is
292/// off ([`CoalescerConfig::without_bocpd`]) or, with
293/// [`CoalescerConfig::heuristic_fallback`], while the posterior is undefined
294/// (first event, inter-arrival outside the observation range, non-finite
295/// posterior). Recorded on `decision` and `regime_transition` evidence rows.
296#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
297pub enum RegimeDetector {
298    /// Rate threshold heuristic (`burst_enter_rate` / `burst_exit_rate`).
299    #[default]
300    Heuristic,
301    /// BOCPD run-length posterior.
302    Bocpd,
303}
304
305impl RegimeDetector {
306    /// Stable string form for JSONL evidence.
307    #[must_use]
308    pub const fn as_str(self) -> &'static str {
309        match self {
310            Self::Heuristic => "heuristic",
311            Self::Bocpd => "bocpd",
312        }
313    }
314}
315
316/// How many regime decisions each detector made in this session.
317#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
318pub struct DetectorDecisions {
319    /// Decisions made by the BOCPD posterior.
320    pub bocpd: u64,
321    /// Decisions made by the rate heuristic (BOCPD off or fallback active).
322    pub heuristic: u64,
323}
324
325/// Action returned by the coalescer.
326#[derive(Debug, Clone, Copy, PartialEq, Eq)]
327pub enum CoalesceAction {
328    /// Nothing to apply this cycle: either no resize is pending or the
329    /// pending one is still being coalesced (check
330    /// [`ResizeCoalescer::has_pending`] to tell the two apart).
331    None,
332
333    /// Apply the resize with the given dimensions.
334    ApplyResize {
335        width: u16,
336        height: u16,
337        /// Time spent coalescing.
338        coalesce_time: Duration,
339        /// Whether this was forced by hard deadline.
340        forced_by_deadline: bool,
341    },
342}
343
344/// Detected regime for resize events.
345#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
346pub enum Regime {
347    /// Single resize or slow sequence.
348    #[default]
349    Steady,
350    /// Rapid resize events (storm).
351    Burst,
352}
353
354impl Regime {
355    /// Get the stable string representation.
356    #[must_use]
357    pub const fn as_str(self) -> &'static str {
358        match self {
359            Self::Steady => "steady",
360            Self::Burst => "burst",
361        }
362    }
363}
364
365/// Structured reason codes for regime transitions.
366#[derive(Debug, Clone, Copy, PartialEq, Eq)]
367pub enum TransitionReasonCode {
368    /// Heuristic detector entered burst because event rate crossed enter threshold.
369    HeuristicEnterBurstRate,
370    /// Heuristic detector exited burst after cooldown with low event rate.
371    HeuristicExitBurstCooldown,
372    /// Heuristic detector exited burst on the immediate path because the
373    /// event rate had fallen below the exit threshold (no frame ticks run
374    /// the cooldown in `ResizeBehavior::Immediate`).
375    HeuristicExitBurstRate,
376    /// BOCPD posterior crossed burst threshold.
377    BocpdPosteriorBurst,
378    /// BOCPD posterior crossed steady threshold.
379    BocpdPosteriorSteady,
380    /// BOCPD mode exited burst on a tick because no event arrived for at
381    /// least the steady mean inter-arrival (`mu_steady_ms`). The posterior
382    /// only updates on events, so without this a burst followed by silence
383    /// would stay `Burst` (and keep the load governor in soft overload)
384    /// until the next resize.
385    BocpdIdleExit,
386}
387
388impl TransitionReasonCode {
389    /// Stable string form for JSONL evidence.
390    #[must_use]
391    pub const fn as_str(self) -> &'static str {
392        match self {
393            Self::HeuristicEnterBurstRate => "heuristic_enter_burst_rate",
394            Self::HeuristicExitBurstCooldown => "heuristic_exit_burst_cooldown",
395            Self::HeuristicExitBurstRate => "heuristic_exit_burst_rate",
396            Self::BocpdPosteriorBurst => "bocpd_posterior_burst",
397            Self::BocpdPosteriorSteady => "bocpd_posterior_steady",
398            Self::BocpdIdleExit => "bocpd_idle_exit",
399        }
400    }
401}
402
403/// Event emitted when a resize operation is applied (bd-bksf.6 stub).
404///
405/// Used by `ResizeSlaMonitor` for latency tracking.
406#[derive(Debug, Clone)]
407pub struct ResizeAppliedEvent {
408    /// New terminal size after resize.
409    pub new_size: (u16, u16),
410    /// Previous terminal size.
411    pub old_size: (u16, u16),
412    /// Time elapsed from resize request to apply.
413    pub elapsed: Duration,
414    /// Whether the apply was forced (hard deadline).
415    pub forced: bool,
416}
417
418/// Event emitted when regime changes between Steady and Burst (bd-bksf.6 stub).
419///
420/// Used by SLA monitoring for regime-aware alerting.
421#[derive(Debug, Clone)]
422pub struct RegimeChangeEvent {
423    /// Previous regime.
424    pub from: Regime,
425    /// New regime.
426    pub to: Regime,
427    /// Event index when transition occurred.
428    pub event_idx: u64,
429    /// Structured reason for the transition.
430    pub reason_code: TransitionReasonCode,
431    /// Transition confidence in [0, 1].
432    pub confidence: f64,
433}
434
435// =============================================================================
436// Evidence Ledger for Scheduler Decisions (bd-1rz0.27)
437// =============================================================================
438
439/// Evidence supporting a scheduler decision with Bayes factors.
440///
441/// This captures the mathematical reasoning behind coalesce/apply decisions,
442/// providing explainability for the regime-adaptive scheduler.
443///
444/// # Bayes Factor Interpretation
445///
446/// The `log_bayes_factor` represents log10(P(evidence|apply_now) / P(evidence|coalesce)):
447/// - Positive values favor immediate apply (respond quickly)
448/// - Negative values favor coalescing (wait for more events)
449/// - |LBF| > 1 is "strong" evidence, |LBF| > 2 is "decisive"
450///
451/// # Example
452///
453/// ```ignore
454/// let evidence = DecisionEvidence {
455///     log_bayes_factor: 1.5,  // Strong evidence to apply now
456///     regime_contribution: 0.8,
457///     timing_contribution: 0.5,
458///     rate_contribution: 0.2,
459///     explanation: "Steady regime with long idle interval".to_string(),
460/// };
461/// ```
462#[derive(Debug, Clone)]
463pub struct DecisionEvidence {
464    /// Log10 Bayes factor: positive favors apply, negative favors coalesce.
465    pub log_bayes_factor: f64,
466
467    /// Contribution from regime detection (Steady vs Burst).
468    pub regime_contribution: f64,
469
470    /// Contribution from timing (dt_ms, time since last render).
471    pub timing_contribution: f64,
472
473    /// Contribution from event rate.
474    pub rate_contribution: f64,
475
476    /// Human-readable explanation of the decision.
477    pub explanation: String,
478}
479
480impl DecisionEvidence {
481    /// Evidence strongly favoring immediate apply (Steady regime, long idle).
482    #[must_use]
483    pub fn favor_apply(regime: Regime, dt_ms: f64, event_rate: f64) -> Self {
484        let regime_contrib = if regime == Regime::Steady { 1.0 } else { -0.5 };
485        let timing_contrib = (dt_ms / 50.0).min(2.0); // Higher dt -> favor apply
486        let rate_contrib = if event_rate < 5.0 { 0.5 } else { -0.3 };
487
488        let lbf = regime_contrib + timing_contrib + rate_contrib;
489
490        Self {
491            log_bayes_factor: lbf,
492            regime_contribution: regime_contrib,
493            timing_contribution: timing_contrib,
494            rate_contribution: rate_contrib,
495            explanation: format!(
496                "Regime={:?} (contrib={:.2}), dt={:.1}ms (contrib={:.2}), rate={:.1}/s (contrib={:.2})",
497                regime, regime_contrib, dt_ms, timing_contrib, event_rate, rate_contrib
498            ),
499        }
500    }
501
502    /// Evidence favoring coalescing (Burst regime, high rate).
503    #[must_use]
504    pub fn favor_coalesce(regime: Regime, dt_ms: f64, event_rate: f64) -> Self {
505        let regime_contrib = if regime == Regime::Burst { 1.0 } else { -0.5 };
506        let timing_contrib = (20.0 / dt_ms.max(1.0)).min(2.0); // Lower dt -> favor coalesce
507        let rate_contrib = if event_rate > 10.0 { 0.5 } else { -0.3 };
508
509        let lbf = -(regime_contrib + timing_contrib + rate_contrib);
510
511        Self {
512            log_bayes_factor: lbf,
513            regime_contribution: regime_contrib,
514            timing_contribution: timing_contrib,
515            rate_contribution: rate_contrib,
516            explanation: format!(
517                "Regime={:?} (contrib={:.2}), dt={:.1}ms (contrib={:.2}), rate={:.1}/s (contrib={:.2})",
518                regime, regime_contrib, dt_ms, timing_contrib, event_rate, rate_contrib
519            ),
520        }
521    }
522
523    /// Evidence for a forced deadline decision.
524    #[must_use]
525    pub fn forced_deadline(deadline_ms: f64) -> Self {
526        Self {
527            log_bayes_factor: f64::INFINITY,
528            regime_contribution: 0.0,
529            timing_contribution: deadline_ms,
530            rate_contribution: 0.0,
531            explanation: format!("Forced by hard deadline ({:.1}ms)", deadline_ms),
532        }
533    }
534
535    /// Serialize to JSONL format.
536    #[must_use]
537    pub fn to_jsonl(
538        &self,
539        run_id: &str,
540        screen_mode: ScreenMode,
541        cols: u16,
542        rows: u16,
543        event_idx: u64,
544    ) -> String {
545        let lbf_str = if self.log_bayes_factor.is_infinite() {
546            "\"inf\"".to_string()
547        } else {
548            format!("{:.3}", self.log_bayes_factor)
549        };
550        let prefix = evidence_prefix(run_id, screen_mode, cols, rows, event_idx);
551        format!(
552            r#"{{{prefix},"event":"decision_evidence","log_bayes_factor":{},"regime_contribution":{:.3},"timing_contribution":{:.3},"rate_contribution":{:.3},"explanation":"{}"}}"#,
553            lbf_str,
554            self.regime_contribution,
555            self.timing_contribution,
556            self.rate_contribution,
557            json_escape(&self.explanation)
558        )
559    }
560
561    /// Check if evidence strongly supports the action (|LBF| > 1).
562    #[must_use]
563    pub fn is_strong(&self) -> bool {
564        self.log_bayes_factor.abs() > 1.0
565    }
566
567    /// Check if evidence decisively supports the action (|LBF| > 2).
568    #[must_use]
569    pub fn is_decisive(&self) -> bool {
570        self.log_bayes_factor.abs() > 2.0 || self.log_bayes_factor.is_infinite()
571    }
572}
573
574/// Decision log entry for observability.
575#[derive(Debug, Clone)]
576pub struct DecisionLog {
577    /// Timestamp of the decision.
578    pub timestamp: Instant,
579    /// Elapsed time since logging started (ms).
580    pub elapsed_ms: f64,
581    /// Event index in session.
582    pub event_idx: u64,
583    /// Time since last event (ms).
584    pub dt_ms: f64,
585    /// Current event rate (events/sec).
586    pub event_rate: f64,
587    /// Detected regime.
588    pub regime: Regime,
589    /// Chosen action.
590    pub action: &'static str,
591    /// Pending size (if any).
592    pub pending_size: Option<(u16, u16)>,
593    /// Applied size (for apply decisions).
594    pub applied_size: Option<(u16, u16)>,
595    /// Time since last render (ms).
596    pub time_since_render_ms: f64,
597    /// Time spent coalescing until apply (ms).
598    pub coalesce_ms: Option<f64>,
599    /// Was forced by deadline.
600    pub forced: bool,
601    /// Transition reason code if this decision coincided with a regime transition.
602    pub transition_reason_code: Option<TransitionReasonCode>,
603    /// Transition confidence if this decision coincided with a regime transition.
604    pub transition_confidence: Option<f64>,
605    /// Detector that made the regime decision this row reflects.
606    pub detector: RegimeDetector,
607    /// BOCPD posterior probability of burst at decision time (`None` when
608    /// BOCPD is off or the posterior is not finite).
609    pub p_burst: Option<f64>,
610}
611
612impl DecisionLog {
613    /// Serialize decision log to JSONL format.
614    #[must_use]
615    pub fn to_jsonl(&self, run_id: &str, screen_mode: ScreenMode, cols: u16, rows: u16) -> String {
616        let (pending_w, pending_h) = match self.pending_size {
617            Some((w, h)) => (w.to_string(), h.to_string()),
618            None => ("null".to_string(), "null".to_string()),
619        };
620        let (applied_w, applied_h) = match self.applied_size {
621            Some((w, h)) => (w.to_string(), h.to_string()),
622            None => ("null".to_string(), "null".to_string()),
623        };
624        let coalesce_ms = match self.coalesce_ms {
625            Some(ms) => format!("{:.3}", ms),
626            None => "null".to_string(),
627        };
628        let transition_reason_code = self
629            .transition_reason_code
630            .map(TransitionReasonCode::as_str)
631            .map(|code| format!(r#""{code}""#))
632            .unwrap_or_else(|| "null".to_string());
633        let transition_confidence = self
634            .transition_confidence
635            .map(|confidence| format!("{confidence:.6}"))
636            .unwrap_or_else(|| "null".to_string());
637        let prefix = evidence_prefix(run_id, screen_mode, cols, rows, self.event_idx);
638
639        format!(
640            r#"{{{prefix},"event":"decision","idx":{},"elapsed_ms":{:.3},"dt_ms":{:.3},"event_rate":{:.3},"regime":"{}","action":"{}","pending_w":{},"pending_h":{},"applied_w":{},"applied_h":{},"time_since_render_ms":{:.3},"coalesce_ms":{},"forced":{},"transition_reason_code":{},"transition_confidence":{},"detector":"{}","p_burst":{}}}"#,
641            self.event_idx,
642            self.elapsed_ms,
643            self.dt_ms,
644            self.event_rate,
645            self.regime.as_str(),
646            self.action,
647            pending_w,
648            pending_h,
649            applied_w,
650            applied_h,
651            self.time_since_render_ms,
652            coalesce_ms,
653            self.forced,
654            transition_reason_code,
655            transition_confidence,
656            self.detector.as_str(),
657            self.p_burst
658                .map_or_else(|| "null".to_string(), |p| format!("{p:.6}"))
659        )
660    }
661}
662
663#[derive(Debug, Clone, Copy)]
664struct PendingTransitionEvidence {
665    reason_code: TransitionReasonCode,
666    confidence: f64,
667}
668
669/// Transition evidence entry emitted when the controller changes regime.
670#[derive(Debug, Clone)]
671pub struct RegimeTransitionLog {
672    /// Timestamp when transition occurred.
673    pub timestamp: Instant,
674    /// Event index when transition occurred.
675    pub event_idx: u64,
676    /// Previous regime.
677    pub from_regime: Regime,
678    /// New regime.
679    pub to_regime: Regime,
680    /// Structured reason code.
681    pub reason_code: TransitionReasonCode,
682    /// Confidence in [0, 1].
683    pub confidence: f64,
684    /// Event rate at transition time.
685    pub event_rate: f64,
686    /// BOCPD posterior probability of burst, if available.
687    pub p_burst: Option<f64>,
688    /// Current cooldown counter after transition accounting.
689    pub cooldown_remaining: u32,
690    /// Detector that made the transition.
691    pub detector: RegimeDetector,
692}
693
694impl RegimeTransitionLog {
695    /// Serialize transition evidence to JSONL format.
696    #[must_use]
697    pub fn to_jsonl(&self, run_id: &str, screen_mode: ScreenMode, cols: u16, rows: u16) -> String {
698        let prefix = evidence_prefix(run_id, screen_mode, cols, rows, self.event_idx);
699        let p_burst = self
700            .p_burst
701            .map(|value| format!("{value:.6}"))
702            .unwrap_or_else(|| "null".to_string());
703        format!(
704            r#"{{{prefix},"event":"regime_transition","from_regime":"{}","to_regime":"{}","reason_code":"{}","confidence":{:.6},"event_rate":{:.3},"p_burst":{},"detector":"{}","cooldown_remaining":{}}}"#,
705            self.from_regime.as_str(),
706            self.to_regime.as_str(),
707            self.reason_code.as_str(),
708            self.confidence,
709            self.event_rate,
710            p_burst,
711            self.detector.as_str(),
712            self.cooldown_remaining,
713        )
714    }
715}
716
717/// Adaptive resize stream coalescer.
718///
719/// Implements latest-wins coalescing with regime-aware behavior.
720#[derive(Debug)]
721pub struct ResizeCoalescer {
722    config: CoalescerConfig,
723
724    /// Currently pending size (latest wins).
725    pending_size: Option<(u16, u16)>,
726
727    /// Last applied size.
728    last_applied: (u16, u16),
729
730    /// Timestamp of first event in current coalesce window.
731    window_start: Option<Instant>,
732
733    /// Timestamp of last resize event.
734    last_event: Option<Instant>,
735
736    /// Timestamp of last render.
737    last_render: Instant,
738
739    /// Current detected regime.
740    regime: Regime,
741
742    /// Frames remaining in cooldown (for burst exit hysteresis).
743    cooldown_remaining: u32,
744
745    /// Recent event timestamps for rate calculation.
746    event_times: VecDeque<Instant>,
747
748    /// Total event count.
749    event_count: u64,
750
751    /// Logging start time for elapsed timestamps.
752    log_start: Option<Instant>,
753
754    /// Decision logs (if logging enabled).
755    logs: Vec<DecisionLog>,
756    /// Regime transition evidence logs.
757    transition_logs: Vec<RegimeTransitionLog>,
758    /// Pending transition evidence to attach to the next decision row.
759    pending_transition_evidence: Option<PendingTransitionEvidence>,
760    /// Evidence sink for JSONL decision logs.
761    evidence_sink: Option<EvidenceSink>,
762    /// Whether config has been logged to the evidence sink.
763    config_logged: bool,
764    /// Run identifier for evidence logs.
765    evidence_run_id: String,
766    /// Screen mode label for evidence logs.
767    evidence_screen_mode: ScreenMode,
768
769    // --- Telemetry integration (bd-1rz0.7) ---
770    /// Telemetry hooks for external observability.
771    telemetry_hooks: Option<TelemetryHooks>,
772
773    /// Count of regime transitions during this session.
774    regime_transitions: u64,
775
776    /// Events coalesced in current window.
777    events_in_window: u64,
778
779    /// History of cycle times (ms) for percentile calculation.
780    cycle_times: Vec<f64>,
781
782    /// BOCPD detector for Bayesian regime detection (when enabled).
783    bocpd: Option<BocpdDetector>,
784
785    /// Detector that made the most recent regime decision.
786    last_detector: RegimeDetector,
787
788    /// Regime decisions per detector.
789    detector_decisions: DetectorDecisions,
790}
791
792/// Cycle time percentiles for reflow diagnostics (bd-1rz0.7).
793#[derive(Debug, Clone, Copy)]
794pub struct CycleTimePercentiles {
795    /// 50th percentile (median) cycle time in ms.
796    pub p50_ms: f64,
797    /// 95th percentile cycle time in ms.
798    pub p95_ms: f64,
799    /// 99th percentile cycle time in ms.
800    pub p99_ms: f64,
801    /// Number of samples.
802    pub count: usize,
803    /// Mean cycle time in ms.
804    pub mean_ms: f64,
805}
806
807impl CycleTimePercentiles {
808    /// Serialize to JSONL format.
809    #[must_use]
810    pub fn to_jsonl(&self) -> String {
811        format!(
812            r#"{{"event":"cycle_time_percentiles","p50_ms":{:.3},"p95_ms":{:.3},"p99_ms":{:.3},"mean_ms":{:.3},"count":{}}}"#,
813            self.p50_ms, self.p95_ms, self.p99_ms, self.mean_ms, self.count
814        )
815    }
816}
817
818impl ResizeCoalescer {
819    /// Create a new coalescer with the given configuration and initial size.
820    pub fn new(config: CoalescerConfig, initial_size: (u16, u16)) -> Self {
821        let bocpd = if config.enable_bocpd {
822            let mut bocpd_cfg = config.bocpd_config.clone().unwrap_or_default();
823            if config.enable_logging {
824                bocpd_cfg.enable_logging = true;
825            }
826            Some(BocpdDetector::new(bocpd_cfg))
827        } else {
828            None
829        };
830
831        Self {
832            config,
833            pending_size: None,
834            last_applied: initial_size,
835            window_start: None,
836            last_event: None,
837            last_render: Instant::now(),
838            regime: Regime::Steady,
839            cooldown_remaining: 0,
840            event_times: VecDeque::new(),
841            event_count: 0,
842            log_start: None,
843            logs: Vec::new(),
844            transition_logs: Vec::new(),
845            pending_transition_evidence: None,
846            evidence_sink: None,
847            config_logged: false,
848            evidence_run_id: default_resize_run_id(),
849            evidence_screen_mode: ScreenMode::AltScreen,
850            telemetry_hooks: None,
851            regime_transitions: 0,
852            events_in_window: 0,
853            cycle_times: Vec::new(),
854            bocpd,
855            last_detector: RegimeDetector::Heuristic,
856            detector_decisions: DetectorDecisions::default(),
857        }
858    }
859
860    /// Attach telemetry hooks for external observability.
861    #[must_use]
862    pub fn with_telemetry_hooks(mut self, hooks: TelemetryHooks) -> Self {
863        self.telemetry_hooks = Some(hooks);
864        self
865    }
866
867    /// Attach an evidence sink for JSONL decision logs.
868    #[must_use]
869    pub fn with_evidence_sink(mut self, sink: EvidenceSink) -> Self {
870        self.evidence_sink = Some(sink);
871        self.config_logged = false;
872        self
873    }
874
875    /// Set the run identifier used in evidence logs.
876    #[must_use]
877    pub fn with_evidence_run_id(mut self, run_id: impl Into<String>) -> Self {
878        self.evidence_run_id = run_id.into();
879        self
880    }
881
882    /// Set the screen mode label used in evidence logs.
883    #[must_use]
884    pub fn with_screen_mode(mut self, screen_mode: ScreenMode) -> Self {
885        self.evidence_screen_mode = screen_mode;
886        self
887    }
888
889    /// Set or clear the evidence sink.
890    pub fn set_evidence_sink(&mut self, sink: Option<EvidenceSink>) {
891        self.evidence_sink = sink;
892        self.config_logged = false;
893    }
894
895    /// Set the last render time (for deterministic testing).
896    #[must_use]
897    pub fn with_last_render(mut self, time: Instant) -> Self {
898        self.last_render = time;
899        self
900    }
901
902    /// Record an externally-applied resize (immediate path).
903    pub fn record_external_apply(&mut self, width: u16, height: u16, now: Instant) {
904        self.event_count += 1;
905        self.event_times.push_back(now);
906        while self.event_times.len() > self.config.rate_window_size {
907            self.event_times.pop_front();
908        }
909        self.update_regime(now);
910        // The frame loop never ticks the coalescer in
911        // `ResizeBehavior::Immediate`, so the cooldown-based exit in `tick_at`
912        // cannot run on this path; without an event-path exit one burst
913        // pinned the regime to `Burst` for the rest of the session
914        // (bd-1za0z item 2). BOCPD mode exits through its posterior above;
915        // while the heuristic fallback is deciding, it owns the exit too.
916        if self.heuristic_decides() && self.regime == Regime::Burst {
917            let rate = self.calculate_event_rate(now);
918            if rate < self.config.burst_exit_rate {
919                self.record_regime_transition(
920                    now,
921                    Regime::Steady,
922                    TransitionReasonCode::HeuristicExitBurstRate,
923                    (1.0 - (rate / self.config.burst_exit_rate)).clamp(0.0, 1.0),
924                    rate,
925                    None,
926                );
927            }
928        }
929
930        self.pending_size = None;
931        self.window_start = None;
932        self.last_event = Some(now);
933        self.last_applied = (width, height);
934        self.last_render = now;
935        self.events_in_window = 0;
936        self.cooldown_remaining = 0;
937
938        self.log_decision(now, "apply_immediate", false, Some(0.0), Some(0.0));
939
940        if let Some(ref hooks) = self.telemetry_hooks
941            && let Some(entry) = self.logs.last()
942        {
943            hooks.fire_resize_applied(entry);
944        }
945    }
946
947    /// Get current regime transition count.
948    #[must_use]
949    pub fn regime_transition_count(&self) -> u64 {
950        self.regime_transitions
951    }
952
953    /// Get cycle time percentiles (p50, p95, p99) in milliseconds.
954    /// Returns None if no cycle times recorded.
955    #[must_use]
956    pub fn cycle_time_percentiles(&self) -> Option<CycleTimePercentiles> {
957        if self.cycle_times.is_empty() {
958            return None;
959        }
960
961        let mut sorted = self.cycle_times.clone();
962        sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
963
964        let len = sorted.len();
965        let p50_idx = len / 2;
966        let p95_idx = (len * 95) / 100;
967        let p99_idx = (len * 99) / 100;
968
969        Some(CycleTimePercentiles {
970            p50_ms: sorted[p50_idx],
971            p95_ms: sorted[p95_idx.min(len - 1)],
972            p99_ms: sorted[p99_idx.min(len - 1)],
973            count: len,
974            mean_ms: sorted.iter().sum::<f64>() / len as f64,
975        })
976    }
977
978    /// Handle a resize event.
979    ///
980    /// Returns the action to take immediately.
981    pub fn handle_resize(&mut self, width: u16, height: u16) -> CoalesceAction {
982        self.handle_resize_at(width, height, Instant::now())
983    }
984
985    /// Handle a resize event at a specific time (for testing).
986    pub fn handle_resize_at(&mut self, width: u16, height: u16, now: Instant) -> CoalesceAction {
987        self.event_count += 1;
988
989        // Calculate dt
990        let dt = self.last_event.map(|t| duration_since_or_zero(now, t));
991        let dt_ms = dt.map(|d| d.as_secs_f64() * 1000.0).unwrap_or(0.0);
992
993        // Track event time for rate calculation
994        // Clear stale events that artificially inflate the window duration
995        if dt_ms > 1000.0 {
996            self.event_times.clear();
997        }
998
999        self.event_times.push_back(now);
1000        while self.event_times.len() > self.config.rate_window_size {
1001            self.event_times.pop_front();
1002        }
1003
1004        // Update regime based on event rate
1005        self.update_regime(now);
1006
1007        self.last_event = Some(now);
1008
1009        // If no pending, and this matches current size, no action needed
1010        if self.pending_size.is_none() && (width, height) == self.last_applied {
1011            self.log_decision(now, "skip_same_size", false, Some(dt_ms), None);
1012            return CoalesceAction::None;
1013        }
1014
1015        // Whether work was already waiting BEFORE this event arrived: a
1016        // deadline apply counts as forced only if it breached the SLA of
1017        // previously-pending work, not this fresh event (bd-1za0z).
1018        let had_pending_before_event = self.pending_size.is_some();
1019
1020        // Update pending size (latest wins)
1021        self.pending_size = Some((width, height));
1022
1023        // Track events in current coalesce window (bd-1rz0.7)
1024        self.events_in_window += 1;
1025
1026        // Mark window start if this is first event
1027        if self.window_start.is_none() {
1028            self.window_start = Some(now);
1029        }
1030
1031        // Check hard deadline. `forced` must mean "work was ALREADY waiting
1032        // and sat past its SLA deadline" — an isolated resize arriving after
1033        // a quiet gap is applied instantly, but it is not a deadline breach
1034        // and must not inflate the SLA forced count (bd-1za0z).
1035        let time_since_render = duration_since_or_zero(now, self.last_render);
1036        if time_since_render >= Duration::from_millis(self.config.hard_deadline_ms) {
1037            return self.apply_pending_at(now, had_pending_before_event);
1038        }
1039
1040        // If enough time has passed since the last event, apply now.
1041        // In heuristic mode, only apply immediately in Steady; burst applies via tick.
1042        let time_ok = match dt {
1043            Some(d) => d >= Duration::from_millis(self.current_delay_ms()),
1044            None => false, // First event must be coalesced to establish steady state timing
1045        };
1046
1047        if time_ok && (!self.heuristic_decides() || self.regime == Regime::Steady) {
1048            return self.apply_pending_at(now, false);
1049        }
1050
1051        self.log_decision(now, "coalesce", false, Some(dt_ms), None);
1052
1053        // Fire decision hook for coalesce events (bd-1rz0.7)
1054        if let Some(ref hooks) = self.telemetry_hooks
1055            && let Some(entry) = self.logs.last()
1056        {
1057            hooks.fire_decision(entry);
1058        }
1059
1060        // Coalescing: the runtime keeps showing the last frame. (A separate
1061        // `ShowPlaceholder` action existed here for years and was consumed by
1062        // nothing; removed under bd-1za0z item 2 / G12.)
1063        CoalesceAction::None
1064    }
1065
1066    /// Tick the coalescer (call each frame).
1067    ///
1068    /// Returns the action to take.
1069    pub fn tick(&mut self) -> CoalesceAction {
1070        self.tick_at(Instant::now())
1071    }
1072
1073    /// Tick at a specific time (for testing).
1074    pub fn tick_at(&mut self, now: Instant) -> CoalesceAction {
1075        // Heuristic cooldown exit: HEURISTIC MODE ONLY. In BOCPD mode the
1076        // posterior owns regime changes (BocpdPosteriorSteady on the next
1077        // event); letting this rate-based exit fire too produced
1078        // contradictory transitions — and with a low-rate custom BocpdConfig
1079        // it was the only between-events Burst exit, fighting the posterior
1080        // and flapping the regime (bd-1za0z). While the heuristic fallback
1081        // is deciding (BOCPD posterior undefined) it must own the exit too,
1082        // or an out-of-range burst would pin the regime until the posterior
1083        // sees an in-range event again.
1084        if self.regime == Regime::Burst && self.heuristic_decides() {
1085            let rate = self.calculate_event_rate(now);
1086            if rate >= self.config.burst_exit_rate {
1087                self.cooldown_remaining = self.config.cooldown_frames.max(1);
1088            } else if self.cooldown_remaining > 0 {
1089                self.cooldown_remaining -= 1;
1090                if self.cooldown_remaining == 0 {
1091                    self.record_regime_transition(
1092                        now,
1093                        Regime::Steady,
1094                        TransitionReasonCode::HeuristicExitBurstCooldown,
1095                        (1.0 - (rate / self.config.burst_exit_rate)).clamp(0.0, 1.0),
1096                        rate,
1097                        None,
1098                    );
1099                }
1100            }
1101        }
1102
1103        // BOCPD idle exit: the posterior only moves on events, so a burst
1104        // followed by silence would otherwise stay `Burst` until the next
1105        // resize. Once the silence is at least the steady mean inter-arrival
1106        // the run is over by the model's own parameters; the confidence is
1107        // the probability a burst inter-arrival would not have lasted this
1108        // long, 1 - exp(-idle / mu_burst).
1109        if self.regime == Regime::Burst
1110            && !self.heuristic_decides()
1111            && let Some(idle_exit) = self.bocpd_idle_exit(now)
1112        {
1113            let (confidence, rate, p_burst) = idle_exit;
1114            self.record_regime_transition(
1115                now,
1116                Regime::Steady,
1117                TransitionReasonCode::BocpdIdleExit,
1118                confidence,
1119                rate,
1120                Some(p_burst),
1121            );
1122        }
1123
1124        if self.pending_size.is_none() {
1125            return CoalesceAction::None;
1126        }
1127
1128        if self.window_start.is_none() {
1129            return CoalesceAction::None;
1130        }
1131
1132        // Check hard deadline
1133        let time_since_render = duration_since_or_zero(now, self.last_render);
1134        if time_since_render >= Duration::from_millis(self.config.hard_deadline_ms) {
1135            return self.apply_pending_at(now, true);
1136        }
1137
1138        let delay_ms = self.current_delay_ms();
1139
1140        // Check if enough time has passed since last event
1141        if let Some(last_event) = self.last_event {
1142            let since_last_event = duration_since_or_zero(now, last_event);
1143            if since_last_event >= Duration::from_millis(delay_ms) {
1144                return self.apply_pending_at(now, false);
1145            }
1146        }
1147
1148        CoalesceAction::None
1149    }
1150
1151    /// Time until the pending resize should be applied.
1152    pub fn time_until_apply(&self, now: Instant) -> Option<Duration> {
1153        let _pending = self.pending_size?;
1154
1155        // 1. Check hard deadline relative to last_render
1156        let time_since_render = duration_since_or_zero(now, self.last_render);
1157        let hard_deadline = Duration::from_millis(self.config.hard_deadline_ms);
1158        let hard_deadline_remaining = hard_deadline.saturating_sub(time_since_render);
1159
1160        // 2. Check delay since last event
1161        let delay_remaining = if let Some(last_event) = self.last_event {
1162            let since_last_event = duration_since_or_zero(now, last_event);
1163            let delay = Duration::from_millis(self.current_delay_ms());
1164            delay.saturating_sub(since_last_event)
1165        } else {
1166            Duration::ZERO
1167        };
1168
1169        // We apply when BOTH conditions are met (or hard deadline reached)
1170        // Wait, the logic in handle_resize/tick is:
1171        // IF (time_since_render >= hard_deadline) OR (since_last_event >= delay)
1172        // So time_until_apply should be the MIN of these two.
1173        Some(hard_deadline_remaining.min(delay_remaining))
1174    }
1175
1176    /// Check if there's a pending resize.
1177    #[inline]
1178    pub fn has_pending(&self) -> bool {
1179        self.pending_size.is_some()
1180    }
1181
1182    /// Get the current regime.
1183    #[inline]
1184    pub fn regime(&self) -> Regime {
1185        self.regime
1186    }
1187
1188    /// Check if BOCPD-based regime detection is enabled.
1189    #[inline]
1190    pub fn bocpd_enabled(&self) -> bool {
1191        self.bocpd.is_some()
1192    }
1193
1194    /// Detector that made the most recent regime decision (`Heuristic`
1195    /// before the first event).
1196    #[inline]
1197    pub fn last_detector(&self) -> RegimeDetector {
1198        self.last_detector
1199    }
1200
1201    /// Regime decisions made by each detector in this session.
1202    #[inline]
1203    pub fn detector_decisions(&self) -> DetectorDecisions {
1204        self.detector_decisions
1205    }
1206
1207    /// Get the BOCPD detector for inspection (if enabled).
1208    ///
1209    /// Returns `None` if BOCPD is not enabled.
1210    #[inline]
1211    pub fn bocpd(&self) -> Option<&BocpdDetector> {
1212        self.bocpd.as_ref()
1213    }
1214
1215    /// Get the current P(burst) from BOCPD (if enabled).
1216    ///
1217    /// Returns the posterior probability that the system is in burst regime.
1218    /// Returns `None` if BOCPD is not enabled.
1219    #[inline]
1220    pub fn bocpd_p_burst(&self) -> Option<f64> {
1221        self.bocpd.as_ref().map(|b| b.p_burst())
1222    }
1223
1224    /// Get the recommended delay from BOCPD (if enabled).
1225    ///
1226    /// Returns the recommended coalesce delay in milliseconds based on the
1227    /// current posterior distribution. Returns `None` if BOCPD is not enabled.
1228    #[inline]
1229    pub fn bocpd_recommended_delay(&self) -> Option<u64> {
1230        self.bocpd
1231            .as_ref()
1232            .map(|b| b.recommended_delay(self.config.steady_delay_ms, self.config.burst_delay_ms))
1233    }
1234
1235    /// Get the current event rate (events/second).
1236    pub fn event_rate(&self) -> f64 {
1237        self.calculate_event_rate(Instant::now())
1238    }
1239
1240    /// Get the last applied size.
1241    #[inline]
1242    pub fn last_applied(&self) -> (u16, u16) {
1243        self.last_applied
1244    }
1245
1246    /// Get decision logs (if logging enabled).
1247    pub fn logs(&self) -> &[DecisionLog] {
1248        &self.logs
1249    }
1250
1251    /// Get regime transition evidence logs.
1252    pub fn transition_logs(&self) -> &[RegimeTransitionLog] {
1253        &self.transition_logs
1254    }
1255
1256    /// Record a coalesce cycle time, retaining only the most recent window.
1257    ///
1258    /// Unbounded retention is a slow leak in long-lived sessions (one entry
1259    /// per applied resize); percentiles over the recent window are also the
1260    /// more meaningful telemetry.
1261    fn record_cycle_time(&mut self, coalesce_ms: f64) {
1262        self.cycle_times.push(coalesce_ms);
1263        let len = self.cycle_times.len();
1264        if len > MAX_CYCLE_TIME_SAMPLES {
1265            self.cycle_times.drain(..len - MAX_CYCLE_TIME_SAMPLES);
1266        }
1267    }
1268
1269    /// Append a regime-transition evidence entry, retaining only the most
1270    /// recent window (one entry per regime flip, never truncated by the
1271    /// runtime otherwise).
1272    fn push_transition_log(&mut self, log: RegimeTransitionLog) {
1273        self.transition_logs.push(log);
1274        let len = self.transition_logs.len();
1275        if len > MAX_TRANSITION_LOGS {
1276            self.transition_logs.drain(..len - MAX_TRANSITION_LOGS);
1277        }
1278    }
1279
1280    /// Clear decision logs.
1281    pub fn clear_logs(&mut self) {
1282        self.logs.clear();
1283        self.transition_logs.clear();
1284        self.pending_transition_evidence = None;
1285        self.log_start = None;
1286        self.config_logged = false;
1287    }
1288
1289    /// Get statistics about the coalescer.
1290    pub fn stats(&self) -> CoalescerStats {
1291        CoalescerStats {
1292            event_count: self.event_count,
1293            regime: self.regime,
1294            event_rate: self.event_rate(),
1295            has_pending: self.pending_size.is_some(),
1296            last_applied: self.last_applied,
1297            detector: self.last_detector,
1298            detector_decisions: self.detector_decisions,
1299        }
1300    }
1301
1302    /// Export decision logs as JSONL (one entry per line).
1303    ///
1304    /// Stamping semantics (by design, bd-1za0z item 2): every row carries its
1305    /// own decision-time `pending_size` / `applied_size`; the `cols` / `rows`
1306    /// header fields are the size applied at export time, so a batch export
1307    /// answers "what was the terminal when this file was written", not "what
1308    /// was it at each decision". Consumers that need the per-decision size
1309    /// read the row's own fields.
1310    #[must_use]
1311    pub fn decision_logs_jsonl(&self) -> String {
1312        let (cols, rows) = self.last_applied;
1313        let run_id = self.evidence_run_id.as_str();
1314        let screen_mode = self.evidence_screen_mode;
1315        self.logs
1316            .iter()
1317            .map(|entry| entry.to_jsonl(run_id, screen_mode, cols, rows))
1318            .collect::<Vec<_>>()
1319            .join("\n")
1320    }
1321
1322    /// Compute a deterministic checksum of decision logs.
1323    #[must_use]
1324    pub fn decision_checksum(&self) -> u64 {
1325        let mut hash = FNV_OFFSET_BASIS;
1326        for entry in &self.logs {
1327            fnv_hash_bytes(&mut hash, &entry.event_idx.to_le_bytes());
1328            fnv_hash_bytes(&mut hash, &entry.elapsed_ms.to_bits().to_le_bytes());
1329            fnv_hash_bytes(&mut hash, &entry.dt_ms.to_bits().to_le_bytes());
1330            fnv_hash_bytes(&mut hash, &entry.event_rate.to_bits().to_le_bytes());
1331            fnv_hash_bytes(
1332                &mut hash,
1333                &[match entry.regime {
1334                    Regime::Steady => 0u8,
1335                    Regime::Burst => 1u8,
1336                }],
1337            );
1338            fnv_hash_bytes(&mut hash, entry.action.as_bytes());
1339            fnv_hash_bytes(&mut hash, &[0u8]); // separator
1340
1341            fnv_hash_bytes(&mut hash, &[entry.pending_size.is_some() as u8]);
1342            if let Some((w, h)) = entry.pending_size {
1343                fnv_hash_bytes(&mut hash, &w.to_le_bytes());
1344                fnv_hash_bytes(&mut hash, &h.to_le_bytes());
1345            }
1346
1347            fnv_hash_bytes(&mut hash, &[entry.applied_size.is_some() as u8]);
1348            if let Some((w, h)) = entry.applied_size {
1349                fnv_hash_bytes(&mut hash, &w.to_le_bytes());
1350                fnv_hash_bytes(&mut hash, &h.to_le_bytes());
1351            }
1352
1353            fnv_hash_bytes(
1354                &mut hash,
1355                &entry.time_since_render_ms.to_bits().to_le_bytes(),
1356            );
1357            fnv_hash_bytes(&mut hash, &[entry.coalesce_ms.is_some() as u8]);
1358            if let Some(ms) = entry.coalesce_ms {
1359                fnv_hash_bytes(&mut hash, &ms.to_bits().to_le_bytes());
1360            }
1361            fnv_hash_bytes(&mut hash, &[entry.forced as u8]);
1362            fnv_hash_bytes(&mut hash, &[entry.transition_reason_code.is_some() as u8]);
1363            if let Some(reason_code) = entry.transition_reason_code {
1364                fnv_hash_bytes(&mut hash, reason_code.as_str().as_bytes());
1365            }
1366            fnv_hash_bytes(&mut hash, &[entry.transition_confidence.is_some() as u8]);
1367            if let Some(confidence) = entry.transition_confidence {
1368                fnv_hash_bytes(&mut hash, &confidence.to_bits().to_le_bytes());
1369            }
1370        }
1371        hash
1372    }
1373
1374    /// Compute checksum as hex string.
1375    #[must_use]
1376    pub fn decision_checksum_hex(&self) -> String {
1377        format!("{:016x}", self.decision_checksum())
1378    }
1379
1380    /// Compute a summary of the decision log.
1381    #[must_use]
1382    #[allow(clippy::field_reassign_with_default)]
1383    pub fn decision_summary(&self) -> DecisionSummary {
1384        let mut summary = DecisionSummary::default();
1385        summary.decision_count = self.logs.len();
1386        summary.last_applied = self.last_applied;
1387        summary.regime = self.regime;
1388
1389        for entry in &self.logs {
1390            match entry.action {
1391                "apply" | "apply_forced" | "apply_immediate" => {
1392                    summary.apply_count += 1;
1393                    if entry.forced {
1394                        summary.forced_apply_count += 1;
1395                    }
1396                }
1397                "coalesce" => summary.coalesce_count += 1,
1398                "skip_same_size" => summary.skip_count += 1,
1399                _ => {}
1400            }
1401        }
1402
1403        summary.checksum = self.decision_checksum();
1404        summary
1405    }
1406
1407    /// Export config + decision logs + summary as JSONL.
1408    #[must_use]
1409    pub fn evidence_to_jsonl(&self) -> String {
1410        let mut lines = Vec::with_capacity(self.logs.len() + self.transition_logs.len() + 2);
1411        let (cols, rows) = self.last_applied;
1412        let run_id = self.evidence_run_id.as_str();
1413        let screen_mode = self.evidence_screen_mode;
1414        let summary_event_idx = self
1415            .logs
1416            .last()
1417            .map(|entry| entry.event_idx)
1418            .or_else(|| self.transition_logs.last().map(|entry| entry.event_idx))
1419            .unwrap_or(0);
1420        lines.push(self.config.to_jsonl(run_id, screen_mode, cols, rows, 0));
1421        lines.extend(
1422            self.logs
1423                .iter()
1424                .map(|entry| entry.to_jsonl(run_id, screen_mode, cols, rows)),
1425        );
1426        lines.extend(
1427            self.transition_logs
1428                .iter()
1429                .map(|entry| entry.to_jsonl(run_id, screen_mode, cols, rows)),
1430        );
1431        lines.push(self.decision_summary().to_jsonl(
1432            run_id,
1433            screen_mode,
1434            cols,
1435            rows,
1436            summary_event_idx,
1437        ));
1438        lines.join("\n")
1439    }
1440
1441    // --- Internal methods ---
1442
1443    fn apply_pending_at(&mut self, now: Instant, forced: bool) -> CoalesceAction {
1444        let Some((width, height)) = self.pending_size.take() else {
1445            return CoalesceAction::None;
1446        };
1447
1448        let coalesce_time = self
1449            .window_start
1450            .map(|s| duration_since_or_zero(now, s))
1451            .unwrap_or(Duration::ZERO);
1452        let coalesce_ms = coalesce_time.as_secs_f64() * 1000.0;
1453
1454        // Track cycle time for percentile calculation (bd-1rz0.7)
1455        self.record_cycle_time(coalesce_ms);
1456
1457        self.window_start = None;
1458        self.last_applied = (width, height);
1459        self.last_render = now;
1460
1461        // Reset events in window counter
1462        self.events_in_window = 0;
1463
1464        self.log_decision(
1465            now,
1466            if forced { "apply_forced" } else { "apply" },
1467            forced,
1468            None,
1469            Some(coalesce_ms),
1470        );
1471
1472        // Fire telemetry hooks (bd-1rz0.7)
1473        if let Some(ref hooks) = self.telemetry_hooks
1474            && let Some(entry) = self.logs.last()
1475        {
1476            hooks.fire_resize_applied(entry);
1477        }
1478
1479        CoalesceAction::ApplyResize {
1480            width,
1481            height,
1482            coalesce_time,
1483            forced_by_deadline: forced,
1484        }
1485    }
1486
1487    #[inline]
1488    fn current_delay_ms(&self) -> u64 {
1489        match (&self.bocpd, self.last_detector) {
1490            (Some(bocpd), RegimeDetector::Bocpd) => {
1491                bocpd.recommended_delay(self.config.steady_delay_ms, self.config.burst_delay_ms)
1492            }
1493            _ => match self.regime {
1494                Regime::Steady => self.config.steady_delay_ms,
1495                Regime::Burst => self.config.burst_delay_ms,
1496            },
1497        }
1498    }
1499
1500    /// True when the rate heuristic owns regime decisions right now: BOCPD
1501    /// is off, or the fallback decided the most recent event.
1502    #[inline]
1503    fn heuristic_decides(&self) -> bool {
1504        self.bocpd.is_none() || self.last_detector == RegimeDetector::Heuristic
1505    }
1506
1507    /// BOCPD-mode idle check for `tick_at`: when the silence since the last
1508    /// event has reached the steady mean inter-arrival, returns the
1509    /// transition confidence, the current event rate and the posterior so
1510    /// the caller can record a `BocpdIdleExit`.
1511    fn bocpd_idle_exit(&self, now: Instant) -> Option<(f64, f64, f64)> {
1512        let bocpd = self.bocpd.as_ref()?;
1513        let last_event = self.last_event?;
1514        let idle_ms = duration_since_or_zero(now, last_event).as_secs_f64() * 1000.0;
1515        let cfg = bocpd.config();
1516        if idle_ms < cfg.mu_steady_ms {
1517            return None;
1518        }
1519        let confidence =
1520            (1.0 - (-idle_ms / cfg.mu_burst_ms.max(f64::EPSILON)).exp()).clamp(0.0, 1.0);
1521        Some((confidence, self.calculate_event_rate(now), bocpd.p_burst()))
1522    }
1523
1524    /// Choose the detector for an event whose inter-arrival is
1525    /// `observation_ms` (`None` for the first event of the session).
1526    fn select_detector(&self, observation_ms: Option<f64>) -> RegimeDetector {
1527        let Some(bocpd) = self.bocpd.as_ref() else {
1528            return RegimeDetector::Heuristic;
1529        };
1530        if !self.config.heuristic_fallback {
1531            return RegimeDetector::Bocpd;
1532        }
1533        let cfg = bocpd.config();
1534        match observation_ms {
1535            None => RegimeDetector::Heuristic,
1536            Some(obs) if !obs.is_finite() => RegimeDetector::Heuristic,
1537            Some(obs) if obs < cfg.min_observation_ms || obs > cfg.max_observation_ms => {
1538                RegimeDetector::Heuristic
1539            }
1540            Some(_) => RegimeDetector::Bocpd,
1541        }
1542    }
1543
1544    fn update_regime(&mut self, now: Instant) {
1545        // Inter-arrival as the posterior would see it (`last_event` is the
1546        // previous event at this point of the event path).
1547        let observation_ms = self
1548            .last_event
1549            .map(|t| duration_since_or_zero(now, t).as_secs_f64() * 1000.0);
1550        let mut detector = self.select_detector(observation_ms);
1551
1552        // The posterior is always updated so it tracks the stream even while
1553        // the heuristic decides; only the verdict source changes.
1554        let posterior = self.bocpd.as_mut().map(|bocpd| {
1555            bocpd.observe_event(now);
1556            (bocpd.regime(), bocpd.p_burst())
1557        });
1558        if self.config.heuristic_fallback
1559            && let Some((_, p_burst)) = posterior
1560            && !p_burst.is_finite()
1561        {
1562            detector = RegimeDetector::Heuristic;
1563        }
1564
1565        if detector != self.last_detector {
1566            tracing::debug!(
1567                target: crate::telemetry_schema::TARGET_RESIZE,
1568                from = self.last_detector.as_str(),
1569                to = detector.as_str(),
1570                observation_ms = ?observation_ms,
1571                event_idx = self.event_count,
1572                "resize regime detector switched"
1573            );
1574        }
1575        self.last_detector = detector;
1576
1577        match detector {
1578            RegimeDetector::Bocpd => {
1579                self.detector_decisions.bocpd += 1;
1580                let Some((bocpd_regime, p_burst)) = posterior else {
1581                    return;
1582                };
1583                // Map BOCPD regime to coalescer regime.
1584                let proposed = match bocpd_regime {
1585                    BocpdRegime::Steady => Regime::Steady,
1586                    BocpdRegime::Burst => Regime::Burst,
1587                    // During transition, maintain current regime to avoid thrashing.
1588                    BocpdRegime::Transitional => self.regime,
1589                };
1590                if proposed != self.regime {
1591                    let (reason_code, confidence) = if proposed == Regime::Burst {
1592                        (
1593                            TransitionReasonCode::BocpdPosteriorBurst,
1594                            p_burst.clamp(0.0, 1.0),
1595                        )
1596                    } else {
1597                        (
1598                            TransitionReasonCode::BocpdPosteriorSteady,
1599                            (1.0 - p_burst).clamp(0.0, 1.0),
1600                        )
1601                    };
1602                    let rate = self.calculate_event_rate(now);
1603                    self.record_regime_transition(
1604                        now,
1605                        proposed,
1606                        reason_code,
1607                        confidence,
1608                        rate,
1609                        Some(p_burst),
1610                    );
1611                }
1612            }
1613            RegimeDetector::Heuristic => {
1614                self.detector_decisions.heuristic += 1;
1615                let rate = self.calculate_event_rate(now);
1616                let p_burst = posterior.map(|(_, p)| p).filter(|p| p.is_finite());
1617
1618                match self.regime {
1619                    Regime::Steady => {
1620                        if rate >= self.config.burst_enter_rate {
1621                            self.cooldown_remaining = self.config.cooldown_frames.max(1);
1622                            let confidence = (rate / self.config.burst_enter_rate).clamp(0.0, 1.0);
1623                            self.record_regime_transition(
1624                                now,
1625                                Regime::Burst,
1626                                TransitionReasonCode::HeuristicEnterBurstRate,
1627                                confidence,
1628                                rate,
1629                                p_burst,
1630                            );
1631                        }
1632                    }
1633                    Regime::Burst => {
1634                        if rate >= self.config.burst_exit_rate {
1635                            self.cooldown_remaining = self.config.cooldown_frames.max(1);
1636                        }
1637                    }
1638                }
1639            }
1640        }
1641    }
1642
1643    fn record_regime_transition(
1644        &mut self,
1645        now: Instant,
1646        to_regime: Regime,
1647        reason_code: TransitionReasonCode,
1648        confidence: f64,
1649        event_rate: f64,
1650        p_burst: Option<f64>,
1651    ) {
1652        let from_regime = self.regime;
1653        if from_regime == to_regime {
1654            return;
1655        }
1656        self.regime = to_regime;
1657        self.regime_transitions += 1;
1658        self.pending_transition_evidence = Some(PendingTransitionEvidence {
1659            reason_code,
1660            confidence,
1661        });
1662        self.push_transition_log(RegimeTransitionLog {
1663            timestamp: now,
1664            event_idx: self.event_count,
1665            from_regime,
1666            to_regime,
1667            reason_code,
1668            confidence,
1669            event_rate,
1670            p_burst,
1671            cooldown_remaining: self.cooldown_remaining,
1672            detector: self.last_detector,
1673        });
1674        if let Some(ref hooks) = self.telemetry_hooks {
1675            hooks.fire_regime_change(from_regime, to_regime);
1676        }
1677
1678        if let Some(ref sink) = self.evidence_sink {
1679            let (cols, rows) = self.last_applied;
1680            let run_id = self.evidence_run_id.as_str();
1681            let screen_mode = self.evidence_screen_mode;
1682            if !self.config_logged {
1683                let _ = sink.write_jsonl(&self.config.to_jsonl(run_id, screen_mode, cols, rows, 0));
1684                self.config_logged = true;
1685            }
1686            if let Some(entry) = self.transition_logs.last() {
1687                let _ = sink.write_jsonl(&entry.to_jsonl(run_id, screen_mode, cols, rows));
1688            }
1689        }
1690    }
1691
1692    fn calculate_event_rate(&self, now: Instant) -> f64 {
1693        if self.event_times.len() < 2 {
1694            return 0.0;
1695        }
1696
1697        let first = *self
1698            .event_times
1699            .front()
1700            .expect("event_times has >=2 elements per length guard");
1701        let window_duration = match now.checked_duration_since(first) {
1702            Some(duration) => duration,
1703            None => return 0.0,
1704        };
1705
1706        // Enforce a minimum duration of 1ms to prevent divide-by-zero or instability
1707        // and to correctly reflect high rates for near-instantaneous bursts.
1708        let duration_secs = window_duration.as_secs_f64().max(0.001);
1709
1710        // Number of intervals is len - 1
1711        ((self.event_times.len() - 1) as f64) / duration_secs
1712    }
1713
1714    fn log_decision(
1715        &mut self,
1716        now: Instant,
1717        action: &'static str,
1718        forced: bool,
1719        dt_ms_override: Option<f64>,
1720        coalesce_ms: Option<f64>,
1721    ) {
1722        if !self.config.enable_logging {
1723            return;
1724        }
1725
1726        if self.log_start.is_none() {
1727            self.log_start = Some(now);
1728        }
1729
1730        let elapsed_ms = self
1731            .log_start
1732            .map(|t| duration_since_or_zero(now, t).as_secs_f64() * 1000.0)
1733            .unwrap_or(0.0);
1734
1735        let dt_ms = dt_ms_override
1736            .or_else(|| {
1737                self.last_event
1738                    .map(|t| duration_since_or_zero(now, t).as_secs_f64() * 1000.0)
1739            })
1740            .unwrap_or(0.0);
1741
1742        let time_since_render_ms =
1743            duration_since_or_zero(now, self.last_render).as_secs_f64() * 1000.0;
1744
1745        let applied_size =
1746            if action == "apply" || action == "apply_forced" || action == "apply_immediate" {
1747                Some(self.last_applied)
1748            } else {
1749                None
1750            };
1751        let (transition_reason_code, transition_confidence) =
1752            match self.pending_transition_evidence.take() {
1753                Some(ev) => (Some(ev.reason_code), Some(ev.confidence)),
1754                None => (None, None),
1755            };
1756
1757        self.logs.push(DecisionLog {
1758            timestamp: now,
1759            elapsed_ms,
1760            event_idx: self.event_count,
1761            dt_ms,
1762            event_rate: self.calculate_event_rate(now),
1763            regime: self.regime,
1764            action,
1765            pending_size: self.pending_size,
1766            applied_size,
1767            time_since_render_ms,
1768            coalesce_ms,
1769            forced,
1770            transition_reason_code,
1771            transition_confidence,
1772            detector: self.last_detector,
1773            p_burst: self.bocpd_p_burst().filter(|p| p.is_finite()),
1774        });
1775
1776        if let Some(ref sink) = self.evidence_sink {
1777            let (cols, rows) = self.last_applied;
1778            let run_id = self.evidence_run_id.as_str();
1779            let screen_mode = self.evidence_screen_mode;
1780            if !self.config_logged {
1781                let _ = sink.write_jsonl(&self.config.to_jsonl(run_id, screen_mode, cols, rows, 0));
1782                self.config_logged = true;
1783            }
1784            if let Some(entry) = self.logs.last() {
1785                let _ = sink.write_jsonl(&entry.to_jsonl(run_id, screen_mode, cols, rows));
1786            }
1787            if let Some(ref bocpd) = self.bocpd
1788                && let Some(jsonl) = bocpd.decision_log_jsonl(
1789                    self.config.steady_delay_ms,
1790                    self.config.burst_delay_ms,
1791                    forced,
1792                )
1793            {
1794                let _ = sink.write_jsonl(&jsonl);
1795            }
1796        }
1797    }
1798}
1799
1800/// Statistics about the coalescer state.
1801#[derive(Debug, Clone)]
1802pub struct CoalescerStats {
1803    /// Total events processed.
1804    pub event_count: u64,
1805    /// Current regime.
1806    pub regime: Regime,
1807    /// Current event rate (events/sec).
1808    pub event_rate: f64,
1809    /// Whether there's a pending resize.
1810    pub has_pending: bool,
1811    /// Last applied size.
1812    pub last_applied: (u16, u16),
1813    /// Detector that made the most recent regime decision.
1814    pub detector: RegimeDetector,
1815    /// Regime decisions per detector.
1816    pub detector_decisions: DetectorDecisions,
1817}
1818
1819/// Summary of decision logs.
1820#[derive(Debug, Clone, Default)]
1821pub struct DecisionSummary {
1822    /// Total number of decisions logged.
1823    pub decision_count: usize,
1824    /// Total apply decisions.
1825    pub apply_count: usize,
1826    /// Applies forced by deadline.
1827    pub forced_apply_count: usize,
1828    /// Total coalesce decisions.
1829    pub coalesce_count: usize,
1830    /// Total skip decisions.
1831    pub skip_count: usize,
1832    /// Final regime at summary time.
1833    pub regime: Regime,
1834    /// Last applied size.
1835    pub last_applied: (u16, u16),
1836    /// Checksum for the decision log.
1837    pub checksum: u64,
1838}
1839
1840impl DecisionSummary {
1841    /// Checksum as hex string.
1842    #[must_use]
1843    pub fn checksum_hex(&self) -> String {
1844        format!("{:016x}", self.checksum)
1845    }
1846
1847    /// Serialize summary to JSONL format.
1848    #[must_use]
1849    pub fn to_jsonl(
1850        &self,
1851        run_id: &str,
1852        screen_mode: ScreenMode,
1853        cols: u16,
1854        rows: u16,
1855        event_idx: u64,
1856    ) -> String {
1857        let prefix = evidence_prefix(run_id, screen_mode, cols, rows, event_idx);
1858        format!(
1859            r#"{{{prefix},"event":"summary","decisions":{},"applies":{},"forced_applies":{},"coalesces":{},"skips":{},"regime":"{}","last_w":{},"last_h":{},"checksum":"{}"}}"#,
1860            self.decision_count,
1861            self.apply_count,
1862            self.forced_apply_count,
1863            self.coalesce_count,
1864            self.skip_count,
1865            self.regime.as_str(),
1866            self.last_applied.0,
1867            self.last_applied.1,
1868            self.checksum_hex()
1869        )
1870    }
1871}
1872
1873// =============================================================================
1874// Telemetry Hooks (bd-1rz0.7)
1875// =============================================================================
1876
1877/// Callback type for resize applied events.
1878pub type OnResizeApplied = Box<dyn Fn(&DecisionLog) + Send + Sync>;
1879/// Callback type for regime change events.
1880pub type OnRegimeChange = Box<dyn Fn(Regime, Regime) + Send + Sync>;
1881/// Callback type for coalesce decision events.
1882pub type OnCoalesceDecision = Box<dyn Fn(&DecisionLog) + Send + Sync>;
1883
1884/// Telemetry hooks for observing resize coalescer events.
1885///
1886/// # Example
1887///
1888/// ```ignore
1889/// use ftui_runtime::resize_coalescer::{ResizeCoalescer, TelemetryHooks, CoalescerConfig};
1890///
1891/// let hooks = TelemetryHooks::new()
1892///     .on_resize_applied(|entry| println!("Applied: {}x{}", entry.applied_size.unwrap().0, entry.applied_size.unwrap().1))
1893///     .on_regime_change(|from, to| println!("Regime: {:?} -> {:?}", from, to));
1894///
1895/// let mut coalescer = ResizeCoalescer::new(CoalescerConfig::default(), (80, 24))
1896///     .with_telemetry_hooks(hooks);
1897/// ```
1898pub struct TelemetryHooks {
1899    /// Called when a resize is applied.
1900    on_resize_applied: Option<OnResizeApplied>,
1901    /// Called when regime changes (Steady <-> Burst).
1902    on_regime_change: Option<OnRegimeChange>,
1903    /// Called for every decision (coalesce, apply, skip).
1904    on_decision: Option<OnCoalesceDecision>,
1905    /// Enable tracing events (requires `tracing` feature).
1906    emit_tracing: bool,
1907}
1908
1909impl Default for TelemetryHooks {
1910    fn default() -> Self {
1911        Self::new()
1912    }
1913}
1914
1915impl std::fmt::Debug for TelemetryHooks {
1916    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1917        f.debug_struct("TelemetryHooks")
1918            .field("on_resize_applied", &self.on_resize_applied.is_some())
1919            .field("on_regime_change", &self.on_regime_change.is_some())
1920            .field("on_decision", &self.on_decision.is_some())
1921            .field("emit_tracing", &self.emit_tracing)
1922            .finish()
1923    }
1924}
1925
1926impl TelemetryHooks {
1927    /// Create a new empty hooks instance.
1928    #[must_use]
1929    pub fn new() -> Self {
1930        Self {
1931            on_resize_applied: None,
1932            on_regime_change: None,
1933            on_decision: None,
1934            emit_tracing: false,
1935        }
1936    }
1937
1938    /// Set callback for resize applied events.
1939    #[must_use]
1940    pub fn on_resize_applied<F>(mut self, callback: F) -> Self
1941    where
1942        F: Fn(&DecisionLog) + Send + Sync + 'static,
1943    {
1944        self.on_resize_applied = Some(Box::new(callback));
1945        self
1946    }
1947
1948    /// Set callback for regime change events.
1949    #[must_use]
1950    pub fn on_regime_change<F>(mut self, callback: F) -> Self
1951    where
1952        F: Fn(Regime, Regime) + Send + Sync + 'static,
1953    {
1954        self.on_regime_change = Some(Box::new(callback));
1955        self
1956    }
1957
1958    /// Set callback for all decision events.
1959    #[must_use]
1960    pub fn on_decision<F>(mut self, callback: F) -> Self
1961    where
1962        F: Fn(&DecisionLog) + Send + Sync + 'static,
1963    {
1964        self.on_decision = Some(Box::new(callback));
1965        self
1966    }
1967
1968    /// Enable tracing event emission for OpenTelemetry integration.
1969    ///
1970    /// When enabled, decision events are emitted as `tracing::event!` calls
1971    /// with target `ftui.decision.resize` and all evidence ledger fields.
1972    #[must_use]
1973    pub fn with_tracing(mut self, enabled: bool) -> Self {
1974        self.emit_tracing = enabled;
1975        self
1976    }
1977
1978    /// Check if a resize-applied hook is registered.
1979    pub fn has_resize_applied(&self) -> bool {
1980        self.on_resize_applied.is_some()
1981    }
1982
1983    /// Check if a regime-change hook is registered.
1984    pub fn has_regime_change(&self) -> bool {
1985        self.on_regime_change.is_some()
1986    }
1987
1988    /// Check if a decision hook is registered.
1989    pub fn has_decision(&self) -> bool {
1990        self.on_decision.is_some()
1991    }
1992
1993    /// Invoke the resize applied callback if set.
1994    fn fire_resize_applied(&self, entry: &DecisionLog) {
1995        if let Some(ref cb) = self.on_resize_applied {
1996            cb(entry);
1997        }
1998        if self.emit_tracing {
1999            Self::emit_resize_tracing(entry);
2000        }
2001    }
2002
2003    /// Invoke the regime change callback if set.
2004    fn fire_regime_change(&self, from: Regime, to: Regime) {
2005        if let Some(ref cb) = self.on_regime_change {
2006            cb(from, to);
2007        }
2008        if self.emit_tracing {
2009            tracing::debug!(
2010                target: crate::telemetry_schema::TARGET_RESIZE,
2011                from_regime = %from.as_str(),
2012                to_regime = %to.as_str(),
2013                "regime_change"
2014            );
2015        }
2016    }
2017
2018    /// Invoke the decision callback if set.
2019    fn fire_decision(&self, entry: &DecisionLog) {
2020        if let Some(ref cb) = self.on_decision {
2021            cb(entry);
2022        }
2023    }
2024
2025    /// Emit a tracing event for resize decisions.
2026    fn emit_resize_tracing(entry: &DecisionLog) {
2027        let (pending_w, pending_h) = entry.pending_size.unwrap_or((0, 0));
2028        let (applied_w, applied_h) = entry.applied_size.unwrap_or((0, 0));
2029        let coalesce_ms = entry.coalesce_ms.unwrap_or(0.0);
2030
2031        tracing::info!(
2032            target: crate::telemetry_schema::TARGET_RESIZE,
2033            event_idx = entry.event_idx,
2034            elapsed_ms = entry.elapsed_ms,
2035            dt_ms = entry.dt_ms,
2036            event_rate = entry.event_rate,
2037            regime = %entry.regime.as_str(),
2038            action = entry.action,
2039            pending_w = pending_w,
2040            pending_h = pending_h,
2041            applied_w = applied_w,
2042            applied_h = applied_h,
2043            time_since_render_ms = entry.time_since_render_ms,
2044            coalesce_ms = coalesce_ms,
2045            forced = entry.forced,
2046            "resize_decision"
2047        );
2048    }
2049}
2050
2051#[cfg(test)]
2052mod tests {
2053    use super::*;
2054
2055    #[test]
2056    fn retained_diagnostics_are_bounded() {
2057        let mut c = ResizeCoalescer::new(test_config(), (80, 24));
2058        for i in 0..(MAX_CYCLE_TIME_SAMPLES + 500) {
2059            c.record_cycle_time(i as f64);
2060        }
2061        assert_eq!(c.cycle_times.len(), MAX_CYCLE_TIME_SAMPLES);
2062        // The retained window is the most recent samples.
2063        assert_eq!(c.cycle_times[0], 500.0);
2064        // Percentiles still work over the bounded window.
2065        assert!(c.cycle_time_percentiles().is_some());
2066
2067        let now = Instant::now();
2068        for i in 0..(MAX_TRANSITION_LOGS + 100) {
2069            c.push_transition_log(RegimeTransitionLog {
2070                timestamp: now,
2071                event_idx: i as u64,
2072                from_regime: Regime::Steady,
2073                to_regime: Regime::Burst,
2074                reason_code: TransitionReasonCode::HeuristicEnterBurstRate,
2075                confidence: 1.0,
2076                event_rate: 0.0,
2077                p_burst: None,
2078                cooldown_remaining: 0,
2079                detector: RegimeDetector::Heuristic,
2080            });
2081        }
2082        assert_eq!(c.transition_logs.len(), MAX_TRANSITION_LOGS);
2083        assert_eq!(c.transition_logs[0].event_idx, 100);
2084    }
2085
2086    fn test_config() -> CoalescerConfig {
2087        CoalescerConfig {
2088            steady_delay_ms: 16,
2089            burst_delay_ms: 40,
2090            hard_deadline_ms: 100,
2091            burst_enter_rate: 10.0,
2092            burst_exit_rate: 5.0,
2093            cooldown_frames: 3,
2094            rate_window_size: 8,
2095            enable_logging: true,
2096            enable_bocpd: false,
2097            heuristic_fallback: true,
2098            bocpd_config: None,
2099        }
2100    }
2101
2102    #[derive(Debug, Clone, Copy)]
2103    struct SimulationMetrics {
2104        event_count: u64,
2105        apply_count: u64,
2106        forced_count: u64,
2107        mean_coalesce_ms: f64,
2108        max_coalesce_ms: f64,
2109        decision_checksum: u64,
2110        final_regime: Regime,
2111    }
2112
2113    impl SimulationMetrics {
2114        fn to_jsonl(self, pattern: &str, mode: &str) -> String {
2115            let pattern = json_escape(pattern);
2116            let mode = json_escape(mode);
2117            let apply_ratio = if self.event_count == 0 {
2118                0.0
2119            } else {
2120                self.apply_count as f64 / self.event_count as f64
2121            };
2122
2123            format!(
2124                r#"{{"event":"simulation_summary","pattern":"{pattern}","mode":"{mode}","events":{},"applies":{},"forced":{},"apply_ratio":{:.4},"mean_coalesce_ms":{:.3},"max_coalesce_ms":{:.3},"final_regime":"{}","checksum":"{:016x}"}}"#,
2125                self.event_count,
2126                self.apply_count,
2127                self.forced_count,
2128                apply_ratio,
2129                self.mean_coalesce_ms,
2130                self.max_coalesce_ms,
2131                self.final_regime.as_str(),
2132                self.decision_checksum
2133            )
2134        }
2135    }
2136
2137    #[derive(Debug, Clone, Copy)]
2138    struct SimulationComparison {
2139        apply_delta: i64,
2140        mean_coalesce_delta_ms: f64,
2141    }
2142
2143    impl SimulationComparison {
2144        fn from_metrics(heuristic: SimulationMetrics, bocpd: SimulationMetrics) -> Self {
2145            let heuristic_apply = i64::try_from(heuristic.apply_count).unwrap_or(i64::MAX);
2146            let bocpd_apply = i64::try_from(bocpd.apply_count).unwrap_or(i64::MAX);
2147            let apply_delta = heuristic_apply.saturating_sub(bocpd_apply);
2148            let mean_coalesce_delta_ms = heuristic.mean_coalesce_ms - bocpd.mean_coalesce_ms;
2149            Self {
2150                apply_delta,
2151                mean_coalesce_delta_ms,
2152            }
2153        }
2154
2155        fn to_jsonl(self, pattern: &str) -> String {
2156            let pattern = json_escape(pattern);
2157            format!(
2158                r#"{{"event":"simulation_compare","pattern":"{pattern}","apply_delta":{},"mean_coalesce_delta_ms":{:.3}}}"#,
2159                self.apply_delta, self.mean_coalesce_delta_ms
2160            )
2161        }
2162    }
2163
2164    fn as_u64(value: usize) -> u64 {
2165        u64::try_from(value).unwrap_or(u64::MAX)
2166    }
2167
2168    fn build_schedule(base: Instant, events: &[(u16, u16, u64)]) -> Vec<(Instant, u16, u16)> {
2169        let mut schedule = Vec::with_capacity(events.len());
2170        let mut elapsed_ms = 0u64;
2171        for (w, h, delay_ms) in events {
2172            elapsed_ms = elapsed_ms.saturating_add(*delay_ms);
2173            schedule.push((base + Duration::from_millis(elapsed_ms), *w, *h));
2174        }
2175        schedule
2176    }
2177
2178    fn run_simulation(
2179        events: &[(u16, u16, u64)],
2180        config: CoalescerConfig,
2181        tick_ms: u64,
2182    ) -> SimulationMetrics {
2183        let mut c = ResizeCoalescer::new(config, (80, 24));
2184        let base = Instant::now();
2185        let schedule = build_schedule(base, events);
2186        let last_event_ms = schedule
2187            .last()
2188            .map(|(time, _, _)| {
2189                u64::try_from(duration_since_or_zero(*time, base).as_millis()).unwrap_or(u64::MAX)
2190            })
2191            .unwrap_or(0);
2192        let end_ms = last_event_ms
2193            .saturating_add(c.config.hard_deadline_ms)
2194            .saturating_add(tick_ms);
2195
2196        let mut next_idx = 0usize;
2197        let mut now_ms = 0u64;
2198        while now_ms <= end_ms {
2199            let now = base + Duration::from_millis(now_ms);
2200
2201            while next_idx < schedule.len() && schedule[next_idx].0 <= now {
2202                let (event_time, w, h) = schedule[next_idx];
2203                let _ = c.handle_resize_at(w, h, event_time);
2204                next_idx += 1;
2205            }
2206
2207            let _ = c.tick_at(now);
2208            now_ms = now_ms.saturating_add(tick_ms);
2209        }
2210
2211        let mut coalesce_values = Vec::new();
2212        let mut apply_count = 0usize;
2213        let mut forced_count = 0usize;
2214        for entry in c.logs() {
2215            if matches!(entry.action, "apply" | "apply_forced" | "apply_immediate") {
2216                apply_count += 1;
2217                if entry.forced {
2218                    forced_count += 1;
2219                }
2220                if let Some(ms) = entry.coalesce_ms {
2221                    coalesce_values.push(ms);
2222                }
2223            }
2224        }
2225
2226        let max_coalesce_ms = coalesce_values
2227            .iter()
2228            .copied()
2229            .fold(0.0_f64, |acc, value| acc.max(value));
2230        let mean_coalesce_ms = if coalesce_values.is_empty() {
2231            0.0
2232        } else {
2233            let sum = coalesce_values.iter().sum::<f64>();
2234            sum / as_u64(coalesce_values.len()) as f64
2235        };
2236
2237        SimulationMetrics {
2238            event_count: as_u64(events.len()),
2239            apply_count: as_u64(apply_count),
2240            forced_count: as_u64(forced_count),
2241            mean_coalesce_ms,
2242            max_coalesce_ms,
2243            decision_checksum: c.decision_checksum(),
2244            final_regime: c.regime(),
2245        }
2246    }
2247
2248    fn steady_pattern() -> Vec<(u16, u16, u64)> {
2249        let mut events = Vec::new();
2250        for i in 0..8u16 {
2251            let width = 90 + i;
2252            let height = 30 + (i % 3);
2253            events.push((width, height, 300));
2254        }
2255        events
2256    }
2257
2258    fn burst_pattern() -> Vec<(u16, u16, u64)> {
2259        let mut events = Vec::new();
2260        for i in 0..30u16 {
2261            let width = 100 + i;
2262            let height = 25 + (i % 5);
2263            events.push((width, height, 10));
2264        }
2265        events
2266    }
2267
2268    fn oscillatory_pattern() -> Vec<(u16, u16, u64)> {
2269        let mut events = Vec::new();
2270        let sizes = [(120, 40), (140, 28), (130, 36), (150, 32)];
2271        let delays = [40u64, 200u64, 60u64, 180u64];
2272        for i in 0..16usize {
2273            let (w, h) = sizes[i % sizes.len()];
2274            let delay = delays[i % delays.len()];
2275            events.push((w + (i as u16 % 3), h, delay));
2276        }
2277        events
2278    }
2279
2280    #[test]
2281    fn new_coalescer_starts_in_steady() {
2282        let c = ResizeCoalescer::new(CoalescerConfig::default(), (80, 24));
2283        assert_eq!(c.regime(), Regime::Steady);
2284        assert!(!c.has_pending());
2285    }
2286
2287    #[test]
2288    fn same_size_returns_none() {
2289        let mut c = ResizeCoalescer::new(test_config(), (80, 24));
2290        let action = c.handle_resize(80, 24);
2291        assert_eq!(action, CoalesceAction::None);
2292    }
2293
2294    #[test]
2295    fn different_size_coalesces_with_no_action_and_a_pending_size() {
2296        let mut c = ResizeCoalescer::new(test_config(), (80, 24));
2297        let action = c.handle_resize(100, 40);
2298        assert_eq!(action, CoalesceAction::None);
2299        assert!(c.has_pending(), "the size is held until the delay elapses");
2300    }
2301
2302    #[test]
2303    fn latest_wins_semantics() {
2304        let config = test_config();
2305        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2306
2307        let base = Instant::now();
2308
2309        // Rapid sequence of resizes
2310        c.handle_resize_at(90, 30, base);
2311        c.handle_resize_at(100, 40, base + Duration::from_millis(5));
2312        c.handle_resize_at(110, 50, base + Duration::from_millis(10));
2313
2314        // Wait for coalesce delay
2315        let action = c.tick_at(base + Duration::from_millis(60));
2316
2317        let (width, height) = if let CoalesceAction::ApplyResize { width, height, .. } = action {
2318            (width, height)
2319        } else {
2320            assert!(
2321                matches!(action, CoalesceAction::ApplyResize { .. }),
2322                "Expected ApplyResize, got {action:?}"
2323            );
2324            return;
2325        };
2326        assert_eq!((width, height), (110, 50), "Should apply latest size");
2327    }
2328
2329    #[test]
2330    fn hard_deadline_forces_apply() {
2331        let config = test_config();
2332        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2333
2334        let base = Instant::now();
2335
2336        // First resize
2337        c.handle_resize_at(100, 40, base);
2338
2339        // Wait past hard deadline
2340        let action = c.tick_at(base + Duration::from_millis(150));
2341
2342        let forced_by_deadline = if let CoalesceAction::ApplyResize {
2343            forced_by_deadline, ..
2344        } = action
2345        {
2346            forced_by_deadline
2347        } else {
2348            assert!(
2349                matches!(action, CoalesceAction::ApplyResize { .. }),
2350                "Expected ApplyResize, got {action:?}"
2351            );
2352            return;
2353        };
2354        assert!(forced_by_deadline, "Should be forced by deadline");
2355    }
2356
2357    /// CONTRACT (bd-1za0z): an isolated resize arriving after a quiet gap is
2358    /// applied instantly but NOT flagged forced — nothing was waiting on the
2359    /// deadline, so it is not an SLA breach.
2360    #[test]
2361    fn isolated_resize_after_quiet_gap_is_not_forced() {
2362        let config = test_config();
2363        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2364
2365        let base = Instant::now();
2366        let action = c.handle_resize_at(120, 40, base + Duration::from_millis(500));
2367
2368        match action {
2369            CoalesceAction::ApplyResize {
2370                forced_by_deadline, ..
2371            } => {
2372                assert!(
2373                    !forced_by_deadline,
2374                    "quiet-gap instant apply must not count as forced"
2375                );
2376            }
2377            other => panic!("Expected ApplyResize, got {other:?}"),
2378        }
2379    }
2380
2381    /// CONTRACT (bd-1za0z): when a resize arrives while an earlier resize is
2382    /// STILL pending past the hard deadline, that IS an SLA breach — forced
2383    /// stays true on the event path too.
2384    #[test]
2385    fn resize_arriving_while_pending_past_deadline_stays_forced() {
2386        let config = test_config();
2387        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2388
2389        let base = Instant::now();
2390        // First event coalesces (no dt yet), leaving work waiting.
2391        c.handle_resize_at(90, 30, base);
2392
2393        // Second event arrives after the hard deadline elapsed with the
2394        // first still unapplied.
2395        let action = c.handle_resize_at(120, 40, base + Duration::from_millis(500));
2396
2397        match action {
2398            CoalesceAction::ApplyResize {
2399                forced_by_deadline, ..
2400            } => {
2401                assert!(
2402                    forced_by_deadline,
2403                    "deadline breach of WAITING work must stay forced"
2404                );
2405            }
2406            other => panic!("Expected ApplyResize, got {other:?}"),
2407        }
2408    }
2409
2410    #[test]
2411    fn burst_mode_detection() {
2412        let config = test_config();
2413        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2414
2415        let base = Instant::now();
2416
2417        // Rapid events to trigger burst mode
2418        for i in 0..15 {
2419            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 10));
2420        }
2421
2422        assert_eq!(c.regime(), Regime::Burst);
2423    }
2424
2425    #[test]
2426    fn steady_mode_fast_response() {
2427        let config = test_config();
2428        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2429
2430        let base = Instant::now();
2431
2432        // Single resize
2433        c.handle_resize_at(100, 40, base);
2434
2435        // In steady mode, should apply after steady_delay
2436        let action = c.tick_at(base + Duration::from_millis(20));
2437
2438        assert!(matches!(action, CoalesceAction::ApplyResize { .. }));
2439    }
2440
2441    #[test]
2442    fn record_external_apply_updates_state_and_logs() {
2443        let config = test_config();
2444        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2445
2446        let base = Instant::now();
2447        c.handle_resize_at(100, 40, base);
2448        c.record_external_apply(120, 50, base + Duration::from_millis(5));
2449
2450        assert!(!c.has_pending());
2451        assert_eq!(c.last_applied(), (120, 50));
2452
2453        let summary = c.decision_summary();
2454        assert_eq!(summary.apply_count, 1);
2455        assert_eq!(summary.last_applied, (120, 50));
2456        assert!(
2457            c.logs()
2458                .iter()
2459                .any(|entry| entry.action == "apply_immediate"),
2460            "record_external_apply should emit apply_immediate decision"
2461        );
2462    }
2463
2464    #[test]
2465    fn coalesce_time_tracked() {
2466        let config = test_config();
2467        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2468
2469        let base = Instant::now();
2470
2471        c.handle_resize_at(100, 40, base);
2472        let action = c.tick_at(base + Duration::from_millis(50));
2473
2474        let coalesce_time = if let CoalesceAction::ApplyResize { coalesce_time, .. } = action {
2475            coalesce_time
2476        } else {
2477            assert!(
2478                matches!(action, CoalesceAction::ApplyResize { .. }),
2479                "Expected ApplyResize"
2480            );
2481            return;
2482        };
2483        assert!(coalesce_time >= Duration::from_millis(40));
2484        assert!(coalesce_time <= Duration::from_millis(60));
2485    }
2486
2487    #[test]
2488    fn event_rate_calculation() {
2489        let config = test_config();
2490        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2491
2492        let base = Instant::now();
2493
2494        // 10 events over 1 second = 10 events/sec
2495        for i in 0..10 {
2496            c.handle_resize_at(80 + i, 24, base + Duration::from_millis(i as u64 * 100));
2497        }
2498
2499        let rate = c.calculate_event_rate(base + Duration::from_millis(1000));
2500        assert!(rate > 8.0 && rate < 12.0, "Rate should be ~10 events/sec");
2501    }
2502
2503    #[test]
2504    fn rapid_burst_triggers_high_rate() {
2505        let config = test_config();
2506        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2507        let base = Instant::now();
2508
2509        // Simulate 8 events arriving at the EXACT same time (or < 1ms)
2510        for _ in 0..8 {
2511            c.handle_resize_at(80, 24, base);
2512        }
2513
2514        let rate = c.calculate_event_rate(base);
2515        // 8 events / 0.001s = 8000 events/sec
2516        assert!(
2517            rate >= 1000.0,
2518            "Rate should be high for instantaneous burst, got {}",
2519            rate
2520        );
2521    }
2522
2523    #[test]
2524    fn cooldown_prevents_immediate_exit() {
2525        let config = test_config();
2526        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2527
2528        let base = Instant::now();
2529
2530        // Enter burst mode
2531        for i in 0..15 {
2532            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 10));
2533        }
2534        assert_eq!(c.regime(), Regime::Burst);
2535
2536        // Rate should drop but cooldown prevents immediate exit
2537        c.tick_at(base + Duration::from_millis(500));
2538        c.tick_at(base + Duration::from_millis(600));
2539
2540        // Cooldown holds while the rate window still reports the storm.
2541        assert_eq!(c.regime(), Regime::Burst);
2542
2543        // The event-rate window clears after a >1s quiet gap; the cooldown
2544        // then decrements per tick and Burst exits.
2545        for i in 0..6 {
2546            c.tick_at(base + Duration::from_millis(1300 + 100 * i));
2547        }
2548
2549        // Should have exited burst (this pins the cooldown exit path —
2550        // with cooldown_frames armed to at least 1, Burst always has an
2551        // exit once the rate decays).
2552        assert_eq!(c.stats().regime, Regime::Steady);
2553    }
2554
2555    #[test]
2556    fn cooldown_frames_zero_cannot_dead_end_burst() {
2557        // Regression: cooldown_frames = 0 armed cooldown_remaining = 0 on
2558        // Burst entry; the only Burst->Steady exit required
2559        // cooldown_remaining > 0, so the regime pinned at Burst forever and
2560        // the load governor latched Stressed for the session. Arming now
2561        // clamps to >= 1 frame.
2562        let mut c = ResizeCoalescer::new(
2563            CoalescerConfig {
2564                cooldown_frames: 0,
2565                ..Default::default()
2566            },
2567            (80, 24),
2568        );
2569        let base = Instant::now();
2570        // Storm: enter Burst.
2571        for i in 0..10 {
2572            let _ =
2573                c.handle_resize_at(100 + i, 40, base + Duration::from_millis(10 * u64::from(i)));
2574        }
2575        assert_eq!(c.stats().regime, Regime::Burst);
2576        // Storm over: quiet ticks must eventually exit Burst.
2577        for i in 1..=20 {
2578            c.tick_at(base + Duration::from_millis(100 + 200 * i));
2579        }
2580        assert_eq!(
2581            c.stats().regime,
2582            Regime::Steady,
2583            "Burst must always have an exit path"
2584        );
2585    }
2586
2587    #[test]
2588    fn logging_captures_decisions() {
2589        let mut config = test_config();
2590        config.enable_logging = true;
2591        let mut c = ResizeCoalescer::new(config, (80, 24));
2592
2593        let base = Instant::now();
2594        c.handle_resize_at(100, 40, base);
2595        c.tick_at(base + Duration::from_millis(50));
2596
2597        assert!(!c.logs().is_empty());
2598        assert_eq!(c.logs()[0].action, "coalesce");
2599    }
2600
2601    #[test]
2602    fn logging_jsonl_format() {
2603        let mut config = test_config();
2604        config.enable_logging = true;
2605        let mut c = ResizeCoalescer::new(config, (80, 24));
2606
2607        c.handle_resize_at(100, 40, Instant::now());
2608        c.tick_at(Instant::now() + Duration::from_millis(50));
2609
2610        let (cols, rows) = c.last_applied();
2611        let jsonl = c.logs()[0].to_jsonl("resize-test", ScreenMode::AltScreen, cols, rows);
2612
2613        assert!(jsonl.contains("\"event\":\"decision\""));
2614        assert!(jsonl.contains("\"action\":\"coalesce\""));
2615        assert!(jsonl.contains("\"regime\":\"steady\""));
2616        assert!(jsonl.contains("\"pending_w\":100"));
2617        assert!(jsonl.contains("\"pending_h\":40"));
2618    }
2619
2620    #[test]
2621    fn apply_logs_coalesce_ms() {
2622        let mut config = test_config();
2623        config.enable_logging = true;
2624        let mut c = ResizeCoalescer::new(config, (80, 24));
2625
2626        let base = Instant::now();
2627        c.handle_resize_at(100, 40, base);
2628        let action = c.tick_at(base + Duration::from_millis(50));
2629        assert!(matches!(action, CoalesceAction::ApplyResize { .. }));
2630
2631        let last = c.logs().last().expect("Expected a decision log entry");
2632        assert!(last.coalesce_ms.is_some());
2633        assert!(last.coalesce_ms.unwrap() >= 0.0);
2634    }
2635
2636    #[test]
2637    fn decision_checksum_is_stable() {
2638        let mut config = test_config();
2639        config.enable_logging = true;
2640
2641        let base = Instant::now();
2642        let mut c1 = ResizeCoalescer::new(config.clone(), (80, 24)).with_last_render(base);
2643        let mut c2 = ResizeCoalescer::new(config, (80, 24)).with_last_render(base);
2644
2645        for c in [&mut c1, &mut c2] {
2646            c.handle_resize_at(90, 30, base);
2647            c.handle_resize_at(100, 40, base + Duration::from_millis(10));
2648            let _ = c.tick_at(base + Duration::from_millis(80));
2649        }
2650
2651        assert_eq!(c1.decision_checksum(), c2.decision_checksum());
2652    }
2653
2654    #[test]
2655    fn evidence_jsonl_includes_summary() {
2656        let mut config = test_config();
2657        config.enable_logging = true;
2658        let mut c = ResizeCoalescer::new(config, (80, 24));
2659
2660        c.handle_resize_at(100, 40, Instant::now());
2661        c.tick_at(Instant::now() + Duration::from_millis(50));
2662
2663        let jsonl = c.evidence_to_jsonl();
2664
2665        assert!(jsonl.contains("\"event\":\"config\""));
2666        assert!(jsonl.contains("\"event\":\"summary\""));
2667    }
2668
2669    #[test]
2670    fn evidence_jsonl_parses_and_has_required_fields() {
2671        use serde_json::Value;
2672
2673        let mut config = test_config();
2674        config.enable_logging = true;
2675        let base = Instant::now();
2676        let mut c = ResizeCoalescer::new(config, (80, 24))
2677            .with_last_render(base)
2678            .with_evidence_run_id("resize-test")
2679            .with_screen_mode(ScreenMode::AltScreen);
2680
2681        c.handle_resize_at(90, 30, base);
2682        c.handle_resize_at(100, 40, base + Duration::from_millis(10));
2683        let _ = c.tick_at(base + Duration::from_millis(120));
2684
2685        let jsonl = c.evidence_to_jsonl();
2686        let mut saw_config = false;
2687        let mut saw_decision = false;
2688        let mut saw_summary = false;
2689
2690        for line in jsonl.lines() {
2691            let value: Value = serde_json::from_str(line).expect("valid JSONL evidence");
2692            let event = value
2693                .get("event")
2694                .and_then(Value::as_str)
2695                .expect("event field");
2696            assert_eq!(value["schema_version"], EVIDENCE_SCHEMA_VERSION);
2697            assert_eq!(value["run_id"], "resize-test");
2698            assert!(
2699                value["event_idx"].is_number(),
2700                "event_idx should be numeric"
2701            );
2702            assert_eq!(value["screen_mode"], "altscreen");
2703            assert!(value["cols"].is_number(), "cols should be numeric");
2704            assert!(value["rows"].is_number(), "rows should be numeric");
2705            match event {
2706                "config" => {
2707                    for key in [
2708                        "steady_delay_ms",
2709                        "burst_delay_ms",
2710                        "hard_deadline_ms",
2711                        "burst_enter_rate",
2712                        "burst_exit_rate",
2713                        "cooldown_frames",
2714                        "rate_window_size",
2715                        "logging_enabled",
2716                    ] {
2717                        assert!(value.get(key).is_some(), "missing config field {key}");
2718                    }
2719                    saw_config = true;
2720                }
2721                "decision" => {
2722                    for key in [
2723                        "idx",
2724                        "elapsed_ms",
2725                        "dt_ms",
2726                        "event_rate",
2727                        "regime",
2728                        "action",
2729                        "pending_w",
2730                        "pending_h",
2731                        "applied_w",
2732                        "applied_h",
2733                        "time_since_render_ms",
2734                        "coalesce_ms",
2735                        "forced",
2736                        "transition_reason_code",
2737                        "transition_confidence",
2738                    ] {
2739                        assert!(value.get(key).is_some(), "missing decision field {key}");
2740                    }
2741                    saw_decision = true;
2742                }
2743                "summary" => {
2744                    for key in [
2745                        "decisions",
2746                        "applies",
2747                        "forced_applies",
2748                        "coalesces",
2749                        "skips",
2750                        "regime",
2751                        "last_w",
2752                        "last_h",
2753                        "checksum",
2754                    ] {
2755                        assert!(value.get(key).is_some(), "missing summary field {key}");
2756                    }
2757                    saw_summary = true;
2758                }
2759                _ => {}
2760            }
2761        }
2762
2763        assert!(saw_config, "config evidence missing");
2764        assert!(saw_decision, "decision evidence missing");
2765        assert!(saw_summary, "summary evidence missing");
2766    }
2767
2768    #[test]
2769    fn evidence_jsonl_is_deterministic_for_fixed_schedule() {
2770        let mut config = test_config();
2771        config.enable_logging = true;
2772        let base = Instant::now();
2773
2774        let run = || {
2775            let mut c = ResizeCoalescer::new(config.clone(), (80, 24))
2776                .with_last_render(base)
2777                .with_evidence_run_id("resize-test")
2778                .with_screen_mode(ScreenMode::AltScreen);
2779            c.handle_resize_at(90, 30, base);
2780            c.handle_resize_at(100, 40, base + Duration::from_millis(10));
2781            let _ = c.tick_at(base + Duration::from_millis(120));
2782            c.evidence_to_jsonl()
2783        };
2784
2785        let first = run();
2786        let second = run();
2787        assert_eq!(first, second);
2788    }
2789
2790    #[test]
2791    fn bocpd_logging_inherits_coalescer_logging() {
2792        let mut config = test_config();
2793        config.enable_bocpd = true;
2794        config.bocpd_config = Some(BocpdConfig::default());
2795
2796        let c = ResizeCoalescer::new(config, (80, 24));
2797        let bocpd = c.bocpd().expect("BOCPD should be enabled");
2798        assert!(bocpd.config().enable_logging);
2799    }
2800
2801    #[test]
2802    fn stats_reflect_state() {
2803        let mut c = ResizeCoalescer::new(test_config(), (80, 24));
2804        let base = Instant::now();
2805
2806        c.handle_resize_at(100, 40, base);
2807        let action = c.tick_at(base + Duration::from_millis(5));
2808        assert_eq!(action, CoalesceAction::None);
2809
2810        let stats = c.stats();
2811        assert_eq!(stats.event_count, 1);
2812        assert!(stats.has_pending);
2813        assert_eq!(stats.last_applied, (80, 24));
2814
2815        let action = c.tick_at(base + Duration::from_millis(50));
2816        assert_eq!(
2817            action,
2818            CoalesceAction::ApplyResize {
2819                width: 100,
2820                height: 40,
2821                coalesce_time: Duration::from_millis(50),
2822                forced_by_deadline: false,
2823            }
2824        );
2825
2826        let stats = c.stats();
2827        assert!(!stats.has_pending);
2828        assert_eq!(stats.last_applied, (100, 40));
2829    }
2830
2831    #[test]
2832    fn time_until_apply_calculation() {
2833        let config = test_config();
2834        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2835
2836        let base = Instant::now();
2837        c.handle_resize_at(100, 40, base);
2838
2839        let time_left = c.time_until_apply(base + Duration::from_millis(5));
2840        assert!(time_left.is_some());
2841        let time_left = time_left.unwrap();
2842        assert!(time_left.as_millis() > 0);
2843        assert!(time_left.as_millis() < config.steady_delay_ms as u128);
2844    }
2845
2846    #[test]
2847    fn deterministic_behavior() {
2848        let config = test_config();
2849
2850        // Run twice with same inputs
2851        let results: Vec<_> = (0..2)
2852            .map(|_| {
2853                let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
2854                let base = Instant::now();
2855
2856                for i in 0..5 {
2857                    c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 20));
2858                }
2859
2860                c.tick_at(base + Duration::from_millis(200))
2861            })
2862            .collect();
2863
2864        assert_eq!(results[0], results[1], "Results must be deterministic");
2865    }
2866
2867    #[test]
2868    fn transition_reason_codes_and_evidence_fields_are_logged() {
2869        let mut config = test_config();
2870        config.enable_logging = true;
2871        config.hard_deadline_ms = 5_000;
2872        config.burst_delay_ms = 50;
2873        let base = Instant::now();
2874        let mut c = ResizeCoalescer::new(config, (80, 24)).with_last_render(base);
2875
2876        for i in 0..12 {
2877            c.handle_resize_at(90 + i, 30, base + Duration::from_millis(i as u64 * 10));
2878        }
2879
2880        let transition = c
2881            .transition_logs()
2882            .first()
2883            .expect("rapid events should trigger a transition");
2884        assert_eq!(transition.from_regime, Regime::Steady);
2885        assert_eq!(transition.to_regime, Regime::Burst);
2886        assert_eq!(
2887            transition.reason_code,
2888            TransitionReasonCode::HeuristicEnterBurstRate
2889        );
2890        assert!(
2891            (0.0..=1.0).contains(&transition.confidence),
2892            "transition confidence should be normalized"
2893        );
2894        assert!(
2895            transition.event_rate >= 0.0,
2896            "event-rate evidence should be included"
2897        );
2898
2899        let decision_with_transition = c
2900            .logs()
2901            .iter()
2902            .find(|entry| entry.transition_reason_code.is_some())
2903            .expect("transition decisions should include reason code/evidence");
2904        assert_eq!(
2905            decision_with_transition.transition_reason_code,
2906            Some(TransitionReasonCode::HeuristicEnterBurstRate)
2907        );
2908        assert!(decision_with_transition.transition_confidence.is_some());
2909
2910        let jsonl = c.evidence_to_jsonl();
2911        assert!(jsonl.contains("\"event\":\"regime_transition\""));
2912        assert!(jsonl.contains("\"reason_code\":\"heuristic_enter_burst_rate\""));
2913        assert!(jsonl.contains("\"transition_reason_code\":"));
2914    }
2915
2916    #[test]
2917    fn regime_transition_sequence_is_deterministic_for_fixed_schedule() {
2918        let config = CoalescerConfig {
2919            burst_enter_rate: 5.0,
2920            burst_exit_rate: 2.0,
2921            cooldown_frames: 3,
2922            rate_window_size: 4,
2923            steady_delay_ms: 10,
2924            burst_delay_ms: 50,
2925            hard_deadline_ms: 5_000,
2926            enable_logging: true,
2927            enable_bocpd: false,
2928            heuristic_fallback: true,
2929            bocpd_config: None,
2930        };
2931        let base = Instant::now();
2932
2933        let run = || {
2934            let mut c = ResizeCoalescer::new(config.clone(), (80, 24)).with_last_render(base);
2935
2936            // Enter burst with rapid events.
2937            for i in 0..8u64 {
2938                let t = base + Duration::from_millis(30 * i);
2939                c.handle_resize_at(80 + i as u16, 24 + i as u16, t);
2940            }
2941
2942            // Apply pending and flush rate window with slow events.
2943            let mut t = base + Duration::from_millis(280);
2944            let _ = c.tick_at(t);
2945            for i in 0..5u64 {
2946                t += Duration::from_secs(1);
2947                c.handle_resize_at(100 + i as u16, 30 + i as u16, t);
2948                let _ = c.tick_at(t + Duration::from_millis(60));
2949            }
2950
2951            // Drain cooldown without triggering apply.
2952            t += Duration::from_millis(70);
2953            c.handle_resize_at(120, 35, t);
2954            for step in 1..=config.cooldown_frames {
2955                let _ = c.tick_at(t + Duration::from_millis(step as u64 * 5));
2956            }
2957
2958            c.transition_logs()
2959                .iter()
2960                .map(|entry| {
2961                    (
2962                        entry.from_regime,
2963                        entry.to_regime,
2964                        entry.reason_code,
2965                        entry.event_idx,
2966                        entry.cooldown_remaining,
2967                    )
2968                })
2969                .collect::<Vec<_>>()
2970        };
2971
2972        let first = run();
2973        let second = run();
2974        assert_eq!(first, second);
2975        assert!(
2976            first.iter().any(|(_, to, reason, _, _)| {
2977                *to == Regime::Burst && *reason == TransitionReasonCode::HeuristicEnterBurstRate
2978            }),
2979            "expected steady->burst transition with heuristic reason"
2980        );
2981        assert!(
2982            first.iter().any(|(_, to, reason, _, _)| {
2983                *to == Regime::Steady && *reason == TransitionReasonCode::HeuristicExitBurstCooldown
2984            }),
2985            "expected burst->steady transition with cooldown reason"
2986        );
2987    }
2988
2989    #[test]
2990    fn bounded_oscillation_and_converges_to_steady() {
2991        let config = CoalescerConfig {
2992            burst_enter_rate: 5.0,
2993            burst_exit_rate: 2.0,
2994            cooldown_frames: 3,
2995            rate_window_size: 4,
2996            steady_delay_ms: 10,
2997            burst_delay_ms: 50,
2998            hard_deadline_ms: 5_000,
2999            enable_logging: true,
3000            enable_bocpd: false,
3001            heuristic_fallback: true,
3002            bocpd_config: None,
3003        };
3004        let base = Instant::now();
3005        let mut c = ResizeCoalescer::new(config.clone(), (80, 24)).with_last_render(base);
3006        let mut t = base;
3007
3008        // Alternate burst pulses with limited cooldown opportunities.
3009        for cycle in 0..30u64 {
3010            for pulse in 0..6u64 {
3011                t += Duration::from_millis(30);
3012                c.handle_resize_at(80 + ((cycle + pulse) % 40) as u16, 24 + pulse as u16, t);
3013            }
3014            t += Duration::from_millis(70);
3015            let _ = c.tick_at(t);
3016
3017            t += Duration::from_secs(1);
3018            c.handle_resize_at(120 + (cycle % 20) as u16, 30 + (cycle % 5) as u16, t);
3019            let _ = c.tick_at(t + Duration::from_millis(60));
3020        }
3021
3022        let transitions_before_convergence = c.regime_transition_count();
3023        assert!(
3024            transitions_before_convergence <= 4,
3025            "oscillation should stay bounded, transitions={}",
3026            transitions_before_convergence
3027        );
3028
3029        // Final quiet period: explicitly drain cooldown and verify convergence.
3030        t += Duration::from_secs(1);
3031        c.handle_resize_at(160, 40, t);
3032        for step in 1..=config.cooldown_frames {
3033            let _ = c.tick_at(t + Duration::from_millis(step as u64 * 5));
3034        }
3035        assert_eq!(c.regime(), Regime::Steady);
3036        let last_transition = c
3037            .transition_logs()
3038            .last()
3039            .expect("expected at least one transition");
3040        assert_eq!(last_transition.to_regime, Regime::Steady);
3041        assert_eq!(
3042            last_transition.reason_code,
3043            TransitionReasonCode::HeuristicExitBurstCooldown
3044        );
3045    }
3046
3047    #[test]
3048    fn simulation_bocpd_vs_heuristic_metrics() {
3049        let tick_ms = 5;
3050        // Keep heuristic thresholds high so burst classification is conservative,
3051        // while BOCPD uses a responsive posterior to detect bursty streams.
3052        let mut heuristic_config = test_config();
3053        heuristic_config.burst_enter_rate = 60.0;
3054        heuristic_config.burst_exit_rate = 30.0;
3055        let mut bocpd_cfg = BocpdConfig::responsive();
3056        bocpd_cfg.burst_prior = 0.35;
3057        bocpd_cfg.steady_threshold = 0.2;
3058        bocpd_cfg.burst_threshold = 0.6;
3059        let bocpd_config = heuristic_config.clone().with_bocpd_config(bocpd_cfg);
3060        let patterns = vec![
3061            ("steady", steady_pattern()),
3062            ("burst", burst_pattern()),
3063            ("oscillatory", oscillatory_pattern()),
3064        ];
3065
3066        for (pattern, events) in patterns {
3067            let heuristic = run_simulation(&events, heuristic_config.clone(), tick_ms);
3068            let bocpd = run_simulation(&events, bocpd_config.clone(), tick_ms);
3069
3070            let heuristic_jsonl = heuristic.to_jsonl(pattern, "heuristic");
3071            let bocpd_jsonl = bocpd.to_jsonl(pattern, "bocpd");
3072            let comparison = SimulationComparison::from_metrics(heuristic, bocpd);
3073            let comparison_jsonl = comparison.to_jsonl(pattern);
3074
3075            eprintln!("{heuristic_jsonl}");
3076            eprintln!("{bocpd_jsonl}");
3077            eprintln!("{comparison_jsonl}");
3078
3079            assert!(heuristic_jsonl.contains("\"event\":\"simulation_summary\""));
3080            assert!(bocpd_jsonl.contains("\"event\":\"simulation_summary\""));
3081            assert!(comparison_jsonl.contains("\"event\":\"simulation_compare\""));
3082
3083            #[allow(clippy::cast_precision_loss)]
3084            let max_allowed = test_config().hard_deadline_ms as f64 + 1.0;
3085            assert!(
3086                heuristic.max_coalesce_ms <= max_allowed,
3087                "heuristic latency bounded for {pattern}"
3088            );
3089            assert!(
3090                bocpd.max_coalesce_ms <= max_allowed,
3091                "bocpd latency bounded for {pattern}"
3092            );
3093
3094            if pattern == "burst" {
3095                let event_count = as_u64(events.len());
3096                assert!(
3097                    heuristic.apply_count < event_count,
3098                    "heuristic should coalesce under burst pattern"
3099                );
3100                assert!(
3101                    bocpd.apply_count < event_count,
3102                    "bocpd should coalesce under burst pattern"
3103                );
3104                assert!(
3105                    comparison.apply_delta >= 0,
3106                    "BOCPD should not increase renders in burst (apply_delta={})",
3107                    comparison.apply_delta
3108                );
3109            }
3110        }
3111    }
3112
3113    #[test]
3114    fn never_drops_final_size() {
3115        let config = test_config();
3116        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
3117
3118        let base = Instant::now();
3119
3120        // Many rapid resizes that may trigger some applies due to hard deadline
3121        let mut intermediate_applies = Vec::new();
3122        for i in 0..100 {
3123            let action = c.handle_resize_at(
3124                80 + (i % 50),
3125                24 + (i % 30),
3126                base + Duration::from_millis(i as u64 * 5),
3127            );
3128            if let CoalesceAction::ApplyResize { width, height, .. } = action {
3129                intermediate_applies.push((width, height));
3130            }
3131        }
3132
3133        // The final size - may apply immediately if deadline is hit
3134        let final_action = c.handle_resize_at(200, 100, base + Duration::from_millis(600));
3135
3136        let applied_size = if let CoalesceAction::ApplyResize { width, height, .. } = final_action {
3137            Some((width, height))
3138        } else {
3139            // If not applied immediately, tick until it is
3140            let mut result = None;
3141            for tick in 0..100 {
3142                let action = c.tick_at(base + Duration::from_millis(700 + tick * 20));
3143                if let CoalesceAction::ApplyResize { width, height, .. } = action {
3144                    result = Some((width, height));
3145                    break;
3146                }
3147            }
3148            result
3149        };
3150
3151        assert_eq!(
3152            applied_size,
3153            Some((200, 100)),
3154            "Must apply final size 200x100"
3155        );
3156    }
3157
3158    #[test]
3159    fn bounded_latency_invariant() {
3160        let config = test_config();
3161        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
3162
3163        let base = Instant::now();
3164        c.handle_resize_at(100, 40, base);
3165
3166        // Simulate time passing without any new events
3167        let mut applied_at = None;
3168        for ms in 0..200 {
3169            let now = base + Duration::from_millis(ms);
3170            let action = c.tick_at(now);
3171            if matches!(action, CoalesceAction::ApplyResize { .. }) {
3172                applied_at = Some(ms);
3173                break;
3174            }
3175        }
3176
3177        assert!(applied_at.is_some(), "Must apply within reasonable time");
3178        assert!(
3179            applied_at.unwrap() <= config.hard_deadline_ms,
3180            "Must apply within hard deadline"
3181        );
3182    }
3183
3184    // =========================================================================
3185    // Property tests (bd-1rz0.8)
3186    // =========================================================================
3187
3188    mod property {
3189        use super::*;
3190        use proptest::prelude::*;
3191
3192        /// Strategy for generating resize dimensions.
3193        fn dimension() -> impl Strategy<Value = u16> {
3194            1u16..500
3195        }
3196
3197        /// Strategy for generating resize event sequences.
3198        fn resize_sequence(max_len: usize) -> impl Strategy<Value = Vec<(u16, u16, u64)>> {
3199            proptest::collection::vec((dimension(), dimension(), 0u64..200), 0..max_len)
3200        }
3201
3202        proptest! {
3203            /// Property: identical sequences yield identical final results.
3204            ///
3205            /// The coalescer must be deterministic - same inputs → same outputs.
3206            #[test]
3207            fn determinism_across_sequences(
3208                events in resize_sequence(50),
3209                tick_offset in 100u64..500
3210            ) {
3211                let config = CoalescerConfig::default();
3212
3213                let results: Vec<_> = (0..2)
3214                    .map(|_| {
3215                        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
3216                        let base = Instant::now();
3217
3218                        for (i, (w, h, delay)) in events.iter().enumerate() {
3219                            let offset = events[..i].iter().map(|(_, _, d)| *d).sum::<u64>() + delay;
3220                            c.handle_resize_at(*w, *h, base + Duration::from_millis(offset));
3221                        }
3222
3223                        // Tick to trigger apply
3224                        let total_time = events.iter().map(|(_, _, d)| d).sum::<u64>() + tick_offset;
3225                        c.tick_at(base + Duration::from_millis(total_time))
3226                    })
3227                    .collect();
3228
3229                prop_assert_eq!(results[0], results[1], "Results must be deterministic");
3230            }
3231
3232            /// Property: the latest resize is never lost (latest-wins semantics).
3233            ///
3234            /// When all coalescing completes, the applied size must match the
3235            /// final requested size.
3236            #[test]
3237            fn latest_wins_never_drops(
3238                events in resize_sequence(20),
3239                final_w in dimension(),
3240                final_h in dimension()
3241            ) {
3242                if events.is_empty() {
3243                    // No events to test
3244                    return Ok(());
3245                }
3246
3247                let config = CoalescerConfig::default();
3248                let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
3249                let base = Instant::now();
3250
3251                // Feed all events
3252                let mut offset = 0u64;
3253                for (w, h, delay) in &events {
3254                    offset += delay;
3255                    c.handle_resize_at(*w, *h, base + Duration::from_millis(offset));
3256                }
3257
3258                // Add final event
3259                offset += 50;
3260                c.handle_resize_at(final_w, final_h, base + Duration::from_millis(offset));
3261
3262                // Tick until we get an apply
3263                let mut result = None;
3264                for tick in 0..200 {
3265                    let action = c.tick_at(base + Duration::from_millis(offset + 10 + tick * 20));
3266                    if let CoalesceAction::ApplyResize { width, height, .. } = action {
3267                        result = Some((width, height));
3268                        break;
3269                    }
3270                }
3271
3272                // The final applied size must match the latest requested size
3273                if let Some((applied_w, applied_h)) = result {
3274                    prop_assert_eq!(
3275                        (applied_w, applied_h),
3276                        (final_w, final_h),
3277                        "Must apply the final size {} x {}",
3278                        final_w,
3279                        final_h
3280                    );
3281                }
3282            }
3283
3284            /// Property: bounded latency is always maintained.
3285            ///
3286            /// A pending resize must be applied within hard_deadline_ms.
3287            #[test]
3288            fn bounded_latency_maintained(
3289                w in dimension(),
3290                h in dimension()
3291            ) {
3292                let config = CoalescerConfig::default();
3293                // Use (0,0) so no generated size (1..500) hits the skip_same_size path
3294                let mut c = ResizeCoalescer::new(config.clone(), (0, 0));
3295                let base = Instant::now();
3296
3297                c.handle_resize_at(w, h, base);
3298
3299                // Tick forward until applied
3300                let mut applied_at = None;
3301                for ms in 0..=config.hard_deadline_ms + 50 {
3302                    let action = c.tick_at(base + Duration::from_millis(ms));
3303                    if matches!(action, CoalesceAction::ApplyResize { .. }) {
3304                        applied_at = Some(ms);
3305                        break;
3306                    }
3307                }
3308
3309                prop_assert!(applied_at.is_some(), "Resize must be applied");
3310                prop_assert!(
3311                    applied_at.unwrap() <= config.hard_deadline_ms,
3312                    "Must apply within hard deadline ({}ms), took {}ms",
3313                    config.hard_deadline_ms,
3314                    applied_at.unwrap()
3315                );
3316            }
3317
3318            /// Property: applied sizes are never corrupted.
3319            ///
3320            /// When a resize is applied, the dimensions must exactly match
3321            /// what was requested (no off-by-one, no swapped axes).
3322            #[test]
3323            fn no_size_corruption(
3324                w in dimension(),
3325                h in dimension()
3326            ) {
3327                let config = CoalescerConfig::default();
3328                // Use (0,0) so no generated size (1..500) hits the skip_same_size path
3329                let mut c = ResizeCoalescer::new(config.clone(), (0, 0));
3330                let base = Instant::now();
3331
3332                c.handle_resize_at(w, h, base);
3333
3334                // Tick until applied
3335                let mut result = None;
3336                for ms in 0..200 {
3337                    let action = c.tick_at(base + Duration::from_millis(ms));
3338                    if let CoalesceAction::ApplyResize { width, height, .. } = action {
3339                        result = Some((width, height));
3340                        break;
3341                    }
3342                }
3343
3344                prop_assert!(result.is_some());
3345                let (applied_w, applied_h) = result.unwrap();
3346                prop_assert_eq!(applied_w, w, "Width must not be corrupted");
3347                prop_assert_eq!(applied_h, h, "Height must not be corrupted");
3348            }
3349
3350            /// Property: regime transitions are monotonic with event rate.
3351            ///
3352            /// Higher event rates should more reliably trigger burst mode.
3353            #[test]
3354            fn regime_follows_event_rate(
3355                event_count in 1usize..30
3356            ) {
3357                // This property is about the rate rule itself, so run the
3358                // heuristic detector alone.
3359                let config = CoalescerConfig {
3360                    burst_enter_rate: 10.0,
3361                    burst_exit_rate: 5.0,
3362                    ..CoalescerConfig::default().without_bocpd()
3363                };
3364                let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
3365                let base = Instant::now();
3366
3367                // Very fast events (>10/sec) should trigger burst mode
3368                for i in 0..event_count {
3369                    c.handle_resize_at(
3370                        80 + i as u16,
3371                        24,
3372                        base + Duration::from_millis(i as u64 * 50), // 20 events/sec
3373                    );
3374                }
3375
3376                // With enough fast events, should enter burst
3377                if event_count >= 10 {
3378                    prop_assert_eq!(
3379                        c.regime(),
3380                        Regime::Burst,
3381                        "Many rapid events should trigger burst mode"
3382                    );
3383                }
3384            }
3385
3386            /// Property: event count invariant - coalescer tracks all incoming events.
3387            ///
3388            /// The `event_count` field tracks ALL resize events for rate calculation
3389            /// and telemetry, including same-size events that are skipped.
3390            #[test]
3391            fn event_count_invariant(
3392                events in resize_sequence(100)
3393            ) {
3394                let config = CoalescerConfig::default();
3395                let mut c = ResizeCoalescer::new(config, (80, 24));
3396                let base = Instant::now();
3397
3398                for (w, h, delay) in &events {
3399                    c.handle_resize_at(*w, *h, base + Duration::from_millis(*delay));
3400                }
3401
3402                let stats = c.stats();
3403                // Event count should equal total incoming events (for rate calculation).
3404                prop_assert_eq!(
3405                    stats.event_count,
3406                    events.len() as u64,
3407                    "Event count should match total incoming events"
3408                );
3409            }
3410
3411            // =========================================================================
3412            // BOCPD Property Tests (bd-3e1t.2.5)
3413            // =========================================================================
3414
3415            /// Property: BOCPD determinism - identical sequences yield identical results.
3416            #[test]
3417            fn bocpd_determinism_across_sequences(
3418                events in resize_sequence(30),
3419                tick_offset in 100u64..400
3420            ) {
3421                let config = CoalescerConfig::default().with_bocpd();
3422
3423                let results: Vec<_> = (0..2)
3424                    .map(|_| {
3425                        let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
3426                        let base = Instant::now();
3427
3428                        for (i, (w, h, delay)) in events.iter().enumerate() {
3429                            let offset = events[..i].iter().map(|(_, _, d)| *d).sum::<u64>() + delay;
3430                            c.handle_resize_at(*w, *h, base + Duration::from_millis(offset));
3431                        }
3432
3433                        let total_time = events.iter().map(|(_, _, d)| d).sum::<u64>() + tick_offset;
3434                        let action = c.tick_at(base + Duration::from_millis(total_time));
3435                        (action, c.regime(), c.bocpd_p_burst())
3436                    })
3437                    .collect();
3438
3439                prop_assert_eq!(results[0], results[1], "BOCPD results must be deterministic");
3440            }
3441
3442            /// Property: BOCPD latest-wins - final resize is always applied.
3443            #[test]
3444            fn bocpd_latest_wins_never_drops(
3445                events in resize_sequence(15),
3446                final_w in dimension(),
3447                final_h in dimension()
3448            ) {
3449                if events.is_empty() {
3450                    return Ok(());
3451                }
3452
3453                let config = CoalescerConfig::default().with_bocpd();
3454                let mut c = ResizeCoalescer::new(config, (80, 24));
3455                let base = Instant::now();
3456
3457                let mut offset = 0u64;
3458                for (w, h, delay) in &events {
3459                    offset += delay;
3460                    c.handle_resize_at(*w, *h, base + Duration::from_millis(offset));
3461                }
3462
3463                offset += 50;
3464                c.handle_resize_at(final_w, final_h, base + Duration::from_millis(offset));
3465
3466                let mut final_applied = None;
3467                for tick in 0..200 {
3468                    let action = c.tick_at(base + Duration::from_millis(offset + 10 + tick * 20));
3469                    if let CoalesceAction::ApplyResize { width, height, .. } = action {
3470                        final_applied = Some((width, height));
3471                    }
3472                    if !c.has_pending() && final_applied.is_some() {
3473                        break;
3474                    }
3475                }
3476
3477                if let Some((applied_w, applied_h)) = final_applied {
3478                    prop_assert_eq!(
3479                        (applied_w, applied_h),
3480                        (final_w, final_h),
3481                        "BOCPD must apply the final size"
3482                    );
3483                }
3484            }
3485
3486            /// Property: BOCPD bounded latency - hard deadline is always met.
3487            #[test]
3488            fn bocpd_bounded_latency_maintained(
3489                w in dimension(),
3490                h in dimension()
3491            ) {
3492                let config = CoalescerConfig::default().with_bocpd();
3493                let mut c = ResizeCoalescer::new(config.clone(), (0, 0));
3494                let base = Instant::now();
3495
3496                c.handle_resize_at(w, h, base);
3497
3498                let mut applied_at = None;
3499                for ms in 0..=config.hard_deadline_ms + 50 {
3500                    let action = c.tick_at(base + Duration::from_millis(ms));
3501                    if matches!(action, CoalesceAction::ApplyResize { .. }) {
3502                        applied_at = Some(ms);
3503                        break;
3504                    }
3505                }
3506
3507                prop_assert!(applied_at.is_some(), "BOCPD resize must be applied");
3508                prop_assert!(
3509                    applied_at.unwrap() <= config.hard_deadline_ms,
3510                    "BOCPD must apply within hard deadline ({}ms), took {}ms",
3511                    config.hard_deadline_ms,
3512                    applied_at.unwrap()
3513                );
3514            }
3515
3516            /// Property: BOCPD posterior always valid (normalized, bounded).
3517            #[test]
3518            fn bocpd_posterior_always_valid(
3519                events in resize_sequence(50)
3520            ) {
3521                if events.is_empty() {
3522                    return Ok(());
3523                }
3524
3525                let config = CoalescerConfig::default().with_bocpd();
3526                let mut c = ResizeCoalescer::new(config, (80, 24));
3527                let base = Instant::now();
3528
3529                for (w, h, delay) in &events {
3530                    c.handle_resize_at(*w, *h, base + Duration::from_millis(*delay));
3531
3532                    // Check posterior validity after each event
3533                    if let Some(bocpd) = c.bocpd() {
3534                        let sum: f64 = bocpd.run_length_posterior().iter().sum();
3535                        prop_assert!(
3536                            (sum - 1.0).abs() < 1e-8,
3537                            "Posterior must sum to 1, got {}",
3538                            sum
3539                        );
3540                    }
3541
3542                    let p_burst = c.bocpd_p_burst().unwrap();
3543                    prop_assert!(
3544                        (0.0..=1.0).contains(&p_burst),
3545                        "P(burst) must be in [0,1], got {}",
3546                        p_burst
3547                    );
3548                }
3549            }
3550        }
3551    }
3552
3553    // =========================================================================
3554    // Telemetry Hooks Tests (bd-1rz0.7)
3555    // =========================================================================
3556
3557    #[test]
3558    fn telemetry_hooks_fire_on_resize_applied() {
3559        use std::sync::Arc;
3560        use std::sync::atomic::{AtomicU32, Ordering};
3561
3562        let applied_count = Arc::new(AtomicU32::new(0));
3563        let applied_count_clone = applied_count.clone();
3564
3565        let hooks = TelemetryHooks::new().on_resize_applied(move |_entry| {
3566            applied_count_clone.fetch_add(1, Ordering::SeqCst);
3567        });
3568
3569        let mut config = test_config();
3570        config.enable_logging = true;
3571        let mut c = ResizeCoalescer::new(config, (80, 24)).with_telemetry_hooks(hooks);
3572
3573        let base = Instant::now();
3574        c.handle_resize_at(100, 40, base);
3575        c.tick_at(base + Duration::from_millis(50));
3576
3577        assert_eq!(applied_count.load(Ordering::SeqCst), 1);
3578    }
3579
3580    #[test]
3581    fn telemetry_hooks_fire_on_regime_change() {
3582        use std::sync::Arc;
3583        use std::sync::atomic::{AtomicU32, Ordering};
3584
3585        let regime_changes = Arc::new(AtomicU32::new(0));
3586        let regime_changes_clone = regime_changes.clone();
3587
3588        let hooks = TelemetryHooks::new().on_regime_change(move |_from, _to| {
3589            regime_changes_clone.fetch_add(1, Ordering::SeqCst);
3590        });
3591
3592        let config = test_config();
3593        let mut c = ResizeCoalescer::new(config, (80, 24)).with_telemetry_hooks(hooks);
3594
3595        let base = Instant::now();
3596
3597        // Rapid events to trigger burst mode
3598        for i in 0..15 {
3599            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 10));
3600        }
3601
3602        // Should have triggered at least one regime change (Steady -> Burst)
3603        assert!(regime_changes.load(Ordering::SeqCst) >= 1);
3604    }
3605
3606    #[test]
3607    fn regime_transition_count_tracks_changes() {
3608        let config = test_config();
3609        let mut c = ResizeCoalescer::new(config, (80, 24));
3610
3611        assert_eq!(c.regime_transition_count(), 0);
3612
3613        let base = Instant::now();
3614
3615        // Rapid events to trigger burst mode
3616        for i in 0..15 {
3617            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 10));
3618        }
3619
3620        // Should have transitioned to Burst at least once
3621        assert!(c.regime_transition_count() >= 1);
3622    }
3623
3624    #[test]
3625    fn cycle_time_percentiles_calculated() {
3626        let mut config = test_config();
3627        config.enable_logging = true;
3628        let mut c = ResizeCoalescer::new(config, (80, 24));
3629
3630        // Initially no percentiles
3631        assert!(c.cycle_time_percentiles().is_none());
3632
3633        let base = Instant::now();
3634
3635        // Generate multiple applies to get cycle times
3636        for i in 0..5 {
3637            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 100));
3638            c.tick_at(base + Duration::from_millis(i as u64 * 100 + 50));
3639        }
3640
3641        // Now should have percentiles
3642        let percentiles = c.cycle_time_percentiles();
3643        assert!(percentiles.is_some());
3644
3645        let p = percentiles.unwrap();
3646        assert!(p.count >= 1);
3647        assert!(p.mean_ms >= 0.0);
3648        assert!(p.p50_ms >= 0.0);
3649        assert!(p.p95_ms >= p.p50_ms);
3650        assert!(p.p99_ms >= p.p95_ms);
3651    }
3652
3653    #[test]
3654    fn cycle_time_percentiles_jsonl_format() {
3655        let percentiles = CycleTimePercentiles {
3656            p50_ms: 10.5,
3657            p95_ms: 25.3,
3658            p99_ms: 42.1,
3659            count: 100,
3660            mean_ms: 15.2,
3661        };
3662
3663        let jsonl = percentiles.to_jsonl();
3664        assert!(jsonl.contains("\"event\":\"cycle_time_percentiles\""));
3665        assert!(jsonl.contains("\"p50_ms\":10.500"));
3666        assert!(jsonl.contains("\"p95_ms\":25.300"));
3667        assert!(jsonl.contains("\"p99_ms\":42.100"));
3668        assert!(jsonl.contains("\"mean_ms\":15.200"));
3669        assert!(jsonl.contains("\"count\":100"));
3670    }
3671
3672    // =========================================================================
3673    // BOCPD Integration Tests (bd-3e1t.2.2)
3674    // =========================================================================
3675
3676    #[test]
3677    fn config_default_enables_bocpd_with_heuristic_fallback() {
3678        let config = CoalescerConfig::default();
3679        assert!(config.enable_bocpd);
3680        assert!(config.heuristic_fallback);
3681        assert!(
3682            config.bocpd_config.is_none(),
3683            "None means BocpdConfig::default()"
3684        );
3685        let jsonl = config.to_jsonl("run", ScreenMode::AltScreen, 80, 24, 0);
3686        assert!(jsonl.contains(r#""enable_bocpd":true"#), "{jsonl}");
3687        assert!(jsonl.contains(r#""heuristic_fallback":true"#), "{jsonl}");
3688
3689        let c = ResizeCoalescer::new(config, (80, 24));
3690        assert!(c.bocpd_enabled());
3691        assert!(c.bocpd().is_some());
3692        assert!(c.bocpd_p_burst().is_some());
3693        assert_eq!(
3694            c.last_detector(),
3695            RegimeDetector::Heuristic,
3696            "nothing decided yet"
3697        );
3698        assert_eq!(c.detector_decisions(), DetectorDecisions::default());
3699    }
3700
3701    /// With defaults the first event has no inter-arrival, so the heuristic
3702    /// decides it; from the second event on the posterior is defined and
3703    /// BOCPD decides. Every `decision` row names its detector.
3704    #[test]
3705    fn first_event_uses_heuristic_then_bocpd() {
3706        let mut c = ResizeCoalescer::new(CoalescerConfig::default().with_logging(true), (80, 24));
3707        let base = Instant::now();
3708
3709        c.handle_resize_at(81, 24, base);
3710        assert_eq!(c.last_detector(), RegimeDetector::Heuristic);
3711        c.handle_resize_at(82, 24, base + Duration::from_millis(30));
3712        assert_eq!(c.last_detector(), RegimeDetector::Bocpd);
3713        c.handle_resize_at(83, 24, base + Duration::from_millis(60));
3714        assert_eq!(c.last_detector(), RegimeDetector::Bocpd);
3715
3716        let jsonl = c.decision_logs_jsonl();
3717        let decisions: Vec<&str> = jsonl
3718            .lines()
3719            .filter(|line| line.contains(r#""event":"decision""#))
3720            .collect();
3721        assert_eq!(decisions.len(), 3, "{jsonl}");
3722        assert!(
3723            decisions[0].contains(r#""detector":"heuristic""#),
3724            "{}",
3725            decisions[0]
3726        );
3727        assert!(decisions[0].contains(r#""p_burst":"#), "{}", decisions[0]);
3728        assert!(
3729            decisions[1].contains(r#""detector":"bocpd""#),
3730            "{}",
3731            decisions[1]
3732        );
3733        assert!(
3734            decisions[2].contains(r#""detector":"bocpd""#),
3735            "{}",
3736            decisions[2]
3737        );
3738        assert_eq!(
3739            c.detector_decisions(),
3740            DetectorDecisions {
3741                bocpd: 2,
3742                heuristic: 1
3743            }
3744        );
3745    }
3746
3747    /// An inter-arrival beyond `max_observation_ms` (10 s by default) would
3748    /// only reach the posterior clamped, so the heuristic decides that event.
3749    #[test]
3750    fn clamped_observation_falls_back_to_heuristic() {
3751        let mut c = ResizeCoalescer::new(CoalescerConfig::default().with_logging(true), (80, 24));
3752        let base = Instant::now();
3753
3754        c.handle_resize_at(81, 24, base);
3755        c.handle_resize_at(82, 24, base + Duration::from_millis(30));
3756        assert_eq!(c.last_detector(), RegimeDetector::Bocpd);
3757
3758        c.handle_resize_at(83, 24, base + Duration::from_secs(20));
3759        assert_eq!(c.last_detector(), RegimeDetector::Heuristic);
3760        let last = c
3761            .decision_logs_jsonl()
3762            .lines()
3763            .rfind(|line| line.contains(r#""event":"decision""#))
3764            .map(str::to_owned)
3765            .expect("decision row");
3766        assert!(last.contains(r#""detector":"heuristic""#), "{last}");
3767
3768        // Sub-millisecond inter-arrivals sit below `min_observation_ms`.
3769        c.handle_resize_at(
3770            84,
3771            24,
3772            base + Duration::from_secs(20) + Duration::from_micros(200),
3773        );
3774        assert_eq!(c.last_detector(), RegimeDetector::Heuristic);
3775
3776        // Back in range: the posterior decides again.
3777        c.handle_resize_at(
3778            85,
3779            24,
3780            base + Duration::from_secs(20) + Duration::from_millis(40),
3781        );
3782        assert_eq!(c.last_detector(), RegimeDetector::Bocpd);
3783    }
3784
3785    /// `heuristic_fallback = false` hands every event to the posterior, even
3786    /// the first one.
3787    #[test]
3788    fn fallback_off_lets_bocpd_decide_the_first_event() {
3789        let config = CoalescerConfig::default().with_heuristic_fallback(false);
3790        let mut c = ResizeCoalescer::new(config, (80, 24));
3791        c.handle_resize_at(81, 24, Instant::now());
3792        assert_eq!(c.last_detector(), RegimeDetector::Bocpd);
3793        assert_eq!(c.detector_decisions().bocpd, 1);
3794    }
3795
3796    /// `without_bocpd()` builds no detector: every decision is heuristic and
3797    /// tagged as such, and rapid events enter Burst through the rate rule.
3798    #[test]
3799    fn explicit_disable_keeps_heuristic_only() {
3800        let config = CoalescerConfig::default()
3801            .without_bocpd()
3802            .with_logging(true);
3803        assert!(!config.enable_bocpd);
3804        assert!(config.bocpd_config.is_none());
3805        let config_row = config.to_jsonl("run", ScreenMode::AltScreen, 80, 24, 0);
3806        assert!(
3807            config_row.contains(r#""enable_bocpd":false"#),
3808            "{config_row}"
3809        );
3810        let mut c = ResizeCoalescer::new(config, (80, 24));
3811        assert!(c.bocpd().is_none());
3812
3813        let base = Instant::now();
3814        for i in 0..12u64 {
3815            c.handle_resize_at(81 + i as u16, 24, base + Duration::from_millis(i * 20));
3816        }
3817        assert_eq!(c.regime(), Regime::Burst);
3818        assert_eq!(c.detector_decisions().bocpd, 0);
3819        assert_eq!(c.detector_decisions().heuristic, 12);
3820
3821        let jsonl = c.decision_logs_jsonl();
3822        assert!(!jsonl.contains(r#""detector":"bocpd""#), "{jsonl}");
3823        assert!(jsonl.contains(r#""detector":"heuristic""#), "{jsonl}");
3824        assert!(jsonl.contains(r#""p_burst":null"#), "{jsonl}");
3825
3826        let transitions = c.transition_logs();
3827        assert!(
3828            transitions.iter().any(|t| t.to_regime == Regime::Burst
3829                && t.reason_code == TransitionReasonCode::HeuristicEnterBurstRate),
3830            "{transitions:?}"
3831        );
3832        assert!(
3833            transitions
3834                .iter()
3835                .all(|t| t.detector == RegimeDetector::Heuristic),
3836            "{transitions:?}"
3837        );
3838        let row = transitions[0].to_jsonl("run", ScreenMode::AltScreen, 80, 24);
3839        assert!(row.contains(r#""detector":"heuristic""#), "{row}");
3840    }
3841
3842    /// BOCPD mode has no between-event exit from the posterior itself, so a
3843    /// burst followed by silence leaves Burst on a tick once the silence
3844    /// reaches `mu_steady_ms`, tagged `bocpd_idle_exit`.
3845    #[test]
3846    fn bocpd_mode_exits_burst_on_idle_tick() {
3847        let mut c = ResizeCoalescer::new(CoalescerConfig::default(), (80, 24));
3848        let base = Instant::now();
3849        let mut now = base;
3850        for i in 0..40u16 {
3851            now += Duration::from_millis(5);
3852            let _ = c.handle_resize_at(100 + (i % 7), 40 + (i % 3), now);
3853        }
3854        assert_eq!(c.last_detector(), RegimeDetector::Bocpd);
3855        assert_eq!(
3856            c.regime(),
3857            Regime::Burst,
3858            "40 events at 200/s must be a burst"
3859        );
3860        let mu_steady = c
3861            .bocpd()
3862            .expect("bocpd on by default")
3863            .config()
3864            .mu_steady_ms;
3865
3866        // Quiet ticks shorter than the steady mean inter-arrival keep Burst.
3867        let _ = c.tick_at(now + Duration::from_millis((mu_steady / 2.0) as u64));
3868        assert_eq!(c.regime(), Regime::Burst);
3869
3870        // Once the silence reaches it, the regime returns to Steady.
3871        let _ = c.tick_at(now + Duration::from_millis(mu_steady as u64 + 1));
3872        assert_eq!(c.regime(), Regime::Steady);
3873        let last = c.transition_logs().last().expect("idle exit recorded");
3874        assert_eq!(last.reason_code, TransitionReasonCode::BocpdIdleExit);
3875        assert_eq!(last.detector, RegimeDetector::Bocpd);
3876        assert!(last.confidence > 0.99, "{last:?}");
3877        assert!(last.p_burst.is_some());
3878        let row = last.to_jsonl("run", ScreenMode::AltScreen, 80, 24);
3879        assert!(row.contains(r#""reason_code":"bocpd_idle_exit""#), "{row}");
3880    }
3881
3882    /// The stats snapshot exposes the detector counters the evidence rows
3883    /// are derived from.
3884    #[test]
3885    fn stats_counts_detector_decisions() {
3886        let mut c = ResizeCoalescer::new(CoalescerConfig::default(), (80, 24));
3887        let base = Instant::now();
3888        c.handle_resize_at(81, 24, base);
3889        c.handle_resize_at(82, 24, base + Duration::from_millis(25));
3890        c.handle_resize_at(83, 24, base + Duration::from_millis(50));
3891        let stats = c.stats();
3892        assert_eq!(stats.detector, RegimeDetector::Bocpd);
3893        assert_eq!(stats.detector_decisions.heuristic, 1);
3894        assert_eq!(stats.detector_decisions.bocpd, 2);
3895        assert_eq!(
3896            stats.detector_decisions.bocpd + stats.detector_decisions.heuristic,
3897            stats.event_count
3898        );
3899    }
3900
3901    #[test]
3902    fn bocpd_enabled_with_config() {
3903        let config = CoalescerConfig::default().with_bocpd();
3904        let c = ResizeCoalescer::new(config, (80, 24));
3905        assert!(c.bocpd_enabled());
3906        assert!(c.bocpd().is_some());
3907    }
3908
3909    #[test]
3910    fn bocpd_posterior_normalized() {
3911        let config = CoalescerConfig::default().with_bocpd();
3912        let mut c = ResizeCoalescer::new(config, (80, 24));
3913
3914        let base = Instant::now();
3915
3916        // Feed events with various inter-arrival times
3917        for i in 0..20 {
3918            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 50));
3919        }
3920
3921        // Check posterior is valid probability
3922        let p_burst = c.bocpd_p_burst().expect("BOCPD should be enabled");
3923        assert!(
3924            (0.0..=1.0).contains(&p_burst),
3925            "P(burst) must be in [0,1], got {}",
3926            p_burst
3927        );
3928
3929        // Check BOCPD internal posterior is normalized
3930        if let Some(bocpd) = c.bocpd() {
3931            let sum: f64 = bocpd.run_length_posterior().iter().sum();
3932            assert!(
3933                (sum - 1.0).abs() < 1e-9,
3934                "Posterior must sum to 1, got {}",
3935                sum
3936            );
3937        }
3938    }
3939
3940    #[test]
3941    fn bocpd_detects_burst_from_rapid_events() {
3942        use crate::bocpd::BocpdConfig;
3943
3944        // Configure BOCPD with clear burst detection
3945        let bocpd_config = BocpdConfig {
3946            mu_steady_ms: 200.0,
3947            mu_burst_ms: 20.0,
3948            burst_threshold: 0.6,
3949            steady_threshold: 0.4,
3950            ..BocpdConfig::default()
3951        };
3952
3953        let config = CoalescerConfig::default().with_bocpd_config(bocpd_config);
3954        let mut c = ResizeCoalescer::new(config, (80, 24));
3955
3956        let base = Instant::now();
3957
3958        // Feed rapid events (10ms intervals = burst-like)
3959        for i in 0..30 {
3960            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 10));
3961        }
3962
3963        // Should have high P(burst) and be in Burst regime
3964        let p_burst = c.bocpd_p_burst().expect("BOCPD should be enabled");
3965        assert!(
3966            p_burst > 0.5,
3967            "Rapid events should yield high P(burst), got {}",
3968            p_burst
3969        );
3970        assert_eq!(
3971            c.regime(),
3972            Regime::Burst,
3973            "Regime should be Burst with rapid events"
3974        );
3975    }
3976
3977    #[test]
3978    fn bocpd_detects_steady_from_slow_events() {
3979        use crate::bocpd::BocpdConfig;
3980
3981        // Configure BOCPD with clear steady detection
3982        let bocpd_config = BocpdConfig {
3983            mu_steady_ms: 200.0,
3984            mu_burst_ms: 20.0,
3985            burst_threshold: 0.7,
3986            steady_threshold: 0.3,
3987            ..BocpdConfig::default()
3988        };
3989
3990        let config = CoalescerConfig::default().with_bocpd_config(bocpd_config);
3991        let mut c = ResizeCoalescer::new(config, (80, 24));
3992
3993        let base = Instant::now();
3994
3995        // Feed slow events (300ms intervals = steady-like)
3996        for i in 0..10 {
3997            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 300));
3998        }
3999
4000        // Should have low P(burst) and be in Steady regime
4001        let p_burst = c.bocpd_p_burst().expect("BOCPD should be enabled");
4002        assert!(
4003            p_burst < 0.5,
4004            "Slow events should yield low P(burst), got {}",
4005            p_burst
4006        );
4007        assert_eq!(
4008            c.regime(),
4009            Regime::Steady,
4010            "Regime should be Steady with slow events"
4011        );
4012    }
4013
4014    #[test]
4015    fn bocpd_recommended_delay_varies_with_regime() {
4016        let config = CoalescerConfig::default().with_bocpd();
4017        let mut c = ResizeCoalescer::new(config, (80, 24));
4018
4019        let base = Instant::now();
4020
4021        // Initial delay (before any events)
4022        c.handle_resize_at(85, 30, base);
4023        let delay_initial = c.bocpd_recommended_delay().expect("BOCPD enabled");
4024
4025        // Feed burst-like events
4026        for i in 1..30 {
4027            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 10));
4028        }
4029        let delay_burst = c.bocpd_recommended_delay().expect("BOCPD enabled");
4030
4031        // Recommended delay should be positive
4032        assert!(delay_initial > 0, "Initial delay should be positive");
4033        assert!(delay_burst > 0, "Burst delay should be positive");
4034    }
4035
4036    #[test]
4037    fn bocpd_update_is_deterministic() {
4038        let config = CoalescerConfig::default().with_bocpd();
4039
4040        let base = Instant::now();
4041
4042        // Run twice with identical inputs
4043        let results: Vec<_> = (0..2)
4044            .map(|_| {
4045                let mut c = ResizeCoalescer::new(config.clone(), (80, 24));
4046                for i in 0..20 {
4047                    c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(i as u64 * 25));
4048                }
4049                (c.regime(), c.bocpd_p_burst())
4050            })
4051            .collect();
4052
4053        assert_eq!(
4054            results[0], results[1],
4055            "BOCPD results must be deterministic"
4056        );
4057    }
4058
4059    #[test]
4060    fn bocpd_memory_bounded() {
4061        use crate::bocpd::BocpdConfig;
4062
4063        // Use a small max_run_length to test memory bounds
4064        let bocpd_config = BocpdConfig {
4065            max_run_length: 50,
4066            ..BocpdConfig::default()
4067        };
4068
4069        let config = CoalescerConfig::default().with_bocpd_config(bocpd_config);
4070        let mut c = ResizeCoalescer::new(config, (80, 24));
4071
4072        let base = Instant::now();
4073
4074        // Feed many events
4075        for i in 0u64..200 {
4076            c.handle_resize_at(
4077                80 + (i as u16 % 100),
4078                24 + (i as u16 % 50),
4079                base + Duration::from_millis(i * 20),
4080            );
4081        }
4082
4083        // Check posterior length is bounded
4084        if let Some(bocpd) = c.bocpd() {
4085            let posterior_len = bocpd.run_length_posterior().len();
4086            assert!(
4087                posterior_len <= 51, // max_run_length + 1
4088                "Posterior length should be bounded, got {}",
4089                posterior_len
4090            );
4091        }
4092    }
4093
4094    #[test]
4095    fn bocpd_stable_under_mixed_traffic() {
4096        let config = CoalescerConfig::default().with_bocpd();
4097        let mut c = ResizeCoalescer::new(config, (80, 24));
4098
4099        let base = Instant::now();
4100        let mut offset = 0u64;
4101
4102        // Steady period
4103        for i in 0..5 {
4104            offset += 200;
4105            c.handle_resize_at(80 + i, 24 + i, base + Duration::from_millis(offset));
4106        }
4107
4108        // Burst period
4109        for i in 0..15 {
4110            offset += 15;
4111            c.handle_resize_at(90 + i, 30 + i, base + Duration::from_millis(offset));
4112        }
4113
4114        // Steady period again
4115        for i in 0..5 {
4116            offset += 250;
4117            c.handle_resize_at(100 + i, 40 + i, base + Duration::from_millis(offset));
4118        }
4119
4120        // Posterior should still be valid
4121        let p_burst = c.bocpd_p_burst().expect("BOCPD enabled");
4122        assert!(
4123            (0.0..=1.0).contains(&p_burst),
4124            "P(burst) must remain valid after mixed traffic"
4125        );
4126
4127        if let Some(bocpd) = c.bocpd() {
4128            let sum: f64 = bocpd.run_length_posterior().iter().sum();
4129            assert!((sum - 1.0).abs() < 1e-9, "Posterior must remain normalized");
4130        }
4131    }
4132
4133    // =========================================================================
4134    // Evidence JSONL field validation tests (bd-plwf)
4135    // =========================================================================
4136
4137    #[test]
4138    fn evidence_decision_jsonl_contains_all_required_fields() {
4139        let log = DecisionLog {
4140            timestamp: Instant::now(),
4141            elapsed_ms: 16.5,
4142            event_idx: 1,
4143            dt_ms: 16.0,
4144            event_rate: 62.5,
4145            regime: Regime::Steady,
4146            action: "apply",
4147            pending_size: Some((100, 40)),
4148            applied_size: Some((100, 40)),
4149            time_since_render_ms: 16.2,
4150            coalesce_ms: Some(16.0),
4151            forced: false,
4152            transition_reason_code: None,
4153            transition_confidence: None,
4154            detector: RegimeDetector::Heuristic,
4155            p_burst: None,
4156        };
4157
4158        let jsonl = log.to_jsonl("test-run-1", ScreenMode::AltScreen, 100, 40);
4159        let parsed: serde_json::Value =
4160            serde_json::from_str(&jsonl).expect("Decision JSONL must be valid JSON");
4161
4162        // Schema fields
4163        assert_eq!(
4164            parsed["schema_version"].as_str().unwrap(),
4165            EVIDENCE_SCHEMA_VERSION
4166        );
4167        assert_eq!(parsed["run_id"].as_str().unwrap(), "test-run-1");
4168        assert_eq!(parsed["event_idx"].as_u64().unwrap(), 1);
4169        assert_eq!(parsed["screen_mode"].as_str().unwrap(), "altscreen");
4170        assert_eq!(parsed["cols"].as_u64().unwrap(), 100);
4171        assert_eq!(parsed["rows"].as_u64().unwrap(), 40);
4172
4173        // Event-specific fields
4174        assert_eq!(parsed["event"].as_str().unwrap(), "decision");
4175        assert!(parsed["elapsed_ms"].as_f64().is_some());
4176        assert!(parsed["dt_ms"].as_f64().is_some());
4177        assert!(parsed["event_rate"].as_f64().is_some());
4178        assert_eq!(parsed["regime"].as_str().unwrap(), "steady");
4179        assert_eq!(parsed["action"].as_str().unwrap(), "apply");
4180        assert_eq!(parsed["pending_w"].as_u64().unwrap(), 100);
4181        assert_eq!(parsed["pending_h"].as_u64().unwrap(), 40);
4182        assert_eq!(parsed["applied_w"].as_u64().unwrap(), 100);
4183        assert_eq!(parsed["applied_h"].as_u64().unwrap(), 40);
4184        assert!(parsed["time_since_render_ms"].as_f64().is_some());
4185        assert!(parsed["coalesce_ms"].as_f64().is_some());
4186        assert!(!parsed["forced"].as_bool().unwrap());
4187        assert!(parsed["transition_reason_code"].is_null());
4188        assert!(parsed["transition_confidence"].is_null());
4189    }
4190
4191    #[test]
4192    fn evidence_decision_jsonl_null_fields_when_no_pending() {
4193        let log = DecisionLog {
4194            timestamp: Instant::now(),
4195            elapsed_ms: 0.0,
4196            event_idx: 0,
4197            dt_ms: 0.0,
4198            event_rate: 0.0,
4199            regime: Regime::Steady,
4200            action: "skip_same_size",
4201            pending_size: None,
4202            applied_size: None,
4203            time_since_render_ms: 0.0,
4204            coalesce_ms: None,
4205            forced: false,
4206            transition_reason_code: None,
4207            transition_confidence: None,
4208            detector: RegimeDetector::Heuristic,
4209            p_burst: None,
4210        };
4211
4212        let jsonl = log.to_jsonl("test-run-2", ScreenMode::AltScreen, 80, 24);
4213        let parsed: serde_json::Value =
4214            serde_json::from_str(&jsonl).expect("Decision JSONL must be valid JSON");
4215
4216        assert!(parsed["pending_w"].is_null());
4217        assert!(parsed["pending_h"].is_null());
4218        assert!(parsed["applied_w"].is_null());
4219        assert!(parsed["applied_h"].is_null());
4220        assert!(parsed["coalesce_ms"].is_null());
4221        assert!(parsed["transition_reason_code"].is_null());
4222        assert!(parsed["transition_confidence"].is_null());
4223    }
4224
4225    #[test]
4226    fn evidence_config_jsonl_contains_all_fields() {
4227        let config = test_config();
4228        let jsonl = config.to_jsonl("cfg-run", ScreenMode::AltScreen, 80, 24, 0);
4229        let parsed: serde_json::Value =
4230            serde_json::from_str(&jsonl).expect("Config JSONL must be valid JSON");
4231
4232        assert_eq!(parsed["event"].as_str().unwrap(), "config");
4233        assert_eq!(
4234            parsed["schema_version"].as_str().unwrap(),
4235            EVIDENCE_SCHEMA_VERSION
4236        );
4237        assert_eq!(parsed["steady_delay_ms"].as_u64().unwrap(), 16);
4238        assert_eq!(parsed["burst_delay_ms"].as_u64().unwrap(), 40);
4239        assert_eq!(parsed["hard_deadline_ms"].as_u64().unwrap(), 100);
4240        assert!(parsed["burst_enter_rate"].as_f64().is_some());
4241        assert!(parsed["burst_exit_rate"].as_f64().is_some());
4242        assert_eq!(parsed["cooldown_frames"].as_u64().unwrap(), 3);
4243        assert_eq!(parsed["rate_window_size"].as_u64().unwrap(), 8);
4244    }
4245
4246    #[test]
4247    fn evidence_inline_screen_mode_string() {
4248        let log = DecisionLog {
4249            timestamp: Instant::now(),
4250            elapsed_ms: 0.0,
4251            event_idx: 0,
4252            dt_ms: 0.0,
4253            event_rate: 0.0,
4254            regime: Regime::Burst,
4255            action: "coalesce",
4256            pending_size: Some((120, 40)),
4257            applied_size: None,
4258            time_since_render_ms: 5.0,
4259            coalesce_ms: None,
4260            forced: false,
4261            transition_reason_code: None,
4262            transition_confidence: None,
4263            detector: RegimeDetector::Heuristic,
4264            p_burst: None,
4265        };
4266
4267        let jsonl = log.to_jsonl("inline-run", ScreenMode::Inline { ui_height: 12 }, 120, 40);
4268        let parsed: serde_json::Value =
4269            serde_json::from_str(&jsonl).expect("JSONL must be valid JSON");
4270
4271        assert_eq!(parsed["screen_mode"].as_str().unwrap(), "inline");
4272        assert_eq!(parsed["regime"].as_str().unwrap(), "burst");
4273    }
4274
4275    #[test]
4276    fn resize_scheduling_steady_applies_within_steady_delay() {
4277        let config = CoalescerConfig {
4278            steady_delay_ms: 20,
4279            burst_delay_ms: 50,
4280            hard_deadline_ms: 200,
4281            enable_logging: true,
4282            ..test_config()
4283        };
4284        let base = Instant::now();
4285        let mut c = ResizeCoalescer::new(config, (80, 24));
4286
4287        // Single resize in steady mode
4288        let action = c.handle_resize_at(100, 40, base);
4289        // First resize may or may not apply immediately depending on implementation
4290        match action {
4291            CoalesceAction::ApplyResize { width, height, .. } => {
4292                assert_eq!(width, 100);
4293                assert_eq!(height, 40);
4294            }
4295            CoalesceAction::None => {
4296                // Tick past steady delay to get the apply
4297                let later = base + Duration::from_millis(25);
4298                let action = c.tick_at(later);
4299                if let CoalesceAction::ApplyResize { width, height, .. } = action {
4300                    assert_eq!(width, 100);
4301                    assert_eq!(height, 40);
4302                }
4303            }
4304        }
4305
4306        // Verify final applied size
4307        assert_eq!(c.last_applied(), (100, 40));
4308    }
4309
4310    #[test]
4311    fn resize_scheduling_burst_regime_coalesces_rapid_events() {
4312        let config = CoalescerConfig {
4313            steady_delay_ms: 16,
4314            burst_delay_ms: 40,
4315            hard_deadline_ms: 100,
4316            burst_enter_rate: 10.0,
4317            enable_logging: true,
4318            ..test_config()
4319        };
4320        let base = Instant::now();
4321        let mut c = ResizeCoalescer::new(config, (80, 24));
4322        let mut apply_count = 0u32;
4323
4324        // Rapid resize events (20 events at 50ms intervals = 20 Hz)
4325        for i in 0..20 {
4326            let t = base + Duration::from_millis(i * 50);
4327            let action = c.handle_resize_at(80 + (i as u16), 24, t);
4328            if matches!(action, CoalesceAction::ApplyResize { .. }) {
4329                apply_count += 1;
4330            }
4331            // Tick between events
4332            let tick_t = t + Duration::from_millis(10);
4333            let tick_action = c.tick_at(tick_t);
4334            if matches!(tick_action, CoalesceAction::ApplyResize { .. }) {
4335                apply_count += 1;
4336            }
4337        }
4338
4339        // Should have coalesced: fewer applies than events
4340        assert!(
4341            apply_count < 20,
4342            "Expected coalescing: {apply_count} applies for 20 events"
4343        );
4344        // But should still have rendered at least once
4345        assert!(apply_count > 0, "Should have at least one apply");
4346    }
4347
4348    #[test]
4349    fn evidence_summary_jsonl_includes_checksum() {
4350        let config = CoalescerConfig {
4351            enable_logging: true,
4352            ..test_config()
4353        };
4354        let base = Instant::now();
4355        let mut c = ResizeCoalescer::new(config, (80, 24));
4356
4357        // Generate some events
4358        c.handle_resize_at(100, 40, base + Duration::from_millis(10));
4359        c.tick_at(base + Duration::from_millis(30));
4360
4361        let all_lines = c.evidence_to_jsonl();
4362        let summary_line = all_lines.lines().last().expect("Should have summary line");
4363        let parsed: serde_json::Value =
4364            serde_json::from_str(summary_line).expect("Summary JSONL line must be valid JSON");
4365
4366        assert_eq!(parsed["event"].as_str().unwrap(), "summary");
4367        assert!(parsed["decisions"].as_u64().is_some());
4368        assert!(parsed["applies"].as_u64().is_some());
4369        assert!(parsed["forced_applies"].as_u64().is_some());
4370        assert!(parsed["coalesces"].as_u64().is_some());
4371        assert!(parsed["skips"].as_u64().is_some());
4372        assert!(parsed["regime"].as_str().is_some());
4373        assert!(parsed["checksum"].as_str().is_some());
4374    }
4375
4376    // =========================================================================
4377    // DecisionEvidence tests (bd-dionl)
4378    // =========================================================================
4379
4380    #[test]
4381    fn decision_evidence_favor_apply_steady() {
4382        let ev = DecisionEvidence::favor_apply(Regime::Steady, 80.0, 2.0);
4383        // Steady regime contrib = 1.0, timing = min(80/50, 2) = 1.6, rate<5 = 0.5
4384        assert!(ev.log_bayes_factor > 0.0, "Should favor apply");
4385        assert_eq!(ev.regime_contribution, 1.0);
4386        assert!((ev.timing_contribution - 1.6).abs() < 0.01);
4387        assert_eq!(ev.rate_contribution, 0.5);
4388        assert!(ev.is_strong());
4389        assert!(ev.is_decisive());
4390    }
4391
4392    #[test]
4393    fn decision_evidence_favor_apply_burst_regime() {
4394        let ev = DecisionEvidence::favor_apply(Regime::Burst, 10.0, 20.0);
4395        // Burst regime contrib = -0.5, timing = min(10/50, 2) = 0.2, rate>=5 = -0.3
4396        assert_eq!(ev.regime_contribution, -0.5);
4397        assert!((ev.timing_contribution - 0.2).abs() < 0.01);
4398        assert_eq!(ev.rate_contribution, -0.3);
4399        // LBF = -0.5 + 0.2 + (-0.3) = -0.6, so not strong
4400        assert!(!ev.is_strong());
4401    }
4402
4403    #[test]
4404    fn decision_evidence_favor_coalesce_burst() {
4405        let ev = DecisionEvidence::favor_coalesce(Regime::Burst, 5.0, 15.0);
4406        // Burst regime contrib = 1.0, timing = min(20/5, 2) = 2.0, rate>10 = 0.5
4407        // LBF = -(1.0 + 2.0 + 0.5) = -3.5
4408        assert!(ev.log_bayes_factor < 0.0, "Should favor coalesce");
4409        assert_eq!(ev.regime_contribution, 1.0);
4410        assert!((ev.timing_contribution - 2.0).abs() < 0.01);
4411        assert_eq!(ev.rate_contribution, 0.5);
4412        assert!(ev.is_strong());
4413        assert!(ev.is_decisive());
4414    }
4415
4416    #[test]
4417    fn decision_evidence_favor_coalesce_steady_regime() {
4418        let ev = DecisionEvidence::favor_coalesce(Regime::Steady, 100.0, 3.0);
4419        // Steady regime contrib = -0.5, timing = min(20/100, 2) = 0.2, rate<=10 = -0.3
4420        assert_eq!(ev.regime_contribution, -0.5);
4421        assert!((ev.timing_contribution - 0.2).abs() < 0.01);
4422        assert_eq!(ev.rate_contribution, -0.3);
4423    }
4424
4425    #[test]
4426    fn decision_evidence_forced_deadline() {
4427        let ev = DecisionEvidence::forced_deadline(100.0);
4428        assert!(ev.log_bayes_factor.is_infinite());
4429        assert_eq!(ev.regime_contribution, 0.0);
4430        assert!((ev.timing_contribution - 100.0).abs() < 0.01);
4431        assert_eq!(ev.rate_contribution, 0.0);
4432        assert!(ev.is_strong());
4433        assert!(ev.is_decisive());
4434        assert!(ev.explanation.contains("100.0ms"));
4435    }
4436
4437    #[test]
4438    fn decision_evidence_is_strong_boundary() {
4439        // Exactly 1.0 is NOT strong (need >1.0)
4440        let ev = DecisionEvidence {
4441            log_bayes_factor: 1.0,
4442            regime_contribution: 0.0,
4443            timing_contribution: 0.0,
4444            rate_contribution: 0.0,
4445            explanation: String::new(),
4446        };
4447        assert!(!ev.is_strong());
4448
4449        let ev2 = DecisionEvidence {
4450            log_bayes_factor: 1.001,
4451            ..ev.clone()
4452        };
4453        assert!(ev2.is_strong());
4454
4455        // Negative values also count
4456        let ev3 = DecisionEvidence {
4457            log_bayes_factor: -1.5,
4458            ..ev
4459        };
4460        assert!(ev3.is_strong());
4461    }
4462
4463    #[test]
4464    fn decision_evidence_is_decisive_boundary() {
4465        let ev = DecisionEvidence {
4466            log_bayes_factor: 2.0,
4467            regime_contribution: 0.0,
4468            timing_contribution: 0.0,
4469            rate_contribution: 0.0,
4470            explanation: String::new(),
4471        };
4472        assert!(!ev.is_decisive()); // need >2.0
4473
4474        let ev2 = DecisionEvidence {
4475            log_bayes_factor: 2.001,
4476            ..ev
4477        };
4478        assert!(ev2.is_decisive());
4479    }
4480
4481    #[test]
4482    fn decision_evidence_to_jsonl_valid() {
4483        let ev = DecisionEvidence::favor_apply(Regime::Steady, 50.0, 3.0);
4484        let jsonl = ev.to_jsonl("test-run", ScreenMode::AltScreen, 80, 24, 5);
4485        let parsed: serde_json::Value =
4486            serde_json::from_str(&jsonl).expect("DecisionEvidence JSONL must be valid JSON");
4487
4488        assert_eq!(parsed["event"].as_str().unwrap(), "decision_evidence");
4489        assert!(parsed["log_bayes_factor"].as_f64().is_some());
4490        assert!(parsed["regime_contribution"].as_f64().is_some());
4491        assert!(parsed["timing_contribution"].as_f64().is_some());
4492        assert!(parsed["rate_contribution"].as_f64().is_some());
4493        assert!(parsed["explanation"].as_str().is_some());
4494    }
4495
4496    #[test]
4497    fn decision_evidence_to_jsonl_infinity() {
4498        let ev = DecisionEvidence::forced_deadline(100.0);
4499        let jsonl = ev.to_jsonl("test-run", ScreenMode::AltScreen, 80, 24, 0);
4500        // Infinity serialized as "inf" string
4501        assert!(jsonl.contains("\"inf\""));
4502    }
4503
4504    // =========================================================================
4505    // Edge case tests (bd-dionl)
4506    // =========================================================================
4507
4508    #[test]
4509    fn hard_deadline_zero_applies_immediately() {
4510        let config = CoalescerConfig {
4511            hard_deadline_ms: 0,
4512            enable_logging: true,
4513            ..test_config()
4514        };
4515        let mut c = ResizeCoalescer::new(config, (80, 24));
4516        let base = Instant::now();
4517
4518        // Any resize should apply immediately since deadline is 0
4519        let action = c.handle_resize_at(100, 40, base);
4520        assert!(
4521            matches!(action, CoalesceAction::ApplyResize { .. }),
4522            "hard_deadline_ms=0 should force immediate apply, got {action:?}"
4523        );
4524    }
4525
4526    #[test]
4527    fn rate_window_size_zero_returns_zero_rate() {
4528        let config = CoalescerConfig {
4529            rate_window_size: 0,
4530            enable_logging: true,
4531            ..test_config()
4532        };
4533        let mut c = ResizeCoalescer::new(config, (80, 24));
4534        let base = Instant::now();
4535
4536        for i in 0..5 {
4537            c.handle_resize_at(80 + i, 24, base + Duration::from_millis(i as u64 * 10));
4538        }
4539        // With window=0, only 1 event kept, so < 2 elements → rate=0
4540        let rate = c.calculate_event_rate(base + Duration::from_millis(50));
4541        assert_eq!(rate, 0.0, "rate_window_size=0 should yield 0 rate");
4542    }
4543
4544    #[test]
4545    fn tick_no_pending_returns_none() {
4546        let config = test_config();
4547        let mut c = ResizeCoalescer::new(config, (80, 24));
4548        let base = Instant::now();
4549
4550        // No resize events, tick should return None
4551        let action = c.tick_at(base);
4552        assert_eq!(action, CoalesceAction::None);
4553        let action = c.tick_at(base + Duration::from_millis(500));
4554        assert_eq!(action, CoalesceAction::None);
4555    }
4556
4557    #[test]
4558    fn time_until_apply_none_when_no_pending() {
4559        let c = ResizeCoalescer::new(test_config(), (80, 24));
4560        assert!(c.time_until_apply(Instant::now()).is_none());
4561    }
4562
4563    #[test]
4564    fn time_until_apply_zero_when_past_delay() {
4565        let config = test_config();
4566        let mut c = ResizeCoalescer::new(config, (80, 24));
4567        let base = Instant::now();
4568
4569        c.handle_resize_at(100, 40, base);
4570        // Well past the steady_delay_ms of 16ms
4571        let result = c.time_until_apply(base + Duration::from_millis(500));
4572        assert_eq!(result, Some(Duration::ZERO));
4573    }
4574
4575    // =========================================================================
4576    // json_escape tests (bd-dionl)
4577    // =========================================================================
4578
4579    #[test]
4580    fn json_escape_special_characters() {
4581        assert_eq!(json_escape("hello"), "hello");
4582        assert_eq!(json_escape("a\"b"), "a\\\"b");
4583        assert_eq!(json_escape("a\\b"), "a\\\\b");
4584        assert_eq!(json_escape("a\nb"), "a\\nb");
4585        assert_eq!(json_escape("a\rb"), "a\\rb");
4586        assert_eq!(json_escape("a\tb"), "a\\tb");
4587    }
4588
4589    #[test]
4590    fn json_escape_control_characters() {
4591        // Control char \x01 should be escaped as \u0001
4592        let input = "a\x01b";
4593        let escaped = json_escape(input);
4594        assert_eq!(escaped, "a\\u0001b");
4595    }
4596
4597    #[test]
4598    fn json_escape_empty_string() {
4599        assert_eq!(json_escape(""), "");
4600    }
4601
4602    // =========================================================================
4603    // clear_logs and decision_logs_jsonl tests (bd-dionl)
4604    // =========================================================================
4605
4606    #[test]
4607    fn clear_logs_resets_state() {
4608        let mut config = test_config();
4609        config.enable_logging = true;
4610        let mut c = ResizeCoalescer::new(config, (80, 24));
4611
4612        c.handle_resize_at(100, 40, Instant::now());
4613        c.tick_at(Instant::now() + Duration::from_millis(50));
4614
4615        assert!(!c.logs().is_empty());
4616
4617        c.clear_logs();
4618        assert!(c.logs().is_empty());
4619
4620        // After clearing, new logs should work
4621        c.handle_resize_at(120, 50, Instant::now());
4622        c.tick_at(Instant::now() + Duration::from_millis(50));
4623        assert!(!c.logs().is_empty());
4624    }
4625
4626    #[test]
4627    fn decision_logs_jsonl_each_line_valid() {
4628        let mut config = test_config();
4629        config.enable_logging = true;
4630        let base = Instant::now();
4631        let mut c = ResizeCoalescer::new(config, (80, 24))
4632            .with_evidence_run_id("jsonl-test")
4633            .with_screen_mode(ScreenMode::AltScreen);
4634
4635        c.handle_resize_at(100, 40, base);
4636        c.handle_resize_at(110, 50, base + Duration::from_millis(5));
4637        c.tick_at(base + Duration::from_millis(50));
4638
4639        let jsonl = c.decision_logs_jsonl();
4640        assert!(!jsonl.is_empty());
4641        for line in jsonl.lines() {
4642            let _: serde_json::Value =
4643                serde_json::from_str(line).expect("Each JSONL line must be valid JSON");
4644        }
4645    }
4646
4647    // =========================================================================
4648    // TelemetryHooks tests (bd-dionl)
4649    // =========================================================================
4650
4651    #[test]
4652    fn telemetry_hooks_has_methods() {
4653        let hooks = TelemetryHooks::new();
4654        assert!(!hooks.has_resize_applied());
4655        assert!(!hooks.has_regime_change());
4656        assert!(!hooks.has_decision());
4657
4658        let hooks = hooks.on_resize_applied(|_| {});
4659        assert!(hooks.has_resize_applied());
4660        assert!(!hooks.has_regime_change());
4661        assert!(!hooks.has_decision());
4662    }
4663
4664    #[test]
4665    fn telemetry_hooks_with_tracing() {
4666        let hooks = TelemetryHooks::new().with_tracing(true);
4667        let debug_str = format!("{:?}", hooks);
4668        assert!(debug_str.contains("emit_tracing: true"));
4669    }
4670
4671    #[test]
4672    fn telemetry_hooks_default_equals_new() {
4673        let h1 = TelemetryHooks::default();
4674        let h2 = TelemetryHooks::new();
4675        assert!(!h1.has_resize_applied());
4676        assert!(!h2.has_resize_applied());
4677    }
4678
4679    #[test]
4680    fn telemetry_hooks_on_decision_fires() {
4681        use std::sync::Arc;
4682        use std::sync::atomic::{AtomicU32, Ordering};
4683
4684        let count = Arc::new(AtomicU32::new(0));
4685        let count_clone = count.clone();
4686
4687        let hooks = TelemetryHooks::new().on_decision(move |_entry| {
4688            count_clone.fetch_add(1, Ordering::SeqCst);
4689        });
4690
4691        let mut config = test_config();
4692        config.enable_logging = true;
4693        let mut c = ResizeCoalescer::new(config, (80, 24)).with_telemetry_hooks(hooks);
4694
4695        let base = Instant::now();
4696        c.handle_resize_at(100, 40, base);
4697
4698        // The coalesce decision should fire the on_decision hook
4699        assert!(count.load(Ordering::SeqCst) >= 1);
4700    }
4701
4702    // =========================================================================
4703    // Regime::as_str tests (bd-dionl)
4704    // =========================================================================
4705
4706    #[test]
4707    fn regime_as_str_values() {
4708        assert_eq!(Regime::Steady.as_str(), "steady");
4709        assert_eq!(Regime::Burst.as_str(), "burst");
4710    }
4711
4712    #[test]
4713    fn regime_default_is_steady() {
4714        assert_eq!(Regime::default(), Regime::Steady);
4715    }
4716
4717    // =========================================================================
4718    // DecisionSummary tests (bd-dionl)
4719    // =========================================================================
4720
4721    #[test]
4722    fn decision_summary_checksum_hex_format() {
4723        let summary = DecisionSummary {
4724            checksum: 0x0123456789ABCDEF,
4725            ..DecisionSummary::default()
4726        };
4727        assert_eq!(summary.checksum_hex(), "0123456789abcdef");
4728    }
4729
4730    #[test]
4731    fn decision_summary_default_values() {
4732        let summary = DecisionSummary::default();
4733        assert_eq!(summary.decision_count, 0);
4734        assert_eq!(summary.apply_count, 0);
4735        assert_eq!(summary.forced_apply_count, 0);
4736        assert_eq!(summary.coalesce_count, 0);
4737        assert_eq!(summary.skip_count, 0);
4738        assert_eq!(summary.regime, Regime::Steady);
4739        assert_eq!(summary.last_applied, (0, 0));
4740        assert_eq!(summary.checksum, 0);
4741    }
4742
4743    #[test]
4744    fn decision_summary_to_jsonl_valid() {
4745        let summary = DecisionSummary {
4746            decision_count: 5,
4747            apply_count: 2,
4748            forced_apply_count: 1,
4749            coalesce_count: 2,
4750            skip_count: 1,
4751            regime: Regime::Burst,
4752            last_applied: (120, 40),
4753            checksum: 0xDEADBEEF,
4754        };
4755        let jsonl = summary.to_jsonl("run-1", ScreenMode::AltScreen, 120, 40, 5);
4756        let parsed: serde_json::Value =
4757            serde_json::from_str(&jsonl).expect("Summary JSONL must be valid JSON");
4758
4759        assert_eq!(parsed["event"].as_str().unwrap(), "summary");
4760        assert_eq!(parsed["decisions"].as_u64().unwrap(), 5);
4761        assert_eq!(parsed["applies"].as_u64().unwrap(), 2);
4762        assert_eq!(parsed["forced_applies"].as_u64().unwrap(), 1);
4763        assert_eq!(parsed["coalesces"].as_u64().unwrap(), 2);
4764        assert_eq!(parsed["skips"].as_u64().unwrap(), 1);
4765        assert_eq!(parsed["regime"].as_str().unwrap(), "burst");
4766        assert_eq!(parsed["last_w"].as_u64().unwrap(), 120);
4767        assert_eq!(parsed["last_h"].as_u64().unwrap(), 40);
4768        assert!(parsed["checksum"].as_str().unwrap().contains("deadbeef"));
4769    }
4770
4771    // =========================================================================
4772    // screen_mode_str tests (bd-dionl)
4773    // =========================================================================
4774
4775    #[test]
4776    fn screen_mode_str_all_variants() {
4777        assert_eq!(screen_mode_str(ScreenMode::AltScreen), "altscreen");
4778        assert_eq!(
4779            screen_mode_str(ScreenMode::Inline { ui_height: 10 }),
4780            "inline"
4781        );
4782        assert_eq!(
4783            screen_mode_str(ScreenMode::InlineAuto {
4784                min_height: 5,
4785                max_height: 20,
4786            }),
4787            "inline_auto"
4788        );
4789    }
4790
4791    // =========================================================================
4792    // Config builder chaining tests (bd-dionl)
4793    // =========================================================================
4794
4795    #[test]
4796    fn config_with_logging_chaining() {
4797        let config = CoalescerConfig::default().with_logging(true);
4798        assert!(config.enable_logging);
4799
4800        let config2 = config.with_logging(false);
4801        assert!(!config2.enable_logging);
4802    }
4803
4804    #[test]
4805    fn config_with_bocpd_chaining() {
4806        let config = CoalescerConfig::default().with_bocpd();
4807        assert!(config.enable_bocpd);
4808        assert!(config.bocpd_config.is_some());
4809    }
4810
4811    #[test]
4812    fn config_with_bocpd_config_chaining() {
4813        let bocpd_cfg = BocpdConfig {
4814            max_run_length: 42,
4815            ..BocpdConfig::default()
4816        };
4817        let config = CoalescerConfig::default().with_bocpd_config(bocpd_cfg);
4818        assert!(config.enable_bocpd);
4819        assert_eq!(config.bocpd_config.as_ref().unwrap().max_run_length, 42);
4820    }
4821
4822    // =========================================================================
4823    // Coalescer builder chaining tests (bd-dionl)
4824    // =========================================================================
4825
4826    #[test]
4827    fn coalescer_with_evidence_run_id() {
4828        let c = ResizeCoalescer::new(test_config(), (80, 24)).with_evidence_run_id("custom-run-id");
4829        // Verify via evidence JSONL output
4830        let jsonl = c.evidence_to_jsonl();
4831        assert!(jsonl.contains("custom-run-id"));
4832    }
4833
4834    #[test]
4835    fn coalescer_with_screen_mode() {
4836        let mut config = test_config();
4837        config.enable_logging = true;
4838        let mut c = ResizeCoalescer::new(config, (80, 24))
4839            .with_screen_mode(ScreenMode::Inline { ui_height: 8 });
4840
4841        c.handle_resize(100, 40);
4842        let jsonl = c.evidence_to_jsonl();
4843        assert!(jsonl.contains("\"screen_mode\":\"inline\""));
4844    }
4845
4846    #[test]
4847    fn coalescer_set_evidence_sink_clears_config_logged() {
4848        let mut config = test_config();
4849        config.enable_logging = true;
4850        let mut c = ResizeCoalescer::new(config, (80, 24));
4851
4852        // Generate some events so config is logged
4853        c.handle_resize(100, 40);
4854
4855        // Setting evidence sink to None should reset config_logged
4856        c.set_evidence_sink(None);
4857
4858        // Evidence JSONL should still have config line since it rebuilds from config
4859        let jsonl = c.evidence_to_jsonl();
4860        assert!(jsonl.contains("\"event\":\"config\""));
4861    }
4862
4863    // =========================================================================
4864    // duration_since_or_zero tests (bd-dionl)
4865    // =========================================================================
4866
4867    #[test]
4868    fn duration_since_or_zero_normal() {
4869        let earlier = Instant::now();
4870        std::thread::sleep(Duration::from_millis(1));
4871        let now = Instant::now();
4872        let result = duration_since_or_zero(now, earlier);
4873        assert!(result >= Duration::from_millis(1));
4874    }
4875
4876    #[test]
4877    fn duration_since_or_zero_same_instant() {
4878        let now = Instant::now();
4879        let result = duration_since_or_zero(now, now);
4880        assert_eq!(result, Duration::ZERO);
4881    }
4882
4883    // =========================================================================
4884    // ResizeAppliedEvent and RegimeChangeEvent struct tests (bd-dionl)
4885    // =========================================================================
4886
4887    #[test]
4888    fn resize_applied_event_fields() {
4889        let event = ResizeAppliedEvent {
4890            new_size: (100, 40),
4891            old_size: (80, 24),
4892            elapsed: Duration::from_millis(42),
4893            forced: true,
4894        };
4895        assert_eq!(event.new_size, (100, 40));
4896        assert_eq!(event.old_size, (80, 24));
4897        assert_eq!(event.elapsed, Duration::from_millis(42));
4898        assert!(event.forced);
4899    }
4900
4901    #[test]
4902    fn regime_change_event_fields() {
4903        let event = RegimeChangeEvent {
4904            from: Regime::Steady,
4905            to: Regime::Burst,
4906            event_idx: 42,
4907            reason_code: TransitionReasonCode::HeuristicEnterBurstRate,
4908            confidence: 0.91,
4909        };
4910        assert_eq!(event.from, Regime::Steady);
4911        assert_eq!(event.to, Regime::Burst);
4912        assert_eq!(event.event_idx, 42);
4913        assert_eq!(
4914            event.reason_code,
4915            TransitionReasonCode::HeuristicEnterBurstRate
4916        );
4917        assert!((event.confidence - 0.91).abs() < f64::EPSILON);
4918    }
4919
4920    // =========================================================================
4921    // CoalesceAction equality edge cases (bd-dionl)
4922    // =========================================================================
4923
4924    #[test]
4925    fn coalesce_action_none_eq() {
4926        assert_eq!(CoalesceAction::None, CoalesceAction::None);
4927        assert_ne!(
4928            CoalesceAction::None,
4929            CoalesceAction::ApplyResize {
4930                width: 1,
4931                height: 1,
4932                coalesce_time: Duration::ZERO,
4933                forced_by_deadline: false,
4934            }
4935        );
4936    }
4937
4938    /// CONTRACT (bd-1za0z item 2, pinned): in BOCPD mode the posterior owns
4939    /// regime changes; the heuristic cooldown exit must never fire, and the
4940    /// transition log must alternate regimes (no `Burst -> Burst` pairs).
4941    #[test]
4942    fn bocpd_mode_never_emits_heuristic_cooldown_exit() {
4943        let mut c = ResizeCoalescer::new(test_config().with_bocpd(), (80, 24));
4944        let base = Instant::now();
4945        let mut now = base;
4946        // 200 events at 200 events/s (well above the 10/s burst threshold).
4947        for i in 0..200u16 {
4948            now += Duration::from_millis(5);
4949            let _ = c.handle_resize_at(100 + (i % 7), 40 + (i % 3), now);
4950        }
4951        // Then 100 quiet ticks (one per 16 ms frame).
4952        for _ in 0..100 {
4953            now += Duration::from_millis(16);
4954            let _ = c.tick_at(now);
4955        }
4956        let logs = c.transition_logs();
4957        assert!(
4958            logs.iter()
4959                .all(|t| t.reason_code != TransitionReasonCode::HeuristicExitBurstCooldown),
4960            "heuristic cooldown exit fired in BOCPD mode: {logs:?}"
4961        );
4962        for window in logs.windows(2) {
4963            assert_ne!(
4964                window[0].from_regime, window[0].to_regime,
4965                "a transition must change regime: {logs:?}"
4966            );
4967            assert_eq!(
4968                window[0].to_regime, window[1].from_regime,
4969                "consecutive transitions must chain: {logs:?}"
4970            );
4971        }
4972        assert_eq!(c.regime_transition_count(), logs.len() as u64);
4973    }
4974
4975    /// CONTRACT (bd-1za0z item 2, regression): the immediate path
4976    /// (`record_external_apply`, used by `ResizeBehavior::Immediate`) must not
4977    /// leave `stats().regime` pinned to `Burst` once the burst is over.
4978    #[test]
4979    fn immediate_mode_regime_is_not_pinned_to_burst() {
4980        let mut c = ResizeCoalescer::new(test_config(), (80, 24));
4981        let mut now = Instant::now();
4982        assert_eq!(c.stats().regime, Regime::Steady);
4983        // A burst of externally applied resizes (5 ms apart = 200/s).
4984        for i in 0..30u16 {
4985            now += Duration::from_millis(5);
4986            c.record_external_apply(100 + i, 40, now);
4987        }
4988        assert_eq!(c.stats().regime, Regime::Burst, "burst detected");
4989        let transitions_after_burst = c.regime_transition_count();
4990        // The immediate path is never ticked by the frame loop, so the next
4991        // observation is the next resize: an isolated apply after a quiet gap
4992        // must bring the regime back to Steady instead of leaving it pinned.
4993        now += Duration::from_secs(2);
4994        c.record_external_apply(90, 30, now);
4995        assert_eq!(
4996            c.stats().regime,
4997            Regime::Steady,
4998            "regime pinned to Burst after the burst ended"
4999        );
5000        assert_eq!(c.stats().last_applied, (90, 30));
5001        assert_eq!(c.regime_transition_count(), transitions_after_burst + 1);
5002        let last = c.transition_logs().last().expect("exit transition logged");
5003        assert_eq!(
5004            last.reason_code,
5005            TransitionReasonCode::HeuristicExitBurstRate
5006        );
5007        assert_eq!(
5008            (last.from_regime, last.to_regime),
5009            (Regime::Burst, Regime::Steady)
5010        );
5011        assert_eq!(last.reason_code.as_str(), "heuristic_exit_burst_rate");
5012    }
5013
5014    #[test]
5015    fn coalesce_action_apply_resize_eq() {
5016        let a = CoalesceAction::ApplyResize {
5017            width: 100,
5018            height: 40,
5019            coalesce_time: Duration::from_millis(16),
5020            forced_by_deadline: false,
5021        };
5022        let b = CoalesceAction::ApplyResize {
5023            width: 100,
5024            height: 40,
5025            coalesce_time: Duration::from_millis(16),
5026            forced_by_deadline: false,
5027        };
5028        assert_eq!(a, b);
5029
5030        let c = CoalesceAction::ApplyResize {
5031            width: 100,
5032            height: 40,
5033            coalesce_time: Duration::from_millis(16),
5034            forced_by_deadline: true,
5035        };
5036        assert_ne!(a, c);
5037    }
5038
5039    // =========================================================================
5040    // FNV hash consistency (bd-dionl)
5041    // =========================================================================
5042
5043    #[test]
5044    fn fnv_hash_deterministic() {
5045        let mut h1 = FNV_OFFSET_BASIS;
5046        fnv_hash_bytes(&mut h1, b"hello world");
5047
5048        let mut h2 = FNV_OFFSET_BASIS;
5049        fnv_hash_bytes(&mut h2, b"hello world");
5050
5051        assert_eq!(h1, h2);
5052    }
5053
5054    #[test]
5055    fn fnv_hash_different_inputs_different_hashes() {
5056        let mut h1 = FNV_OFFSET_BASIS;
5057        fnv_hash_bytes(&mut h1, b"hello");
5058
5059        let mut h2 = FNV_OFFSET_BASIS;
5060        fnv_hash_bytes(&mut h2, b"world");
5061
5062        assert_ne!(h1, h2);
5063    }
5064
5065    #[test]
5066    fn fnv_hash_empty_input_returns_basis() {
5067        let mut hash = FNV_OFFSET_BASIS;
5068        fnv_hash_bytes(&mut hash, b"");
5069        assert_eq!(hash, FNV_OFFSET_BASIS);
5070    }
5071}