use super::verify::Verdict;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Skip {
Regressed,
Unchanged,
AlreadyHelping,
}
impl Skip {
pub fn reason(&self, setting_id: &str) -> String {
match self {
Skip::Regressed => format!(
"{setting_id} was applied and measured as a regression on this machine, \
and was reverted; it will not be proposed again until the ledger is cleared"
),
Skip::Unchanged => format!(
"{setting_id} was applied and measured, and nothing moved beyond noise; \
re-measuring it every cycle costs time and learns the same thing"
),
Skip::AlreadyHelping => format!(
"{setting_id} was applied and measured as an improvement, so it is \
already in effect"
),
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Entry {
pub attempts: u32,
pub last: Verdict,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct Ledger {
entries: BTreeMap<String, Entry>,
}
impl Ledger {
pub fn new() -> Self {
Self::default()
}
pub fn record(&mut self, setting_id: &str, verdict: Verdict) {
let entry = self.entries.entry(setting_id.to_string()).or_insert(Entry {
attempts: 0,
last: verdict.clone(),
});
entry.attempts = entry.attempts.saturating_add(1);
entry.last = verdict;
}
pub fn skip(&self, setting_id: &str) -> Option<Skip> {
match &self.entries.get(setting_id)?.last {
Verdict::Regressed { .. } => Some(Skip::Regressed),
Verdict::Unchanged { .. } => Some(Skip::Unchanged),
Verdict::Improved { .. } => Some(Skip::AlreadyHelping),
Verdict::Unverifiable { .. } => None,
}
}
pub fn get(&self, setting_id: &str) -> Option<&Entry> {
self.entries.get(setting_id)
}
pub fn len(&self) -> usize {
self.entries.len()
}
pub fn is_empty(&self) -> bool {
self.entries.is_empty()
}
pub fn forget(&mut self, setting_id: &str) -> Option<Entry> {
self.entries.remove(setting_id)
}
pub fn clear(&mut self) {
self.entries.clear();
}
pub fn iter(&self) -> impl Iterator<Item = (&String, &Entry)> {
self.entries.iter()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn regressed() -> Verdict {
Verdict::Regressed {
metric: "m".into(),
before: 10.0,
after: 20.0,
delta: 10.0,
}
}
fn improved() -> Verdict {
Verdict::Improved {
metric: "m".into(),
before: 20.0,
after: 10.0,
delta: -10.0,
}
}
fn unchanged() -> Verdict {
Verdict::Unchanged {
metric: "m".into(),
before: 10.0,
after: 10.0,
delta: 0.0,
threshold: 1.0,
}
}
#[test]
fn a_regression_is_not_proposed_again() {
let mut l = Ledger::new();
assert_eq!(l.skip("governor"), None, "an untried setting is fair game");
l.record("governor", regressed());
assert_eq!(l.skip("governor"), Some(Skip::Regressed));
}
#[test]
fn an_improvement_is_already_in_effect_and_needs_no_rewrite() {
let mut l = Ledger::new();
l.record("governor", improved());
assert_eq!(l.skip("governor"), Some(Skip::AlreadyHelping));
}
#[test]
fn a_null_result_is_not_remeasured_every_cycle() {
let mut l = Ledger::new();
l.record("governor", unchanged());
assert_eq!(l.skip("governor"), Some(Skip::Unchanged));
}
#[test]
fn unverifiable_never_stops_a_setting_being_tried() {
let mut l = Ledger::new();
l.record(
"governor",
Verdict::Unverifiable {
reason: "no metric is declared".into(),
},
);
assert_eq!(
l.skip("governor"),
None,
"an absent measurement is not evidence that the setting is bad"
);
assert_eq!(
l.get("governor").map(|e| e.attempts),
Some(1),
"it is still recorded, so a reader can see it was tried"
);
}
#[test]
fn the_latest_verdict_wins_and_attempts_accumulate() {
let mut l = Ledger::new();
l.record("governor", regressed());
l.record("governor", improved());
assert_eq!(l.skip("governor"), Some(Skip::AlreadyHelping));
assert_eq!(l.get("governor").unwrap().attempts, 2);
}
#[test]
fn forgetting_puts_a_setting_back_in_play() {
let mut l = Ledger::new();
l.record("governor", regressed());
assert!(l.skip("governor").is_some());
l.forget("governor");
assert_eq!(
l.skip("governor"),
None,
"a regression measured once is evidence about that moment, not a life sentence"
);
}
#[test]
fn a_ledger_survives_serialisation() {
let mut l = Ledger::new();
l.record("governor", regressed());
let json = serde_json::to_string(&l).unwrap();
let back: Ledger = serde_json::from_str(&json).unwrap();
assert_eq!(back, l);
assert_eq!(back.skip("governor"), Some(Skip::Regressed));
}
#[test]
fn skip_reasons_name_the_setting_and_the_evidence() {
for skip in [Skip::Regressed, Skip::Unchanged, Skip::AlreadyHelping] {
let r = skip.reason("scaling_governor");
assert!(r.contains("scaling_governor"), "{r}");
assert!(
r.contains("measured"),
"a skip must say it was measured, not just that it was skipped: {r}"
);
}
}
}