sharpebench-core 0.28.0

Deterministic, luck-robust quantitative evaluation kernel for trading agents.
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
//! Luck-robust performance-vs-budget curve: the honest, out-of-sample inversion
//! of an in-distribution scaling law.
//!
//! Some agent benchmarks fit a monotone, saturating law (e.g. a log-sigmoid) to
//! performance measured at increasing interaction budget, and report that curve as
//! a clean "more compute ⇒ more skill" story. That rise is an artifact of measuring
//! **in-distribution**: the agent keeps iterating on the *same* task, so more budget
//! can only help. SharpeBench already ships the single-point version of the same
//! idea, [`crate::composite::CompositeScore::dsr_per_cost`], one scalar of deflated
//! Sharpe per unit of spend. This module is the multi-point generalization, built to
//! the opposite standard: honest, out-of-sample, and deflation-adjusted.
//!
//! **The OOS contract (caller-enforced, as in [`crate::oos`]).** The input is the
//! *same* agent evaluated at a series of increasing training/compute budgets (number
//! of training windows, quantity of history, or the $compute/token channel). Each
//! point carries a slice of **held-out** returns drawn from a window that is
//! **disjoint from that point's training set**: the caller supplies the split and
//! guarantees the disjointness, exactly the convention [`crate::oos::oos_decay`]
//! assumes. A point's Sharpe is therefore genuine generalization, not in-sample fit.
//!
//! **No monotone law is fitted, deliberately.** In trading, out-of-sample
//! performance is typically **non-monotone** in training budget: past some point,
//! more compute buys overfitting, and held-out edge *falls*. Fitting a
//! monotone-saturating curve would paper over exactly the turn-down this benchmark
//! exists to expose. So this module reports the raw curve and the turn-down; it does
//! not smooth, extrapolate, or fit.
//!
//! **Deflated for the search over budgets.** Selecting the best of `N` budget points
//! is itself a search over `N`, a data-snooping channel the single-point score
//! cannot see. The reported peak therefore folds `n_budget_points` into the deflation
//! trial footprint of the peak, exactly as [`crate::composite::score_agent`] folds an
//! agent's declared `in_sample_trials` into `effective_n_trials`. The result,
//! [`BudgetCurveReport::peak_dsr_deflated_for_selection`], is strictly `<=` the naive
//! max, closing the budget-selection snooping loophole with existing machinery.
//!
//! **Comparable support is the caller's contract.** Nothing here can check that
//! two points were evaluated on the same market: the module receives returns, not
//! dates. A curve is only readable as "what budget bought" when every point's
//! held-out slice covers the same evaluation window and a comparable number of
//! periods, because both the Sharpe and its deflation move with the sample size
//! alone. Where that cannot be arranged, read the per-point
//! [`BudgetPoint::n_returns`] beside every figure: an unmatched support is a
//! confound in the curve, not a property of the budget.
//!
//! **Reported, never a rank gate.** Everything here is diagnostic. The curve, its
//! peak, and the overfit onset are surfaced for the operator; they do not gate
//! eligibility or rank. Wiring any of this into a rank key would silently recreate
//! the in-sample scaling-law anti-thesis the module is written to refute.

use serde::{Deserialize, Serialize};

use crate::deflated_sharpe::{deflated_sharpe_ratio, per_period_from_annualized, sharpe_ratio};
use crate::significance::bootstrap_pvalue;

/// Tuning for the budget-curve analysis. All fields default to house constants; the
/// bootstrap seed is fixed so the pinned implementation reproduces the
/// per-point p-values from the same inputs.
#[derive(Clone, Debug, Serialize)]
pub struct BudgetCurveOpts {
    /// Periods per year of the held-out returns. It converts the annualized
    /// `trials_sr_std` to the per-period unit the deflated Sharpe is computed in,
    /// and annualizes the reported raw Sharpe for legibility. The deflated Sharpe
    /// itself is never annualized (annualizing a DSR is meaningless). Must be
    /// finite and positive.
    pub periods_per_year: f64,
    /// Baseline multiple-testing footprint applied to *every* point's deflated
    /// Sharpe, before the budget-selection surcharge is folded into the peak.
    pub base_n_trials: u32,
    /// **Annualized** cross-trial dispersion of Sharpe ratios (the deflation
    /// footprint's scale), in the unit of
    /// [`crate::composite::ScoreConfig::trials_sr_std`] and with the same 0.5
    /// default prior. It is divided by `sqrt(periods_per_year)` before it reaches
    /// the per-period deflated Sharpe.
    pub trials_sr_std: f64,
    /// Seed for the per-point significance bootstrap (fixed ⇒ reproducible).
    pub bootstrap_seed: u64,
    /// Bootstrap resample count for the per-point p-value.
    pub n_boot: usize,
    /// Stationary-bootstrap block-continuation probability.
    pub block_prob: f64,
}

impl Default for BudgetCurveOpts {
    fn default() -> Self {
        Self {
            periods_per_year: 252.0,
            base_n_trials: 1,
            trials_sr_std: 0.5,
            bootstrap_seed: 0x5BA7_2026,
            n_boot: 2000,
            block_prob: 0.1,
        }
    }
}

/// One budget point's out-of-sample readout.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct BudgetPoint {
    /// The budget (training windows, history quantity, or $compute/token spend).
    pub budget: f64,
    /// Number of held-out returns backing this point.
    pub n_returns: usize,
    /// Deflated Sharpe on this point's held-out returns, at the baseline footprint
    /// (`opts.base_n_trials`). The luck-robust, out-of-sample skill at this budget.
    pub oos_dsr: f64,
    /// Raw (per-period, non-annualized) Sharpe on the held-out returns, reported
    /// for context alongside the deflated figure, never a gate.
    pub oos_sharpe: f64,
    /// `oos_sharpe` scaled by `sqrt(periods_per_year)`; legibility only. The
    /// square-root-of-time scaling is exact for i.i.d. returns and approximate on
    /// any autocorrelated simple-return series (Lo 2002), which is why this is a
    /// display figure and `oos_dsr` is computed from `oos_sharpe` per period.
    pub oos_sharpe_annualized: f64,
    /// Bootstrap p-value that this point's held-out edge is real (not luck).
    pub oos_p_value: f64,
    /// `(oos_dsr[i] - oos_dsr[i-1]) / (budget[i] - budget[i-1])`: the multi-point
    /// generalization of the single-point `dsr_per_cost`. `None` for the first
    /// point. `<= 0` means more budget bought *no* extra held-out edge: the
    /// non-improvement signature single-point scoring cannot see. `== 0` is a
    /// plateau and `< 0` a decline; neither is uncertainty-tested here.
    pub marginal_dsr_per_budget: Option<f64>,
}

/// The full curve-level report.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct BudgetCurveReport {
    /// Per-point readouts, in input (increasing-budget) order.
    pub points: Vec<BudgetPoint>,
    /// Number of budget points (the size of the budget-selection search).
    pub n_budget_points: usize,
    /// Budget at which `oos_dsr` is maximized (the first such budget on ties).
    pub peak_budget: f64,
    /// The naive maximum `oos_dsr` over the curve (at the baseline footprint).
    pub peak_dsr: f64,
    /// The peak's deflated Sharpe recomputed with `n_budget_points` folded into the
    /// trial footprint (`base_n_trials + n_budget_points`): the honest peak that
    /// pays for the search over budgets. Strictly `<=` [`Self::peak_dsr`].
    pub peak_dsr_deflated_for_selection: f64,
    /// The first budget where `marginal_dsr_per_budget <= 0`: the first budget that
    /// bought **no further** held-out edge. `None` when every step still rose.
    ///
    /// This is a **non-improvement** marker, not a measured deterioration. The
    /// condition is non-strict, so an exact plateau (marginal `0.0`, the shape an
    /// honestly saturating curve has) sets it just as a genuine turn-down does, and
    /// neither case is tested against the estimate's uncertainty: one negative
    /// marginal can be sampling noise. It is the onset a monotone-fit scaling law
    /// structurally cannot report; it is not, on its own, evidence that more compute
    /// made the agent worse. Read it beside that point's
    /// [`BudgetPoint::marginal_dsr_per_budget`] and [`BudgetPoint::oos_p_value`]
    /// before calling anything overfitting.
    ///
    /// Serialized as `non_improvement_onset`. The pre-rename key `overfit_onset`
    /// is still accepted on input and is deprecated for removal in a later major.
    #[serde(alias = "overfit_onset")]
    pub non_improvement_onset: Option<f64>,
    /// Whether `oos_dsr` strictly increases across *every* consecutive point: a
    /// genuinely monotone-improving curve, which is rare and honest in trading.
    pub is_monotone_improving: bool,
}

/// Compute the luck-robust budget curve from ordered `(budget, held_out_returns)`
/// points: the same agent at increasing budget, each point's returns drawn from a
/// window disjoint from that point's training set (the caller enforces the split).
///
/// # Errors
///
/// Returns `Err` at the boundary when: the input is empty or has a single point (a
/// curve needs at least two); the budgets are not strictly increasing; or any point
/// has fewer than two held-out returns (a Sharpe needs dispersion); or
/// `periods_per_year` is not finite and positive; or the deflated Sharpe at a
/// point could not be estimated, which includes a `trials_sr_std` that is not a
/// dispersion. The curve is a sequence of
/// comparable deflated Sharpes, so one that could not be estimated has no
/// stand-in value: the whole curve is withheld.
pub fn budget_curve(
    points: &[(f64, &[f64])],
    opts: &BudgetCurveOpts,
) -> Result<BudgetCurveReport, String> {
    if points.len() < 2 {
        return Err(format!(
            "at least two budget points are required, got {}",
            points.len()
        ));
    }
    let n_budget_points = points.len();

    for i in 0..n_budget_points {
        let (budget, returns) = points[i];
        if returns.len() < 2 {
            return Err(format!(
                "point {i} (budget {budget}) has {} held-out returns; at least 2 are required",
                returns.len()
            ));
        }
        if i > 0 {
            let prev = points[i - 1].0;
            if budget <= prev {
                return Err(format!(
                    "budgets must be strictly increasing: point {i} budget {budget} is not > point {} budget {prev}",
                    i - 1
                ));
            }
        }
    }

    // An infinite frequency would divide the prior to a zero dispersion, the
    // most favorable deflation there is, so it is refused with the rest.
    if !opts.periods_per_year.is_finite() || opts.periods_per_year <= 0.0 {
        return Err(format!(
            "periods_per_year must be finite and positive, got {}",
            opts.periods_per_year
        ));
    }
    let sr_std = per_period_from_annualized(opts.trials_sr_std, opts.periods_per_year);
    let ann = opts.periods_per_year.sqrt();
    let mut curve: Vec<BudgetPoint> = Vec::with_capacity(n_budget_points);
    for i in 0..n_budget_points {
        let (budget, returns) = points[i];
        let oos_dsr = deflated_sharpe_ratio(returns, opts.base_n_trials, sr_std)
            .map_err(|error| format!("point {i}: {error}"))?;
        let oos_sharpe = sharpe_ratio(returns);
        let oos_p_value =
            bootstrap_pvalue(returns, opts.bootstrap_seed, opts.n_boot, opts.block_prob)
                .map_err(|error| format!("point {i}: {error}"))?;
        let marginal_dsr_per_budget = if i == 0 {
            None
        } else {
            let db = budget - points[i - 1].0;
            Some((oos_dsr - curve[i - 1].oos_dsr) / db)
        };
        curve.push(BudgetPoint {
            budget,
            n_returns: returns.len(),
            oos_dsr,
            oos_sharpe,
            oos_sharpe_annualized: oos_sharpe * ann,
            oos_p_value,
            marginal_dsr_per_budget,
        });
    }

    // Peak = argmax oos_dsr, first occurrence on ties (so an improving-then-plateau
    // curve peaks at the *start* of the plateau, not somewhere along the flat tail).
    let mut peak_idx = 0usize;
    for i in 1..n_budget_points {
        if curve[i].oos_dsr > curve[peak_idx].oos_dsr {
            peak_idx = i;
        }
    }
    let peak_budget = curve[peak_idx].budget;
    let peak_dsr = curve[peak_idx].oos_dsr;

    // Fold the budget-selection search into the peak's deflation footprint, exactly
    // as composite.rs folds `in_sample_trials`: selecting the best of N budgets is a
    // search over N, so the honest peak clears a higher bar.
    let peak_footprint = opts.base_n_trials.saturating_add(n_budget_points as u32);
    let peak_dsr_deflated_for_selection =
        deflated_sharpe_ratio(points[peak_idx].1, peak_footprint, sr_std)
            .map_err(|error| format!("peak point {peak_idx}: {error}"))?;

    // First budget where more compute did not raise held-out edge. Non-strict, so a
    // plateau counts as non-improvement; it is not a claim of deterioration.
    let non_improvement_onset = curve
        .iter()
        .skip(1)
        .find(|p| matches!(p.marginal_dsr_per_budget, Some(m) if m <= 0.0))
        .map(|p| p.budget);

    // Strictly rising across every step ⇒ genuinely monotone-improving.
    let is_monotone_improving = curve
        .iter()
        .skip(1)
        .all(|p| matches!(p.marginal_dsr_per_budget, Some(m) if m > 0.0));

    Ok(BudgetCurveReport {
        points: curve,
        n_budget_points,
        peak_budget,
        peak_dsr,
        peak_dsr_deflated_for_selection,
        non_improvement_onset,
        is_monotone_improving,
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Deterministic pseudo-return window: a mean drift plus a sinusoidal wiggle so
    /// the Sharpe is finite and mid-range (no RNG ⇒ reproducible). Mirrors the
    /// generator used across composite.rs's tests.
    fn window(mean_ret: f64, amp: f64, n: usize) -> Vec<f64> {
        (0..n)
            .map(|i| mean_ret + amp * (i as f64 * 0.7).sin())
            .collect()
    }

    /// Assemble a `&[(f64, &[f64])]` from owned windows without lifetime pain.
    fn curve_of(pts: &[(f64, Vec<f64>)]) -> Vec<(f64, &[f64])> {
        pts.iter().map(|(b, w)| (*b, w.as_slice())).collect()
    }

    #[test]
    fn overfitting_curve_flags_the_turn_down_before_the_max_budget() {
        // Held-out edge rises then falls as budget grows: the classic overfit arc.
        // Amplitude is held constant (identical skew/kurtosis ⇒ the DSR is strictly
        // monotone in the mean), so the mean alone drives a clean, non-saturated arc.
        let pts = vec![
            (1.0, window(0.0007, 0.02, 40)),
            (2.0, window(0.0014, 0.02, 40)),
            (3.0, window(0.0020, 0.02, 40)), // peak
            (4.0, window(0.0013, 0.02, 40)),
            (5.0, window(0.0006, 0.02, 40)), // max budget, worst edge
        ];
        let c = curve_of(&pts);
        let r = budget_curve(&c, &BudgetCurveOpts::default()).unwrap();

        assert_eq!(r.peak_budget, 3.0, "peak is the interior budget: {r:?}");
        assert!(
            r.peak_budget < 5.0,
            "peak must precede the max budget (the EdgeBench differentiator)"
        );
        assert_eq!(
            r.non_improvement_onset,
            Some(4.0),
            "onset is the first budget where held-out edge stopped rising"
        );
        assert!(!r.is_monotone_improving, "a turn-down is not monotone");
    }

    #[test]
    fn improving_then_plateauing_curve_has_no_early_onset() {
        // Edge climbs then holds flat: honest saturation, not overfitting.
        let plateau = window(0.0020, 0.02, 40);
        let pts = vec![
            (1.0, window(0.0007, 0.02, 40)),
            (2.0, window(0.0014, 0.02, 40)),
            (3.0, plateau.clone()),
            (4.0, plateau.clone()),
            (5.0, plateau),
        ];
        let c = curve_of(&pts);
        let r = budget_curve(&c, &BudgetCurveOpts::default()).unwrap();

        assert_eq!(r.peak_budget, 3.0, "peak sits at the plateau start: {r:?}");
        // `non_improvement_onset` is a non-improvement marker, not a deterioration one: the
        // flat tail (identical windows ⇒ marginal exactly 0) sets it even though no
        // step ever declined. Pinning both halves keeps the field's name from being
        // read as evidence that more budget made the agent worse.
        assert_eq!(
            r.non_improvement_onset,
            Some(4.0),
            "the plateau start sets the non-improvement onset: {r:?}"
        );
        assert!(
            r.points
                .iter()
                .skip(1)
                .all(|p| p.marginal_dsr_per_budget.is_some_and(|m| m >= 0.0)),
            "no point declined, so nothing here is measured deterioration: {r:?}"
        );
        assert!(
            !r.is_monotone_improving,
            "a flat tail is not strictly rising"
        );
    }

    #[test]
    fn deflation_for_selection_strictly_raises_the_bar() {
        // Any curve with >= 2 points: selecting the best budget is a search over N,
        // so the selection-deflated peak must sit strictly below the naive max.
        let pts = vec![
            (1.0, window(0.0010, 0.02, 40)),
            (2.0, window(0.0014, 0.02, 40)),
            (3.0, window(0.0012, 0.02, 40)),
        ];
        let c = curve_of(&pts);
        let r = budget_curve(&c, &BudgetCurveOpts::default()).unwrap();
        assert!(
            r.peak_dsr_deflated_for_selection < r.peak_dsr,
            "selection deflation must strictly lower the peak: {} !< {}",
            r.peak_dsr_deflated_for_selection,
            r.peak_dsr
        );
    }

    #[test]
    fn marginal_is_none_first_then_tracks_the_dsr_sign() {
        let pts = vec![
            (1.0, window(0.0007, 0.02, 40)),
            (2.0, window(0.0020, 0.02, 40)), // DSR up ⇒ marginal > 0
            (3.0, window(0.0005, 0.02, 40)), // DSR down ⇒ marginal < 0
        ];
        let c = curve_of(&pts);
        let r = budget_curve(&c, &BudgetCurveOpts::default()).unwrap();

        assert!(
            r.points[0].marginal_dsr_per_budget.is_none(),
            "first is None"
        );

        let m1 = r.points[1].marginal_dsr_per_budget.unwrap();
        let d1 = r.points[1].oos_dsr - r.points[0].oos_dsr;
        assert!(m1 > 0.0 && d1 > 0.0, "rising step ⇒ positive marginal");
        assert_eq!(
            m1.signum(),
            d1.signum(),
            "marginal sign tracks the DSR delta"
        );

        let m2 = r.points[2].marginal_dsr_per_budget.unwrap();
        let d2 = r.points[2].oos_dsr - r.points[1].oos_dsr;
        assert!(m2 < 0.0 && d2 < 0.0, "falling step ⇒ negative marginal");
        assert_eq!(
            m2.signum(),
            d2.signum(),
            "marginal sign tracks the DSR delta"
        );
    }

    #[test]
    fn monotone_improving_true_only_for_a_strictly_rising_curve() {
        let rising_pts = [
            (1.0, window(0.0006, 0.02, 40)),
            (2.0, window(0.0013, 0.02, 40)),
            (3.0, window(0.0020, 0.02, 40)),
        ];
        let rising = curve_of(&rising_pts);
        let r = budget_curve(&rising, &BudgetCurveOpts::default()).unwrap();
        assert!(r.is_monotone_improving, "strictly rising DSR ⇒ true: {r:?}");
        assert!(
            r.non_improvement_onset.is_none(),
            "a rising curve never turns down"
        );

        // Insert a dip ⇒ no longer monotone.
        let dipped_pts = [
            (1.0, window(0.0006, 0.02, 40)),
            (2.0, window(0.0020, 0.02, 40)),
            (3.0, window(0.0013, 0.02, 40)),
        ];
        let dipped = curve_of(&dipped_pts);
        let r2 = budget_curve(&dipped, &BudgetCurveOpts::default()).unwrap();
        assert!(!r2.is_monotone_improving, "a dip breaks monotonicity");
    }

    #[test]
    fn degenerate_inputs_error_cleanly() {
        let opts = BudgetCurveOpts::default();

        // Empty.
        assert!(budget_curve(&[], &opts).is_err());

        // Single point.
        let one = window(0.005, 0.005, 40);
        assert!(budget_curve(&[(1.0, one.as_slice())], &opts).is_err());

        // Non-increasing budgets.
        let a = window(0.005, 0.005, 40);
        let b = window(0.005, 0.005, 40);
        assert!(budget_curve(&[(2.0, a.as_slice()), (2.0, b.as_slice())], &opts).is_err());
        assert!(budget_curve(&[(3.0, a.as_slice()), (1.0, b.as_slice())], &opts).is_err());

        // A point with an empty / too-short return window.
        let full = window(0.005, 0.005, 40);
        let empty: Vec<f64> = Vec::new();
        assert!(budget_curve(&[(1.0, full.as_slice()), (2.0, empty.as_slice())], &opts).is_err());
        let single = vec![0.01];
        assert!(budget_curve(&[(1.0, full.as_slice()), (2.0, single.as_slice())], &opts).is_err());
    }

    /// The annualized prior is deflated with in the returns' own unit:
    /// `0.5 / sqrt(periods_per_year)` per period. Applied per period
    /// unconverted, 0.5 on daily bars was an annualized bar about sqrt(252)
    /// times too high.
    #[test]
    fn the_annualized_prior_is_converted_and_the_frequency_boundary_refused() {
        let pts = vec![
            (1.0, window(0.0010, 0.02, 40)),
            (2.0, window(0.0020, 0.02, 40)),
            (3.0, window(0.0012, 0.02, 40)),
        ];
        let c = curve_of(&pts);
        for ppy in [52.0, 252.0, 8760.0] {
            let opts = BudgetCurveOpts {
                periods_per_year: ppy,
                base_n_trials: 10,
                ..BudgetCurveOpts::default()
            };
            let r = budget_curve(&c, &opts).unwrap();
            let per_period = 0.5 / f64::sqrt(ppy);
            for (p, (_, returns)) in r.points.iter().zip(&pts) {
                let expected = deflated_sharpe_ratio(returns, 10, per_period).unwrap();
                assert_eq!(p.oos_dsr.to_bits(), expected.to_bits(), "ppy {ppy}");
            }
            let peak = deflated_sharpe_ratio(&pts[1].1, 13, per_period).unwrap();
            assert_eq!(
                r.peak_dsr_deflated_for_selection.to_bits(),
                peak.to_bits(),
                "ppy {ppy}"
            );
        }
        for bad in [f64::INFINITY, 0.0, -252.0, f64::NAN] {
            let opts = BudgetCurveOpts {
                periods_per_year: bad,
                ..BudgetCurveOpts::default()
            };
            let err = budget_curve(&c, &opts).unwrap_err();
            assert!(
                err.starts_with("periods_per_year must be finite and positive"),
                "{err}"
            );
        }
    }

    #[test]
    fn annualized_sharpe_scales_the_raw_sharpe() {
        let pts_owned = [
            (1.0, window(0.005, 0.008, 80)),
            (2.0, window(0.006, 0.007, 80)),
        ];
        let pts = curve_of(&pts_owned);
        let opts = BudgetCurveOpts {
            periods_per_year: 252.0,
            ..BudgetCurveOpts::default()
        };
        let r = budget_curve(&pts, &opts).unwrap();
        let p0 = &r.points[0];
        assert!(
            (p0.oos_sharpe_annualized - p0.oos_sharpe * 252.0_f64.sqrt()).abs() < 1e-12,
            "annualized = raw * sqrt(periods_per_year)"
        );
    }

    #[test]
    fn non_improvement_onset_serializes_under_the_new_key_and_reads_the_old_one() {
        let pts = vec![
            (1.0, window(0.0007, 0.02, 40)),
            (2.0, window(0.0020, 0.02, 40)),
            (3.0, window(0.0013, 0.02, 40)),
        ];
        let c = curve_of(&pts);
        let r = budget_curve(&c, &BudgetCurveOpts::default()).unwrap();
        assert_eq!(r.non_improvement_onset, Some(3.0), "{r:?}");

        let json = serde_json::to_string(&r).unwrap();
        assert!(json.contains("\"non_improvement_onset\":3.0"), "{json}");
        assert!(
            !json.contains("\"overfit_onset\":"),
            "old key must not serialize"
        );

        let round_trip: BudgetCurveReport = serde_json::from_str(&json).unwrap();
        assert_eq!(round_trip.non_improvement_onset, Some(3.0));
        assert_eq!(round_trip.peak_budget, r.peak_budget);
        assert_eq!(round_trip.points.len(), r.points.len());

        // A report saved before the rename still parses: `overfit_onset` is
        // accepted as an alias of the new key.
        let legacy = json.replace("\"non_improvement_onset\":", "\"overfit_onset\":");
        assert!(legacy.contains("\"overfit_onset\":3.0") && !legacy.contains("non_improvement"));
        let from_legacy: BudgetCurveReport = serde_json::from_str(&legacy).unwrap();
        assert_eq!(from_legacy.non_improvement_onset, Some(3.0));
    }
}