Skip to main content

ftui_runtime/
evidence_telemetry.rs

1#![forbid(unsafe_code)]
2
3//! Evidence telemetry snapshots for runtime explainability overlays.
4//!
5//! These snapshots provide a low-overhead, in-memory view of the most recent
6//! diff, resize, and budget decisions so demo screens can render cockpit
7//! views without parsing JSONL logs.
8
9use std::sync::{LazyLock, RwLock};
10
11#[cfg(test)]
12use std::sync::Mutex;
13
14use ftui_render::budget::{BudgetDecision, DegradationLevel};
15use ftui_render::diff_strategy::{DiffStrategy, StrategyEvidence};
16
17use crate::bocpd::BocpdEvidence;
18use crate::resize_coalescer::Regime;
19
20/// Snapshot of the most recent diff-strategy decision.
21#[derive(Debug, Clone)]
22pub struct DiffDecisionSnapshot {
23    pub event_idx: u64,
24    pub screen_mode: String,
25    pub cols: u16,
26    pub rows: u16,
27    pub evidence: StrategyEvidence,
28    pub span_count: usize,
29    pub span_coverage_pct: f64,
30    pub max_span_len: usize,
31    pub scan_cost_estimate: usize,
32    pub fallback_reason: String,
33    pub tile_used: bool,
34    pub tile_fallback: String,
35    pub strategy_used: DiffStrategy,
36}
37
38/// Snapshot of the most recent resize/coalescer decision.
39#[derive(Debug, Clone)]
40pub struct ResizeDecisionSnapshot {
41    pub event_idx: u64,
42    pub action: &'static str,
43    pub dt_ms: f64,
44    pub event_rate: f64,
45    pub regime: Regime,
46    pub pending_size: Option<(u16, u16)>,
47    pub applied_size: Option<(u16, u16)>,
48    pub time_since_render_ms: f64,
49    pub bocpd: Option<BocpdEvidence>,
50}
51
52/// Conformal evidence snapshot for budget decisions.
53#[derive(Debug, Clone)]
54pub struct ConformalSnapshot {
55    pub bucket_key: String,
56    pub sample_count: usize,
57    pub upper_us: Option<f64>,
58    pub risk: bool,
59    pub status: crate::ConformalStatus,
60    pub required_rank: usize,
61}
62
63/// Snapshot of the most recent budget decision.
64#[derive(Debug, Clone)]
65pub struct BudgetDecisionSnapshot {
66    pub frame_idx: u64,
67    pub decision: BudgetDecision,
68    pub controller_decision: BudgetDecision,
69    pub degradation_before: DegradationLevel,
70    pub degradation_after: DegradationLevel,
71    pub frame_time_us: f64,
72    pub budget_us: f64,
73    pub pid_output: f64,
74    pub e_value: f64,
75    pub frames_observed: u32,
76    pub frames_since_change: u32,
77    pub in_warmup: bool,
78    pub conformal: Option<ConformalSnapshot>,
79}
80
81static DIFF_SNAPSHOT: LazyLock<RwLock<Option<DiffDecisionSnapshot>>> =
82    LazyLock::new(|| RwLock::new(None));
83static RESIZE_SNAPSHOT: LazyLock<RwLock<Option<ResizeDecisionSnapshot>>> =
84    LazyLock::new(|| RwLock::new(None));
85static BUDGET_SNAPSHOT: LazyLock<RwLock<Option<BudgetDecisionSnapshot>>> =
86    LazyLock::new(|| RwLock::new(None));
87
88// Global snapshot telemetry is shared state. In tests, we serialize snapshot
89// access to avoid flakiness under parallel test execution.
90#[cfg(test)]
91static TEST_LOCK: LazyLock<Mutex<()>> = LazyLock::new(|| Mutex::new(()));
92
93/// Store the latest diff decision snapshot.
94pub fn set_diff_snapshot(snapshot: Option<DiffDecisionSnapshot>) {
95    #[cfg(test)]
96    let _lock = TEST_LOCK.lock().expect("test lock poisoned");
97
98    if let Ok(mut guard) = DIFF_SNAPSHOT.write() {
99        *guard = snapshot;
100    }
101}
102
103/// Fetch the latest diff decision snapshot.
104#[must_use]
105pub fn diff_snapshot() -> Option<DiffDecisionSnapshot> {
106    #[cfg(test)]
107    let _lock = TEST_LOCK.lock().expect("test lock poisoned");
108
109    DIFF_SNAPSHOT.read().ok().and_then(|guard| guard.clone())
110}
111
112/// Clear any stored diff snapshot.
113pub fn clear_diff_snapshot() {
114    set_diff_snapshot(None);
115}
116
117/// Store the latest resize decision snapshot.
118pub fn set_resize_snapshot(snapshot: Option<ResizeDecisionSnapshot>) {
119    #[cfg(test)]
120    let _lock = TEST_LOCK.lock().expect("test lock poisoned");
121
122    if let Ok(mut guard) = RESIZE_SNAPSHOT.write() {
123        *guard = snapshot;
124    }
125}
126
127/// Fetch the latest resize decision snapshot.
128#[must_use]
129pub fn resize_snapshot() -> Option<ResizeDecisionSnapshot> {
130    #[cfg(test)]
131    let _lock = TEST_LOCK.lock().expect("test lock poisoned");
132
133    RESIZE_SNAPSHOT.read().ok().and_then(|guard| guard.clone())
134}
135
136/// Clear any stored resize snapshot.
137pub fn clear_resize_snapshot() {
138    set_resize_snapshot(None);
139}
140
141/// Store the latest budget decision snapshot.
142pub fn set_budget_snapshot(snapshot: Option<BudgetDecisionSnapshot>) {
143    #[cfg(test)]
144    let _lock = TEST_LOCK.lock().expect("test lock poisoned");
145
146    if let Ok(mut guard) = BUDGET_SNAPSHOT.write() {
147        *guard = snapshot;
148    }
149}
150
151/// Fetch the latest budget decision snapshot.
152#[must_use]
153pub fn budget_snapshot() -> Option<BudgetDecisionSnapshot> {
154    #[cfg(test)]
155    let _lock = TEST_LOCK.lock().expect("test lock poisoned");
156
157    BUDGET_SNAPSHOT.read().ok().and_then(|guard| guard.clone())
158}
159
160/// Clear any stored budget snapshot.
161pub fn clear_budget_snapshot() {
162    set_budget_snapshot(None);
163}
164
165#[cfg(test)]
166mod tests {
167    use super::*;
168    use ftui_render::budget::{BudgetDecision, DegradationLevel};
169    use ftui_render::diff_strategy::{DiffStrategy, StrategyEvidence};
170
171    use crate::bocpd::{BocpdEvidence, BocpdRegime};
172
173    // ── helpers ──────────────────────────────────────────────────────
174
175    fn make_diff_snapshot(event_idx: u64) -> DiffDecisionSnapshot {
176        DiffDecisionSnapshot {
177            event_idx,
178            screen_mode: "alt".into(),
179            cols: 80,
180            rows: 24,
181            evidence: StrategyEvidence {
182                strategy: DiffStrategy::DirtyRows,
183                cost_full: 1.0,
184                cost_dirty: 0.5,
185                cost_redraw: 2.0,
186                posterior_mean: 0.05,
187                posterior_variance: 0.001,
188                alpha: 2.0,
189                beta: 38.0,
190                dirty_rows: 3,
191                total_rows: 24,
192                total_cells: 1920,
193                guard_reason: "none",
194                hysteresis_applied: false,
195                hysteresis_ratio: 0.05,
196            },
197            span_count: 2,
198            span_coverage_pct: 6.25,
199            max_span_len: 12,
200            scan_cost_estimate: 200,
201            fallback_reason: "none".into(),
202            tile_used: false,
203            tile_fallback: String::new(),
204            strategy_used: DiffStrategy::DirtyRows,
205        }
206    }
207
208    fn make_resize_snapshot(event_idx: u64) -> ResizeDecisionSnapshot {
209        ResizeDecisionSnapshot {
210            event_idx,
211            action: "apply",
212            dt_ms: 150.0,
213            event_rate: 5.0,
214            regime: Regime::Steady,
215            pending_size: None,
216            applied_size: Some((120, 40)),
217            time_since_render_ms: 100.0,
218            bocpd: None,
219        }
220    }
221
222    fn make_budget_snapshot(frame_idx: u64) -> BudgetDecisionSnapshot {
223        BudgetDecisionSnapshot {
224            frame_idx,
225            decision: BudgetDecision::Hold,
226            controller_decision: BudgetDecision::Hold,
227            degradation_before: DegradationLevel::Full,
228            degradation_after: DegradationLevel::Full,
229            frame_time_us: 8000.0,
230            budget_us: 16000.0,
231            pid_output: 0.1,
232            e_value: 0.5,
233            frames_observed: 100,
234            frames_since_change: 50,
235            in_warmup: false,
236            conformal: None,
237        }
238    }
239
240    // ── diff snapshot tests ─────────────────────────────────────────
241
242    #[test]
243    fn diff_snapshot_initially_none() {
244        let mut guard = DIFF_SNAPSHOT.write().expect("diff snapshot lock poisoned");
245        *guard = None;
246        assert!(guard.is_none());
247    }
248
249    #[test]
250    fn diff_snapshot_store_and_retrieve() {
251        let snap = make_diff_snapshot(42);
252        let mut guard = DIFF_SNAPSHOT.write().expect("diff snapshot lock poisoned");
253        *guard = Some(snap);
254        let retrieved = guard.clone().expect("should be Some");
255        assert_eq!(retrieved.event_idx, 42);
256        assert_eq!(retrieved.cols, 80);
257        assert_eq!(retrieved.rows, 24);
258        *guard = None;
259    }
260
261    #[test]
262    fn diff_snapshot_overwrite() {
263        let mut guard = DIFF_SNAPSHOT.write().expect("diff snapshot lock poisoned");
264        *guard = Some(make_diff_snapshot(1));
265        *guard = Some(make_diff_snapshot(2));
266        let snap = guard.clone().expect("should be Some");
267        assert_eq!(snap.event_idx, 2);
268        *guard = None;
269    }
270
271    #[test]
272    fn diff_snapshot_clear() {
273        let mut guard = DIFF_SNAPSHOT.write().expect("diff snapshot lock poisoned");
274        *guard = Some(make_diff_snapshot(10));
275        *guard = None;
276        assert!(guard.is_none());
277    }
278
279    #[test]
280    fn diff_snapshot_preserves_evidence_fields() {
281        let snap = make_diff_snapshot(7);
282        let mut guard = DIFF_SNAPSHOT.write().expect("diff snapshot lock poisoned");
283        *guard = Some(snap);
284        let retrieved = guard.clone().unwrap();
285        assert_eq!(retrieved.evidence.strategy, DiffStrategy::DirtyRows);
286        assert!((retrieved.evidence.cost_full - 1.0).abs() < f64::EPSILON);
287        assert!((retrieved.evidence.posterior_mean - 0.05).abs() < f64::EPSILON);
288        assert_eq!(retrieved.span_count, 2);
289        assert_eq!(retrieved.strategy_used, DiffStrategy::DirtyRows);
290        *guard = None;
291    }
292
293    // ── resize snapshot tests ───────────────────────────────────────
294
295    #[test]
296    fn resize_snapshot_initially_none() {
297        let mut guard = RESIZE_SNAPSHOT
298            .write()
299            .expect("resize snapshot lock poisoned");
300        *guard = None;
301        assert!(guard.is_none());
302    }
303
304    #[test]
305    fn resize_snapshot_store_and_retrieve() {
306        let snap = make_resize_snapshot(5);
307        let mut guard = RESIZE_SNAPSHOT
308            .write()
309            .expect("resize snapshot lock poisoned");
310        *guard = Some(snap);
311        let retrieved = guard.clone().expect("should be Some");
312        assert_eq!(retrieved.event_idx, 5);
313        assert_eq!(retrieved.action, "apply");
314        assert_eq!(retrieved.regime, Regime::Steady);
315        assert_eq!(retrieved.applied_size, Some((120, 40)));
316        *guard = None;
317    }
318
319    #[test]
320    fn resize_snapshot_overwrite() {
321        let mut guard = RESIZE_SNAPSHOT
322            .write()
323            .expect("resize snapshot lock poisoned");
324        *guard = Some(make_resize_snapshot(1));
325        *guard = Some(make_resize_snapshot(2));
326        let snap = guard.clone().unwrap();
327        assert_eq!(snap.event_idx, 2);
328        *guard = None;
329    }
330
331    #[test]
332    fn resize_snapshot_clear() {
333        let mut guard = RESIZE_SNAPSHOT
334            .write()
335            .expect("resize snapshot lock poisoned");
336        *guard = Some(make_resize_snapshot(10));
337        *guard = None;
338        assert!(guard.is_none());
339    }
340
341    #[test]
342    fn resize_snapshot_with_bocpd_evidence() {
343        let mut snap = make_resize_snapshot(3);
344        snap.regime = Regime::Burst;
345        snap.bocpd = Some(BocpdEvidence {
346            p_burst: 0.85,
347            log_bayes_factor: 1.5,
348            observation_ms: 15.0,
349            regime: BocpdRegime::Burst,
350            likelihood_steady: 0.001,
351            likelihood_burst: 0.05,
352            expected_run_length: 3.0,
353            run_length_variance: 2.0,
354            run_length_mode: 2,
355            run_length_p95: 8,
356            run_length_tail_mass: 0.01,
357            recommended_delay_ms: Some(20),
358            hard_deadline_forced: None,
359            observation_count: 50,
360            timestamp: web_time::Instant::now(),
361        });
362        let mut guard = RESIZE_SNAPSHOT
363            .write()
364            .expect("resize snapshot lock poisoned");
365        *guard = Some(snap);
366        let retrieved = guard.clone().unwrap();
367        assert_eq!(retrieved.regime, Regime::Burst);
368        let bocpd = retrieved.bocpd.as_ref().unwrap();
369        assert!((bocpd.p_burst - 0.85).abs() < f64::EPSILON);
370        assert_eq!(bocpd.regime, BocpdRegime::Burst);
371        *guard = None;
372    }
373
374    // ── budget snapshot tests ───────────────────────────────────────
375
376    #[test]
377    fn budget_snapshot_clear_then_none() {
378        let mut guard = BUDGET_SNAPSHOT
379            .write()
380            .expect("budget snapshot lock poisoned");
381        *guard = None;
382        assert!(guard.is_none());
383    }
384
385    #[test]
386    fn budget_snapshot_store_and_retrieve() {
387        let snap = make_budget_snapshot(100);
388        let mut guard = BUDGET_SNAPSHOT
389            .write()
390            .expect("budget snapshot lock poisoned");
391        *guard = Some(snap);
392        let retrieved = guard.clone().expect("should be Some");
393        assert_eq!(retrieved.frame_idx, 100);
394        assert_eq!(retrieved.decision, BudgetDecision::Hold);
395        assert_eq!(retrieved.degradation_before, DegradationLevel::Full);
396        assert_eq!(retrieved.frames_observed, 100);
397        *guard = None;
398    }
399
400    #[test]
401    fn budget_snapshot_overwrite() {
402        let mut guard = BUDGET_SNAPSHOT
403            .write()
404            .expect("budget snapshot lock poisoned");
405        *guard = Some(make_budget_snapshot(1));
406        *guard = Some(make_budget_snapshot(2));
407        let snap = guard.clone().unwrap();
408        assert_eq!(snap.frame_idx, 2);
409        *guard = None;
410    }
411
412    #[test]
413    fn budget_snapshot_clear() {
414        let mut guard = BUDGET_SNAPSHOT
415            .write()
416            .expect("budget snapshot lock poisoned");
417        *guard = Some(make_budget_snapshot(10));
418        *guard = None;
419        assert!(guard.is_none());
420    }
421
422    #[test]
423    fn budget_snapshot_with_conformal() {
424        let mut snap = make_budget_snapshot(50);
425        snap.decision = BudgetDecision::Degrade;
426        snap.conformal = Some(ConformalSnapshot {
427            bucket_key: "alt:DirtyRows:medium".into(),
428            sample_count: 30,
429            upper_us: Some(20000.0),
430            risk: true,
431            status: crate::ConformalStatus::Calibrated,
432            required_rank: 30,
433        });
434        let mut guard = BUDGET_SNAPSHOT
435            .write()
436            .expect("budget snapshot lock poisoned");
437        *guard = Some(snap);
438        let retrieved = guard.clone().unwrap();
439        assert_eq!(retrieved.decision, BudgetDecision::Degrade);
440        let conformal = retrieved.conformal.as_ref().unwrap();
441        assert_eq!(conformal.bucket_key, "alt:DirtyRows:medium");
442        assert_eq!(conformal.sample_count, 30);
443        assert!(conformal.risk);
444        *guard = None;
445    }
446
447    #[test]
448    fn budget_snapshot_degradation_levels() {
449        let mut snap = make_budget_snapshot(1);
450        snap.degradation_before = DegradationLevel::Full;
451        snap.degradation_after = DegradationLevel::SimpleBorders;
452        snap.decision = BudgetDecision::Degrade;
453        let mut guard = BUDGET_SNAPSHOT
454            .write()
455            .expect("budget snapshot lock poisoned");
456        *guard = Some(snap);
457        let retrieved = guard.clone().unwrap();
458        assert!(retrieved.degradation_after > retrieved.degradation_before);
459        *guard = None;
460    }
461
462    #[test]
463    fn budget_snapshot_warmup_flag() {
464        let mut snap = make_budget_snapshot(1);
465        snap.in_warmup = true;
466        snap.frames_observed = 5;
467        let mut guard = BUDGET_SNAPSHOT
468            .write()
469            .expect("budget snapshot lock poisoned");
470        *guard = Some(snap);
471        let retrieved = guard.clone().unwrap();
472        assert!(retrieved.in_warmup);
473        assert_eq!(retrieved.frames_observed, 5);
474        *guard = None;
475    }
476
477    // ── set_*_snapshot(None) tests ──────────────────────────────────
478
479    #[test]
480    fn set_diff_none_clears() {
481        let mut guard = DIFF_SNAPSHOT.write().expect("diff snapshot lock poisoned");
482        *guard = Some(make_diff_snapshot(1));
483        *guard = None;
484        assert!(guard.is_none());
485    }
486
487    #[test]
488    fn set_resize_none_clears() {
489        let mut guard = RESIZE_SNAPSHOT
490            .write()
491            .expect("resize snapshot lock poisoned");
492        *guard = Some(make_resize_snapshot(1));
493        *guard = None;
494        assert!(guard.is_none());
495    }
496
497    #[test]
498    fn set_budget_none_clears() {
499        let mut guard = BUDGET_SNAPSHOT
500            .write()
501            .expect("budget snapshot lock poisoned");
502        *guard = Some(make_budget_snapshot(1));
503        *guard = None;
504        assert!(guard.is_none());
505    }
506}