use std::collections::HashMap;
use std::sync::Mutex;
use std::time::{Duration, Instant};
use firstpass_core::config::SessionPromotion;
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Pin {
pub rung: u32,
pub failures: u32,
pub since_probe: u32,
#[serde(skip, default = "Instant::now")]
pub 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)
}
#[async_trait::async_trait]
pub trait PromotionStore: Send + Sync + std::fmt::Debug {
async fn load(&self, key: &str, now: Instant) -> Option<Pin>;
async fn store(&self, key: &str, pin: Pin, now: Instant);
}
#[must_use]
pub fn promotion_key(tenant: &str, session: &str) -> String {
format!("{tenant}|{session}")
}
#[derive(Debug)]
pub struct SessionPromoter {
cfg: SessionPromotion,
ttl: Duration,
shared: Option<std::sync::Arc<dyn PromotionStore>>,
pins: Mutex<HashMap<String, Pin>>,
}
#[async_trait::async_trait]
impl PromotionStore for SessionPromoter {
async fn load(&self, key: &str, now: Instant) -> Option<Pin> {
let Ok(pins) = self.pins.lock() else {
return None;
};
pins.get(key)
.filter(|p| now.duration_since(p.seen) < self.ttl)
.copied()
}
async fn store(&self, key: &str, pin: Pin, now: Instant) {
let Ok(mut pins) = self.pins.lock() else {
return;
};
if pins.len() >= self.cfg.max_sessions {
pins.retain(|_, p| now.duration_since(p.seen) < self.ttl);
if pins.len() >= self.cfg.max_sessions {
let mut by_age: Vec<(String, Instant)> =
pins.iter().map(|(k, p)| (k.clone(), p.seen)).collect();
by_age.sort_by_key(|(_, t)| *t);
for (k, _) in by_age.into_iter().take(self.cfg.max_sessions.max(2) / 2) {
pins.remove(&k);
}
}
}
pins.insert(key.to_owned(), pin);
}
}
impl SessionPromoter {
pub fn new(cfg: SessionPromotion) -> firstpass_core::Result<Self> {
let ttl = cfg.window_duration()?;
Ok(Self {
cfg,
ttl,
shared: None,
pins: Mutex::new(HashMap::new()),
})
}
#[must_use]
pub fn with_shared(mut self, store: std::sync::Arc<dyn PromotionStore>) -> Self {
self.shared = Some(store);
self
}
async fn pin_for(&self, key: &str, now: Instant) -> Option<Pin> {
match self.shared.as_ref() {
Some(s) => s.load(key, now).await,
None => PromotionStore::load(self, key, now).await,
}
}
async fn put_pin(&self, key: &str, pin: Pin, now: Instant) {
match self.shared.as_ref() {
Some(s) => s.store(key, pin, now).await,
None => PromotionStore::store(self, key, pin, now).await,
}
}
pub async fn decide_async(&self, tenant: &str, session: &str, now: Instant) -> Decision {
let key = promotion_key(tenant, session);
decide(self.pin_for(&key, now).await.as_ref(), &self.cfg)
}
pub async fn record_async(
&self,
tenant: &str,
session: &str,
served_rung: u32,
escalated: bool,
now: Instant,
) {
let key = promotion_key(tenant, session);
let mut pin = self.pin_for(&key, now).await.unwrap_or(Pin {
rung: 0,
failures: 0,
since_probe: 0,
seen: now,
});
pin.seen = now;
if escalated {
pin.failures = pin.failures.saturating_add(1);
pin.rung = pin.rung.max(served_rung);
pin.since_probe = 0;
} else if served_rung < pin.rung {
pin.rung = served_rung;
pin.failures = 0;
pin.since_probe = 0;
} else {
pin.since_probe = pin.since_probe.saturating_add(1);
}
self.put_pin(&key, pin, now).await;
}
#[must_use]
pub fn decide(&self, tenant: &str, session: &str, now: Instant) -> Decision {
let key = promotion_key(tenant, session);
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 = promotion_key(tenant, session);
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, 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, 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(feature = "redis-cache")]
pub struct RedisPromotionStore {
client: redis::aio::ConnectionManager,
ttl_secs: u64,
}
#[cfg(feature = "redis-cache")]
impl std::fmt::Debug for RedisPromotionStore {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("RedisPromotionStore")
.field("ttl_secs", &self.ttl_secs)
.finish_non_exhaustive()
}
}
#[cfg(feature = "redis-cache")]
impl RedisPromotionStore {
pub async fn connect(url: &str, ttl_secs: u64) -> Result<Self, String> {
let safe = crate::verified_cache::redact_redis_url(url);
let client = redis::Client::open(url).map_err(|e| format!("redis url {safe}: {e}"))?;
let mgr = tokio::time::timeout(
std::time::Duration::from_secs(5),
redis::aio::ConnectionManager::new(client),
)
.await
.map_err(|_| format!("redis at {safe} did not answer within 5s"))?
.map_err(|e| format!("redis connect {safe}: {e}"))?;
let mut probe = mgr.clone();
let pong: Result<String, _> = tokio::time::timeout(
std::time::Duration::from_secs(5),
redis::cmd("PING").query_async(&mut probe),
)
.await
.map_err(|_| {
format!(
"redis at {safe} did not answer PING within 5s. Refusing to start rather than run \
with session promotion silently fragmented across replicas."
)
})?;
pong.map_err(|e| format!("redis at {safe} rejected PING: {e}"))?;
Ok(Self {
client: mgr,
ttl_secs,
})
}
}
#[cfg(feature = "redis-cache")]
#[async_trait::async_trait]
impl PromotionStore for RedisPromotionStore {
async fn load(&self, key: &str, _now: Instant) -> Option<Pin> {
let mut c = self.client.clone();
let raw: Option<String> = redis::cmd("GET")
.arg(format!("fp:sp:{key}"))
.query_async(&mut c)
.await
.ok()?;
serde_json::from_str(&raw?).ok()
}
async fn store(&self, key: &str, pin: Pin, _now: Instant) {
let Ok(body) = serde_json::to_string(&pin) else {
return;
};
let mut c = self.client.clone();
let _: Result<(), _> = redis::cmd("SETEX")
.arg(format!("fp:sp:{key}"))
.arg(self.ttl_secs)
.arg(body)
.query_async::<()>(&mut c)
.await;
}
}
#[cfg(test)]
mod tests {
use super::*;
fn cfg() -> SessionPromotion {
SessionPromotion {
after_failures: 1,
window: "30m".to_owned(),
probe_every: 3,
max_sessions: 100,
redis_url: None,
}
}
fn promoter() -> SessionPromoter {
SessionPromoter::new(cfg()).expect("30m parses")
}
#[tokio::test]
async fn the_async_path_matches_the_sync_one() {
let p = promoter();
let now = Instant::now();
p.record_async("t", "s", 1, true, now).await;
assert_eq!(p.decide_async("t", "s", now).await, Decision::Promoted(1));
assert_eq!(p.decide("t", "s", now), Decision::Promoted(1));
}
#[tokio::test]
async fn a_pin_survives_serde_without_its_local_clock() {
let pin = Pin {
rung: 2,
failures: 3,
since_probe: 1,
seen: Instant::now(),
};
let wire = serde_json::to_string(&pin).expect("serializes");
assert!(
!wire.contains("seen"),
"a local Instant must not go on the wire: {wire}"
);
let back: Pin = serde_json::from_str(&wire).expect("deserializes");
assert_eq!(back.rung, 2);
assert_eq!(back.failures, 3);
assert_eq!(back.since_probe, 1);
}
#[cfg(feature = "redis-cache")]
#[tokio::test]
async fn promotion_survives_across_replicas() {
let url = std::env::var("FIRSTPASS_TEST_REDIS").unwrap_or_else(|_| {
panic!("set FIRSTPASS_TEST_REDIS (e.g. redis://127.0.0.1:6379/15) to run this test")
});
let store = std::sync::Arc::new(
RedisPromotionStore::connect(&url, 300)
.await
.expect("connect"),
);
let session = format!("sess-{}", uuid::Uuid::now_v7());
let now = Instant::now();
let a = SessionPromoter::new(cfg())
.expect("cfg")
.with_shared(store.clone());
a.record_async("t", &session, 2, true, now).await;
let b = SessionPromoter::new(cfg())
.expect("cfg")
.with_shared(store.clone());
assert_eq!(
b.decide_async("t", &session, now).await,
Decision::Promoted(2),
"a session that escalated on one replica must not start cold on the next"
);
assert_eq!(
b.decide_async("other-tenant", &session, now).await,
Decision::Cold,
"promotion must not cross tenants through the shared store"
);
}
#[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");
}
}