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}
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}