Skip to main content

firstpass_proxy/
shadow.rs

1//! Shadow-spend ledger (ADR 0009 D2).
2//!
3//! Shadow scoring makes **real model calls** to answer "what would Firstpass have served, and what
4//! would it have cost?" for traffic that is only being observed. That is the number an operator
5//! needs before flipping to enforce, and it is not free.
6//!
7//! So the ceiling is not advisory. This ledger is checked before every shadow evaluation and
8//! debited after it, and when a day's budget is exhausted shadow work stops and *says so* — a
9//! measurement that silently degrades is worse than one that never ran, because the operator
10//! keeps trusting a projection that has quietly stopped tracking their traffic.
11//!
12//! Scoped per (tenant, route) so one tenant's shadow spend cannot consume another's budget, which
13//! matters the moment this runs anywhere multi-tenant (ADR 0004).
14
15use std::collections::HashMap;
16use std::sync::Mutex;
17
18/// UTC day number, used as the reset boundary. A calendar day is the unit an operator budgets in.
19fn day_of(ts: jiff::Timestamp) -> i64 {
20    ts.as_second().div_euclid(86_400)
21}
22
23/// Why a shadow evaluation did not run. Recorded rather than swallowed.
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25pub enum Skip {
26    /// This request was not in the configured sample.
27    NotSampled,
28    /// The day's shadow budget is spent.
29    BudgetExhausted,
30}
31
32/// Per-(tenant, route) shadow spend for the current UTC day.
33#[derive(Debug, Default)]
34pub struct ShadowLedger {
35    inner: Mutex<HashMap<(String, usize), (i64, f64)>>, // key -> (day, spent_usd)
36}
37
38impl ShadowLedger {
39    /// A fresh ledger.
40    #[must_use]
41    pub fn new() -> Self {
42        Self::default()
43    }
44
45    /// Whether a shadow evaluation may start, given the day's ceiling.
46    ///
47    /// Checked *before* the call rather than after, because the point of a ceiling is to not spend
48    /// the money — discovering the overrun afterwards defeats it. The trade is that a single
49    /// evaluation can overshoot by its own cost; with per-call costs in fractions of a cent
50    /// against a dollar-scale daily cap that is immaterial, and erring toward one extra cheap call
51    /// is better than erring toward silently skipping measurements.
52    pub fn may_spend(
53        &self,
54        tenant: &str,
55        route_ix: usize,
56        max_usd_per_day: f64,
57        now: jiff::Timestamp,
58    ) -> bool {
59        if max_usd_per_day <= 0.0 {
60            return false;
61        }
62        let today = day_of(now);
63        let mut g = match self.inner.lock() {
64            Ok(g) => g,
65            // A poisoned lock must not take shadow down with it, and must not be treated as
66            // "budget available" either — refusing to spend is the safe direction.
67            Err(_) => return false,
68        };
69        let e = g
70            .entry((tenant.to_owned(), route_ix))
71            .or_insert((today, 0.0));
72        if e.0 != today {
73            *e = (today, 0.0); // new UTC day, fresh budget
74        }
75        e.1 < max_usd_per_day
76    }
77
78    /// Record what a completed shadow evaluation cost.
79    pub fn debit(&self, tenant: &str, route_ix: usize, usd: f64, now: jiff::Timestamp) {
80        if !usd.is_finite() || usd <= 0.0 {
81            return;
82        }
83        let today = day_of(now);
84        if let Ok(mut g) = self.inner.lock() {
85            let e = g
86                .entry((tenant.to_owned(), route_ix))
87                .or_insert((today, 0.0));
88            if e.0 != today {
89                *e = (today, 0.0);
90            }
91            e.1 += usd;
92        }
93    }
94
95    /// Re-apply spend recorded at `at`, but only if `at` falls on the same UTC day as `now`. Used
96    /// at startup to rebuild today's total from persisted evaluations, so restarting the process
97    /// does not hand out a fresh daily budget.
98    pub fn seed(
99        &self,
100        tenant: &str,
101        route_ix: usize,
102        usd: f64,
103        at: jiff::Timestamp,
104        now: jiff::Timestamp,
105    ) {
106        if day_of(at) == day_of(now) {
107            self.debit(tenant, route_ix, usd, now);
108        }
109    }
110
111    /// Spend so far today, for reporting.
112    #[must_use]
113    pub fn spent_today(&self, tenant: &str, route_ix: usize, now: jiff::Timestamp) -> f64 {
114        let today = day_of(now);
115        self.inner
116            .lock()
117            .ok()
118            .and_then(|g| g.get(&(tenant.to_owned(), route_ix)).copied())
119            .filter(|(d, _)| *d == today)
120            .map_or(0.0, |(_, spent)| spent)
121    }
122}
123
124#[cfg(test)]
125mod tests {
126    use super::*;
127
128    /// Startup seeding counts today's persisted spend toward today's cap and ignores yesterday's.
129    #[test]
130    fn seed_counts_only_spend_from_the_same_utc_day() {
131        let now: jiff::Timestamp = "2026-10-31T12:00:00Z".parse().unwrap();
132        let earlier_today: jiff::Timestamp = "2026-10-31T00:00:01Z".parse().unwrap();
133        let yesterday: jiff::Timestamp = "2026-10-30T23:59:59Z".parse().unwrap();
134        let l = ShadowLedger::new();
135        l.seed("t", 0, 0.75, yesterday, now);
136        l.seed("t", 0, 0.60, earlier_today, now);
137        l.seed("t", 0, 0.50, earlier_today, now);
138        assert!((l.spent_today("t", 0, now) - 1.10).abs() < 1e-12);
139        assert!(
140            !l.may_spend("t", 0, 1.0, now),
141            "seeded spend counts toward the cap"
142        );
143        assert!(l.may_spend("other", 0, 1.0, now), "per tenant");
144    }
145
146    fn ts(secs: i64) -> jiff::Timestamp {
147        jiff::Timestamp::from_second(secs).unwrap()
148    }
149
150    #[test]
151    fn spending_stops_at_the_ceiling() {
152        let l = ShadowLedger::new();
153        let now = ts(1_000_000);
154        assert!(
155            l.may_spend("t", 0, 1.00, now),
156            "fresh budget must allow the first call"
157        );
158        l.debit("t", 0, 0.60, now);
159        assert!(
160            l.may_spend("t", 0, 1.00, now),
161            "0.60 of 1.00 spent — still under"
162        );
163        l.debit("t", 0, 0.50, now);
164        assert!(
165            !l.may_spend("t", 0, 1.00, now),
166            "1.10 of 1.00 spent — must refuse, or the ceiling is decoration"
167        );
168    }
169
170    /// The budget is per UTC day; a new day must restore it, or shadow silently dies after the
171    /// first busy day and the operator's projection stops tracking without any signal.
172    #[test]
173    fn budget_resets_on_a_new_utc_day() {
174        let l = ShadowLedger::new();
175        let day1 = ts(86_400 * 100);
176        l.debit("t", 0, 5.0, day1);
177        assert!(!l.may_spend("t", 0, 1.0, day1));
178        let day2 = ts(86_400 * 101);
179        assert!(
180            l.may_spend("t", 0, 1.0, day2),
181            "new UTC day must restore the budget"
182        );
183        assert!((l.spent_today("t", 0, day2) - 0.0).abs() < f64::EPSILON);
184    }
185
186    /// One tenant must not be able to exhaust another's shadow budget.
187    #[test]
188    fn budgets_are_isolated_per_tenant_and_route() {
189        let l = ShadowLedger::new();
190        let now = ts(1_000_000);
191        l.debit("noisy", 0, 99.0, now);
192        assert!(!l.may_spend("noisy", 0, 1.0, now));
193        assert!(
194            l.may_spend("quiet", 0, 1.0, now),
195            "another tenant's budget was consumed"
196        );
197        assert!(
198            l.may_spend("noisy", 1, 1.0, now),
199            "another route's budget was consumed"
200        );
201    }
202
203    /// A zero or negative ceiling means "never", not "unlimited" — the failure direction of a
204    /// misconfigured budget must be to spend nothing.
205    #[test]
206    fn non_positive_ceiling_never_spends() {
207        let l = ShadowLedger::new();
208        let now = ts(1_000_000);
209        assert!(!l.may_spend("t", 0, 0.0, now));
210        assert!(!l.may_spend("t", 0, -5.0, now));
211    }
212
213    #[test]
214    fn nonsense_debits_are_ignored() {
215        let l = ShadowLedger::new();
216        let now = ts(1_000_000);
217        for bad in [f64::NAN, f64::INFINITY, -1.0, 0.0] {
218            l.debit("t", 0, bad, now);
219        }
220        assert!((l.spent_today("t", 0, now) - 0.0).abs() < f64::EPSILON);
221        assert!(l.may_spend("t", 0, 1.0, now));
222    }
223}