Skip to main content

nautilus_model/orderbook/
ladder.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//! Represents a ladder of price levels for one side of an order book.
17
18use std::{
19    cmp::Ordering,
20    collections::{BTreeMap, HashMap},
21    fmt::{Debug, Display},
22};
23
24use nautilus_core::{
25    UnixNanos,
26    correctness::{CorrectnessError, CorrectnessResult},
27};
28
29use crate::{
30    data::order::{BookOrder, OrderId},
31    enums::{BookType, OrderSide, RecordFlag},
32    orderbook::BookLevel,
33    types::{Price, Quantity},
34};
35
36/// Represents a price level with a specified side in an order books ladder.
37///
38/// # Comparison Semantics
39///
40/// `BookPrice` instances are only meaningfully compared within the same side
41/// (i.e., within a single `BookLadder`). Cross-side comparisons are not expected
42/// in normal use, as bid and ask ladders maintain separate `BTreeMap<BookPrice, BookLevel>`
43/// collections.
44///
45/// - Equality requires both `value` and `side` to match.
46/// - Ordering is side-dependent: Buy side sorts descending, Sell side ascending.
47#[derive(Clone, Copy, Debug, Eq)]
48#[cfg_attr(
49    feature = "python",
50    pyo3::pyclass(module = "nautilus_trader.model", from_py_object)
51)]
52pub struct BookPrice {
53    pub value: Price,
54    pub side: OrderSide,
55}
56
57impl BookPrice {
58    /// Creates a new [`BookPrice`] instance.
59    #[must_use]
60    pub fn new(value: Price, side: OrderSide) -> Self {
61        Self { value, side }
62    }
63}
64
65impl PartialOrd for BookPrice {
66    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
67        Some(self.cmp(other))
68    }
69}
70
71impl PartialEq for BookPrice {
72    fn eq(&self, other: &Self) -> bool {
73        self.side == other.side && self.value == other.value
74    }
75}
76
77impl Ord for BookPrice {
78    fn cmp(&self, other: &Self) -> Ordering {
79        assert_eq!(
80            self.side, other.side,
81            "BookPrice compared across sides: {:?} vs {:?}",
82            self.side, other.side
83        );
84
85        match self.side {
86            OrderSide::Buy => other.value.cmp(&self.value),
87            OrderSide::Sell => self.value.cmp(&other.value),
88        }
89    }
90}
91
92impl Display for BookPrice {
93    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
94        write!(f, "{}", self.value)
95    }
96}
97
98/// Tracks the type of L1 batch currently being accumulated.
99///
100/// Separating MBP and snapshot batches prevents cross-contamination where
101/// stale MBP data could pollute a new snapshot. Without this distinction,
102/// an incomplete MBP stream (missing `F_LAST`) would leave batch state that
103/// incorrectly affects subsequent snapshot processing.
104///
105/// The discriminants are serialized in `OrderBook` state and must remain stable.
106#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
107#[repr(u8)]
108enum L1BatchState {
109    /// Not in any batch.
110    #[default]
111    None = 0,
112    /// Accumulating an `F_MBP` batch (final two deltas accumulate).
113    MbpBatch = 1,
114    /// Accumulating an `F_SNAPSHOT` batch (all deltas accumulate).
115    SnapshotBatch = 2,
116}
117
118/// Represents a ladder of price levels for one side of an order book.
119#[derive(Clone, Debug)]
120pub(crate) struct BookLadder {
121    pub side: OrderSide,
122    pub book_type: BookType,
123    pub levels: BTreeMap<BookPrice, BookLevel>,
124    // The standard hasher measured faster than ahash for this map's steady-state
125    // clear-and-insert pattern; see the 2026-11-02 rejection record in
126    // `crates/backtest/benches/BENCHMARKS.md` before changing hashers.
127    pub cache: HashMap<u64, BookPrice>,
128    batch_state: L1BatchState,
129}
130
131impl BookLadder {
132    /// Creates a new [`Ladder`] instance.
133    #[must_use]
134    pub(crate) fn new(side: OrderSide, book_type: BookType) -> Self {
135        Self {
136            side,
137            book_type,
138            levels: BTreeMap::new(),
139            cache: HashMap::new(),
140            batch_state: L1BatchState::None,
141        }
142    }
143
144    /// Returns the number of price levels in the ladder.
145    #[must_use]
146    pub(crate) fn len(&self) -> usize {
147        self.levels.len()
148    }
149
150    /// Returns true if the ladder has no price levels.
151    #[must_use]
152    #[allow(dead_code)]
153    pub(crate) fn is_empty(&self) -> bool {
154        self.levels.is_empty()
155    }
156
157    #[must_use]
158    pub(crate) fn batch_state_code(&self) -> u8 {
159        self.batch_state as u8
160    }
161
162    /// Restores the state of an unfinished L1 batch.
163    ///
164    /// # Errors
165    ///
166    /// Returns an error if the state code is unknown or a batch state appears on a non-L1 ladder.
167    pub(crate) fn set_batch_state_code(&mut self, code: u8) -> CorrectnessResult<()> {
168        let batch_state = match code {
169            0 => L1BatchState::None,
170            1 => L1BatchState::MbpBatch,
171            2 => L1BatchState::SnapshotBatch,
172            _ => {
173                return Err(CorrectnessError::PredicateViolation {
174                    message: format!("Invalid L1 batch state code: {code}"),
175                });
176            }
177        };
178
179        if self.book_type != BookType::L1_MBP && batch_state != L1BatchState::None {
180            return Err(CorrectnessError::PredicateViolation {
181                message: format!(
182                    "Cannot restore L1 batch state for book type {:?}",
183                    self.book_type
184                ),
185            });
186        }
187
188        self.batch_state = batch_state;
189        Ok(())
190    }
191
192    /// Removes all orders and price levels from the ladder.
193    ///
194    /// Also resets the batch state to ensure clean handling of subsequent batches.
195    pub(crate) fn clear(&mut self) {
196        self.levels.clear();
197        self.cache.clear();
198        self.batch_state = L1BatchState::None;
199    }
200
201    pub(crate) fn replace_l1(&mut self, order: BookOrder) {
202        debug_assert_eq!(self.book_type, BookType::L1_MBP);
203
204        let reusable_level = self.levels.pop_first().map(|(_, level)| level);
205        self.clear();
206
207        if !order.size.is_positive() {
208            let side = self.side;
209            log::debug!("L1 zero-size add cleared ladder: side={side:?}");
210            return;
211        }
212
213        let book_price = order.to_book_price();
214        self.cache.insert(order.order_id, book_price);
215
216        if let Some(mut level) = reusable_level {
217            level.price = book_price;
218
219            // Same order ID replaces the value without rehashing, as L1 quote and trade
220            // ticks reuse side-constant IDs so this hits on every steady-state tick.
221            let same_id = level.orders.len() == 1
222                && level
223                    .orders
224                    .get_index(0)
225                    .is_some_and(|(id, _)| *id == order.order_id);
226
227            if same_id {
228                let (_, existing) = level
229                    .orders
230                    .get_index_mut(0)
231                    .expect("single L1 order exists");
232                *existing = order;
233            } else {
234                level.orders.clear();
235                level.add(order);
236            }
237
238            self.levels.insert(book_price, level);
239        } else {
240            self.levels.insert(book_price, BookLevel::from_order(order));
241        }
242    }
243
244    /// Adds an order to the ladder at its price level.
245    ///
246    /// For `L2_MBP` and `L3_MBO` books, an order ID lives at exactly one price
247    /// level within a ladder: re-adding an ID at a different price moves the
248    /// order to the new level's FIFO tail. This is a no-op for `L2_MBP`, whose
249    /// IDs are price hashes, and covers `L3_MBO` venue IDs as well as `F_TOB`
250    /// side-constant IDs.
251    ///
252    /// `L1_MBP` is exempt: batch accumulation must compare levels sharing the
253    /// side-constant ID before retaining only the best.
254    /// `L1_MBP` behavior depends on flags:
255    /// - `F_MBP` or `F_SNAPSHOT` (multi-level batch): Retains best after each add to prevent
256    ///   accumulation even if `F_LAST` is never sent.
257    /// - `F_TOB` or no batch flags (single replacement): Clears existing levels first,
258    ///   allowing price to degrade.
259    pub(crate) fn add(&mut self, order: BookOrder, flags: u8) {
260        if self.book_type == BookType::L1_MBP && !self.handle_l1_add(&order, flags) {
261            return;
262        }
263
264        if self.book_type != BookType::L1_MBP && !order.size.is_positive() {
265            log::warn!(
266                "Attempted to add order with non-positive size: order_id={}, size={}, ignoring",
267                order.order_id,
268                order.size,
269            );
270            return;
271        }
272
273        let book_price = order.to_book_price();
274
275        if self.book_type != BookType::L1_MBP
276            && let Some(existing_price) = self.cache.get(&order.order_id).copied()
277            && existing_price != book_price
278            && let Some(existing_level) = self.levels.get_mut(&existing_price)
279        {
280            existing_level.delete(&order);
281            if existing_level.is_empty() {
282                self.levels.remove(&existing_price);
283            }
284        }
285
286        self.cache.insert(order.order_id, book_price);
287
288        if let Some(level) = self.levels.get_mut(&book_price) {
289            level.add(order);
290        } else {
291            let level = BookLevel::from_order(order);
292            self.levels.insert(book_price, level);
293        }
294
295        // For L1_MBP with F_MBP or F_SNAPSHOT, always retain best to prevent unbounded
296        // accumulation if F_LAST is never sent
297        let is_batch = RecordFlag::F_MBP.matches(flags) || RecordFlag::F_SNAPSHOT.matches(flags);
298        if self.book_type == BookType::L1_MBP && is_batch {
299            self.retain_best_only();
300
301            if RecordFlag::F_LAST.matches(flags) {
302                self.batch_state = L1BatchState::None;
303            }
304        }
305    }
306
307    /// Handles L1_MBP-specific add logic.
308    ///
309    /// Returns `true` to continue with normal add flow, `false` to abort.
310    ///
311    /// Behavior depends on flags:
312    /// - `F_SNAPSHOT` with `F_LAST`: End of snapshot batch. If in snapshot batch, accumulate;
313    ///   otherwise clear (single-delta snapshot or cross-contamination from MBP).
314    /// - `F_SNAPSHOT` without `F_LAST`: Start/continue snapshot batch. Clears if not already
315    ///   in a snapshot batch (handles stale MBP data).
316    /// - `F_MBP` with `F_LAST`: End of MBP batch. If in MBP batch, accumulate final two;
317    ///   otherwise clear.
318    /// - `F_MBP` without `F_LAST`: Always clear (streaming mode, prevents stale prices).
319    /// - `F_TOB` or no batch flags: Single replacement (clears first).
320    ///
321    /// Zero-size orders clear the entire L1 ladder.
322    fn handle_l1_add(&mut self, order: &BookOrder, flags: u8) -> bool {
323        if !order.size.is_positive() {
324            self.clear();
325            let side = self.side;
326            log::debug!("L1 zero-size add cleared ladder: side={side:?}");
327            return false;
328        }
329
330        let is_mbp = RecordFlag::F_MBP.matches(flags);
331        let is_snapshot = RecordFlag::F_SNAPSHOT.matches(flags);
332        let is_last = RecordFlag::F_LAST.matches(flags);
333
334        if is_snapshot && is_last {
335            // F_SNAPSHOT|F_LAST: end of snapshot batch
336            // Only accumulate if we're in a snapshot batch; otherwise clear to prevent
337            // cross-contamination from stale MBP data
338            if self.batch_state != L1BatchState::SnapshotBatch {
339                self.clear();
340            }
341        } else if is_snapshot {
342            // F_SNAPSHOT without F_LAST: start/continue snapshot batch
343            if self.batch_state != L1BatchState::SnapshotBatch {
344                self.clear();
345                self.batch_state = L1BatchState::SnapshotBatch;
346            }
347        } else if is_mbp && is_last {
348            // F_MBP|F_LAST: end of MBP batch, accumulate if already in MBP batch
349            if self.batch_state != L1BatchState::MbpBatch {
350                self.clear();
351            }
352        } else if is_mbp {
353            // F_MBP without F_LAST: always clear (streaming mode)
354            self.clear();
355            self.batch_state = L1BatchState::MbpBatch;
356        } else {
357            // Non-batch: replacement mode
358            self.clear();
359        }
360
361        true
362    }
363
364    /// Updates an existing order in the ladder, moving it to a new price level if needed.
365    pub(crate) fn update(&mut self, order: BookOrder, flags: u8) {
366        let price = self.cache.get(&order.order_id).copied();
367        if let Some(price) = price
368            && let Some(level) = self.levels.get_mut(&price)
369        {
370            if order.price == level.price.value {
371                let level_len_before = level.len();
372                level.update(order);
373
374                // If level.update removed the order due to zero size, remove from cache too
375                if order.size.is_zero() {
376                    self.cache.remove(&order.order_id);
377                    debug_assert_eq!(
378                        level.len(),
379                        level_len_before - 1,
380                        "Level should have one less order after zero-size update"
381                    );
382                } else {
383                    debug_assert!(
384                        self.cache.contains_key(&order.order_id),
385                        "Cache should still contain order {0} after update",
386                        order.order_id
387                    );
388                }
389
390                if level.is_empty() {
391                    self.levels.remove(&price);
392                    debug_assert!(
393                        !self.cache.values().any(|p| *p == price),
394                        "Cache should not contain removed price level {price:?}"
395                    );
396                }
397
398                debug_assert_eq!(
399                    self.cache.len(),
400                    self.levels.values().map(BookLevel::len).sum::<usize>(),
401                    "Cache size should equal total orders across all levels"
402                );
403                return;
404            }
405
406            // Price update: delete and insert at new level
407            self.cache.remove(&order.order_id);
408            level.delete(&order);
409
410            if level.is_empty() {
411                self.levels.remove(&price);
412                debug_assert!(
413                    !self.cache.values().any(|p| *p == price),
414                    "Cache should not contain removed price level {price:?}"
415                );
416            }
417        }
418
419        // Only add if the order has positive size
420        if order.size.is_positive() {
421            self.add(order, flags);
422        }
423
424        // Validate cache consistency after update
425        debug_assert_eq!(
426            self.cache.len(),
427            self.levels.values().map(BookLevel::len).sum::<usize>(),
428            "Cache size should equal total orders across all levels"
429        );
430    }
431
432    /// Deletes an order from the ladder.
433    pub(crate) fn delete(&mut self, order: BookOrder, sequence: u64, ts_event: UnixNanos) {
434        self.remove_order(order.order_id, sequence, ts_event);
435    }
436
437    /// Removes an order by its ID from the ladder.
438    pub(crate) fn remove_order(&mut self, order_id: OrderId, sequence: u64, ts_event: UnixNanos) {
439        if let Some(price) = self.cache.get(&order_id).copied()
440            && let Some(level) = self.levels.get_mut(&price)
441        {
442            // Check if order exists in level before modifying cache
443            if level.orders.contains_key(&order_id) {
444                let level_len_before = level.len();
445
446                // Now safe to remove from cache since we know order exists in level
447                self.cache.remove(&order_id);
448                level.remove_by_id(order_id, sequence, ts_event);
449
450                debug_assert_eq!(
451                    level.len(),
452                    level_len_before - 1,
453                    "Level should have exactly one less order after removal"
454                );
455
456                if level.is_empty() {
457                    self.levels.remove(&price);
458                    debug_assert!(
459                        !self.cache.values().any(|p| *p == price),
460                        "Cache should not contain removed price level {price:?}"
461                    );
462                }
463            }
464        }
465
466        // Validate cache consistency after removal
467        debug_assert_eq!(
468            self.cache.len(),
469            self.levels.values().map(BookLevel::len).sum::<usize>(),
470            "Cache size should equal total orders across all levels"
471        );
472    }
473
474    /// Removes an entire price level from the ladder and returns it.
475    pub(crate) fn remove_level(&mut self, price: BookPrice) -> Option<BookLevel> {
476        if let Some(level) = self.levels.remove(&price) {
477            // Remove all orders in this level from the cache
478            for order_id in level.orders.keys() {
479                self.cache.remove(order_id);
480            }
481
482            debug_assert_eq!(
483                self.cache.len(),
484                self.levels.values().map(BookLevel::len).sum::<usize>(),
485                "Cache size should equal total orders across all levels"
486            );
487
488            Some(level)
489        } else {
490            None
491        }
492    }
493
494    /// Retains only the best price level, removing all others.
495    ///
496    /// For `L1_MBP` books, this ensures only the top-of-book level is kept after
497    /// processing multi-level data. The `BTreeMap` ordering ensures the first
498    /// entry is always the best price (highest for bids, lowest for asks).
499    fn retain_best_only(&mut self) {
500        if self.levels.len() <= 1 {
501            return;
502        }
503
504        let best_price = match self.levels.keys().next().copied() {
505            Some(price) => price,
506            None => return,
507        };
508
509        // Remove all levels except the best (don't use remove_level as it
510        // incorrectly handles cache for L1 where all orders share order_id)
511        self.levels.retain(|price, _| *price == best_price);
512
513        // Rebuild cache from remaining level (necessary for L1 where
514        // all orders use the same order_id and remove_level would corrupt cache)
515        self.cache.clear();
516
517        for (book_price, level) in &self.levels {
518            for order_id in level.orders.keys() {
519                self.cache.insert(*order_id, *book_price);
520            }
521        }
522
523        debug_assert!(
524            self.levels.len() <= 1,
525            "L1 ladder should have at most 1 level after retain_best_only"
526        );
527        debug_assert_eq!(
528            self.cache.len(),
529            self.levels.values().map(BookLevel::len).sum::<usize>(),
530            "Cache size should equal total orders across all levels"
531        );
532    }
533
534    /// Returns the total size of all orders in the ladder.
535    #[must_use]
536    #[allow(dead_code)]
537    pub(crate) fn sizes(&self) -> f64 {
538        self.levels.values().map(BookLevel::size).sum()
539    }
540
541    /// Returns the total value exposure (price * size) of all orders in the ladder.
542    #[must_use]
543    #[allow(dead_code)]
544    pub(crate) fn exposures(&self) -> f64 {
545        self.levels.values().map(BookLevel::exposure).sum()
546    }
547
548    /// Returns the best price level in the ladder.
549    #[must_use]
550    pub(crate) fn top(&self) -> Option<&BookLevel> {
551        self.levels.values().next()
552    }
553
554    /// Simulates fills for an order against this ladder's liquidity.
555    /// Returns a list of (price, size) tuples representing the simulated fills.
556    #[must_use]
557    pub(crate) fn simulate_fills(&self, order: &BookOrder) -> Vec<(Price, Quantity)> {
558        let is_reversed = self.side == OrderSide::Buy;
559        let mut fills = Vec::new();
560        let mut cumulative_denominator = Quantity::zero(order.size.precision);
561        let target = order.size;
562
563        for level in self.levels.values() {
564            if (is_reversed && level.price.value < order.price)
565                || (!is_reversed && level.price.value > order.price)
566            {
567                break;
568            }
569
570            for book_order in level.orders.values() {
571                let current = book_order.size;
572                let remainder = target - cumulative_denominator;
573                if current >= remainder {
574                    // This order has filled us, add fill and return
575                    if remainder.is_positive() {
576                        fills.push((book_order.price, remainder));
577                    }
578                    return fills;
579                }
580
581                // Add this fill and continue
582                fills.push((book_order.price, current));
583                cumulative_denominator = cumulative_denominator + current;
584            }
585        }
586
587        fills
588    }
589}
590
591impl Display for BookLadder {
592    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
593        writeln!(f, "{}(side={})", stringify!(BookLadder), self.side)?;
594        for (price, level) in &self.levels {
595            writeln!(f, "  {} -> {} orders", price, level.len())?;
596        }
597        Ok(())
598    }
599}
600
601#[cfg(test)]
602impl BookLadder {
603    /// Adds multiple orders to the ladder.
604    pub(crate) fn add_bulk(&mut self, orders: &[BookOrder]) {
605        for order in orders {
606            self.add(*order, 0);
607        }
608    }
609}
610
611#[cfg(test)]
612mod tests {
613    use nautilus_core::correctness::CorrectnessError;
614    use rstest::rstest;
615
616    use crate::{
617        data::order::BookOrder,
618        enums::{BookType, OrderSide, RecordFlag},
619        orderbook::{
620            ladder::{BookLadder, BookPrice},
621            level::BookLevel,
622        },
623        types::{Price, Quantity},
624    };
625
626    #[rstest]
627    fn test_is_empty_after_add() {
628        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
629        assert!(ladder.is_empty(), "Ladder should start empty");
630        let order = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(100), 1);
631        ladder.add(order, 0);
632        assert!(
633            !ladder.is_empty(),
634            "Ladder should not be empty after adding an order"
635        );
636    }
637
638    #[rstest]
639    fn test_add_bulk_empty() {
640        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
641        ladder.add_bulk(&[]);
642        assert!(
643            ladder.is_empty(),
644            "Adding an empty vector should leave the ladder empty"
645        );
646    }
647
648    #[rstest]
649    fn test_add_bulk_orders() {
650        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
651        let orders = [
652            BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1),
653            BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(30), 2),
654            BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(50), 3),
655        ];
656        ladder.add_bulk(&orders);
657        // All orders share the same price, so there should be one price level.
658        assert_eq!(ladder.len(), 1, "Ladder should have one price level");
659        let orders_in_level = ladder.top().unwrap().get_orders();
660        assert_eq!(
661            orders_in_level.len(),
662            3,
663            "Price level should contain all bulk orders"
664        );
665    }
666
667    #[rstest]
668    #[case::bid(OrderSide::Buy, "4.0")]
669    #[case::ask(OrderSide::Sell, "1.0")]
670    fn test_book_price_sorting(#[case] side: OrderSide, #[case] expected_top: &str) {
671        let mut prices = [
672            BookPrice::new(Price::from("2.0"), side),
673            BookPrice::new(Price::from("4.0"), side),
674            BookPrice::new(Price::from("1.0"), side),
675            BookPrice::new(Price::from("3.0"), side),
676        ];
677
678        prices.sort();
679
680        assert_eq!(prices[0].value, Price::from(expected_top));
681    }
682
683    #[rstest]
684    fn test_add_single_order() {
685        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
686        let order = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 0);
687
688        ladder.add(order, 0);
689        assert_eq!(ladder.len(), 1);
690        assert_eq!(ladder.sizes(), 20.0);
691        assert_eq!(ladder.exposures(), 200.0);
692        assert_eq!(ladder.top().unwrap().price.value, Price::from("10.0"));
693    }
694
695    #[rstest]
696    fn test_add_multiple_buy_orders() {
697        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
698        let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 0);
699        let order2 = BookOrder::new(OrderSide::Buy, Price::from("9.00"), Quantity::from(30), 1);
700        let order3 = BookOrder::new(OrderSide::Buy, Price::from("9.00"), Quantity::from(50), 2);
701        let order4 = BookOrder::new(OrderSide::Buy, Price::from("8.00"), Quantity::from(200), 3);
702
703        ladder.add_bulk(&[order1, order2, order3, order4]);
704        assert_eq!(ladder.len(), 3);
705        assert_eq!(ladder.sizes(), 300.0);
706        assert_eq!(ladder.exposures(), 2520.0);
707        assert_eq!(ladder.top().unwrap().price.value, Price::from("10.0"));
708    }
709
710    #[rstest]
711    fn test_add_multiple_sell_orders() {
712        let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L3_MBO);
713        let order1 = BookOrder::new(OrderSide::Sell, Price::from("11.00"), Quantity::from(20), 0);
714        let order2 = BookOrder::new(OrderSide::Sell, Price::from("12.00"), Quantity::from(30), 1);
715        let order3 = BookOrder::new(OrderSide::Sell, Price::from("12.00"), Quantity::from(50), 2);
716        let order4 = BookOrder::new(
717            OrderSide::Sell,
718            Price::from("13.00"),
719            Quantity::from(200),
720            3,
721        );
722
723        ladder.add_bulk(&[order1, order2, order3, order4]);
724        assert_eq!(ladder.len(), 3);
725        assert_eq!(ladder.sizes(), 300.0);
726        assert_eq!(ladder.exposures(), 3780.0);
727        assert_eq!(ladder.top().unwrap().price.value, Price::from("11.0"));
728    }
729
730    #[rstest]
731    fn test_add_to_same_price_level() {
732        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
733        let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
734        let order2 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(30), 2);
735
736        ladder.add(order1, 0);
737        ladder.add(order2, 0);
738
739        assert_eq!(ladder.len(), 1);
740        assert_eq!(ladder.sizes(), 50.0);
741        assert_eq!(ladder.exposures(), 500.0);
742    }
743
744    #[rstest]
745    #[case::bid(OrderSide::Buy, "9.00", "8.00", "9.00")]
746    #[case::ask(OrderSide::Sell, "8.00", "9.00", "8.00")]
747    fn test_add_orders_preserves_top(
748        #[case] side: OrderSide,
749        #[case] first_price: &str,
750        #[case] second_price: &str,
751        #[case] expected_top: &str,
752    ) {
753        let mut ladder = BookLadder::new(side, BookType::L3_MBO);
754        let order1 = BookOrder::new(side, Price::from(first_price), Quantity::from(20), 1);
755        let order2 = BookOrder::new(side, Price::from(second_price), Quantity::from(30), 2);
756
757        ladder.add(order1, 0);
758        ladder.add(order2, 0);
759
760        assert_eq!(ladder.top().unwrap().price.value, Price::from(expected_top));
761    }
762
763    #[rstest]
764    #[case::bid(OrderSide::Buy)]
765    #[case::ask(OrderSide::Sell)]
766    fn test_update_order_price(#[case] side: OrderSide) {
767        let mut ladder = BookLadder::new(side, BookType::L3_MBO);
768        let order = BookOrder::new(side, Price::from("11.00"), Quantity::from(20), 1);
769
770        ladder.add(order, 0);
771        let order = BookOrder::new(side, Price::from("11.10"), Quantity::from(20), 1);
772
773        ladder.update(order, 0);
774        assert_eq!(ladder.len(), 1);
775        assert_eq!(ladder.sizes(), 20.0);
776        assert_eq!(ladder.exposures(), 222.0);
777        assert_eq!(ladder.top().unwrap().price.value, Price::from("11.1"));
778    }
779
780    #[rstest]
781    #[case::bid(OrderSide::Buy)]
782    #[case::ask(OrderSide::Sell)]
783    fn test_update_order_size(#[case] side: OrderSide) {
784        let mut ladder = BookLadder::new(side, BookType::L3_MBO);
785        let order = BookOrder::new(side, Price::from("11.00"), Quantity::from(20), 1);
786
787        ladder.add(order, 0);
788        let order = BookOrder::new(side, Price::from("11.00"), Quantity::from(10), 1);
789
790        ladder.update(order, 0);
791        assert_eq!(ladder.len(), 1);
792        assert_eq!(ladder.sizes(), 10.0);
793        assert_eq!(ladder.exposures(), 110.0);
794        assert_eq!(ladder.top().unwrap().price.value, Price::from("11.0"));
795    }
796
797    #[rstest]
798    fn test_delete_non_existing_order() {
799        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
800        let order = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
801
802        ladder.delete(order, 0, 0.into());
803
804        assert_eq!(ladder.len(), 0);
805    }
806
807    #[rstest]
808    #[case::bid(OrderSide::Buy, "11.00", "20", "10")]
809    #[case::ask(OrderSide::Sell, "10.00", "10", "10")]
810    fn test_delete_order(
811        #[case] side: OrderSide,
812        #[case] price: &str,
813        #[case] stored_size: &str,
814        #[case] delete_size: &str,
815    ) {
816        let mut ladder = BookLadder::new(side, BookType::L3_MBO);
817        let order = BookOrder::new(side, Price::from(price), Quantity::from(stored_size), 1);
818
819        ladder.add(order, 0);
820        let delete = BookOrder::new(side, Price::from(price), Quantity::from(delete_size), 1);
821
822        ladder.delete(delete, 0, 0.into());
823        assert_eq!(ladder.len(), 0);
824        assert_eq!(ladder.sizes(), 0.0);
825        assert_eq!(ladder.exposures(), 0.0);
826        assert_eq!(ladder.top(), None);
827    }
828
829    #[rstest]
830    fn test_ladder_totals_empty() {
831        let ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
832        assert_eq!(ladder.sizes(), 0.0);
833        assert_eq!(ladder.exposures(), 0.0);
834    }
835
836    #[rstest]
837    fn test_ladder_totals() {
838        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
839        let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
840        let order2 = BookOrder::new(OrderSide::Buy, Price::from("9.50"), Quantity::from(30), 2);
841        ladder.add(order1, 0);
842        ladder.add(order2, 0);
843
844        let expected_size = 20.0 + 30.0;
845        let expected_exposure = 10.00 * 20.0 + 9.50 * 30.0;
846
847        assert_eq!(ladder.sizes(), expected_size);
848        assert_eq!(ladder.exposures(), expected_exposure);
849    }
850
851    #[rstest]
852    fn test_iter_returns_fifo() {
853        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
854        let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
855        let order2 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(30), 2);
856        ladder.add(order1, 0);
857        ladder.add(order2, 0);
858        let orders: Vec<BookOrder> = ladder.top().unwrap().iter().copied().collect();
859        assert_eq!(
860            orders,
861            vec![order1, order2],
862            "Iterator should return orders in FIFO order"
863        );
864    }
865
866    #[rstest]
867    fn test_update_missing_order_inserts() {
868        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
869        let order = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
870        // Call update on an order that hasn't been added yet (upsert behavior)
871        ladder.update(order, 0);
872        assert_eq!(
873            ladder.len(),
874            1,
875            "Ladder should have one level after upsert update"
876        );
877        let orders = ladder.top().unwrap().get_orders();
878        assert_eq!(
879            orders.len(),
880            1,
881            "Price level should contain the inserted order"
882        );
883        assert_eq!(orders[0], order, "The inserted order should match");
884    }
885
886    #[rstest]
887    fn test_cache_consistency_after_operations() {
888        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
889        let order1 = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
890        let order2 = BookOrder::new(OrderSide::Buy, Price::from("9.00"), Quantity::from(30), 2);
891        ladder.add(order1, 0);
892        ladder.add(order2, 0);
893
894        // Ensure that each order in the cache is present in the corresponding price level.
895        for (order_id, price) in &ladder.cache {
896            let level = ladder
897                .levels
898                .get(price)
899                .expect("Every price in the cache should have a corresponding level");
900            assert!(
901                level.orders.contains_key(order_id),
902                "Order id {order_id} should be present in the level for price {price}",
903            );
904        }
905    }
906
907    #[rstest]
908    fn test_simulate_fills_with_empty_book() {
909        let ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
910        let order = BookOrder::new(OrderSide::Buy, Price::max(2), Quantity::from(500), 1);
911
912        let fills = ladder.simulate_fills(&order);
913
914        assert!(fills.is_empty());
915    }
916
917    #[rstest]
918    #[case(OrderSide::Buy, Price::max(2), OrderSide::Sell)]
919    #[case(OrderSide::Sell, Price::min(2), OrderSide::Buy)]
920    fn test_simulate_order_fills_with_no_size(
921        #[case] side: OrderSide,
922        #[case] price: Price,
923        #[case] ladder_side: OrderSide,
924    ) {
925        let ladder = BookLadder::new(ladder_side, BookType::L3_MBO);
926        let order = BookOrder {
927            price, // <-- Simulate a MARKET order
928            size: Quantity::from(500),
929            side: side.into(),
930            order_id: 2,
931        };
932
933        let fills = ladder.simulate_fills(&order);
934
935        assert!(fills.is_empty());
936    }
937
938    #[rstest]
939    #[case(OrderSide::Buy, OrderSide::Sell, Price::from("60.0"))]
940    #[case(OrderSide::Sell, OrderSide::Buy, Price::from("40.0"))]
941    fn test_simulate_order_fills_buy_when_far_from_market(
942        #[case] order_side: OrderSide,
943        #[case] ladder_side: OrderSide,
944        #[case] ladder_price: Price,
945    ) {
946        let mut ladder = BookLadder::new(ladder_side, BookType::L3_MBO);
947
948        ladder.add(
949            BookOrder {
950                price: ladder_price,
951                size: Quantity::from(100),
952                side: ladder_side.into(),
953                order_id: 1,
954            },
955            0,
956        );
957
958        let order = BookOrder {
959            price: Price::from("50.00"),
960            size: Quantity::from(500),
961            side: order_side.into(),
962            order_id: 2,
963        };
964
965        let fills = ladder.simulate_fills(&order);
966
967        assert!(fills.is_empty());
968    }
969
970    #[rstest]
971    fn test_simulate_order_fills_sell_when_far_from_market() {
972        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
973
974        ladder.add(
975            BookOrder {
976                price: Price::from("100.00"),
977                size: Quantity::from(100),
978                side: OrderSide::Buy.into(),
979                order_id: 1,
980            },
981            0,
982        );
983
984        let order = BookOrder {
985            price: Price::from("150.00"), // <-- Simulate a MARKET order
986            size: Quantity::from(500),
987            side: OrderSide::Buy.into(),
988            order_id: 2,
989        };
990
991        let fills = ladder.simulate_fills(&order);
992
993        assert!(fills.is_empty());
994    }
995
996    #[rstest]
997    fn test_simulate_order_fills_buy() {
998        let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L3_MBO);
999
1000        ladder.add_bulk(&[
1001            BookOrder {
1002                price: Price::from("100.00"),
1003                size: Quantity::from(100),
1004                side: OrderSide::Sell.into(),
1005                order_id: 1,
1006            },
1007            BookOrder {
1008                price: Price::from("101.00"),
1009                size: Quantity::from(200),
1010                side: OrderSide::Sell.into(),
1011                order_id: 2,
1012            },
1013            BookOrder {
1014                price: Price::from("102.00"),
1015                size: Quantity::from(400),
1016                side: OrderSide::Sell.into(),
1017                order_id: 3,
1018            },
1019        ]);
1020
1021        let order = BookOrder {
1022            price: Price::max(2), // <-- Simulate a MARKET order
1023            size: Quantity::from(500),
1024            side: OrderSide::Buy.into(),
1025            order_id: 4,
1026        };
1027
1028        let fills = ladder.simulate_fills(&order);
1029
1030        assert_eq!(fills.len(), 3);
1031
1032        let (price1, size1) = fills[0];
1033        assert_eq!(price1, Price::from("100.00"));
1034        assert_eq!(size1, Quantity::from(100));
1035
1036        let (price2, size2) = fills[1];
1037        assert_eq!(price2, Price::from("101.00"));
1038        assert_eq!(size2, Quantity::from(200));
1039
1040        let (price3, size3) = fills[2];
1041        assert_eq!(price3, Price::from("102.00"));
1042        assert_eq!(size3, Quantity::from(200));
1043    }
1044
1045    #[rstest]
1046    fn test_simulate_order_fills_sell() {
1047        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1048
1049        ladder.add_bulk(&[
1050            BookOrder {
1051                price: Price::from("102.00"),
1052                size: Quantity::from(100),
1053                side: OrderSide::Buy.into(),
1054                order_id: 1,
1055            },
1056            BookOrder {
1057                price: Price::from("101.00"),
1058                size: Quantity::from(200),
1059                side: OrderSide::Buy.into(),
1060                order_id: 2,
1061            },
1062            BookOrder {
1063                price: Price::from("100.00"),
1064                size: Quantity::from(400),
1065                side: OrderSide::Buy.into(),
1066                order_id: 3,
1067            },
1068        ]);
1069
1070        let order = BookOrder {
1071            price: Price::min(2), // <-- Simulate a MARKET order
1072            size: Quantity::from(500),
1073            side: OrderSide::Sell.into(),
1074            order_id: 4,
1075        };
1076
1077        let fills = ladder.simulate_fills(&order);
1078
1079        assert_eq!(fills.len(), 3);
1080
1081        let (price1, size1) = fills[0];
1082        assert_eq!(price1, Price::from("102.00"));
1083        assert_eq!(size1, Quantity::from(100));
1084
1085        let (price2, size2) = fills[1];
1086        assert_eq!(price2, Price::from("101.00"));
1087        assert_eq!(size2, Quantity::from(200));
1088
1089        let (price3, size3) = fills[2];
1090        assert_eq!(price3, Price::from("100.00"));
1091        assert_eq!(size3, Quantity::from(200));
1092    }
1093
1094    #[rstest]
1095    fn test_simulate_order_fills_sell_with_size_at_limit_of_precision() {
1096        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1097
1098        ladder.add_bulk(&[
1099            BookOrder {
1100                price: Price::from("102.00"),
1101                size: Quantity::from("100.000000000"),
1102                side: OrderSide::Buy.into(),
1103                order_id: 1,
1104            },
1105            BookOrder {
1106                price: Price::from("101.00"),
1107                size: Quantity::from("200.000000000"),
1108                side: OrderSide::Buy.into(),
1109                order_id: 2,
1110            },
1111            BookOrder {
1112                price: Price::from("100.00"),
1113                size: Quantity::from("400.000000000"),
1114                side: OrderSide::Buy.into(),
1115                order_id: 3,
1116            },
1117        ]);
1118
1119        let order = BookOrder {
1120            price: Price::min(2),                  // <-- Simulate a MARKET order
1121            size: Quantity::from("699.999999999"), // <-- Size slightly less than total size in ladder
1122            side: OrderSide::Sell.into(),
1123            order_id: 4,
1124        };
1125
1126        let fills = ladder.simulate_fills(&order);
1127
1128        assert_eq!(fills.len(), 3);
1129
1130        let (price1, size1) = fills[0];
1131        assert_eq!(price1, Price::from("102.00"));
1132        assert_eq!(size1, Quantity::from("100.000000000"));
1133
1134        let (price2, size2) = fills[1];
1135        assert_eq!(price2, Price::from("101.00"));
1136        assert_eq!(size2, Quantity::from("200.000000000"));
1137
1138        let (price3, size3) = fills[2];
1139        assert_eq!(price3, Price::from("100.00"));
1140        assert_eq!(size3, Quantity::from("399.999999999"));
1141    }
1142
1143    #[rstest]
1144    fn test_boundary_prices() {
1145        let max_price = Price::max(1);
1146        let min_price = Price::min(1);
1147
1148        let mut ladder_buy = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1149        let mut ladder_sell = BookLadder::new(OrderSide::Sell, BookType::L3_MBO);
1150
1151        let order_buy = BookOrder::new(OrderSide::Buy, min_price, Quantity::from(1), 1);
1152        let order_sell = BookOrder::new(OrderSide::Sell, max_price, Quantity::from(1), 1);
1153
1154        ladder_buy.add(order_buy, 0);
1155        ladder_sell.add(order_sell, 0);
1156
1157        assert_eq!(ladder_buy.top().unwrap().price.value, min_price);
1158        assert_eq!(ladder_sell.top().unwrap().price.value, max_price);
1159    }
1160
1161    #[rstest]
1162    fn test_l1_single_delta_batches_replace_each_other() {
1163        // Test that single-delta batches (each add has F_LAST) replace each other.
1164        // Each batch represents the current top-of-book, not a running best.
1165        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1166        let side_constant = OrderSide::Buy as u64;
1167
1168        // Using F_MBP | F_LAST simulates receiving single-delta batches
1169        let batch_flags = RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8;
1170
1171        // Add first L1 order at price 100.00
1172        let order1 = BookOrder {
1173            side: OrderSide::Buy.into(),
1174            price: Price::from("100.00"),
1175            size: Quantity::from(50),
1176            order_id: side_constant,
1177        };
1178        ladder.add(order1, batch_flags);
1179
1180        assert_eq!(ladder.len(), 1, "Should have one level after first add");
1181        assert_eq!(
1182            ladder.top().unwrap().price.value,
1183            Price::from("100.00"),
1184            "Top level should be at 100.00"
1185        );
1186
1187        let order2 = BookOrder {
1188            side: OrderSide::Buy.into(),
1189            price: Price::from("101.00"),
1190            size: Quantity::from(60),
1191            order_id: side_constant,
1192        };
1193        ladder.add(order2, batch_flags);
1194
1195        assert_eq!(ladder.len(), 1, "Should have only one level");
1196        assert_eq!(
1197            ladder.top().unwrap().price.value,
1198            Price::from("101.00"),
1199            "Top level should be at 101.00"
1200        );
1201
1202        // Price CAN degrade between batches
1203        let order3 = BookOrder {
1204            side: OrderSide::Buy.into(),
1205            price: Price::from("100.50"),
1206            size: Quantity::from(70),
1207            order_id: side_constant,
1208        };
1209        ladder.add(order3, batch_flags);
1210
1211        assert_eq!(ladder.len(), 1, "Should have only one level");
1212        assert_eq!(
1213            ladder.top().unwrap().price.value,
1214            Price::from("100.50"),
1215            "Top level should be at 100.50 (new batch replaced old)"
1216        );
1217    }
1218
1219    #[rstest]
1220    fn test_l2_orders_create_multiple_levels() {
1221        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L2_MBP);
1222
1223        let order1 = BookOrder {
1224            side: OrderSide::Buy.into(),
1225            price: Price::from("100.00"),
1226            size: Quantity::from(50),
1227            order_id: Price::from("100.00").raw() as u64,
1228        };
1229        ladder.add(order1, 0);
1230
1231        let order2 = BookOrder {
1232            side: OrderSide::Buy.into(),
1233            price: Price::from("99.00"),
1234            size: Quantity::from(60),
1235            order_id: Price::from("99.00").raw() as u64,
1236        };
1237        ladder.add(order2, 0);
1238
1239        assert_eq!(ladder.len(), 2, "L2 orders should create multiple levels");
1240        assert_eq!(
1241            ladder.top().unwrap().price.value,
1242            Price::from("100.00"),
1243            "Top level should be best bid"
1244        );
1245    }
1246
1247    #[rstest]
1248    fn test_zero_size_l1_order_clears_top() {
1249        // Venues send Add with size=0 to clear top-of-book
1250        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1251        let side_constant = OrderSide::Buy as u64;
1252
1253        let order1 = BookOrder {
1254            side: OrderSide::Buy.into(),
1255            price: Price::from("100.00"),
1256            size: Quantity::from(50),
1257            order_id: side_constant,
1258        };
1259        ladder.add(order1, 0);
1260
1261        assert_eq!(ladder.len(), 1);
1262        assert_eq!(ladder.top().unwrap().price.value, Price::from("100.00"));
1263        assert!(ladder.top().unwrap().first().is_some());
1264
1265        // Try to add zero-size L1 order (venue clearing the book)
1266        let order2 = BookOrder {
1267            side: OrderSide::Buy.into(),
1268            price: Price::from("101.00"),
1269            size: Quantity::zero(9), // Zero size
1270            order_id: side_constant,
1271        };
1272        ladder.add(order2, 0);
1273
1274        // L1 zero-size should clear the top of book
1275        assert_eq!(ladder.len(), 0, "Zero-size L1 add should clear the book");
1276        assert!(ladder.top().is_none(), "Book should be empty after clear");
1277
1278        // Cache should be empty
1279        assert!(
1280            ladder.cache.is_empty(),
1281            "Cache should be empty after L1 clear"
1282        );
1283    }
1284
1285    #[rstest]
1286    fn test_zero_size_order_to_empty_ladder() {
1287        // Edge case: Adding zero-size L1 order to empty ladder should remain empty
1288        let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L1_MBP);
1289        let side_constant = OrderSide::Sell as u64;
1290
1291        let order = BookOrder {
1292            side: OrderSide::Sell.into(),
1293            price: Price::from("100.00"),
1294            size: Quantity::zero(9),
1295            order_id: side_constant,
1296        };
1297        ladder.add(order, 0);
1298
1299        assert_eq!(ladder.len(), 0, "Empty ladder should remain empty");
1300        assert!(ladder.top().is_none(), "Top should be None");
1301        assert!(
1302            ladder.cache.is_empty(),
1303            "Cache should remain empty for zero-size add"
1304        );
1305    }
1306
1307    #[rstest]
1308    fn test_l3_order_id_collision_moves_order() {
1309        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1310
1311        // Add order with ID 1 at 100.00 (matches Buy side constant)
1312        let order1 = BookOrder {
1313            side: OrderSide::Buy.into(),
1314            price: Price::from("100.00"),
1315            size: Quantity::from(50),
1316            order_id: 1, // Matches OrderSide::Buy as u64
1317        };
1318        ladder.add(order1, 0);
1319
1320        assert_eq!(ladder.len(), 1);
1321
1322        let order2 = BookOrder {
1323            side: OrderSide::Buy.into(),
1324            price: Price::from("99.00"),
1325            size: Quantity::from(60),
1326            order_id: 1,
1327        };
1328        ladder.add(order2, 0);
1329
1330        assert_eq!(ladder.len(), 1, "Order ID 1 must live at exactly one level");
1331        assert_eq!(
1332            ladder.top().unwrap().price.value,
1333            Price::from("99.00"),
1334            "Order should have moved to 99.00"
1335        );
1336        assert_eq!(
1337            ladder.top().unwrap().first().unwrap().size,
1338            Quantity::from(60),
1339            "Size should come from the re-added order"
1340        );
1341        assert_eq!(
1342            ladder.cache.len(),
1343            1,
1344            "Cache should track exactly one entry for the moved order"
1345        );
1346    }
1347
1348    #[rstest]
1349    fn test_l3_duplicate_order_id_update_and_delete_leave_no_ghost() {
1350        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1351
1352        let order1 = BookOrder {
1353            side: OrderSide::Buy.into(),
1354            price: Price::from("100.00"),
1355            size: Quantity::from(50),
1356            order_id: 1,
1357        };
1358        ladder.add(order1, 0);
1359
1360        let order2 = BookOrder {
1361            side: OrderSide::Buy.into(),
1362            price: Price::from("99.00"),
1363            size: Quantity::from(60),
1364            order_id: 1,
1365        };
1366        ladder.add(order2, 0);
1367
1368        let zero_update = BookOrder {
1369            side: OrderSide::Buy.into(),
1370            price: Price::from("99.00"),
1371            size: Quantity::zero(9),
1372            order_id: 1,
1373        };
1374        ladder.update(zero_update, 0);
1375
1376        assert!(
1377            ladder.is_empty(),
1378            "Zero-size update must not ghost the order"
1379        );
1380        assert!(ladder.cache.is_empty());
1381
1382        ladder.add(order1, 0);
1383        ladder.add(order2, 0);
1384        ladder.delete(order2, 0, 0.into());
1385
1386        assert!(ladder.is_empty(), "Delete must not ghost the order");
1387        assert!(ladder.cache.is_empty());
1388    }
1389
1390    #[rstest]
1391    #[case::bids(OrderSide::Buy, Some(OrderSide::Buy), "100.00", "99.00")]
1392    #[case::asks(OrderSide::Sell, Some(OrderSide::Sell), "100.00", "101.00")]
1393    fn test_move_leaves_other_orders_at_old_level(
1394        #[case] side_spec: OrderSide,
1395        #[case] side: Option<OrderSide>,
1396        #[case] old_price: &str,
1397        #[case] new_price: &str,
1398        #[values(false, true)] via_update: bool,
1399    ) {
1400        let mut ladder = BookLadder::new(side_spec, BookType::L3_MBO);
1401
1402        let moved = BookOrder {
1403            side,
1404            price: Price::from(old_price),
1405            size: Quantity::from(50),
1406            order_id: 1,
1407        };
1408        let staying = BookOrder {
1409            side,
1410            price: Price::from(old_price),
1411            size: Quantity::from(30),
1412            order_id: 2,
1413        };
1414        ladder.add(moved, 0);
1415        ladder.add(staying, 0);
1416
1417        let moved_new = BookOrder {
1418            side,
1419            price: Price::from(new_price),
1420            size: Quantity::from(60),
1421            order_id: 1,
1422        };
1423
1424        if via_update {
1425            ladder.update(moved_new, 0);
1426        } else {
1427            ladder.add(moved_new, 0);
1428        }
1429
1430        assert_eq!(
1431            ladder.len(),
1432            2,
1433            "Old level must survive with the remaining order"
1434        );
1435        let old_level = ladder
1436            .levels
1437            .get(&BookPrice::new(Price::from(old_price), side_spec))
1438            .expect("Old level should remain");
1439        let new_level = ladder
1440            .levels
1441            .get(&BookPrice::new(Price::from(new_price), side_spec))
1442            .expect("New level should exist");
1443
1444        // `BookOrder` equality compares IDs only, so compare the fields that must move
1445        let fields = |level: &BookLevel| {
1446            level
1447                .iter()
1448                .map(|order| (order.order_id, order.price, order.size))
1449                .collect::<Vec<_>>()
1450        };
1451
1452        assert_eq!(
1453            fields(old_level),
1454            vec![(2, Price::from(old_price), Quantity::from(30))]
1455        );
1456        assert_eq!(
1457            fields(new_level),
1458            vec![(1, Price::from(new_price), Quantity::from(60))]
1459        );
1460        assert_eq!(ladder.cache.len(), 2);
1461        assert_eq!(ladder.cache[&1], new_level.price);
1462        assert_eq!(ladder.cache[&2], old_level.price);
1463    }
1464
1465    #[rstest]
1466    fn test_l1_vs_l3_duplicate_order_id_replacement() {
1467        // L1 behavior with replacement (flags=0): successive adds replace
1468        let mut l1_ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1469        let side_constant = OrderSide::Buy as u64;
1470
1471        let order1 = BookOrder {
1472            side: OrderSide::Buy.into(),
1473            price: Price::from("100.00"),
1474            size: Quantity::from(50),
1475            order_id: side_constant,
1476        };
1477        l1_ladder.add(order1, 0);
1478
1479        let order2 = BookOrder {
1480            side: OrderSide::Buy.into(),
1481            price: Price::from("101.00"),
1482            size: Quantity::from(60),
1483            order_id: side_constant, // Same ID
1484        };
1485        l1_ladder.add(order2, 0);
1486
1487        assert_eq!(l1_ladder.len(), 1, "L1 should have only 1 level");
1488        assert_eq!(
1489            l1_ladder.top().unwrap().price.value,
1490            Price::from("101.00"),
1491            "L1 should have replaced the old level"
1492        );
1493
1494        let mut l3_ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1495
1496        let order3 = BookOrder {
1497            side: OrderSide::Buy.into(),
1498            price: Price::from("100.00"),
1499            size: Quantity::from(50),
1500            order_id: 1, // Happens to match side constant
1501        };
1502        l3_ladder.add(order3, 0);
1503
1504        let order4 = BookOrder {
1505            side: OrderSide::Buy.into(),
1506            price: Price::from("101.00"),
1507            size: Quantity::from(60),
1508            order_id: 1,
1509        };
1510        l3_ladder.add(order4, 0);
1511
1512        assert_eq!(
1513            l3_ladder.len(),
1514            1,
1515            "L3 should move the order to its new price level"
1516        );
1517        assert_eq!(
1518            l3_ladder.top().unwrap().price.value,
1519            Price::from("101.00"),
1520            "L3 order should have moved to 101.00"
1521        );
1522    }
1523
1524    #[rstest]
1525    #[case::bids_worst_to_best(OrderSide::Buy, Some(OrderSide::Buy), &["99.00", "100.00", "101.00", "102.00"], "102.00")]
1526    #[case::bids_best_to_worst(OrderSide::Buy, Some(OrderSide::Buy), &["102.00", "101.00", "100.00", "99.00"], "100.00")]
1527    #[case::asks_worst_to_best(OrderSide::Sell, Some(OrderSide::Sell), &["105.00", "104.00", "103.00", "102.00"], "102.00")]
1528    #[case::asks_best_to_worst(OrderSide::Sell, Some(OrderSide::Sell), &["102.00", "103.00", "104.00", "105.00"], "104.00")]
1529    fn test_l1_multi_delta_batch_keeps_best_of_final_two(
1530        #[case] side_spec: OrderSide,
1531        #[case] side: Option<OrderSide>,
1532        #[case] prices: &[&str],
1533        #[case] expected_best: &str,
1534    ) {
1535        // Multi-delta batch: F_MBP without F_LAST clears each time.
1536        // Only the delta before F_LAST + F_LAST delta accumulate.
1537        let mut ladder = BookLadder::new(side_spec, BookType::L1_MBP);
1538
1539        let batch_size = prices.len();
1540        for (i, price_str) in prices.iter().enumerate() {
1541            let order = BookOrder {
1542                side,
1543                price: Price::from(*price_str),
1544                size: Quantity::from((i + 1) as u64 * 10),
1545                order_id: (i + 100) as u64,
1546            };
1547            let flags = if i == batch_size - 1 {
1548                RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8
1549            } else {
1550                RecordFlag::F_MBP as u8
1551            };
1552            ladder.add(order, flags);
1553        }
1554
1555        assert_eq!(ladder.len(), 1, "L1 should have only 1 level");
1556        assert_eq!(
1557            ladder.top().unwrap().price.value,
1558            Price::from(expected_best),
1559            "Should keep best of final two deltas"
1560        );
1561    }
1562
1563    #[rstest]
1564    fn test_l1_retain_best_only_cache_consistency() {
1565        // Verify cache is properly cleaned up when retaining only the best level
1566        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1567        let batch_flags = RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8;
1568        let prices = ["100.00", "101.00", "102.00", "103.00", "104.00"];
1569
1570        for (i, price_str) in prices.iter().enumerate() {
1571            let order = BookOrder {
1572                side: OrderSide::Buy.into(),
1573                price: Price::from(*price_str),
1574                size: Quantity::from(10),
1575                order_id: (i + 1) as u64,
1576            };
1577            ladder.add(order, batch_flags);
1578        }
1579
1580        assert_eq!(ladder.len(), 1);
1581        assert_eq!(
1582            ladder.cache.len(),
1583            1,
1584            "Cache should have exactly 1 entry for L1"
1585        );
1586
1587        let total_orders: usize = ladder.levels.values().map(BookLevel::len).sum();
1588        assert_eq!(
1589            ladder.cache.len(),
1590            total_orders,
1591            "Cache should be consistent with levels"
1592        );
1593    }
1594
1595    #[rstest]
1596    fn test_l1_sequential_replacement_allows_price_degradation() {
1597        // Test that sequential L1 replacements (without F_MBP) allow price degradation
1598        // This is the expected behavior for top-of-book feeds like F_TOB
1599        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1600        let side_constant = OrderSide::Buy as u64;
1601
1602        // Add first L1 order at price 101.00 (best bid)
1603        let order1 = BookOrder {
1604            side: OrderSide::Buy.into(),
1605            price: Price::from("101.00"),
1606            size: Quantity::from(50),
1607            order_id: side_constant,
1608        };
1609        ladder.add(order1, 0); // flags=0 means replacement mode
1610
1611        assert_eq!(ladder.len(), 1);
1612        assert_eq!(
1613            ladder.top().unwrap().price.value,
1614            Price::from("101.00"),
1615            "Should have bid at 101.00"
1616        );
1617
1618        // Add second L1 order at worse price 100.00 (replacement mode)
1619        // This should REPLACE the previous level, allowing price degradation
1620        let order2 = BookOrder {
1621            side: OrderSide::Buy.into(),
1622            price: Price::from("100.00"),
1623            size: Quantity::from(60),
1624            order_id: side_constant,
1625        };
1626        ladder.add(order2, 0); // flags=0 means replacement mode
1627
1628        assert_eq!(ladder.len(), 1);
1629        assert_eq!(
1630            ladder.top().unwrap().price.value,
1631            Price::from("100.00"),
1632            "Sequential replacement should allow price to degrade from 101 to 100"
1633        );
1634
1635        // Verify the size was updated too
1636        assert_eq!(
1637            ladder.top().unwrap().first().unwrap().size,
1638            Quantity::from(60),
1639            "Size should be from the new order"
1640        );
1641    }
1642
1643    #[rstest]
1644    #[case::bids(OrderSide::Buy, Some(OrderSide::Buy), &["100.00", "101.00", "102.00"], "102.00", &["97.00", "98.00", "99.00"], "99.00")]
1645    #[case::asks(OrderSide::Sell, Some(OrderSide::Sell), &["100.00", "101.00", "102.00"], "101.00", &["103.00", "104.00", "105.00"], "104.00")]
1646    fn test_l1_consecutive_batches_clear_between(
1647        #[case] side_spec: OrderSide,
1648        #[case] side: Option<OrderSide>,
1649        #[case] batch1_prices: &[&str],
1650        #[case] expected1: &str,
1651        #[case] batch2_prices: &[&str],
1652        #[case] expected2: &str,
1653    ) {
1654        // Consecutive batches clear old data when a new batch starts
1655        let mut ladder = BookLadder::new(side_spec, BookType::L1_MBP);
1656
1657        // Batch 1
1658        for (i, price_str) in batch1_prices.iter().enumerate() {
1659            let order = BookOrder {
1660                side,
1661                price: Price::from(*price_str),
1662                size: Quantity::from(10),
1663                order_id: (i + 100) as u64,
1664            };
1665            let flags = if i == batch1_prices.len() - 1 {
1666                RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8
1667            } else {
1668                RecordFlag::F_MBP as u8
1669            };
1670            ladder.add(order, flags);
1671        }
1672
1673        assert_eq!(ladder.len(), 1);
1674        assert_eq!(
1675            ladder.top().unwrap().price.value,
1676            Price::from(expected1),
1677            "After batch 1"
1678        );
1679
1680        // Batch 2 (worse prices for bids, higher prices for asks)
1681        for (i, price_str) in batch2_prices.iter().enumerate() {
1682            let order = BookOrder {
1683                side,
1684                price: Price::from(*price_str),
1685                size: Quantity::from(20),
1686                order_id: (i + 200) as u64,
1687            };
1688            let flags = if i == batch2_prices.len() - 1 {
1689                RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8
1690            } else {
1691                RecordFlag::F_MBP as u8
1692            };
1693            ladder.add(order, flags);
1694        }
1695
1696        assert_eq!(ladder.len(), 1);
1697        assert_eq!(
1698            ladder.top().unwrap().price.value,
1699            Price::from(expected2),
1700            "After batch 2: batch 1 data cleared"
1701        );
1702    }
1703
1704    #[rstest]
1705    fn test_l1_zero_size_clears_regardless_of_order_id() {
1706        // Regression test: Zero-size clears must work even when order_id
1707        // differs between F_MBP batch (price-hash ID) and clear (side-constant ID)
1708        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1709
1710        // Add order with F_MBP flags (uses price-hash order_id via pre_process_order)
1711        let batch_flags = RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8;
1712        let order = BookOrder {
1713            side: OrderSide::Buy.into(),
1714            price: Price::from("100.00"),
1715            size: Quantity::from(50),
1716            order_id: 12345, // Price-hash ID
1717        };
1718        ladder.add(order, batch_flags);
1719        assert_eq!(ladder.len(), 1);
1720
1721        // Clear with zero-size and different order_id (side-constant)
1722        let clear_order = BookOrder {
1723            side: OrderSide::Buy.into(),
1724            price: Price::from("100.00"),
1725            size: Quantity::zero(9),
1726            order_id: OrderSide::Buy as u64, // Side-constant ID (different!)
1727        };
1728        ladder.add(clear_order, 0);
1729
1730        // Should be cleared despite order_id mismatch
1731        assert_eq!(
1732            ladder.len(),
1733            0,
1734            "Zero-size should clear L1 regardless of order_id"
1735        );
1736        assert!(ladder.cache.is_empty(), "Cache should be empty after clear");
1737    }
1738
1739    #[rstest]
1740    fn test_l1_f_mbp_without_f_last_does_not_accumulate() {
1741        // F_MBP without F_LAST: each message clears, preventing stale prices.
1742        // This allows prices to degrade when the market moves.
1743        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1744        let flags = RecordFlag::F_MBP as u8; // No F_LAST
1745
1746        // Prices descending from 100 to 91 (simulates degrading market)
1747        let prices = [
1748            "100.00", "99.00", "98.00", "97.00", "96.00", "95.00", "94.00", "93.00", "92.00",
1749            "91.00",
1750        ];
1751
1752        for (i, price_str) in prices.iter().enumerate() {
1753            let order = BookOrder {
1754                side: OrderSide::Buy.into(),
1755                price: Price::from(*price_str),
1756                size: Quantity::from(10),
1757                order_id: (i + 100) as u64,
1758            };
1759            ladder.add(order, flags);
1760
1761            assert_eq!(
1762                ladder.len(),
1763                1,
1764                "L1 should always have at most 1 level, iteration {i}"
1765            );
1766        }
1767
1768        // Final price should be 91 (the last added), not 100 (the best ever seen)
1769        assert_eq!(
1770            ladder.top().unwrap().price.value,
1771            Price::from("91.00"),
1772            "Should show last price (91), allowing degradation"
1773        );
1774    }
1775
1776    #[rstest]
1777    fn test_l1_f_mbp_two_delta_batch_retains_best() {
1778        // A 2-delta batch (F_MBP then F_MBP|F_LAST) accumulates both and keeps best
1779        let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L1_MBP);
1780
1781        // Delta 1 (F_MBP only): clears, adds 100, sets in_l1_batch=true
1782        let order1 = BookOrder {
1783            side: OrderSide::Sell.into(),
1784            price: Price::from("100.00"),
1785            size: Quantity::from(10),
1786            order_id: 100,
1787        };
1788        ladder.add(order1, RecordFlag::F_MBP as u8);
1789
1790        // Delta 2 (F_MBP|F_LAST): in_l1_batch=true so doesn't clear,
1791        // adds 101, now has 100+101, retain_best → 100
1792        let order2 = BookOrder {
1793            side: OrderSide::Sell.into(),
1794            price: Price::from("101.00"),
1795            size: Quantity::from(20),
1796            order_id: 101,
1797        };
1798        ladder.add(order2, RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8);
1799
1800        assert_eq!(ladder.len(), 1);
1801        assert_eq!(
1802            ladder.top().unwrap().price.value,
1803            Price::from("100.00"),
1804            "2-delta batch keeps best ask (100) from both deltas"
1805        );
1806    }
1807
1808    #[rstest]
1809    fn test_l1_snapshot_batch_accumulates_all_levels_bids() {
1810        // F_SNAPSHOT batch accumulates ALL levels and keeps best bid
1811        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1812        let prices = ["98.00", "99.00", "100.00", "101.00"];
1813        let batch_size = prices.len();
1814
1815        for (i, price_str) in prices.iter().enumerate() {
1816            let order = BookOrder {
1817                side: OrderSide::Buy.into(),
1818                price: Price::from(*price_str),
1819                size: Quantity::from(10),
1820                order_id: (i + 100) as u64,
1821            };
1822            let flags = if i == batch_size - 1 {
1823                RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
1824            } else {
1825                RecordFlag::F_SNAPSHOT as u8
1826            };
1827            ladder.add(order, flags);
1828        }
1829
1830        assert_eq!(
1831            ladder.len(),
1832            1,
1833            "L1 should have only 1 level after snapshot"
1834        );
1835        assert_eq!(
1836            ladder.top().unwrap().price.value,
1837            Price::from("101.00"),
1838            "F_SNAPSHOT batch should keep best bid (101) from ALL deltas"
1839        );
1840    }
1841
1842    #[rstest]
1843    fn test_l1_snapshot_batch_accumulates_all_levels_asks() {
1844        // F_SNAPSHOT batch accumulates ALL levels and keeps best ask
1845        let mut ladder = BookLadder::new(OrderSide::Sell, BookType::L1_MBP);
1846        let prices = ["104.00", "103.00", "102.00", "101.00"];
1847        let batch_size = prices.len();
1848
1849        for (i, price_str) in prices.iter().enumerate() {
1850            let order = BookOrder {
1851                side: OrderSide::Sell.into(),
1852                price: Price::from(*price_str),
1853                size: Quantity::from(10),
1854                order_id: (i + 100) as u64,
1855            };
1856            let flags = if i == batch_size - 1 {
1857                RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
1858            } else {
1859                RecordFlag::F_SNAPSHOT as u8
1860            };
1861            ladder.add(order, flags);
1862        }
1863
1864        assert_eq!(
1865            ladder.len(),
1866            1,
1867            "L1 should have only 1 level after snapshot"
1868        );
1869        assert_eq!(
1870            ladder.top().unwrap().price.value,
1871            Price::from("101.00"),
1872            "F_SNAPSHOT batch should keep best ask (101) from ALL deltas"
1873        );
1874    }
1875
1876    #[rstest]
1877    #[case::bids(OrderSide::Buy, ["101.00", "100.00", "99.00"], "101.00")]
1878    #[case::asks(OrderSide::Sell, ["99.00", "100.00", "101.00"], "99.00")]
1879    fn test_l1_snapshot_batch_keeps_best_when_delivered_first(
1880        #[case] side: OrderSide,
1881        #[case] prices: [&str; 3],
1882        #[case] expected_best: &str,
1883    ) {
1884        let mut ladder = BookLadder::new(side, BookType::L1_MBP);
1885        let batch_size = prices.len();
1886
1887        for (i, price_str) in prices.iter().enumerate() {
1888            let order = BookOrder {
1889                side: side.into(),
1890                price: Price::from(*price_str),
1891                size: Quantity::from(10),
1892                order_id: side as u64,
1893            };
1894
1895            let flags = if i == batch_size - 1 {
1896                RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
1897            } else {
1898                RecordFlag::F_SNAPSHOT as u8
1899            };
1900
1901            ladder.add(order, flags);
1902        }
1903
1904        assert_eq!(ladder.len(), 1);
1905        assert_eq!(
1906            ladder.top().unwrap().price.value,
1907            Price::from(expected_best)
1908        );
1909        assert_eq!(ladder.cache.len(), 1);
1910    }
1911
1912    #[rstest]
1913    fn test_display() {
1914        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L3_MBO);
1915        ladder.add_bulk(&[
1916            BookOrder::new(OrderSide::Buy, Price::from("100.00"), Quantity::from(10), 1),
1917            BookOrder::new(OrderSide::Buy, Price::from("100.00"), Quantity::from(20), 2),
1918            BookOrder::new(OrderSide::Buy, Price::from("99.00"), Quantity::from(30), 3),
1919        ]);
1920
1921        assert_eq!(
1922            ladder.to_string(),
1923            "BookLadder(side=BUY)\n  100.00 -> 2 orders\n  99.00 -> 1 orders\n"
1924        );
1925    }
1926
1927    #[rstest]
1928    fn test_batch_state_code_round_trips_on_l1_ladder(#[values(0, 1, 2)] code: u8) {
1929        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1930
1931        ladder.set_batch_state_code(code).unwrap();
1932
1933        assert_eq!(ladder.batch_state_code(), code);
1934    }
1935
1936    #[rstest]
1937    #[case::unknown_code(BookType::L1_MBP, 3, "Invalid L1 batch state code: 3")]
1938    #[case::non_l1_batch(
1939        BookType::L2_MBP,
1940        1,
1941        "Cannot restore L1 batch state for book type L2_MBP"
1942    )]
1943    fn test_set_batch_state_code_rejects_invalid_state(
1944        #[case] book_type: BookType,
1945        #[case] code: u8,
1946        #[case] message: &str,
1947    ) {
1948        let mut ladder = BookLadder::new(OrderSide::Buy, book_type);
1949
1950        let result = ladder.set_batch_state_code(code);
1951
1952        assert_eq!(
1953            result,
1954            Err(CorrectnessError::PredicateViolation {
1955                message: message.to_string(),
1956            })
1957        );
1958        assert_eq!(ladder.batch_state_code(), 0);
1959    }
1960
1961    #[rstest]
1962    fn test_set_batch_state_code_accepts_no_batch_on_non_l1_ladder() {
1963        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L2_MBP);
1964
1965        assert_eq!(ladder.set_batch_state_code(0), Ok(()));
1966        assert_eq!(ladder.batch_state_code(), 0);
1967    }
1968
1969    #[rstest]
1970    fn test_l1_snapshot_vs_mbp_different_accumulation_behavior() {
1971        // F_SNAPSHOT accumulates all levels, F_MBP only accumulates final two
1972        let mut mbp_ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1973        let prices = ["98.00", "99.00", "100.00", "101.00"];
1974        for (i, price_str) in prices.iter().enumerate() {
1975            let order = BookOrder {
1976                side: OrderSide::Buy.into(),
1977                price: Price::from(*price_str),
1978                size: Quantity::from(10),
1979                order_id: (i + 100) as u64,
1980            };
1981            let flags = if i == prices.len() - 1 {
1982                RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8
1983            } else {
1984                RecordFlag::F_MBP as u8
1985            };
1986            mbp_ladder.add(order, flags);
1987        }
1988        assert_eq!(
1989            mbp_ladder.top().unwrap().price.value,
1990            Price::from("101.00"),
1991            "F_MBP keeps best of final two (100, 101)"
1992        );
1993
1994        let mut snapshot_ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
1995
1996        for (i, price_str) in prices.iter().enumerate() {
1997            let order = BookOrder {
1998                side: OrderSide::Buy.into(),
1999                price: Price::from(*price_str),
2000                size: Quantity::from(10),
2001                order_id: (i + 200) as u64,
2002            };
2003            let flags = if i == prices.len() - 1 {
2004                RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2005            } else {
2006                RecordFlag::F_SNAPSHOT as u8
2007            };
2008            snapshot_ladder.add(order, flags);
2009        }
2010        assert_eq!(
2011            snapshot_ladder.top().unwrap().price.value,
2012            Price::from("101.00"),
2013            "F_SNAPSHOT keeps best of ALL deltas (98, 99, 100, 101)"
2014        );
2015    }
2016
2017    #[rstest]
2018    fn test_l1_snapshot_after_incomplete_mbp_stream() {
2019        // Snapshot must clear stale state from incomplete F_MBP stream (no F_LAST sent)
2020        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2021
2022        // Incomplete F_MBP stream leaves stale batch state
2023        let stale_order = BookOrder {
2024            side: OrderSide::Buy.into(),
2025            price: Price::from("101.00"),
2026            size: Quantity::from(10),
2027            order_id: 100,
2028        };
2029        ladder.add(stale_order, RecordFlag::F_MBP as u8);
2030        assert_eq!(ladder.top().unwrap().price.value, Price::from("101.00"));
2031
2032        // Snapshot arrives with Clear delta first
2033        ladder.clear();
2034
2035        // Snapshot prices worse than stale 101
2036        for (i, price_str) in ["98.00", "99.00", "100.00"].iter().enumerate() {
2037            let order = BookOrder {
2038                side: OrderSide::Buy.into(),
2039                price: Price::from(*price_str),
2040                size: Quantity::from(10),
2041                order_id: (i + 200) as u64,
2042            };
2043            let flags = if i == 2 {
2044                RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2045            } else {
2046                RecordFlag::F_SNAPSHOT as u8
2047            };
2048            ladder.add(order, flags);
2049        }
2050
2051        assert_eq!(
2052            ladder.top().unwrap().price.value,
2053            Price::from("100.00"),
2054            "Snapshot replaces stale MBP state: best is 100, not stale 101"
2055        );
2056    }
2057
2058    #[rstest]
2059    fn test_l1_snapshot_clears_previous_batch() {
2060        // New F_SNAPSHOT batch clears previous batch
2061        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2062
2063        for (i, price_str) in ["100.00", "101.00", "102.00"].iter().enumerate() {
2064            let order = BookOrder {
2065                side: OrderSide::Buy.into(),
2066                price: Price::from(*price_str),
2067                size: Quantity::from(10),
2068                order_id: (i + 100) as u64,
2069            };
2070            let flags = if i == 2 {
2071                RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2072            } else {
2073                RecordFlag::F_SNAPSHOT as u8
2074            };
2075            ladder.add(order, flags);
2076        }
2077        assert_eq!(ladder.top().unwrap().price.value, Price::from("102.00"));
2078
2079        // Second batch with worse prices
2080        for (i, price_str) in ["95.00", "96.00", "97.00"].iter().enumerate() {
2081            let order = BookOrder {
2082                side: OrderSide::Buy.into(),
2083                price: Price::from(*price_str),
2084                size: Quantity::from(20),
2085                order_id: (i + 200) as u64,
2086            };
2087            let flags = if i == 2 {
2088                RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2089            } else {
2090                RecordFlag::F_SNAPSHOT as u8
2091            };
2092            ladder.add(order, flags);
2093        }
2094        assert_eq!(
2095            ladder.top().unwrap().price.value,
2096            Price::from("97.00"),
2097            "Second batch clears first: best is 97, not 102"
2098        );
2099    }
2100
2101    #[rstest]
2102    fn test_l1_single_delta_snapshot_after_mbp_batch() {
2103        // Single-delta snapshot (F_SNAPSHOT|F_LAST) must clear stale MBP batch state
2104        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2105
2106        let mbp_order1 = BookOrder {
2107            side: OrderSide::Buy.into(),
2108            price: Price::from("100.00"),
2109            size: Quantity::from(10),
2110            order_id: 1,
2111        };
2112        let mbp_order2 = BookOrder {
2113            side: OrderSide::Buy.into(),
2114            price: Price::from("101.00"),
2115            size: Quantity::from(10),
2116            order_id: 2,
2117        };
2118        ladder.add(mbp_order1, RecordFlag::F_MBP as u8);
2119        ladder.add(
2120            mbp_order2,
2121            RecordFlag::F_MBP as u8 | RecordFlag::F_LAST as u8,
2122        );
2123
2124        assert_eq!(ladder.top().unwrap().price.value, Price::from("101.00"));
2125
2126        // Single-delta snapshot at worse price (no preceding Clear)
2127        let snapshot_order = BookOrder {
2128            side: OrderSide::Buy.into(),
2129            price: Price::from("95.00"),
2130            size: Quantity::from(20),
2131            order_id: 100,
2132        };
2133        ladder.add(
2134            snapshot_order,
2135            RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8,
2136        );
2137
2138        assert_eq!(
2139            ladder.top().unwrap().price.value,
2140            Price::from("95.00"),
2141            "Single-delta snapshot clears MBP state: best is 95, not stale 101"
2142        );
2143        assert_eq!(ladder.len(), 1);
2144    }
2145
2146    #[rstest]
2147    fn test_replace_l1_same_id_updates_price_in_place() {
2148        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2149        let first = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
2150        ladder.replace_l1(first);
2151        assert_eq!(ladder.len(), 1);
2152
2153        let second = BookOrder::new(OrderSide::Buy, Price::from("11.00"), Quantity::from(30), 1);
2154        ladder.replace_l1(second);
2155
2156        assert_eq!(ladder.len(), 1);
2157        let top = ladder.top().unwrap();
2158        assert_eq!(top.price.value, Price::from("11.00"));
2159        assert_eq!(top.len(), 1);
2160        let orders = top.get_orders();
2161        assert_eq!(orders.len(), 1);
2162        assert_eq!(orders[0].order_id, 1);
2163        assert_eq!(orders[0].price, Price::from("11.00"));
2164        assert_eq!(orders[0].size, Quantity::from(30));
2165        assert_eq!(ladder.cache.len(), 1);
2166        assert_eq!(ladder.cache.get(&1).unwrap().value, Price::from("11.00"));
2167    }
2168
2169    #[rstest]
2170    fn test_replace_l1_different_id_falls_back_to_clear_and_add() {
2171        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2172        let first = BookOrder::new(OrderSide::Buy, Price::from("10.00"), Quantity::from(20), 1);
2173        ladder.replace_l1(first);
2174
2175        let second = BookOrder::new(OrderSide::Buy, Price::from("11.00"), Quantity::from(30), 2);
2176        ladder.replace_l1(second);
2177
2178        assert_eq!(ladder.len(), 1);
2179        let top = ladder.top().unwrap();
2180        assert_eq!(top.price.value, Price::from("11.00"));
2181        assert_eq!(top.len(), 1);
2182        let orders = top.get_orders();
2183        assert_eq!(orders.len(), 1);
2184        assert_eq!(orders[0].order_id, 2);
2185        assert_eq!(ladder.cache.len(), 1);
2186        assert!(!ladder.cache.contains_key(&1));
2187        assert_eq!(ladder.cache.get(&2).unwrap().value, Price::from("11.00"));
2188    }
2189
2190    #[rstest]
2191    fn test_replace_l1_multi_order_level_falls_back_to_clear_and_add() {
2192        let mut ladder = BookLadder::new(OrderSide::Buy, BookType::L1_MBP);
2193        let price = BookPrice::new(Price::from("10.00"), OrderSide::Buy);
2194        let mut level = BookLevel::new(price);
2195        level.add(BookOrder::new(
2196            OrderSide::Buy,
2197            Price::from("10.00"),
2198            Quantity::from(20),
2199            1,
2200        ));
2201        level.add(BookOrder::new(
2202            OrderSide::Buy,
2203            Price::from("10.00"),
2204            Quantity::from(25),
2205            2,
2206        ));
2207        ladder.levels.insert(price, level);
2208        ladder.cache.insert(1, price);
2209        ladder.cache.insert(2, price);
2210        assert_eq!(ladder.top().unwrap().len(), 2);
2211
2212        let replacement =
2213            BookOrder::new(OrderSide::Buy, Price::from("11.00"), Quantity::from(30), 1);
2214        ladder.replace_l1(replacement);
2215
2216        assert_eq!(ladder.len(), 1);
2217        let top = ladder.top().unwrap();
2218        assert_eq!(top.price.value, Price::from("11.00"));
2219        assert_eq!(top.len(), 1);
2220        let orders = top.get_orders();
2221        assert_eq!(orders.len(), 1);
2222        assert_eq!(orders[0].order_id, 1);
2223        assert_eq!(ladder.cache.len(), 1);
2224        assert_eq!(ladder.cache.get(&1).unwrap().value, Price::from("11.00"));
2225    }
2226}