firstpass-proxy 0.8.1

Drop-in, Anthropic-compatible LLM proxy that routes each request to the cheapest model that provably passes a quality gate, escalates on failure, and records a tamper-evident audit trace.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
//! Recalibrate the serving threshold from real deferred feedback (SPEC §10.1, run against live
//! traffic instead of a static benchmark suite) — the "learns your quality bar" loop.
//!
//! Three calibration methods are available:
//! - **conformal** (default): split-conformal with Hoeffding bound — [`calibrate_from_store`].
//! - **ltt**: Learn-then-Test / RCPS with exact-binomial fixed-sequence testing —
//!   [`calibrate_from_store_ltt`].
//! - **eprocess**: anytime-valid risk control — [`calibrate_from_store_eprocess`].
//!
//! All three enumerate stored traces, pair each trace that has a deferred outcome with the score of
//! the attempt actually served, and hand the pairs to the respective core module. None feeds
//! back into the request hot path — that wiring is a deliberate follow-on once an operator has
//! reviewed a report.
//!
//! ## Which one to run, and why there are three
//!
//! The first two are **fixed-sample**: they answer "given this calibration set, what threshold is
//! safe?", and their guarantees are stated over that one set. That is the right question when an
//! operator recalibrates deliberately, reviews the report, and adopts a threshold.
//!
//! It is the wrong question when calibration runs continuously. Re-running a fixed-sample method
//! whenever more feedback lands, and adopting the winner each time, is optional stopping on a
//! growing stream — each individual run is valid while the sequence of adoptions is not. `eprocess`
//! exists for that regime: its bound holds at **every** round, so re-reading it as often as you like
//! costs nothing in validity. It pays for that in conservatism, and
//! [`firstpass_core::eprocess`] documents the trade rather than burying it.

use std::path::Path;

use firstpass_core::conformal::{self, ConformalResult};
use firstpass_core::eprocess;
use firstpass_core::ltt::{self, LttResult};
use firstpass_core::{Attempt, DeferredVerdict, GateResult, Score, Trace, Verdict};

use crate::store::{self, StoreError};

/// The result of calibrating a conformal threshold against real deferred feedback.
#[derive(Debug, Clone)]
pub struct CalibrationReport {
    /// Number of `(score, correct)` pairs calibration ran on — one per trace with at least one
    /// deferred verdict recorded.
    pub n_pairs: usize,
    /// The conformal calibration result (threshold, feasibility, calibration risk).
    pub conformal: ConformalResult,
    /// Empirical served-failure rate at `conformal.threshold`, measured on the same pairs used
    /// to calibrate (a sanity check, not a held-out estimate — the proxy doesn't yet split
    /// feedback into separate calibration/test batches).
    pub empirical_served_failure: f64,
    /// How many pairs would be served at the calibrated threshold.
    pub n_served: usize,
}

impl CalibrationReport {
    /// Render the report as human-readable lines for `firstpass calibrate`.
    #[must_use]
    pub fn render(&self) -> String {
        format!(
            "pairs: {n_pairs} ({n_served} served at threshold)\n\
             threshold: {threshold:.4}\n\
             feasible: {feasible}\n\
             target alpha: {alpha:.4} (delta {delta:.4})\n\
             calibration risk: {calib_risk:.4}\n\
             empirical served-failure: {empirical:.4}\n",
            n_pairs = self.n_pairs,
            n_served = self.n_served,
            threshold = self.conformal.threshold,
            feasible = self.conformal.feasible,
            alpha = self.conformal.alpha,
            delta = self.conformal.delta,
            calib_risk = self.conformal.calib_risk,
            empirical = self.empirical_served_failure,
        )
    }
}

/// Calibrate a conformal threshold from `(score, correct)` pairs — a thin wrapper over
/// [`firstpass_core::conformal`] that also reports the empirical served-failure at the chosen
/// threshold.
#[must_use]
pub fn calibrate_pairs(
    pairs: &[(f64, bool)],
    alpha: f64,
    delta: f64,
    min_n: usize,
) -> CalibrationReport {
    let result = conformal::calibrate(pairs, alpha, delta, min_n);
    let (empirical_served_failure, n_served) =
        conformal::served_failure_rate(pairs, result.threshold);
    CalibrationReport {
        n_pairs: pairs.len(),
        conformal: result,
        empirical_served_failure,
        n_served,
    }
}

/// The aggregate score for a set of gate results at a given verdict: the mean of the numeric gate
/// scores, or — when no gate reported a numeric score at all — `1.0` if it passed and `0.0` if it
/// didn't. A bare pass/fail with no score still needs to sit somewhere on the `[0, 1]` axis
/// conformal thresholds against; treating a scoreless pass as maximally confident and a scoreless
/// fail as minimally confident keeps "higher score = more servable" true either way.
///
/// Shared by [`attempt_score`] (calibration, offline) and the router's `serve_threshold` decision
/// (serving, online) so the two agree on what "the score" means.
pub(crate) fn gate_score(gates: &[GateResult], verdict: Verdict) -> f64 {
    let numeric: Vec<f64> = gates
        .iter()
        .filter_map(|g| g.score.map(Score::value))
        .collect();
    if numeric.is_empty() {
        f64::from(verdict == Verdict::Pass)
    } else {
        numeric.iter().sum::<f64>() / numeric.len() as f64
    }
}

/// The aggregate score for a served attempt (see [`gate_score`]).
fn attempt_score(attempt: &Attempt) -> f64 {
    gate_score(&attempt.gates, attempt.verdict)
}

/// Build a `(score, correct)` pair for one trace, if it has deferred feedback and a served
/// attempt. `correct` is whether the MOST RECENT deferred verdict for the trace is `Pass` (later
/// feedback supersedes earlier — e.g. a flaky CI run retried).
fn trace_pair(trace: &Trace, deferred: &[DeferredVerdict]) -> Option<(f64, bool)> {
    let last = deferred.last()?;
    let served_rung = trace.final_.served_rung?;
    let attempt = trace.attempts.iter().find(|a| a.rung == served_rung)?;
    Some((attempt_score(attempt), last.verdict == Verdict::Pass))
}

/// The result of LTT calibration against real deferred feedback.
#[derive(Debug, Clone)]
pub struct LttReport {
    /// Number of `(score, correct)` pairs — one per trace with a deferred verdict.
    pub n_pairs: usize,
    /// The LTT calibration result (threshold, feasibility, empirical risk, diagnostics).
    pub ltt: LttResult,
}

impl LttReport {
    /// Render the report as human-readable lines for `firstpass calibrate --method ltt`.
    /// Format mirrors [`CalibrationReport::render`] with an added verifier ROC note.
    #[must_use]
    pub fn render(&self) -> String {
        let far = match self.ltt.false_accept_rate {
            Some(r) => format!("{r:.4}"),
            None => "N/A (no incorrect items in calibration set)".to_owned(),
        };
        format!(
            "method: ltt\n\
             pairs: {n_pairs} ({n_served} served at threshold)\n\
             threshold: {threshold:.4}\n\
             feasible: {feasible}\n\
             target alpha: {alpha:.4} (delta {delta:.4})\n\
             empirical risk: {risk:.4}\n\
             false-accept rate: {far}  (P(score >= lambda | incorrect); verifier ROC point)\n",
            n_pairs = self.n_pairs,
            n_served = self.ltt.n_served,
            threshold = self.ltt.threshold,
            feasible = self.ltt.feasible,
            alpha = self.ltt.alpha,
            delta = self.ltt.delta,
            risk = self.ltt.empirical_risk,
        )
    }
}

/// Calibrate an LTT threshold from `(score, correct)` pairs — thin wrapper over
/// [`firstpass_core::ltt`].
#[must_use]
pub fn calibrate_pairs_ltt(
    pairs: &[(f64, bool)],
    alpha: f64,
    delta: f64,
    min_n: usize,
) -> LttReport {
    LttReport {
        n_pairs: pairs.len(),
        ltt: ltt::calibrate(pairs, alpha, delta, min_n),
    }
}

/// Report for `--method eprocess`: anytime-valid risk control.
///
/// Unlike [`CalibrationReport`] and [`LttReport`], which each summarise a **single** fixed-sample
/// decision, this replays the stored feedback as the *stream it actually was* and reports what the
/// controller would certify at the end of it. That difference is the point: the other two answer
/// "given this calibration set, what threshold is safe?", while this answers "having watched this
/// stream round by round, what is certified *now*?" — the question a continuously-recalibrating
/// deployment is really asking.
#[derive(Debug, Clone)]
pub struct EProcessReport {
    /// Pairs replayed.
    pub n_pairs: usize,
    /// Certified threshold and its evidence, or `None` if the stream never certified anything.
    pub certification: Option<firstpass_core::eprocess::Certification>,
    /// Target served-failure rate.
    pub alpha: f64,
    /// Family-wise error budget across the grid and all rounds.
    pub delta: f64,
    /// Evidence required per threshold (`n / delta`, the Bonferroni crossing level).
    pub crossing_level: f64,
    /// Realized served-failure over the replay, as a diagnostic — not the guarantee.
    pub realized_served_failure: f64,
}

impl EProcessReport {
    /// Render for `firstpass calibrate --method eprocess`. Mirrors [`LttReport::render`].
    #[must_use]
    pub fn render(&self) -> String {
        let cert = match &self.certification {
            Some(c) => format!(
                "{:.4}  (e-value {:.1} >= {:.1}, first certified at round {})",
                c.threshold, c.e_value, self.crossing_level, c.certified_at_round
            ),
            // Not an error, and deliberately not a number: an uncertified controller has proven
            // nothing, and printing a threshold anyway is exactly the unproven claim this method
            // exists to refuse.
            None => "NONE — no threshold has earned a guarantee on this stream yet".to_owned(),
        };
        format!(
            "method: eprocess (anytime-valid)\n\
             pairs: {n_pairs}\n\
             certified threshold: {cert}\n\
             target alpha: {alpha:.4} (delta {delta:.4}, family-wise across grid AND rounds)\n\
             realized served-failure: {realized:.4}\n\
             guarantee: holds at EVERY round, no exchangeability assumed (Ville / e-process)\n",
            n_pairs = self.n_pairs,
            alpha = self.alpha,
            delta = self.delta,
            realized = self.realized_served_failure,
        )
    }
}

/// Replay `pairs` through an anytime-valid controller, in order.
///
/// Order matters here and nowhere else in this module: the other two methods sort or sweep, because
/// exchangeability makes order irrelevant to them. This one consumes the sequence as a stream, which
/// is what lets it stay valid when the stream is *not* exchangeable.
#[must_use]
pub fn calibrate_pairs_eprocess(pairs: &[(f64, bool)], alpha: f64, delta: f64) -> EProcessReport {
    // Grid from the observed score support, as LTT does — but QUANTISED, which LTT does not need to
    // be and this does.
    //
    // The Bonferroni crossing level is `n/delta`, so evidence required per threshold grows linearly
    // in the number of distinct scores. LTT can take one candidate per distinct score for free
    // because its exact-binomial test does not pay per candidate; here, a judge emitting
    // full-precision floats over 10k traces yields ~10k distinct scores and a crossing level of
    // 200,000 — a threshold that would essentially never certify, and the failure is silent: the
    // report just says "nothing certified" and looks like insufficient data rather than a
    // self-inflicted power collapse.
    //
    // Quantising to 2dp bounds the grid at 101 points regardless of store size. Resolution finer
    // than 0.01 on a gate score is not information anyone acts on, and the statistical power bought
    // back is worth far more than the granularity given up.
    //
    // Caught in review after I documented this exact hazard in the module doc and then failed to
    // guard it — the grid is data-derived, so it looked bounded while being bounded by the data.
    const GRID_QUANTUM: f64 = 100.0;
    let mut grid: Vec<f64> = pairs
        .iter()
        .map(|&(s, _)| (s * GRID_QUANTUM).round() / GRID_QUANTUM)
        .collect();
    grid.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
    grid.dedup();

    let mut ctrl = eprocess::EProcessRiskControl::new(alpha, delta, eprocess::DEFAULT_BET, &grid);
    for &(score, correct) in pairs {
        ctrl.observe_served(score, correct);
    }
    EProcessReport {
        n_pairs: pairs.len(),
        certification: ctrl.certified_threshold(),
        alpha,
        delta,
        crossing_level: ctrl.crossing_level(),
        realized_served_failure: ctrl.realized_served_failure(),
    }
}

/// Anytime-valid calibration from every trace in the store that has a deferred outcome.
///
/// Error handling and tenant scoping match [`calibrate_from_store`] exactly.
///
/// # Errors
/// Returns [`StoreError`] if a stored trace's deferred verdicts cannot be read.
pub fn calibrate_from_store_eprocess(
    db_path: impl AsRef<Path>,
    tenant: &str,
    alpha: f64,
    delta: f64,
) -> Result<EProcessReport, StoreError> {
    let db_path = db_path.as_ref();
    let traces = store::load_tenant_traces(db_path, tenant).unwrap_or_default();
    let mut pairs = Vec::with_capacity(traces.len());
    for trace in &traces {
        let deferred = store::load_deferred(db_path, &trace.trace_id.to_string())?;
        if let Some(pair) = trace_pair(trace, &deferred) {
            pairs.push(pair);
        }
    }
    Ok(calibrate_pairs_eprocess(&pairs, alpha, delta))
}

/// Calibrate an LTT threshold from every trace in the store that has a deferred outcome.
///
/// Error handling and tenant scoping match [`calibrate_from_store`] exactly.
///
/// # Errors
/// Returns [`StoreError`] if a stored trace's deferred verdicts cannot be read.
pub fn calibrate_from_store_ltt(
    db_path: impl AsRef<Path>,
    tenant: &str,
    alpha: f64,
    delta: f64,
    min_n: usize,
) -> Result<LttReport, StoreError> {
    let traces = store::load_tenant_traces(&db_path, tenant).unwrap_or_default();
    let mut pairs = Vec::with_capacity(traces.len());
    for trace in &traces {
        let deferred = store::load_deferred(&db_path, &trace.trace_id.to_string())?;
        if let Some(pair) = trace_pair(trace, &deferred) {
            pairs.push(pair);
        }
    }
    Ok(calibrate_pairs_ltt(&pairs, alpha, delta, min_n))
}

/// Calibrate a conformal threshold from every trace in the store that has a deferred outcome
/// recorded.
///
/// # Errors
/// Returns [`StoreError`] if a stored trace's deferred verdicts cannot be read. An unreadable or
/// not-yet-initialized store is treated as zero traces (a 0-pair, infeasible report), matching the
/// forgiving behaviour of `firstpass trace` — calibrating before any traffic is a valid state, not
/// an error.
pub fn calibrate_from_store(
    db_path: impl AsRef<Path>,
    tenant: &str,
    alpha: f64,
    delta: f64,
    min_n: usize,
) -> Result<CalibrationReport, StoreError> {
    // Tenant-scoped (ADR 0004 §D3): a tenant only ever calibrates against its own feedback. The
    // per-trace `load_deferred` below is safe unscoped because every `trace` here already belongs
    // to `tenant`.
    let traces = store::load_tenant_traces(&db_path, tenant).unwrap_or_default();
    let mut pairs = Vec::with_capacity(traces.len());
    for trace in &traces {
        let deferred = store::load_deferred(&db_path, &trace.trace_id.to_string())?;
        if let Some(pair) = trace_pair(trace, &deferred) {
            pairs.push(pair);
        }
    }
    Ok(calibrate_pairs(&pairs, alpha, delta, min_n))
}

#[cfg(test)]
mod tests {
    use firstpass_core::{
        Features, FinalOutcome, GENESIS_HASH, GateResult, Mode, PolicyRef, RequestInfo, ServedFrom,
        TaskKind,
    };

    use super::*;
    use crate::store;

    /// A minimal trace serving rung 0 with a single deterministic gate score, mirroring
    /// `store::sample_trace` but with a caller-chosen score.
    fn trace_with_score(score: f64) -> Trace {
        let verdict = if score >= 0.5 {
            Verdict::Pass
        } else {
            Verdict::Fail
        };
        let attempt = Attempt {
            rung: 0,
            model: "claude-haiku-4-5".to_owned(),
            provider: "anthropic".to_owned(),
            in_tokens: 10,
            cache_write_tokens: 0,
            cache_read_tokens: 0,
            out_tokens: 5,
            cost_usd: 0.001,
            latency_ms: 12,
            gates: vec![GateResult {
                gate_id: "gate@v1".to_owned(),
                verdict,
                score: Some(Score::clamped(score)),
                cost_usd: 0.0,
                ms: 10,
                reason: None,
                evidence_ref: None,
            }],
            verdict,
        };
        let mut trace = Trace {
            trace_id: uuid::Uuid::now_v7(),
            prev_hash: GENESIS_HASH.to_owned(),
            tenant_id: "tenant-a".to_owned(),
            session_id: "session-1".to_owned(),
            ts: jiff::Timestamp::now(),
            mode: Mode::Enforce,
            policy: PolicyRef {
                id: "test@v0".to_owned(),
                explore: false,
                propensity: None,
                mode_profile: None,
            },
            request: RequestInfo {
                api: "anthropic.messages".to_owned(),
                prompt_hash: "deadbeef".to_owned(),
                features: Features::new(TaskKind::Other),
            },
            attempts: vec![attempt],
            deferred: Vec::new(),
            final_: FinalOutcome {
                served_rung: Some(0),
                served_from: ServedFrom::Attempt,
                total_cost_usd: 0.001,
                gate_cost_usd: 0.0,
                total_latency_ms: 12,
                escalations: 0,
                counterfactual_baseline_usd: 0.001,
                savings_usd: 0.0,
                cache_source: None,
            },
            probe: None,
            rollout: None,
            shadow: None,
            route_ix: None,
            predicted_pass: None,
            elastic: None,
        };
        trace.recompute_savings();
        trace
    }

    #[test]
    fn calibrate_pairs_finds_a_feasible_threshold_on_clean_pairs() {
        // Scores cleanly separate correct (>=0.7) from incorrect (<0.3). alpha=0.2 tolerates
        // some incorrect items being served, so conformal maximizes coverage — not just
        // separation — up to that budget; alpha=0.2 also keeps the Hoeffding slack satisfiable
        // at this sample size (min_n=30 wants a workable n, not the hundreds needed to certify
        // alpha=0.1 at zero observed failures).
        let mut pairs = Vec::new();
        for i in 0..60u32 {
            pairs.push((0.7 + f64::from(i % 10) * 0.01, true));
        }
        for i in 0..60u32 {
            pairs.push((0.2 + f64::from(i % 10) * 0.01, false));
        }
        let report = calibrate_pairs(&pairs, 0.2, 0.1, 30);
        assert!(
            report.conformal.feasible,
            "clean separation must be feasible"
        );
        assert!(
            report.conformal.threshold >= 0.2 && report.conformal.threshold <= 0.79,
            "threshold {} must land inside the observed score range",
            report.conformal.threshold
        );
        assert_eq!(report.n_pairs, 120);
        assert!(
            report.empirical_served_failure <= 0.2 + 1e-9,
            "empirical served-failure {} must respect alpha — the conformal guarantee",
            report.empirical_served_failure
        );
    }

    #[test]
    fn calibrate_pairs_infeasible_below_min_n() {
        let pairs = vec![(0.9, true), (0.9, true), (0.1, false)];
        let report = calibrate_pairs(&pairs, 0.1, 0.1, 30);
        assert!(
            !report.conformal.feasible,
            "too few pairs must be infeasible"
        );
    }

    #[tokio::test]
    async fn calibrate_from_store_pairs_only_traces_with_deferred_feedback() {
        let db_path = std::env::temp_dir().join(format!(
            "firstpass-calibrate-test-{}.db",
            uuid::Uuid::now_v7()
        ));
        let (tx, handle) = store::open(&db_path).unwrap();

        // 40 high-score traces confirmed correct, 40 low-score traces confirmed incorrect, and
        // 5 traces with no deferred verdict at all (must be excluded from calibration).
        let mut correct_ids = Vec::new();
        let mut incorrect_ids = Vec::new();
        for i in 0..40u32 {
            let t = trace_with_score(0.7 + f64::from(i % 10) * 0.01);
            correct_ids.push(t.trace_id.to_string());
            tx.try_send(t).unwrap();
        }
        for i in 0..40u32 {
            let t = trace_with_score(0.2 + f64::from(i % 10) * 0.01);
            incorrect_ids.push(t.trace_id.to_string());
            tx.try_send(t).unwrap();
        }
        for i in 0..5u32 {
            tx.try_send(trace_with_score(0.5 + f64::from(i) * 0.01))
                .unwrap();
        }
        drop(tx);
        handle.await.unwrap();

        for trace_id in &correct_ids {
            let dv = DeferredVerdict {
                gate_id: "outcome".to_owned(),
                verdict: Verdict::Pass,
                score: None,
                reported_at: jiff::Timestamp::now(),
                reporter: "unit-test".to_owned(),
            };
            store::append_deferred(&db_path, trace_id, &dv).unwrap();
        }
        for trace_id in &incorrect_ids {
            let dv = DeferredVerdict {
                gate_id: "outcome".to_owned(),
                verdict: Verdict::Fail,
                score: None,
                reported_at: jiff::Timestamp::now(),
                reporter: "unit-test".to_owned(),
            };
            store::append_deferred(&db_path, trace_id, &dv).unwrap();
        }

        // alpha=0.2 for the same Hoeffding-slack reason as the calibrate_pairs test above.
        let report = calibrate_from_store(&db_path, "tenant-a", 0.2, 0.1, 30).unwrap();
        assert_eq!(
            report.n_pairs, 80,
            "only the 80 traces with deferred feedback pair up"
        );
        assert!(report.conformal.feasible);
        assert!(
            report.empirical_served_failure <= 0.2 + 1e-9,
            "empirical served-failure {} must respect alpha on clean synthetic data",
            report.empirical_served_failure
        );

        // D7 isolation: a different tenant sees none of tenant-a's pairs — calibration is empty.
        let other = calibrate_from_store(&db_path, "tenant-b", 0.2, 0.1, 30).unwrap();
        assert_eq!(
            other.n_pairs, 0,
            "tenant-b must not see tenant-a's feedback"
        );

        let _ = std::fs::remove_file(&db_path);
    }

    // ── LTT wiring tests ─────────────────────────────────────────────────────────────────────

    #[test]
    fn calibrate_pairs_ltt_feasible_on_clean_pairs() {
        // Same synthetic data as the conformal test — clean score separation, alpha=0.2.
        let mut pairs = Vec::new();
        for i in 0..60u32 {
            pairs.push((0.7 + f64::from(i % 10) * 0.01, true));
        }
        for i in 0..60u32 {
            pairs.push((0.2 + f64::from(i % 10) * 0.01, false));
        }
        let report = calibrate_pairs_ltt(&pairs, 0.2, 0.1, 30);
        assert!(
            report.ltt.feasible,
            "clean separation must be feasible with LTT"
        );
        assert!(
            report.ltt.threshold >= 0.2 && report.ltt.threshold <= 0.79,
            "threshold {} must land inside the observed score range",
            report.ltt.threshold
        );
        assert_eq!(report.n_pairs, 120);
        assert!(
            report.ltt.empirical_risk <= 0.2 + 1e-9,
            "empirical risk {} must respect alpha",
            report.ltt.empirical_risk
        );
    }

    #[test]
    fn calibrate_pairs_ltt_infeasible_below_min_n() {
        let pairs = vec![(0.9, true), (0.9, true), (0.1, false)];
        let report = calibrate_pairs_ltt(&pairs, 0.1, 0.05, 30);
        assert!(
            !report.ltt.feasible,
            "too few pairs must be infeasible with LTT"
        );
    }

    /// **The grid must stay bounded no matter how many distinct scores the store holds.**
    ///
    /// Caught in review. The Bonferroni crossing level is `n/delta`, so evidence required per
    /// threshold grows linearly in grid size: a judge emitting full-precision floats over 10k traces
    /// gives ~10k candidates and a crossing level of 200,000. Nothing would ever certify, and the
    /// report would say "no threshold certified" — indistinguishable from honest insufficient data,
    /// which is what makes it dangerous rather than merely wasteful.
    ///
    /// Asserts both halves: the grid is bounded, AND a clean stream at that scale still certifies.
    /// Bounding it while destroying certification would pass a size check and fail the user.
    #[test]
    fn a_high_precision_score_distribution_does_not_collapse_statistical_power() {
        // 4000 pairs, each with a distinct full-precision score in a tight band — exactly what a
        // continuous judge emits, and previously ~4000 grid points.
        let pairs: Vec<(f64, bool)> = (0..4000)
            .map(|i| {
                let score = 0.90 + f64::from(i) * 1e-7;
                (score, i % 20 != 0) // 5% failure rate, well under alpha
            })
            .collect();
        let report = calibrate_pairs_eprocess(&pairs, 0.20, 0.05);

        // 2dp quantisation over a 0.9..0.9004 band collapses to a handful of points; the hard
        // requirement is that it cannot scale with the store.
        assert!(
            report.crossing_level <= 101.0 / 0.05,
            "the grid must be bounded by quantisation, not by the data: crossing level {} implies \
             {} grid points",
            report.crossing_level,
            report.crossing_level * 0.05
        );
        assert!(
            report.certification.is_some(),
            "4000 clean pairs must still certify — bounding the grid must not cost the power it \
             was meant to protect"
        );
    }

    /// An uncertified stream must render as NONE, never as a number.
    ///
    /// The failure this guards is a quiet one: printing some default threshold when nothing has been
    /// proven reads exactly like a calibrated result to whoever runs the command. Too few pairs to
    /// certify must look like too few pairs to certify.
    #[test]
    fn eprocess_reports_no_threshold_when_nothing_is_certified() {
        let pairs: Vec<(f64, bool)> = vec![(0.9, true), (0.8, true)];
        let report = calibrate_pairs_eprocess(&pairs, 0.10, 0.05);
        assert!(
            report.certification.is_none(),
            "two pairs cannot certify anything at delta=0.05"
        );
        let rendered = report.render();
        assert!(
            rendered.contains("NONE"),
            "an uncertified stream must say so plainly, got: {rendered}"
        );
        assert!(
            rendered.contains("anytime-valid"),
            "the report must name the guarantee it provides, got: {rendered}"
        );
    }

    /// Enough clean evidence must certify, and the rendered threshold must be the certified one.
    /// The pairing with the test above is the contract: silent when unproven, specific when proven.
    #[test]
    fn eprocess_certifies_and_renders_the_threshold_on_a_clean_stream() {
        let mut pairs: Vec<(f64, bool)> = Vec::new();
        for i in 0..2000 {
            // Deterministic 5% failure rate, well under alpha — no RNG, so this is reproducible.
            pairs.push((0.9, i % 20 != 0));
        }
        let report = calibrate_pairs_eprocess(&pairs, 0.20, 0.05);
        let cert = report
            .certification
            .as_ref()
            .expect("2000 clean pairs must certify");
        assert!(
            cert.e_value >= report.crossing_level,
            "a certified threshold must meet the Bonferroni crossing level: {} < {}",
            cert.e_value,
            report.crossing_level
        );
        assert!(
            report.render().contains(&format!("{:.4}", cert.threshold)),
            "the rendered report must show the certified threshold"
        );
    }

    #[test]
    fn ltt_report_render_includes_method_and_far() {
        // Smoke-test that render() produces the expected key fields without panicking.
        let mut pairs: Vec<(f64, bool)> = Vec::new();
        for _ in 0..200 {
            pairs.push((0.9, true));
        }
        for _ in 0..5 {
            pairs.push((0.9, false));
        }
        for _ in 0..15 {
            pairs.push((0.2, false));
        }
        let report = calibrate_pairs_ltt(&pairs, 0.10, 0.05, 30);
        let rendered = report.render();
        assert!(
            rendered.contains("method: ltt"),
            "render must tag the method"
        );
        assert!(
            rendered.contains("false-accept rate:"),
            "render must include verifier ROC note"
        );
        assert!(
            rendered.contains("feasible:"),
            "render must include feasibility"
        );
    }
}