Skip to main content

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}