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