Skip to main content

firstpass_proxy/
affinity.rs

1//! Session promotion (SPEC §8.4): start a continuing session on the rung it already needed.
2//!
3//! `[escalation.session_promotion]` has been parseable — and exported from `firstpass_core` — since
4//! before this module existed, but nothing ever read it. A config that parses and does nothing is
5//! the same class of defect as a receipt that records `$0.00`: the file states one thing and the
6//! system does another, with no error to notice. This makes it real.
7//!
8//! ## What it buys
9//!
10//! The escalation tax, measured at 18% of first-pass spend on MBPP: when turn 1 of a conversation
11//! escalates haiku → sonnet, turn 2 pays for the doomed haiku call all over again, and so does
12//! turn 3. A session that has demonstrated it needs the stronger rung should start there.
13//!
14//! ## What it must not become
15//!
16//! A ratchet. Promotion on its own is one-way — a session that escalates once would stay expensive
17//! for its whole life, including the trivial turns at the end ("thanks, that worked"). So every
18//! `probe_every` turns the promotion is deliberately ignored and the request starts one rung lower.
19//! If that cheaper rung passes its gate, the promotion is released. That probe is the only way a
20//! promotion ever comes down, which is why it is not optional.
21//!
22//! ## What it cannot do
23//!
24//! Lower quality. Like the bandit, this chooses only where the ladder **starts**; the gate still
25//! verifies whatever is served, and escalation still runs from wherever it started. A wrong
26//! promotion costs money, never correctness — and the probe bounds even that.
27
28use std::collections::HashMap;
29use std::sync::Mutex;
30use std::time::{Duration, Instant};
31
32use firstpass_core::config::SessionPromotion;
33
34/// Per-session state. Small and `Copy`-cheap; there is one of these per live session.
35#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
36pub struct Pin {
37    /// Rung this session is promoted to, once `failures` has crossed the threshold.
38    pub rung: u32,
39    /// Gate failures observed inside the window.
40    pub failures: u32,
41    /// Turns served since the last downward probe.
42    pub since_probe: u32,
43    /// Last touch, for both TTL expiry and eviction order.
44    ///
45    /// Skipped on the wire and re-stamped on read: an `Instant` is meaningless in another process,
46    /// and expiry in the shared store is Redis's own TTL rather than a comparison two replicas'
47    /// monotonic clocks would disagree about.
48    #[serde(skip, default = "Instant::now")]
49    pub seen: Instant,
50}
51
52/// What the router should do for this request.
53#[derive(Debug, Clone, Copy, PartialEq, Eq)]
54pub enum Decision {
55    /// Start at rung 0, as if promotion were off.
56    Cold,
57    /// Start at this rung — the session has earned the promotion.
58    Promoted(u32),
59    /// Start one rung below the promotion, to test whether it is still needed.
60    Probe(u32),
61}
62
63impl Decision {
64    /// The rung to actually start on.
65    #[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    /// Label for the audit trace, so a receipt says *why* it did not start at rung 0.
74    #[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
84/// Decide from a pin alone. Pure — every rule below is testable without a clock or a map.
85fn 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    // Time to check whether the promotion is still earned. `probe_every` of 0 would divide by
93    // zero and also means "never probe", which is the ratchet this must not have — treat it as 1.
94    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/// Where promotion state lives.
101///
102/// Same seam as the verified cache, for the same reason: in-process state fragments behind a load
103/// balancer. A session that escalated on replica A starts cold on replica B, so the escalation tax
104/// this feature exists to remove is paid again on roughly (N-1)/N of turns.
105///
106/// **Concurrent turns of one session race.** `record` is a read-modify-write, and two replicas
107/// handling turns simultaneously can lose one increment — last write wins. That is deliberate
108/// rather than overlooked: the cost is a promotion arriving one turn late, which is one extra
109/// cheap-rung call. The gate still verifies whatever is served, so the race cannot affect
110/// correctness, and a Lua script or WATCH loop to remove it would add real complexity to an
111/// optimisation.
112#[async_trait::async_trait]
113pub trait PromotionStore: Send + Sync + std::fmt::Debug {
114    /// Read a session's pin, if one is live.
115    async fn load(&self, key: &str, now: Instant) -> Option<Pin>;
116    /// Write a session's pin.
117    async fn store(&self, key: &str, pin: Pin, now: Instant);
118}
119
120/// Key for a session's promotion. Tenant first, and not optional: a session id is only unique
121/// inside a tenant, and one tenant's traffic pattern is not a fact about another's.
122#[must_use]
123pub fn promotion_key(tenant: &str, session: &str) -> String {
124    format!("{tenant}|{session}")
125}
126
127/// Tracks which sessions have earned a higher starting rung.
128///
129/// Keyed by `(tenant, session)`: a session id is only unique inside a tenant, and a promotion must
130/// never cross that boundary — one tenant's traffic pattern is not a fact about another's.
131#[derive(Debug)]
132pub struct SessionPromoter {
133    cfg: SessionPromotion,
134    ttl: Duration,
135    /// Shared backing, when configured. `None` uses `pins` below — the in-process map — so a
136    /// single-instance deployment is byte-identical to before and pays for no network hop.
137    shared: Option<std::sync::Arc<dyn PromotionStore>>,
138    // ponytail: one mutex over the whole map. Each critical section is a hash lookup and a few
139    // integer writes, so contention is far below what a router's provider I/O costs. Shard by
140    // session hash if this ever shows up in a profile.
141    pins: Mutex<HashMap<String, Pin>>,
142}
143
144#[async_trait::async_trait]
145impl PromotionStore for SessionPromoter {
146    // Delegates to the existing map rather than reimplementing it: the in-process path is the one
147    // already covered by 12 tests, and a parallel async copy would be free to drift on the probe
148    // and ratchet rules that keep a promotion from becoming permanent.
149    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    /// Build from config. `window` doubles as the idle TTL.
179    ///
180    /// # Errors
181    /// [`firstpass_core::Error::BadDuration`] when `window` is not `<int><unit>`.
182    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    /// Back this promoter with a shared store, so a session keeps its rung across replicas.
193    #[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    /// Read a pin from wherever this promoter's state lives.
200    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    /// Write a pin to wherever this promoter's state lives.
208    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    /// Where this request should start.
216    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    /// Record how a request ended, against wherever this promoter's state lives.
222    ///
223    /// Read-modify-write, so two replicas handling concurrent turns of one session can lose an
224    /// increment — last write wins. The cost is a promotion arriving one turn late, which is one
225    /// extra cheap-rung call; the gate still verifies whatever is served, so it cannot affect
226    /// correctness.
227    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    /// Where this request should start.
258    #[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            // A poisoned lock must not take routing down; falling back to cold is always safe,
263            // because cold is exactly the behaviour with promotion disabled.
264            return Decision::Cold;
265        };
266        match pins.get(&key) {
267            // Expired pins are treated as absent here and reaped on the next write, so a read
268            // never has to take a write lock.
269            Some(p) if now.duration_since(p.seen) < self.ttl => decide(Some(p), &self.cfg),
270            _ => Decision::Cold,
271        }
272    }
273
274    /// Record how a request ended: which rung actually served it, and whether the ladder had to
275    /// climb to get there.
276    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            // The session needed a higher rung than it started on: that is the evidence promotion
307            // is for. Promote to where it actually landed.
308            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            // A probe (or any request) served below the promotion without escalating — the
313            // promotion is no longer earned. Release it to what actually worked. This is the path
314            // that stops promotion being one-way.
315            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    /// Drop expired entries, then oldest-first until under the cap.
324    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        // ponytail: full sort only on the rare over-cap write, not per request. A heap would be
330        // asymptotically better and materially more code for a path that runs approximately never.
331        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/// A Redis-backed promotion store, so a session keeps its rung across replicas.
343///
344/// Without it, promotion fragments behind a load balancer: a session that escalated on replica A
345/// starts cold on replica B, so the escalation tax this feature exists to remove is paid again on
346/// roughly (N-1)/N of turns — the feature is configured, reports nothing wrong, and does a fraction
347/// of its job.
348///
349/// One key per session, `fp:sp:<tenant>|<session>`, with a Redis TTL equal to the configured
350/// `window`. Expiry is the server's job for the same reason it is in the verified cache: two
351/// replicas comparing monotonic clocks would disagree about what is stale.
352///
353/// `max_sessions` does not apply here — a Redis-backed store is bounded by its TTL and the
354/// server's own eviction policy, and imposing a per-replica cap on a shared store would have each
355/// replica evicting the others' sessions.
356#[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        // Same reasoning as the cache's store: never print a URL that may carry credentials.
366        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    /// Connect to `url`, proving the connection with a PING.
375    ///
376    /// # Errors
377    /// A malformed URL, or a server that does not answer within the timeout. `ConnectionManager`
378    /// connects lazily, so without the PING this would report success against a dead server and
379    /// the proxy would run with promotion silently fragmented — configured, and not working.
380    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        // A malformed value is a miss, not an error: the session simply starts cold, which is
423        // exactly the behaviour with promotion off. Failing a request over it would turn an
424        // optimisation into an outage.
425        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        // Both APIs must agree, or a deployment gets different routing depending on which one the
463        // request path happens to call — a difference no test of either alone would surface.
464        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        // Redis carries pins between processes, where an Instant is meaningless. The routing state
475        // — rung, failures, probe counter — is what must cross; `seen` is re-stamped, and expiry
476        // there is Redis's TTL rather than two machines comparing monotonic clocks.
477        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    /// The shared store, against a real Redis.
496    ///
497    /// Requires `FIRSTPASS_TEST_REDIS`. **Fails without it rather than skipping** — a suite that
498    /// passes quietly when its subject is unavailable reports green having tested nothing.
499    #[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        // Replica A sees the escalation.
514        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        // Replica B — a different process in production — must see the promotion.
520        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        // And the tenant boundary still holds through the shared store.
530        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        // The escalation tax in one test: turn 1 climbs 0 → 1, so turn 2 must not pay for rung 0
546        // again.
547        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        // Without this the feature is a cost regression on any long conversation that gets easier.
570        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        // Serve at the promoted rung without escalating, probe_every(3) times.
576        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        // The probe served at rung 1 with no escalation — rung 2 is no longer earned.
597        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        // Probe started at 1, still had to climb to 2 → promotion re-earned.
616        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        // One tenant's traffic pattern is not a fact about another's, and a session id is only
623        // unique within a tenant.
624        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        // A permanent pin is a cost regression an operator would only discover in a bill, so it
667        // fails loudly at startup instead. `.max(1)` in `decide` is defence in depth for a config
668        // built in code rather than parsed.
669        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        // Defence in depth: constructed directly, 0 behaves as 1 rather than dividing or pinning.
686        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}