Skip to main content

nautilus_model/instruments/
tick_scheme.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Tick scheme definitions for price-level navigation.
17
18use std::{
19    fmt::Display,
20    str::FromStr,
21    sync::{LazyLock, PoisonError, RwLock},
22};
23
24use ahash::AHashMap;
25use nautilus_core::correctness::{
26    CorrectnessError, CorrectnessResult, check_in_range_inclusive_u8, check_predicate_true,
27    check_valid_string_ascii, check_valid_string_ascii_optional,
28};
29use thiserror::Error;
30
31#[cfg(not(feature = "high-precision"))]
32use crate::types::fixed::{check_fixed_raw_i64 as check_fixed_raw, f64_to_fixed_i64};
33#[cfg(feature = "high-precision")]
34use crate::types::fixed::{check_fixed_raw_i128 as check_fixed_raw, f64_to_fixed_i128};
35use crate::types::{
36    Price,
37    fixed::{FIXED_PRECISION, FIXED_SCALAR},
38    price::{PRICE_MAX, PRICE_MIN, PRICE_RAW_MAX, PRICE_RAW_MIN, PriceRaw},
39};
40
41pub trait TickSchemeRule: Display {
42    fn next_bid_price(&self, value: f64, n: i32, precision: u8) -> Option<Price>;
43    fn next_ask_price(&self, value: f64, n: i32, precision: u8) -> Option<Price>;
44}
45
46/// Error returned when tick scheme construction or parsing fails.
47#[derive(Clone, Debug, Error, PartialEq)]
48pub enum TickSchemeError {
49    /// A fixed tick size was not positive.
50    #[error("tick must be positive")]
51    TickNotPositive {
52        /// The invalid tick size.
53        tick: Price,
54    },
55    /// No tier definitions were supplied.
56    #[error("tiers must not be empty")]
57    EmptyTiers,
58    /// A tier contained a NaN value.
59    #[error("tier {index}: values must not be NaN")]
60    TierValuesNaN {
61        /// The invalid tier index.
62        index: usize,
63        /// The tier start value.
64        start: f64,
65        /// The tier stop value.
66        stop: f64,
67        /// The tier step value.
68        step: f64,
69    },
70    /// A tier start was not less than its stop.
71    #[error("tier {index}: start ({start}) must be less than stop ({stop})")]
72    TierStartNotLessThanStop {
73        /// The invalid tier index.
74        index: usize,
75        /// The tier start value.
76        start: f64,
77        /// The tier stop value.
78        stop: f64,
79    },
80    /// A tier step was not positive.
81    #[error("tier {index}: step ({step}) must be positive")]
82    TierStepNotPositive {
83        /// The invalid tier index.
84        index: usize,
85        /// The tier step value.
86        step: f64,
87    },
88    /// A finite tier step was not smaller than the tier range.
89    #[error("tier {index}: step ({step}) must be less than range ({stop} - {start} = {range})")]
90    TierStepNotLessThanRange {
91        /// The invalid tier index.
92        index: usize,
93        /// The tier start value.
94        start: f64,
95        /// The tier stop value.
96        stop: f64,
97        /// The tier step value.
98        step: f64,
99        /// The tier range.
100        range: f64,
101    },
102    /// A tier overlaps the previous tier.
103    #[error("tier {index}: start ({start}) overlaps previous tier stop ({prev_stop})")]
104    TierOverlapsPrevious {
105        /// The invalid tier index.
106        index: usize,
107        /// The tier start value.
108        start: f64,
109        /// The previous tier stop value.
110        prev_stop: f64,
111    },
112    /// A tier start was outside the representable price range.
113    #[error("tier {index}: start ({start}) outside Price range")]
114    TierStartOutsidePriceRange {
115        /// The invalid tier index.
116        index: usize,
117        /// The tier start value.
118        start: f64,
119    },
120    /// A tier stop was outside the representable price range.
121    #[error("tier {index}: stop ({stop}) outside Price range")]
122    TierStopOutsidePriceRange {
123        /// The invalid tier index.
124        index: usize,
125        /// The tier stop value.
126        stop: f64,
127    },
128    /// The requested price precision is invalid.
129    #[error("{source}")]
130    InvalidPrecision {
131        /// The source correctness error.
132        #[source]
133        source: CorrectnessError,
134    },
135    /// The fixed tick cannot be represented at the requested precision.
136    #[error("tick {tick} cannot be represented at precision {precision}")]
137    TickNotRepresentable {
138        /// The invalid tick size.
139        tick: Price,
140        /// The requested price precision.
141        precision: u8,
142    },
143    /// A tick scheme name was invalid.
144    #[error("{source}")]
145    InvalidName {
146        /// The source correctness error.
147        #[source]
148        source: CorrectnessError,
149    },
150    /// A tick scheme name was already registered.
151    #[error("tick scheme {name} is already registered")]
152    DuplicateName {
153        /// The normalized duplicate name.
154        name: String,
155    },
156    /// Tier expansion produced no ticks.
157    #[error("tier expansion produced no ticks")]
158    EmptyTickExpansion,
159    /// An expanded tick value was outside the representable price range.
160    #[error("expanded tick value {value} outside Price range")]
161    ExpandedTickOutsidePriceRange {
162        /// The invalid expanded tick value.
163        value: f64,
164    },
165    /// The requested tick scheme name is not registered.
166    #[error("unknown tick scheme {name}")]
167    UnknownName {
168        /// The requested tick scheme name.
169        name: String,
170    },
171    /// Expanded ticks were not strictly increasing.
172    #[error("tick at index {index} is not greater than the previous tick")]
173    TicksNotIncreasing {
174        /// The invalid tick index.
175        index: usize,
176    },
177}
178
179pub const BETFAIR_TICK_SCHEME_NAME: &str = "BETFAIR";
180pub const TOPIX100_TICK_SCHEME_NAME: &str = "TOPIX100";
181pub const CRYPTO_0_01_TICK_SCHEME_NAME: &str = "CRYPTO_0_01";
182pub const FOREX_3DECIMAL_TICK_SCHEME_NAME: &str = "FOREX_3DECIMAL";
183pub const FOREX_5DECIMAL_TICK_SCHEME_NAME: &str = "FOREX_5DECIMAL";
184pub const FIXED_TICK_SCHEME_NAME: &str = "FIXED";
185pub const FIXED_PRECISION_TICK_SCHEME_PREFIX: &str = "FIXED_PRECISION_";
186
187const BETFAIR_PRICE_TIERS: [(f64, f64, f64); 10] = [
188    (1.01, 2.0, 0.01),
189    (2.0, 3.0, 0.02),
190    (3.0, 4.0, 0.05),
191    (4.0, 6.0, 0.1),
192    (6.0, 10.0, 0.2),
193    (10.0, 20.0, 0.5),
194    (20.0, 30.0, 1.0),
195    (30.0, 50.0, 2.0),
196    (50.0, 100.0, 5.0),
197    (100.0, 1010.0, 10.0),
198];
199
200pub static BETFAIR_TICK_SCHEME: LazyLock<TieredTickScheme> = LazyLock::new(|| {
201    TieredTickScheme::new(&BETFAIR_PRICE_TIERS, 2, 100)
202        .expect("BETFAIR tick scheme tiers are valid by construction")
203});
204
205pub static TOPIX100_TICK_SCHEME: LazyLock<TieredTickScheme> = LazyLock::new(|| {
206    TieredTickScheme::new(
207        &[
208            (0.1, 1_000.0, 0.1),
209            (1_000.0, 3_000.0, 0.5),
210            (3_000.0, 10_000.0, 1.0),
211            (10_000.0, 30_000.0, 5.0),
212            (30_000.0, 100_000.0, 10.0),
213            (100_000.0, 300_000.0, 50.0),
214            (300_000.0, 1_000_000.0, 100.0),
215            (1_000_000.0, 3_000_000.0, 500.0),
216            (3_000_000.0, 10_000_000.0, 1_000.0),
217            (10_000_000.0, 30_000_000.0, 5_000.0),
218            (30_000_000.0, f64::INFINITY, 10_000.0),
219        ],
220        4,
221        10_000,
222    )
223    .expect("TOPIX100 tick scheme tiers are valid by construction")
224});
225
226static FIXED_TICK_SCHEME: LazyLock<FixedTickScheme> =
227    LazyLock::new(|| FixedTickScheme::new(Price::from("1")).expect("fixed tick scheme is valid"));
228
229pub(crate) static CRYPTO_0_01_TICK_SCHEME: LazyLock<FixedTickScheme> = LazyLock::new(|| {
230    FixedTickScheme::new(Price::from("0.01")).expect("crypto tick scheme is valid")
231});
232
233static FIXED_PRECISION_TICK_SCHEMES: LazyLock<Vec<FixedTickScheme>> = LazyLock::new(|| {
234    (0..=FIXED_PRECISION)
235        .map(|precision| {
236            let raw = PriceRaw::pow(10, u32::from(FIXED_PRECISION - precision));
237            let tick = Price::from_raw(raw, precision);
238            FixedTickScheme::new(tick).expect("fixed precision tick scheme is valid")
239        })
240        .collect()
241});
242
243static TICK_SCHEMES: LazyLock<RwLock<AHashMap<String, &'static TickScheme>>> =
244    LazyLock::new(|| RwLock::new(AHashMap::new()));
245
246/// Fixed price grid with an exact, positive tick size.
247///
248/// Navigation returns `None` if the requested output precision cannot represent the tick exactly.
249#[derive(Debug, Clone, Copy, Eq)]
250pub struct FixedTickScheme {
251    tick: Price,
252}
253
254impl FixedTickScheme {
255    /// Creates a new [`FixedTickScheme`] with the given tick size.
256    ///
257    /// # Errors
258    ///
259    /// Returns an error if the tick is not positive, is outside the representable price range,
260    /// has invalid precision, or contains fractional digits beyond its precision.
261    pub fn new(tick: Price) -> Result<Self, TickSchemeError> {
262        check_in_range_inclusive_u8(tick.precision, 0, FIXED_PRECISION, "precision")
263            .map_err(|source| TickSchemeError::InvalidPrecision { source })?;
264
265        if tick.is_zero() || tick.is_negative() {
266            return Err(TickSchemeError::TickNotPositive { tick });
267        }
268
269        if tick > Price::max(tick.precision) || fixed_tick_raw(tick, tick.precision).is_none() {
270            return Err(TickSchemeError::TickNotRepresentable {
271                tick,
272                precision: tick.precision,
273            });
274        }
275
276        Ok(Self { tick })
277    }
278
279    /// Creates a fixed tick scheme with an explicit default output precision.
280    ///
281    /// # Errors
282    ///
283    /// Returns an error if the tick is invalid, the output precision is invalid,
284    /// or the tick is not exactly representable at that precision.
285    pub fn new_with_precision(tick: Price, price_precision: u8) -> Result<Self, TickSchemeError> {
286        Self::new(tick)?;
287        check_in_range_inclusive_u8(price_precision, 0, FIXED_PRECISION, "precision")
288            .map_err(|source| TickSchemeError::InvalidPrecision { source })?;
289
290        if fixed_tick_raw(tick, price_precision).is_none() {
291            return Err(TickSchemeError::TickNotRepresentable {
292                tick,
293                precision: price_precision,
294            });
295        }
296
297        Ok(Self {
298            tick: Price::from_raw(tick.raw(), price_precision),
299        })
300    }
301
302    /// Returns the fixed tick size.
303    #[must_use]
304    pub const fn tick(&self) -> Price {
305        self.tick
306    }
307
308    /// Returns the default output price precision.
309    #[must_use]
310    pub const fn precision(&self) -> u8 {
311        self.tick.precision
312    }
313}
314
315impl PartialEq for FixedTickScheme {
316    fn eq(&self, other: &Self) -> bool {
317        self.tick == other.tick && self.precision() == other.precision()
318    }
319}
320
321impl TickSchemeRule for FixedTickScheme {
322    #[inline(always)]
323    fn next_bid_price(&self, value: f64, n: i32, precision: u8) -> Option<Price> {
324        fixed_next_bid_price(self.tick, value, n, precision)
325    }
326
327    #[inline(always)]
328    fn next_ask_price(&self, value: f64, n: i32, precision: u8) -> Option<Price> {
329        fixed_next_ask_price(self.tick, value, n, precision)
330    }
331}
332
333impl Display for FixedTickScheme {
334    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
335        f.write_str(FIXED_TICK_SCHEME_NAME)
336    }
337}
338
339/// Tick scheme with price-dependent tick sizes.
340///
341/// Stores expanded ticks as raw fixed-point integers for exact comparison
342/// and fast binary search. Each tier defines a (start, stop, step) range
343/// that is expanded at construction.
344#[derive(Debug, Clone, PartialEq, Eq)]
345pub struct TieredTickScheme {
346    ticks: Vec<PriceRaw>,
347    precision: u8,
348}
349
350impl TieredTickScheme {
351    /// Creates a new [`TieredTickScheme`] from tier definitions.
352    ///
353    /// Each tier is `(start, stop, step)` where `start < stop` and `step > 0`.
354    /// Use `f64::INFINITY` for the last tier's stop value.
355    ///
356    /// # Errors
357    ///
358    /// Returns an error if any tier is invalid or contains out-of-range values.
359    pub fn new(
360        tiers: &[(f64, f64, f64)],
361        price_precision: u8,
362        max_ticks_per_tier: usize,
363    ) -> Result<Self, TickSchemeError> {
364        if tiers.is_empty() {
365            return Err(TickSchemeError::EmptyTiers);
366        }
367
368        for (index, &(start, stop, step)) in tiers.iter().enumerate() {
369            if start.is_nan() || stop.is_nan() || step.is_nan() {
370                return Err(TickSchemeError::TierValuesNaN {
371                    index,
372                    start,
373                    stop,
374                    step,
375                });
376            }
377
378            if start >= stop {
379                return Err(TickSchemeError::TierStartNotLessThanStop { index, start, stop });
380            }
381
382            if step <= 0.0 {
383                return Err(TickSchemeError::TierStepNotPositive { index, step });
384            }
385
386            if !stop.is_infinite() && step >= (stop - start) {
387                return Err(TickSchemeError::TierStepNotLessThanRange {
388                    index,
389                    start,
390                    stop,
391                    step,
392                    range: stop - start,
393                });
394            }
395
396            if index > 0 {
397                let prev_stop = tiers[index - 1].1;
398
399                if start < prev_stop {
400                    return Err(TickSchemeError::TierOverlapsPrevious {
401                        index,
402                        start,
403                        prev_stop,
404                    });
405                }
406            }
407
408            if !(PRICE_MIN..=PRICE_MAX).contains(&start) {
409                return Err(TickSchemeError::TierStartOutsidePriceRange { index, start });
410            }
411
412            if !stop.is_infinite() && !(PRICE_MIN..=PRICE_MAX).contains(&stop) {
413                return Err(TickSchemeError::TierStopOutsidePriceRange { index, stop });
414            }
415        }
416
417        let _ = Price::new_checked(0.0, price_precision)
418            .map_err(|source| TickSchemeError::InvalidPrecision { source })?;
419
420        let ticks = Self::build_ticks(tiers, price_precision, max_ticks_per_tier)?;
421
422        if ticks.is_empty() {
423            return Err(TickSchemeError::EmptyTickExpansion);
424        }
425        Ok(Self {
426            ticks,
427            precision: price_precision,
428        })
429    }
430
431    /// Reconstructs a tiered scheme from exact expanded prices.
432    ///
433    /// # Errors
434    ///
435    /// Returns an error if ticks are empty, are not strictly increasing, or cannot
436    /// be represented exactly at the requested price precision.
437    pub fn from_ticks(ticks: Vec<Price>, price_precision: u8) -> Result<Self, TickSchemeError> {
438        check_in_range_inclusive_u8(price_precision, 0, FIXED_PRECISION, "precision")
439            .map_err(|source| TickSchemeError::InvalidPrecision { source })?;
440
441        if ticks.is_empty() {
442            return Err(TickSchemeError::EmptyTickExpansion);
443        }
444
445        let mut raw_ticks = Vec::with_capacity(ticks.len());
446        for (index, tick) in ticks.into_iter().enumerate() {
447            if !(PRICE_RAW_MIN..=PRICE_RAW_MAX).contains(&tick.raw())
448                || fixed_tick_raw(tick, tick.precision).is_none()
449                || fixed_tick_raw(tick, price_precision).is_none()
450            {
451                return Err(TickSchemeError::TickNotRepresentable {
452                    tick,
453                    precision: price_precision,
454                });
455            }
456
457            if raw_ticks
458                .last()
459                .is_some_and(|previous| *previous >= tick.raw())
460            {
461                return Err(TickSchemeError::TicksNotIncreasing { index });
462            }
463
464            raw_ticks.push(tick.raw());
465        }
466
467        Ok(Self {
468            ticks: raw_ticks,
469            precision: price_precision,
470        })
471    }
472
473    fn build_ticks(
474        tiers: &[(f64, f64, f64)],
475        precision: u8,
476        max_ticks_per_tier: usize,
477    ) -> Result<Vec<PriceRaw>, TickSchemeError> {
478        let mut all_ticks = Vec::new();
479
480        for &(start, stop, step) in tiers {
481            let effective_stop = if stop.is_infinite() {
482                start + (max_ticks_per_tier.saturating_add(1) as f64) * step
483            } else {
484                stop
485            };
486            let mut i = 0;
487            while i < max_ticks_per_tier {
488                let value = start + (i as f64) * step;
489
490                if value >= effective_stop {
491                    break;
492                }
493
494                if !value.is_finite() || !(PRICE_MIN..=PRICE_MAX).contains(&value) {
495                    return Err(TickSchemeError::ExpandedTickOutsidePriceRange { value });
496                }
497                let raw = f64_to_raw(value, precision);
498
499                if all_ticks.last() != Some(&raw) {
500                    all_ticks.push(raw);
501                }
502                i += 1;
503            }
504        }
505        Ok(all_ticks)
506    }
507
508    #[inline(always)]
509    fn price_at(&self, index: usize) -> Price {
510        Price {
511            raw: self.ticks[index],
512            precision: self.precision,
513        }
514    }
515
516    /// Returns the expanded ticks as `Price` objects.
517    #[must_use]
518    pub fn ticks(&self) -> Vec<Price> {
519        self.ticks
520            .iter()
521            .map(|&raw| Price {
522                raw,
523                precision: self.precision,
524            })
525            .collect()
526    }
527
528    /// Returns the number of ticks.
529    #[must_use]
530    pub fn tick_count(&self) -> usize {
531        self.ticks.len()
532    }
533
534    /// Returns the minimum tick price.
535    #[must_use]
536    pub fn min_price(&self) -> Price {
537        self.price_at(0)
538    }
539
540    /// Returns the maximum tick price.
541    #[must_use]
542    pub fn max_price(&self) -> Price {
543        self.price_at(self.ticks.len() - 1)
544    }
545
546    /// Returns the price precision.
547    #[must_use]
548    pub fn precision(&self) -> u8 {
549        self.precision
550    }
551
552    /// Creates the TOPIX100 tick scheme.
553    ///
554    /// # Panics
555    ///
556    /// Panics if the hardcoded TOPIX100 tiers fail validation (should not happen).
557    #[must_use]
558    pub fn topix100() -> Self {
559        TOPIX100_TICK_SCHEME.clone()
560    }
561
562    /// Creates the BETFAIR tick scheme.
563    ///
564    /// # Panics
565    ///
566    /// Panics if the hardcoded BETFAIR tiers fail validation (should not happen).
567    #[must_use]
568    pub fn betfair() -> Self {
569        BETFAIR_TICK_SCHEME.clone()
570    }
571}
572
573impl TickSchemeRule for TieredTickScheme {
574    fn next_bid_price(&self, value: f64, n: i32, _precision: u8) -> Option<Price> {
575        let n = usize::try_from(n).ok()?;
576
577        if value.is_nan() {
578            return None;
579        }
580
581        // Floor to get a raw value guaranteed <= true value, infinite values
582        // saturate at the integer bounds during the float-to-integer cast.
583        let raw_floor = (value * FIXED_SCALAR).floor() as PriceRaw;
584
585        if raw_floor < self.ticks[0] {
586            return None;
587        }
588
589        // First index where tick >= raw_floor
590        let idx = self.ticks.partition_point(|&t| t < raw_floor);
591
592        if idx < self.ticks.len() && self.ticks[idx] == raw_floor {
593            // Value converts exactly to a tick
594            let target = idx.checked_sub(n)?;
595            return Some(self.price_at(target));
596        }
597
598        // Value is beyond or between ticks; bid is the tick below
599        let target = idx.checked_sub(1)?.checked_sub(n)?;
600        Some(self.price_at(target))
601    }
602
603    fn next_ask_price(&self, value: f64, n: i32, _precision: u8) -> Option<Price> {
604        let n = usize::try_from(n).ok()?;
605
606        if value.is_nan() {
607            return None;
608        }
609
610        // Ceil to get a raw value guaranteed >= true value, infinite values
611        // saturate at the integer bounds during the float-to-integer cast.
612        let raw_ceil = (value * FIXED_SCALAR).ceil() as PriceRaw;
613
614        if raw_ceil > *self.ticks.last()? {
615            return None;
616        }
617
618        // First index where tick >= raw_ceil
619        let idx = self.ticks.partition_point(|&t| t < raw_ceil);
620        let target = idx.checked_add(n)?;
621
622        if target >= self.ticks.len() {
623            return None;
624        }
625        Some(self.price_at(target))
626    }
627}
628
629impl Display for TieredTickScheme {
630    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
631        write!(f, "TIERED")
632    }
633}
634
635#[derive(Clone, Debug, PartialEq, Eq)]
636pub enum TickScheme {
637    Fixed(FixedTickScheme),
638    Tiered(TieredTickScheme),
639    Betfair,
640    Crypto,
641}
642
643impl TickSchemeRule for TickScheme {
644    #[inline(always)]
645    fn next_bid_price(&self, value: f64, n: i32, precision: u8) -> Option<Price> {
646        match self {
647            Self::Fixed(scheme) => scheme.next_bid_price(value, n, precision),
648            Self::Tiered(scheme) => scheme.next_bid_price(value, n, precision),
649            Self::Betfair => BETFAIR_TICK_SCHEME.next_bid_price(value, n, precision),
650            Self::Crypto => CRYPTO_0_01_TICK_SCHEME.next_bid_price(value, n, precision),
651        }
652    }
653
654    #[inline(always)]
655    fn next_ask_price(&self, value: f64, n: i32, precision: u8) -> Option<Price> {
656        match self {
657            Self::Fixed(scheme) => scheme.next_ask_price(value, n, precision),
658            Self::Tiered(scheme) => scheme.next_ask_price(value, n, precision),
659            Self::Betfair => BETFAIR_TICK_SCHEME.next_ask_price(value, n, precision),
660            Self::Crypto => CRYPTO_0_01_TICK_SCHEME.next_ask_price(value, n, precision),
661        }
662    }
663}
664
665impl Display for TickScheme {
666    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
667        match self {
668            Self::Fixed(scheme) => write!(f, "{scheme}"),
669            Self::Tiered(scheme) => write!(f, "{scheme}"),
670            Self::Betfair => write!(f, "{BETFAIR_TICK_SCHEME_NAME}"),
671            Self::Crypto => write!(f, "{CRYPTO_0_01_TICK_SCHEME_NAME}"),
672        }
673    }
674}
675
676impl FromStr for TickScheme {
677    type Err = TickSchemeError;
678
679    fn from_str(s: &str) -> Result<Self, Self::Err> {
680        match s.trim().to_ascii_uppercase().as_str() {
681            FIXED_TICK_SCHEME_NAME => Ok(Self::Fixed(*FIXED_TICK_SCHEME)),
682            FOREX_3DECIMAL_TICK_SCHEME_NAME => Ok(Self::Fixed(FIXED_PRECISION_TICK_SCHEMES[3])),
683            FOREX_5DECIMAL_TICK_SCHEME_NAME => Ok(Self::Fixed(FIXED_PRECISION_TICK_SCHEMES[5])),
684            TOPIX100_TICK_SCHEME_NAME => Ok(Self::Tiered(TieredTickScheme::topix100())),
685            BETFAIR_TICK_SCHEME_NAME => Ok(Self::Betfair),
686            CRYPTO_0_01_TICK_SCHEME_NAME => Ok(Self::Crypto),
687            name => {
688                if let Some(precision) = parse_fixed_precision_name(name)
689                    && precision <= FIXED_PRECISION
690                {
691                    return Ok(Self::Fixed(
692                        FIXED_PRECISION_TICK_SCHEMES[usize::from(precision)],
693                    ));
694                }
695
696                if let Some(scheme) = TICK_SCHEMES
697                    .read()
698                    .unwrap_or_else(PoisonError::into_inner)
699                    .get(name)
700                {
701                    return Ok((*scheme).clone());
702                }
703
704                Err(TickSchemeError::UnknownName {
705                    name: s.to_string(),
706                })
707            }
708        }
709    }
710}
711
712/// Returns a registered tick scheme rule by name.
713#[must_use]
714pub fn tick_scheme_rule_from_name(name: &str) -> Option<&'static dyn TickSchemeRule> {
715    let name = name.trim();
716    if name.eq_ignore_ascii_case(FIXED_TICK_SCHEME_NAME) {
717        Some(&*FIXED_TICK_SCHEME)
718    } else if name.eq_ignore_ascii_case(FOREX_3DECIMAL_TICK_SCHEME_NAME) {
719        Some(&FIXED_PRECISION_TICK_SCHEMES[3])
720    } else if name.eq_ignore_ascii_case(FOREX_5DECIMAL_TICK_SCHEME_NAME) {
721        Some(&FIXED_PRECISION_TICK_SCHEMES[5])
722    } else if name.eq_ignore_ascii_case(TOPIX100_TICK_SCHEME_NAME) {
723        Some(&*TOPIX100_TICK_SCHEME)
724    } else if name.eq_ignore_ascii_case(BETFAIR_TICK_SCHEME_NAME) {
725        Some(&*BETFAIR_TICK_SCHEME)
726    } else if name.eq_ignore_ascii_case(CRYPTO_0_01_TICK_SCHEME_NAME) {
727        Some(&*CRYPTO_0_01_TICK_SCHEME)
728    } else {
729        parse_fixed_precision_name_ignore_ascii_case(name)
730            .and_then(|precision| {
731                FIXED_PRECISION_TICK_SCHEMES
732                    .get(usize::from(precision))
733                    .map(|scheme| scheme as &dyn TickSchemeRule)
734            })
735            .or_else(|| {
736                TICK_SCHEMES
737                    .read()
738                    .unwrap_or_else(PoisonError::into_inner)
739                    .get(&name.to_ascii_uppercase())
740                    .map(|scheme| *scheme as &dyn TickSchemeRule)
741            })
742    }
743}
744
745/// Registers a named tick scheme for the lifetime of the process.
746///
747/// Names are trimmed and matched without regard to ASCII case. Registered names,
748/// including built-in names and aliases, cannot be replaced or removed.
749///
750/// # Errors
751///
752/// Returns an error if the name is invalid or already registered.
753pub fn register_tick_scheme(name: &str, scheme: TickScheme) -> Result<(), TickSchemeError> {
754    let name = name.trim().to_ascii_uppercase();
755    check_valid_string_ascii(&name, "name")
756        .map_err(|source| TickSchemeError::InvalidName { source })?;
757
758    if tick_scheme_rule_from_name(&name).is_some() {
759        return Err(TickSchemeError::DuplicateName { name });
760    }
761
762    let mut schemes = TICK_SCHEMES.write().unwrap_or_else(PoisonError::into_inner);
763    if schemes.contains_key(&name) {
764        return Err(TickSchemeError::DuplicateName { name });
765    }
766
767    // The registry is append-only so borrowed rules remain valid after the lock is released
768    schemes.insert(name, Box::leak(Box::new(scheme)));
769    Ok(())
770}
771
772/// Returns a copy of a registered scheme, matching trimmed names without regard to ASCII case.
773#[must_use]
774pub fn get_tick_scheme(name: &str) -> Option<TickScheme> {
775    name.parse().ok()
776}
777
778/// Returns all registered names in uppercase, sorted lexicographically.
779#[must_use]
780pub fn list_tick_schemes() -> Vec<String> {
781    let mut names: Vec<String> = [
782        FIXED_TICK_SCHEME_NAME,
783        FOREX_3DECIMAL_TICK_SCHEME_NAME,
784        FOREX_5DECIMAL_TICK_SCHEME_NAME,
785        TOPIX100_TICK_SCHEME_NAME,
786        BETFAIR_TICK_SCHEME_NAME,
787        CRYPTO_0_01_TICK_SCHEME_NAME,
788    ]
789    .into_iter()
790    .map(String::from)
791    .chain(
792        (0..=FIXED_PRECISION)
793            .map(|precision| format!("{FIXED_PRECISION_TICK_SCHEME_PREFIX}{precision}")),
794    )
795    .collect();
796    names.extend(
797        TICK_SCHEMES
798            .read()
799            .unwrap_or_else(PoisonError::into_inner)
800            .keys()
801            .cloned(),
802    );
803    names.sort_unstable();
804    names
805}
806
807/// Validates an optional tick scheme name.
808///
809/// # Errors
810///
811/// Returns an error if the name is not valid ASCII or does not identify a registered scheme.
812pub fn check_tick_scheme<T: AsRef<str> + Copy>(tick_scheme: Option<T>) -> CorrectnessResult<()> {
813    check_valid_string_ascii_optional(tick_scheme, "tick_scheme")?;
814    if let Some(name) = tick_scheme {
815        check_predicate_true(
816            tick_scheme_rule_from_name(name.as_ref()).is_some(),
817            "tick_scheme not found in tick schemes",
818        )?;
819    }
820    Ok(())
821}
822
823/// Converts an f64 value to a `PriceRaw` fixed-point integer.
824#[inline(always)]
825fn f64_to_raw(value: f64, precision: u8) -> PriceRaw {
826    #[cfg(feature = "high-precision")]
827    {
828        f64_to_fixed_i128(value, precision)
829    }
830    #[cfg(not(feature = "high-precision"))]
831    {
832        f64_to_fixed_i64(value, precision)
833    }
834}
835
836fn parse_fixed_precision_name(name: &str) -> Option<u8> {
837    name.strip_prefix(FIXED_PRECISION_TICK_SCHEME_PREFIX)
838        .and_then(|precision| precision.parse::<u8>().ok())
839}
840
841fn parse_fixed_precision_name_ignore_ascii_case(name: &str) -> Option<u8> {
842    let prefix_len = FIXED_PRECISION_TICK_SCHEME_PREFIX.len();
843    let prefix = name.get(..prefix_len)?;
844    if !prefix.eq_ignore_ascii_case(FIXED_PRECISION_TICK_SCHEME_PREFIX) {
845        return None;
846    }
847
848    name.get(prefix_len..)?.parse::<u8>().ok()
849}
850
851fn fixed_next_bid_price(tick: Price, value: f64, n: i32, precision: u8) -> Option<Price> {
852    let n = PriceRaw::from(u32::try_from(n).ok()?);
853    let tick_raw = fixed_tick_raw(tick, precision)?;
854    let value_raw = value_to_raw(value)?;
855    let base = value_raw
856        .checked_div_euclid(tick_raw)?
857        .checked_mul(tick_raw)?;
858    let offset = tick_raw.checked_mul(n)?;
859    price_from_raw_checked(base.checked_sub(offset)?, precision)
860}
861
862fn fixed_next_ask_price(tick: Price, value: f64, n: i32, precision: u8) -> Option<Price> {
863    let n = PriceRaw::from(u32::try_from(n).ok()?);
864    let tick_raw = fixed_tick_raw(tick, precision)?;
865    let value_raw = value_to_raw(value)?;
866    let base = value_raw
867        .checked_neg()?
868        .checked_div_euclid(tick_raw)?
869        .checked_neg()?
870        .checked_mul(tick_raw)?;
871    let offset = tick_raw.checked_mul(n)?;
872    price_from_raw_checked(base.checked_add(offset)?, precision)
873}
874
875fn fixed_tick_raw(tick: Price, precision: u8) -> Option<PriceRaw> {
876    if precision > FIXED_PRECISION {
877        return None;
878    }
879
880    check_fixed_raw(tick.raw(), precision).ok()?;
881    Some(tick.raw())
882}
883
884fn value_to_raw(value: f64) -> Option<PriceRaw> {
885    if !value.is_finite() || !(PRICE_MIN..=PRICE_MAX).contains(&value) {
886        return None;
887    }
888    Some(f64_to_raw(value, FIXED_PRECISION))
889}
890
891fn price_from_raw_checked(raw: PriceRaw, precision: u8) -> Option<Price> {
892    if !(PRICE_RAW_MIN..=PRICE_RAW_MAX).contains(&raw) {
893        return None;
894    }
895    Some(Price { raw, precision })
896}
897
898#[cfg(test)]
899mod tests {
900    use std::{
901        str::FromStr,
902        sync::{Arc, Barrier},
903    };
904
905    use proptest::prelude::*;
906    use rstest::rstest;
907    use ustr::Ustr;
908
909    use super::*;
910    use crate::instruments::{CurrencyPair, Instrument, stubs::currency_pair_btcusdt};
911
912    #[rstest]
913    fn tiered_from_ticks_preserves_exact_prices_and_precision() {
914        let ticks = vec![
915            Price::from("-0.000000001"),
916            Price::from("0.000000002"),
917            Price::from("0.123456789"),
918        ];
919        let scheme = TieredTickScheme::from_ticks(ticks.clone(), 9).unwrap();
920
921        assert_eq!(scheme.ticks(), ticks);
922        assert_eq!(scheme.precision(), 9);
923        assert_eq!(scheme.tick_count(), 3);
924        assert_eq!(scheme.min_price(), ticks[0]);
925        assert_eq!(scheme.max_price(), ticks[2]);
926    }
927
928    #[rstest]
929    #[case::empty(vec![], TickSchemeError::EmptyTickExpansion)]
930    #[case::duplicate(vec![Price::from("0.01"), Price::from("0.01")], TickSchemeError::TicksNotIncreasing { index: 1 })]
931    #[case::descending(vec![Price::from("0.03"), Price::from("0.01")], TickSchemeError::TicksNotIncreasing { index: 1 })]
932    #[case::inexact(vec![Price::from("0.001")], TickSchemeError::TickNotRepresentable { tick: Price::from("0.001"), precision: 2 })]
933    fn tiered_from_ticks_rejects_invalid_prices(
934        #[case] ticks: Vec<Price>,
935        #[case] expected_error: TickSchemeError,
936    ) {
937        assert_eq!(TieredTickScheme::from_ticks(ticks, 2), Err(expected_error));
938    }
939
940    #[rstest]
941    fn tiered_from_ticks_rejects_invalid_precision() {
942        let precision = FIXED_PRECISION + 1;
943        let source =
944            check_in_range_inclusive_u8(precision, 0, FIXED_PRECISION, "precision").unwrap_err();
945
946        assert_eq!(
947            TieredTickScheme::from_ticks(vec![Price::from("0.01")], precision),
948            Err(TickSchemeError::InvalidPrecision { source })
949        );
950    }
951
952    #[rstest]
953    #[case::raw_fraction(Price { raw: 1, precision: 2 })]
954    #[case::out_of_range(Price { raw: PRICE_RAW_MAX + 1, precision: FIXED_PRECISION })]
955    #[case::invalid_precision(Price { raw: 0, precision: FIXED_PRECISION + 1 })]
956    fn tiered_from_ticks_rejects_invalid_raw_price(#[case] tick: Price) {
957        assert_eq!(
958            TieredTickScheme::from_ticks(vec![tick], 2),
959            Err(TickSchemeError::TickNotRepresentable { tick, precision: 2 })
960        );
961    }
962
963    #[rstest]
964    #[case(" test_builder_registered_scheme ", true)]
965    #[case(" test_builder_unknown_scheme ", false)]
966    fn instrument_builder_validates_registered_scheme_names(
967        mut currency_pair_btcusdt: CurrencyPair,
968        #[case] name: &str,
969        #[case] registered: bool,
970    ) {
971        if registered {
972            register_tick_scheme(
973                name,
974                TickScheme::Fixed(FixedTickScheme::new(Price::from("0.05")).unwrap()),
975            )
976            .unwrap();
977        }
978
979        currency_pair_btcusdt.tick_scheme = Some(Ustr::from(name));
980        let expected = currency_pair_btcusdt;
981        let result = CurrencyPair::builder()
982            .instrument_id(expected.id)
983            .raw_symbol(expected.raw_symbol)
984            .base_currency(expected.base_currency)
985            .quote_currency(expected.quote_currency)
986            .price_precision(expected.price_precision)
987            .size_precision(expected.size_precision)
988            .price_increment(expected.price_increment)
989            .size_increment(expected.size_increment)
990            .max_quantity(expected.max_quantity.unwrap())
991            .min_quantity(expected.min_quantity.unwrap())
992            .max_price(expected.max_price.unwrap())
993            .min_price(expected.min_price.unwrap())
994            .margin_init(expected.margin_init)
995            .margin_maint(expected.margin_maint)
996            .tick_scheme(Ustr::from(name))
997            .ts_event(expected.ts_event)
998            .ts_init(expected.ts_init)
999            .build();
1000
1001        if registered {
1002            let instrument = result.unwrap();
1003
1004            assert_eq!(
1005                serde_json::to_value(&instrument).unwrap(),
1006                serde_json::to_value(&expected).unwrap()
1007            );
1008            assert_eq!(
1009                instrument.next_bid_price(1.13, 0),
1010                Some(Price::from("1.10"))
1011            );
1012            assert_eq!(
1013                instrument.next_ask_price(1.13, 0),
1014                Some(Price::from("1.15"))
1015            );
1016        } else {
1017            assert_eq!(
1018                result.unwrap_err(),
1019                CorrectnessError::PredicateViolation {
1020                    message: "tick_scheme not found in tick schemes".into(),
1021                }
1022            );
1023        }
1024    }
1025
1026    #[rstest]
1027    fn registered_fixed_scheme_rounds_and_rejects_duplicate_cases() {
1028        let name = "TEST_REGISTERED_FIXED_CASES";
1029        let scheme = FixedTickScheme::new_with_precision(Price::from("0.05"), 2).unwrap();
1030        register_tick_scheme(name, TickScheme::Fixed(scheme)).unwrap();
1031
1032        let registered = get_tick_scheme(" test_registered_fixed_cases ").unwrap();
1033        let rule = tick_scheme_rule_from_name(name).unwrap();
1034        let duplicate = register_tick_scheme(
1035            "test_registered_fixed_cases",
1036            TickScheme::Fixed(FixedTickScheme::new(Price::from("1.0")).unwrap()),
1037        );
1038
1039        assert_eq!(registered, TickScheme::Fixed(scheme));
1040        assert_eq!(rule.next_bid_price(1.13, 0, 2), Some(Price::from("1.10")));
1041        assert_eq!(rule.next_ask_price(1.13, 1, 2), Some(Price::from("1.20")));
1042        assert_eq!(
1043            duplicate,
1044            Err(TickSchemeError::DuplicateName { name: name.into() })
1045        );
1046        assert_eq!(get_tick_scheme(name), Some(TickScheme::Fixed(scheme)));
1047        let names = list_tick_schemes();
1048        assert!(names.windows(2).all(|pair| pair[0] < pair[1]));
1049        assert!(names.contains(&name.to_string()));
1050    }
1051
1052    #[rstest]
1053    #[case("FIXED")]
1054    #[case("forex_3decimal")]
1055    #[case("FOREX_5DECIMAL")]
1056    #[case("TOPIX100")]
1057    #[case("betfair")]
1058    #[case("CRYPTO_0_01")]
1059    #[case("FIXED_PRECISION_1")]
1060    #[case(" fixed_precision_01 ")]
1061    fn registration_protects_builtins(#[case] name: &str) {
1062        let original = get_tick_scheme(name).unwrap();
1063        let result = register_tick_scheme(
1064            name,
1065            TickScheme::Fixed(FixedTickScheme::new(Price::from("2.0")).unwrap()),
1066        );
1067
1068        assert_eq!(
1069            result,
1070            Err(TickSchemeError::DuplicateName {
1071                name: name.trim().to_ascii_uppercase()
1072            })
1073        );
1074        assert_eq!(get_tick_scheme(name), Some(original));
1075    }
1076
1077    #[rstest]
1078    #[case("")]
1079    #[case("   ")]
1080    #[case("\u{e9}")]
1081    fn registration_rejects_invalid_names(#[case] name: &str) {
1082        let source = check_valid_string_ascii(name.trim(), "name").unwrap_err();
1083        let result = register_tick_scheme(name, TickScheme::Betfair);
1084
1085        assert_eq!(result, Err(TickSchemeError::InvalidName { source }));
1086    }
1087
1088    #[rstest]
1089    #[case(PRICE_RAW_MAX + 1)]
1090    #[case(crate::types::price::PRICE_UNDEF)]
1091    fn fixed_tick_rejects_out_of_range_raw_values(#[case] raw: PriceRaw) {
1092        let tick = Price { raw, precision: 0 };
1093
1094        assert_eq!(
1095            FixedTickScheme::new(tick),
1096            Err(TickSchemeError::TickNotRepresentable { tick, precision: 0 })
1097        );
1098    }
1099
1100    #[rstest]
1101    fn registration_is_atomic_across_threads() {
1102        let barrier = Arc::new(Barrier::new(8));
1103
1104        #[allow(
1105            clippy::needless_collect,
1106            reason = "all threads must start before any joins so the barrier can open"
1107        )]
1108        let handles: Vec<_> = (0..8)
1109            .map(|index| {
1110                let barrier = barrier.clone();
1111                std::thread::spawn(move || {
1112                    barrier.wait();
1113
1114                    let name = if index % 2 == 0 {
1115                        "TEST_ATOMIC_REGISTRATION"
1116                    } else {
1117                        "test_atomic_registration"
1118                    };
1119
1120                    register_tick_scheme(name, TickScheme::Crypto)
1121                })
1122            })
1123            .collect();
1124
1125        let results: Vec<_> = handles
1126            .into_iter()
1127            .map(|handle| handle.join().unwrap())
1128            .collect();
1129
1130        assert_eq!(results.iter().filter(|result| result.is_ok()).count(), 1);
1131        assert_eq!(
1132            results
1133                .iter()
1134                .filter(|result| **result
1135                    == Err(TickSchemeError::DuplicateName {
1136                        name: "TEST_ATOMIC_REGISTRATION".into()
1137                    }))
1138                .count(),
1139            7
1140        );
1141        assert_eq!(
1142            get_tick_scheme("test_atomic_registration"),
1143            Some(TickScheme::Crypto)
1144        );
1145    }
1146
1147    #[rstest]
1148    fn registered_tiered_scheme_preserves_exact_transition_rounding() {
1149        let scheme =
1150            TieredTickScheme::new(&[(0.05, 10.0, 0.05), (10.0, f64::INFINITY, 0.25)], 2, 1000)
1151                .unwrap();
1152        register_tick_scheme(
1153            "TEST_REGISTERED_TIERED_TRANSITION",
1154            TickScheme::Tiered(scheme.clone()),
1155        )
1156        .unwrap();
1157        let rule = tick_scheme_rule_from_name("test_registered_tiered_transition").unwrap();
1158
1159        assert_eq!(rule.next_bid_price(9.99, 0, 2), Some(Price::from("9.95")));
1160        assert_eq!(rule.next_ask_price(9.99, 0, 2), Some(Price::from("10.00")));
1161        assert_eq!(rule.next_bid_price(10.63, 0, 2), Some(Price::from("10.50")));
1162        assert_eq!(rule.next_ask_price(10.63, 0, 2), Some(Price::from("10.75")));
1163        assert_eq!(
1164            get_tick_scheme("TEST_REGISTERED_TIERED_TRANSITION"),
1165            Some(TickScheme::Tiered(scheme))
1166        );
1167    }
1168
1169    #[rstest]
1170    fn fixed_explicit_precision_validates_and_preserves_tick() {
1171        let scheme = FixedTickScheme::new_with_precision(Price::from("0.25"), 3).unwrap();
1172
1173        assert_eq!(scheme.tick(), Price::from("0.250"));
1174        assert_eq!(scheme.precision(), 3);
1175        assert_eq!(scheme, FixedTickScheme::new(Price::from("0.250")).unwrap());
1176        assert_ne!(scheme, FixedTickScheme::new(Price::from("0.25")).unwrap());
1177        assert_eq!(
1178            scheme.next_bid_price(1.63, 0, 3),
1179            Some(Price::from("1.500"))
1180        );
1181        assert_eq!(
1182            scheme.next_ask_price(1.63, 0, 3),
1183            Some(Price::from("1.750"))
1184        );
1185    }
1186
1187    #[rstest]
1188    #[case("0.015", 2)]
1189    #[case("0.001", 2)]
1190    #[case("0.050000001", 2)]
1191    fn fixed_explicit_precision_rejects_unrepresentable_ticks(
1192        #[case] value: &str,
1193        #[case] precision: u8,
1194    ) {
1195        let tick = Price::from(value);
1196
1197        assert_eq!(
1198            FixedTickScheme::new_with_precision(tick, precision),
1199            Err(TickSchemeError::TickNotRepresentable { tick, precision })
1200        );
1201    }
1202
1203    #[rstest]
1204    fn fixed_explicit_precision_returns_typed_precision_error() {
1205        let precision = FIXED_PRECISION + 1;
1206        let source =
1207            check_in_range_inclusive_u8(precision, 0, FIXED_PRECISION, "precision").unwrap_err();
1208
1209        assert_eq!(
1210            FixedTickScheme::new_with_precision(Price::from("0.01"), precision),
1211            Err(TickSchemeError::InvalidPrecision { source })
1212        );
1213    }
1214
1215    #[rstest]
1216    fn fixed_explicit_precision_accepts_large_exact_tick() {
1217        let scheme = FixedTickScheme::new_with_precision(Price::from("1000000.25"), 2).unwrap();
1218
1219        assert_eq!(scheme.precision(), 2);
1220        assert_eq!(
1221            scheme.next_bid_price(1_000_000.26, 0, 2),
1222            Some(Price::from("1000000.25"))
1223        );
1224    }
1225
1226    #[rstest]
1227    fn fixed_tick_scheme_prices() {
1228        let scheme = FixedTickScheme::new(Price::from("0.5")).unwrap();
1229        let bid = scheme.next_bid_price(10.3, 0, 2).unwrap();
1230        let ask = scheme.next_ask_price(10.3, 0, 2).unwrap();
1231        assert_eq!(bid, Price::from("10.00"));
1232        assert_eq!(ask, Price::from("10.50"));
1233    }
1234
1235    #[rstest]
1236    fn fixed_tick_negative_returns_typed_error_with_display() {
1237        let error = FixedTickScheme::new(Price::from("-0.01")).unwrap_err();
1238
1239        assert_eq!(
1240            error,
1241            TickSchemeError::TickNotPositive {
1242                tick: Price::from("-0.01")
1243            }
1244        );
1245        assert_eq!(error.to_string(), "tick must be positive");
1246    }
1247
1248    #[rstest]
1249    fn fixed_tick_boundary() {
1250        let scheme = FixedTickScheme::new(Price::from("0.5")).unwrap();
1251        let price = scheme.next_bid_price(10.5, 0, 2).unwrap();
1252        assert_eq!(price, Price::new(10.5, 2));
1253    }
1254
1255    #[rstest]
1256    fn fixed_tick_scheme_preserves_decimal_boundaries() {
1257        let tenth = FixedTickScheme::new(Price::from("0.1")).unwrap();
1258        let cent = FixedTickScheme::new(Price::from("0.01")).unwrap();
1259
1260        assert_eq!(tenth.next_bid_price(0.3, 0, 1), Some(Price::new(0.3, 1)));
1261        assert_eq!(tenth.next_ask_price(0.3, 0, 1), Some(Price::new(0.3, 1)));
1262        assert_eq!(cent.next_bid_price(0.07, 0, 2), Some(Price::new(0.07, 2)));
1263        assert_eq!(cent.next_ask_price(0.07, 0, 2), Some(Price::new(0.07, 2)));
1264    }
1265
1266    #[rstest]
1267    fn fixed_tick_multiple_steps() {
1268        let scheme = FixedTickScheme::new(Price::from("1.0")).unwrap();
1269        let bid = scheme.next_bid_price(10.0, 2, 1).unwrap();
1270        let ask = scheme.next_ask_price(10.0, 3, 1).unwrap();
1271        assert_eq!(bid, Price::new(8.0, 1));
1272        assert_eq!(ask, Price::new(13.0, 1));
1273    }
1274
1275    #[rstest]
1276    fn tick_scheme_round_trip() {
1277        let scheme = TickScheme::from_str("CRYPTO_0_01").unwrap();
1278        assert_eq!(scheme.to_string(), "CRYPTO_0_01");
1279    }
1280
1281    #[rstest]
1282    fn tick_scheme_rule_from_fixed_precision_name() {
1283        let scheme = tick_scheme_rule_from_name("fixed_precision_1").unwrap();
1284
1285        assert_eq!(scheme.next_bid_price(0.3, 0, 1), Some(Price::new(0.3, 1)));
1286        assert_eq!(scheme.next_ask_price(0.31, 0, 1), Some(Price::new(0.4, 1)));
1287    }
1288
1289    #[rstest]
1290    fn tick_scheme_unknown() {
1291        let error = TickScheme::from_str("UNKNOWN").unwrap_err();
1292
1293        assert_eq!(
1294            error,
1295            TickSchemeError::UnknownName {
1296                name: "UNKNOWN".to_string(),
1297            }
1298        );
1299        assert_eq!(error.to_string(), "unknown tick scheme UNKNOWN");
1300    }
1301
1302    #[rstest]
1303    fn tick_scheme_fixed_precision_above_max_returns_unknown_name() {
1304        let name = format!("FIXED_PRECISION_{}", FIXED_PRECISION + 1);
1305        let error = TickScheme::from_str(&name).unwrap_err();
1306
1307        assert_eq!(error, TickSchemeError::UnknownName { name: name.clone() });
1308        assert_eq!(error.to_string(), format!("unknown tick scheme {name}"));
1309    }
1310
1311    #[rstest]
1312    fn fixed_tick_zero() {
1313        let error = FixedTickScheme::new(Price::from("0.0")).unwrap_err();
1314
1315        assert_eq!(
1316            error,
1317            TickSchemeError::TickNotPositive {
1318                tick: Price::from("0.0")
1319            }
1320        );
1321        assert_eq!(error.to_string(), "tick must be positive");
1322    }
1323
1324    #[rstest]
1325    fn fixed_tick_rejects_fractional_digits_beyond_precision() {
1326        let tick = Price {
1327            raw: 1,
1328            precision: 2,
1329        };
1330
1331        assert_eq!(
1332            FixedTickScheme::new(tick),
1333            Err(TickSchemeError::TickNotRepresentable { tick, precision: 2 })
1334        );
1335    }
1336
1337    #[rstest]
1338    fn fixed_tick_rejects_invalid_input_precision() {
1339        let precision = FIXED_PRECISION + 1;
1340        let mut tick = Price::from("1");
1341        tick.precision = precision;
1342        let source =
1343            check_in_range_inclusive_u8(precision, 0, FIXED_PRECISION, "precision").unwrap_err();
1344
1345        assert_eq!(
1346            FixedTickScheme::new(tick),
1347            Err(TickSchemeError::InvalidPrecision { source })
1348        );
1349    }
1350
1351    #[rstest]
1352    #[case(0)]
1353    #[case(1)]
1354    #[case(FIXED_PRECISION + 1)]
1355    fn fixed_tick_rejects_output_precision_that_cannot_represent_tick(#[case] precision: u8) {
1356        let scheme = FixedTickScheme::new(Price::from("0.25")).unwrap();
1357
1358        assert_eq!(scheme.next_bid_price(1.63, 0, precision), None);
1359        assert_eq!(scheme.next_ask_price(1.63, 0, precision), None);
1360    }
1361
1362    #[rstest]
1363    fn fixed_tick_accepts_lower_output_precision_when_tick_is_representable() {
1364        let scheme = FixedTickScheme::new(Price::from("0.250")).unwrap();
1365        let rescaled = FixedTickScheme::new_with_precision(scheme.tick(), 2).unwrap();
1366
1367        assert_eq!(rescaled.tick(), Price::from("0.25"));
1368        assert_eq!(rescaled.precision(), 2);
1369        assert_eq!(scheme.next_bid_price(1.63, 0, 2), Some(Price::from("1.50")));
1370        assert_eq!(scheme.next_ask_price(1.63, 0, 2), Some(Price::from("1.75")));
1371    }
1372
1373    #[rstest]
1374    fn fixed_tick_preserves_digits_beyond_float_accuracy() {
1375        let tick = Price::from("9000000000.000000001");
1376        let scheme = FixedTickScheme::new(tick).unwrap();
1377
1378        assert_eq!(scheme.tick().raw, tick.raw);
1379        assert_eq!(scheme.precision(), 9);
1380        assert_eq!(scheme.next_ask_price(0.0, 1, 9), Some(tick));
1381        assert_eq!(scheme.next_bid_price(0.0, 1, 9), Some(-tick));
1382    }
1383
1384    #[rstest]
1385    fn fixed_tick_steps_at_max_precision() {
1386        let scheme = FixedTickScheme::new(Price::from_raw(1, FIXED_PRECISION)).unwrap();
1387
1388        assert_eq!(
1389            scheme.next_ask_price(0.0, 2, FIXED_PRECISION),
1390            Some(Price::from_raw(2, FIXED_PRECISION))
1391        );
1392        assert_eq!(
1393            scheme.next_bid_price(0.0, 2, FIXED_PRECISION),
1394            Some(Price::from_raw(-2, FIXED_PRECISION))
1395        );
1396    }
1397
1398    #[rstest]
1399    fn fixed_tick_scheme_nan_value_returns_none() {
1400        let scheme = FixedTickScheme::new(Price::from("1.0")).unwrap();
1401        assert!(scheme.next_bid_price(f64::NAN, 0, 2).is_none());
1402        assert!(scheme.next_ask_price(f64::NAN, 0, 2).is_none());
1403    }
1404
1405    #[rstest]
1406    fn fixed_tick_scheme_out_of_range_returns_none() {
1407        // Stepping one tick above PRICE_MAX must yield None rather than panicking
1408        let scheme = FixedTickScheme::new(Price::from_raw(PRICE_RAW_MAX, 0)).unwrap();
1409        assert!(scheme.next_ask_price(PRICE_MAX, 1, 2).is_none());
1410    }
1411
1412    #[rstest]
1413    fn tiered_tick_scheme_topix100_construction() {
1414        let scheme = TieredTickScheme::topix100();
1415        assert!(scheme.tick_count() > 0);
1416        assert_eq!(scheme.precision(), 4);
1417        assert_eq!(scheme.min_price(), Price::new(0.1, 4));
1418    }
1419
1420    #[rstest]
1421    fn tiered_tick_scheme_betfair_construction() {
1422        let scheme = TieredTickScheme::betfair();
1423        assert_eq!(scheme.tick_count(), 350);
1424        assert_eq!(scheme.precision(), 2);
1425        assert_eq!(scheme.min_price(), Price::new(1.01, 2));
1426        assert_eq!(scheme.max_price(), Price::new(1000.0, 2));
1427    }
1428
1429    #[rstest]
1430    fn tiered_tick_scheme_ask_at_low_price() {
1431        let scheme = TieredTickScheme::topix100();
1432        let ask = scheme.next_ask_price(500.0, 0, 4).unwrap();
1433        assert_eq!(ask, Price::new(500.0, 4));
1434    }
1435
1436    #[rstest]
1437    fn tiered_tick_scheme_bid_at_low_price() {
1438        let scheme = TieredTickScheme::topix100();
1439        let bid = scheme.next_bid_price(500.0, 0, 4).unwrap();
1440        assert_eq!(bid, Price::new(500.0, 4));
1441    }
1442
1443    #[rstest]
1444    fn tiered_tick_scheme_ask_steps() {
1445        let scheme = TieredTickScheme::topix100();
1446        let ask0 = scheme.next_ask_price(500.0, 0, 4).unwrap();
1447        let ask1 = scheme.next_ask_price(500.0, 1, 4).unwrap();
1448        assert!(ask1 > ask0);
1449        assert_eq!(ask1, Price::new(500.1, 4));
1450    }
1451
1452    #[rstest]
1453    fn tiered_tick_scheme_bid_steps() {
1454        let scheme = TieredTickScheme::topix100();
1455        let bid0 = scheme.next_bid_price(500.0, 0, 4).unwrap();
1456        let bid1 = scheme.next_bid_price(500.0, 1, 4).unwrap();
1457        assert!(bid1 < bid0);
1458        assert_eq!(bid1, Price::new(499.9, 4));
1459    }
1460
1461    #[rstest]
1462    fn tiered_tick_scheme_tier_boundary_1000() {
1463        let scheme = TieredTickScheme::topix100();
1464        // At 1000.0 we cross from 0.1 step to 0.5 step
1465        let ask = scheme.next_ask_price(1000.0, 1, 4).unwrap();
1466        assert_eq!(ask, Price::new(1000.5, 4));
1467    }
1468
1469    #[rstest]
1470    #[case(3.90, 1, "3.95")]
1471    #[case(4.0, 1, "4.10")]
1472    fn tiered_tick_scheme_betfair_ask_transition(
1473        #[case] value: f64,
1474        #[case] n: i32,
1475        #[case] expected: &str,
1476    ) {
1477        let scheme = TieredTickScheme::betfair();
1478        let ask = scheme.next_ask_price(value, n, 2).unwrap();
1479        assert_eq!(ask, Price::from(expected));
1480    }
1481
1482    #[rstest]
1483    #[case(1.499, 0, "1.49")]
1484    #[case(2.011, 0, "2.00")]
1485    #[case(2.027, 2, "1.99")]
1486    fn tiered_tick_scheme_betfair_bid_transition(
1487        #[case] value: f64,
1488        #[case] n: i32,
1489        #[case] expected: &str,
1490    ) {
1491        let scheme = TieredTickScheme::betfair();
1492        let bid = scheme.next_bid_price(value, n, 2).unwrap();
1493        assert_eq!(bid, Price::from(expected));
1494    }
1495
1496    #[rstest]
1497    fn tiered_tick_scheme_between_ticks() {
1498        let scheme = TieredTickScheme::topix100();
1499        // 1000.3 is between ticks in the 0.5-step tier (1000.0, 1000.5)
1500        let ask = scheme.next_ask_price(1000.3, 0, 4).unwrap();
1501        assert!(ask.as_f64() >= 1000.3);
1502        let bid = scheme.next_bid_price(1000.3, 0, 4).unwrap();
1503        assert!(bid.as_f64() <= 1000.3);
1504    }
1505
1506    #[rstest]
1507    fn tiered_tick_scheme_off_grid_bid_below_tick() {
1508        // 1.049 is below the 1.05 tick; bid should be 1.00, not 1.05
1509        let scheme = TieredTickScheme::new(&[(1.0, 2.0, 0.05)], 2, 100).unwrap();
1510        let bid = scheme.next_bid_price(1.049, 0, 2).unwrap();
1511        assert_eq!(bid, Price::new(1.0, 2));
1512    }
1513
1514    #[rstest]
1515    fn tiered_tick_scheme_off_grid_ask_above_tick() {
1516        // 1.051 is above the 1.05 tick; ask should be 1.10, not 1.05
1517        let scheme = TieredTickScheme::new(&[(1.0, 2.0, 0.05)], 2, 100).unwrap();
1518        let ask = scheme.next_ask_price(1.051, 0, 2).unwrap();
1519        assert_eq!(ask, Price::new(1.10, 2));
1520    }
1521
1522    #[rstest]
1523    fn tiered_tick_scheme_bid_below_min_returns_none() {
1524        let scheme = TieredTickScheme::topix100();
1525        assert!(scheme.next_bid_price(0.05, 0, 4).is_none());
1526    }
1527
1528    #[rstest]
1529    fn tiered_tick_scheme_ask_beyond_last_tick_returns_none() {
1530        let scheme = TieredTickScheme::topix100();
1531        let last = scheme.max_price().as_f64();
1532        assert!(scheme.next_ask_price(last, 1, 4).is_none());
1533    }
1534
1535    #[rstest]
1536    fn tiered_tick_scheme_bid_beyond_last_tick_returns_last() {
1537        let scheme = TieredTickScheme::new(&[(1.0, 10.0, 1.0)], 1, 100).unwrap();
1538        // 9.5 is beyond last tick (9.0) but bid should be 9.0
1539        let bid = scheme.next_bid_price(9.5, 0, 1).unwrap();
1540        assert_eq!(bid, Price::new(9.0, 1));
1541    }
1542
1543    #[rstest]
1544    fn tiered_tick_scheme_negative_n_returns_none() {
1545        let scheme = TieredTickScheme::topix100();
1546        assert!(scheme.next_bid_price(500.0, -1, 4).is_none());
1547        assert!(scheme.next_ask_price(500.0, -1, 4).is_none());
1548    }
1549
1550    #[rstest]
1551    fn tiered_tick_scheme_nan_value_returns_none() {
1552        let scheme = TieredTickScheme::topix100();
1553        assert!(scheme.next_bid_price(f64::NAN, 0, 4).is_none());
1554        assert!(scheme.next_ask_price(f64::NAN, 0, 4).is_none());
1555    }
1556
1557    #[rstest]
1558    fn tiered_tick_scheme_infinite_value_saturates() {
1559        let scheme = TieredTickScheme::topix100();
1560        assert_eq!(
1561            scheme.next_bid_price(f64::INFINITY, 0, 4),
1562            Some(scheme.max_price())
1563        );
1564        assert!(scheme.next_ask_price(f64::INFINITY, 0, 4).is_none());
1565        assert!(scheme.next_bid_price(f64::NEG_INFINITY, 0, 4).is_none());
1566    }
1567
1568    #[rstest]
1569    fn crypto_tick_scheme_out_of_range_returns_none() {
1570        // Values beyond the Price range must yield None rather than panicking
1571        let scheme = TickScheme::Crypto;
1572        assert!(scheme.next_ask_price(PRICE_MAX * 2.0, 0, 2).is_none());
1573        assert!(scheme.next_bid_price(PRICE_MIN * 2.0, 0, 2).is_none());
1574    }
1575
1576    #[rstest]
1577    fn tiered_tick_scheme_validation_empty_tiers() {
1578        let error = TieredTickScheme::new(&[], 2, 100).unwrap_err();
1579
1580        assert_eq!(error, TickSchemeError::EmptyTiers);
1581        assert_eq!(error.to_string(), "tiers must not be empty");
1582    }
1583
1584    #[rstest]
1585    #[case(
1586        vec![(100.0, 50.0, 1.0)],
1587        TickSchemeError::TierStartNotLessThanStop {
1588            index: 0,
1589            start: 100.0,
1590            stop: 50.0,
1591        },
1592        "tier 0: start (100) must be less than stop (50)"
1593    )]
1594    #[case(
1595        vec![(2.0, 2.0, 0.1)],
1596        TickSchemeError::TierStartNotLessThanStop {
1597            index: 0,
1598            start: 2.0,
1599            stop: 2.0,
1600        },
1601        "tier 0: start (2) must be less than stop (2)"
1602    )]
1603    #[case(
1604        vec![(0.0, 100.0, -1.0)],
1605        TickSchemeError::TierStepNotPositive {
1606            index: 0,
1607            step: -1.0,
1608        },
1609        "tier 0: step (-1) must be positive"
1610    )]
1611    #[case(
1612        vec![(1.0, 2.0, 0.0)],
1613        TickSchemeError::TierStepNotPositive {
1614            index: 0,
1615            step: 0.0,
1616        },
1617        "tier 0: step (0) must be positive"
1618    )]
1619    #[case(
1620        vec![(0.0, 100.0, 200.0)],
1621        TickSchemeError::TierStepNotLessThanRange {
1622            index: 0,
1623            start: 0.0,
1624            stop: 100.0,
1625            step: 200.0,
1626            range: 100.0,
1627        },
1628        "tier 0: step (200) must be less than range (100 - 0 = 100)"
1629    )]
1630    #[case(
1631        vec![(10.0, 20.0, 1.0), (1.0, 10.0, 1.0)],
1632        TickSchemeError::TierOverlapsPrevious {
1633            index: 1,
1634            start: 1.0,
1635            prev_stop: 20.0,
1636        },
1637        "tier 1: start (1) overlaps previous tier stop (20)"
1638    )]
1639    #[case(
1640        vec![(1.0, 10.0, 1.0), (5.0, 15.0, 1.0)],
1641        TickSchemeError::TierOverlapsPrevious {
1642            index: 1,
1643            start: 5.0,
1644            prev_stop: 10.0,
1645        },
1646        "tier 1: start (5) overlaps previous tier stop (10)"
1647    )]
1648    fn tiered_tick_scheme_invalid_tiers_return_typed_errors(
1649        #[case] tiers: Vec<(f64, f64, f64)>,
1650        #[case] expected_error: TickSchemeError,
1651        #[case] expected_display: &str,
1652    ) {
1653        let error = TieredTickScheme::new(&tiers, 2, 100).unwrap_err();
1654
1655        assert_eq!(error, expected_error);
1656        assert_eq!(error.to_string(), expected_display);
1657    }
1658
1659    #[rstest]
1660    #[case(vec![(f64::NAN, 10.0, 1.0)])]
1661    #[case(vec![(1.0, f64::NAN, 1.0)])]
1662    #[case(vec![(1.0, 10.0, f64::NAN)])]
1663    fn tiered_tick_scheme_nan_tiers_return_typed_error(#[case] tiers: Vec<(f64, f64, f64)>) {
1664        let error = TieredTickScheme::new(&tiers, 2, 100).unwrap_err();
1665
1666        match &error {
1667            TickSchemeError::TierValuesNaN {
1668                index,
1669                start,
1670                stop,
1671                step,
1672            } => {
1673                assert_eq!(*index, 0);
1674                assert!(
1675                    start.is_nan() || stop.is_nan() || step.is_nan(),
1676                    "expected one NaN tier value in {error:?}",
1677                );
1678            }
1679            _ => panic!("unexpected error variant: {error:?}"),
1680        }
1681        assert_eq!(error.to_string(), "tier 0: values must not be NaN");
1682    }
1683
1684    #[rstest]
1685    fn tiered_tick_scheme_start_outside_price_range_returns_typed_error() {
1686        let start = PRICE_MIN - 1.0;
1687        let stop = PRICE_MIN + 1.0;
1688        let error = TieredTickScheme::new(&[(start, stop, 1.0)], 2, 100).unwrap_err();
1689
1690        assert_eq!(
1691            error,
1692            TickSchemeError::TierStartOutsidePriceRange { index: 0, start }
1693        );
1694        assert_eq!(
1695            error.to_string(),
1696            format!("tier 0: start ({start}) outside Price range")
1697        );
1698    }
1699
1700    #[rstest]
1701    fn tiered_tick_scheme_stop_outside_price_range_returns_typed_error() {
1702        let start = PRICE_MAX - 2.0;
1703        let stop = PRICE_MAX + 1.0;
1704        let error = TieredTickScheme::new(&[(start, stop, 1.0)], 2, 100).unwrap_err();
1705
1706        assert_eq!(
1707            error,
1708            TickSchemeError::TierStopOutsidePriceRange { index: 0, stop }
1709        );
1710        assert_eq!(
1711            error.to_string(),
1712            format!("tier 0: stop ({stop}) outside Price range")
1713        );
1714    }
1715
1716    #[rstest]
1717    fn tiered_tick_scheme_invalid_precision_wraps_source_error() {
1718        let invalid_precision = FIXED_PRECISION + 1;
1719        let source = Price::new_checked(0.0, invalid_precision).unwrap_err();
1720        let error = TieredTickScheme::new(&[(1.0, 10.0, 1.0)], invalid_precision, 100).unwrap_err();
1721
1722        assert_eq!(
1723            error,
1724            TickSchemeError::InvalidPrecision {
1725                source: source.clone(),
1726            }
1727        );
1728        assert_eq!(error.to_string(), source.to_string());
1729    }
1730
1731    #[rstest]
1732    fn tiered_tick_scheme_empty_expansion_returns_typed_error() {
1733        let error = TieredTickScheme::new(&[(1.0, f64::INFINITY, 1.0)], 2, 0).unwrap_err();
1734
1735        assert_eq!(error, TickSchemeError::EmptyTickExpansion);
1736        assert_eq!(error.to_string(), "tier expansion produced no ticks");
1737    }
1738
1739    #[rstest]
1740    fn tiered_tick_scheme_expanded_tick_outside_range_returns_typed_error() {
1741        let invalid_value = PRICE_MAX + 1.0;
1742        let error = TieredTickScheme::new(&[(PRICE_MAX, f64::INFINITY, 1.0)], 2, 2).unwrap_err();
1743
1744        assert_eq!(
1745            error,
1746            TickSchemeError::ExpandedTickOutsidePriceRange {
1747                value: invalid_value,
1748            }
1749        );
1750        assert_eq!(
1751            error.to_string(),
1752            format!("expanded tick value {invalid_value} outside Price range")
1753        );
1754    }
1755
1756    #[rstest]
1757    fn tiered_tick_scheme_finite_tier_includes_all_ticks() {
1758        // (0.0, 0.3, 0.1) should produce 0.0, 0.1, 0.2 (3 ticks, not 2)
1759        let scheme = TieredTickScheme::new(&[(0.0, 0.3, 0.1)], 1, 100).unwrap();
1760        assert_eq!(scheme.tick_count(), 3);
1761    }
1762
1763    #[rstest]
1764    fn tiered_tick_scheme_simple_two_tiers() {
1765        let scheme =
1766            TieredTickScheme::new(&[(1.0, 10.0, 1.0), (10.0, 100.0, 5.0)], 2, 100).unwrap();
1767        let ticks = scheme.ticks();
1768        // First tier: 1, 2, 3, ..., 9
1769        // Second tier: 10, 15, 20, ..., 95
1770        assert_eq!(ticks[0], Price::new(1.0, 2));
1771        assert_eq!(ticks[8], Price::new(9.0, 2));
1772        assert_eq!(ticks[9], Price::new(10.0, 2));
1773        assert_eq!(ticks[10], Price::new(15.0, 2));
1774    }
1775
1776    #[rstest]
1777    fn tiered_tick_scheme_infinity_tier() {
1778        let scheme = TieredTickScheme::new(&[(100.0, f64::INFINITY, 10.0)], 1, 5).unwrap();
1779        assert_eq!(scheme.tick_count(), 5);
1780        let ticks = scheme.ticks();
1781        assert_eq!(ticks[0], Price::new(100.0, 1));
1782        assert_eq!(ticks[4], Price::new(140.0, 1));
1783    }
1784
1785    #[rstest]
1786    fn tiered_tick_scheme_from_str_topix100() {
1787        let scheme = TickScheme::from_str("TOPIX100").unwrap();
1788        assert_eq!(scheme.to_string(), "TIERED");
1789    }
1790
1791    #[rstest]
1792    fn tiered_tick_scheme_from_str_betfair() {
1793        let scheme = TickScheme::from_str("BETFAIR").unwrap();
1794        assert_eq!(scheme.to_string(), BETFAIR_TICK_SCHEME_NAME);
1795        assert_eq!(
1796            scheme.next_ask_price(4.0, 1, 2).unwrap(),
1797            Price::new(4.1, 2)
1798        );
1799    }
1800
1801    #[rstest]
1802    fn tiered_tick_scheme_display() {
1803        let scheme = TieredTickScheme::new(&[(1.0, 10.0, 1.0)], 2, 100).unwrap();
1804        assert_eq!(scheme.to_string(), "TIERED");
1805    }
1806
1807    #[rstest]
1808    fn tiered_tick_scheme_min_tick_bid() {
1809        let scheme = TieredTickScheme::topix100();
1810        let result = scheme.next_bid_price(0.1, 0, 4).unwrap();
1811        assert_eq!(result, Price::new(0.1, 4));
1812    }
1813
1814    #[rstest]
1815    fn tiered_tick_scheme_min_tick_bid_n1_returns_none() {
1816        let scheme = TieredTickScheme::topix100();
1817        assert!(scheme.next_bid_price(0.1, 1, 4).is_none());
1818    }
1819
1820    #[rstest]
1821    fn tiered_tick_scheme_boundary_tick_equality() {
1822        let scheme = TieredTickScheme::topix100();
1823        let bid = scheme.next_bid_price(1000.0, 0, 4).unwrap();
1824        assert_eq!(bid, Price::new(1000.0, 4));
1825        let ask = scheme.next_ask_price(1000.0, 0, 4).unwrap();
1826        assert_eq!(ask, Price::new(1000.0, 4));
1827    }
1828
1829    #[rstest]
1830    fn tiered_tick_scheme_tier_transition_ask_from_999_9() {
1831        let scheme = TieredTickScheme::topix100();
1832        let ask = scheme.next_ask_price(999.9, 0, 4).unwrap();
1833        assert_eq!(ask, Price::new(999.9, 4));
1834    }
1835
1836    #[rstest]
1837    fn tiered_tick_scheme_tier_transition_bid_from_1000_5() {
1838        let scheme = TieredTickScheme::topix100();
1839        let bid = scheme.next_bid_price(1000.5, 1, 4).unwrap();
1840        assert_eq!(bid, Price::new(1000.0, 4));
1841    }
1842
1843    #[rstest]
1844    fn tiered_tick_scheme_large_n_beyond_bounds_ask() {
1845        let scheme = TieredTickScheme::topix100();
1846        let max = scheme.max_price().as_f64();
1847        assert!(scheme.next_ask_price(max - 1000.0, 100_000, 4).is_none());
1848    }
1849
1850    #[rstest]
1851    fn tiered_tick_scheme_large_n_beyond_bounds_bid() {
1852        let scheme = TieredTickScheme::topix100();
1853        let min = scheme.min_price().as_f64();
1854        assert!(scheme.next_bid_price(min + 1000.0, 100_000, 4).is_none());
1855    }
1856
1857    #[rstest]
1858    fn tiered_tick_scheme_out_of_bounds_ask_far_above() {
1859        let scheme = TieredTickScheme::topix100();
1860        assert!(scheme.next_ask_price(999_999_999.0, 0, 4).is_none());
1861    }
1862
1863    #[rstest]
1864    fn tiered_tick_scheme_idempotent_on_tick() {
1865        let scheme = TieredTickScheme::topix100();
1866        let price = 500.0;
1867        let ask = scheme.next_ask_price(price, 0, 4).unwrap();
1868        let ask2 = scheme.next_ask_price(ask.as_f64(), 0, 4).unwrap();
1869        assert_eq!(ask, ask2);
1870        let bid = scheme.next_bid_price(price, 0, 4).unwrap();
1871        let bid2 = scheme.next_bid_price(bid.as_f64(), 0, 4).unwrap();
1872        assert_eq!(bid, bid2);
1873    }
1874
1875    #[rstest]
1876    fn tiered_tick_scheme_consistency_forward_backward() {
1877        let scheme = TieredTickScheme::topix100();
1878        let start = 5000.0;
1879        let forward = scheme.next_ask_price(start, 10, 4).unwrap();
1880        let back = scheme.next_bid_price(forward.as_f64(), 10, 4).unwrap();
1881        assert!(back.as_f64() <= start);
1882    }
1883
1884    #[rstest]
1885    fn tiered_tick_scheme_cumulative_equals_direct() {
1886        let scheme = TieredTickScheme::topix100();
1887        let price = 1000.0;
1888        let mut cumulative = price;
1889        for _ in 0..5 {
1890            if let Some(result) = scheme.next_ask_price(cumulative, 1, 4) {
1891                cumulative = result.as_f64();
1892            }
1893        }
1894        let direct = scheme.next_ask_price(price, 5, 4).unwrap();
1895        assert!((cumulative - direct.as_f64()).abs() < 1e-10);
1896    }
1897
1898    #[rstest]
1899    #[case(1000.0, 0, 1000.0)]
1900    #[case(1000.25, 0, 1000.5)]
1901    #[case(10_001.0, 0, 10_005.0)]
1902    #[case(10_000_001.0, 0, 10_005_000.0)]
1903    #[case(9999.0, 2, 10_005.0)]
1904    fn tiered_tick_scheme_topix100_ask_parametrized(
1905        #[case] value: f64,
1906        #[case] n: i32,
1907        #[case] expected: f64,
1908    ) {
1909        let scheme = TieredTickScheme::topix100();
1910        let ask = scheme.next_ask_price(value, n, 4).unwrap();
1911        assert_eq!(ask, Price::new(expected, 4));
1912    }
1913
1914    #[rstest]
1915    #[case(1000.75, 0, 1000.5)]
1916    #[case(10_007.0, 0, 10_005.0)]
1917    #[case(10_000_001.0, 0, 10_000_000.0)]
1918    #[case(10_006.0, 2, 9999.0)]
1919    fn tiered_tick_scheme_topix100_bid_parametrized(
1920        #[case] value: f64,
1921        #[case] n: i32,
1922        #[case] expected: f64,
1923    ) {
1924        let scheme = TieredTickScheme::topix100();
1925        let bid = scheme.next_bid_price(value, n, 4).unwrap();
1926        assert_eq!(bid, Price::new(expected, 4));
1927    }
1928
1929    // Property: bid(value, 0) <= value for any value in range
1930    proptest! {
1931        #[rstest]
1932        fn prop_tiered_bid_at_or_below_value(value in 0.1f64..100_000.0) {
1933            let scheme = TieredTickScheme::topix100();
1934            if let Some(bid) = scheme.next_bid_price(value, 0, 4) {
1935                prop_assert!(bid.as_f64() <= value + 1e-9);
1936            }
1937        }
1938    }
1939
1940    // Property: ask(value, 0) >= value for any value in range
1941    proptest! {
1942        #[rstest]
1943        fn prop_tiered_ask_at_or_above_value(value in 0.1f64..100_000.0) {
1944            let scheme = TieredTickScheme::topix100();
1945            if let Some(ask) = scheme.next_ask_price(value, 0, 4) {
1946                prop_assert!(ask.as_f64() >= value - 1e-9);
1947            }
1948        }
1949    }
1950
1951    proptest! {
1952        #[rstest]
1953        fn prop_tiered_bid_ask_match_adjacent_ticks(
1954            raw_index in any::<usize>(),
1955            offset in 0usize..=4,
1956        ) {
1957            let scheme = TieredTickScheme::topix100();
1958            let ticks = scheme.ticks();
1959            let index = raw_index % (ticks.len() - 1);
1960            let lower = ticks[index];
1961            let upper = ticks[index + 1];
1962            let value = f64::midpoint(lower.as_f64(), upper.as_f64());
1963            let steps = i32::try_from(offset).unwrap();
1964
1965            let expected_bid = index
1966                .checked_sub(offset)
1967                .map(|target| ticks[target]);
1968            let expected_ask = index
1969                .checked_add(offset + 1)
1970                .filter(|target| *target < ticks.len())
1971                .map(|target| ticks[target]);
1972
1973            prop_assert_eq!(scheme.next_bid_price(value, steps, 4), expected_bid);
1974            prop_assert_eq!(scheme.next_ask_price(value, steps, 4), expected_ask);
1975        }
1976    }
1977
1978    // Property: ask(value, n) is monotonically increasing in n
1979    proptest! {
1980        #[rstest]
1981        fn prop_tiered_ask_monotonic_in_n(value in 1.0f64..10_000.0) {
1982            let scheme = TieredTickScheme::topix100();
1983            let mut prev: Option<Price> = None;
1984
1985            for n in 0..5 {
1986                if let Some(ask) = scheme.next_ask_price(value, n, 4) {
1987                    if let Some(p) = prev {
1988                        prop_assert!(ask >= p);
1989                    }
1990                    prev = Some(ask);
1991                }
1992            }
1993        }
1994    }
1995
1996    // Property: ticks are strictly sorted
1997    proptest! {
1998        #[rstest]
1999        fn prop_tiered_ticks_sorted(
2000            start in 1.0f64..100.0,
2001            step in 0.01f64..10.0,
2002        ) {
2003            let stop = start + step * 10.0;
2004            if let Ok(scheme) = TieredTickScheme::new(&[(start, stop, step)], 2, 100) {
2005                let ticks = scheme.ticks();
2006                for i in 1..ticks.len() {
2007                    prop_assert!(ticks[i] > ticks[i - 1]);
2008                }
2009            }
2010        }
2011    }
2012}