1use std::collections::HashMap;
29use std::sync::Mutex;
30use std::time::{Duration, Instant};
31
32use firstpass_core::config::SessionPromotion;
33
34#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
36pub struct Pin {
37 pub rung: u32,
39 pub failures: u32,
41 pub since_probe: u32,
43 #[serde(skip, default = "Instant::now")]
49 pub seen: Instant,
50}
51
52#[derive(Debug, Clone, Copy, PartialEq, Eq)]
54pub enum Decision {
55 Cold,
57 Promoted(u32),
59 Probe(u32),
61}
62
63impl Decision {
64 #[must_use]
66 pub const fn start_rung(self) -> u32 {
67 match self {
68 Self::Cold => 0,
69 Self::Promoted(r) | Self::Probe(r) => r,
70 }
71 }
72
73 #[must_use]
75 pub const fn reason(self) -> &'static str {
76 match self {
77 Self::Cold => "cold",
78 Self::Promoted(_) => "session-promoted",
79 Self::Probe(_) => "session-probe",
80 }
81 }
82}
83
84fn decide(pin: Option<&Pin>, cfg: &SessionPromotion) -> Decision {
86 let Some(pin) = pin else {
87 return Decision::Cold;
88 };
89 if pin.failures < cfg.after_failures || pin.rung == 0 {
90 return Decision::Cold;
91 }
92 if pin.since_probe >= cfg.probe_every.max(1) {
95 return Decision::Probe(pin.rung.saturating_sub(1));
96 }
97 Decision::Promoted(pin.rung)
98}
99
100#[async_trait::async_trait]
113pub trait PromotionStore: Send + Sync + std::fmt::Debug {
114 async fn load(&self, key: &str, now: Instant) -> Option<Pin>;
116 async fn store(&self, key: &str, pin: Pin, now: Instant);
118}
119
120#[must_use]
123pub fn promotion_key(tenant: &str, session: &str) -> String {
124 format!("{tenant}|{session}")
125}
126
127#[derive(Debug)]
132pub struct SessionPromoter {
133 cfg: SessionPromotion,
134 ttl: Duration,
135 shared: Option<std::sync::Arc<dyn PromotionStore>>,
138 pins: Mutex<HashMap<String, Pin>>,
142}
143
144#[async_trait::async_trait]
145impl PromotionStore for SessionPromoter {
146 async fn load(&self, key: &str, now: Instant) -> Option<Pin> {
150 let Ok(pins) = self.pins.lock() else {
151 return None;
152 };
153 pins.get(key)
154 .filter(|p| now.duration_since(p.seen) < self.ttl)
155 .copied()
156 }
157
158 async fn store(&self, key: &str, pin: Pin, now: Instant) {
159 let Ok(mut pins) = self.pins.lock() else {
160 return;
161 };
162 if pins.len() >= self.cfg.max_sessions {
163 pins.retain(|_, p| now.duration_since(p.seen) < self.ttl);
164 if pins.len() >= self.cfg.max_sessions {
165 let mut by_age: Vec<(String, Instant)> =
166 pins.iter().map(|(k, p)| (k.clone(), p.seen)).collect();
167 by_age.sort_by_key(|(_, t)| *t);
168 for (k, _) in by_age.into_iter().take(self.cfg.max_sessions.max(2) / 2) {
169 pins.remove(&k);
170 }
171 }
172 }
173 pins.insert(key.to_owned(), pin);
174 }
175}
176
177impl SessionPromoter {
178 pub fn new(cfg: SessionPromotion) -> firstpass_core::Result<Self> {
183 let ttl = cfg.window_duration()?;
184 Ok(Self {
185 cfg,
186 ttl,
187 shared: None,
188 pins: Mutex::new(HashMap::new()),
189 })
190 }
191
192 #[must_use]
194 pub fn with_shared(mut self, store: std::sync::Arc<dyn PromotionStore>) -> Self {
195 self.shared = Some(store);
196 self
197 }
198
199 async fn pin_for(&self, key: &str, now: Instant) -> Option<Pin> {
201 match self.shared.as_ref() {
202 Some(s) => s.load(key, now).await,
203 None => PromotionStore::load(self, key, now).await,
204 }
205 }
206
207 async fn put_pin(&self, key: &str, pin: Pin, now: Instant) {
209 match self.shared.as_ref() {
210 Some(s) => s.store(key, pin, now).await,
211 None => PromotionStore::store(self, key, pin, now).await,
212 }
213 }
214
215 pub async fn decide_async(&self, tenant: &str, session: &str, now: Instant) -> Decision {
217 let key = promotion_key(tenant, session);
218 decide(self.pin_for(&key, now).await.as_ref(), &self.cfg)
219 }
220
221 pub async fn record_async(
228 &self,
229 tenant: &str,
230 session: &str,
231 served_rung: u32,
232 escalated: bool,
233 now: Instant,
234 ) {
235 let key = promotion_key(tenant, session);
236 let mut pin = self.pin_for(&key, now).await.unwrap_or(Pin {
237 rung: 0,
238 failures: 0,
239 since_probe: 0,
240 seen: now,
241 });
242 pin.seen = now;
243 if escalated {
244 pin.failures = pin.failures.saturating_add(1);
245 pin.rung = pin.rung.max(served_rung);
246 pin.since_probe = 0;
247 } else if served_rung < pin.rung {
248 pin.rung = served_rung;
249 pin.failures = 0;
250 pin.since_probe = 0;
251 } else {
252 pin.since_probe = pin.since_probe.saturating_add(1);
253 }
254 self.put_pin(&key, pin, now).await;
255 }
256
257 #[must_use]
259 pub fn decide(&self, tenant: &str, session: &str, now: Instant) -> Decision {
260 let key = promotion_key(tenant, session);
261 let Ok(pins) = self.pins.lock() else {
262 return Decision::Cold;
265 };
266 match pins.get(&key) {
267 Some(p) if now.duration_since(p.seen) < self.ttl => decide(Some(p), &self.cfg),
270 _ => Decision::Cold,
271 }
272 }
273
274 pub fn record(
277 &self,
278 tenant: &str,
279 session: &str,
280 served_rung: u32,
281 escalated: bool,
282 now: Instant,
283 ) {
284 let key = promotion_key(tenant, session);
285 let Ok(mut pins) = self.pins.lock() else {
286 return;
287 };
288 self.evict_if_needed(&mut pins, now);
289
290 let expired = pins
291 .get(&key)
292 .is_some_and(|p| now.duration_since(p.seen) >= self.ttl);
293 if expired {
294 pins.remove(&key);
295 }
296
297 let entry = pins.entry(key).or_insert(Pin {
298 rung: 0,
299 failures: 0,
300 since_probe: 0,
301 seen: now,
302 });
303 entry.seen = now;
304
305 if escalated {
306 entry.failures = entry.failures.saturating_add(1);
309 entry.rung = entry.rung.max(served_rung);
310 entry.since_probe = 0;
311 } else if served_rung < entry.rung {
312 entry.rung = served_rung;
316 entry.failures = 0;
317 entry.since_probe = 0;
318 } else {
319 entry.since_probe = entry.since_probe.saturating_add(1);
320 }
321 }
322
323 fn evict_if_needed(&self, pins: &mut HashMap<String, Pin>, now: Instant) {
325 if pins.len() < self.cfg.max_sessions {
326 return;
327 }
328 pins.retain(|_, p| now.duration_since(p.seen) < self.ttl);
329 if pins.len() >= self.cfg.max_sessions {
332 let mut by_age: Vec<(String, Instant)> =
333 pins.iter().map(|(k, p)| (k.clone(), p.seen)).collect();
334 by_age.sort_by_key(|(_, seen)| *seen);
335 for (k, _) in by_age.into_iter().take(self.cfg.max_sessions.max(2) / 2) {
336 pins.remove(&k);
337 }
338 }
339 }
340}
341
342#[cfg(feature = "redis-cache")]
357pub struct RedisPromotionStore {
358 client: redis::aio::ConnectionManager,
359 ttl_secs: u64,
360}
361
362#[cfg(feature = "redis-cache")]
363impl std::fmt::Debug for RedisPromotionStore {
364 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
365 f.debug_struct("RedisPromotionStore")
367 .field("ttl_secs", &self.ttl_secs)
368 .finish_non_exhaustive()
369 }
370}
371
372#[cfg(feature = "redis-cache")]
373impl RedisPromotionStore {
374 pub async fn connect(url: &str, ttl_secs: u64) -> Result<Self, String> {
381 let safe = crate::verified_cache::redact_redis_url(url);
382 let client = redis::Client::open(url).map_err(|e| format!("redis url {safe}: {e}"))?;
383 let mgr = tokio::time::timeout(
384 std::time::Duration::from_secs(5),
385 redis::aio::ConnectionManager::new(client),
386 )
387 .await
388 .map_err(|_| format!("redis at {safe} did not answer within 5s"))?
389 .map_err(|e| format!("redis connect {safe}: {e}"))?;
390
391 let mut probe = mgr.clone();
392 let pong: Result<String, _> = tokio::time::timeout(
393 std::time::Duration::from_secs(5),
394 redis::cmd("PING").query_async(&mut probe),
395 )
396 .await
397 .map_err(|_| {
398 format!(
399 "redis at {safe} did not answer PING within 5s. Refusing to start rather than run \
400 with session promotion silently fragmented across replicas."
401 )
402 })?;
403 pong.map_err(|e| format!("redis at {safe} rejected PING: {e}"))?;
404
405 Ok(Self {
406 client: mgr,
407 ttl_secs,
408 })
409 }
410}
411
412#[cfg(feature = "redis-cache")]
413#[async_trait::async_trait]
414impl PromotionStore for RedisPromotionStore {
415 async fn load(&self, key: &str, _now: Instant) -> Option<Pin> {
416 let mut c = self.client.clone();
417 let raw: Option<String> = redis::cmd("GET")
418 .arg(format!("fp:sp:{key}"))
419 .query_async(&mut c)
420 .await
421 .ok()?;
422 serde_json::from_str(&raw?).ok()
426 }
427
428 async fn store(&self, key: &str, pin: Pin, _now: Instant) {
429 let Ok(body) = serde_json::to_string(&pin) else {
430 return;
431 };
432 let mut c = self.client.clone();
433 let _: Result<(), _> = redis::cmd("SETEX")
434 .arg(format!("fp:sp:{key}"))
435 .arg(self.ttl_secs)
436 .arg(body)
437 .query_async::<()>(&mut c)
438 .await;
439 }
440}
441
442#[cfg(test)]
443mod tests {
444 use super::*;
445
446 fn cfg() -> SessionPromotion {
447 SessionPromotion {
448 after_failures: 1,
449 window: "30m".to_owned(),
450 probe_every: 3,
451 max_sessions: 100,
452 redis_url: None,
453 }
454 }
455
456 fn promoter() -> SessionPromoter {
457 SessionPromoter::new(cfg()).expect("30m parses")
458 }
459
460 #[tokio::test]
461 async fn the_async_path_matches_the_sync_one() {
462 let p = promoter();
465 let now = Instant::now();
466 p.record_async("t", "s", 1, true, now).await;
467
468 assert_eq!(p.decide_async("t", "s", now).await, Decision::Promoted(1));
469 assert_eq!(p.decide("t", "s", now), Decision::Promoted(1));
470 }
471
472 #[tokio::test]
473 async fn a_pin_survives_serde_without_its_local_clock() {
474 let pin = Pin {
478 rung: 2,
479 failures: 3,
480 since_probe: 1,
481 seen: Instant::now(),
482 };
483 let wire = serde_json::to_string(&pin).expect("serializes");
484 assert!(
485 !wire.contains("seen"),
486 "a local Instant must not go on the wire: {wire}"
487 );
488
489 let back: Pin = serde_json::from_str(&wire).expect("deserializes");
490 assert_eq!(back.rung, 2);
491 assert_eq!(back.failures, 3);
492 assert_eq!(back.since_probe, 1);
493 }
494
495 #[cfg(feature = "redis-cache")]
500 #[tokio::test]
501 async fn promotion_survives_across_replicas() {
502 let url = std::env::var("FIRSTPASS_TEST_REDIS").unwrap_or_else(|_| {
503 panic!("set FIRSTPASS_TEST_REDIS (e.g. redis://127.0.0.1:6379/15) to run this test")
504 });
505 let store = std::sync::Arc::new(
506 RedisPromotionStore::connect(&url, 300)
507 .await
508 .expect("connect"),
509 );
510 let session = format!("sess-{}", uuid::Uuid::now_v7());
511 let now = Instant::now();
512
513 let a = SessionPromoter::new(cfg())
515 .expect("cfg")
516 .with_shared(store.clone());
517 a.record_async("t", &session, 2, true, now).await;
518
519 let b = SessionPromoter::new(cfg())
521 .expect("cfg")
522 .with_shared(store.clone());
523 assert_eq!(
524 b.decide_async("t", &session, now).await,
525 Decision::Promoted(2),
526 "a session that escalated on one replica must not start cold on the next"
527 );
528
529 assert_eq!(
531 b.decide_async("other-tenant", &session, now).await,
532 Decision::Cold,
533 "promotion must not cross tenants through the shared store"
534 );
535 }
536
537 #[test]
538 fn an_unknown_session_starts_cold() {
539 let p = promoter();
540 assert_eq!(p.decide("t", "never-seen", Instant::now()), Decision::Cold);
541 }
542
543 #[test]
544 fn a_session_that_escalated_starts_where_it_landed() {
545 let p = promoter();
548 let now = Instant::now();
549 p.record("t", "s", 1, true, now);
550 assert_eq!(p.decide("t", "s", now), Decision::Promoted(1));
551 assert_eq!(p.decide("t", "s", now).start_rung(), 1);
552 }
553
554 #[test]
555 fn one_escalation_is_not_enough_when_the_threshold_is_higher() {
556 let mut c = cfg();
557 c.after_failures = 3;
558 let p = SessionPromoter::new(c).expect("parses");
559 let now = Instant::now();
560 p.record("t", "s", 1, true, now);
561 p.record("t", "s", 1, true, now);
562 assert_eq!(p.decide("t", "s", now), Decision::Cold, "2 < 3");
563 p.record("t", "s", 1, true, now);
564 assert_eq!(p.decide("t", "s", now), Decision::Promoted(1));
565 }
566
567 #[test]
568 fn promotion_is_not_a_ratchet_it_probes_downward() {
569 let p = promoter();
571 let now = Instant::now();
572 p.record("t", "s", 2, true, now);
573 assert_eq!(p.decide("t", "s", now), Decision::Promoted(2));
574
575 for _ in 0..3 {
577 p.record("t", "s", 2, false, now);
578 }
579 assert_eq!(
580 p.decide("t", "s", now),
581 Decision::Probe(1),
582 "must periodically test one rung lower"
583 );
584 }
585
586 #[test]
587 fn a_successful_probe_releases_the_promotion() {
588 let p = promoter();
589 let now = Instant::now();
590 p.record("t", "s", 2, true, now);
591 for _ in 0..3 {
592 p.record("t", "s", 2, false, now);
593 }
594 assert_eq!(p.decide("t", "s", now), Decision::Probe(1));
595
596 p.record("t", "s", 1, false, now);
598 assert_eq!(
599 p.decide("t", "s", now),
600 Decision::Cold,
601 "released to rung 1"
602 );
603 }
604
605 #[test]
606 fn a_failed_probe_restores_the_promotion() {
607 let p = promoter();
608 let now = Instant::now();
609 p.record("t", "s", 2, true, now);
610 for _ in 0..3 {
611 p.record("t", "s", 2, false, now);
612 }
613 assert_eq!(p.decide("t", "s", now), Decision::Probe(1));
614
615 p.record("t", "s", 2, true, now);
617 assert_eq!(p.decide("t", "s", now), Decision::Promoted(2));
618 }
619
620 #[test]
621 fn a_promotion_never_crosses_a_tenant_boundary() {
622 let p = promoter();
625 let now = Instant::now();
626 p.record("tenant-a", "shared-id", 2, true, now);
627 assert_eq!(
628 p.decide("tenant-a", "shared-id", now),
629 Decision::Promoted(2)
630 );
631 assert_eq!(p.decide("tenant-b", "shared-id", now), Decision::Cold);
632 }
633
634 #[test]
635 fn an_idle_session_forgets_its_promotion() {
636 let mut c = cfg();
637 c.window = "1s".to_owned();
638 let p = SessionPromoter::new(c).expect("parses");
639 let t0 = Instant::now();
640 p.record("t", "s", 2, true, t0);
641 assert_eq!(p.decide("t", "s", t0), Decision::Promoted(2));
642
643 let later = t0 + Duration::from_secs(2);
644 assert_eq!(
645 p.decide("t", "s", later),
646 Decision::Cold,
647 "a reused session id must not inherit a stale rung"
648 );
649 }
650
651 #[test]
652 fn the_map_cannot_grow_without_bound() {
653 let mut c = cfg();
654 c.max_sessions = 10;
655 let p = SessionPromoter::new(c).expect("parses");
656 let now = Instant::now();
657 for i in 0..100 {
658 p.record("t", &format!("s{i}"), 1, true, now);
659 }
660 let len = p.pins.lock().expect("not poisoned").len();
661 assert!(len <= 10, "expected <= 10 tracked sessions, got {len}");
662 }
663
664 #[test]
665 fn probe_every_zero_is_rejected_at_parse_not_silently_coerced() {
666 let err = firstpass_core::config::Config::parse(
670 r#"
671 [escalation.session_promotion]
672 after_failures = 2
673 window = "30m"
674 probe_every = 0
675
676 [[route]]
677 mode = "enforce"
678 ladder = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-5"]
679 "#,
680 )
681 .expect_err("probe_every = 0 must not parse");
682 let msg = err.to_string();
683 assert!(msg.contains("probe_every"), "unhelpful message: {msg}");
684
685 let mut c = cfg();
687 c.probe_every = 0;
688 let pin = Pin {
689 rung: 2,
690 failures: 5,
691 since_probe: 1,
692 seen: Instant::now(),
693 };
694 assert_eq!(decide(Some(&pin), &c), Decision::Probe(1));
695 }
696
697 #[test]
698 fn a_valid_promotion_block_parses_with_defaults() {
699 let cfg = firstpass_core::config::Config::parse(
700 r#"
701 [escalation.session_promotion]
702 after_failures = 2
703 window = "30m"
704
705 [[route]]
706 mode = "enforce"
707 ladder = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-5"]
708 "#,
709 )
710 .expect("valid promotion config parses");
711 let p = cfg
712 .escalation
713 .session_promotion
714 .expect("promotion block present");
715 assert_eq!(p.after_failures, 2);
716 assert_eq!(p.probe_every, 5, "default must not be a ratchet");
717 assert_eq!(p.max_sessions, 10_000);
718 }
719
720 #[test]
721 fn the_decision_carries_its_reason_into_the_receipt() {
722 assert_eq!(Decision::Cold.reason(), "cold");
723 assert_eq!(Decision::Promoted(2).reason(), "session-promoted");
724 assert_eq!(Decision::Probe(1).reason(), "session-probe");
725 }
726}