firstpass_core/trace.rs
1//! The audit trace (SPEC §9.1) — the tamper-evident record of one routing decision.
2//!
3//! A trace captures *why* a request went where it did and *what it cost*: the features it was
4//! routed on, every attempt and its gate verdicts, the final served outcome, and the savings
5//! versus always calling the top rung. Each record links to the previous via [`Trace::prev_hash`]
6//! (see [`crate::hashchain`]), so the log is append-only and any tampering is detectable.
7//!
8//! **The serde field names in this module are the wire/audit contract.** External auditors
9//! parse them and re-derive the hash chain; renaming one is a breaking change that requires a
10//! schema/version bump, never a silent edit.
11
12use crate::Result;
13use crate::config::Mode;
14use crate::features::Features;
15use crate::hashchain::{Chained, record_hash};
16use crate::select::Arm;
17use crate::verdict::{GateResult, Score, Verdict};
18use jiff::Timestamp;
19use serde::{Deserialize, Serialize};
20use uuid::Uuid;
21
22/// Regime classification from the k-sample visible-pass count (ADR 0008).
23///
24/// The three regimes are validated on MBPP (k=5, n=150): 0/5 pass → 0% oracle-correct (12% of
25/// traffic); 5/5 pass → 99% oracle-correct (65%); 1–4/5 → mixed (23%). Keyed on the pass
26/// *count*, not entropy — the entropy AUC (0.431) was falsified; the count AUC is decisive.
27#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
28#[serde(rename_all = "snake_case")]
29pub enum ProbeRegime {
30 /// All k samples passed — oracle-correct ≈99% (validated on MBPP).
31 ConfidentPass,
32 /// Zero of k samples passed — oracle-correct ≈0%.
33 ConfidentFail,
34 /// 1..k-1 samples passed — mixed signal; verification information is worth its cost.
35 Ambiguous,
36}
37
38impl ProbeRegime {
39 /// Classify a pass-count into one of three regimes.
40 ///
41 /// - `0` → `ConfidentFail`
42 /// - `pass_count >= k` → `ConfidentPass`
43 /// - otherwise → `Ambiguous`
44 #[must_use]
45 pub fn classify(pass_count: u32, k: u32) -> Self {
46 if pass_count == 0 {
47 Self::ConfidentFail
48 } else if pass_count >= k {
49 Self::ConfidentPass
50 } else {
51 Self::Ambiguous
52 }
53 }
54}
55
56/// The shadow-probe signal recorded on a sampled receipt (ADR 0008 Phase 1). Records the k-sample
57/// gate-pass-count signal and its cost separately from the served cost, so savings math is clean.
58#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
59pub struct ProbeSignal {
60 /// Number of parallel probe samples drawn.
61 pub k: u32,
62 /// How many of the k samples would have been served under the route's gate/threshold rule.
63 pub gate_pass_count: u32,
64 /// Which of the three validated regimes this request falls into.
65 pub regime: ProbeRegime,
66 /// USD cost of the k shadow model calls — **separate** from `trace.final_.total_cost_usd`
67 /// so per-request savings math is not polluted by measurement cost.
68 pub probe_cost_usd: f64,
69}
70
71/// The action elastic verification (ADR 0008 Phase 3) took on the served rung.
72#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
73#[serde(rename_all = "snake_case")]
74pub enum ElasticAction {
75 /// Visible signal cleared λ → served **without** running the expensive gates (skip authorized
76 /// by the conformal bound). This is the un-verified serve the bound must cover.
77 ServeSkip,
78 /// Visible gates failed (signal at the floor) → escalated **without** paying for the expensive
79 /// gates on a doomed attempt.
80 EscalateNow,
81 /// Ambiguous middle → the expensive gates ran as usual; the gate decided.
82 Verified,
83}
84
85/// Why elastic verification (ADR 0008 Phase 3) skipped or ran the expensive gates on the served
86/// rung — recorded so an auditor can see *why* verification was skipped and check the conformal
87/// bound authorized it. Absent when elastic is off (the default), keeping pre-elastic traces
88/// byte-identical and hash-chain compatible.
89#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
90pub struct ElasticDecision {
91 /// Which of the three regimes fired.
92 pub action: ElasticAction,
93 /// The visible-gate score that drove the decision (`gate_score` over the cheap gates).
94 pub signal: f64,
95 /// The calibrated skip threshold λ the signal was compared against.
96 pub lambda: f64,
97 /// Target served-failure α the λ was calibrated at (provenance, from config).
98 #[serde(default, skip_serializing_if = "Option::is_none")]
99 pub alpha: Option<f64>,
100 /// Confidence (1−δ) the λ was calibrated at (provenance, from config).
101 #[serde(default, skip_serializing_if = "Option::is_none")]
102 pub delta: Option<f64>,
103 /// Provenance id of the calibration run that produced λ (from config).
104 #[serde(default, skip_serializing_if = "Option::is_none")]
105 pub calibration_id: Option<String>,
106}
107
108/// The rollout arm this request landed in (ADR 0009 D1), recorded so an auditor can re-derive
109/// arm membership from the receipt alone. Absent when the route has no rollout — byte-identical
110/// What Firstpass *would* have done for an observed request (ADR 0009 D2).
111///
112/// This describes a counterfactual that was never served, so it must never enter the conformal
113/// calibration set for served failures — it is a separate estimate with its own sample size.
114/// Pooling it with served outcomes would let a projection contaminate the published bound.
115#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
116pub struct ShadowSignal {
117 /// Rung that would have been served, if any gate passed.
118 #[serde(default, skip_serializing_if = "Option::is_none")]
119 pub would_serve_rung: Option<u32>,
120 /// Whether the ladder would have produced a servable answer at all.
121 pub would_pass: bool,
122 /// What the shadow evaluation cost to run.
123 pub projected_cost_usd: f64,
124 /// What the request actually cost upstream, for comparison.
125 pub actual_cost_usd: f64,
126 /// Present when shadow did not run, saying why — a skipped measurement is recorded rather
127 /// than silently absent, so a projection that has stopped tracking is visible in the record.
128 #[serde(default, skip_serializing_if = "Option::is_none")]
129 pub skipped: Option<String>,
130}
131
132/// to pre-rollout traces and hash-chain compatible.
133#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
134pub struct RolloutRecord {
135 /// Configured percent at decision time. Recorded because it changes as an operator ramps,
136 /// and a bound computed over a window spanning a ramp must be able to see that.
137 pub percent: f64,
138 /// Which identity was held constant (`session` / `request` / `tenant`).
139 pub key: String,
140 /// The bucket this request fell in, within `0..10_000`.
141 pub bucket: u32,
142 /// Whether this request enforced. The observed arm is not a failure — it is the control.
143 pub enforced: bool,
144}
145
146/// Which arm of a certified-selection experiment served this request (ADR 0014).
147///
148/// Present on every request of a route that has a `[route.challenger]`, in *both* arms: the
149/// incumbent arm is the control, and a log that only marked the challenger could not be split back
150/// into the two populations. `arm` is the ladder that actually served — once an experiment halts,
151/// sessions that would have gone to the challenger are served by the incumbent and are recorded
152/// as such, so per-arm cost is never blended.
153#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
154pub struct ExperimentRecord {
155 /// The ladder that served this request.
156 pub arm: Arm,
157 /// Configured challenger percent at decision time.
158 pub percent: f64,
159 /// The session's bucket within `0..10_000` (domain-tagged `challenger`).
160 pub bucket: u32,
161 /// Identity of the experiment configuration this request ran under (ladders, margin, alpha;
162 /// see `Challenger::fingerprint`). Evidence is only pooled across receipts that share it.
163 pub fingerprint: String,
164}
165
166/// A single routing decision, start to finish.
167#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
168pub struct Trace {
169 /// Time-ordered unique id (UUIDv7).
170 pub trace_id: Uuid,
171 /// Hash of the previous record in this chain (or [`crate::hashchain::GENESIS_HASH`]).
172 pub prev_hash: String,
173 /// Tenant this trace belongs to.
174 pub tenant_id: String,
175 /// Session (e.g. an agent run) this request is part of.
176 pub session_id: String,
177 /// When the decision was made.
178 pub ts: Timestamp,
179 /// Serving mode in effect.
180 pub mode: Mode,
181 /// Which policy produced this decision.
182 pub policy: PolicyRef,
183 /// The request that was routed.
184 pub request: RequestInfo,
185 /// Every attempt made, cheapest rung first.
186 pub attempts: Vec<Attempt>,
187 /// Verdicts that arrived after serving (deferred gates, feedback API). Attach over time.
188 #[serde(default, skip_serializing_if = "Vec::is_empty")]
189 pub deferred: Vec<DeferredVerdict>,
190 /// The final served outcome and its economics.
191 #[serde(rename = "final")]
192 pub final_: FinalOutcome,
193 /// Shadow probe signal (ADR 0008 Phase 1). Absent when probe is off (the default) or when
194 /// this request was not in the configured `sample_rate` — byte-identical to pre-probe traces
195 /// and hash-chain compatible (the `skip_serializing_if` keeps absent = absent).
196 #[serde(default, skip_serializing_if = "Option::is_none")]
197 pub probe: Option<ProbeSignal>,
198 /// Which rollout arm this request was in (ADR 0009 D1). Absent when the route has no
199 /// rollout configured.
200 #[serde(default, skip_serializing_if = "Option::is_none")]
201 pub rollout: Option<RolloutRecord>,
202 /// Counterfactual signal from shadow scoring (ADR 0009 D2). Absent unless shadow is enabled.
203 #[serde(default, skip_serializing_if = "Option::is_none")]
204 pub shadow: Option<ShadowSignal>,
205 /// Index of the route that handled this request, so a downstream outcome arriving later can
206 /// be attributed to the route that actually produced it (ADR 0009 D3).
207 ///
208 /// Without this the guardrail has to pool every tenant's outcomes onto one route, which in a
209 /// multi-route config means a failing route can be masked by healthy siblings — the guard
210 /// would sit green while the thing it guards degrades. Absent on traces written before this
211 /// field existed; the guardrail treats absent as route 0, its prior behaviour.
212 #[serde(default, skip_serializing_if = "Option::is_none")]
213 pub route_ix: Option<u32>,
214 /// Shadow prediction of `P(gate-pass)` for the start rung (ADR 0008 Phase 2), from the
215 /// per-query predictor. Absent when the predictor is off (the default) — byte-identical to
216 /// pre-predictor traces and hash-chain compatible. Recorded but never acted on in this phase.
217 #[serde(default, skip_serializing_if = "Option::is_none")]
218 pub predicted_pass: Option<f64>,
219 /// Cumulative gate-pass prior per ladder rung from the pre-generation decision-model prior
220 /// (verified predictive routing), in ladder order: `decision_prior[r]` is `P(rung r fully
221 /// handles this request)`. Absent when `[escalation.prior]` is off (the default) —
222 /// byte-identical to pre-prior traces and hash-chain compatible. Feeds the start-rung
223 /// expected-cost argmin; the gate still verifies every output regardless.
224 #[serde(default, skip_serializing_if = "Option::is_none")]
225 pub decision_prior: Option<Vec<f64>>,
226 /// Elastic verification decision (ADR 0008 Phase 3) on the served rung: why the expensive gates
227 /// were skipped or run, plus the λ / calibration provenance the skip was authorized under.
228 /// Absent when elastic is off (the default) — byte-identical to pre-elastic traces and
229 /// hash-chain compatible (the `skip_serializing_if` keeps absent = absent).
230 #[serde(default, skip_serializing_if = "Option::is_none")]
231 pub elastic: Option<ElasticDecision>,
232 /// The risk-control certificate the serve threshold was taken from: which controller, the
233 /// threshold, and the evidence behind it. Inside the hash chain, so an auditor can check from
234 /// the receipt alone which guarantee this answer was served under — and a later edit to it
235 /// breaks the chain. Absent when no serve threshold was in force (plain pass/fail serving) —
236 /// byte-identical to earlier traces and hash-chain compatible.
237 #[serde(default, skip_serializing_if = "Option::is_none")]
238 pub risk: Option<RiskCertificate>,
239 /// Which certified-selection arm served this request (ADR 0014). Absent unless the route has
240 /// a `[route.challenger]` — byte-identical to earlier traces and hash-chain compatible.
241 #[serde(default, skip_serializing_if = "Option::is_none")]
242 pub experiment: Option<ExperimentRecord>,
243}
244
245/// Which controller supplied the serve threshold. Precedence is e-process > ACI > fixed
246/// (ADR 0011): only the e-process's bound holds at the round it is read.
247#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
248#[serde(rename_all = "snake_case")]
249pub enum ThresholdSource {
250 /// Anytime-valid e-process: served-failure ≤ α at every round, with probability ≥ 1−δ.
251 Eprocess,
252 /// Adaptive conformal: long-run average served-failure → α. No per-round guarantee.
253 Aci,
254 /// A configured constant. No guarantee is claimed.
255 Fixed,
256}
257
258/// The guarantee a served answer was decided under (see [`Trace::risk`]).
259#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
260pub struct RiskCertificate {
261 /// Which controller supplied the threshold.
262 pub source: ThresholdSource,
263 /// The serve threshold in force: a gate score at or above it was servable.
264 pub threshold: f64,
265 /// Target served-failure rate (e-process, ACI).
266 #[serde(default, skip_serializing_if = "Option::is_none")]
267 pub alpha: Option<f64>,
268 /// Family-wise error budget (e-process only).
269 #[serde(default, skip_serializing_if = "Option::is_none")]
270 pub delta: Option<f64>,
271 /// E-value backing the threshold; `>= 1/delta` whenever certified (e-process only).
272 #[serde(default, skip_serializing_if = "Option::is_none")]
273 pub e_value: Option<f64>,
274 /// Round at which the threshold was first certified (e-process only).
275 #[serde(default, skip_serializing_if = "Option::is_none")]
276 pub certified_at_round: Option<u64>,
277}
278
279/// Reference to the policy that produced a decision.
280#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
281pub struct PolicyRef {
282 /// Policy identity/version, e.g. `"static@v0"` or `"bandit@v3"`.
283 pub id: String,
284 /// Whether this decision was a deliberate exploration draw (bounded, §, only in enforce).
285 #[serde(default)]
286 pub explore: bool,
287 /// The probability the logging policy assigned to the start rung it chose — the
288 /// Horvitz-Thompson denominator for IPS / SNIPS off-policy evaluation.
289 ///
290 /// `None` for deterministic (non-exploring) policies. `skip_serializing_if` keeps old
291 /// trace bytes byte-identical when `None`, preserving hash-chain compatibility with
292 /// existing logs. Only populated when `[escalation.exploration]` is configured.
293 #[serde(default, skip_serializing_if = "Option::is_none")]
294 pub propensity: Option<f64>,
295 /// Resolved routing-mode profile when it was explicitly set (header / route / global env).
296 /// `None` means `Balanced` was in effect (the default, no override active). Absent from
297 /// the JSON when `None` → byte-identical serialization for all existing traces.
298 #[serde(default, skip_serializing_if = "Option::is_none")]
299 pub mode_profile: Option<String>,
300}
301
302/// The routed request, described without its raw content.
303#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
304pub struct RequestInfo {
305 /// Wire API the caller used, e.g. `"anthropic.messages"` / `"openai.chat"`.
306 pub api: String,
307 /// Salted hash of the prompt — never the prompt text itself.
308 pub prompt_hash: String,
309 /// The versioned feature vector routing keyed on.
310 pub features: Features,
311}
312
313/// One attempt at a rung: the model call plus the gates run against its output.
314#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
315pub struct Attempt {
316 /// Ladder rung (0 = cheapest).
317 pub rung: u32,
318 /// Model called, `provider/model`.
319 pub model: String,
320 /// Provider segment (denormalized for cheap querying).
321 pub provider: String,
322 /// Input tokens consumed, **uncached only**.
323 ///
324 /// When the caller uses prompt caching this is the small remainder; the bulk of the prompt is
325 /// reported separately below and billed at different rates. Read `billable_input()` rather
326 /// than this field for anything cost-shaped.
327 pub in_tokens: u64,
328 /// Prompt tokens written to the provider's cache on this call, billed at a **premium**
329 /// (Anthropic: 1.25× base input).
330 ///
331 /// Defaults to 0, so a receipt written before this field existed still deserializes and still
332 /// re-derives the same hash — the field is skipped when zero.
333 #[serde(default, skip_serializing_if = "is_zero")]
334 pub cache_write_tokens: u64,
335 /// Prompt tokens served from the provider's cache, billed at a **discount** (Anthropic: 0.1×
336 /// base input). Same zero-default reasoning as `cache_write_tokens`.
337 #[serde(default, skip_serializing_if = "is_zero")]
338 pub cache_read_tokens: u64,
339 /// Output tokens produced.
340 pub out_tokens: u64,
341 /// USD cost of this model call (excludes gate cost).
342 pub cost_usd: f64,
343 /// Wall-clock latency of the model call.
344 pub latency_ms: u64,
345 /// Gate verdicts for this attempt's output.
346 pub gates: Vec<GateResult>,
347 /// The attempt's overall verdict (the aggregate that drove escalate-or-serve).
348 pub verdict: Verdict,
349 /// The model stopped at the request's output-token limit, so the answer is cut off and a gate
350 /// failure on it may describe the cap rather than the model. Skipped when false, so a receipt
351 /// written before this field existed still re-derives the same hash.
352 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
353 pub truncated: bool,
354}
355
356/// `skip_serializing_if` helper: keeps zero-valued cache fields out of the canonical JSON, so a
357/// receipt written before those fields existed hashes identically to one written after.
358#[allow(clippy::trivially_copy_pass_by_ref)] // serde requires the &-taking shape
359fn is_zero(n: &u64) -> bool {
360 *n == 0
361}
362
363impl Trace {
364 /// Milliseconds this proxy added on top of the work it actually dispatched — provider calls
365 /// plus gates. The number a gateway is judged on, and the one Firstpass could not previously
366 /// state about itself.
367 ///
368 /// Returns `None` rather than a wrong figure when it cannot be computed honestly. Under
369 /// speculation, rungs run concurrently, so the summed work legitimately exceeds wall-clock and
370 /// the subtraction is meaningless; a receipt like that is excluded from an overhead
371 /// distribution instead of being floored to zero, which would silently drag a p95 down.
372 ///
373 /// Deliberately derived rather than stored: a recorded overhead field could disagree with the
374 /// timings beside it, and this way an auditor recomputes it from the same numbers we do.
375 #[must_use]
376 pub fn overhead_ms(&self) -> Option<u64> {
377 let dispatched: u64 = self
378 .attempts
379 .iter()
380 .map(|a| {
381 a.latency_ms
382 .saturating_add(a.gates.iter().map(|g| g.ms).sum::<u64>())
383 })
384 .sum();
385 self.final_.total_latency_ms.checked_sub(dispatched)
386 }
387}
388
389impl Attempt {
390 /// Total prompt tokens this call actually consumed, cached or not.
391 ///
392 /// `in_tokens` alone is **not** the prompt size when the caller uses prompt caching: providers
393 /// report the cached portion in separate fields, and a 190k-token cached prefix shows up as an
394 /// `in_tokens` of about 20. Anything reporting prompt volume wants this, not the raw field.
395 #[must_use]
396 pub const fn billable_input(&self) -> u64 {
397 self.in_tokens
398 .saturating_add(self.cache_write_tokens)
399 .saturating_add(self.cache_read_tokens)
400 }
401}
402
403/// A verdict that arrived after the response was served (deferred gate or downstream feedback).
404#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
405pub struct DeferredVerdict {
406 /// Gate/source identity, e.g. `"tests"` or `"feedback:ci"`.
407 pub gate_id: String,
408 /// The late verdict.
409 pub verdict: Verdict,
410 /// Optional score.
411 #[serde(default, skip_serializing_if = "Option::is_none")]
412 pub score: Option<Score>,
413 /// When it arrived.
414 pub reported_at: Timestamp,
415 /// Who reported it (a deferred gate, or a feedback-API caller identity).
416 pub reporter: String,
417}
418
419/// Where the served response came from.
420#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
421#[serde(rename_all = "snake_case")]
422pub enum ServedFrom {
423 /// A passing attempt (the normal path).
424 Attempt,
425 /// The best attempt seen, served because budget/ladder was exhausted without a pass.
426 BestAttempt,
427 /// No output served; a structured error was returned.
428 Error,
429 /// Replayed from the verified cache: this exact prompt was answered before, that answer
430 /// **passed its gate**, and the receipt names the decision that proved it.
431 ///
432 /// Distinct from [`ServedFrom::Attempt`] because no model was called — a receipt that reported
433 /// this as a normal attempt would claim a verification that did not run today, and inflate
434 /// every pass-rate computed over receipts. `cache_source` carries the trace it came from, so
435 /// the proof is one lookup away rather than asserted.
436 Cache,
437}
438
439/// The final outcome and economics of a decision.
440#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
441pub struct FinalOutcome {
442 /// Rung whose output was served (`None` if `served_from = error`).
443 #[serde(default, skip_serializing_if = "Option::is_none")]
444 pub served_rung: Option<u32>,
445 /// Provenance of the served response.
446 pub served_from: ServedFrom,
447 /// Total USD spent (all model calls + all gates).
448 pub total_cost_usd: f64,
449 /// USD portion spent on gates alone.
450 pub gate_cost_usd: f64,
451 /// Total wall-clock latency the caller experienced.
452 pub total_latency_ms: u64,
453 /// Number of rung escalations taken.
454 pub escalations: u32,
455 /// What always calling the top rung would have cost (§9.1 counterfactual).
456 pub counterfactual_baseline_usd: f64,
457 /// The decision this answer was replayed from, when `served_from = cache`.
458 ///
459 /// The whole point of a verified cache: the receipt does not merely say "cached", it names the
460 /// earlier decision whose gate passed, so an auditor can follow the link and check that the
461 /// thing being replayed was actually proven. Absent otherwise, so pre-cache receipts serialize
462 /// byte-identically and re-derive the same hash.
463 #[serde(default, skip_serializing_if = "Option::is_none")]
464 pub cache_source: Option<Uuid>,
465 /// `counterfactual_baseline_usd - total_cost_usd` — the savings this decision proves.
466 pub savings_usd: f64,
467}
468
469impl Chained for Trace {
470 fn prev_hash(&self) -> &str {
471 &self.prev_hash
472 }
473}
474
475impl Trace {
476 /// This record's own hash (SHA-256 over its canonical JSON) — the value the *next*
477 /// record stores as its `prev_hash`.
478 ///
479 /// # Errors
480 /// Returns [`crate::Error::Json`] if the trace cannot be serialized.
481 pub fn hash(&self) -> Result<String> {
482 record_hash(self)
483 }
484
485 /// Compute `savings_usd = baseline - total` and store it, keeping the field consistent
486 /// with the two it is derived from. Returns the savings.
487 pub fn recompute_savings(&mut self) -> f64 {
488 let s = self.final_.counterfactual_baseline_usd - self.final_.total_cost_usd;
489 self.final_.savings_usd = s;
490 s
491 }
492}
493
494impl std::fmt::Display for Trace {
495 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
496 write!(
497 f,
498 "trace {} rung {:?} served_from {:?} cost ${:.4} saved ${:.4}",
499 self.trace_id,
500 self.final_.served_rung,
501 self.final_.served_from,
502 self.final_.total_cost_usd,
503 self.final_.savings_usd,
504 )
505 }
506}
507
508#[cfg(test)]
509mod tests {
510 use super::*;
511 use crate::features::{Features, TaskKind};
512 use crate::hashchain::{GENESIS_HASH, verify_chain};
513 use crate::verdict::Verdict;
514
515 fn sample_trace(prev_hash: &str, id: u128) -> Trace {
516 let mut t = Trace {
517 trace_id: Uuid::from_u128(id),
518 prev_hash: prev_hash.to_owned(),
519 tenant_id: "acme".into(),
520 session_id: "agent-run-4417".into(),
521 ts: "2026-07-08T15:04:05Z".parse().unwrap(),
522 mode: Mode::Enforce,
523 policy: PolicyRef {
524 id: "static@v0".into(),
525 explore: false,
526 propensity: None,
527 mode_profile: None,
528 },
529 request: RequestInfo {
530 api: "anthropic.messages".into(),
531 prompt_hash: "deadbeef".into(),
532 features: Features::new(TaskKind::CodeEdit),
533 },
534 attempts: vec![
535 Attempt {
536 rung: 0,
537 model: "anthropic/claude-haiku-4-5".into(),
538 provider: "anthropic".into(),
539 in_tokens: 2000,
540 cache_write_tokens: 0,
541 cache_read_tokens: 0,
542 out_tokens: 700,
543 cost_usd: 0.0007,
544 latency_ms: 900,
545 gates: vec![GateResult::deterministic("cargo-test", Verdict::Fail, 3100)],
546 verdict: Verdict::Fail,
547 truncated: false,
548 },
549 Attempt {
550 rung: 1,
551 model: "anthropic/claude-sonnet-5".into(),
552 provider: "anthropic".into(),
553 in_tokens: 2000,
554 cache_write_tokens: 0,
555 cache_read_tokens: 0,
556 out_tokens: 800,
557 cost_usd: 0.0121,
558 latency_ms: 1200,
559 gates: vec![GateResult::deterministic("cargo-test", Verdict::Pass, 2950)],
560 verdict: Verdict::Pass,
561 truncated: false,
562 },
563 ],
564 deferred: vec![],
565 final_: FinalOutcome {
566 served_rung: Some(1),
567 served_from: ServedFrom::Attempt,
568 total_cost_usd: 0.0128,
569 gate_cost_usd: 0.0,
570 total_latency_ms: 2100,
571 escalations: 1,
572 counterfactual_baseline_usd: 0.0630,
573 savings_usd: 0.0,
574 cache_source: None,
575 },
576 probe: None,
577 rollout: None,
578 shadow: None,
579 route_ix: None,
580 predicted_pass: None,
581 decision_prior: None,
582 elastic: None,
583 risk: None,
584 experiment: None,
585 };
586 t.recompute_savings();
587 t
588 }
589
590 #[test]
591 fn wire_field_names_are_the_contract() {
592 let t = sample_trace(GENESIS_HASH, 1);
593 let j = serde_json::to_string(&t).unwrap();
594 assert!(j.contains("\"prev_hash\":"));
595 assert!(
596 j.contains("\"final\":"),
597 "the outcome key must serialize as `final`"
598 );
599 assert!(j.contains("\"served_from\":\"attempt\""));
600 assert!(j.contains("\"verdict\":\"fail\""));
601 assert!(j.contains("\"verdict\":\"pass\""));
602 assert!(j.contains("\"counterfactual_baseline_usd\":"));
603 }
604
605 #[test]
606 fn savings_is_baseline_minus_total() {
607 let t = sample_trace(GENESIS_HASH, 1);
608 assert!((t.final_.savings_usd - (0.0630 - 0.0128)).abs() < 1e-12);
609 }
610
611 #[test]
612 fn traces_chain_and_verify() {
613 let t0 = sample_trace(GENESIS_HASH, 1);
614 let t1 = sample_trace(&t0.hash().unwrap(), 2);
615 let chain = [t0, t1];
616 assert!(verify_chain(&chain, GENESIS_HASH).is_ok());
617 }
618
619 #[test]
620 fn tampering_a_served_trace_is_detectable() {
621 let t0 = sample_trace(GENESIS_HASH, 1);
622 let t1 = sample_trace(&t0.hash().unwrap(), 2);
623 let mut chain = [t0, t1];
624 chain[0].final_.total_cost_usd = 0.0; // forge a cheaper decision after the fact
625 assert!(verify_chain(&chain, GENESIS_HASH).is_err());
626 }
627
628 #[test]
629 fn roundtrips_through_json() {
630 let t = sample_trace(GENESIS_HASH, 7);
631 let j = serde_json::to_string(&t).unwrap();
632 let back: Trace = serde_json::from_str(&j).unwrap();
633 assert_eq!(t, back);
634 }
635
636 /// An attempt that was not cut off serializes without `truncated` and hashes exactly as a
637 /// receipt written before the field existed; a cut-off one carries it inside the chain.
638 #[test]
639 fn truncated_false_is_absent_and_hash_neutral() {
640 let t = sample_trace(GENESIS_HASH, 1);
641 let j = serde_json::to_string(&t).unwrap();
642 assert!(!j.contains("truncated"), "false must be omitted: {j}");
643 let back: Trace = serde_json::from_str(&j).unwrap();
644 assert!(!back.attempts[0].truncated);
645 assert_eq!(back.hash().unwrap(), t.hash().unwrap());
646
647 let mut cut = t.clone();
648 cut.attempts[0].truncated = true;
649 assert_ne!(cut.hash().unwrap(), t.hash().unwrap());
650 let jc = serde_json::to_string(&cut).unwrap();
651 assert!(jc.contains("\"truncated\":true"), "{jc}");
652 let rt: Trace = serde_json::from_str(&jc).unwrap();
653 assert_eq!(rt.hash().unwrap(), cut.hash().unwrap());
654 }
655
656 // ── experiment backward-compat ───────────────────────────────────────────
657
658 /// A trace without an experiment record must serialize without the key and hash exactly as it
659 /// did before the field existed; a trace with one must differ (it is inside the chain).
660 #[test]
661 fn experiment_none_is_absent_and_hash_neutral() {
662 let t = sample_trace(GENESIS_HASH, 1);
663 let j = serde_json::to_string(&t).unwrap();
664 assert!(!j.contains("experiment"), "None must be omitted: {j}");
665 // Re-derive the hash from the pre-field wire form: same JSON, so same hash.
666 let mut v: serde_json::Value = serde_json::from_str(&j).unwrap();
667 assert!(v.as_object_mut().unwrap().remove("experiment").is_none());
668 let back: Trace = serde_json::from_value(v).unwrap();
669 assert_eq!(back.hash().unwrap(), t.hash().unwrap());
670
671 let mut with = t.clone();
672 with.experiment = Some(ExperimentRecord {
673 arm: Arm::Challenger,
674 percent: 10.0,
675 bucket: 42,
676 fingerprint: "0123456789abcdef".to_owned(),
677 });
678 assert_ne!(with.hash().unwrap(), t.hash().unwrap());
679 let jw = serde_json::to_string(&with).unwrap();
680 assert!(jw.contains("\"arm\":\"challenger\""), "{jw}");
681 // The record's field names are the audit contract: a rename is a schema change.
682 for key in ["\"percent\":", "\"bucket\":", "\"fingerprint\":"] {
683 assert!(jw.contains(key), "missing {key} in {jw}");
684 }
685 let rt: Trace = serde_json::from_str(&jw).unwrap();
686 assert_eq!(rt, with);
687 }
688
689 // ── propensity backward-compat ────────────────────────────────────────────
690
691 /// Traces where propensity is None must serialize byte-identically to pre-field traces:
692 /// the field must be absent from the JSON, not serialized as `null`.
693 #[test]
694 fn propensity_none_absent_from_json() {
695 let pr = PolicyRef {
696 id: "static@v0".into(),
697 explore: false,
698 propensity: None,
699 mode_profile: None,
700 };
701 let j = serde_json::to_string(&pr).unwrap();
702 assert!(
703 !j.contains("propensity"),
704 "propensity=None must be omitted (skip_serializing_if): {j}"
705 );
706 }
707
708 /// Old JSON without a `propensity` field must deserialize to `propensity: None`
709 /// (via `#[serde(default)]`), keeping old traces readable without schema migration.
710 #[test]
711 fn old_trace_without_propensity_deserializes_to_none() {
712 let old_json = r#"{"id":"static@v0","explore":false}"#;
713 let pr: PolicyRef = serde_json::from_str(old_json).unwrap();
714 assert_eq!(pr.propensity, None);
715 }
716
717 /// New JSON with a propensity value round-trips correctly.
718 #[test]
719 fn propensity_some_roundtrips() {
720 let pr = PolicyRef {
721 id: "bandit@v1+eps".into(),
722 explore: true,
723 propensity: Some(0.3),
724 mode_profile: None,
725 };
726 let j = serde_json::to_string(&pr).unwrap();
727 assert!(
728 j.contains("\"propensity\":0.3"),
729 "expected propensity in: {j}"
730 );
731 let back: PolicyRef = serde_json::from_str(&j).unwrap();
732 assert_eq!(back, pr);
733 }
734
735 // ── mode_profile backward-compat ─────────────────────────────────────────
736
737 /// `mode_profile = None` must not appear in the serialized JSON — byte-identical for
738 /// existing traces (Balanced is the default and must be invisible).
739 #[test]
740 fn mode_profile_none_absent_from_json() {
741 let pr = PolicyRef {
742 id: "static@v0".into(),
743 explore: false,
744 propensity: None,
745 mode_profile: None,
746 };
747 let j = serde_json::to_string(&pr).unwrap();
748 assert!(
749 !j.contains("mode_profile"),
750 "mode_profile=None must be omitted (skip_serializing_if): {j}"
751 );
752 }
753
754 /// Old JSON without a `mode_profile` field deserializes to `mode_profile: None`.
755 #[test]
756 fn old_trace_without_mode_profile_deserializes_to_none() {
757 let old_json = r#"{"id":"static@v0","explore":false}"#;
758 let pr: PolicyRef = serde_json::from_str(old_json).unwrap();
759 assert_eq!(pr.mode_profile, None);
760 }
761
762 /// `mode_profile = Some(...)` round-trips correctly.
763 #[test]
764 fn mode_profile_some_roundtrips() {
765 let pr = PolicyRef {
766 id: "static@v0".into(),
767 explore: false,
768 propensity: None,
769 mode_profile: Some("quality".into()),
770 };
771 let j = serde_json::to_string(&pr).unwrap();
772 assert!(
773 j.contains("\"mode_profile\":\"quality\""),
774 "expected mode_profile in: {j}"
775 );
776 let back: PolicyRef = serde_json::from_str(&j).unwrap();
777 assert_eq!(back, pr);
778 }
779
780 // ── ProbeRegime::classify ─────────────────────────────────────────────────
781
782 #[test]
783 fn classify_zero_is_confident_fail() {
784 assert_eq!(ProbeRegime::classify(0, 5), ProbeRegime::ConfidentFail);
785 }
786
787 #[test]
788 fn classify_all_pass_is_confident_pass() {
789 assert_eq!(ProbeRegime::classify(5, 5), ProbeRegime::ConfidentPass);
790 }
791
792 #[test]
793 fn classify_above_k_is_confident_pass() {
794 // pass_count > k is technically impossible but the rule handles it gracefully.
795 assert_eq!(ProbeRegime::classify(6, 5), ProbeRegime::ConfidentPass);
796 }
797
798 #[test]
799 fn classify_mixed_is_ambiguous() {
800 assert_eq!(ProbeRegime::classify(1, 5), ProbeRegime::Ambiguous);
801 assert_eq!(ProbeRegime::classify(2, 5), ProbeRegime::Ambiguous);
802 assert_eq!(ProbeRegime::classify(4, 5), ProbeRegime::Ambiguous);
803 }
804
805 #[test]
806 fn classify_k_equals_2_boundaries() {
807 assert_eq!(ProbeRegime::classify(0, 2), ProbeRegime::ConfidentFail);
808 assert_eq!(ProbeRegime::classify(1, 2), ProbeRegime::Ambiguous);
809 assert_eq!(ProbeRegime::classify(2, 2), ProbeRegime::ConfidentPass);
810 }
811
812 // ── ProbeSignal serde backward-compat ────────────────────────────────────
813
814 /// `probe = None` must be absent from the JSON — byte-identical to pre-probe traces.
815 #[test]
816 fn probe_none_absent_from_json() {
817 let t = sample_trace(GENESIS_HASH, 1);
818 assert!(t.probe.is_none());
819 let j = serde_json::to_string(&t).unwrap();
820 assert!(
821 !j.contains("\"probe\""),
822 "probe=None must be omitted (skip_serializing_if): {j}"
823 );
824 }
825
826 /// Old JSON without a `probe` field deserializes cleanly (probe defaults to None).
827 #[test]
828 fn old_trace_without_probe_deserializes_to_none() {
829 // Use the canonical JSON of a probe-None trace as a stand-in for old traces.
830 let t = sample_trace(GENESIS_HASH, 1);
831 let j = serde_json::to_string(&t).unwrap();
832 assert!(!j.contains("probe"));
833 let back: Trace = serde_json::from_str(&j).unwrap();
834 assert_eq!(back.probe, None);
835 }
836
837 /// `probe = Some(...)` round-trips correctly.
838 #[test]
839 fn probe_signal_some_roundtrips() {
840 let mut t = sample_trace(GENESIS_HASH, 1);
841 t.probe = Some(ProbeSignal {
842 k: 5,
843 gate_pass_count: 5,
844 regime: ProbeRegime::ConfidentPass,
845 probe_cost_usd: 0.0003,
846 });
847 let j = serde_json::to_string(&t).unwrap();
848 assert!(j.contains("\"probe\""), "probe=Some must be present: {j}");
849 assert!(j.contains("\"regime\":\"confident_pass\""));
850 assert!(j.contains("\"gate_pass_count\":5"));
851 let back: Trace = serde_json::from_str(&j).unwrap();
852 assert_eq!(back.probe, t.probe);
853 }
854
855 /// Hash chain still verifies when `probe` is present — field participates in the hash.
856 #[test]
857 fn verify_chain_passes_with_probe_field_present() {
858 let mut t0 = sample_trace(GENESIS_HASH, 10);
859 t0.probe = Some(ProbeSignal {
860 k: 3,
861 gate_pass_count: 0,
862 regime: ProbeRegime::ConfidentFail,
863 probe_cost_usd: 0.0001,
864 });
865 let t1 = sample_trace(&t0.hash().unwrap(), 11);
866 let chain = [t0, t1];
867 assert!(
868 verify_chain(&chain, GENESIS_HASH).is_ok(),
869 "chain must verify when probe is present"
870 );
871 }
872
873 /// Tampering the probe field is detectable via the hash chain.
874 #[test]
875 fn tampering_probe_field_is_detectable() {
876 let mut t0 = sample_trace(GENESIS_HASH, 20);
877 t0.probe = Some(ProbeSignal {
878 k: 5,
879 gate_pass_count: 5,
880 regime: ProbeRegime::ConfidentPass,
881 probe_cost_usd: 0.0005,
882 });
883 let t1 = sample_trace(&t0.hash().unwrap(), 21);
884 let mut chain = [t0, t1];
885 // Tamper the probe field.
886 chain[0].probe.as_mut().unwrap().gate_pass_count = 0;
887 assert!(
888 verify_chain(&chain, GENESIS_HASH).is_err(),
889 "tampered probe must break the chain"
890 );
891 }
892
893 // ── decision_prior serde backward-compat (verified predictive routing) ──────
894
895 /// `decision_prior = None` (the default, prior off) must be absent from the JSON — a trace
896 /// serializes byte-identically to before this field existed, so the hash chain is unchanged.
897 #[test]
898 fn decision_prior_none_serializes_byte_identically_to_before() {
899 let t = sample_trace(GENESIS_HASH, 1);
900 assert!(t.decision_prior.is_none());
901 let j = serde_json::to_string(&t).unwrap();
902 assert!(
903 !j.contains("decision_prior"),
904 "decision_prior=None must be omitted (skip_serializing_if): {j}"
905 );
906 // Chained with a successor, exactly as any pre-prior trace would be.
907 let t1 = sample_trace(&t.hash().unwrap(), 2);
908 assert!(verify_chain(&[t, t1], GENESIS_HASH).is_ok());
909 }
910
911 /// Old JSON without a `decision_prior` field deserializes cleanly (defaults to `None`).
912 #[test]
913 fn old_trace_without_decision_prior_deserializes_to_none() {
914 let t = sample_trace(GENESIS_HASH, 1);
915 let j = serde_json::to_string(&t).unwrap();
916 let back: Trace = serde_json::from_str(&j).unwrap();
917 assert_eq!(back.decision_prior, None);
918 }
919
920 /// `decision_prior = Some(...)` round-trips and participates in the hash chain.
921 #[test]
922 fn decision_prior_some_roundtrips_and_hashes() {
923 let mut t0 = sample_trace(GENESIS_HASH, 30);
924 t0.decision_prior = Some(vec![0.2, 0.6, 1.0]);
925 let j = serde_json::to_string(&t0).unwrap();
926 assert!(j.contains("\"decision_prior\":[0.2,0.6,1.0]"), "{j}");
927 let back: Trace = serde_json::from_str(&j).unwrap();
928 assert_eq!(back.decision_prior, t0.decision_prior);
929
930 let t1 = sample_trace(&t0.hash().unwrap(), 31);
931 let mut chain = [t0, t1];
932 assert!(verify_chain(&chain, GENESIS_HASH).is_ok());
933 // Tampering the field is detectable via the hash chain.
934 chain[0].decision_prior = Some(vec![0.9, 0.95, 1.0]);
935 assert!(verify_chain(&chain, GENESIS_HASH).is_err());
936 }
937
938 // ── risk certificate in the receipt ─────────────────────────────────────────
939
940 /// No threshold in force ⇒ no `risk` key: pre-certificate traces hash exactly as before.
941 #[test]
942 fn risk_none_serializes_byte_identically_to_before() {
943 let t = sample_trace(GENESIS_HASH, 1);
944 let j = serde_json::to_string(&t).unwrap();
945 assert!(!j.contains("\"risk\""), "risk=None must be omitted: {j}");
946 let back: Trace = serde_json::from_str(&j).unwrap();
947 assert_eq!(back.risk, None);
948 }
949
950 /// The certificate round-trips with its wire names, and editing it after the fact — e.g.
951 /// claiming a tighter α than the answer was served under — breaks the chain.
952 #[test]
953 fn risk_certificate_roundtrips_and_tamper_breaks_chain() {
954 let mut t0 = sample_trace(GENESIS_HASH, 40);
955 t0.risk = Some(RiskCertificate {
956 source: ThresholdSource::Eprocess,
957 threshold: 0.7,
958 alpha: Some(0.1),
959 delta: Some(0.05),
960 e_value: Some(25.0),
961 certified_at_round: Some(312),
962 });
963 let j = serde_json::to_string(&t0).unwrap();
964 assert!(j.contains("\"source\":\"eprocess\""), "{j}");
965 let back: Trace = serde_json::from_str(&j).unwrap();
966 assert_eq!(back.risk, t0.risk);
967
968 let t1 = sample_trace(&t0.hash().unwrap(), 41);
969 let mut chain = [t0, t1];
970 assert!(verify_chain(&chain, GENESIS_HASH).is_ok());
971 chain[0].risk.as_mut().unwrap().alpha = Some(0.01);
972 assert!(
973 verify_chain(&chain, GENESIS_HASH).is_err(),
974 "an edited certificate must break the chain"
975 );
976 }
977}