use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Certification {
pub threshold: f64,
pub e_value: f64,
pub certified_at_round: u64,
}
pub const DEFAULT_BET: f64 = 0.5;
pub const DEFAULT_CAP: f64 = 10.0;
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EProcessRiskControl {
alpha: f64,
delta: f64,
bet: f64,
cap: f64,
grid: Vec<f64>,
e_values: Vec<f64>,
certified_at: Vec<Option<u64>>,
rounds: u64,
served: u64,
served_fails: u64,
}
impl EProcessRiskControl {
#[must_use]
pub fn new(alpha: f64, delta: f64, bet: f64, grid: &[f64]) -> Self {
Self::with_cap(alpha, delta, bet, DEFAULT_CAP, grid)
}
#[must_use]
pub fn with_cap(alpha: f64, delta: f64, bet: f64, cap: f64, grid: &[f64]) -> Self {
let max_bet = 0.5 / (1.0 - alpha).max(f64::EPSILON);
let bet = if bet.is_finite() {
bet.clamp(0.0, max_bet)
} else {
DEFAULT_BET.min(max_bet)
};
let mut grid: Vec<f64> = grid.iter().copied().filter(|g| g.is_finite()).collect();
grid.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
grid.dedup();
let n = grid.len();
Self {
alpha,
delta,
bet,
cap,
grid,
e_values: vec![1.0; n],
certified_at: vec![None; n],
rounds: 0,
served: 0,
served_fails: 0,
}
}
#[must_use]
pub fn crossing_level(&self) -> f64 {
if self.grid.is_empty() || self.delta <= 0.0 {
return f64::INFINITY;
}
self.grid.len() as f64 / self.delta
}
pub fn observe_served(&mut self, score: f64, was_correct: bool) {
self.rounds += 1;
self.served += 1;
self.served_fails += u64::from(!was_correct);
let err = f64::from(!was_correct);
let level = self.crossing_level();
for i in 0..self.grid.len() {
if self.grid[i] > score {
continue;
}
let factor = (1.0 + self.bet * (self.alpha - err)).max(0.0);
self.e_values[i] = (self.e_values[i] * factor).min(self.cap * level);
if self.certified_at[i].is_none() && self.e_values[i] >= level {
self.certified_at[i] = Some(self.rounds);
}
}
}
#[must_use]
pub fn certified_threshold(&self) -> Option<Certification> {
let level = self.crossing_level();
self.grid
.iter()
.enumerate()
.find(|(i, _)| self.e_values[*i] >= level)
.map(|(i, &threshold)| Certification {
threshold,
e_value: self.e_values[i],
certified_at_round: self.certified_at[i].unwrap_or(self.rounds),
})
}
#[must_use]
pub fn should_serve(&self, score: f64) -> bool {
self.certified_threshold()
.is_some_and(|c| score >= c.threshold)
}
#[must_use]
pub fn realized_served_failure(&self) -> f64 {
if self.served == 0 {
0.0
} else {
self.served_fails as f64 / self.served as f64
}
}
#[must_use]
pub const fn rounds(&self) -> u64 {
self.rounds
}
#[must_use]
pub fn e_values(&self) -> &[f64] {
&self.e_values
}
#[must_use]
pub fn grid(&self) -> &[f64] {
&self.grid
}
#[must_use]
pub const fn alpha(&self) -> f64 {
self.alpha
}
#[must_use]
pub const fn delta(&self) -> f64 {
self.delta
}
}
#[cfg(test)]
mod tests {
use super::*;
struct Lcg(u64);
impl Lcg {
fn next_f64(&mut self) -> f64 {
self.0 = self
.0
.wrapping_mul(6_364_136_223_846_793_005)
.wrapping_add(1);
((self.0 >> 11) as f64) / ((1u64 << 53) as f64)
}
}
fn grid() -> Vec<f64> {
(0..=20).map(|i| f64::from(i) / 20.0).collect()
}
fn correct_for(score: f64, u: f64) -> bool {
u < score
}
#[test]
fn nothing_is_certified_before_any_evidence() {
let e = EProcessRiskControl::new(0.1, 0.05, DEFAULT_BET, &grid());
assert!(
e.certified_threshold().is_none(),
"a fresh controller must certify nothing"
);
assert!(
!e.should_serve(1.0),
"even a perfect score must not serve without a certified threshold"
);
}
#[test]
fn a_clean_stream_eventually_certifies() {
let mut e = EProcessRiskControl::new(0.2, 0.05, DEFAULT_BET, &grid());
let mut rng = Lcg(42);
for _ in 0..4000 {
let score = 0.90 + rng.next_f64() * 0.10;
let correct = correct_for(score, rng.next_f64());
e.observe_served(score, correct);
}
let cert = e
.certified_threshold()
.expect("4000 clean rounds must certify some threshold");
assert!(
cert.e_value >= e.crossing_level(),
"a certified threshold must sit at or above the Bonferroni crossing level: {} < {}",
cert.e_value,
e.crossing_level()
);
}
#[test]
fn coverage_holds_at_every_round_under_a_regime_change() {
let alpha = 0.20;
let mut worst: f64 = 0.0;
for seed in 0..40u64 {
let mut e = EProcessRiskControl::new(alpha, 0.05, DEFAULT_BET, &grid());
let mut rng = Lcg(seed.wrapping_mul(2_654_435_761).wrapping_add(7));
let mut served = 0u64;
let mut fails = 0u64;
for t in 0..3000 {
let score = 0.80 + rng.next_f64() * 0.20;
let correct = if t < 1500 {
correct_for(score, rng.next_f64())
} else {
rng.next_f64() < 0.55
};
if e.should_serve(score) {
served += 1;
fails += u64::from(!correct);
if served >= 50 {
let rate = fails as f64 / served as f64;
worst = worst.max(rate);
}
}
e.observe_served(score, correct);
}
}
assert!(
worst <= alpha + 0.10,
"worst per-round served-failure {worst:.3} exceeded alpha={alpha} plus slack"
);
}
#[test]
fn split_conformal_breaches_where_the_e_process_holds() {
let alpha = 0.15;
let n = 6000;
let mut rng = Lcg(20_260_814);
let mut calib: Vec<(f64, bool)> = Vec::new();
for _ in 0..1000 {
let score = 0.70 + rng.next_f64() * 0.30;
calib.push((score, correct_for(score, rng.next_f64())));
}
let fixed = crate::conformal::calibrate(&calib, alpha, 0.05, 30).threshold;
let mut e = EProcessRiskControl::new(alpha, 0.05, DEFAULT_BET, &grid());
for &(s, c) in &calib {
e.observe_served(s, c);
}
let (mut sc_served, mut sc_fails) = (0u64, 0u64);
let (mut ep_served, mut ep_fails) = (0u64, 0u64);
for t in 0..n {
let score = 0.70 + rng.next_f64() * 0.30;
let correct = if t < n / 2 {
correct_for(score, rng.next_f64())
} else {
rng.next_f64() < 0.60
};
if score >= fixed {
sc_served += 1;
sc_fails += u64::from(!correct);
}
if e.should_serve(score) {
ep_served += 1;
ep_fails += u64::from(!correct);
}
e.observe_served(score, correct);
}
let sc_rate = sc_fails as f64 / sc_served.max(1) as f64;
let ep_rate = ep_fails as f64 / ep_served.max(1) as f64;
assert!(
sc_rate > alpha,
"the stream is meant to break split conformal, but its rate was {sc_rate:.3} <= alpha={alpha} \
— the test has stopped being adversarial and proves nothing"
);
assert!(
ep_rate < sc_rate,
"the e-process ({ep_rate:.3}) must beat split conformal ({sc_rate:.3}) under shift"
);
}
#[test]
fn the_cap_bounds_how_long_a_stale_certification_survives() {
let alpha = 0.10;
let lag = |cap: f64| -> u64 {
let mut e = EProcessRiskControl::with_cap(alpha, 0.05, DEFAULT_BET, cap, &grid());
let mut rng = Lcg(99);
for _ in 0..5000 {
let score = 0.95 + rng.next_f64() * 0.05;
e.observe_served(score, correct_for(score, rng.next_f64()));
}
assert!(
e.certified_threshold().is_some(),
"the clean stretch must certify, or the lag measurement is meaningless"
);
let mut rounds = 0u64;
while e.certified_threshold().is_some() && rounds < 100_000 {
e.observe_served(0.99, false);
rounds += 1;
}
rounds
};
let capped = lag(DEFAULT_CAP);
let uncapped = lag(f64::INFINITY);
assert!(
capped < uncapped,
"the cap must shorten de-certification lag: capped={capped} uncapped={uncapped}"
);
assert!(
capped <= 100,
"a capped controller must drop a contradicted certification within ~tens of rounds, took {capped}"
);
}
#[test]
fn an_oversized_bet_cannot_permanently_kill_a_threshold() {
let alpha = 0.20;
let mut e = EProcessRiskControl::with_cap(alpha, 0.05, 5.0, DEFAULT_CAP, &grid());
e.observe_served(0.9, false);
assert!(
e.e_values().iter().all(|v| *v > 0.0),
"a failure must shrink e-values, never zero them: {:?}",
e.e_values()
);
let mut rng = Lcg(7);
for _ in 0..4000 {
let score = 0.95 + rng.next_f64() * 0.05;
e.observe_served(score, correct_for(score, rng.next_f64()));
}
assert!(
e.certified_threshold().is_some(),
"a controller that took one early failure must still be able to certify later"
);
}
#[test]
fn an_uncertified_controller_yields_nothing_for_the_router_to_prefer() {
let mut e = EProcessRiskControl::new(0.2, 0.05, DEFAULT_BET, &grid());
for _ in 0..10 {
e.observe_served(0.95, true);
}
assert!(
e.certified_threshold().is_none(),
"ten rounds must not certify at delta=0.05 over a 21-point grid"
);
let mut rng = Lcg(11);
for _ in 0..4000 {
let score = 0.95 + rng.next_f64() * 0.05;
e.observe_served(score, correct_for(score, rng.next_f64()));
}
let c = e
.certified_threshold()
.expect("sustained clean evidence must certify");
assert!(
(0.0..=1.0).contains(&c.threshold),
"a certified threshold must be servable: {}",
c.threshold
);
}
#[test]
fn a_zero_error_budget_certifies_nothing() {
for delta in [0.0, -0.1] {
let mut e = EProcessRiskControl::new(0.2, delta, DEFAULT_BET, &grid());
let mut rng = Lcg(3);
for _ in 0..5000 {
let score = 0.99;
e.observe_served(score, correct_for(score, rng.next_f64()));
}
assert!(
e.crossing_level().is_infinite(),
"delta={delta} must make the crossing level unreachable"
);
assert!(
e.certified_threshold().is_none(),
"delta={delta} is a zero error budget: nothing may ever be certified"
);
assert!(!e.should_serve(1.0), "and nothing may be served");
}
}
#[test]
fn the_crossing_level_scales_with_grid_size() {
let small = EProcessRiskControl::new(0.1, 0.05, DEFAULT_BET, &[0.5, 0.6]);
let large = EProcessRiskControl::new(0.1, 0.05, DEFAULT_BET, &grid());
assert!(
large.crossing_level() > small.crossing_level(),
"a larger grid must demand more evidence per threshold: {} vs {}",
large.crossing_level(),
small.crossing_level()
);
assert!(
(small.crossing_level() - 2.0 / 0.05).abs() < 1e-9,
"crossing level must be exactly n/delta"
);
}
#[test]
fn thresholds_that_would_not_have_served_are_not_updated() {
let mut e = EProcessRiskControl::new(0.1, 0.05, DEFAULT_BET, &[0.2, 0.9]);
e.observe_served(0.5, true);
let vals = e.e_values();
assert!(
(vals[1] - 1.0).abs() < f64::EPSILON,
"threshold 0.9 did not serve a 0.5-scoring item, so its e-value must stay 1.0, got {}",
vals[1]
);
assert!(
vals[0] > 1.0,
"threshold 0.2 did serve it correctly, so its e-value must grow, got {}",
vals[0]
);
}
#[test]
fn a_degenerate_grid_certifies_nothing_and_does_not_panic() {
let mut e = EProcessRiskControl::new(0.1, 0.05, DEFAULT_BET, &[f64::NAN, f64::INFINITY]);
e.observe_served(0.9, true);
assert!(e.certified_threshold().is_none());
assert!(!e.should_serve(1.0));
assert!(
e.crossing_level().is_infinite(),
"an empty grid can never cross"
);
}
}