1#![forbid(unsafe_code)]
2
3use std::collections::{BTreeMap, VecDeque};
120use std::sync::atomic::{AtomicU64, Ordering};
121use web_time::{Duration, Instant};
122
123const EPS: f64 = 1e-12;
124const MU_0_MIN: f64 = 1e-6;
125const MU_0_MAX: f64 = 1.0 - 1e-6;
126const LAMBDA_EPS: f64 = 1e-9;
127const E_MIN: f64 = 1e-12;
128const E_MAX: f64 = 1e12;
129const VAR_MAX: f64 = 0.25; static VOI_SAMPLES_TAKEN_TOTAL: AtomicU64 = AtomicU64::new(0);
136static VOI_SAMPLES_SKIPPED_TOTAL: AtomicU64 = AtomicU64::new(0);
137
138#[must_use]
140pub fn voi_samples_taken_total() -> u64 {
141 VOI_SAMPLES_TAKEN_TOTAL.load(Ordering::Relaxed)
142}
143
144#[must_use]
146pub fn voi_samples_skipped_total() -> u64 {
147 VOI_SAMPLES_SKIPPED_TOTAL.load(Ordering::Relaxed)
148}
149
150#[derive(Debug, Clone)]
152pub struct VoiConfig {
153 pub alpha: f64,
156
157 pub prior_alpha: f64,
159
160 pub prior_beta: f64,
162
163 pub mu_0: f64,
165
166 pub lambda: f64,
168
169 pub value_scale: f64,
171
172 pub boundary_weight: f64,
174
175 pub sample_cost: f64,
177
178 pub min_interval_ms: u64,
180
181 pub max_interval_ms: u64,
184
185 pub min_interval_events: u64,
187
188 pub max_interval_events: u64,
191
192 pub enable_logging: bool,
194
195 pub max_log_entries: usize,
197}
198
199impl Default for VoiConfig {
200 fn default() -> Self {
201 Self {
202 alpha: 0.05,
203 prior_alpha: 1.0,
204 prior_beta: 1.0,
205 mu_0: 0.05,
206 lambda: 0.5,
207 value_scale: 1.0,
208 boundary_weight: 1.0,
209 sample_cost: 0.01,
210 min_interval_ms: 0,
211 max_interval_ms: 250,
212 min_interval_events: 0,
213 max_interval_events: 20,
214 enable_logging: false,
215 max_log_entries: 2048,
216 }
217 }
218}
219
220#[derive(Debug, Clone)]
222pub struct VoiDecision {
223 pub event_idx: u64,
224 pub should_sample: bool,
225 pub forced_by_interval: bool,
226 pub blocked_by_min_interval: bool,
227 pub voi_gain: f64,
228 pub score: f64,
229 pub cost: f64,
230 pub log_bayes_factor: f64,
231 pub posterior_mean: f64,
232 pub posterior_variance: f64,
233 pub e_value: f64,
234 pub e_threshold: f64,
235 pub boundary_score: f64,
236 pub events_since_sample: u64,
237 pub time_since_sample_ms: f64,
238 pub reason: &'static str,
239}
240
241impl VoiDecision {
242 #[must_use]
244 pub fn to_jsonl(&self) -> String {
245 format!(
246 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":"{}"}}"#,
247 self.event_idx,
248 self.should_sample,
249 self.forced_by_interval,
250 self.blocked_by_min_interval,
251 self.voi_gain,
252 self.score,
253 self.cost,
254 self.log_bayes_factor,
255 self.posterior_mean,
256 self.posterior_variance,
257 self.e_value,
258 self.e_threshold,
259 self.boundary_score,
260 self.events_since_sample,
261 self.time_since_sample_ms,
262 self.reason
263 )
264 }
265}
266
267#[derive(Debug, Clone)]
269pub struct VoiObservation {
270 pub event_idx: u64,
271 pub sample_idx: u64,
272 pub violated: bool,
273 pub posterior_mean: f64,
274 pub posterior_variance: f64,
275 pub alpha: f64,
276 pub beta: f64,
277 pub e_value: f64,
278 pub e_threshold: f64,
279}
280
281impl VoiObservation {
282 #[must_use]
284 pub fn to_jsonl(&self) -> String {
285 format!(
286 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}}}"#,
287 self.event_idx,
288 self.sample_idx,
289 self.violated,
290 self.posterior_mean,
291 self.posterior_variance,
292 self.alpha,
293 self.beta,
294 self.e_value,
295 self.e_threshold
296 )
297 }
298}
299
300#[derive(Debug, Clone)]
302pub enum VoiLogEntry {
303 Decision(VoiDecision),
304 Observation(VoiObservation),
305}
306
307impl VoiLogEntry {
308 #[must_use]
310 pub fn to_jsonl(&self) -> String {
311 match self {
312 Self::Decision(decision) => decision.to_jsonl(),
313 Self::Observation(obs) => obs.to_jsonl(),
314 }
315 }
316}
317
318#[derive(Debug, Clone)]
320pub struct VoiSummary {
321 pub total_events: u64,
322 pub total_samples: u64,
323 pub forced_samples: u64,
324 pub skipped_events: u64,
325 pub current_mean: f64,
326 pub current_variance: f64,
327 pub e_value: f64,
328 pub e_threshold: f64,
329 pub avg_events_between_samples: f64,
330 pub avg_ms_between_samples: f64,
331}
332
333#[derive(Debug, Clone)]
335pub struct VoiSamplerSnapshot {
336 pub captured_ms: u64,
337 pub alpha: f64,
338 pub beta: f64,
339 pub posterior_mean: f64,
340 pub posterior_variance: f64,
341 pub expected_variance_after: f64,
342 pub voi_gain: f64,
343 pub last_decision: Option<VoiDecision>,
344 pub last_observation: Option<VoiObservation>,
345 pub recent_logs: Vec<VoiLogEntry>,
346}
347
348#[derive(Debug, Clone)]
350pub struct VoiSampler {
351 config: VoiConfig,
352 alpha: f64,
353 beta: f64,
354 mu_0: f64,
355 lambda: f64,
356 e_value: f64,
357 e_threshold: f64,
358 event_idx: u64,
359 sample_idx: u64,
360 forced_samples: u64,
361 last_sample_event: u64,
362 last_sample_time: Instant,
363 start_time: Instant,
364 last_decision_forced: bool,
365 logs: VecDeque<VoiLogEntry>,
366 last_decision: Option<VoiDecision>,
367 last_observation: Option<VoiObservation>,
368}
369
370impl VoiSampler {
371 pub fn new(config: VoiConfig) -> Self {
373 Self::new_at(config, Instant::now())
374 }
375
376 pub fn new_at(config: VoiConfig, now: Instant) -> Self {
378 let mut cfg = config;
379
380 let prior_alpha = if cfg.prior_alpha.is_nan() {
381 EPS
382 } else {
383 cfg.prior_alpha.max(EPS)
384 };
385 let prior_beta = if cfg.prior_beta.is_nan() {
386 EPS
387 } else {
388 cfg.prior_beta.max(EPS)
389 };
390 let mu_0 = if cfg.mu_0.is_nan() {
391 0.5
392 } else {
393 cfg.mu_0.clamp(MU_0_MIN, MU_0_MAX)
394 };
395 let lambda_max = (1.0 / (1.0 - mu_0)) - LAMBDA_EPS;
396 let lambda = if cfg.lambda.is_nan() {
397 LAMBDA_EPS
398 } else {
399 cfg.lambda.clamp(LAMBDA_EPS, lambda_max)
400 };
401
402 cfg.value_scale = if cfg.value_scale.is_nan() {
403 EPS
404 } else {
405 cfg.value_scale.max(EPS)
406 };
407 cfg.boundary_weight = if cfg.boundary_weight.is_nan() {
408 0.0
409 } else {
410 cfg.boundary_weight.max(0.0)
411 };
412 cfg.sample_cost = if cfg.sample_cost.is_nan() {
413 EPS
414 } else {
415 cfg.sample_cost.max(EPS)
416 };
417 cfg.max_log_entries = cfg.max_log_entries.max(1);
418
419 let e_threshold = 1.0 / cfg.alpha.max(EPS);
420
421 Self {
422 config: cfg,
423 alpha: prior_alpha,
424 beta: prior_beta,
425 mu_0,
426 lambda,
427 e_value: 1.0,
428 e_threshold,
429 event_idx: 0,
430 sample_idx: 0,
431 forced_samples: 0,
432 last_sample_event: 0,
433 last_sample_time: now,
434 start_time: now,
435 last_decision_forced: false,
436 logs: VecDeque::new(),
437 last_decision: None,
438 last_observation: None,
439 }
440 }
441
442 #[must_use]
444 pub fn config(&self) -> &VoiConfig {
445 &self.config
446 }
447
448 #[must_use]
450 pub fn posterior_params(&self) -> (f64, f64) {
451 (self.alpha, self.beta)
452 }
453
454 #[must_use]
456 pub fn posterior_mean(&self) -> f64 {
457 beta_mean(self.alpha, self.beta)
458 }
459
460 #[must_use]
462 pub fn posterior_variance(&self) -> f64 {
463 beta_variance(self.alpha, self.beta)
464 }
465
466 #[must_use]
468 pub fn expected_variance_after(&self) -> f64 {
469 expected_variance_after(self.alpha, self.beta)
470 }
471
472 #[must_use]
474 pub fn last_decision(&self) -> Option<&VoiDecision> {
475 self.last_decision.as_ref()
476 }
477
478 #[must_use]
480 pub fn last_observation(&self) -> Option<&VoiObservation> {
481 self.last_observation.as_ref()
482 }
483
484 pub fn decide(&mut self, now: Instant) -> VoiDecision {
486 self.event_idx += 1;
487
488 let events_since_sample = if self.sample_idx == 0 {
489 self.event_idx
490 } else {
491 self.event_idx.saturating_sub(self.last_sample_event)
492 };
493 let time_since_sample = if now >= self.last_sample_time {
494 now.saturating_duration_since(self.last_sample_time)
495 } else {
496 Duration::ZERO
497 };
498
499 let forced_by_events = self.config.max_interval_events > 0
500 && events_since_sample >= self.config.max_interval_events;
501 let forced_by_time = self.config.max_interval_ms > 0
502 && time_since_sample >= Duration::from_millis(self.config.max_interval_ms);
503 let forced = forced_by_events || forced_by_time;
504
505 let blocked_by_events = self.sample_idx > 0
506 && self.config.min_interval_events > 0
507 && events_since_sample < self.config.min_interval_events;
508 let blocked_by_time = self.sample_idx > 0
509 && self.config.min_interval_ms > 0
510 && time_since_sample < Duration::from_millis(self.config.min_interval_ms);
511 let blocked = blocked_by_events || blocked_by_time;
512
513 let variance = beta_variance(self.alpha, self.beta);
514 let expected_after = expected_variance_after(self.alpha, self.beta);
515 let voi_gain = (variance - expected_after).max(0.0);
516
517 let boundary_score = boundary_score(self.e_value, self.e_threshold);
518 let score = voi_gain
519 * self.config.value_scale
520 * (1.0 + self.config.boundary_weight * boundary_score);
521 let cost = self.config.sample_cost;
522 let log_bayes_factor = log10_ratio(score, cost);
523
524 let should_sample = if forced {
525 true
526 } else if blocked {
527 false
528 } else {
529 score >= cost
530 };
531
532 let reason = if forced {
533 "forced_interval"
534 } else if blocked {
535 "min_interval"
536 } else if should_sample {
537 "voi_ge_cost"
538 } else {
539 "voi_lt_cost"
540 };
541
542 let decision = VoiDecision {
543 event_idx: self.event_idx,
544 should_sample,
545 forced_by_interval: forced,
546 blocked_by_min_interval: blocked,
547 voi_gain,
548 score,
549 cost,
550 log_bayes_factor,
551 posterior_mean: beta_mean(self.alpha, self.beta),
552 posterior_variance: variance,
553 e_value: self.e_value,
554 e_threshold: self.e_threshold,
555 boundary_score,
556 events_since_sample,
557 time_since_sample_ms: time_since_sample.as_secs_f64() * 1000.0,
558 reason,
559 };
560
561 self.last_decision = Some(decision.clone());
562 self.last_decision_forced = forced;
563
564 let _span = tracing::debug_span!(
566 "voi.evaluate",
567 decision_context = %reason,
568 voi_estimate = %voi_gain,
569 sample_cost = %cost,
570 sample_decision = should_sample,
571 )
572 .entered();
573
574 tracing::debug!(
575 target: crate::telemetry_schema::TARGET_VOI,
576 voi_gain = %voi_gain,
577 score = %score,
578 cost = %cost,
579 log_bayes_factor = %log_bayes_factor,
580 posterior_mean = %decision.posterior_mean,
581 posterior_variance = %variance,
582 boundary_score = %boundary_score,
583 e_value = %self.e_value,
584 reason = %reason,
585 event_idx = self.event_idx,
586 "voi calculation"
587 );
588
589 tracing::debug!(
590 target: crate::telemetry_schema::TARGET_VOI,
591 voi_estimate_value = %voi_gain,
592 "voi estimate histogram"
593 );
594
595 if should_sample {
596 VOI_SAMPLES_TAKEN_TOTAL.fetch_add(1, Ordering::Relaxed);
597 } else {
598 VOI_SAMPLES_SKIPPED_TOTAL.fetch_add(1, Ordering::Relaxed);
599 }
600
601 if self.config.enable_logging {
602 self.push_log(VoiLogEntry::Decision(decision.clone()));
603 }
604
605 decision
606 }
607
608 pub fn observe_at(&mut self, violated: bool, now: Instant) -> VoiObservation {
610 self.sample_idx += 1;
611 self.last_sample_event = self.event_idx;
612 self.last_sample_time = now;
613 if self.last_decision_forced {
614 self.forced_samples += 1;
615 }
616
617 if violated {
618 self.alpha += 1.0;
619 } else {
620 self.beta += 1.0;
621 }
622
623 self.update_eprocess(violated);
624
625 let obs_posterior_mean = beta_mean(self.alpha, self.beta);
626 let obs_posterior_variance = beta_variance(self.alpha, self.beta);
627 let obs_voi_estimate =
628 (obs_posterior_variance - expected_variance_after(self.alpha, self.beta)).max(0.0);
629
630 let observation = VoiObservation {
631 event_idx: self.event_idx,
632 sample_idx: self.sample_idx,
633 violated,
634 posterior_mean: obs_posterior_mean,
635 posterior_variance: obs_posterior_variance,
636 alpha: self.alpha,
637 beta: self.beta,
638 e_value: self.e_value,
639 e_threshold: self.e_threshold,
640 };
641
642 tracing::trace!(
644 target: crate::telemetry_schema::TARGET_VOI,
645 violated = violated,
646 alpha = %self.alpha,
647 beta = %self.beta,
648 posterior_mean = %obs_posterior_mean,
649 posterior_variance = %obs_posterior_variance,
650 e_value = %self.e_value,
651 voi_estimate_value = %obs_voi_estimate,
652 sample_idx = self.sample_idx,
653 "utility estimate after observation"
654 );
655
656 self.last_observation = Some(observation.clone());
657 if self.config.enable_logging {
658 self.push_log(VoiLogEntry::Observation(observation.clone()));
659 }
660
661 observation
662 }
663
664 pub fn observe(&mut self, violated: bool) -> VoiObservation {
666 self.observe_at(violated, Instant::now())
667 }
668
669 #[must_use]
671 pub fn summary(&self) -> VoiSummary {
672 let skipped_events = self.event_idx.saturating_sub(self.sample_idx);
673 let avg_events_between_samples = if self.sample_idx > 0 {
674 self.event_idx as f64 / self.sample_idx as f64
675 } else {
676 0.0
677 };
678 let elapsed_ms = self.start_time.elapsed().as_secs_f64() * 1000.0;
679 let avg_ms_between_samples = if self.sample_idx > 0 {
680 elapsed_ms / self.sample_idx as f64
681 } else {
682 0.0
683 };
684
685 VoiSummary {
686 total_events: self.event_idx,
687 total_samples: self.sample_idx,
688 forced_samples: self.forced_samples,
689 skipped_events,
690 current_mean: beta_mean(self.alpha, self.beta),
691 current_variance: beta_variance(self.alpha, self.beta),
692 e_value: self.e_value,
693 e_threshold: self.e_threshold,
694 avg_events_between_samples,
695 avg_ms_between_samples,
696 }
697 }
698
699 #[must_use]
701 pub fn logs(&self) -> &VecDeque<VoiLogEntry> {
702 &self.logs
703 }
704
705 #[must_use]
707 pub fn logs_to_jsonl(&self) -> String {
708 self.logs
709 .iter()
710 .map(VoiLogEntry::to_jsonl)
711 .collect::<Vec<_>>()
712 .join("\n")
713 }
714
715 #[must_use]
717 pub fn snapshot(&self, max_logs: usize, captured_ms: u64) -> VoiSamplerSnapshot {
718 let expected_after = expected_variance_after(self.alpha, self.beta);
719 let variance = beta_variance(self.alpha, self.beta);
720 let voi_gain = (variance - expected_after).max(0.0);
721 let mut recent_logs: Vec<VoiLogEntry> = self
722 .logs
723 .iter()
724 .rev()
725 .take(max_logs.max(1))
726 .cloned()
727 .collect();
728 recent_logs.reverse();
729
730 VoiSamplerSnapshot {
731 captured_ms,
732 alpha: self.alpha,
733 beta: self.beta,
734 posterior_mean: beta_mean(self.alpha, self.beta),
735 posterior_variance: variance,
736 expected_variance_after: expected_after,
737 voi_gain,
738 last_decision: self.last_decision.clone(),
739 last_observation: self.last_observation.clone(),
740 recent_logs,
741 }
742 }
743
744 fn push_log(&mut self, entry: VoiLogEntry) {
745 if self.logs.len() >= self.config.max_log_entries {
746 self.logs.pop_front();
747 }
748 self.logs.push_back(entry);
749 }
750
751 fn update_eprocess(&mut self, violated: bool) {
752 let x = if violated { 1.0 } else { 0.0 };
753 let factor = 1.0 + self.lambda * (x - self.mu_0);
754 let next = self.e_value * factor.max(EPS);
755 self.e_value = next.clamp(E_MIN, E_MAX);
756 }
757
758 pub fn mark_forced_sample(&mut self) {
760 self.forced_samples += 1;
761 }
762}
763
764fn beta_mean(alpha: f64, beta: f64) -> f64 {
765 alpha / (alpha + beta)
766}
767
768fn beta_variance(alpha: f64, beta: f64) -> f64 {
769 let sum = alpha + beta;
770 if sum <= 0.0 {
771 return 0.0;
772 }
773 let var = (alpha * beta) / (sum * sum * (sum + 1.0));
774 var.min(VAR_MAX)
775}
776
777fn expected_variance_after(alpha: f64, beta: f64) -> f64 {
778 let p = beta_mean(alpha, beta);
779 let var_success = beta_variance(alpha + 1.0, beta);
780 let var_failure = beta_variance(alpha, beta + 1.0);
781 p * var_success + (1.0 - p) * var_failure
782}
783
784fn boundary_score(e_value: f64, threshold: f64) -> f64 {
785 let e = e_value.max(EPS);
786 let t = threshold.max(EPS);
787 let gap = (e.ln() - t.ln()).abs();
788 1.0 / (1.0 + gap)
789}
790
791fn log10_ratio(score: f64, cost: f64) -> f64 {
792 let ratio = (score + EPS) / (cost + EPS);
793 ratio.ln() / std::f64::consts::LN_10
794}
795
796#[derive(Debug, Clone, PartialEq)]
805pub struct DeferredRefinementConfig {
806 pub min_spare_budget_us: u64,
808 pub max_refinements_per_frame: usize,
810 pub voi_gain_cutoff: f64,
812 pub fairness_boost_per_skip: f64,
814 pub fairness_boost_cap: f64,
816}
817
818impl Default for DeferredRefinementConfig {
819 fn default() -> Self {
820 Self {
821 min_spare_budget_us: 500,
822 max_refinements_per_frame: 2,
823 voi_gain_cutoff: 0.01,
824 fairness_boost_per_skip: 0.02,
825 fairness_boost_cap: 1.0,
826 }
827 }
828}
829
830#[derive(Debug, Clone, Copy, PartialEq)]
832pub struct RefinementCandidate {
833 pub region_id: u64,
835 pub estimated_cost_us: u64,
837 pub voi_gain: f64,
839}
840
841#[derive(Debug, Clone, Copy, PartialEq)]
843pub struct RefinementSelection {
844 pub region_id: u64,
845 pub estimated_cost_us: u64,
846 pub voi_gain: f64,
847 pub fairness_boost: f64,
848 pub effective_voi: f64,
849 pub score: f64,
850}
851
852#[derive(Debug, Clone, PartialEq)]
854pub struct DeferredRefinementPlan {
855 pub frame_budget_us: u64,
856 pub mandatory_work_us: u64,
857 pub reserved_spare_us: u64,
858 pub optional_budget_us: u64,
859 pub spent_optional_us: u64,
860 pub selected: Vec<RefinementSelection>,
861}
862
863impl DeferredRefinementPlan {
864 #[must_use]
866 pub fn hard_budget_respected(&self) -> bool {
867 self.mandatory_work_us
868 .saturating_add(self.reserved_spare_us)
869 .saturating_add(self.spent_optional_us)
870 <= self.frame_budget_us
871 }
872}
873
874#[derive(Debug, Clone)]
876pub struct DeferredRefinementScheduler {
877 config: DeferredRefinementConfig,
878 skipped_frames: BTreeMap<u64, u32>,
879}
880
881impl DeferredRefinementScheduler {
882 #[must_use]
884 pub fn new(config: DeferredRefinementConfig) -> Self {
885 Self {
886 config,
887 skipped_frames: BTreeMap::new(),
888 }
889 }
890
891 #[must_use]
893 pub fn config(&self) -> &DeferredRefinementConfig {
894 &self.config
895 }
896
897 #[must_use]
899 pub fn skipped_frames_for(&self, region_id: u64) -> u32 {
900 self.skipped_frames.get(®ion_id).copied().unwrap_or(0)
901 }
902
903 pub fn plan_frame(
909 &mut self,
910 frame_budget_us: u64,
911 mandatory_work_us: u64,
912 candidates: &[RefinementCandidate],
913 ) -> DeferredRefinementPlan {
914 let reserved_spare_us = self.config.min_spare_budget_us;
915 let available_after_mandatory = frame_budget_us.saturating_sub(mandatory_work_us);
916 let optional_budget_us = available_after_mandatory.saturating_sub(reserved_spare_us);
917
918 let mut scored = Vec::with_capacity(candidates.len());
919 for candidate in candidates.iter().copied() {
920 let skip_count = self.skipped_frames_for(candidate.region_id);
921 let fairness_boost = (skip_count as f64 * self.config.fairness_boost_per_skip)
922 .min(self.config.fairness_boost_cap);
923 let voi_gain = if candidate.voi_gain.is_finite() {
924 candidate.voi_gain.max(0.0)
925 } else {
926 0.0
927 };
928 let effective_voi = voi_gain + fairness_boost;
929 let normalized_cost = candidate.estimated_cost_us.max(1) as f64;
930 let score = effective_voi / normalized_cost;
931 scored.push((
932 candidate,
933 fairness_boost,
934 effective_voi,
935 score,
936 candidate.region_id,
937 ));
938 }
939
940 scored.sort_by(|a, b| {
943 b.3.total_cmp(&a.3)
944 .then_with(|| b.2.total_cmp(&a.2))
945 .then_with(|| a.4.cmp(&b.4))
946 });
947
948 let mut remaining_optional_us = optional_budget_us;
949 let mut selected = Vec::with_capacity(self.config.max_refinements_per_frame);
950 let mut selected_ids = BTreeMap::<u64, ()>::new();
951
952 for (candidate, fairness_boost, effective_voi, score, _) in scored {
953 if selected.len() >= self.config.max_refinements_per_frame {
954 break;
955 }
956 if effective_voi < self.config.voi_gain_cutoff {
957 continue;
958 }
959 if candidate.estimated_cost_us > remaining_optional_us {
960 continue;
961 }
962 selected.push(RefinementSelection {
963 region_id: candidate.region_id,
964 estimated_cost_us: candidate.estimated_cost_us,
965 voi_gain: if candidate.voi_gain.is_finite() {
966 candidate.voi_gain.max(0.0)
967 } else {
968 0.0
969 },
970 fairness_boost,
971 effective_voi,
972 score,
973 });
974 selected_ids.insert(candidate.region_id, ());
975 remaining_optional_us =
976 remaining_optional_us.saturating_sub(candidate.estimated_cost_us);
977 }
978
979 for candidate in candidates {
981 if selected_ids.contains_key(&candidate.region_id) {
982 self.skipped_frames.insert(candidate.region_id, 0);
983 } else {
984 let next = self
985 .skipped_frames_for(candidate.region_id)
986 .saturating_add(1);
987 self.skipped_frames.insert(candidate.region_id, next);
988 }
989 }
990
991 let spent_optional_us = optional_budget_us.saturating_sub(remaining_optional_us);
992 let plan = DeferredRefinementPlan {
993 frame_budget_us,
994 mandatory_work_us,
995 reserved_spare_us,
996 optional_budget_us,
997 spent_optional_us,
998 selected,
999 };
1000
1001 debug_assert!(plan.hard_budget_respected());
1002 plan
1003 }
1004}
1005
1006#[cfg(test)]
1011mod tests {
1012 use super::*;
1013 use proptest::prelude::*;
1014 use std::collections::HashMap;
1015 use std::sync::{Arc, Mutex};
1016 use tracing_subscriber::layer::SubscriberExt;
1017 use tracing_subscriber::registry::LookupSpan;
1018
1019 const FNV_OFFSET_BASIS: u64 = 0xcbf29ce484222325;
1020 const FNV_PRIME: u64 = 0x100000001b3;
1021
1022 fn hash_bytes(hash: &mut u64, bytes: &[u8]) {
1023 for byte in bytes {
1024 *hash ^= *byte as u64;
1025 *hash = hash.wrapping_mul(FNV_PRIME);
1026 }
1027 }
1028
1029 fn hash_u64(hash: &mut u64, value: u64) {
1030 hash_bytes(hash, &value.to_le_bytes());
1031 }
1032
1033 fn hash_f64(hash: &mut u64, value: f64) {
1034 hash_u64(hash, value.to_bits());
1035 }
1036
1037 fn decision_checksum(decisions: &[VoiDecision]) -> u64 {
1038 let mut hash = FNV_OFFSET_BASIS;
1039 for decision in decisions {
1040 hash_u64(&mut hash, decision.event_idx);
1041 hash_u64(&mut hash, decision.should_sample as u64);
1042 hash_u64(&mut hash, decision.forced_by_interval as u64);
1043 hash_u64(&mut hash, decision.blocked_by_min_interval as u64);
1044 hash_f64(&mut hash, decision.voi_gain);
1045 hash_f64(&mut hash, decision.score);
1046 hash_f64(&mut hash, decision.cost);
1047 hash_f64(&mut hash, decision.log_bayes_factor);
1048 hash_f64(&mut hash, decision.posterior_mean);
1049 hash_f64(&mut hash, decision.posterior_variance);
1050 hash_f64(&mut hash, decision.e_value);
1051 hash_f64(&mut hash, decision.e_threshold);
1052 hash_f64(&mut hash, decision.boundary_score);
1053 hash_u64(&mut hash, decision.events_since_sample);
1054 hash_f64(&mut hash, decision.time_since_sample_ms);
1055 }
1056 hash
1057 }
1058
1059 #[test]
1060 fn voi_gain_non_negative() {
1061 let mut sampler = VoiSampler::new(VoiConfig::default());
1062 let decision = sampler.decide(Instant::now());
1063 assert!(decision.voi_gain >= 0.0);
1064 }
1065
1066 #[test]
1067 fn forced_by_max_interval() {
1068 let config = VoiConfig {
1069 max_interval_events: 2,
1070 sample_cost: 1.0, ..Default::default()
1072 };
1073 let mut sampler = VoiSampler::new(config);
1074 let now = Instant::now();
1075
1076 let d1 = sampler.decide(now);
1077 assert!(!d1.forced_by_interval);
1078
1079 let d2 = sampler.decide(now + Duration::from_millis(1));
1080 assert!(d2.forced_by_interval);
1081 assert!(d2.should_sample);
1082 }
1083
1084 #[test]
1085 fn min_interval_blocks_sampling_after_first() {
1086 let config = VoiConfig {
1087 min_interval_events: 5,
1088 sample_cost: 0.0, ..Default::default()
1090 };
1091 let mut sampler = VoiSampler::new(config);
1092
1093 let first = sampler.decide(Instant::now());
1094 assert!(first.should_sample);
1095 sampler.observe(false);
1096
1097 let second = sampler.decide(Instant::now());
1098 assert!(second.blocked_by_min_interval);
1099 assert!(!second.should_sample);
1100 }
1101
1102 #[test]
1103 fn variance_shrinks_with_samples() {
1104 let mut sampler = VoiSampler::new(VoiConfig::default());
1105 let mut now = Instant::now();
1106 let mut variances = Vec::new();
1107 for _ in 0..5 {
1108 let decision = sampler.decide(now);
1109 if decision.should_sample {
1110 sampler.observe_at(false, now);
1111 }
1112 variances.push(beta_variance(sampler.alpha, sampler.beta));
1113 now += Duration::from_millis(1);
1114 }
1115 for window in variances.windows(2) {
1116 assert!(window[1] <= window[0] + 1e-9);
1117 }
1118 }
1119
1120 #[test]
1121 fn decision_checksum_is_stable() {
1122 let config = VoiConfig {
1123 sample_cost: 0.01,
1124 ..Default::default()
1125 };
1126 let mut now = Instant::now();
1127 let mut sampler = VoiSampler::new_at(config, now);
1128
1129 let mut state: u64 = 42;
1130 let mut decisions = Vec::new();
1131
1132 for _ in 0..32 {
1133 let decision = sampler.decide(now);
1134 let violated = lcg_next(&mut state).is_multiple_of(10);
1135 if decision.should_sample {
1136 sampler.observe_at(violated, now);
1137 }
1138 decisions.push(decision);
1139 now += Duration::from_millis(5 + (lcg_next(&mut state) % 7));
1140 }
1141
1142 let checksum = decision_checksum(&decisions);
1143 assert_eq!(checksum, 0x0b51_d8b6_47a7_b00c);
1144 }
1145
1146 #[test]
1147 fn logs_render_jsonl() {
1148 let config = VoiConfig {
1149 enable_logging: true,
1150 ..Default::default()
1151 };
1152 let mut sampler = VoiSampler::new(config);
1153 let decision = sampler.decide(Instant::now());
1154 if decision.should_sample {
1155 sampler.observe(false);
1156 }
1157 let jsonl = sampler.logs_to_jsonl();
1158 assert!(jsonl.contains("\"event\":\"voi_decision\""));
1159 }
1160
1161 proptest! {
1162 #[test]
1163 fn prop_voi_gain_non_negative(alpha in 0.01f64..10.0, beta in 0.01f64..10.0) {
1164 let var = beta_variance(alpha, beta);
1165 let expected_after = expected_variance_after(alpha, beta);
1166 prop_assert!(var + 1e-12 >= expected_after);
1167 }
1168
1169 #[test]
1170 fn prop_e_value_stays_positive(seq in proptest::collection::vec(any::<bool>(), 1..50)) {
1171 let mut sampler = VoiSampler::new(VoiConfig::default());
1172 let mut now = Instant::now();
1173 for violated in seq {
1174 let decision = sampler.decide(now);
1175 if decision.should_sample {
1176 sampler.observe_at(violated, now);
1177 }
1178 now += Duration::from_millis(1);
1179 prop_assert!(sampler.e_value >= E_MIN - 1e-12);
1180 }
1181 }
1182
1183 #[test]
1184 fn prop_voi_decision_to_jsonl_valid_json(
1185 event_idx in any::<u64>(),
1186 should_sample in any::<bool>(),
1187 forced in any::<bool>(),
1188 blocked in any::<bool>(),
1189 voi_gain in -100.0f64..100.0f64,
1190 score in -100.0f64..100.0f64,
1191 cost in 0.0f64..100.0f64,
1192 log_bayes_factor in -50.0f64..50.0f64,
1193 posterior_mean in 0.0f64..1.0f64,
1194 posterior_variance in 0.0f64..1.0f64,
1195 e_value in 0.0f64..100.0f64,
1196 e_threshold in 1.0f64..100.0f64,
1197 boundary_score in 0.0f64..1.0f64,
1198 events_since_sample in any::<u64>(),
1199 time_since_sample_ms in 0.0f64..100_000.0f64,
1200 reason_idx in 0..5usize,
1201 ) {
1202 let reasons = [
1203 "forced_max_interval",
1204 "blocked_min_interval",
1205 "score_exceeds_cost",
1206 "e_value_threshold",
1207 "test_reason",
1208 ];
1209 let reason = reasons[reason_idx];
1210 let decision = VoiDecision {
1211 event_idx,
1212 should_sample,
1213 forced_by_interval: forced,
1214 blocked_by_min_interval: blocked,
1215 voi_gain,
1216 score,
1217 cost,
1218 log_bayes_factor,
1219 posterior_mean,
1220 posterior_variance,
1221 e_value,
1222 e_threshold,
1223 boundary_score,
1224 events_since_sample,
1225 time_since_sample_ms,
1226 reason,
1227 };
1228 let jsonl = decision.to_jsonl();
1229 let parsed: serde_json::Value = serde_json::from_str(&jsonl).expect("valid json");
1230 prop_assert_eq!(parsed["event"].as_str(), Some("voi_decision"));
1231 prop_assert_eq!(parsed["schema_version"].as_str(), Some("ftui-evidence-v1"));
1232 prop_assert_eq!(parsed["should_sample"].as_bool(), Some(should_sample));
1233 prop_assert_eq!(parsed["forced"].as_bool(), Some(forced));
1234 prop_assert_eq!(parsed["blocked"].as_bool(), Some(blocked));
1235 }
1236 }
1237
1238 #[test]
1243 fn perf_voi_sampling_budget() {
1244 use std::io::Write as _;
1245
1246 const RUNS: usize = 60;
1247 let mut sampler = VoiSampler::new(VoiConfig::default());
1248 let mut now = Instant::now();
1249 let mut samples = Vec::with_capacity(RUNS);
1250 let mut jsonl = Vec::new();
1251
1252 for i in 0..RUNS {
1253 let start = Instant::now();
1254 let decision = sampler.decide(now);
1255 let violated = i % 11 == 0;
1256 if decision.should_sample {
1257 sampler.observe_at(violated, now);
1258 }
1259 let elapsed_ns = start.elapsed().as_nanos() as u64;
1260 samples.push(elapsed_ns);
1261
1262 writeln!(
1263 &mut jsonl,
1264 "{{\"test\":\"voi_sampling\",\"case\":\"decision\",\"idx\":{},\
1265\"elapsed_ns\":{},\"sample\":{},\"violated\":{},\"e_value\":{:.6}}}",
1266 i, elapsed_ns, decision.should_sample, violated, sampler.e_value
1267 )
1268 .expect("jsonl write failed");
1269
1270 now += Duration::from_millis(1);
1271 }
1272
1273 fn percentile(samples: &mut [u64], p: f64) -> u64 {
1274 samples.sort_unstable();
1275 let idx = ((samples.len() as f64 - 1.0) * p).round() as usize;
1276 samples[idx]
1277 }
1278
1279 let mut samples_sorted = samples.clone();
1280 let _p50 = percentile(&mut samples_sorted, 0.50);
1281 let p95 = percentile(&mut samples_sorted, 0.95);
1282 let p99 = percentile(&mut samples_sorted, 0.99);
1283
1284 let (budget_p95, budget_p99) = if cfg!(debug_assertions) {
1285 (200_000, 400_000)
1286 } else {
1287 (20_000, 40_000)
1288 };
1289
1290 assert!(p95 <= budget_p95, "p95 {p95}ns exceeds {budget_p95}ns");
1291 assert!(p99 <= budget_p99, "p99 {p99}ns exceeds {budget_p99}ns");
1292
1293 let text = String::from_utf8(jsonl).expect("jsonl utf8");
1294 print!("{text}");
1295 assert_eq!(text.lines().count(), RUNS);
1296 }
1297
1298 #[test]
1303 fn e2e_deterministic_jsonl() {
1304 use std::io::Write as _;
1305
1306 let seed = std::env::var("VOI_SEED")
1307 .ok()
1308 .and_then(|s| s.parse::<u64>().ok())
1309 .unwrap_or(0);
1310
1311 let config = VoiConfig {
1312 enable_logging: false,
1313 ..Default::default()
1314 };
1315 let mut now = Instant::now();
1316 let mut sampler = VoiSampler::new_at(config, now);
1317 let mut state = seed;
1318 let mut decisions = Vec::new();
1319 let mut jsonl = Vec::new();
1320
1321 for idx in 0..40u64 {
1322 let decision = sampler.decide(now);
1323 let violated = lcg_next(&mut state).is_multiple_of(7);
1324 if decision.should_sample {
1325 sampler.observe_at(violated, now);
1326 }
1327 decisions.push(decision.clone());
1328
1329 writeln!(
1330 &mut jsonl,
1331 "{{\"event\":\"voi_decision\",\"seed\":{},\"idx\":{},\
1332\"sample\":{},\"violated\":{},\"voi_gain\":{:.6}}}",
1333 seed, idx, decision.should_sample, violated, decision.voi_gain
1334 )
1335 .expect("jsonl write failed");
1336
1337 now += Duration::from_millis(3 + (lcg_next(&mut state) % 5));
1338 }
1339
1340 let checksum = decision_checksum(&decisions);
1341 writeln!(
1342 &mut jsonl,
1343 "{{\"event\":\"voi_checksum\",\"seed\":{},\"checksum\":\"{checksum:016x}\",\"decisions\":{}}}",
1344 seed,
1345 decisions.len()
1346 )
1347 .expect("jsonl write failed");
1348
1349 let text = String::from_utf8(jsonl).expect("jsonl utf8");
1350 print!("{text}");
1351 assert!(text.contains("\"event\":\"voi_checksum\""));
1352 }
1353
1354 fn lcg_next(state: &mut u64) -> u64 {
1355 *state = state.wrapping_mul(6364136223846793005).wrapping_add(1);
1356 *state
1357 }
1358
1359 #[test]
1364 fn default_config_values() {
1365 let cfg = VoiConfig::default();
1366 assert!((cfg.alpha - 0.05).abs() < f64::EPSILON);
1367 assert!((cfg.prior_alpha - 1.0).abs() < f64::EPSILON);
1368 assert!((cfg.prior_beta - 1.0).abs() < f64::EPSILON);
1369 assert!((cfg.mu_0 - 0.05).abs() < f64::EPSILON);
1370 assert!((cfg.lambda - 0.5).abs() < f64::EPSILON);
1371 assert_eq!(cfg.max_interval_ms, 250);
1372 assert_eq!(cfg.max_interval_events, 20);
1373 assert_eq!(cfg.min_interval_ms, 0);
1374 assert_eq!(cfg.min_interval_events, 0);
1375 assert!(!cfg.enable_logging);
1376 }
1377
1378 #[test]
1379 fn config_clamping_prior_alpha_beta() {
1380 let config = VoiConfig {
1381 prior_alpha: -1.0,
1382 prior_beta: 0.0,
1383 ..Default::default()
1384 };
1385 let sampler = VoiSampler::new(config);
1386 let (a, b) = sampler.posterior_params();
1387 assert!(a > 0.0, "alpha should be clamped above zero");
1388 assert!(b > 0.0, "beta should be clamped above zero");
1389 }
1390
1391 #[test]
1392 fn config_clamping_mu_0() {
1393 let config = VoiConfig {
1394 mu_0: -0.5,
1395 ..Default::default()
1396 };
1397 let sampler = VoiSampler::new(config);
1398 let mean = sampler.posterior_mean();
1399 assert!((0.0..=1.0).contains(&mean));
1400 }
1401
1402 #[test]
1403 fn config_clamping_sample_cost() {
1404 let config = VoiConfig {
1405 sample_cost: -1.0,
1406 ..Default::default()
1407 };
1408 let mut sampler = VoiSampler::new(config);
1409 let d = sampler.decide(Instant::now());
1410 assert!(d.cost > 0.0, "cost should be clamped above zero");
1411 }
1412
1413 #[test]
1414 fn accessor_config() {
1415 let config = VoiConfig {
1416 alpha: 0.1,
1417 ..Default::default()
1418 };
1419 let sampler = VoiSampler::new(config);
1420 assert!((sampler.config().alpha - 0.1).abs() < f64::EPSILON);
1421 }
1422
1423 #[test]
1424 fn accessor_posterior_params() {
1425 let config = VoiConfig {
1426 prior_alpha: 3.0,
1427 prior_beta: 7.0,
1428 ..Default::default()
1429 };
1430 let sampler = VoiSampler::new(config);
1431 let (a, b) = sampler.posterior_params();
1432 assert!((a - 3.0).abs() < f64::EPSILON);
1433 assert!((b - 7.0).abs() < f64::EPSILON);
1434 }
1435
1436 #[test]
1437 fn accessor_posterior_mean() {
1438 let config = VoiConfig {
1439 prior_alpha: 2.0,
1440 prior_beta: 8.0,
1441 ..Default::default()
1442 };
1443 let sampler = VoiSampler::new(config);
1444 assert!((sampler.posterior_mean() - 0.2).abs() < 1e-9);
1446 }
1447
1448 #[test]
1449 fn accessor_posterior_variance() {
1450 let sampler = VoiSampler::new(VoiConfig::default());
1451 let var = sampler.posterior_variance();
1452 assert!(var >= 0.0);
1453 assert!(var <= 0.25); }
1455
1456 #[test]
1457 fn accessor_expected_variance_after() {
1458 let sampler = VoiSampler::new(VoiConfig::default());
1459 let before = sampler.posterior_variance();
1460 let after = sampler.expected_variance_after();
1461 assert!(
1462 after <= before + 1e-12,
1463 "expected variance after should not exceed current"
1464 );
1465 }
1466
1467 #[test]
1468 fn last_decision_initially_none() {
1469 let sampler = VoiSampler::new(VoiConfig::default());
1470 assert!(sampler.last_decision().is_none());
1471 }
1472
1473 #[test]
1474 fn last_decision_after_decide() {
1475 let mut sampler = VoiSampler::new(VoiConfig::default());
1476 sampler.decide(Instant::now());
1477 assert!(sampler.last_decision().is_some());
1478 }
1479
1480 #[test]
1481 fn last_observation_initially_none() {
1482 let sampler = VoiSampler::new(VoiConfig::default());
1483 assert!(sampler.last_observation().is_none());
1484 }
1485
1486 #[test]
1487 fn last_observation_after_observe() {
1488 let mut sampler = VoiSampler::new(VoiConfig::default());
1489 sampler.decide(Instant::now());
1490 sampler.observe(false);
1491 assert!(sampler.last_observation().is_some());
1492 assert!(!sampler.last_observation().unwrap().violated);
1493 }
1494
1495 #[test]
1496 fn observe_violation_updates_alpha() {
1497 let mut sampler = VoiSampler::new(VoiConfig::default());
1498 let (a_before, _) = sampler.posterior_params();
1499 sampler.decide(Instant::now());
1500 sampler.observe(true);
1501 let (a_after, _) = sampler.posterior_params();
1502 assert!((a_after - a_before - 1.0).abs() < 1e-9);
1503 }
1504
1505 #[test]
1506 fn observe_no_violation_updates_beta() {
1507 let mut sampler = VoiSampler::new(VoiConfig::default());
1508 let (_, b_before) = sampler.posterior_params();
1509 sampler.decide(Instant::now());
1510 sampler.observe(false);
1511 let (_, b_after) = sampler.posterior_params();
1512 assert!((b_after - b_before - 1.0).abs() < 1e-9);
1513 }
1514
1515 #[test]
1516 fn e_value_positive_after_violations() {
1517 let mut sampler = VoiSampler::new(VoiConfig::default());
1518 let mut now = Instant::now();
1519 for _ in 0..10 {
1520 sampler.decide(now);
1521 sampler.observe_at(true, now);
1522 now += Duration::from_millis(1);
1523 }
1524 let summary = sampler.summary();
1525 assert!(summary.e_value > 0.0);
1526 }
1527
1528 #[test]
1529 fn summary_initial_state() {
1530 let sampler = VoiSampler::new(VoiConfig::default());
1531 let summary = sampler.summary();
1532 assert_eq!(summary.total_events, 0);
1533 assert_eq!(summary.total_samples, 0);
1534 assert_eq!(summary.forced_samples, 0);
1535 assert_eq!(summary.skipped_events, 0);
1536 assert!((summary.avg_events_between_samples).abs() < f64::EPSILON);
1537 }
1538
1539 #[test]
1540 fn summary_after_observations() {
1541 let mut sampler = VoiSampler::new(VoiConfig::default());
1542 let now = Instant::now();
1543 sampler.decide(now);
1544 sampler.observe_at(false, now);
1545 sampler.decide(now + Duration::from_millis(10));
1546 let summary = sampler.summary();
1547 assert_eq!(summary.total_events, 2);
1548 assert_eq!(summary.total_samples, 1);
1549 assert_eq!(summary.skipped_events, 1);
1550 }
1551
1552 #[test]
1553 fn mark_forced_sample_increments() {
1554 let mut sampler = VoiSampler::new(VoiConfig::default());
1555 assert_eq!(sampler.summary().forced_samples, 0);
1556 sampler.mark_forced_sample();
1557 sampler.mark_forced_sample();
1558 assert_eq!(sampler.summary().forced_samples, 2);
1559 }
1560
1561 #[test]
1562 fn snapshot_captures_state() {
1563 let mut sampler = VoiSampler::new(VoiConfig {
1564 enable_logging: true,
1565 ..Default::default()
1566 });
1567 let now = Instant::now();
1568 sampler.decide(now);
1569 sampler.observe_at(false, now);
1570
1571 let snap = sampler.snapshot(10, 42);
1572 assert_eq!(snap.captured_ms, 42);
1573 assert!(snap.alpha > 0.0);
1574 assert!(snap.beta > 0.0);
1575 assert!((0.0..=1.0).contains(&snap.posterior_mean));
1576 assert!(snap.last_decision.is_some());
1577 assert!(snap.last_observation.is_some());
1578 }
1579
1580 #[test]
1581 fn log_rotation_respects_max_entries() {
1582 let config = VoiConfig {
1583 enable_logging: true,
1584 max_log_entries: 3,
1585 ..Default::default()
1586 };
1587 let mut sampler = VoiSampler::new(config);
1588 let mut now = Instant::now();
1589
1590 for _ in 0..10 {
1591 let d = sampler.decide(now);
1592 if d.should_sample {
1593 sampler.observe_at(false, now);
1594 }
1595 now += Duration::from_millis(300);
1596 }
1597
1598 assert!(sampler.logs().len() <= 3);
1599 }
1600
1601 #[test]
1602 fn logs_empty_when_logging_disabled() {
1603 let config = VoiConfig {
1604 enable_logging: false,
1605 ..Default::default()
1606 };
1607 let mut sampler = VoiSampler::new(config);
1608 sampler.decide(Instant::now());
1609 assert!(sampler.logs().is_empty());
1610 }
1611
1612 #[test]
1613 fn decision_jsonl_format() {
1614 let mut sampler = VoiSampler::new(VoiConfig::default());
1615 let decision = sampler.decide(Instant::now());
1616 let jsonl = decision.to_jsonl();
1617 assert!(jsonl.starts_with('{'));
1618 assert!(jsonl.ends_with('}'));
1619 assert!(jsonl.contains("\"event\":\"voi_decision\""));
1620 assert!(jsonl.contains("\"should_sample\":"));
1621 assert!(jsonl.contains("\"reason\":"));
1622 }
1623
1624 #[test]
1625 fn observation_jsonl_format() {
1626 let mut sampler = VoiSampler::new(VoiConfig::default());
1627 sampler.decide(Instant::now());
1628 let obs = sampler.observe(false);
1629 let jsonl = obs.to_jsonl();
1630 assert!(jsonl.starts_with('{'));
1631 assert!(jsonl.ends_with('}'));
1632 assert!(jsonl.contains("\"event\":\"voi_observe\""));
1633 assert!(jsonl.contains("\"violated\":false"));
1634 }
1635
1636 #[test]
1637 fn log_entry_jsonl_decision_variant() {
1638 let mut sampler = VoiSampler::new(VoiConfig::default());
1639 let decision = sampler.decide(Instant::now());
1640 let entry = VoiLogEntry::Decision(decision);
1641 let jsonl = entry.to_jsonl();
1642 assert!(jsonl.contains("\"event\":\"voi_decision\""));
1643 }
1644
1645 #[test]
1646 fn log_entry_jsonl_observation_variant() {
1647 let mut sampler = VoiSampler::new(VoiConfig::default());
1648 sampler.decide(Instant::now());
1649 let obs = sampler.observe(true);
1650 let entry = VoiLogEntry::Observation(obs);
1651 let jsonl = entry.to_jsonl();
1652 assert!(jsonl.contains("\"event\":\"voi_observe\""));
1653 assert!(jsonl.contains("\"violated\":true"));
1654 }
1655
1656 #[test]
1657 fn time_based_max_interval_forces_sample() {
1658 let config = VoiConfig {
1659 max_interval_ms: 100,
1660 max_interval_events: 0, sample_cost: 100.0, ..Default::default()
1663 };
1664 let now = Instant::now();
1665 let mut sampler = VoiSampler::new_at(config, now);
1666
1667 let _d1 = sampler.decide(now + Duration::from_millis(1));
1669 sampler.observe_at(false, now + Duration::from_millis(1));
1670
1671 let d2 = sampler.decide(now + Duration::from_millis(10));
1673 assert!(!d2.forced_by_interval, "should not force within 100ms");
1674
1675 let d3 = sampler.decide(now + Duration::from_millis(110));
1677 assert!(d3.forced_by_interval, "should force after 100ms");
1678 assert!(d3.should_sample);
1679 }
1680
1681 #[test]
1682 fn time_based_min_interval_blocks() {
1683 let config = VoiConfig {
1684 min_interval_ms: 50,
1685 min_interval_events: 0,
1686 ..Default::default()
1687 };
1688 let now = Instant::now();
1689 let mut sampler = VoiSampler::new_at(config, now);
1690
1691 let d1 = sampler.decide(now);
1693 assert!(d1.should_sample);
1694 sampler.observe_at(false, now);
1695
1696 let d2 = sampler.decide(now + Duration::from_millis(10));
1698 assert!(d2.blocked_by_min_interval);
1699 assert!(!d2.should_sample);
1700
1701 let d3 = sampler.decide(now + Duration::from_millis(60));
1703 assert!(!d3.blocked_by_min_interval);
1704 }
1705
1706 #[test]
1707 fn decision_reason_strings() {
1708 let config = VoiConfig {
1710 max_interval_events: 1,
1711 ..Default::default()
1712 };
1713 let mut sampler = VoiSampler::new(config);
1714 let d = sampler.decide(Instant::now());
1715 assert_eq!(d.reason, "forced_interval");
1716 }
1717
1718 #[test]
1719 fn decision_reason_min_interval() {
1720 let config = VoiConfig {
1721 min_interval_events: 100,
1722 sample_cost: 0.0,
1723 ..Default::default()
1724 };
1725 let mut sampler = VoiSampler::new(config);
1726 sampler.decide(Instant::now());
1727 sampler.observe(false);
1728 let d = sampler.decide(Instant::now());
1729 assert_eq!(d.reason, "min_interval");
1730 }
1731
1732 #[test]
1733 fn beta_mean_basic() {
1734 assert!((beta_mean(1.0, 1.0) - 0.5).abs() < 1e-9);
1735 assert!((beta_mean(2.0, 8.0) - 0.2).abs() < 1e-9);
1736 assert!((beta_mean(5.0, 5.0) - 0.5).abs() < 1e-9);
1737 }
1738
1739 #[test]
1740 fn beta_variance_basic() {
1741 let var = beta_variance(1.0, 1.0);
1743 assert!((var - 1.0 / 12.0).abs() < 1e-9);
1744 }
1745
1746 #[test]
1747 fn beta_variance_degenerate() {
1748 assert!((beta_variance(0.0, 0.0)).abs() < f64::EPSILON);
1749 assert!((beta_variance(-1.0, -1.0)).abs() < f64::EPSILON);
1750 }
1751
1752 #[test]
1753 fn boundary_score_at_threshold() {
1754 let score = boundary_score(20.0, 20.0);
1756 assert!((score - 1.0).abs() < 1e-9);
1757 }
1758
1759 #[test]
1760 fn boundary_score_far_from_threshold() {
1761 let score = boundary_score(1.0, 1e6);
1763 assert!(score < 0.1);
1764 }
1765
1766 #[test]
1767 fn logs_to_jsonl_multiple_entries() {
1768 let config = VoiConfig {
1769 enable_logging: true,
1770 ..Default::default()
1771 };
1772 let mut sampler = VoiSampler::new(config);
1773 let mut now = Instant::now();
1774 for _ in 0..5 {
1775 let d = sampler.decide(now);
1776 if d.should_sample {
1777 sampler.observe_at(false, now);
1778 }
1779 now += Duration::from_millis(300);
1780 }
1781 let jsonl = sampler.logs_to_jsonl();
1782 let line_count = jsonl.lines().count();
1783 assert!(
1784 line_count >= 2,
1785 "should have at least 2 log lines, got {line_count}"
1786 );
1787 }
1788
1789 #[derive(Debug, Clone)]
1794 #[allow(dead_code)]
1795 struct CapturedSpan {
1796 name: String,
1797 target: String,
1798 level: tracing::Level,
1799 fields: HashMap<String, String>,
1800 parent_name: Option<String>,
1801 }
1802
1803 #[derive(Debug, Clone)]
1804 #[allow(dead_code)]
1805 struct CapturedEvent {
1806 level: tracing::Level,
1807 target: String,
1808 message: String,
1809 fields: HashMap<String, String>,
1810 parent_span_name: Option<String>,
1811 }
1812
1813 struct SpanCapture {
1814 spans: Arc<Mutex<Vec<CapturedSpan>>>,
1815 events: Arc<Mutex<Vec<CapturedEvent>>>,
1816 span_index: Arc<Mutex<HashMap<u64, usize>>>,
1817 }
1818
1819 impl SpanCapture {
1820 fn new() -> (Self, CaptureHandle) {
1821 let spans = Arc::new(Mutex::new(Vec::new()));
1822 let events = Arc::new(Mutex::new(Vec::new()));
1823 let span_index = Arc::new(Mutex::new(HashMap::new()));
1824
1825 let handle = CaptureHandle {
1826 spans: spans.clone(),
1827 events: events.clone(),
1828 };
1829
1830 (
1831 Self {
1832 spans,
1833 events,
1834 span_index,
1835 },
1836 handle,
1837 )
1838 }
1839 }
1840
1841 struct CaptureHandle {
1842 spans: Arc<Mutex<Vec<CapturedSpan>>>,
1843 events: Arc<Mutex<Vec<CapturedEvent>>>,
1844 }
1845
1846 impl CaptureHandle {
1847 fn spans(&self) -> Vec<CapturedSpan> {
1848 self.spans.lock().unwrap().clone()
1849 }
1850
1851 fn events(&self) -> Vec<CapturedEvent> {
1852 self.events.lock().unwrap().clone()
1853 }
1854 }
1855
1856 struct FieldVisitor(Vec<(String, String)>);
1857
1858 impl tracing::field::Visit for FieldVisitor {
1859 fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
1860 self.0
1861 .push((field.name().to_string(), format!("{value:?}")));
1862 }
1863
1864 fn record_u64(&mut self, field: &tracing::field::Field, value: u64) {
1865 self.0.push((field.name().to_string(), value.to_string()));
1866 }
1867
1868 fn record_i64(&mut self, field: &tracing::field::Field, value: i64) {
1869 self.0.push((field.name().to_string(), value.to_string()));
1870 }
1871
1872 fn record_f64(&mut self, field: &tracing::field::Field, value: f64) {
1873 self.0.push((field.name().to_string(), value.to_string()));
1874 }
1875
1876 fn record_str(&mut self, field: &tracing::field::Field, value: &str) {
1877 self.0.push((field.name().to_string(), value.to_string()));
1878 }
1879
1880 fn record_bool(&mut self, field: &tracing::field::Field, value: bool) {
1881 self.0.push((field.name().to_string(), value.to_string()));
1882 }
1883 }
1884
1885 impl<S> tracing_subscriber::Layer<S> for SpanCapture
1886 where
1887 S: tracing::Subscriber + for<'a> LookupSpan<'a>,
1888 {
1889 fn on_new_span(
1890 &self,
1891 attrs: &tracing::span::Attributes<'_>,
1892 id: &tracing::span::Id,
1893 ctx: tracing_subscriber::layer::Context<'_, S>,
1894 ) {
1895 let mut visitor = FieldVisitor(Vec::new());
1896 attrs.record(&mut visitor);
1897
1898 let parent_name = ctx
1899 .current_span()
1900 .id()
1901 .and_then(|pid| ctx.span(pid))
1902 .map(|span_ref| span_ref.name().to_string());
1903
1904 let mut fields: HashMap<String, String> = visitor.0.into_iter().collect();
1905 for field in attrs.metadata().fields() {
1906 fields.entry(field.name().to_string()).or_default();
1907 }
1908
1909 let mut spans = self.spans.lock().unwrap();
1910 let idx = spans.len();
1911 spans.push(CapturedSpan {
1912 name: attrs.metadata().name().to_string(),
1913 target: attrs.metadata().target().to_string(),
1914 level: *attrs.metadata().level(),
1915 fields,
1916 parent_name,
1917 });
1918
1919 self.span_index.lock().unwrap().insert(id.into_u64(), idx);
1920 }
1921
1922 fn on_record(
1923 &self,
1924 id: &tracing::span::Id,
1925 values: &tracing::span::Record<'_>,
1926 _ctx: tracing_subscriber::layer::Context<'_, S>,
1927 ) {
1928 let mut visitor = FieldVisitor(Vec::new());
1929 values.record(&mut visitor);
1930
1931 let index = self.span_index.lock().unwrap();
1932 if let Some(&idx) = index.get(&id.into_u64()) {
1933 let mut spans = self.spans.lock().unwrap();
1934 if let Some(span) = spans.get_mut(idx) {
1935 for (k, v) in visitor.0 {
1936 span.fields.insert(k, v);
1937 }
1938 }
1939 }
1940 }
1941
1942 fn on_event(
1943 &self,
1944 event: &tracing::Event<'_>,
1945 ctx: tracing_subscriber::layer::Context<'_, S>,
1946 ) {
1947 let mut visitor = FieldVisitor(Vec::new());
1948 event.record(&mut visitor);
1949
1950 let fields: HashMap<String, String> = visitor.0.clone().into_iter().collect();
1951 let message = visitor
1952 .0
1953 .iter()
1954 .find(|(k, _)| k == "message")
1955 .map(|(_, v)| v.clone())
1956 .unwrap_or_default();
1957
1958 let parent_span_name = ctx
1959 .current_span()
1960 .id()
1961 .and_then(|id| ctx.span(id))
1962 .map(|span_ref| span_ref.name().to_string());
1963
1964 self.events.lock().unwrap().push(CapturedEvent {
1965 level: *event.metadata().level(),
1966 target: event.metadata().target().to_string(),
1967 message,
1968 fields,
1969 parent_span_name,
1970 });
1971 }
1972 }
1973
1974 fn with_captured_tracing<F>(f: F) -> CaptureHandle
1975 where
1976 F: FnOnce(),
1977 {
1978 let (layer, handle) = SpanCapture::new();
1979 let subscriber = tracing_subscriber::registry().with(layer);
1980 tracing::subscriber::with_default(subscriber, f);
1981 handle
1982 }
1983
1984 #[test]
1989 fn span_voi_evaluate_has_required_fields() {
1990 let handle = with_captured_tracing(|| {
1991 let mut sampler = VoiSampler::new(VoiConfig::default());
1992 sampler.decide(Instant::now());
1993 });
1994
1995 let spans = handle.spans();
1996 let voi_spans: Vec<_> = spans.iter().filter(|s| s.name == "voi.evaluate").collect();
1997 assert!(
1998 !voi_spans.is_empty(),
1999 "expected at least one voi.evaluate span, got none"
2000 );
2001
2002 let span = &voi_spans[0];
2003 assert!(
2004 span.fields.contains_key("decision_context"),
2005 "missing decision_context field"
2006 );
2007 assert!(
2008 span.fields.contains_key("voi_estimate"),
2009 "missing voi_estimate field"
2010 );
2011 assert!(
2012 span.fields.contains_key("sample_cost"),
2013 "missing sample_cost field"
2014 );
2015 assert!(
2016 span.fields.contains_key("sample_decision"),
2017 "missing sample_decision field"
2018 );
2019 }
2020
2021 #[test]
2022 fn span_voi_evaluate_decision_context_values() {
2023 let handle = with_captured_tracing(|| {
2024 let config = VoiConfig {
2026 max_interval_events: 0,
2027 max_interval_ms: 0,
2028 sample_cost: 1000.0,
2029 ..Default::default()
2030 };
2031 let mut sampler = VoiSampler::new(config);
2032 sampler.decide(Instant::now());
2033 });
2034
2035 let spans = handle.spans();
2036 let voi_spans: Vec<_> = spans.iter().filter(|s| s.name == "voi.evaluate").collect();
2037 assert!(!voi_spans.is_empty());
2038
2039 let ctx = &voi_spans[0].fields["decision_context"];
2040 assert!(
2041 ctx == "voi_lt_cost" || ctx == "voi_ge_cost",
2042 "unexpected context: {ctx}"
2043 );
2044 }
2045
2046 #[test]
2047 fn span_voi_evaluate_forced_interval_context() {
2048 let handle = with_captured_tracing(|| {
2049 let config = VoiConfig {
2050 max_interval_events: 1,
2051 ..Default::default()
2052 };
2053 let mut sampler = VoiSampler::new(config);
2054 sampler.decide(Instant::now());
2055 });
2056
2057 let spans = handle.spans();
2058 let voi_spans: Vec<_> = spans.iter().filter(|s| s.name == "voi.evaluate").collect();
2059 assert!(!voi_spans.is_empty());
2060 assert_eq!(voi_spans[0].fields["decision_context"], "forced_interval");
2061 }
2062
2063 #[test]
2068 fn debug_log_voi_calculation() {
2069 let handle = with_captured_tracing(|| {
2070 let mut sampler = VoiSampler::new(VoiConfig::default());
2071 sampler.decide(Instant::now());
2072 });
2073
2074 let events = handle.events();
2075 let debug_events: Vec<_> = events
2076 .iter()
2077 .filter(|e| {
2078 e.level == tracing::Level::DEBUG
2079 && e.target == crate::telemetry_schema::TARGET_VOI
2080 && e.fields.contains_key("voi_gain")
2081 })
2082 .collect();
2083
2084 assert!(
2085 !debug_events.is_empty(),
2086 "expected at least one DEBUG voi calculation event"
2087 );
2088
2089 let evt = &debug_events[0];
2090 assert!(evt.fields.contains_key("score"), "missing score field");
2091 assert!(evt.fields.contains_key("cost"), "missing cost field");
2092 assert!(
2093 evt.fields.contains_key("posterior_mean"),
2094 "missing posterior_mean"
2095 );
2096 assert!(
2097 evt.fields.contains_key("boundary_score"),
2098 "missing boundary_score"
2099 );
2100 }
2101
2102 #[test]
2103 fn debug_log_voi_estimate_histogram() {
2104 let handle = with_captured_tracing(|| {
2105 let mut sampler = VoiSampler::new(VoiConfig::default());
2106 sampler.decide(Instant::now());
2107 });
2108
2109 let events = handle.events();
2110 let hist_events: Vec<_> = events
2111 .iter()
2112 .filter(|e| {
2113 e.level == tracing::Level::DEBUG
2114 && e.target == crate::telemetry_schema::TARGET_VOI
2115 && e.fields.contains_key("voi_estimate_value")
2116 })
2117 .collect();
2118
2119 assert!(
2120 !hist_events.is_empty(),
2121 "expected voi_estimate_value histogram event"
2122 );
2123 }
2124
2125 #[test]
2130 fn trace_log_utility_estimate_after_observation() {
2131 let handle = with_captured_tracing(|| {
2132 let mut sampler = VoiSampler::new(VoiConfig::default());
2133 let now = Instant::now();
2134 sampler.decide(now);
2135 sampler.observe_at(false, now);
2136 });
2137
2138 let events = handle.events();
2139 let trace_events: Vec<_> = events
2140 .iter()
2141 .filter(|e| {
2142 e.level == tracing::Level::TRACE
2143 && e.target == crate::telemetry_schema::TARGET_VOI
2144 && e.fields.contains_key("voi_estimate_value")
2145 })
2146 .collect();
2147
2148 assert!(
2149 !trace_events.is_empty(),
2150 "expected TRACE utility estimate event after observe"
2151 );
2152
2153 let evt = &trace_events[0];
2154 assert!(evt.fields.contains_key("alpha"), "missing alpha");
2155 assert!(evt.fields.contains_key("beta"), "missing beta");
2156 assert!(
2157 evt.fields.contains_key("posterior_mean"),
2158 "missing posterior_mean"
2159 );
2160 assert!(evt.fields.contains_key("e_value"), "missing e_value");
2161 }
2162
2163 #[test]
2168 fn counters_increment_on_sample_decision() {
2169 let handle = with_captured_tracing(|| {
2170 let mut sampler = VoiSampler::new(VoiConfig::default());
2171 let mut now = Instant::now();
2172 for _ in 0..5 {
2173 let d = sampler.decide(now);
2174 if d.should_sample {
2175 sampler.observe_at(false, now);
2176 }
2177 now += Duration::from_millis(100);
2178 }
2179 });
2180
2181 let events = handle.events();
2185 let calc_events: Vec<_> = events
2186 .iter()
2187 .filter(|e| {
2188 e.level == tracing::Level::DEBUG
2189 && e.target == crate::telemetry_schema::TARGET_VOI
2190 && e.fields.contains_key("voi_gain")
2191 })
2192 .collect();
2193
2194 assert_eq!(
2195 calc_events.len(),
2196 5,
2197 "expected 5 voi calculation events for 5 decide() calls"
2198 );
2199 }
2200
2201 #[test]
2202 fn counter_accessors_are_callable() {
2203 let taken = voi_samples_taken_total();
2205 let skipped = voi_samples_skipped_total();
2206 let _ = taken.checked_add(skipped).expect("counter overflow");
2208 }
2209
2210 #[test]
2211 fn counters_increase_monotonically() {
2212 let before_taken = voi_samples_taken_total();
2213 let before_skipped = voi_samples_skipped_total();
2214
2215 let mut sampler = VoiSampler::new(VoiConfig::default());
2216 let mut now = Instant::now();
2217 for _ in 0..10 {
2218 let d = sampler.decide(now);
2219 if d.should_sample {
2220 sampler.observe_at(false, now);
2221 }
2222 now += Duration::from_millis(100);
2223 }
2224
2225 let after_taken = voi_samples_taken_total();
2226 let after_skipped = voi_samples_skipped_total();
2227
2228 assert!(
2230 (after_taken + after_skipped) >= (before_taken + before_skipped) + 10,
2231 "expected at least 10 counter increments total, \
2232 taken: {before_taken}→{after_taken}, skipped: {before_skipped}→{after_skipped}"
2233 );
2234 }
2235
2236 #[test]
2241 fn deferred_scheduler_respects_hard_budget() {
2242 let mut scheduler = DeferredRefinementScheduler::new(DeferredRefinementConfig {
2243 min_spare_budget_us: 200,
2244 max_refinements_per_frame: 3,
2245 voi_gain_cutoff: 0.01,
2246 fairness_boost_per_skip: 0.02,
2247 fairness_boost_cap: 0.5,
2248 });
2249
2250 let candidates = [
2251 RefinementCandidate {
2252 region_id: 1,
2253 estimated_cost_us: 600,
2254 voi_gain: 0.25,
2255 },
2256 RefinementCandidate {
2257 region_id: 2,
2258 estimated_cost_us: 500,
2259 voi_gain: 0.21,
2260 },
2261 RefinementCandidate {
2262 region_id: 3,
2263 estimated_cost_us: 300,
2264 voi_gain: 0.08,
2265 },
2266 ];
2267
2268 let plan = scheduler.plan_frame(3_000, 1_900, &candidates);
2269 assert!(plan.hard_budget_respected());
2270 assert!(plan.spent_optional_us <= plan.optional_budget_us);
2271 assert!(
2272 plan.mandatory_work_us
2273 .saturating_add(plan.reserved_spare_us)
2274 .saturating_add(plan.spent_optional_us)
2275 <= 3_000
2276 );
2277 }
2278
2279 #[test]
2280 fn deferred_scheduler_is_deterministic_for_identical_inputs() {
2281 let config = DeferredRefinementConfig {
2282 min_spare_budget_us: 100,
2283 max_refinements_per_frame: 2,
2284 voi_gain_cutoff: 0.01,
2285 fairness_boost_per_skip: 0.03,
2286 fairness_boost_cap: 0.6,
2287 };
2288 let mut a = DeferredRefinementScheduler::new(config.clone());
2289 let mut b = DeferredRefinementScheduler::new(config);
2290
2291 let candidates = [
2292 RefinementCandidate {
2293 region_id: 11,
2294 estimated_cost_us: 450,
2295 voi_gain: 0.13,
2296 },
2297 RefinementCandidate {
2298 region_id: 22,
2299 estimated_cost_us: 500,
2300 voi_gain: 0.11,
2301 },
2302 RefinementCandidate {
2303 region_id: 33,
2304 estimated_cost_us: 350,
2305 voi_gain: 0.07,
2306 },
2307 ];
2308
2309 for _ in 0..25 {
2310 let pa = a.plan_frame(2_800, 1_600, &candidates);
2311 let pb = b.plan_frame(2_800, 1_600, &candidates);
2312 assert_eq!(pa, pb);
2313 }
2314 }
2315
2316 #[test]
2317 fn deferred_scheduler_fairness_avoids_starvation() {
2318 let mut scheduler = DeferredRefinementScheduler::new(DeferredRefinementConfig {
2319 min_spare_budget_us: 400,
2320 max_refinements_per_frame: 1,
2321 voi_gain_cutoff: 0.01,
2322 fairness_boost_per_skip: 0.05,
2323 fairness_boost_cap: 2.0,
2324 });
2325
2326 let candidates = [
2327 RefinementCandidate {
2328 region_id: 100,
2329 estimated_cost_us: 700,
2330 voi_gain: 0.20,
2331 },
2332 RefinementCandidate {
2333 region_id: 200,
2334 estimated_cost_us: 700,
2335 voi_gain: 0.02,
2336 },
2337 ];
2338
2339 let mut low_region_selected = 0u32;
2340 for _ in 0..30 {
2341 let plan = scheduler.plan_frame(4_000, 2_700, &candidates);
2342 assert!(plan.hard_budget_respected());
2343 if plan.selected.iter().any(|s| s.region_id == 200) {
2344 low_region_selected = low_region_selected.saturating_add(1);
2345 }
2346 }
2347
2348 assert!(
2349 low_region_selected > 0,
2350 "fairness boosting should eventually schedule the lower-VOI region"
2351 );
2352 }
2353}