Skip to main content

ftui_runtime/
voi_sampling.rs

1#![forbid(unsafe_code)]
2
3//! Value-of-Information (VOI) Sampling Policy for expensive measurements.
4//!
5//! This module decides **when** to sample costly latency/cost measurements so
6//! overhead stays low while guarantees remain intact.
7//!
8//! # Mathematical Model
9//!
10//! We treat "violation" observations as Bernoulli random variables:
11//!
12//! ```text
13//! X_t ∈ {0,1},  X_t = 1  ⇔  measurement violates SLA threshold
14//! ```
15//!
16//! We maintain a Beta prior/posterior over the violation probability `p`:
17//!
18//! ```text
19//! p ~ Beta(α, β)
20//! α ← α + X_t
21//! β ← β + (1 − X_t)
22//! ```
23//!
24//! The posterior variance is:
25//!
26//! ```text
27//! Var[p] = αβ / ((α+β)^2 (α+β+1))
28//! ```
29//!
30//! ## Expected VOI (Variance Reduction)
31//!
32//! The expected variance **after one more sample** is:
33//!
34//! ```text
35//! E[Var[p] | one sample] =
36//!   p̂ · Var[Beta(α+1,β)] + (1−p̂) · Var[Beta(α,β+1)]
37//! ```
38//!
39//! where `p̂ = α / (α+β)` is the posterior mean.
40//!
41//! The **value of information** (VOI) is the expected reduction, which simplifies
42//! algebraically to:
43//!
44//! ```text
45//! VOI(α, β) = Var[p] − E[Var[p] | one sample]
46//!           = αβ / ((α+β)^2 (α+β+1)^2)  ≥ 0
47//!           ≤ 1 / (4 (α+β+1)^2)
48//! ```
49//!
50//! For example, under a uniform `Beta(1, 1)` prior:
51//! - `Var[Beta(1, 1)] = 1/12`
52//! - `Var[Beta(2, 1)] = Var[Beta(1, 2)] = 1/18`
53//! - `E[Var[p] | one sample] = (1/2)(1/18) + (1/2)(1/18) = 1/18`
54//! - `VOI(1, 1) = 1/12 − 1/18 = 1/36`
55//!
56//! ## E-Process Boundary-Proximity Layer (Conditional Supermartingale vs. Clamped Heuristic)
57//!
58//! We track a multiplicative wealth accumulator over the sampled Bernoulli stream:
59//!
60//! ```text
61//! W_0 = 1
62//! W_t = clamp(W_{t-1} × max(1 + λ (X_t − μ₀), EPS), E_MIN, E_MAX)
63//! ```
64//!
65//! where `μ₀` is the baseline violation rate under $H_0$ and $\lambda$ is a betting
66//! fraction clamped to `(LAMBDA_EPS, 1/(1 − μ₀) − LAMBDA_EPS)`.
67//!
68//! - **Exact conditional supermartingale domain**: Because `decide` depends only on
69//!   $\mathcal{F}_{t-1}$ (past observations), when $\lambda \in (0, 1/\mu_0)$ (so
70//!   $1 - \lambda \mu_0 > 0$ on $X_t = 0$) and the trajectory stays strictly inside
71//!   $(E_{\min}, E_{\max})$, $E[W_t \mid \mathcal{F}_{t-1}] \le W_{t-1}$ under the
72//!   conditional null $P(X_t = 1 \mid \mathcal{F}_{t-1}) \le \mu_0$, preserving Ville's
73//!   inequality $P(\exists t: W_t \ge 1/\alpha \mid H_0) \le \alpha$ under adaptive sampling.
74//! - **Heuristic floor/clamp boundary**: When $\lambda \ge 1/\mu_0$ (possible if $\mu_0 > 0.5$)
75//!   or when sustained non-violations drive $W_t$ down to `E_MIN = 1e-12`, the lower floors
76//!   (`max(..., EPS)` and `clamp(E_MIN, E_MAX)`) prevent permanent zero-lock at the cost of
77//!   injecting upward bias on the boundary; in that regime `W_t` acts as a bounded heuristic
78//!   proximity weight for `boundary_score` rather than a formal α-test.
79//!
80//! ## Decision Rule (Explainable)
81//!
82//! We compute a scalar **score**:
83//!
84//! ```text
85//! score = VOI × value_scale × (1 + boundary_weight × boundary_score)
86//! boundary_score = 1 / (1 + |log W − log W*|)
87//! ```
88//!
89//! where `W* = 1/α` is the e-value threshold.
90//!
91//! Then:
92//! 1) If `max_interval` exceeded ⇒ **sample** (forced).
93//! 2) If `min_interval` not met ⇒ **skip** (guard).
94//! 3) Else **sample** iff `score ≥ cost`.
95//!
96//! This yields a deterministic, explainable policy that preferentially samples
97//! when uncertainty is high **and** evidence is near the decision boundary.
98//!
99//! # Perf JSONL Schema
100//!
101//! The microbench emits JSONL lines per decision:
102//!
103//! ```text
104//! {"test":"voi_sampling","case":"decision","idx":N,"elapsed_ns":N,"sample":true,"violated":false,"e_value":1.23}
105//! ```
106//!
107//! # Key Invariants
108//!
109//! 1. **Deterministic**: same inputs → same decisions.
110//! 2. **VOI non-negative**: expected variance reduction $\alpha\beta / (n^2(n+1)^2) \ge 0$.
111//! 3. **Predictable adaptive sampling**: sampling decisions are $\mathcal{F}_{t-1}$-measurable;
112//!    $W_t$ is a supermartingale under $P(X_t=1\mid\mathcal{F}_{t-1})\le\mu_0$ when $\lambda < 1/\mu_0$
113//!    and unclamped in $(E_{\min}, E_{\max})$.
114//! 4. **Bounded silence**: max-interval forces periodic sampling.
115//!
116//! # Failure Modes
117//!
118//! | Condition | Behavior | Rationale |
119//! |-----------|----------|-----------|
120//! | α,β ≤ 0 | Clamp to ε | Avoid invalid Beta |
121//! | μ₀ ≤ 0 or ≥ 1 | Clamp to (ε, 1−ε) | Avoid degenerate e-process |
122//! | λ out of range | Clamp to valid range | Prevent negative wealth |
123//! | cost ≤ 0 | Clamp to ε | Avoid divide-by-zero in evidence |
124//! | max_interval = 0 | Disabled | Explicit opt-out |
125//!
126//! # Usage
127//!
128//! ```ignore
129//! use ftui_runtime::voi_sampling::{VoiConfig, VoiSampler};
130//! use std::time::Instant;
131//!
132//! let mut sampler = VoiSampler::new(VoiConfig::default());
133//! let decision = sampler.decide(Instant::now());
134//! if decision.should_sample {
135//!     let violated = false; // measure and evaluate
136//!     sampler.observe(violated);
137//! }
138//! ```
139
140use std::collections::{BTreeMap, VecDeque};
141use std::sync::atomic::{AtomicU64, Ordering};
142use web_time::{Duration, Instant};
143
144const EPS: f64 = 1e-12;
145const MU_0_MIN: f64 = 1e-6;
146const MU_0_MAX: f64 = 1.0 - 1e-6;
147const LAMBDA_EPS: f64 = 1e-9;
148const E_MIN: f64 = 1e-12;
149const E_MAX: f64 = 1e12;
150const VAR_MAX: f64 = 0.25; // Max Beta variance as α,β → 0
151
152// ---------------------------------------------------------------------------
153// Monotonic counters (exported for observability dashboards / tests)
154// ---------------------------------------------------------------------------
155
156static VOI_SAMPLES_TAKEN_TOTAL: AtomicU64 = AtomicU64::new(0);
157static VOI_SAMPLES_SKIPPED_TOTAL: AtomicU64 = AtomicU64::new(0);
158
159/// Total VOI samples taken (monotonic counter for metrics export).
160#[must_use]
161pub fn voi_samples_taken_total() -> u64 {
162    VOI_SAMPLES_TAKEN_TOTAL.load(Ordering::Relaxed)
163}
164
165/// Total VOI samples skipped (monotonic counter for metrics export).
166#[must_use]
167pub fn voi_samples_skipped_total() -> u64 {
168    VOI_SAMPLES_SKIPPED_TOTAL.load(Ordering::Relaxed)
169}
170
171/// Configuration for the VOI sampling policy.
172#[derive(Debug, Clone)]
173pub struct VoiConfig {
174    /// Significance level α for the e-process threshold (W* = 1/α).
175    /// Default: 0.05.
176    pub alpha: f64,
177
178    /// Beta prior α for violation probability. Default: 1.0.
179    pub prior_alpha: f64,
180
181    /// Beta prior β for violation probability. Default: 1.0.
182    pub prior_beta: f64,
183
184    /// Baseline violation rate μ₀ under H₀. Default: 0.05.
185    pub mu_0: f64,
186
187    /// E-process betting fraction λ. Default: 0.5 (clamped).
188    pub lambda: f64,
189
190    /// Value scaling factor for VOI. Default: 1.0.
191    pub value_scale: f64,
192
193    /// Weight for boundary proximity. Default: 1.0.
194    pub boundary_weight: f64,
195
196    /// Sampling cost (in normalized units). Default: 0.01.
197    pub sample_cost: f64,
198
199    /// Minimum interval between samples (ms). Default: 0.
200    pub min_interval_ms: u64,
201
202    /// Maximum interval between samples (ms). 0 disables time forcing.
203    /// Default: 250.
204    pub max_interval_ms: u64,
205
206    /// Minimum events between samples. Default: 0.
207    pub min_interval_events: u64,
208
209    /// Maximum events between samples. 0 disables event forcing.
210    /// Default: 20.
211    pub max_interval_events: u64,
212
213    /// Enable JSONL-compatible logging.
214    pub enable_logging: bool,
215
216    /// Maximum log entries to retain.
217    pub max_log_entries: usize,
218}
219
220impl Default for VoiConfig {
221    fn default() -> Self {
222        Self {
223            alpha: 0.05,
224            prior_alpha: 1.0,
225            prior_beta: 1.0,
226            mu_0: 0.05,
227            lambda: 0.5,
228            value_scale: 1.0,
229            boundary_weight: 1.0,
230            sample_cost: 0.01,
231            min_interval_ms: 0,
232            max_interval_ms: 250,
233            min_interval_events: 0,
234            max_interval_events: 20,
235            enable_logging: false,
236            max_log_entries: 2048,
237        }
238    }
239}
240
241/// Sampling decision with full evidence.
242#[derive(Debug, Clone)]
243pub struct VoiDecision {
244    pub event_idx: u64,
245    pub should_sample: bool,
246    pub forced_by_interval: bool,
247    pub blocked_by_min_interval: bool,
248    pub voi_gain: f64,
249    pub score: f64,
250    pub cost: f64,
251    pub log_bayes_factor: f64,
252    pub posterior_mean: f64,
253    pub posterior_variance: f64,
254    pub e_value: f64,
255    pub e_threshold: f64,
256    pub boundary_score: f64,
257    pub events_since_sample: u64,
258    pub time_since_sample_ms: f64,
259    pub reason: &'static str,
260}
261
262impl VoiDecision {
263    /// Serialize decision to JSONL.
264    #[must_use]
265    pub fn to_jsonl(&self) -> String {
266        format!(
267            r#"{{"schema_version":"ftui-evidence-v1","event":"voi_decision","idx":{},"should_sample":{},"forced":{},"blocked":{},"voi_gain":{:.6},"score":{:.6},"cost":{:.6},"log_bayes_factor":{:.4},"posterior_mean":{:.6},"posterior_variance":{:.6},"e_value":{:.6},"e_threshold":{:.6},"boundary_score":{:.6},"events_since_sample":{},"time_since_sample_ms":{:.3},"reason":"{}"}}"#,
268            self.event_idx,
269            self.should_sample,
270            self.forced_by_interval,
271            self.blocked_by_min_interval,
272            self.voi_gain,
273            self.score,
274            self.cost,
275            self.log_bayes_factor,
276            self.posterior_mean,
277            self.posterior_variance,
278            self.e_value,
279            self.e_threshold,
280            self.boundary_score,
281            self.events_since_sample,
282            self.time_since_sample_ms,
283            self.reason
284        )
285    }
286}
287
288/// Observation result after a sample is taken.
289#[derive(Debug, Clone)]
290pub struct VoiObservation {
291    pub event_idx: u64,
292    pub sample_idx: u64,
293    pub violated: bool,
294    pub posterior_mean: f64,
295    pub posterior_variance: f64,
296    pub alpha: f64,
297    pub beta: f64,
298    pub e_value: f64,
299    pub e_threshold: f64,
300}
301
302impl VoiObservation {
303    /// Serialize observation to JSONL.
304    #[must_use]
305    pub fn to_jsonl(&self) -> String {
306        format!(
307            r#"{{"schema_version":"ftui-evidence-v1","event":"voi_observe","idx":{},"sample_idx":{},"violated":{},"posterior_mean":{:.6},"posterior_variance":{:.6},"alpha":{:.3},"beta":{:.3},"e_value":{:.6},"e_threshold":{:.6}}}"#,
308            self.event_idx,
309            self.sample_idx,
310            self.violated,
311            self.posterior_mean,
312            self.posterior_variance,
313            self.alpha,
314            self.beta,
315            self.e_value,
316            self.e_threshold
317        )
318    }
319}
320
321/// Log entry for VOI sampling.
322#[derive(Debug, Clone)]
323pub enum VoiLogEntry {
324    Decision(VoiDecision),
325    Observation(VoiObservation),
326}
327
328impl VoiLogEntry {
329    /// Serialize log entry to JSONL.
330    #[must_use]
331    pub fn to_jsonl(&self) -> String {
332        match self {
333            Self::Decision(decision) => decision.to_jsonl(),
334            Self::Observation(obs) => obs.to_jsonl(),
335        }
336    }
337}
338
339/// Summary statistics for VOI sampling.
340#[derive(Debug, Clone)]
341pub struct VoiSummary {
342    pub total_events: u64,
343    pub total_samples: u64,
344    pub forced_samples: u64,
345    pub skipped_events: u64,
346    pub current_mean: f64,
347    pub current_variance: f64,
348    pub e_value: f64,
349    pub e_threshold: f64,
350    pub avg_events_between_samples: f64,
351    pub avg_ms_between_samples: f64,
352}
353
354/// Snapshot of VOI sampler state for debug overlays.
355#[derive(Debug, Clone)]
356pub struct VoiSamplerSnapshot {
357    pub captured_ms: u64,
358    pub alpha: f64,
359    pub beta: f64,
360    pub posterior_mean: f64,
361    pub posterior_variance: f64,
362    pub expected_variance_after: f64,
363    pub voi_gain: f64,
364    pub last_decision: Option<VoiDecision>,
365    pub last_observation: Option<VoiObservation>,
366    pub recent_logs: Vec<VoiLogEntry>,
367}
368
369/// VOI-driven sampler with Beta-Bernoulli posterior and e-process control.
370#[derive(Debug, Clone)]
371pub struct VoiSampler {
372    config: VoiConfig,
373    alpha: f64,
374    beta: f64,
375    mu_0: f64,
376    lambda: f64,
377    e_value: f64,
378    e_threshold: f64,
379    event_idx: u64,
380    sample_idx: u64,
381    forced_samples: u64,
382    last_sample_event: u64,
383    last_sample_time: Instant,
384    start_time: Instant,
385    last_decision_forced: bool,
386    logs: VecDeque<VoiLogEntry>,
387    last_decision: Option<VoiDecision>,
388    last_observation: Option<VoiObservation>,
389}
390
391impl VoiSampler {
392    /// Create a new VOI sampler with given config.
393    pub fn new(config: VoiConfig) -> Self {
394        Self::new_at(config, Instant::now())
395    }
396
397    /// Create a new VOI sampler at a specific time (for deterministic tests).
398    pub fn new_at(config: VoiConfig, now: Instant) -> Self {
399        let mut cfg = config;
400
401        let prior_alpha = if cfg.prior_alpha.is_nan() {
402            EPS
403        } else {
404            cfg.prior_alpha.max(EPS)
405        };
406        let prior_beta = if cfg.prior_beta.is_nan() {
407            EPS
408        } else {
409            cfg.prior_beta.max(EPS)
410        };
411        let mu_0 = if cfg.mu_0.is_nan() {
412            0.5
413        } else {
414            cfg.mu_0.clamp(MU_0_MIN, MU_0_MAX)
415        };
416        let lambda_max = (1.0 / (1.0 - mu_0)) - LAMBDA_EPS;
417        let lambda = if cfg.lambda.is_nan() {
418            LAMBDA_EPS
419        } else {
420            cfg.lambda.clamp(LAMBDA_EPS, lambda_max)
421        };
422
423        cfg.value_scale = if cfg.value_scale.is_nan() {
424            EPS
425        } else {
426            cfg.value_scale.max(EPS)
427        };
428        cfg.boundary_weight = if cfg.boundary_weight.is_nan() {
429            0.0
430        } else {
431            cfg.boundary_weight.max(0.0)
432        };
433        cfg.sample_cost = if cfg.sample_cost.is_nan() {
434            EPS
435        } else {
436            cfg.sample_cost.max(EPS)
437        };
438        cfg.max_log_entries = cfg.max_log_entries.max(1);
439
440        let e_threshold = 1.0 / cfg.alpha.max(EPS);
441
442        Self {
443            config: cfg,
444            alpha: prior_alpha,
445            beta: prior_beta,
446            mu_0,
447            lambda,
448            e_value: 1.0,
449            e_threshold,
450            event_idx: 0,
451            sample_idx: 0,
452            forced_samples: 0,
453            last_sample_event: 0,
454            last_sample_time: now,
455            start_time: now,
456            last_decision_forced: false,
457            logs: VecDeque::new(),
458            last_decision: None,
459            last_observation: None,
460        }
461    }
462
463    /// Access the sampler configuration.
464    #[must_use]
465    pub fn config(&self) -> &VoiConfig {
466        &self.config
467    }
468
469    /// Current posterior parameters (alpha, beta).
470    #[must_use]
471    pub fn posterior_params(&self) -> (f64, f64) {
472        (self.alpha, self.beta)
473    }
474
475    /// Current posterior mean.
476    #[must_use]
477    pub fn posterior_mean(&self) -> f64 {
478        beta_mean(self.alpha, self.beta)
479    }
480
481    /// Current posterior variance.
482    #[must_use]
483    pub fn posterior_variance(&self) -> f64 {
484        beta_variance(self.alpha, self.beta)
485    }
486
487    /// Expected posterior variance after one additional sample.
488    #[must_use]
489    pub fn expected_variance_after(&self) -> f64 {
490        expected_variance_after(self.alpha, self.beta)
491    }
492
493    /// Expected variance reduction (Value of Information) from one sample.
494    #[must_use]
495    pub fn value_of_information(&self) -> f64 {
496        ftui_core::voi::beta_voi(self.alpha, self.beta)
497    }
498
499    /// Most recent decision, if any.
500    #[must_use]
501    pub fn last_decision(&self) -> Option<&VoiDecision> {
502        self.last_decision.as_ref()
503    }
504
505    /// Most recent observation, if any.
506    #[must_use]
507    pub fn last_observation(&self) -> Option<&VoiObservation> {
508        self.last_observation.as_ref()
509    }
510
511    /// Decide whether to sample at time `now`.
512    pub fn decide(&mut self, now: Instant) -> VoiDecision {
513        self.event_idx += 1;
514
515        let events_since_sample = if self.sample_idx == 0 {
516            self.event_idx
517        } else {
518            self.event_idx.saturating_sub(self.last_sample_event)
519        };
520        let time_since_sample = if now >= self.last_sample_time {
521            now.saturating_duration_since(self.last_sample_time)
522        } else {
523            Duration::ZERO
524        };
525
526        let forced_by_events = self.config.max_interval_events > 0
527            && events_since_sample >= self.config.max_interval_events;
528        let forced_by_time = self.config.max_interval_ms > 0
529            && time_since_sample >= Duration::from_millis(self.config.max_interval_ms);
530        let forced = forced_by_events || forced_by_time;
531
532        let blocked_by_events = self.sample_idx > 0
533            && self.config.min_interval_events > 0
534            && events_since_sample < self.config.min_interval_events;
535        let blocked_by_time = self.sample_idx > 0
536            && self.config.min_interval_ms > 0
537            && time_since_sample < Duration::from_millis(self.config.min_interval_ms);
538        let blocked = blocked_by_events || blocked_by_time;
539
540        let variance = beta_variance(self.alpha, self.beta);
541        let voi_gain = ftui_core::voi::beta_voi(self.alpha, self.beta);
542
543        let boundary_score = boundary_score(self.e_value, self.e_threshold);
544        let score = voi_gain
545            * self.config.value_scale
546            * (1.0 + self.config.boundary_weight * boundary_score);
547        let cost = self.config.sample_cost;
548        let log_bayes_factor = log10_ratio(score, cost);
549
550        let should_sample = if forced {
551            true
552        } else if blocked {
553            false
554        } else {
555            score >= cost
556        };
557
558        let reason = if forced {
559            "forced_interval"
560        } else if blocked {
561            "min_interval"
562        } else if should_sample {
563            "voi_ge_cost"
564        } else {
565            "voi_lt_cost"
566        };
567
568        let decision = VoiDecision {
569            event_idx: self.event_idx,
570            should_sample,
571            forced_by_interval: forced,
572            blocked_by_min_interval: blocked,
573            voi_gain,
574            score,
575            cost,
576            log_bayes_factor,
577            posterior_mean: beta_mean(self.alpha, self.beta),
578            posterior_variance: variance,
579            e_value: self.e_value,
580            e_threshold: self.e_threshold,
581            boundary_score,
582            events_since_sample,
583            time_since_sample_ms: time_since_sample.as_secs_f64() * 1000.0,
584            reason,
585        };
586
587        self.last_decision = Some(decision.clone());
588        self.last_decision_forced = forced;
589
590        // --- Tracing observability (bd-37a.4) ---
591        let _span = tracing::debug_span!(
592            "voi.evaluate",
593            decision_context = %reason,
594            voi_estimate = %voi_gain,
595            sample_cost = %cost,
596            sample_decision = should_sample,
597        )
598        .entered();
599
600        tracing::debug!(
601            target: crate::telemetry_schema::TARGET_VOI,
602            voi_gain = %voi_gain,
603            score = %score,
604            cost = %cost,
605            log_bayes_factor = %log_bayes_factor,
606            posterior_mean = %decision.posterior_mean,
607            posterior_variance = %variance,
608            boundary_score = %boundary_score,
609            e_value = %self.e_value,
610            reason = %reason,
611            event_idx = self.event_idx,
612            "voi calculation"
613        );
614
615        tracing::debug!(
616            target: crate::telemetry_schema::TARGET_VOI,
617            voi_estimate_value = %voi_gain,
618            "voi estimate histogram"
619        );
620
621        if should_sample {
622            VOI_SAMPLES_TAKEN_TOTAL.fetch_add(1, Ordering::Relaxed);
623        } else {
624            VOI_SAMPLES_SKIPPED_TOTAL.fetch_add(1, Ordering::Relaxed);
625        }
626
627        if self.config.enable_logging {
628            self.push_log(VoiLogEntry::Decision(decision.clone()));
629        }
630
631        decision
632    }
633
634    /// Record a sampled observation at time `now`.
635    pub fn observe_at(&mut self, violated: bool, now: Instant) -> VoiObservation {
636        self.sample_idx += 1;
637        self.last_sample_event = self.event_idx;
638        self.last_sample_time = now;
639        if self.last_decision_forced {
640            self.forced_samples += 1;
641        }
642
643        if violated {
644            self.alpha += 1.0;
645        } else {
646            self.beta += 1.0;
647        }
648
649        self.update_eprocess(violated);
650
651        let obs_posterior_mean = beta_mean(self.alpha, self.beta);
652        let obs_posterior_variance = beta_variance(self.alpha, self.beta);
653        let obs_voi_estimate =
654            (obs_posterior_variance - expected_variance_after(self.alpha, self.beta)).max(0.0);
655
656        let observation = VoiObservation {
657            event_idx: self.event_idx,
658            sample_idx: self.sample_idx,
659            violated,
660            posterior_mean: obs_posterior_mean,
661            posterior_variance: obs_posterior_variance,
662            alpha: self.alpha,
663            beta: self.beta,
664            e_value: self.e_value,
665            e_threshold: self.e_threshold,
666        };
667
668        // --- TRACE: individual utility estimate after observation ---
669        tracing::trace!(
670            target: crate::telemetry_schema::TARGET_VOI,
671            violated = violated,
672            alpha = %self.alpha,
673            beta = %self.beta,
674            posterior_mean = %obs_posterior_mean,
675            posterior_variance = %obs_posterior_variance,
676            e_value = %self.e_value,
677            voi_estimate_value = %obs_voi_estimate,
678            sample_idx = self.sample_idx,
679            "utility estimate after observation"
680        );
681
682        self.last_observation = Some(observation.clone());
683        if self.config.enable_logging {
684            self.push_log(VoiLogEntry::Observation(observation.clone()));
685        }
686
687        observation
688    }
689
690    /// Record a sampled observation using `Instant::now()`.
691    pub fn observe(&mut self, violated: bool) -> VoiObservation {
692        self.observe_at(violated, Instant::now())
693    }
694
695    /// Current summary statistics.
696    #[must_use]
697    pub fn summary(&self) -> VoiSummary {
698        let skipped_events = self.event_idx.saturating_sub(self.sample_idx);
699        let avg_events_between_samples = if self.sample_idx > 0 {
700            self.event_idx as f64 / self.sample_idx as f64
701        } else {
702            0.0
703        };
704        let elapsed_ms = self.start_time.elapsed().as_secs_f64() * 1000.0;
705        let avg_ms_between_samples = if self.sample_idx > 0 {
706            elapsed_ms / self.sample_idx as f64
707        } else {
708            0.0
709        };
710
711        VoiSummary {
712            total_events: self.event_idx,
713            total_samples: self.sample_idx,
714            forced_samples: self.forced_samples,
715            skipped_events,
716            current_mean: beta_mean(self.alpha, self.beta),
717            current_variance: beta_variance(self.alpha, self.beta),
718            e_value: self.e_value,
719            e_threshold: self.e_threshold,
720            avg_events_between_samples,
721            avg_ms_between_samples,
722        }
723    }
724
725    /// Access current logs.
726    #[must_use]
727    pub fn logs(&self) -> &VecDeque<VoiLogEntry> {
728        &self.logs
729    }
730
731    /// Render logs as JSONL.
732    #[must_use]
733    pub fn logs_to_jsonl(&self) -> String {
734        self.logs
735            .iter()
736            .map(VoiLogEntry::to_jsonl)
737            .collect::<Vec<_>>()
738            .join("\n")
739    }
740
741    /// Create a snapshot of the sampler state for debug overlays.
742    #[must_use]
743    pub fn snapshot(&self, max_logs: usize, captured_ms: u64) -> VoiSamplerSnapshot {
744        let expected_after = expected_variance_after(self.alpha, self.beta);
745        let variance = beta_variance(self.alpha, self.beta);
746        let voi_gain = (variance - expected_after).max(0.0);
747        let mut recent_logs: Vec<VoiLogEntry> = self
748            .logs
749            .iter()
750            .rev()
751            .take(max_logs.max(1))
752            .cloned()
753            .collect();
754        recent_logs.reverse();
755
756        VoiSamplerSnapshot {
757            captured_ms,
758            alpha: self.alpha,
759            beta: self.beta,
760            posterior_mean: beta_mean(self.alpha, self.beta),
761            posterior_variance: variance,
762            expected_variance_after: expected_after,
763            voi_gain,
764            last_decision: self.last_decision.clone(),
765            last_observation: self.last_observation.clone(),
766            recent_logs,
767        }
768    }
769
770    fn push_log(&mut self, entry: VoiLogEntry) {
771        if self.logs.len() >= self.config.max_log_entries {
772            self.logs.pop_front();
773        }
774        self.logs.push_back(entry);
775    }
776
777    fn update_eprocess(&mut self, violated: bool) {
778        let x = if violated { 1.0 } else { 0.0 };
779        let factor = 1.0 + self.lambda * (x - self.mu_0);
780        let next = self.e_value * factor.max(EPS);
781        self.e_value = next.clamp(E_MIN, E_MAX);
782    }
783
784    /// Increment forced sample counter (for testing/integration).
785    pub fn mark_forced_sample(&mut self) {
786        self.forced_samples += 1;
787    }
788}
789
790fn beta_mean(alpha: f64, beta: f64) -> f64 {
791    ftui_core::voi::beta_mean(alpha, beta)
792}
793
794fn beta_variance(alpha: f64, beta: f64) -> f64 {
795    ftui_core::voi::beta_variance(alpha, beta).min(VAR_MAX)
796}
797
798fn expected_variance_after(alpha: f64, beta: f64) -> f64 {
799    ftui_core::voi::expected_variance_after(alpha, beta)
800}
801
802fn boundary_score(e_value: f64, threshold: f64) -> f64 {
803    let e = e_value.max(EPS);
804    let t = threshold.max(EPS);
805    let gap = (e.ln() - t.ln()).abs();
806    1.0 / (1.0 + gap)
807}
808
809fn log10_ratio(score: f64, cost: f64) -> f64 {
810    let ratio = (score + EPS) / (cost + EPS);
811    ratio.ln() / std::f64::consts::LN_10
812}
813
814// =============================================================================
815// Deferred refinement scheduler (bd-2vr05.15.4.4)
816// =============================================================================
817
818/// Configuration for VOI-guided deferred refinement scheduling.
819///
820/// This scheduler only allocates work from spare frame budget and uses a
821/// deterministic VOI score with fairness boosts to avoid starvation.
822#[derive(Debug, Clone, PartialEq)]
823pub struct DeferredRefinementConfig {
824    /// Minimum spare budget to keep reserved for non-optional work.
825    pub min_spare_budget_us: u64,
826    /// Hard cap on optional refinements scheduled per frame.
827    pub max_refinements_per_frame: usize,
828    /// Minimum effective VOI required to schedule a refinement.
829    pub voi_gain_cutoff: f64,
830    /// Fairness boost added per skipped frame for a region.
831    pub fairness_boost_per_skip: f64,
832    /// Maximum fairness boost for a region.
833    pub fairness_boost_cap: f64,
834}
835
836impl Default for DeferredRefinementConfig {
837    fn default() -> Self {
838        Self {
839            min_spare_budget_us: 500,
840            max_refinements_per_frame: 2,
841            voi_gain_cutoff: 0.01,
842            fairness_boost_per_skip: 0.02,
843            fairness_boost_cap: 1.0,
844        }
845    }
846}
847
848/// Candidate optional refinement unit for a region/paragraph bucket.
849#[derive(Debug, Clone, Copy, PartialEq)]
850pub struct RefinementCandidate {
851    /// Deterministic region identifier.
852    pub region_id: u64,
853    /// Estimated runtime cost for this refinement.
854    pub estimated_cost_us: u64,
855    /// Predicted value-of-information gain (higher is better).
856    pub voi_gain: f64,
857}
858
859/// Selected refinement with explainable scoring terms.
860#[derive(Debug, Clone, Copy, PartialEq)]
861pub struct RefinementSelection {
862    pub region_id: u64,
863    pub estimated_cost_us: u64,
864    pub voi_gain: f64,
865    pub fairness_boost: f64,
866    pub effective_voi: f64,
867    pub score: f64,
868}
869
870/// Frame-level refinement plan.
871#[derive(Debug, Clone, PartialEq)]
872pub struct DeferredRefinementPlan {
873    pub frame_budget_us: u64,
874    pub mandatory_work_us: u64,
875    pub reserved_spare_us: u64,
876    pub optional_budget_us: u64,
877    pub spent_optional_us: u64,
878    pub selected: Vec<RefinementSelection>,
879}
880
881impl DeferredRefinementPlan {
882    /// Hard budget predicate for CI assertions.
883    #[must_use]
884    pub fn hard_budget_respected(&self) -> bool {
885        self.mandatory_work_us
886            .saturating_add(self.reserved_spare_us)
887            .saturating_add(self.spent_optional_us)
888            <= self.frame_budget_us
889    }
890}
891
892/// Deterministic VOI-guided scheduler for optional deferred refinements.
893#[derive(Debug, Clone)]
894pub struct DeferredRefinementScheduler {
895    config: DeferredRefinementConfig,
896    skipped_frames: BTreeMap<u64, u32>,
897}
898
899impl DeferredRefinementScheduler {
900    /// Create a scheduler from explicit config.
901    #[must_use]
902    pub fn new(config: DeferredRefinementConfig) -> Self {
903        Self {
904            config,
905            skipped_frames: BTreeMap::new(),
906        }
907    }
908
909    /// Access scheduler config.
910    #[must_use]
911    pub fn config(&self) -> &DeferredRefinementConfig {
912        &self.config
913    }
914
915    /// Number of consecutive frames this region has been skipped.
916    #[must_use]
917    pub fn skipped_frames_for(&self, region_id: u64) -> u32 {
918        self.skipped_frames.get(&region_id).copied().unwrap_or(0)
919    }
920
921    /// Compute a deterministic frame plan under a hard budget cap.
922    ///
923    /// - `frame_budget_us`: total frame budget.
924    /// - `mandatory_work_us`: non-optional cost already committed.
925    /// - `candidates`: optional refinements for this frame.
926    pub fn plan_frame(
927        &mut self,
928        frame_budget_us: u64,
929        mandatory_work_us: u64,
930        candidates: &[RefinementCandidate],
931    ) -> DeferredRefinementPlan {
932        let reserved_spare_us = self.config.min_spare_budget_us;
933        let available_after_mandatory = frame_budget_us.saturating_sub(mandatory_work_us);
934        let optional_budget_us = available_after_mandatory.saturating_sub(reserved_spare_us);
935
936        let mut scored = Vec::with_capacity(candidates.len());
937        for candidate in candidates.iter().copied() {
938            let skip_count = self.skipped_frames_for(candidate.region_id);
939            let fairness_boost = (skip_count as f64 * self.config.fairness_boost_per_skip)
940                .min(self.config.fairness_boost_cap);
941            let voi_gain = if candidate.voi_gain.is_finite() {
942                candidate.voi_gain.max(0.0)
943            } else {
944                0.0
945            };
946            let effective_voi = voi_gain + fairness_boost;
947            let normalized_cost = candidate.estimated_cost_us.max(1) as f64;
948            let score = effective_voi / normalized_cost;
949            scored.push((
950                candidate,
951                fairness_boost,
952                effective_voi,
953                score,
954                candidate.region_id,
955            ));
956        }
957
958        // Deterministic ordering:
959        // 1) score DESC, 2) effective_voi DESC, 3) region_id ASC.
960        scored.sort_by(|a, b| {
961            b.3.total_cmp(&a.3)
962                .then_with(|| b.2.total_cmp(&a.2))
963                .then_with(|| a.4.cmp(&b.4))
964        });
965
966        let mut remaining_optional_us = optional_budget_us;
967        let mut selected = Vec::with_capacity(self.config.max_refinements_per_frame);
968        let mut selected_ids = BTreeMap::<u64, ()>::new();
969
970        for (candidate, fairness_boost, effective_voi, score, _) in scored {
971            if selected.len() >= self.config.max_refinements_per_frame {
972                break;
973            }
974            if effective_voi < self.config.voi_gain_cutoff {
975                continue;
976            }
977            if candidate.estimated_cost_us > remaining_optional_us {
978                continue;
979            }
980            selected.push(RefinementSelection {
981                region_id: candidate.region_id,
982                estimated_cost_us: candidate.estimated_cost_us,
983                voi_gain: if candidate.voi_gain.is_finite() {
984                    candidate.voi_gain.max(0.0)
985                } else {
986                    0.0
987                },
988                fairness_boost,
989                effective_voi,
990                score,
991            });
992            selected_ids.insert(candidate.region_id, ());
993            remaining_optional_us =
994                remaining_optional_us.saturating_sub(candidate.estimated_cost_us);
995        }
996
997        // Update fairness accounting for all regions visible this frame.
998        for candidate in candidates {
999            if selected_ids.contains_key(&candidate.region_id) {
1000                self.skipped_frames.insert(candidate.region_id, 0);
1001            } else {
1002                let next = self
1003                    .skipped_frames_for(candidate.region_id)
1004                    .saturating_add(1);
1005                self.skipped_frames.insert(candidate.region_id, next);
1006            }
1007        }
1008
1009        let spent_optional_us = optional_budget_us.saturating_sub(remaining_optional_us);
1010        let plan = DeferredRefinementPlan {
1011            frame_budget_us,
1012            mandatory_work_us,
1013            reserved_spare_us,
1014            optional_budget_us,
1015            spent_optional_us,
1016            selected,
1017        };
1018
1019        debug_assert!(plan.hard_budget_respected());
1020        plan
1021    }
1022}
1023
1024// =============================================================================
1025// Tests
1026// =============================================================================
1027
1028#[cfg(test)]
1029mod tests {
1030    use super::*;
1031    use proptest::prelude::*;
1032    use std::collections::HashMap;
1033    use std::sync::{Arc, Mutex};
1034    use tracing_subscriber::layer::SubscriberExt;
1035    use tracing_subscriber::registry::LookupSpan;
1036
1037    const FNV_OFFSET_BASIS: u64 = 0xcbf29ce484222325;
1038    const FNV_PRIME: u64 = 0x100000001b3;
1039
1040    fn hash_bytes(hash: &mut u64, bytes: &[u8]) {
1041        for byte in bytes {
1042            *hash ^= *byte as u64;
1043            *hash = hash.wrapping_mul(FNV_PRIME);
1044        }
1045    }
1046
1047    fn hash_u64(hash: &mut u64, value: u64) {
1048        hash_bytes(hash, &value.to_le_bytes());
1049    }
1050
1051    fn hash_f64(hash: &mut u64, value: f64) {
1052        hash_u64(hash, value.to_bits());
1053    }
1054
1055    fn decision_checksum(decisions: &[VoiDecision]) -> u64 {
1056        let mut hash = FNV_OFFSET_BASIS;
1057        for decision in decisions {
1058            hash_u64(&mut hash, decision.event_idx);
1059            hash_u64(&mut hash, decision.should_sample as u64);
1060            hash_u64(&mut hash, decision.forced_by_interval as u64);
1061            hash_u64(&mut hash, decision.blocked_by_min_interval as u64);
1062            hash_f64(&mut hash, decision.voi_gain);
1063            hash_f64(&mut hash, decision.score);
1064            hash_f64(&mut hash, decision.cost);
1065            hash_f64(&mut hash, decision.log_bayes_factor);
1066            hash_f64(&mut hash, decision.posterior_mean);
1067            hash_f64(&mut hash, decision.posterior_variance);
1068            hash_f64(&mut hash, decision.e_value);
1069            hash_f64(&mut hash, decision.e_threshold);
1070            hash_f64(&mut hash, decision.boundary_score);
1071            hash_u64(&mut hash, decision.events_since_sample);
1072            hash_f64(&mut hash, decision.time_since_sample_ms);
1073        }
1074        hash
1075    }
1076
1077    #[test]
1078    fn voi_gain_non_negative() {
1079        let mut sampler = VoiSampler::new(VoiConfig::default());
1080        let decision = sampler.decide(Instant::now());
1081        assert!(decision.voi_gain >= 0.0);
1082    }
1083
1084    #[test]
1085    fn forced_by_max_interval() {
1086        let config = VoiConfig {
1087            max_interval_events: 2,
1088            sample_cost: 1.0, // discourage sampling unless forced
1089            ..Default::default()
1090        };
1091        let mut sampler = VoiSampler::new(config);
1092        let now = Instant::now();
1093
1094        let d1 = sampler.decide(now);
1095        assert!(!d1.forced_by_interval);
1096
1097        let d2 = sampler.decide(now + Duration::from_millis(1));
1098        assert!(d2.forced_by_interval);
1099        assert!(d2.should_sample);
1100    }
1101
1102    #[test]
1103    fn min_interval_blocks_sampling_after_first() {
1104        let config = VoiConfig {
1105            min_interval_events: 5,
1106            sample_cost: 0.0, // otherwise would sample
1107            ..Default::default()
1108        };
1109        let mut sampler = VoiSampler::new(config);
1110
1111        let first = sampler.decide(Instant::now());
1112        assert!(first.should_sample);
1113        sampler.observe(false);
1114
1115        let second = sampler.decide(Instant::now());
1116        assert!(second.blocked_by_min_interval);
1117        assert!(!second.should_sample);
1118    }
1119
1120    #[test]
1121    fn variance_shrinks_with_samples() {
1122        let mut sampler = VoiSampler::new(VoiConfig::default());
1123        let mut now = Instant::now();
1124        let mut variances = Vec::new();
1125        for _ in 0..5 {
1126            let decision = sampler.decide(now);
1127            if decision.should_sample {
1128                sampler.observe_at(false, now);
1129            }
1130            variances.push(beta_variance(sampler.alpha, sampler.beta));
1131            now += Duration::from_millis(1);
1132        }
1133        for window in variances.windows(2) {
1134            assert!(window[1] <= window[0] + 1e-9);
1135        }
1136    }
1137
1138    #[test]
1139    fn decision_checksum_is_stable() {
1140        let config = VoiConfig {
1141            sample_cost: 0.01,
1142            ..Default::default()
1143        };
1144        let mut now = Instant::now();
1145        let mut sampler = VoiSampler::new_at(config, now);
1146
1147        let mut state: u64 = 42;
1148        let mut decisions = Vec::new();
1149
1150        for _ in 0..32 {
1151            let decision = sampler.decide(now);
1152            let violated = lcg_next(&mut state).is_multiple_of(10);
1153            if decision.should_sample {
1154                sampler.observe_at(violated, now);
1155            }
1156            decisions.push(decision);
1157            now += Duration::from_millis(5 + (lcg_next(&mut state) % 7));
1158        }
1159
1160        let checksum = decision_checksum(&decisions);
1161        assert_eq!(checksum, 0x0b51_d8b6_47a7_b00c);
1162    }
1163
1164    #[test]
1165    fn logs_render_jsonl() {
1166        let config = VoiConfig {
1167            enable_logging: true,
1168            ..Default::default()
1169        };
1170        let mut sampler = VoiSampler::new(config);
1171        let decision = sampler.decide(Instant::now());
1172        if decision.should_sample {
1173            sampler.observe(false);
1174        }
1175        let jsonl = sampler.logs_to_jsonl();
1176        assert!(jsonl.contains("\"event\":\"voi_decision\""));
1177    }
1178
1179    proptest! {
1180        #[test]
1181        fn prop_voi_gain_non_negative(alpha in 0.01f64..10.0, beta in 0.01f64..10.0) {
1182            let var = beta_variance(alpha, beta);
1183            let expected_after = expected_variance_after(alpha, beta);
1184            prop_assert!(var + 1e-12 >= expected_after);
1185        }
1186
1187        #[test]
1188        fn prop_e_value_stays_positive(seq in proptest::collection::vec(any::<bool>(), 1..50)) {
1189            let mut sampler = VoiSampler::new(VoiConfig::default());
1190            let mut now = Instant::now();
1191            for violated in seq {
1192                let decision = sampler.decide(now);
1193                if decision.should_sample {
1194                    sampler.observe_at(violated, now);
1195                }
1196                now += Duration::from_millis(1);
1197                prop_assert!(sampler.e_value >= E_MIN - 1e-12);
1198            }
1199        }
1200
1201        #[test]
1202        fn prop_voi_decision_to_jsonl_valid_json(
1203            event_idx in any::<u64>(),
1204            should_sample in any::<bool>(),
1205            forced in any::<bool>(),
1206            blocked in any::<bool>(),
1207            voi_gain in -100.0f64..100.0f64,
1208            score in -100.0f64..100.0f64,
1209            cost in 0.0f64..100.0f64,
1210            log_bayes_factor in -50.0f64..50.0f64,
1211            posterior_mean in 0.0f64..1.0f64,
1212            posterior_variance in 0.0f64..1.0f64,
1213            e_value in 0.0f64..100.0f64,
1214            e_threshold in 1.0f64..100.0f64,
1215            boundary_score in 0.0f64..1.0f64,
1216            events_since_sample in any::<u64>(),
1217            time_since_sample_ms in 0.0f64..100_000.0f64,
1218            reason_idx in 0..5usize,
1219        ) {
1220            let reasons = [
1221                "forced_max_interval",
1222                "blocked_min_interval",
1223                "score_exceeds_cost",
1224                "e_value_threshold",
1225                "test_reason",
1226            ];
1227            let reason = reasons[reason_idx];
1228            let decision = VoiDecision {
1229                event_idx,
1230                should_sample,
1231                forced_by_interval: forced,
1232                blocked_by_min_interval: blocked,
1233                voi_gain,
1234                score,
1235                cost,
1236                log_bayes_factor,
1237                posterior_mean,
1238                posterior_variance,
1239                e_value,
1240                e_threshold,
1241                boundary_score,
1242                events_since_sample,
1243                time_since_sample_ms,
1244                reason,
1245            };
1246            let jsonl = decision.to_jsonl();
1247            let parsed: serde_json::Value = serde_json::from_str(&jsonl).expect("valid json");
1248            prop_assert_eq!(parsed["event"].as_str(), Some("voi_decision"));
1249            prop_assert_eq!(parsed["schema_version"].as_str(), Some("ftui-evidence-v1"));
1250            prop_assert_eq!(parsed["should_sample"].as_bool(), Some(should_sample));
1251            prop_assert_eq!(parsed["forced"].as_bool(), Some(forced));
1252            prop_assert_eq!(parsed["blocked"].as_bool(), Some(blocked));
1253        }
1254    }
1255
1256    // =========================================================================
1257    // Perf microbench (JSONL + budget gate)
1258    // =========================================================================
1259
1260    #[test]
1261    fn perf_voi_sampling_budget() {
1262        use std::io::Write as _;
1263
1264        const RUNS: usize = 60;
1265        let mut sampler = VoiSampler::new(VoiConfig::default());
1266        let mut now = Instant::now();
1267        let mut samples = Vec::with_capacity(RUNS);
1268        let mut jsonl = Vec::new();
1269
1270        for i in 0..RUNS {
1271            let start = Instant::now();
1272            let decision = sampler.decide(now);
1273            let violated = i % 11 == 0;
1274            if decision.should_sample {
1275                sampler.observe_at(violated, now);
1276            }
1277            let elapsed_ns = start.elapsed().as_nanos() as u64;
1278            samples.push(elapsed_ns);
1279
1280            writeln!(
1281                &mut jsonl,
1282                "{{\"test\":\"voi_sampling\",\"case\":\"decision\",\"idx\":{},\
1283\"elapsed_ns\":{},\"sample\":{},\"violated\":{},\"e_value\":{:.6}}}",
1284                i, elapsed_ns, decision.should_sample, violated, sampler.e_value
1285            )
1286            .expect("jsonl write failed");
1287
1288            now += Duration::from_millis(1);
1289        }
1290
1291        fn percentile(samples: &mut [u64], p: f64) -> u64 {
1292            samples.sort_unstable();
1293            let idx = ((samples.len() as f64 - 1.0) * p).round() as usize;
1294            samples[idx]
1295        }
1296
1297        let mut samples_sorted = samples.clone();
1298        let _p50 = percentile(&mut samples_sorted, 0.50);
1299        let p95 = percentile(&mut samples_sorted, 0.95);
1300        let p99 = percentile(&mut samples_sorted, 0.99);
1301
1302        let (budget_p95, budget_p99) = if cfg!(debug_assertions) {
1303            (200_000, 400_000)
1304        } else {
1305            (20_000, 40_000)
1306        };
1307
1308        assert!(p95 <= budget_p95, "p95 {p95}ns exceeds {budget_p95}ns");
1309        assert!(p99 <= budget_p99, "p99 {p99}ns exceeds {budget_p99}ns");
1310
1311        let text = String::from_utf8(jsonl).expect("jsonl utf8");
1312        print!("{text}");
1313        assert_eq!(text.lines().count(), RUNS);
1314    }
1315
1316    // =========================================================================
1317    // Deterministic JSONL output for E2E harness
1318    // =========================================================================
1319
1320    #[test]
1321    fn e2e_deterministic_jsonl() {
1322        use std::io::Write as _;
1323
1324        let seed = std::env::var("VOI_SEED")
1325            .ok()
1326            .and_then(|s| s.parse::<u64>().ok())
1327            .unwrap_or(0);
1328
1329        let config = VoiConfig {
1330            enable_logging: false,
1331            ..Default::default()
1332        };
1333        let mut now = Instant::now();
1334        let mut sampler = VoiSampler::new_at(config, now);
1335        let mut state = seed;
1336        let mut decisions = Vec::new();
1337        let mut jsonl = Vec::new();
1338
1339        for idx in 0..40u64 {
1340            let decision = sampler.decide(now);
1341            let violated = lcg_next(&mut state).is_multiple_of(7);
1342            if decision.should_sample {
1343                sampler.observe_at(violated, now);
1344            }
1345            decisions.push(decision.clone());
1346
1347            writeln!(
1348                &mut jsonl,
1349                "{{\"event\":\"voi_decision\",\"seed\":{},\"idx\":{},\
1350\"sample\":{},\"violated\":{},\"voi_gain\":{:.6}}}",
1351                seed, idx, decision.should_sample, violated, decision.voi_gain
1352            )
1353            .expect("jsonl write failed");
1354
1355            now += Duration::from_millis(3 + (lcg_next(&mut state) % 5));
1356        }
1357
1358        let checksum = decision_checksum(&decisions);
1359        writeln!(
1360            &mut jsonl,
1361            "{{\"event\":\"voi_checksum\",\"seed\":{},\"checksum\":\"{checksum:016x}\",\"decisions\":{}}}",
1362            seed,
1363            decisions.len()
1364        )
1365        .expect("jsonl write failed");
1366
1367        let text = String::from_utf8(jsonl).expect("jsonl utf8");
1368        print!("{text}");
1369        assert!(text.contains("\"event\":\"voi_checksum\""));
1370    }
1371
1372    fn lcg_next(state: &mut u64) -> u64 {
1373        *state = state.wrapping_mul(6364136223846793005).wrapping_add(1);
1374        *state
1375    }
1376
1377    // =========================================================================
1378    // Additional coverage tests
1379    // =========================================================================
1380
1381    #[test]
1382    fn default_config_values() {
1383        let cfg = VoiConfig::default();
1384        assert!((cfg.alpha - 0.05).abs() < f64::EPSILON);
1385        assert!((cfg.prior_alpha - 1.0).abs() < f64::EPSILON);
1386        assert!((cfg.prior_beta - 1.0).abs() < f64::EPSILON);
1387        assert!((cfg.mu_0 - 0.05).abs() < f64::EPSILON);
1388        assert!((cfg.lambda - 0.5).abs() < f64::EPSILON);
1389        assert_eq!(cfg.max_interval_ms, 250);
1390        assert_eq!(cfg.max_interval_events, 20);
1391        assert_eq!(cfg.min_interval_ms, 0);
1392        assert_eq!(cfg.min_interval_events, 0);
1393        assert!(!cfg.enable_logging);
1394    }
1395
1396    #[test]
1397    fn config_clamping_prior_alpha_beta() {
1398        let config = VoiConfig {
1399            prior_alpha: -1.0,
1400            prior_beta: 0.0,
1401            ..Default::default()
1402        };
1403        let sampler = VoiSampler::new(config);
1404        let (a, b) = sampler.posterior_params();
1405        assert!(a > 0.0, "alpha should be clamped above zero");
1406        assert!(b > 0.0, "beta should be clamped above zero");
1407    }
1408
1409    #[test]
1410    fn config_clamping_mu_0() {
1411        let config = VoiConfig {
1412            mu_0: -0.5,
1413            ..Default::default()
1414        };
1415        let sampler = VoiSampler::new(config);
1416        let mean = sampler.posterior_mean();
1417        assert!((0.0..=1.0).contains(&mean));
1418    }
1419
1420    #[test]
1421    fn config_clamping_sample_cost() {
1422        let config = VoiConfig {
1423            sample_cost: -1.0,
1424            ..Default::default()
1425        };
1426        let mut sampler = VoiSampler::new(config);
1427        let d = sampler.decide(Instant::now());
1428        assert!(d.cost > 0.0, "cost should be clamped above zero");
1429    }
1430
1431    #[test]
1432    fn accessor_config() {
1433        let config = VoiConfig {
1434            alpha: 0.1,
1435            ..Default::default()
1436        };
1437        let sampler = VoiSampler::new(config);
1438        assert!((sampler.config().alpha - 0.1).abs() < f64::EPSILON);
1439    }
1440
1441    #[test]
1442    fn accessor_posterior_params() {
1443        let config = VoiConfig {
1444            prior_alpha: 3.0,
1445            prior_beta: 7.0,
1446            ..Default::default()
1447        };
1448        let sampler = VoiSampler::new(config);
1449        let (a, b) = sampler.posterior_params();
1450        assert!((a - 3.0).abs() < f64::EPSILON);
1451        assert!((b - 7.0).abs() < f64::EPSILON);
1452    }
1453
1454    #[test]
1455    fn accessor_posterior_mean() {
1456        let config = VoiConfig {
1457            prior_alpha: 2.0,
1458            prior_beta: 8.0,
1459            ..Default::default()
1460        };
1461        let sampler = VoiSampler::new(config);
1462        // mean = 2/(2+8) = 0.2
1463        assert!((sampler.posterior_mean() - 0.2).abs() < 1e-9);
1464    }
1465
1466    #[test]
1467    fn accessor_posterior_variance() {
1468        let sampler = VoiSampler::new(VoiConfig::default());
1469        let var = sampler.posterior_variance();
1470        assert!(var >= 0.0);
1471        assert!(var <= 0.25); // max variance for Beta
1472    }
1473
1474    #[test]
1475    fn accessor_expected_variance_after() {
1476        let sampler = VoiSampler::new(VoiConfig::default());
1477        let before = sampler.posterior_variance();
1478        let after = sampler.expected_variance_after();
1479        assert!(
1480            after <= before + 1e-12,
1481            "expected variance after should not exceed current"
1482        );
1483    }
1484
1485    #[test]
1486    fn last_decision_initially_none() {
1487        let sampler = VoiSampler::new(VoiConfig::default());
1488        assert!(sampler.last_decision().is_none());
1489    }
1490
1491    #[test]
1492    fn last_decision_after_decide() {
1493        let mut sampler = VoiSampler::new(VoiConfig::default());
1494        sampler.decide(Instant::now());
1495        assert!(sampler.last_decision().is_some());
1496    }
1497
1498    #[test]
1499    fn last_observation_initially_none() {
1500        let sampler = VoiSampler::new(VoiConfig::default());
1501        assert!(sampler.last_observation().is_none());
1502    }
1503
1504    #[test]
1505    fn last_observation_after_observe() {
1506        let mut sampler = VoiSampler::new(VoiConfig::default());
1507        sampler.decide(Instant::now());
1508        sampler.observe(false);
1509        assert!(sampler.last_observation().is_some());
1510        assert!(!sampler.last_observation().unwrap().violated);
1511    }
1512
1513    #[test]
1514    fn observe_violation_updates_alpha() {
1515        let mut sampler = VoiSampler::new(VoiConfig::default());
1516        let (a_before, _) = sampler.posterior_params();
1517        sampler.decide(Instant::now());
1518        sampler.observe(true);
1519        let (a_after, _) = sampler.posterior_params();
1520        assert!((a_after - a_before - 1.0).abs() < 1e-9);
1521    }
1522
1523    #[test]
1524    fn observe_no_violation_updates_beta() {
1525        let mut sampler = VoiSampler::new(VoiConfig::default());
1526        let (_, b_before) = sampler.posterior_params();
1527        sampler.decide(Instant::now());
1528        sampler.observe(false);
1529        let (_, b_after) = sampler.posterior_params();
1530        assert!((b_after - b_before - 1.0).abs() < 1e-9);
1531    }
1532
1533    #[test]
1534    fn e_value_positive_after_violations() {
1535        let mut sampler = VoiSampler::new(VoiConfig::default());
1536        let mut now = Instant::now();
1537        for _ in 0..10 {
1538            sampler.decide(now);
1539            sampler.observe_at(true, now);
1540            now += Duration::from_millis(1);
1541        }
1542        let summary = sampler.summary();
1543        assert!(summary.e_value > 0.0);
1544    }
1545
1546    #[test]
1547    fn summary_initial_state() {
1548        let sampler = VoiSampler::new(VoiConfig::default());
1549        let summary = sampler.summary();
1550        assert_eq!(summary.total_events, 0);
1551        assert_eq!(summary.total_samples, 0);
1552        assert_eq!(summary.forced_samples, 0);
1553        assert_eq!(summary.skipped_events, 0);
1554        assert!((summary.avg_events_between_samples).abs() < f64::EPSILON);
1555    }
1556
1557    #[test]
1558    fn summary_after_observations() {
1559        let mut sampler = VoiSampler::new(VoiConfig::default());
1560        let now = Instant::now();
1561        sampler.decide(now);
1562        sampler.observe_at(false, now);
1563        sampler.decide(now + Duration::from_millis(10));
1564        let summary = sampler.summary();
1565        assert_eq!(summary.total_events, 2);
1566        assert_eq!(summary.total_samples, 1);
1567        assert_eq!(summary.skipped_events, 1);
1568    }
1569
1570    #[test]
1571    fn mark_forced_sample_increments() {
1572        let mut sampler = VoiSampler::new(VoiConfig::default());
1573        assert_eq!(sampler.summary().forced_samples, 0);
1574        sampler.mark_forced_sample();
1575        sampler.mark_forced_sample();
1576        assert_eq!(sampler.summary().forced_samples, 2);
1577    }
1578
1579    #[test]
1580    fn snapshot_captures_state() {
1581        let mut sampler = VoiSampler::new(VoiConfig {
1582            enable_logging: true,
1583            ..Default::default()
1584        });
1585        let now = Instant::now();
1586        sampler.decide(now);
1587        sampler.observe_at(false, now);
1588
1589        let snap = sampler.snapshot(10, 42);
1590        assert_eq!(snap.captured_ms, 42);
1591        assert!(snap.alpha > 0.0);
1592        assert!(snap.beta > 0.0);
1593        assert!((0.0..=1.0).contains(&snap.posterior_mean));
1594        assert!(snap.last_decision.is_some());
1595        assert!(snap.last_observation.is_some());
1596    }
1597
1598    #[test]
1599    fn log_rotation_respects_max_entries() {
1600        let config = VoiConfig {
1601            enable_logging: true,
1602            max_log_entries: 3,
1603            ..Default::default()
1604        };
1605        let mut sampler = VoiSampler::new(config);
1606        let mut now = Instant::now();
1607
1608        for _ in 0..10 {
1609            let d = sampler.decide(now);
1610            if d.should_sample {
1611                sampler.observe_at(false, now);
1612            }
1613            now += Duration::from_millis(300);
1614        }
1615
1616        assert!(sampler.logs().len() <= 3);
1617    }
1618
1619    #[test]
1620    fn logs_empty_when_logging_disabled() {
1621        let config = VoiConfig {
1622            enable_logging: false,
1623            ..Default::default()
1624        };
1625        let mut sampler = VoiSampler::new(config);
1626        sampler.decide(Instant::now());
1627        assert!(sampler.logs().is_empty());
1628    }
1629
1630    #[test]
1631    fn decision_jsonl_format() {
1632        let mut sampler = VoiSampler::new(VoiConfig::default());
1633        let decision = sampler.decide(Instant::now());
1634        let jsonl = decision.to_jsonl();
1635        assert!(jsonl.starts_with('{'));
1636        assert!(jsonl.ends_with('}'));
1637        assert!(jsonl.contains("\"event\":\"voi_decision\""));
1638        assert!(jsonl.contains("\"should_sample\":"));
1639        assert!(jsonl.contains("\"reason\":"));
1640    }
1641
1642    #[test]
1643    fn observation_jsonl_format() {
1644        let mut sampler = VoiSampler::new(VoiConfig::default());
1645        sampler.decide(Instant::now());
1646        let obs = sampler.observe(false);
1647        let jsonl = obs.to_jsonl();
1648        assert!(jsonl.starts_with('{'));
1649        assert!(jsonl.ends_with('}'));
1650        assert!(jsonl.contains("\"event\":\"voi_observe\""));
1651        assert!(jsonl.contains("\"violated\":false"));
1652    }
1653
1654    #[test]
1655    fn log_entry_jsonl_decision_variant() {
1656        let mut sampler = VoiSampler::new(VoiConfig::default());
1657        let decision = sampler.decide(Instant::now());
1658        let entry = VoiLogEntry::Decision(decision);
1659        let jsonl = entry.to_jsonl();
1660        assert!(jsonl.contains("\"event\":\"voi_decision\""));
1661    }
1662
1663    #[test]
1664    fn log_entry_jsonl_observation_variant() {
1665        let mut sampler = VoiSampler::new(VoiConfig::default());
1666        sampler.decide(Instant::now());
1667        let obs = sampler.observe(true);
1668        let entry = VoiLogEntry::Observation(obs);
1669        let jsonl = entry.to_jsonl();
1670        assert!(jsonl.contains("\"event\":\"voi_observe\""));
1671        assert!(jsonl.contains("\"violated\":true"));
1672    }
1673
1674    #[test]
1675    fn time_based_max_interval_forces_sample() {
1676        let config = VoiConfig {
1677            max_interval_ms: 100,
1678            max_interval_events: 0, // disable event forcing
1679            sample_cost: 100.0,     // very high cost to prevent VOI sampling
1680            ..Default::default()
1681        };
1682        let now = Instant::now();
1683        let mut sampler = VoiSampler::new_at(config, now);
1684
1685        // First decision (no prior sample, but event interval might force)
1686        let _d1 = sampler.decide(now + Duration::from_millis(1));
1687        sampler.observe_at(false, now + Duration::from_millis(1));
1688
1689        // Second decision well within time window
1690        let d2 = sampler.decide(now + Duration::from_millis(10));
1691        assert!(!d2.forced_by_interval, "should not force within 100ms");
1692
1693        // Decision after 100+ ms
1694        let d3 = sampler.decide(now + Duration::from_millis(110));
1695        assert!(d3.forced_by_interval, "should force after 100ms");
1696        assert!(d3.should_sample);
1697    }
1698
1699    #[test]
1700    fn time_based_min_interval_blocks() {
1701        let config = VoiConfig {
1702            min_interval_ms: 50,
1703            min_interval_events: 0,
1704            ..Default::default()
1705        };
1706        let now = Instant::now();
1707        let mut sampler = VoiSampler::new_at(config, now);
1708
1709        // First sample
1710        let d1 = sampler.decide(now);
1711        assert!(d1.should_sample);
1712        sampler.observe_at(false, now);
1713
1714        // Too soon
1715        let d2 = sampler.decide(now + Duration::from_millis(10));
1716        assert!(d2.blocked_by_min_interval);
1717        assert!(!d2.should_sample);
1718
1719        // After min interval
1720        let d3 = sampler.decide(now + Duration::from_millis(60));
1721        assert!(!d3.blocked_by_min_interval);
1722    }
1723
1724    #[test]
1725    fn decision_reason_strings() {
1726        // forced
1727        let config = VoiConfig {
1728            max_interval_events: 1,
1729            ..Default::default()
1730        };
1731        let mut sampler = VoiSampler::new(config);
1732        let d = sampler.decide(Instant::now());
1733        assert_eq!(d.reason, "forced_interval");
1734    }
1735
1736    #[test]
1737    fn decision_reason_min_interval() {
1738        let config = VoiConfig {
1739            min_interval_events: 100,
1740            sample_cost: 0.0,
1741            ..Default::default()
1742        };
1743        let mut sampler = VoiSampler::new(config);
1744        sampler.decide(Instant::now());
1745        sampler.observe(false);
1746        let d = sampler.decide(Instant::now());
1747        assert_eq!(d.reason, "min_interval");
1748    }
1749
1750    #[test]
1751    fn beta_mean_basic() {
1752        assert!((beta_mean(1.0, 1.0) - 0.5).abs() < 1e-9);
1753        assert!((beta_mean(2.0, 8.0) - 0.2).abs() < 1e-9);
1754        assert!((beta_mean(5.0, 5.0) - 0.5).abs() < 1e-9);
1755    }
1756
1757    #[test]
1758    fn beta_variance_basic() {
1759        // Var(Beta(1,1)) = 1*1 / (4*3) = 1/12
1760        let var = beta_variance(1.0, 1.0);
1761        assert!((var - 1.0 / 12.0).abs() < 1e-9);
1762    }
1763
1764    #[test]
1765    fn beta_variance_degenerate() {
1766        assert!((beta_variance(0.0, 0.0)).abs() < f64::EPSILON);
1767        assert!((beta_variance(-1.0, -1.0)).abs() < f64::EPSILON);
1768    }
1769
1770    #[test]
1771    fn boundary_score_at_threshold() {
1772        // When e_value equals threshold, gap = 0, score = 1.0
1773        let score = boundary_score(20.0, 20.0);
1774        assert!((score - 1.0).abs() < 1e-9);
1775    }
1776
1777    #[test]
1778    fn boundary_score_far_from_threshold() {
1779        // Large gap → small score
1780        let score = boundary_score(1.0, 1e6);
1781        assert!(score < 0.1);
1782    }
1783
1784    #[test]
1785    fn logs_to_jsonl_multiple_entries() {
1786        let config = VoiConfig {
1787            enable_logging: true,
1788            ..Default::default()
1789        };
1790        let mut sampler = VoiSampler::new(config);
1791        let mut now = Instant::now();
1792        for _ in 0..5 {
1793            let d = sampler.decide(now);
1794            if d.should_sample {
1795                sampler.observe_at(false, now);
1796            }
1797            now += Duration::from_millis(300);
1798        }
1799        let jsonl = sampler.logs_to_jsonl();
1800        let line_count = jsonl.lines().count();
1801        assert!(
1802            line_count >= 2,
1803            "should have at least 2 log lines, got {line_count}"
1804        );
1805    }
1806
1807    // =========================================================================
1808    // Tracing capture infrastructure
1809    // =========================================================================
1810
1811    #[derive(Debug, Clone)]
1812    #[allow(dead_code)]
1813    struct CapturedSpan {
1814        name: String,
1815        target: String,
1816        level: tracing::Level,
1817        fields: HashMap<String, String>,
1818        parent_name: Option<String>,
1819    }
1820
1821    #[derive(Debug, Clone)]
1822    #[allow(dead_code)]
1823    struct CapturedEvent {
1824        level: tracing::Level,
1825        target: String,
1826        message: String,
1827        fields: HashMap<String, String>,
1828        parent_span_name: Option<String>,
1829    }
1830
1831    struct SpanCapture {
1832        spans: Arc<Mutex<Vec<CapturedSpan>>>,
1833        events: Arc<Mutex<Vec<CapturedEvent>>>,
1834        span_index: Arc<Mutex<HashMap<u64, usize>>>,
1835    }
1836
1837    impl SpanCapture {
1838        fn new() -> (Self, CaptureHandle) {
1839            let spans = Arc::new(Mutex::new(Vec::new()));
1840            let events = Arc::new(Mutex::new(Vec::new()));
1841            let span_index = Arc::new(Mutex::new(HashMap::new()));
1842
1843            let handle = CaptureHandle {
1844                spans: spans.clone(),
1845                events: events.clone(),
1846            };
1847
1848            (
1849                Self {
1850                    spans,
1851                    events,
1852                    span_index,
1853                },
1854                handle,
1855            )
1856        }
1857    }
1858
1859    struct CaptureHandle {
1860        spans: Arc<Mutex<Vec<CapturedSpan>>>,
1861        events: Arc<Mutex<Vec<CapturedEvent>>>,
1862    }
1863
1864    impl CaptureHandle {
1865        fn spans(&self) -> Vec<CapturedSpan> {
1866            self.spans.lock().unwrap().clone()
1867        }
1868
1869        fn events(&self) -> Vec<CapturedEvent> {
1870            self.events.lock().unwrap().clone()
1871        }
1872    }
1873
1874    struct FieldVisitor(Vec<(String, String)>);
1875
1876    impl tracing::field::Visit for FieldVisitor {
1877        fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
1878            self.0
1879                .push((field.name().to_string(), format!("{value:?}")));
1880        }
1881
1882        fn record_u64(&mut self, field: &tracing::field::Field, value: u64) {
1883            self.0.push((field.name().to_string(), value.to_string()));
1884        }
1885
1886        fn record_i64(&mut self, field: &tracing::field::Field, value: i64) {
1887            self.0.push((field.name().to_string(), value.to_string()));
1888        }
1889
1890        fn record_f64(&mut self, field: &tracing::field::Field, value: f64) {
1891            self.0.push((field.name().to_string(), value.to_string()));
1892        }
1893
1894        fn record_str(&mut self, field: &tracing::field::Field, value: &str) {
1895            self.0.push((field.name().to_string(), value.to_string()));
1896        }
1897
1898        fn record_bool(&mut self, field: &tracing::field::Field, value: bool) {
1899            self.0.push((field.name().to_string(), value.to_string()));
1900        }
1901    }
1902
1903    impl<S> tracing_subscriber::Layer<S> for SpanCapture
1904    where
1905        S: tracing::Subscriber + for<'a> LookupSpan<'a>,
1906    {
1907        fn on_new_span(
1908            &self,
1909            attrs: &tracing::span::Attributes<'_>,
1910            id: &tracing::span::Id,
1911            ctx: tracing_subscriber::layer::Context<'_, S>,
1912        ) {
1913            let mut visitor = FieldVisitor(Vec::new());
1914            attrs.record(&mut visitor);
1915
1916            let parent_name = ctx
1917                .current_span()
1918                .id()
1919                .and_then(|pid| ctx.span(pid))
1920                .map(|span_ref| span_ref.name().to_string());
1921
1922            let mut fields: HashMap<String, String> = visitor.0.into_iter().collect();
1923            for field in attrs.metadata().fields() {
1924                fields.entry(field.name().to_string()).or_default();
1925            }
1926
1927            let mut spans = self.spans.lock().unwrap();
1928            let idx = spans.len();
1929            spans.push(CapturedSpan {
1930                name: attrs.metadata().name().to_string(),
1931                target: attrs.metadata().target().to_string(),
1932                level: *attrs.metadata().level(),
1933                fields,
1934                parent_name,
1935            });
1936
1937            self.span_index.lock().unwrap().insert(id.into_u64(), idx);
1938        }
1939
1940        fn on_record(
1941            &self,
1942            id: &tracing::span::Id,
1943            values: &tracing::span::Record<'_>,
1944            _ctx: tracing_subscriber::layer::Context<'_, S>,
1945        ) {
1946            let mut visitor = FieldVisitor(Vec::new());
1947            values.record(&mut visitor);
1948
1949            let index = self.span_index.lock().unwrap();
1950            if let Some(&idx) = index.get(&id.into_u64()) {
1951                let mut spans = self.spans.lock().unwrap();
1952                if let Some(span) = spans.get_mut(idx) {
1953                    for (k, v) in visitor.0 {
1954                        span.fields.insert(k, v);
1955                    }
1956                }
1957            }
1958        }
1959
1960        fn on_event(
1961            &self,
1962            event: &tracing::Event<'_>,
1963            ctx: tracing_subscriber::layer::Context<'_, S>,
1964        ) {
1965            let mut visitor = FieldVisitor(Vec::new());
1966            event.record(&mut visitor);
1967
1968            let fields: HashMap<String, String> = visitor.0.clone().into_iter().collect();
1969            let message = visitor
1970                .0
1971                .iter()
1972                .find(|(k, _)| k == "message")
1973                .map(|(_, v)| v.clone())
1974                .unwrap_or_default();
1975
1976            let parent_span_name = ctx
1977                .current_span()
1978                .id()
1979                .and_then(|id| ctx.span(id))
1980                .map(|span_ref| span_ref.name().to_string());
1981
1982            self.events.lock().unwrap().push(CapturedEvent {
1983                level: *event.metadata().level(),
1984                target: event.metadata().target().to_string(),
1985                message,
1986                fields,
1987                parent_span_name,
1988            });
1989        }
1990    }
1991
1992    fn with_captured_tracing<F>(f: F) -> CaptureHandle
1993    where
1994        F: FnOnce(),
1995    {
1996        let (layer, handle) = SpanCapture::new();
1997        let subscriber = tracing_subscriber::registry().with(layer);
1998        tracing::subscriber::with_default(subscriber, f);
1999        handle
2000    }
2001
2002    // =========================================================================
2003    // Tracing span field assertions (bd-37a.4)
2004    // =========================================================================
2005
2006    #[test]
2007    fn span_voi_evaluate_has_required_fields() {
2008        let handle = with_captured_tracing(|| {
2009            let mut sampler = VoiSampler::new(VoiConfig::default());
2010            sampler.decide(Instant::now());
2011        });
2012
2013        let spans = handle.spans();
2014        let voi_spans: Vec<_> = spans.iter().filter(|s| s.name == "voi.evaluate").collect();
2015        assert!(
2016            !voi_spans.is_empty(),
2017            "expected at least one voi.evaluate span, got none"
2018        );
2019
2020        let span = &voi_spans[0];
2021        assert!(
2022            span.fields.contains_key("decision_context"),
2023            "missing decision_context field"
2024        );
2025        assert!(
2026            span.fields.contains_key("voi_estimate"),
2027            "missing voi_estimate field"
2028        );
2029        assert!(
2030            span.fields.contains_key("sample_cost"),
2031            "missing sample_cost field"
2032        );
2033        assert!(
2034            span.fields.contains_key("sample_decision"),
2035            "missing sample_decision field"
2036        );
2037    }
2038
2039    #[test]
2040    fn span_voi_evaluate_decision_context_values() {
2041        let handle = with_captured_tracing(|| {
2042            // Force a high-cost scenario so first decision is not forced
2043            let config = VoiConfig {
2044                max_interval_events: 0,
2045                max_interval_ms: 0,
2046                sample_cost: 1000.0,
2047                ..Default::default()
2048            };
2049            let mut sampler = VoiSampler::new(config);
2050            sampler.decide(Instant::now());
2051        });
2052
2053        let spans = handle.spans();
2054        let voi_spans: Vec<_> = spans.iter().filter(|s| s.name == "voi.evaluate").collect();
2055        assert!(!voi_spans.is_empty());
2056
2057        let ctx = &voi_spans[0].fields["decision_context"];
2058        assert!(
2059            ctx == "voi_lt_cost" || ctx == "voi_ge_cost",
2060            "unexpected context: {ctx}"
2061        );
2062    }
2063
2064    #[test]
2065    fn span_voi_evaluate_forced_interval_context() {
2066        let handle = with_captured_tracing(|| {
2067            let config = VoiConfig {
2068                max_interval_events: 1,
2069                ..Default::default()
2070            };
2071            let mut sampler = VoiSampler::new(config);
2072            sampler.decide(Instant::now());
2073        });
2074
2075        let spans = handle.spans();
2076        let voi_spans: Vec<_> = spans.iter().filter(|s| s.name == "voi.evaluate").collect();
2077        assert!(!voi_spans.is_empty());
2078        assert_eq!(voi_spans[0].fields["decision_context"], "forced_interval");
2079    }
2080
2081    // =========================================================================
2082    // DEBUG log assertions
2083    // =========================================================================
2084
2085    #[test]
2086    fn debug_log_voi_calculation() {
2087        let handle = with_captured_tracing(|| {
2088            let mut sampler = VoiSampler::new(VoiConfig::default());
2089            sampler.decide(Instant::now());
2090        });
2091
2092        let events = handle.events();
2093        let debug_events: Vec<_> = events
2094            .iter()
2095            .filter(|e| {
2096                e.level == tracing::Level::DEBUG
2097                    && e.target == crate::telemetry_schema::TARGET_VOI
2098                    && e.fields.contains_key("voi_gain")
2099            })
2100            .collect();
2101
2102        assert!(
2103            !debug_events.is_empty(),
2104            "expected at least one DEBUG voi calculation event"
2105        );
2106
2107        let evt = &debug_events[0];
2108        assert!(evt.fields.contains_key("score"), "missing score field");
2109        assert!(evt.fields.contains_key("cost"), "missing cost field");
2110        assert!(
2111            evt.fields.contains_key("posterior_mean"),
2112            "missing posterior_mean"
2113        );
2114        assert!(
2115            evt.fields.contains_key("boundary_score"),
2116            "missing boundary_score"
2117        );
2118    }
2119
2120    #[test]
2121    fn debug_log_voi_estimate_histogram() {
2122        let handle = with_captured_tracing(|| {
2123            let mut sampler = VoiSampler::new(VoiConfig::default());
2124            sampler.decide(Instant::now());
2125        });
2126
2127        let events = handle.events();
2128        let hist_events: Vec<_> = events
2129            .iter()
2130            .filter(|e| {
2131                e.level == tracing::Level::DEBUG
2132                    && e.target == crate::telemetry_schema::TARGET_VOI
2133                    && e.fields.contains_key("voi_estimate_value")
2134            })
2135            .collect();
2136
2137        assert!(
2138            !hist_events.is_empty(),
2139            "expected voi_estimate_value histogram event"
2140        );
2141    }
2142
2143    // =========================================================================
2144    // TRACE log assertions (utility estimates)
2145    // =========================================================================
2146
2147    #[test]
2148    fn trace_log_utility_estimate_after_observation() {
2149        let handle = with_captured_tracing(|| {
2150            let mut sampler = VoiSampler::new(VoiConfig::default());
2151            let now = Instant::now();
2152            sampler.decide(now);
2153            sampler.observe_at(false, now);
2154        });
2155
2156        let events = handle.events();
2157        let trace_events: Vec<_> = events
2158            .iter()
2159            .filter(|e| {
2160                e.level == tracing::Level::TRACE
2161                    && e.target == crate::telemetry_schema::TARGET_VOI
2162                    && e.fields.contains_key("voi_estimate_value")
2163            })
2164            .collect();
2165
2166        assert!(
2167            !trace_events.is_empty(),
2168            "expected TRACE utility estimate event after observe"
2169        );
2170
2171        let evt = &trace_events[0];
2172        assert!(evt.fields.contains_key("alpha"), "missing alpha");
2173        assert!(evt.fields.contains_key("beta"), "missing beta");
2174        assert!(
2175            evt.fields.contains_key("posterior_mean"),
2176            "missing posterior_mean"
2177        );
2178        assert!(evt.fields.contains_key("e_value"), "missing e_value");
2179    }
2180
2181    // =========================================================================
2182    // Counter verification
2183    // =========================================================================
2184
2185    #[test]
2186    fn counters_increment_on_sample_decision() {
2187        let handle = with_captured_tracing(|| {
2188            let mut sampler = VoiSampler::new(VoiConfig::default());
2189            let mut now = Instant::now();
2190            for _ in 0..5 {
2191                let d = sampler.decide(now);
2192                if d.should_sample {
2193                    sampler.observe_at(false, now);
2194                }
2195                now += Duration::from_millis(100);
2196            }
2197        });
2198
2199        // Verify the tracing events were emitted (indirect counter check).
2200        // We can't reliably check global atomic counters in parallel tests,
2201        // so we verify the DEBUG events contain voi_gain (one per decide call).
2202        let events = handle.events();
2203        let calc_events: Vec<_> = events
2204            .iter()
2205            .filter(|e| {
2206                e.level == tracing::Level::DEBUG
2207                    && e.target == crate::telemetry_schema::TARGET_VOI
2208                    && e.fields.contains_key("voi_gain")
2209            })
2210            .collect();
2211
2212        assert_eq!(
2213            calc_events.len(),
2214            5,
2215            "expected 5 voi calculation events for 5 decide() calls"
2216        );
2217    }
2218
2219    #[test]
2220    fn counter_accessors_are_callable() {
2221        // Verify the counter accessor functions exist and return non-panicking values.
2222        let taken = voi_samples_taken_total();
2223        let skipped = voi_samples_skipped_total();
2224        // Verify the sum doesn't overflow (sanity check).
2225        let _ = taken.checked_add(skipped).expect("counter overflow");
2226    }
2227
2228    #[test]
2229    fn counters_increase_monotonically() {
2230        let before_taken = voi_samples_taken_total();
2231        let before_skipped = voi_samples_skipped_total();
2232
2233        let mut sampler = VoiSampler::new(VoiConfig::default());
2234        let mut now = Instant::now();
2235        for _ in 0..10 {
2236            let d = sampler.decide(now);
2237            if d.should_sample {
2238                sampler.observe_at(false, now);
2239            }
2240            now += Duration::from_millis(100);
2241        }
2242
2243        let after_taken = voi_samples_taken_total();
2244        let after_skipped = voi_samples_skipped_total();
2245
2246        // After 10 decisions, at least some should have been taken or skipped.
2247        assert!(
2248            (after_taken + after_skipped) >= (before_taken + before_skipped) + 10,
2249            "expected at least 10 counter increments total, \
2250             taken: {before_taken}→{after_taken}, skipped: {before_skipped}→{after_skipped}"
2251        );
2252    }
2253
2254    // =========================================================================
2255    // Deferred refinement scheduler tests (bd-2vr05.15.4.4)
2256    // =========================================================================
2257
2258    #[test]
2259    fn deferred_scheduler_respects_hard_budget() {
2260        let mut scheduler = DeferredRefinementScheduler::new(DeferredRefinementConfig {
2261            min_spare_budget_us: 200,
2262            max_refinements_per_frame: 3,
2263            voi_gain_cutoff: 0.01,
2264            fairness_boost_per_skip: 0.02,
2265            fairness_boost_cap: 0.5,
2266        });
2267
2268        let candidates = [
2269            RefinementCandidate {
2270                region_id: 1,
2271                estimated_cost_us: 600,
2272                voi_gain: 0.25,
2273            },
2274            RefinementCandidate {
2275                region_id: 2,
2276                estimated_cost_us: 500,
2277                voi_gain: 0.21,
2278            },
2279            RefinementCandidate {
2280                region_id: 3,
2281                estimated_cost_us: 300,
2282                voi_gain: 0.08,
2283            },
2284        ];
2285
2286        let plan = scheduler.plan_frame(3_000, 1_900, &candidates);
2287        assert!(plan.hard_budget_respected());
2288        assert!(plan.spent_optional_us <= plan.optional_budget_us);
2289        assert!(
2290            plan.mandatory_work_us
2291                .saturating_add(plan.reserved_spare_us)
2292                .saturating_add(plan.spent_optional_us)
2293                <= 3_000
2294        );
2295    }
2296
2297    #[test]
2298    fn deferred_scheduler_is_deterministic_for_identical_inputs() {
2299        let config = DeferredRefinementConfig {
2300            min_spare_budget_us: 100,
2301            max_refinements_per_frame: 2,
2302            voi_gain_cutoff: 0.01,
2303            fairness_boost_per_skip: 0.03,
2304            fairness_boost_cap: 0.6,
2305        };
2306        let mut a = DeferredRefinementScheduler::new(config.clone());
2307        let mut b = DeferredRefinementScheduler::new(config);
2308
2309        let candidates = [
2310            RefinementCandidate {
2311                region_id: 11,
2312                estimated_cost_us: 450,
2313                voi_gain: 0.13,
2314            },
2315            RefinementCandidate {
2316                region_id: 22,
2317                estimated_cost_us: 500,
2318                voi_gain: 0.11,
2319            },
2320            RefinementCandidate {
2321                region_id: 33,
2322                estimated_cost_us: 350,
2323                voi_gain: 0.07,
2324            },
2325        ];
2326
2327        for _ in 0..25 {
2328            let pa = a.plan_frame(2_800, 1_600, &candidates);
2329            let pb = b.plan_frame(2_800, 1_600, &candidates);
2330            assert_eq!(pa, pb);
2331        }
2332    }
2333
2334    #[test]
2335    fn deferred_scheduler_fairness_avoids_starvation() {
2336        let mut scheduler = DeferredRefinementScheduler::new(DeferredRefinementConfig {
2337            min_spare_budget_us: 400,
2338            max_refinements_per_frame: 1,
2339            voi_gain_cutoff: 0.01,
2340            fairness_boost_per_skip: 0.05,
2341            fairness_boost_cap: 2.0,
2342        });
2343
2344        let candidates = [
2345            RefinementCandidate {
2346                region_id: 100,
2347                estimated_cost_us: 700,
2348                voi_gain: 0.20,
2349            },
2350            RefinementCandidate {
2351                region_id: 200,
2352                estimated_cost_us: 700,
2353                voi_gain: 0.02,
2354            },
2355        ];
2356
2357        let mut low_region_selected = 0u32;
2358        for _ in 0..30 {
2359            let plan = scheduler.plan_frame(4_000, 2_700, &candidates);
2360            assert!(plan.hard_budget_respected());
2361            if plan.selected.iter().any(|s| s.region_id == 200) {
2362                low_region_selected = low_region_selected.saturating_add(1);
2363            }
2364        }
2365
2366        assert!(
2367            low_region_selected > 0,
2368            "fairness boosting should eventually schedule the lower-VOI region"
2369        );
2370    }
2371
2372    #[test]
2373    fn exact_fraction_oracle_and_inline_auto_default_bound() {
2374        // 1. Uniform Beta(1, 1) exact oracle:
2375        //    Var[Beta(1, 1)] = 1/12
2376        //    Var[Beta(2, 1)] = Var[Beta(1, 2)] = 1/18
2377        //    expected_variance_after(1, 1) = 1/18
2378        //    VOI(1, 1) = 1/12 - 1/18 = 1/36
2379        let var_1_1 = beta_variance(1.0, 1.0);
2380        let exp_1_1 = expected_variance_after(1.0, 1.0);
2381        let voi_1_1 = var_1_1 - exp_1_1;
2382        assert!((var_1_1 - 1.0 / 12.0).abs() < 1e-15);
2383        assert!((exp_1_1 - 1.0 / 18.0).abs() < 1e-15);
2384        assert!((voi_1_1 - 1.0 / 36.0).abs() < 1e-15);
2385
2386        // 2. Check six parameter pairs against exact algebraic identity:
2387        //    VOI(α, β) = αβ / (n^2 * (n+1)^2) <= 1 / (4 * (n+1)^2).
2388        let pairs = [
2389            (1.0, 1.0),
2390            (1.0, 9.0),
2391            (2.0, 3.0),
2392            (5.0, 5.0),
2393            (3.0, 17.0),
2394            (10.0, 90.0),
2395        ];
2396        for (a, b) in pairs {
2397            let n = a + b;
2398            let voi = beta_variance(a, b) - expected_variance_after(a, b);
2399            let exact = (a * b) / (n * n * (n + 1.0) * (n + 1.0));
2400            let upper = 1.0 / (4.0 * (n + 1.0) * (n + 1.0));
2401            assert!(
2402                (voi - exact).abs() < 1e-15,
2403                "VOI({a}, {b})={voi} != exact={exact}"
2404            );
2405            assert!(voi <= upper + 1e-15, "VOI({a}, {b})={voi} > upper={upper}");
2406        }
2407
2408        // 3. InlineAutoRemeasureConfig default prior (α=1, β=9, n=10):
2409        //    VOI(1, 9) = 9 / (100 * 121) = 9 / 12100.
2410        //    With value_scale=1, boundary_weight=1, boundary_score <= 1:
2411        //    score <= 2 * (9 / 12100) <= 2 / (4 * 121) = 1 / 242 ≈ 0.004132 < sample_cost (0.08).
2412        let inline_voi = beta_variance(1.0, 9.0) - expected_variance_after(1.0, 9.0);
2413        assert!((inline_voi - 9.0 / 12_100.0).abs() < 1e-15);
2414        assert!(2.0 * inline_voi <= 1.0 / 242.0 + 1e-15);
2415        assert!(2.0 * inline_voi < 0.08);
2416    }
2417
2418    #[test]
2419    fn adaptive_voi_sampling_eprocess_null_and_alternative_power_with_ci() {
2420        fn splitmix64_u01(state: &mut u64) -> f64 {
2421            *state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
2422            let mut z = *state;
2423            z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
2424            z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
2425            z ^= z >> 31;
2426            ((z >> 11) as f64) * (1.0 / ((1u64 << 53) as f64))
2427        }
2428
2429        let base_cfg = VoiConfig {
2430            alpha: 0.05,
2431            prior_alpha: 1.0,
2432            prior_beta: 1.0,
2433            mu_0: 0.05,
2434            lambda: 1.8,
2435            value_scale: 1.0,
2436            boundary_weight: 1.0,
2437            sample_cost: 0.001,
2438            min_interval_ms: 0,
2439            max_interval_ms: 0,
2440            min_interval_events: 0,
2441            max_interval_events: 4,
2442            enable_logging: false,
2443            max_log_entries: 16,
2444        };
2445        let threshold = 1.0 / base_cfg.alpha; // 20.0
2446        let trials = 1_500usize;
2447        let steps = 80usize;
2448        let t0 = Instant::now();
2449
2450        // 1. Under conditional null P(X_t = 1) = mu_0 = 0.05 with adaptive VOI sampling:
2451        let mut rng_null = 0x7015_2026_1016_0001u64;
2452        let mut null_terminal_w = Vec::with_capacity(trials);
2453        let mut null_crossings = 0usize;
2454
2455        for _ in 0..trials {
2456            let mut sampler = VoiSampler::new_at(base_cfg.clone(), t0);
2457            let mut crossed = false;
2458            for step in 0..steps {
2459                let now = t0 + Duration::from_millis(step as u64 * 10);
2460                let dec = sampler.decide(now);
2461                let x = splitmix64_u01(&mut rng_null) < base_cfg.mu_0;
2462                if dec.should_sample {
2463                    let obs = sampler.observe_at(x, now);
2464                    if obs.e_value >= threshold {
2465                        crossed = true;
2466                    }
2467                }
2468            }
2469            if crossed {
2470                null_crossings += 1;
2471            }
2472            null_terminal_w.push(sampler.summary().e_value);
2473        }
2474
2475        let n = trials as f64;
2476        let mean_w_null = null_terminal_w.iter().sum::<f64>() / n;
2477        let var_w_null = null_terminal_w
2478            .iter()
2479            .map(|&w| (w - mean_w_null).powi(2))
2480            .sum::<f64>()
2481            / (n - 1.0);
2482        let se_w_null = (var_w_null / n).sqrt();
2483        let fpr = null_crossings as f64 / n;
2484        let se_fpr = (base_cfg.alpha * (1.0 - base_cfg.alpha) / n).sqrt();
2485
2486        // Supermartingale property under adaptive sampling: E[W_T] <= 1.0 within sampling uncertainty.
2487        assert!(
2488            mean_w_null <= 1.0 + 3.0 * se_w_null,
2489            "Expected E[W_T] <= 1.0 under H_0, got {mean_w_null:.4} (se={se_w_null:.4})"
2490        );
2491        // Ville's inequality: P(sup_t W_t >= 1/alpha | H_0) <= alpha.
2492        assert!(
2493            fpr <= base_cfg.alpha + 3.0 * se_fpr,
2494            "Null false-positive rate {fpr:.4} exceeded alpha={} + 3*se",
2495            base_cfg.alpha
2496        );
2497
2498        // 2. Under alternative P(X_t = 1) = 0.35 > mu_0 = 0.05: high detection power.
2499        let mut rng_alt = 0x7015_2026_1016_0002u64;
2500        let mut alt_crossings = 0usize;
2501        for _ in 0..trials {
2502            let mut sampler = VoiSampler::new_at(base_cfg.clone(), t0);
2503            let mut crossed = false;
2504            for step in 0..steps {
2505                let now = t0 + Duration::from_millis(step as u64 * 10);
2506                let dec = sampler.decide(now);
2507                let x = splitmix64_u01(&mut rng_alt) < 0.35;
2508                if dec.should_sample {
2509                    let obs = sampler.observe_at(x, now);
2510                    if obs.e_value >= threshold {
2511                        crossed = true;
2512                    }
2513                }
2514            }
2515            if crossed {
2516                alt_crossings += 1;
2517            }
2518        }
2519        let power = alt_crossings as f64 / n;
2520        assert!(
2521            power > 0.75,
2522            "Expected detection power > 0.75 under p=0.35 alternative, got {power:.4}"
2523        );
2524
2525        // 3. Heuristic floor boundary check: when mu_0 = 0.8 and lambda = 2.0 > 1/mu_0 = 1.25,
2526        //    1 + lambda*(0 - mu_0) = -0.6 < 0 is floored at EPS and E_MIN, preventing negative wealth.
2527        let mut high_mu_cfg = base_cfg;
2528        high_mu_cfg.mu_0 = 0.8;
2529        high_mu_cfg.lambda = 2.0;
2530        let mut floored = VoiSampler::new_at(high_mu_cfg, t0);
2531        let obs = floored.observe_at(false, t0);
2532        assert_eq!(obs.e_value, E_MIN);
2533    }
2534}