use std::collections::HashMap;
use std::sync::Mutex;
use std::time::{Duration, Instant};
use firstpass_core::config::SessionPromotion;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct Pin {
rung: u32,
failures: u32,
since_probe: u32,
seen: Instant,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Decision {
Cold,
Promoted(u32),
Probe(u32),
}
impl Decision {
#[must_use]
pub const fn start_rung(self) -> u32 {
match self {
Self::Cold => 0,
Self::Promoted(r) | Self::Probe(r) => r,
}
}
#[must_use]
pub const fn reason(self) -> &'static str {
match self {
Self::Cold => "cold",
Self::Promoted(_) => "session-promoted",
Self::Probe(_) => "session-probe",
}
}
}
fn decide(pin: Option<&Pin>, cfg: &SessionPromotion) -> Decision {
let Some(pin) = pin else {
return Decision::Cold;
};
if pin.failures < cfg.after_failures || pin.rung == 0 {
return Decision::Cold;
}
if pin.since_probe >= cfg.probe_every.max(1) {
return Decision::Probe(pin.rung.saturating_sub(1));
}
Decision::Promoted(pin.rung)
}
#[derive(Debug)]
pub struct SessionPromoter {
cfg: SessionPromotion,
ttl: Duration,
pins: Mutex<HashMap<(String, String), Pin>>,
}
impl SessionPromoter {
pub fn new(cfg: SessionPromotion) -> firstpass_core::Result<Self> {
let ttl = cfg.window_duration()?;
Ok(Self {
cfg,
ttl,
pins: Mutex::new(HashMap::new()),
})
}
#[must_use]
pub fn decide(&self, tenant: &str, session: &str, now: Instant) -> Decision {
let key = (tenant.to_owned(), session.to_owned());
let Ok(pins) = self.pins.lock() else {
return Decision::Cold;
};
match pins.get(&key) {
Some(p) if now.duration_since(p.seen) < self.ttl => decide(Some(p), &self.cfg),
_ => Decision::Cold,
}
}
pub fn record(
&self,
tenant: &str,
session: &str,
served_rung: u32,
escalated: bool,
now: Instant,
) {
let key = (tenant.to_owned(), session.to_owned());
let Ok(mut pins) = self.pins.lock() else {
return;
};
self.evict_if_needed(&mut pins, now);
let expired = pins
.get(&key)
.is_some_and(|p| now.duration_since(p.seen) >= self.ttl);
if expired {
pins.remove(&key);
}
let entry = pins.entry(key).or_insert(Pin {
rung: 0,
failures: 0,
since_probe: 0,
seen: now,
});
entry.seen = now;
if escalated {
entry.failures = entry.failures.saturating_add(1);
entry.rung = entry.rung.max(served_rung);
entry.since_probe = 0;
} else if served_rung < entry.rung {
entry.rung = served_rung;
entry.failures = 0;
entry.since_probe = 0;
} else {
entry.since_probe = entry.since_probe.saturating_add(1);
}
}
fn evict_if_needed(&self, pins: &mut HashMap<(String, String), Pin>, now: Instant) {
if pins.len() < self.cfg.max_sessions {
return;
}
pins.retain(|_, p| now.duration_since(p.seen) < self.ttl);
if pins.len() >= self.cfg.max_sessions {
let mut by_age: Vec<((String, String), Instant)> =
pins.iter().map(|(k, p)| (k.clone(), p.seen)).collect();
by_age.sort_by_key(|(_, seen)| *seen);
for (k, _) in by_age.into_iter().take(self.cfg.max_sessions.max(2) / 2) {
pins.remove(&k);
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn cfg() -> SessionPromotion {
SessionPromotion {
after_failures: 1,
window: "30m".to_owned(),
probe_every: 3,
max_sessions: 100,
}
}
fn promoter() -> SessionPromoter {
SessionPromoter::new(cfg()).expect("30m parses")
}
#[test]
fn an_unknown_session_starts_cold() {
let p = promoter();
assert_eq!(p.decide("t", "never-seen", Instant::now()), Decision::Cold);
}
#[test]
fn a_session_that_escalated_starts_where_it_landed() {
let p = promoter();
let now = Instant::now();
p.record("t", "s", 1, true, now);
assert_eq!(p.decide("t", "s", now), Decision::Promoted(1));
assert_eq!(p.decide("t", "s", now).start_rung(), 1);
}
#[test]
fn one_escalation_is_not_enough_when_the_threshold_is_higher() {
let mut c = cfg();
c.after_failures = 3;
let p = SessionPromoter::new(c).expect("parses");
let now = Instant::now();
p.record("t", "s", 1, true, now);
p.record("t", "s", 1, true, now);
assert_eq!(p.decide("t", "s", now), Decision::Cold, "2 < 3");
p.record("t", "s", 1, true, now);
assert_eq!(p.decide("t", "s", now), Decision::Promoted(1));
}
#[test]
fn promotion_is_not_a_ratchet_it_probes_downward() {
let p = promoter();
let now = Instant::now();
p.record("t", "s", 2, true, now);
assert_eq!(p.decide("t", "s", now), Decision::Promoted(2));
for _ in 0..3 {
p.record("t", "s", 2, false, now);
}
assert_eq!(
p.decide("t", "s", now),
Decision::Probe(1),
"must periodically test one rung lower"
);
}
#[test]
fn a_successful_probe_releases_the_promotion() {
let p = promoter();
let now = Instant::now();
p.record("t", "s", 2, true, now);
for _ in 0..3 {
p.record("t", "s", 2, false, now);
}
assert_eq!(p.decide("t", "s", now), Decision::Probe(1));
p.record("t", "s", 1, false, now);
assert_eq!(
p.decide("t", "s", now),
Decision::Cold,
"released to rung 1"
);
}
#[test]
fn a_failed_probe_restores_the_promotion() {
let p = promoter();
let now = Instant::now();
p.record("t", "s", 2, true, now);
for _ in 0..3 {
p.record("t", "s", 2, false, now);
}
assert_eq!(p.decide("t", "s", now), Decision::Probe(1));
p.record("t", "s", 2, true, now);
assert_eq!(p.decide("t", "s", now), Decision::Promoted(2));
}
#[test]
fn a_promotion_never_crosses_a_tenant_boundary() {
let p = promoter();
let now = Instant::now();
p.record("tenant-a", "shared-id", 2, true, now);
assert_eq!(
p.decide("tenant-a", "shared-id", now),
Decision::Promoted(2)
);
assert_eq!(p.decide("tenant-b", "shared-id", now), Decision::Cold);
}
#[test]
fn an_idle_session_forgets_its_promotion() {
let mut c = cfg();
c.window = "1s".to_owned();
let p = SessionPromoter::new(c).expect("parses");
let t0 = Instant::now();
p.record("t", "s", 2, true, t0);
assert_eq!(p.decide("t", "s", t0), Decision::Promoted(2));
let later = t0 + Duration::from_secs(2);
assert_eq!(
p.decide("t", "s", later),
Decision::Cold,
"a reused session id must not inherit a stale rung"
);
}
#[test]
fn the_map_cannot_grow_without_bound() {
let mut c = cfg();
c.max_sessions = 10;
let p = SessionPromoter::new(c).expect("parses");
let now = Instant::now();
for i in 0..100 {
p.record("t", &format!("s{i}"), 1, true, now);
}
let len = p.pins.lock().expect("not poisoned").len();
assert!(len <= 10, "expected <= 10 tracked sessions, got {len}");
}
#[test]
fn probe_every_zero_is_rejected_at_parse_not_silently_coerced() {
let err = firstpass_core::config::Config::parse(
r#"
[escalation.session_promotion]
after_failures = 2
window = "30m"
probe_every = 0
[[route]]
mode = "enforce"
ladder = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-5"]
"#,
)
.expect_err("probe_every = 0 must not parse");
let msg = err.to_string();
assert!(msg.contains("probe_every"), "unhelpful message: {msg}");
let mut c = cfg();
c.probe_every = 0;
let pin = Pin {
rung: 2,
failures: 5,
since_probe: 1,
seen: Instant::now(),
};
assert_eq!(decide(Some(&pin), &c), Decision::Probe(1));
}
#[test]
fn a_valid_promotion_block_parses_with_defaults() {
let cfg = firstpass_core::config::Config::parse(
r#"
[escalation.session_promotion]
after_failures = 2
window = "30m"
[[route]]
mode = "enforce"
ladder = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-5"]
"#,
)
.expect("valid promotion config parses");
let p = cfg
.escalation
.session_promotion
.expect("promotion block present");
assert_eq!(p.after_failures, 2);
assert_eq!(p.probe_every, 5, "default must not be a ratchet");
assert_eq!(p.max_sessions, 10_000);
}
#[test]
fn the_decision_carries_its_reason_into_the_receipt() {
assert_eq!(Decision::Cold.reason(), "cold");
assert_eq!(Decision::Promoted(2).reason(), "session-promoted");
assert_eq!(Decision::Probe(1).reason(), "session-probe");
}
}