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 /// The upstream provider that was contacted when the request ended in an error and there
244 /// are no attempts to read the provider from. Absent (empty) on successful traces — the
245 /// provider is then authoritative on the attempt. `skip_serializing_if` keeps old hashes
246 /// intact: an absent field serializes as absent, not as `""`.
247 #[serde(default, skip_serializing_if = "String::is_empty")]
248 pub upstream_provider: String,
249}
250
251/// Which controller supplied the serve threshold. Precedence is e-process > ACI > fixed
252/// (ADR 0011): only the e-process's bound holds at the round it is read.
253#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
254#[serde(rename_all = "snake_case")]
255pub enum ThresholdSource {
256 /// Anytime-valid e-process: served-failure ≤ α at every round, with probability ≥ 1−δ.
257 Eprocess,
258 /// Adaptive conformal: long-run average served-failure → α. No per-round guarantee.
259 Aci,
260 /// A configured constant. No guarantee is claimed.
261 Fixed,
262}
263
264/// The guarantee a served answer was decided under (see [`Trace::risk`]).
265#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
266pub struct RiskCertificate {
267 /// Which controller supplied the threshold.
268 pub source: ThresholdSource,
269 /// The serve threshold in force: a gate score at or above it was servable.
270 pub threshold: f64,
271 /// Target served-failure rate (e-process, ACI).
272 #[serde(default, skip_serializing_if = "Option::is_none")]
273 pub alpha: Option<f64>,
274 /// Family-wise error budget (e-process only).
275 #[serde(default, skip_serializing_if = "Option::is_none")]
276 pub delta: Option<f64>,
277 /// E-value backing the threshold; `>= 1/delta` whenever certified (e-process only).
278 #[serde(default, skip_serializing_if = "Option::is_none")]
279 pub e_value: Option<f64>,
280 /// Round at which the threshold was first certified (e-process only).
281 #[serde(default, skip_serializing_if = "Option::is_none")]
282 pub certified_at_round: Option<u64>,
283}
284
285/// Reference to the policy that produced a decision.
286#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
287pub struct PolicyRef {
288 /// Policy identity/version, e.g. `"static@v0"` or `"bandit@v3"`.
289 pub id: String,
290 /// Whether this decision was a deliberate exploration draw (bounded, §, only in enforce).
291 #[serde(default)]
292 pub explore: bool,
293 /// The probability the logging policy assigned to the start rung it chose — the
294 /// Horvitz-Thompson denominator for IPS / SNIPS off-policy evaluation.
295 ///
296 /// `None` for deterministic (non-exploring) policies. `skip_serializing_if` keeps old
297 /// trace bytes byte-identical when `None`, preserving hash-chain compatibility with
298 /// existing logs. Only populated when `[escalation.exploration]` is configured.
299 #[serde(default, skip_serializing_if = "Option::is_none")]
300 pub propensity: Option<f64>,
301 /// Resolved routing-mode profile when it was explicitly set (header / route / global env).
302 /// `None` means `Balanced` was in effect (the default, no override active). Absent from
303 /// the JSON when `None` → byte-identical serialization for all existing traces.
304 #[serde(default, skip_serializing_if = "Option::is_none")]
305 pub mode_profile: Option<String>,
306}
307
308/// The routed request, described without its raw content.
309#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
310pub struct RequestInfo {
311 /// Wire API the caller used, e.g. `"anthropic.messages"` / `"openai.chat"`.
312 pub api: String,
313 /// Salted hash of the prompt — never the prompt text itself.
314 pub prompt_hash: String,
315 /// The versioned feature vector routing keyed on.
316 pub features: Features,
317}
318
319/// One attempt at a rung: the model call plus the gates run against its output.
320#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
321pub struct Attempt {
322 /// Ladder rung (0 = cheapest).
323 pub rung: u32,
324 /// Model called, `provider/model`.
325 pub model: String,
326 /// Provider segment (denormalized for cheap querying).
327 pub provider: String,
328 /// Input tokens consumed, **uncached only**.
329 ///
330 /// When the caller uses prompt caching this is the small remainder; the bulk of the prompt is
331 /// reported separately below and billed at different rates. Read `billable_input()` rather
332 /// than this field for anything cost-shaped.
333 pub in_tokens: u64,
334 /// Prompt tokens written to the provider's cache on this call, billed at a **premium**
335 /// (Anthropic: 1.25× base input).
336 ///
337 /// Defaults to 0, so a receipt written before this field existed still deserializes and still
338 /// re-derives the same hash — the field is skipped when zero.
339 #[serde(default, skip_serializing_if = "is_zero")]
340 pub cache_write_tokens: u64,
341 /// Prompt tokens served from the provider's cache, billed at a **discount** (Anthropic: 0.1×
342 /// base input). Same zero-default reasoning as `cache_write_tokens`.
343 #[serde(default, skip_serializing_if = "is_zero")]
344 pub cache_read_tokens: u64,
345 /// Output tokens produced.
346 pub out_tokens: u64,
347 /// USD cost of this model call (excludes gate cost).
348 pub cost_usd: f64,
349 /// Wall-clock latency of the model call.
350 pub latency_ms: u64,
351 /// Gate verdicts for this attempt's output.
352 pub gates: Vec<GateResult>,
353 /// The attempt's overall verdict (the aggregate that drove escalate-or-serve).
354 pub verdict: Verdict,
355 /// The model stopped at the request's output-token limit, so the answer is cut off and a gate
356 /// failure on it may describe the cap rather than the model. Skipped when false, so a receipt
357 /// written before this field existed still re-derives the same hash.
358 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
359 pub truncated: bool,
360}
361
362/// `skip_serializing_if` helper: keeps zero-valued cache fields out of the canonical JSON, so a
363/// receipt written before those fields existed hashes identically to one written after.
364#[allow(clippy::trivially_copy_pass_by_ref)] // serde requires the &-taking shape
365fn is_zero(n: &u64) -> bool {
366 *n == 0
367}
368
369impl Trace {
370 /// Milliseconds this proxy added on top of the work it actually dispatched — provider calls
371 /// plus gates. The number a gateway is judged on, and the one Firstpass could not previously
372 /// state about itself.
373 ///
374 /// Returns `None` rather than a wrong figure when it cannot be computed honestly. Under
375 /// speculation, rungs run concurrently, so the summed work legitimately exceeds wall-clock and
376 /// the subtraction is meaningless; a receipt like that is excluded from an overhead
377 /// distribution instead of being floored to zero, which would silently drag a p95 down.
378 ///
379 /// Deliberately derived rather than stored: a recorded overhead field could disagree with the
380 /// timings beside it, and this way an auditor recomputes it from the same numbers we do.
381 #[must_use]
382 pub fn overhead_ms(&self) -> Option<u64> {
383 let dispatched: u64 = self
384 .attempts
385 .iter()
386 .map(|a| {
387 a.latency_ms
388 .saturating_add(a.gates.iter().map(|g| g.ms).sum::<u64>())
389 })
390 .sum();
391 self.final_.total_latency_ms.checked_sub(dispatched)
392 }
393}
394
395impl Attempt {
396 /// Total prompt tokens this call actually consumed, cached or not.
397 ///
398 /// `in_tokens` alone is **not** the prompt size when the caller uses prompt caching: providers
399 /// report the cached portion in separate fields, and a 190k-token cached prefix shows up as an
400 /// `in_tokens` of about 20. Anything reporting prompt volume wants this, not the raw field.
401 #[must_use]
402 pub const fn billable_input(&self) -> u64 {
403 self.in_tokens
404 .saturating_add(self.cache_write_tokens)
405 .saturating_add(self.cache_read_tokens)
406 }
407}
408
409/// A verdict that arrived after the response was served (deferred gate or downstream feedback).
410#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
411pub struct DeferredVerdict {
412 /// Gate/source identity, e.g. `"tests"` or `"feedback:ci"`.
413 pub gate_id: String,
414 /// The late verdict.
415 pub verdict: Verdict,
416 /// Optional score.
417 #[serde(default, skip_serializing_if = "Option::is_none")]
418 pub score: Option<Score>,
419 /// When it arrived.
420 pub reported_at: Timestamp,
421 /// Who reported it (a deferred gate, or a feedback-API caller identity).
422 pub reporter: String,
423}
424
425/// Where the served response came from.
426#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
427#[serde(rename_all = "snake_case")]
428pub enum ServedFrom {
429 /// A passing attempt (the normal path).
430 Attempt,
431 /// The best attempt seen, served because budget/ladder was exhausted without a pass.
432 BestAttempt,
433 /// No output served; a structured error was returned.
434 Error,
435 /// Replayed from the verified cache: this exact prompt was answered before, that answer
436 /// **passed its gate**, and the receipt names the decision that proved it.
437 ///
438 /// Distinct from [`ServedFrom::Attempt`] because no model was called — a receipt that reported
439 /// this as a normal attempt would claim a verification that did not run today, and inflate
440 /// every pass-rate computed over receipts. `cache_source` carries the trace it came from, so
441 /// the proof is one lookup away rather than asserted.
442 Cache,
443}
444
445/// The final outcome and economics of a decision.
446#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
447pub struct FinalOutcome {
448 /// Rung whose output was served (`None` if `served_from = error`).
449 #[serde(default, skip_serializing_if = "Option::is_none")]
450 pub served_rung: Option<u32>,
451 /// Provenance of the served response.
452 pub served_from: ServedFrom,
453 /// Total USD spent (all model calls + all gates).
454 pub total_cost_usd: f64,
455 /// USD portion spent on gates alone.
456 pub gate_cost_usd: f64,
457 /// Total wall-clock latency the caller experienced.
458 pub total_latency_ms: u64,
459 /// Number of rung escalations taken.
460 pub escalations: u32,
461 /// What always calling the top rung would have cost (§9.1 counterfactual).
462 pub counterfactual_baseline_usd: f64,
463 /// The decision this answer was replayed from, when `served_from = cache`.
464 ///
465 /// The whole point of a verified cache: the receipt does not merely say "cached", it names the
466 /// earlier decision whose gate passed, so an auditor can follow the link and check that the
467 /// thing being replayed was actually proven. Absent otherwise, so pre-cache receipts serialize
468 /// byte-identically and re-derive the same hash.
469 #[serde(default, skip_serializing_if = "Option::is_none")]
470 pub cache_source: Option<Uuid>,
471 /// `counterfactual_baseline_usd - total_cost_usd` — the savings this decision proves.
472 pub savings_usd: f64,
473}
474
475impl Chained for Trace {
476 fn prev_hash(&self) -> &str {
477 &self.prev_hash
478 }
479}
480
481impl Trace {
482 /// This record's own hash (SHA-256 over its canonical JSON) — the value the *next*
483 /// record stores as its `prev_hash`.
484 ///
485 /// # Errors
486 /// Returns [`crate::Error::Json`] if the trace cannot be serialized.
487 pub fn hash(&self) -> Result<String> {
488 record_hash(self)
489 }
490
491 /// Compute `savings_usd = baseline - total` and store it, keeping the field consistent
492 /// with the two it is derived from. Returns the savings.
493 pub fn recompute_savings(&mut self) -> f64 {
494 let s = self.final_.counterfactual_baseline_usd - self.final_.total_cost_usd;
495 self.final_.savings_usd = s;
496 s
497 }
498}
499
500impl std::fmt::Display for Trace {
501 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
502 write!(
503 f,
504 "trace {} rung {:?} served_from {:?} cost ${:.4} saved ${:.4}",
505 self.trace_id,
506 self.final_.served_rung,
507 self.final_.served_from,
508 self.final_.total_cost_usd,
509 self.final_.savings_usd,
510 )
511 }
512}
513
514#[cfg(test)]
515mod tests {
516 use super::*;
517 use crate::features::{Features, TaskKind};
518 use crate::hashchain::{GENESIS_HASH, verify_chain};
519 use crate::verdict::Verdict;
520
521 fn sample_trace(prev_hash: &str, id: u128) -> Trace {
522 let mut t = Trace {
523 trace_id: Uuid::from_u128(id),
524 prev_hash: prev_hash.to_owned(),
525 tenant_id: "acme".into(),
526 session_id: "agent-run-4417".into(),
527 ts: "2026-07-08T15:04:05Z".parse().unwrap(),
528 mode: Mode::Enforce,
529 policy: PolicyRef {
530 id: "static@v0".into(),
531 explore: false,
532 propensity: None,
533 mode_profile: None,
534 },
535 request: RequestInfo {
536 api: "anthropic.messages".into(),
537 prompt_hash: "deadbeef".into(),
538 features: Features::new(TaskKind::CodeEdit),
539 },
540 attempts: vec![
541 Attempt {
542 rung: 0,
543 model: "anthropic/claude-haiku-4-5".into(),
544 provider: "anthropic".into(),
545 in_tokens: 2000,
546 cache_write_tokens: 0,
547 cache_read_tokens: 0,
548 out_tokens: 700,
549 cost_usd: 0.0007,
550 latency_ms: 900,
551 gates: vec![GateResult::deterministic("cargo-test", Verdict::Fail, 3100)],
552 verdict: Verdict::Fail,
553 truncated: false,
554 },
555 Attempt {
556 rung: 1,
557 model: "anthropic/claude-sonnet-5".into(),
558 provider: "anthropic".into(),
559 in_tokens: 2000,
560 cache_write_tokens: 0,
561 cache_read_tokens: 0,
562 out_tokens: 800,
563 cost_usd: 0.0121,
564 latency_ms: 1200,
565 gates: vec![GateResult::deterministic("cargo-test", Verdict::Pass, 2950)],
566 verdict: Verdict::Pass,
567 truncated: false,
568 },
569 ],
570 deferred: vec![],
571 final_: FinalOutcome {
572 served_rung: Some(1),
573 served_from: ServedFrom::Attempt,
574 total_cost_usd: 0.0128,
575 gate_cost_usd: 0.0,
576 total_latency_ms: 2100,
577 escalations: 1,
578 counterfactual_baseline_usd: 0.0630,
579 savings_usd: 0.0,
580 cache_source: None,
581 },
582 probe: None,
583 rollout: None,
584 shadow: None,
585 route_ix: None,
586 predicted_pass: None,
587 decision_prior: None,
588 elastic: None,
589 risk: None,
590 experiment: None,
591 upstream_provider: String::new(),
592 };
593 t.recompute_savings();
594 t
595 }
596
597 #[test]
598 fn wire_field_names_are_the_contract() {
599 let t = sample_trace(GENESIS_HASH, 1);
600 let j = serde_json::to_string(&t).unwrap();
601 assert!(j.contains("\"prev_hash\":"));
602 assert!(
603 j.contains("\"final\":"),
604 "the outcome key must serialize as `final`"
605 );
606 assert!(j.contains("\"served_from\":\"attempt\""));
607 assert!(j.contains("\"verdict\":\"fail\""));
608 assert!(j.contains("\"verdict\":\"pass\""));
609 assert!(j.contains("\"counterfactual_baseline_usd\":"));
610 }
611
612 #[test]
613 fn savings_is_baseline_minus_total() {
614 let t = sample_trace(GENESIS_HASH, 1);
615 assert!((t.final_.savings_usd - (0.0630 - 0.0128)).abs() < 1e-12);
616 }
617
618 #[test]
619 fn traces_chain_and_verify() {
620 let t0 = sample_trace(GENESIS_HASH, 1);
621 let t1 = sample_trace(&t0.hash().unwrap(), 2);
622 let chain = [t0, t1];
623 assert!(verify_chain(&chain, GENESIS_HASH).is_ok());
624 }
625
626 #[test]
627 fn tampering_a_served_trace_is_detectable() {
628 let t0 = sample_trace(GENESIS_HASH, 1);
629 let t1 = sample_trace(&t0.hash().unwrap(), 2);
630 let mut chain = [t0, t1];
631 chain[0].final_.total_cost_usd = 0.0; // forge a cheaper decision after the fact
632 assert!(verify_chain(&chain, GENESIS_HASH).is_err());
633 }
634
635 #[test]
636 fn roundtrips_through_json() {
637 let t = sample_trace(GENESIS_HASH, 7);
638 let j = serde_json::to_string(&t).unwrap();
639 let back: Trace = serde_json::from_str(&j).unwrap();
640 assert_eq!(t, back);
641 }
642
643 /// A trace with no upstream provider recorded serializes without the key and hashes exactly as
644 /// a receipt written before the field existed; one that carries it hashes differently.
645 #[test]
646 fn upstream_provider_empty_is_absent_and_hash_neutral() {
647 let t = sample_trace(GENESIS_HASH, 1);
648 let j = serde_json::to_string(&t).unwrap();
649 assert!(
650 !j.contains("upstream_provider"),
651 "empty must be omitted: {j}"
652 );
653 let back: Trace = serde_json::from_str(&j).unwrap();
654 assert_eq!(back.hash().unwrap(), t.hash().unwrap());
655 let mut with = t.clone();
656 with.upstream_provider = "openai".to_owned();
657 assert_ne!(with.hash().unwrap(), t.hash().unwrap());
658 let rt: Trace = serde_json::from_str(&serde_json::to_string(&with).unwrap()).unwrap();
659 assert_eq!(rt.upstream_provider, "openai");
660 assert_eq!(rt.hash().unwrap(), with.hash().unwrap());
661 }
662
663 /// An attempt that was not cut off serializes without `truncated` and hashes exactly as a
664 /// receipt written before the field existed; a cut-off one carries it inside the chain.
665 #[test]
666 fn truncated_false_is_absent_and_hash_neutral() {
667 let t = sample_trace(GENESIS_HASH, 1);
668 let j = serde_json::to_string(&t).unwrap();
669 assert!(!j.contains("truncated"), "false must be omitted: {j}");
670 let back: Trace = serde_json::from_str(&j).unwrap();
671 assert!(!back.attempts[0].truncated);
672 assert_eq!(back.hash().unwrap(), t.hash().unwrap());
673
674 let mut cut = t.clone();
675 cut.attempts[0].truncated = true;
676 assert_ne!(cut.hash().unwrap(), t.hash().unwrap());
677 let jc = serde_json::to_string(&cut).unwrap();
678 assert!(jc.contains("\"truncated\":true"), "{jc}");
679 let rt: Trace = serde_json::from_str(&jc).unwrap();
680 assert_eq!(rt.hash().unwrap(), cut.hash().unwrap());
681 }
682
683 // ── experiment backward-compat ───────────────────────────────────────────
684
685 /// A trace without an experiment record must serialize without the key and hash exactly as it
686 /// did before the field existed; a trace with one must differ (it is inside the chain).
687 #[test]
688 fn experiment_none_is_absent_and_hash_neutral() {
689 let t = sample_trace(GENESIS_HASH, 1);
690 let j = serde_json::to_string(&t).unwrap();
691 assert!(!j.contains("experiment"), "None must be omitted: {j}");
692 // Re-derive the hash from the pre-field wire form: same JSON, so same hash.
693 let mut v: serde_json::Value = serde_json::from_str(&j).unwrap();
694 assert!(v.as_object_mut().unwrap().remove("experiment").is_none());
695 let back: Trace = serde_json::from_value(v).unwrap();
696 assert_eq!(back.hash().unwrap(), t.hash().unwrap());
697
698 let mut with = t.clone();
699 with.experiment = Some(ExperimentRecord {
700 arm: Arm::Challenger,
701 percent: 10.0,
702 bucket: 42,
703 fingerprint: "0123456789abcdef".to_owned(),
704 });
705 assert_ne!(with.hash().unwrap(), t.hash().unwrap());
706 let jw = serde_json::to_string(&with).unwrap();
707 assert!(jw.contains("\"arm\":\"challenger\""), "{jw}");
708 // The record's field names are the audit contract: a rename is a schema change.
709 for key in ["\"percent\":", "\"bucket\":", "\"fingerprint\":"] {
710 assert!(jw.contains(key), "missing {key} in {jw}");
711 }
712 let rt: Trace = serde_json::from_str(&jw).unwrap();
713 assert_eq!(rt, with);
714 }
715
716 // ── propensity backward-compat ────────────────────────────────────────────
717
718 /// Traces where propensity is None must serialize byte-identically to pre-field traces:
719 /// the field must be absent from the JSON, not serialized as `null`.
720 #[test]
721 fn propensity_none_absent_from_json() {
722 let pr = PolicyRef {
723 id: "static@v0".into(),
724 explore: false,
725 propensity: None,
726 mode_profile: None,
727 };
728 let j = serde_json::to_string(&pr).unwrap();
729 assert!(
730 !j.contains("propensity"),
731 "propensity=None must be omitted (skip_serializing_if): {j}"
732 );
733 }
734
735 /// Old JSON without a `propensity` field must deserialize to `propensity: None`
736 /// (via `#[serde(default)]`), keeping old traces readable without schema migration.
737 #[test]
738 fn old_trace_without_propensity_deserializes_to_none() {
739 let old_json = r#"{"id":"static@v0","explore":false}"#;
740 let pr: PolicyRef = serde_json::from_str(old_json).unwrap();
741 assert_eq!(pr.propensity, None);
742 }
743
744 /// New JSON with a propensity value round-trips correctly.
745 #[test]
746 fn propensity_some_roundtrips() {
747 let pr = PolicyRef {
748 id: "bandit@v1+eps".into(),
749 explore: true,
750 propensity: Some(0.3),
751 mode_profile: None,
752 };
753 let j = serde_json::to_string(&pr).unwrap();
754 assert!(
755 j.contains("\"propensity\":0.3"),
756 "expected propensity in: {j}"
757 );
758 let back: PolicyRef = serde_json::from_str(&j).unwrap();
759 assert_eq!(back, pr);
760 }
761
762 // ── mode_profile backward-compat ─────────────────────────────────────────
763
764 /// `mode_profile = None` must not appear in the serialized JSON — byte-identical for
765 /// existing traces (Balanced is the default and must be invisible).
766 #[test]
767 fn mode_profile_none_absent_from_json() {
768 let pr = PolicyRef {
769 id: "static@v0".into(),
770 explore: false,
771 propensity: None,
772 mode_profile: None,
773 };
774 let j = serde_json::to_string(&pr).unwrap();
775 assert!(
776 !j.contains("mode_profile"),
777 "mode_profile=None must be omitted (skip_serializing_if): {j}"
778 );
779 }
780
781 /// Old JSON without a `mode_profile` field deserializes to `mode_profile: None`.
782 #[test]
783 fn old_trace_without_mode_profile_deserializes_to_none() {
784 let old_json = r#"{"id":"static@v0","explore":false}"#;
785 let pr: PolicyRef = serde_json::from_str(old_json).unwrap();
786 assert_eq!(pr.mode_profile, None);
787 }
788
789 /// `mode_profile = Some(...)` round-trips correctly.
790 #[test]
791 fn mode_profile_some_roundtrips() {
792 let pr = PolicyRef {
793 id: "static@v0".into(),
794 explore: false,
795 propensity: None,
796 mode_profile: Some("quality".into()),
797 };
798 let j = serde_json::to_string(&pr).unwrap();
799 assert!(
800 j.contains("\"mode_profile\":\"quality\""),
801 "expected mode_profile in: {j}"
802 );
803 let back: PolicyRef = serde_json::from_str(&j).unwrap();
804 assert_eq!(back, pr);
805 }
806
807 // ── ProbeRegime::classify ─────────────────────────────────────────────────
808
809 #[test]
810 fn classify_zero_is_confident_fail() {
811 assert_eq!(ProbeRegime::classify(0, 5), ProbeRegime::ConfidentFail);
812 }
813
814 #[test]
815 fn classify_all_pass_is_confident_pass() {
816 assert_eq!(ProbeRegime::classify(5, 5), ProbeRegime::ConfidentPass);
817 }
818
819 #[test]
820 fn classify_above_k_is_confident_pass() {
821 // pass_count > k is technically impossible but the rule handles it gracefully.
822 assert_eq!(ProbeRegime::classify(6, 5), ProbeRegime::ConfidentPass);
823 }
824
825 #[test]
826 fn classify_mixed_is_ambiguous() {
827 assert_eq!(ProbeRegime::classify(1, 5), ProbeRegime::Ambiguous);
828 assert_eq!(ProbeRegime::classify(2, 5), ProbeRegime::Ambiguous);
829 assert_eq!(ProbeRegime::classify(4, 5), ProbeRegime::Ambiguous);
830 }
831
832 #[test]
833 fn classify_k_equals_2_boundaries() {
834 assert_eq!(ProbeRegime::classify(0, 2), ProbeRegime::ConfidentFail);
835 assert_eq!(ProbeRegime::classify(1, 2), ProbeRegime::Ambiguous);
836 assert_eq!(ProbeRegime::classify(2, 2), ProbeRegime::ConfidentPass);
837 }
838
839 // ── ProbeSignal serde backward-compat ────────────────────────────────────
840
841 /// `probe = None` must be absent from the JSON — byte-identical to pre-probe traces.
842 #[test]
843 fn probe_none_absent_from_json() {
844 let t = sample_trace(GENESIS_HASH, 1);
845 assert!(t.probe.is_none());
846 let j = serde_json::to_string(&t).unwrap();
847 assert!(
848 !j.contains("\"probe\""),
849 "probe=None must be omitted (skip_serializing_if): {j}"
850 );
851 }
852
853 /// Old JSON without a `probe` field deserializes cleanly (probe defaults to None).
854 #[test]
855 fn old_trace_without_probe_deserializes_to_none() {
856 // Use the canonical JSON of a probe-None trace as a stand-in for old traces.
857 let t = sample_trace(GENESIS_HASH, 1);
858 let j = serde_json::to_string(&t).unwrap();
859 assert!(!j.contains("probe"));
860 let back: Trace = serde_json::from_str(&j).unwrap();
861 assert_eq!(back.probe, None);
862 }
863
864 /// `probe = Some(...)` round-trips correctly.
865 #[test]
866 fn probe_signal_some_roundtrips() {
867 let mut t = sample_trace(GENESIS_HASH, 1);
868 t.probe = Some(ProbeSignal {
869 k: 5,
870 gate_pass_count: 5,
871 regime: ProbeRegime::ConfidentPass,
872 probe_cost_usd: 0.0003,
873 });
874 let j = serde_json::to_string(&t).unwrap();
875 assert!(j.contains("\"probe\""), "probe=Some must be present: {j}");
876 assert!(j.contains("\"regime\":\"confident_pass\""));
877 assert!(j.contains("\"gate_pass_count\":5"));
878 let back: Trace = serde_json::from_str(&j).unwrap();
879 assert_eq!(back.probe, t.probe);
880 }
881
882 /// Hash chain still verifies when `probe` is present — field participates in the hash.
883 #[test]
884 fn verify_chain_passes_with_probe_field_present() {
885 let mut t0 = sample_trace(GENESIS_HASH, 10);
886 t0.probe = Some(ProbeSignal {
887 k: 3,
888 gate_pass_count: 0,
889 regime: ProbeRegime::ConfidentFail,
890 probe_cost_usd: 0.0001,
891 });
892 let t1 = sample_trace(&t0.hash().unwrap(), 11);
893 let chain = [t0, t1];
894 assert!(
895 verify_chain(&chain, GENESIS_HASH).is_ok(),
896 "chain must verify when probe is present"
897 );
898 }
899
900 /// Tampering the probe field is detectable via the hash chain.
901 #[test]
902 fn tampering_probe_field_is_detectable() {
903 let mut t0 = sample_trace(GENESIS_HASH, 20);
904 t0.probe = Some(ProbeSignal {
905 k: 5,
906 gate_pass_count: 5,
907 regime: ProbeRegime::ConfidentPass,
908 probe_cost_usd: 0.0005,
909 });
910 let t1 = sample_trace(&t0.hash().unwrap(), 21);
911 let mut chain = [t0, t1];
912 // Tamper the probe field.
913 chain[0].probe.as_mut().unwrap().gate_pass_count = 0;
914 assert!(
915 verify_chain(&chain, GENESIS_HASH).is_err(),
916 "tampered probe must break the chain"
917 );
918 }
919
920 // ── decision_prior serde backward-compat (verified predictive routing) ──────
921
922 /// `decision_prior = None` (the default, prior off) must be absent from the JSON — a trace
923 /// serializes byte-identically to before this field existed, so the hash chain is unchanged.
924 #[test]
925 fn decision_prior_none_serializes_byte_identically_to_before() {
926 let t = sample_trace(GENESIS_HASH, 1);
927 assert!(t.decision_prior.is_none());
928 let j = serde_json::to_string(&t).unwrap();
929 assert!(
930 !j.contains("decision_prior"),
931 "decision_prior=None must be omitted (skip_serializing_if): {j}"
932 );
933 // Chained with a successor, exactly as any pre-prior trace would be.
934 let t1 = sample_trace(&t.hash().unwrap(), 2);
935 assert!(verify_chain(&[t, t1], GENESIS_HASH).is_ok());
936 }
937
938 /// Old JSON without a `decision_prior` field deserializes cleanly (defaults to `None`).
939 #[test]
940 fn old_trace_without_decision_prior_deserializes_to_none() {
941 let t = sample_trace(GENESIS_HASH, 1);
942 let j = serde_json::to_string(&t).unwrap();
943 let back: Trace = serde_json::from_str(&j).unwrap();
944 assert_eq!(back.decision_prior, None);
945 }
946
947 /// `decision_prior = Some(...)` round-trips and participates in the hash chain.
948 #[test]
949 fn decision_prior_some_roundtrips_and_hashes() {
950 let mut t0 = sample_trace(GENESIS_HASH, 30);
951 t0.decision_prior = Some(vec![0.2, 0.6, 1.0]);
952 let j = serde_json::to_string(&t0).unwrap();
953 assert!(j.contains("\"decision_prior\":[0.2,0.6,1.0]"), "{j}");
954 let back: Trace = serde_json::from_str(&j).unwrap();
955 assert_eq!(back.decision_prior, t0.decision_prior);
956
957 let t1 = sample_trace(&t0.hash().unwrap(), 31);
958 let mut chain = [t0, t1];
959 assert!(verify_chain(&chain, GENESIS_HASH).is_ok());
960 // Tampering the field is detectable via the hash chain.
961 chain[0].decision_prior = Some(vec![0.9, 0.95, 1.0]);
962 assert!(verify_chain(&chain, GENESIS_HASH).is_err());
963 }
964
965 // ── risk certificate in the receipt ─────────────────────────────────────────
966
967 /// No threshold in force ⇒ no `risk` key: pre-certificate traces hash exactly as before.
968 #[test]
969 fn risk_none_serializes_byte_identically_to_before() {
970 let t = sample_trace(GENESIS_HASH, 1);
971 let j = serde_json::to_string(&t).unwrap();
972 assert!(!j.contains("\"risk\""), "risk=None must be omitted: {j}");
973 let back: Trace = serde_json::from_str(&j).unwrap();
974 assert_eq!(back.risk, None);
975 }
976
977 /// The certificate round-trips with its wire names, and editing it after the fact — e.g.
978 /// claiming a tighter α than the answer was served under — breaks the chain.
979 #[test]
980 fn risk_certificate_roundtrips_and_tamper_breaks_chain() {
981 let mut t0 = sample_trace(GENESIS_HASH, 40);
982 t0.risk = Some(RiskCertificate {
983 source: ThresholdSource::Eprocess,
984 threshold: 0.7,
985 alpha: Some(0.1),
986 delta: Some(0.05),
987 e_value: Some(25.0),
988 certified_at_round: Some(312),
989 });
990 let j = serde_json::to_string(&t0).unwrap();
991 assert!(j.contains("\"source\":\"eprocess\""), "{j}");
992 let back: Trace = serde_json::from_str(&j).unwrap();
993 assert_eq!(back.risk, t0.risk);
994
995 let t1 = sample_trace(&t0.hash().unwrap(), 41);
996 let mut chain = [t0, t1];
997 assert!(verify_chain(&chain, GENESIS_HASH).is_ok());
998 chain[0].risk.as_mut().unwrap().alpha = Some(0.01);
999 assert!(
1000 verify_chain(&chain, GENESIS_HASH).is_err(),
1001 "an edited certificate must break the chain"
1002 );
1003 }
1004}