use crate::error::VeridictError;
const MAX_TABULATED_HORIZON: u64 = 1_000_000;
#[derive(Debug, Clone)]
pub enum RewardSchedule {
HardDeadline {
deadline: u64,
},
ExponentialDecay {
time_scale: f64,
horizon: u64,
},
Tabulated {
rewards: Vec<f64>,
},
}
impl RewardSchedule {
pub(crate) fn validate(&self) -> Result<(), VeridictError> {
match self {
RewardSchedule::HardDeadline { deadline } => {
if *deadline == 0 {
return Err(VeridictError::InvalidThreshold(
"--deadline must be >= 1".to_string(),
));
}
}
RewardSchedule::ExponentialDecay {
time_scale,
horizon,
} => {
if !time_scale.is_finite() || *time_scale <= 0.0 {
return Err(VeridictError::InvalidThreshold(format!(
"--time-scale must be finite and > 0, got {time_scale}"
)));
}
if *horizon == 0 {
return Err(VeridictError::InvalidThreshold(
"--horizon must be >= 1".to_string(),
));
}
}
RewardSchedule::Tabulated { rewards } => {
if rewards.len() < 2 {
return Err(VeridictError::InvalidThreshold(
"tabulated reward schedule must have at least 2 entries (t=0 and t=1), \
so its horizon is >= 1"
.to_string(),
));
}
let mut prev = f64::INFINITY;
for (t, &r) in rewards.iter().enumerate() {
if !r.is_finite() || r < 0.0 {
return Err(VeridictError::InvalidThreshold(format!(
"tabulated reward at t={t} must be finite and >= 0, got {r}"
)));
}
if r > prev {
return Err(VeridictError::InvalidThreshold(format!(
"tabulated reward schedule must be non-increasing: reward at t={t} \
({r}) exceeds reward at t={} ({prev})",
t - 1
)));
}
prev = r;
}
}
}
Ok(())
}
pub fn horizon(&self) -> u64 {
match self {
RewardSchedule::HardDeadline { deadline } => *deadline,
RewardSchedule::ExponentialDecay { horizon, .. } => *horizon,
RewardSchedule::Tabulated { rewards } => rewards.len() as u64 - 1,
}
}
pub fn at(&self, t: u64) -> f64 {
match self {
RewardSchedule::HardDeadline { deadline } => {
if t <= *deadline {
1.0
} else {
0.0
}
}
RewardSchedule::ExponentialDecay {
time_scale,
horizon,
} => {
if t > *horizon {
0.0
} else {
(-(t as f64) / time_scale).exp()
}
}
RewardSchedule::Tabulated { rewards } => {
rewards.get(t as usize).copied().unwrap_or(0.0)
}
}
}
pub(crate) fn kind_label(&self) -> &'static str {
match self {
RewardSchedule::HardDeadline { .. } => "hard_deadline",
RewardSchedule::ExponentialDecay { .. } => "exponential_decay",
RewardSchedule::Tabulated { .. } => "tabulated",
}
}
pub(crate) fn parameters(&self) -> serde_json::Value {
match self {
RewardSchedule::HardDeadline { deadline } => {
serde_json::json!({ "deadline": deadline })
}
RewardSchedule::ExponentialDecay {
time_scale,
horizon,
} => {
serde_json::json!({ "time_scale": time_scale, "horizon": horizon })
}
RewardSchedule::Tabulated { rewards } => {
serde_json::json!({ "horizon": self.horizon(), "entries": rewards.len() })
}
}
}
pub(crate) fn truncation_note(&self) -> String {
match self {
RewardSchedule::HardDeadline { deadline } => format!(
"hard-deadline reward is exact: R(t) = 0 for t > {deadline} by construction, not \
a truncation approximation"
),
RewardSchedule::ExponentialDecay { horizon, .. } => {
let residual = self.at(*horizon);
format!(
"exponential-decay reward truncated at horizon={horizon}: R(horizon) = \
{residual:.3e} against R(0) = 1.0 is discarded for t > horizon; judge \
negligibility against your own horizon-to-time_scale ratio before trusting \
planned_expected_reward_under_p1 at a small ratio"
)
}
RewardSchedule::Tabulated { rewards } => {
let horizon = self.horizon();
let last = *rewards.last().unwrap_or(&0.0);
format!(
"tabulated reward truncated at horizon={horizon}: last declared value is \
{last}; R(t) = 0 for t > horizon"
)
}
}
}
}
#[derive(Debug, serde::Deserialize)]
pub struct RewardScheduleEntry {
pub until: Option<u64>,
pub after: Option<u64>,
pub value: f64,
}
#[derive(Debug, serde::Deserialize)]
pub struct RewardScheduleFile {
pub rewards: Vec<RewardScheduleEntry>,
}
pub fn expand_schedule_file(file: &RewardScheduleFile) -> Result<RewardSchedule, VeridictError> {
let mut untils: Vec<(u64, f64)> = Vec::new();
let mut after: Option<(u64, f64)> = None;
for entry in &file.rewards {
match (entry.until, entry.after) {
(Some(u), None) => untils.push((u, entry.value)),
(None, Some(_)) if after.is_some() => {
return Err(VeridictError::InvalidThreshold(
"reward schedule file must declare at most one 'after' entry".to_string(),
));
}
(None, Some(boundary)) => after = Some((boundary, entry.value)),
_ => {
return Err(VeridictError::InvalidThreshold(
"each reward schedule entry must set exactly one of 'until'/'after'"
.to_string(),
));
}
}
}
let Some((after_boundary, after)) = after else {
return Err(VeridictError::InvalidThreshold(
"reward schedule file must declare exactly one 'after' entry for the tail value"
.to_string(),
));
};
if after != 0.0 {
return Err(VeridictError::InvalidThreshold(format!(
"reward schedule file's 'after' entry must be 0.0 (got {after}): R(t) as t -> \
infinity must be 0 by definition, so a schedule that stays rewarding forever has no \
well-defined finite-horizon Bellman problem"
)));
}
if untils.is_empty() {
return Err(VeridictError::InvalidThreshold(
"reward schedule file must declare at least one 'until' entry".to_string(),
));
}
untils.sort_by_key(|(u, _)| *u);
for pair in untils.windows(2) {
if pair[0].0 == pair[1].0 {
return Err(VeridictError::InvalidThreshold(format!(
"reward schedule file declares 'until: {}' more than once",
pair[0].0
)));
}
}
let horizon = untils.last().unwrap().0;
if after_boundary != horizon {
return Err(VeridictError::InvalidThreshold(format!(
"reward schedule file's 'after' boundary ({after_boundary}) must equal the largest \
'until' boundary ({horizon})"
)));
}
if horizon > MAX_TABULATED_HORIZON {
return Err(VeridictError::InvalidThreshold(format!(
"tabulated reward schedule horizon {horizon} exceeds the supported maximum of \
{MAX_TABULATED_HORIZON}; use a formula-backed hard-deadline or exponential schedule \
for larger horizons"
)));
}
let len = usize::try_from(horizon)
.ok()
.and_then(|h| h.checked_add(1))
.ok_or_else(|| {
VeridictError::InvalidThreshold(format!(
"tabulated reward schedule horizon {horizon} cannot be represented on this platform"
))
})?;
let mut rewards = vec![after; len];
for &(until, value) in untils.iter().rev() {
for slot in rewards.iter_mut().take(until as usize + 1) {
*slot = value;
}
}
let schedule = RewardSchedule::Tabulated { rewards };
schedule.validate()?;
Ok(schedule)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn hard_deadline_is_one_then_zero() {
let s = RewardSchedule::HardDeadline { deadline: 400 };
assert_eq!(s.at(0), 1.0);
assert_eq!(s.at(400), 1.0);
assert_eq!(s.at(401), 0.0);
assert_eq!(s.horizon(), 400);
s.validate().unwrap();
}
#[test]
fn hard_deadline_zero_is_rejected() {
assert!(
RewardSchedule::HardDeadline { deadline: 0 }
.validate()
.is_err()
);
}
#[test]
fn exponential_decay_is_monotonic_and_positive() {
let s = RewardSchedule::ExponentialDecay {
time_scale: 800.0,
horizon: 3200,
};
s.validate().unwrap();
assert_eq!(s.at(0), 1.0);
assert!(s.at(800) < s.at(0));
assert!(s.at(3200) < s.at(800));
assert_eq!(s.at(3201), 0.0);
}
#[test]
fn exponential_decay_rejects_non_positive_time_scale() {
assert!(
RewardSchedule::ExponentialDecay {
time_scale: 0.0,
horizon: 100,
}
.validate()
.is_err()
);
assert!(
RewardSchedule::ExponentialDecay {
time_scale: -1.0,
horizon: 100,
}
.validate()
.is_err()
);
}
#[test]
fn tabulated_rejects_negative_reward() {
let s = RewardSchedule::Tabulated {
rewards: vec![1.0, -0.1],
};
assert!(s.validate().is_err());
}
#[test]
fn tabulated_rejects_increasing_reward() {
let s = RewardSchedule::Tabulated {
rewards: vec![0.1, 0.4],
};
assert!(s.validate().is_err());
}
#[test]
fn expand_schedule_file_matches_spec_example() {
let file = RewardScheduleFile {
rewards: vec![
RewardScheduleEntry {
until: Some(400),
after: None,
value: 1.0,
},
RewardScheduleEntry {
until: Some(1600),
after: None,
value: 0.4,
},
RewardScheduleEntry {
until: Some(3200),
after: None,
value: 0.1,
},
RewardScheduleEntry {
until: None,
after: Some(3200),
value: 0.0,
},
],
};
let schedule = expand_schedule_file(&file).unwrap();
assert_eq!(schedule.horizon(), 3200);
assert_eq!(schedule.at(0), 1.0);
assert_eq!(schedule.at(400), 1.0);
assert_eq!(schedule.at(401), 0.4);
assert_eq!(schedule.at(1600), 0.4);
assert_eq!(schedule.at(1601), 0.1);
assert_eq!(schedule.at(3200), 0.1);
assert_eq!(schedule.at(3201), 0.0);
}
#[test]
fn expand_schedule_file_rejects_nonzero_tail() {
let file = RewardScheduleFile {
rewards: vec![
RewardScheduleEntry {
until: Some(100),
after: None,
value: 1.0,
},
RewardScheduleEntry {
until: None,
after: Some(100),
value: 0.2,
},
],
};
assert!(expand_schedule_file(&file).is_err());
}
#[test]
fn expand_schedule_file_requires_an_after_entry() {
let file = RewardScheduleFile {
rewards: vec![RewardScheduleEntry {
until: Some(100),
after: None,
value: 1.0,
}],
};
assert!(expand_schedule_file(&file).is_err());
}
#[test]
fn expand_schedule_file_rejects_mismatched_after_boundary() {
let file = RewardScheduleFile {
rewards: vec![
RewardScheduleEntry {
until: Some(100),
after: None,
value: 1.0,
},
RewardScheduleEntry {
until: None,
after: Some(99),
value: 0.0,
},
],
};
assert!(expand_schedule_file(&file).is_err());
}
#[test]
fn expand_schedule_file_rejects_huge_horizon_before_allocation() {
let file = RewardScheduleFile {
rewards: vec![
RewardScheduleEntry {
until: Some(u64::MAX),
after: None,
value: 1.0,
},
RewardScheduleEntry {
until: None,
after: Some(u64::MAX),
value: 0.0,
},
],
};
let error = expand_schedule_file(&file).unwrap_err();
assert!(error.to_string().contains("supported maximum"));
}
}