1#![forbid(unsafe_code)]
2
3use 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; static VOI_SAMPLES_TAKEN_TOTAL: AtomicU64 = AtomicU64::new(0);
157static VOI_SAMPLES_SKIPPED_TOTAL: AtomicU64 = AtomicU64::new(0);
158
159#[must_use]
161pub fn voi_samples_taken_total() -> u64 {
162 VOI_SAMPLES_TAKEN_TOTAL.load(Ordering::Relaxed)
163}
164
165#[must_use]
167pub fn voi_samples_skipped_total() -> u64 {
168 VOI_SAMPLES_SKIPPED_TOTAL.load(Ordering::Relaxed)
169}
170
171#[derive(Debug, Clone)]
173pub struct VoiConfig {
174 pub alpha: f64,
177
178 pub prior_alpha: f64,
180
181 pub prior_beta: f64,
183
184 pub mu_0: f64,
186
187 pub lambda: f64,
189
190 pub value_scale: f64,
192
193 pub boundary_weight: f64,
195
196 pub sample_cost: f64,
198
199 pub min_interval_ms: u64,
201
202 pub max_interval_ms: u64,
205
206 pub min_interval_events: u64,
208
209 pub max_interval_events: u64,
212
213 pub enable_logging: bool,
215
216 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#[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 #[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#[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 #[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#[derive(Debug, Clone)]
323pub enum VoiLogEntry {
324 Decision(VoiDecision),
325 Observation(VoiObservation),
326}
327
328impl VoiLogEntry {
329 #[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#[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#[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#[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 pub fn new(config: VoiConfig) -> Self {
394 Self::new_at(config, Instant::now())
395 }
396
397 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 #[must_use]
465 pub fn config(&self) -> &VoiConfig {
466 &self.config
467 }
468
469 #[must_use]
471 pub fn posterior_params(&self) -> (f64, f64) {
472 (self.alpha, self.beta)
473 }
474
475 #[must_use]
477 pub fn posterior_mean(&self) -> f64 {
478 beta_mean(self.alpha, self.beta)
479 }
480
481 #[must_use]
483 pub fn posterior_variance(&self) -> f64 {
484 beta_variance(self.alpha, self.beta)
485 }
486
487 #[must_use]
489 pub fn expected_variance_after(&self) -> f64 {
490 expected_variance_after(self.alpha, self.beta)
491 }
492
493 #[must_use]
495 pub fn value_of_information(&self) -> f64 {
496 ftui_core::voi::beta_voi(self.alpha, self.beta)
497 }
498
499 #[must_use]
501 pub fn last_decision(&self) -> Option<&VoiDecision> {
502 self.last_decision.as_ref()
503 }
504
505 #[must_use]
507 pub fn last_observation(&self) -> Option<&VoiObservation> {
508 self.last_observation.as_ref()
509 }
510
511 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 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 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 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 pub fn observe(&mut self, violated: bool) -> VoiObservation {
692 self.observe_at(violated, Instant::now())
693 }
694
695 #[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 #[must_use]
727 pub fn logs(&self) -> &VecDeque<VoiLogEntry> {
728 &self.logs
729 }
730
731 #[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 #[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 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#[derive(Debug, Clone, PartialEq)]
823pub struct DeferredRefinementConfig {
824 pub min_spare_budget_us: u64,
826 pub max_refinements_per_frame: usize,
828 pub voi_gain_cutoff: f64,
830 pub fairness_boost_per_skip: f64,
832 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#[derive(Debug, Clone, Copy, PartialEq)]
850pub struct RefinementCandidate {
851 pub region_id: u64,
853 pub estimated_cost_us: u64,
855 pub voi_gain: f64,
857}
858
859#[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#[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 #[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#[derive(Debug, Clone)]
894pub struct DeferredRefinementScheduler {
895 config: DeferredRefinementConfig,
896 skipped_frames: BTreeMap<u64, u32>,
897}
898
899impl DeferredRefinementScheduler {
900 #[must_use]
902 pub fn new(config: DeferredRefinementConfig) -> Self {
903 Self {
904 config,
905 skipped_frames: BTreeMap::new(),
906 }
907 }
908
909 #[must_use]
911 pub fn config(&self) -> &DeferredRefinementConfig {
912 &self.config
913 }
914
915 #[must_use]
917 pub fn skipped_frames_for(&self, region_id: u64) -> u32 {
918 self.skipped_frames.get(®ion_id).copied().unwrap_or(0)
919 }
920
921 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 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 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#[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, ..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, ..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 #[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 #[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 #[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 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); }
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, sample_cost: 100.0, ..Default::default()
1681 };
1682 let now = Instant::now();
1683 let mut sampler = VoiSampler::new_at(config, now);
1684
1685 let _d1 = sampler.decide(now + Duration::from_millis(1));
1687 sampler.observe_at(false, now + Duration::from_millis(1));
1688
1689 let d2 = sampler.decide(now + Duration::from_millis(10));
1691 assert!(!d2.forced_by_interval, "should not force within 100ms");
1692
1693 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 let d1 = sampler.decide(now);
1711 assert!(d1.should_sample);
1712 sampler.observe_at(false, now);
1713
1714 let d2 = sampler.decide(now + Duration::from_millis(10));
1716 assert!(d2.blocked_by_min_interval);
1717 assert!(!d2.should_sample);
1718
1719 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 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 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 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 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 #[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 #[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 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 #[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 #[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 #[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 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 let taken = voi_samples_taken_total();
2223 let skipped = voi_samples_skipped_total();
2224 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 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 #[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 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 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 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; let trials = 1_500usize;
2447 let steps = 80usize;
2448 let t0 = Instant::now();
2449
2450 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 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 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 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 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}