nautilus_execution/matching_engine/

ids_generator.rs

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Identifier generation for the order matching engine.

use std::{cell::RefCell, fmt::Debug, rc::Rc};

use nautilus_common::cache::{Cache, VenueOrderIdOwnershipError};
use nautilus_core::{UUID4, UnixNanos};
use nautilus_model::{
    enums::OmsType,
    identifiers::{PositionId, TradeId, Venue, VenueOrderId},
    orders::{Order, OrderAny},
};

// FNV-1a 64-bit constants (see http://www.isthe.com/chongo/tech/comp/fnv/).
const FNV_OFFSET_BASIS: u64 = 0xcbf2_9ce4_8422_2325;
const FNV_PRIME: u64 = 0x0100_0000_01b3;
const HEX_DIGITS: &[u8; 16] = b"0123456789abcdef";
const TRADE_ID_COUNTER_START: usize = 19;

/// Generates venue order, position, and trade identifiers.
pub struct IdsGenerator {
    venue: Venue,
    raw_id: u32,
    oms_type: OmsType,
    use_random_ids: bool,
    use_position_ids: bool,
    cache: Rc<RefCell<Cache>>,
    position_count: usize,
    order_count: usize,
    execution_count: usize,
}

impl Debug for IdsGenerator {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct(stringify!(IdsGenerator))
            .field("venue", &self.venue)
            .field("raw_id", &self.raw_id)
            .finish()
    }
}

impl IdsGenerator {
    /// Creates a new identifier generator.
    pub const fn new(
        venue: Venue,
        oms_type: OmsType,
        raw_id: u32,
        use_random_ids: bool,
        use_position_ids: bool,
        cache: Rc<RefCell<Cache>>,
    ) -> Self {
        Self {
            venue,
            raw_id,
            oms_type,
            cache,
            use_random_ids,
            use_position_ids,
            position_count: 0,
            order_count: 0,
            execution_count: 0,
        }
    }

    /// Resets all identifier counters.
    pub const fn reset(&mut self) {
        self.position_count = 0;
        self.order_count = 0;
        self.execution_count = 0;
    }

    /// Retrieves or generates a unique venue order ID for the given order.
    ///
    /// # Errors
    ///
    /// Returns an error if ID generation fails.
    pub fn get_venue_order_id(&mut self, order: &OrderAny) -> anyhow::Result<VenueOrderId> {
        // Check existing on order
        if let Some(venue_order_id) = order.venue_order_id() {
            return Ok(venue_order_id);
        }

        // Check existing in cache
        if let Some(venue_order_id) = self.cache.borrow().venue_order_id(&order.client_order_id()) {
            return Ok(venue_order_id.to_owned());
        }

        let client_order_id = order.client_order_id();
        let mut conflict_count = 0_usize;

        loop {
            let venue_order_id = self.try_generate_venue_order_id()?;
            let claim_result = self.cache.borrow_mut().add_venue_order_id(
                &client_order_id,
                &venue_order_id,
                false,
            );

            match claim_result {
                Ok(()) => {
                    if conflict_count > 0 {
                        log::info!(
                            "Allocated venue order ID {venue_order_id} for {client_order_id} after \
                             probing past {conflict_count} ownership conflicts"
                        );
                    }

                    return Ok(venue_order_id);
                }
                Err(e) => {
                    let Some(conflict) = e.downcast_ref::<VenueOrderIdOwnershipError>() else {
                        return Err(e);
                    };

                    if conflict_count == 0 {
                        log::error!(
                            "Generated venue order ID conflict: candidate={}, existing_owner={}, \
                             claimant={}",
                            conflict.venue_order_id,
                            conflict.existing_client_order_id,
                            conflict.claimant_client_order_id,
                        );
                    }

                    conflict_count += 1;
                }
            }
        }
    }

    /// Retrieves or generates a position ID for the given order.
    ///
    /// # Panics
    ///
    /// Panics if hedging mode is active, `generate` is `Some(false)`, and no cached position ID is
    /// available.
    pub fn get_position_id(
        &mut self,
        order: &OrderAny,
        generate: Option<bool>,
    ) -> Option<PositionId> {
        let generate = generate.unwrap_or(true);

        if self.oms_type == OmsType::Hedging {
            {
                let cache = self.cache.as_ref().borrow();
                let position_id_result = cache.position_id(&order.client_order_id());
                if let Some(position_id) = position_id_result {
                    return Some(position_id.to_owned());
                }
            }

            if generate {
                self.generate_venue_position_id()
            } else {
                panic!(
                    "Position id should be generated. Hedging Oms type order matching engine doesn't exist in cache."
                )
            }
        } else {
            // Netting OMS (position id will be derived from instrument and strategy)
            let cache = self.cache.as_ref().borrow();
            let positions_open = cache.positions_open(
                None,
                Some(&order.instrument_id()),
                Some(&order.strategy_id()),
                None,
                None,
            );
            positions_open.first().map(|position| position.id)
        }
    }

    /// Advances the execution counter as if a trade ID was generated.
    pub(crate) const fn skip_trade_id(&mut self) {
        self.execution_count += 1;
    }

    /// Generates a deterministic trade ID.
    ///
    /// # Panics
    ///
    /// Panics if overflow checks are enabled and the execution counter overflows, or if the
    /// generated trade ID exceeds 36 characters.
    pub fn generate_trade_id(&mut self, ts_init: UnixNanos) -> TradeId {
        self.execution_count += 1;

        // Trade IDs are always deterministic; `use_random_ids` only affects
        // venue order IDs and position IDs. A bounded FNV-1a hash of
        // `(venue, raw_id, ts_init)` keeps the ID under the 36-character
        // `TradeId` cap for arbitrary-length venue names; `ts_init` protects
        // against collisions after `reset()` rewinds `execution_count`, and
        // the trailing counter distinguishes multiple fills at the same ts.
        let hash = fnv1a_trade_id_hash(self.venue, self.raw_id, ts_init.as_u64());
        let mut value = [0_u8; TRADE_ID_COUNTER_START + usize::BITS as usize];
        value[..2].copy_from_slice(b"T-");

        for (index, byte) in value[2..18].iter_mut().enumerate() {
            let shift = (15 - index) * 4;
            *byte = HEX_DIGITS[((hash >> shift) & 0x0f) as usize];
        }

        value[18] = b'-';

        let mut counter = self.execution_count;
        let mut digit_start = value.len();
        loop {
            digit_start -= 1;
            value[digit_start] = b'0' + (counter % 10) as u8;
            counter /= 10;
            if counter == 0 {
                break;
            }
        }

        let digit_count = value.len() - digit_start;
        let padding = 3_usize.saturating_sub(digit_count);
        let value_len = TRADE_ID_COUNTER_START + padding + digit_count;
        value[TRADE_ID_COUNTER_START..TRADE_ID_COUNTER_START + padding].fill(b'0');
        value.copy_within(digit_start.., TRADE_ID_COUNTER_START + padding);

        let value =
            std::str::from_utf8(&value[..value_len]).expect("trade ID bytes should be valid ASCII");
        TradeId::from(value)
    }

    /// Generates a venue position ID when position IDs are enabled.
    ///
    /// Skips IDs held by cached positions, including closed positions.
    pub fn generate_venue_position_id(&mut self) -> Option<PositionId> {
        if !self.use_position_ids {
            return None;
        }

        loop {
            self.position_count += 1;

            let position_id = if self.use_random_ids {
                PositionId::new(UUID4::new().to_string())
            } else {
                PositionId::new(
                    format!("{}-{}-{}", self.venue, self.raw_id, self.position_count).as_str(),
                )
            };

            if !self.cache.borrow().position_exists(&position_id) {
                return Some(position_id);
            }
        }
    }

    fn try_generate_venue_order_id(&mut self) -> anyhow::Result<VenueOrderId> {
        self.order_count = self
            .order_count
            .checked_add(1)
            .ok_or_else(|| anyhow::anyhow!("Venue order ID counter exhausted"))?;

        if self.use_random_ids {
            Ok(VenueOrderId::new(UUID4::new().to_string()))
        } else {
            Ok(VenueOrderId::new(
                format!("{}-{}-{}", self.venue, self.raw_id, self.order_count).as_str(),
            ))
        }
    }
}

fn fnv1a_trade_id_hash(venue: Venue, raw_id: u32, ts_init_ns: u64) -> u64 {
    let mut hash: u64 = FNV_OFFSET_BASIS;

    for bytes in [
        venue.as_str().as_bytes(),
        b"\x1f",
        &raw_id.to_le_bytes(),
        b"\x1f",
        &ts_init_ns.to_le_bytes(),
    ] {
        for &byte in bytes {
            hash ^= u64::from(byte);
            hash = hash.wrapping_mul(FNV_PRIME);
        }
    }

    hash
}

#[cfg(test)]
mod tests {
    use std::{cell::RefCell, rc::Rc};

    use nautilus_common::cache::{Cache, VenueOrderIdOwnershipError};
    use nautilus_core::{DurationNanos, UnixNanos};
    use nautilus_model::{
        enums::{OmsType, OrderSide, OrderType},
        events::{OrderFilled, order::spec::OrderFilledSpec},
        identifiers::{
            AccountId, ClientOrderId, PositionId, StrategyId, TradeId, Venue, VenueOrderId,
            stubs::account_id,
        },
        instruments::{
            CryptoPerpetual, Instrument, InstrumentAny, stubs::crypto_perpetual_ethusdt,
        },
        orders::{Order, OrderAny, OrderTestBuilder, stubs::TestOrderEventStubs},
        position::Position,
        types::{Price, Quantity},
    };
    use rstest::{fixture, rstest};

    use crate::matching_engine::ids_generator::IdsGenerator;

    #[fixture]
    fn instrument_eth_usdt(crypto_perpetual_ethusdt: CryptoPerpetual) -> InstrumentAny {
        InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt)
    }

    #[fixture]
    fn market_order_buy(instrument_eth_usdt: InstrumentAny) -> OrderAny {
        OrderTestBuilder::new(OrderType::Market)
            .instrument_id(instrument_eth_usdt.id())
            .side(OrderSide::Buy)
            .quantity(Quantity::from("1.000"))
            .client_order_id(ClientOrderId::from("O-19700101-000000-001-001-1"))
            .submit(true)
            .build()
    }

    #[fixture]
    fn market_order_sell(instrument_eth_usdt: InstrumentAny) -> OrderAny {
        OrderTestBuilder::new(OrderType::Market)
            .instrument_id(instrument_eth_usdt.id())
            .side(OrderSide::Sell)
            .quantity(Quantity::from("1.000"))
            .client_order_id(ClientOrderId::from("O-19700101-000000-001-001-2"))
            .submit(true)
            .build()
    }

    #[fixture]
    fn market_order_fill(
        instrument_eth_usdt: InstrumentAny,
        account_id: AccountId,
        market_order_buy: OrderAny,
    ) -> OrderFilled {
        OrderFilledSpec::builder()
            .trader_id(market_order_buy.trader_id())
            .strategy_id(market_order_buy.strategy_id())
            .instrument_id(market_order_buy.instrument_id())
            .client_order_id(market_order_buy.client_order_id())
            .venue_order_id(VenueOrderId::new("BINANCE-1"))
            .account_id(account_id)
            .last_qty(Quantity::from("1"))
            .last_px(Price::from("1000.000"))
            .currency(instrument_eth_usdt.quote_currency())
            .position_id(PositionId::new("P-1"))
            .build()
    }

    fn get_ids_generator(
        cache: Rc<RefCell<Cache>>,
        use_position_ids: bool,
        oms_type: OmsType,
    ) -> IdsGenerator {
        IdsGenerator::new(
            Venue::from("BINANCE"),
            oms_type,
            1,
            false,
            use_position_ids,
            cache,
        )
    }

    #[rstest]
    fn test_get_position_id_hedging_with_existing_position(
        instrument_eth_usdt: InstrumentAny,
        market_order_buy: OrderAny,
        market_order_fill: OrderFilled,
    ) {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let mut ids_generator = get_ids_generator(cache.clone(), false, OmsType::Hedging);

        let position = Position::new(&instrument_eth_usdt, market_order_fill);

        // Add position to cache
        cache
            .borrow_mut()
            .add_position(&position, OmsType::Hedging)
            .unwrap();

        let position_id = ids_generator.get_position_id(&market_order_buy, None);
        assert_eq!(position_id, Some(position.id));
    }

    #[rstest]
    fn test_get_position_id_hedging_with_generated_position(market_order_buy: OrderAny) {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let mut ids_generator = get_ids_generator(cache, true, OmsType::Hedging);

        let position_id = ids_generator.get_position_id(&market_order_buy, None);
        assert_eq!(position_id, Some(PositionId::new("BINANCE-1-1")));
    }

    #[rstest]
    fn test_get_position_id_probes_past_cached_positions(
        instrument_eth_usdt: InstrumentAny,
        market_order_buy: OrderAny,
        market_order_sell: OrderAny,
        market_order_fill: OrderFilled,
        #[values(false, true)] closed: bool,
        #[values(false, true)] reset: bool,
    ) {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let mut generator = get_ids_generator(cache.clone(), true, OmsType::Hedging);

        if reset {
            assert_eq!(
                generator.generate_venue_position_id(),
                Some(PositionId::from("BINANCE-1-1"))
            );
            generator.reset();
        }

        for suffix in [1, 2, 4] {
            let mut fill = market_order_fill.clone();
            fill.position_id = Some(PositionId::from(format!("BINANCE-1-{suffix}")));
            if suffix != 1 {
                fill.client_order_id = ClientOrderId::from(format!("RETAINED-{suffix}"));
            }

            let mut position = Position::new(&instrument_eth_usdt, fill.clone());
            if closed {
                fill.order_side = OrderSide::Sell;
                fill.trade_id = TradeId::from(format!("CLOSE-{suffix}"));
                position.apply(&fill);
            }

            assert_eq!(position.is_closed(), closed);
            cache
                .borrow_mut()
                .add_position(&position, OmsType::Hedging)
                .unwrap();
        }

        let mapped = generator.get_position_id(&market_order_buy, Some(false));
        let first = generator.get_position_id(&market_order_sell, None);
        let next = generator.get_position_id(&market_order_sell, None);

        assert_eq!(mapped, Some(PositionId::from("BINANCE-1-1")));
        assert_eq!(first, Some(PositionId::from("BINANCE-1-3")));
        assert_eq!(next, Some(PositionId::from("BINANCE-1-5")));
        assert_eq!(
            cache
                .borrow()
                .position_id(&market_order_buy.client_order_id()),
            Some(&PositionId::from("BINANCE-1-1"))
        );
    }

    #[rstest]
    fn test_get_position_id_netting(
        instrument_eth_usdt: InstrumentAny,
        market_order_buy: OrderAny,
        market_order_fill: OrderFilled,
    ) {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let mut ids_generator = get_ids_generator(cache.clone(), false, OmsType::Netting);

        // position id should be none in non-initialized position id for this instrument
        let position_id = ids_generator.get_position_id(&market_order_buy, None);
        assert_eq!(position_id, None);

        // create and add position in cache
        let position = Position::new(&instrument_eth_usdt, market_order_fill);
        cache
            .as_ref()
            .borrow_mut()
            .add_position(&position, OmsType::Netting)
            .unwrap();

        // position id should be returned for the existing position
        let position_id = ids_generator.get_position_id(&market_order_buy, None);
        assert_eq!(position_id, Some(position.id));
    }

    #[rstest]
    fn test_get_position_id_netting_filters_by_strategy(
        instrument_eth_usdt: InstrumentAny,
        market_order_fill: OrderFilled,
    ) {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let mut ids_generator = get_ids_generator(cache.clone(), false, OmsType::Netting);
        let position = Position::new(&instrument_eth_usdt, market_order_fill);
        cache
            .as_ref()
            .borrow_mut()
            .add_position(&position, OmsType::Netting)
            .unwrap();

        let order_for_other_strategy = OrderTestBuilder::new(OrderType::Market)
            .instrument_id(instrument_eth_usdt.id())
            .strategy_id(StrategyId::from("S-002"))
            .side(OrderSide::Buy)
            .quantity(Quantity::from("1.000"))
            .client_order_id(ClientOrderId::from("O-19700101-000000-001-001-9"))
            .submit(true)
            .build();

        let position_id = ids_generator.get_position_id(&order_for_other_strategy, None);
        assert_eq!(position_id, None);
    }

    #[rstest]
    fn test_generate_venue_position_id() {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let mut ids_generator_with_position_ids =
            get_ids_generator(cache.clone(), true, OmsType::Netting);
        let mut ids_generator_no_position_ids = get_ids_generator(cache, false, OmsType::Netting);

        assert_eq!(
            ids_generator_no_position_ids.generate_venue_position_id(),
            None
        );

        let position_id_1 = ids_generator_with_position_ids.generate_venue_position_id();
        let position_id_2 = ids_generator_with_position_ids.generate_venue_position_id();
        assert_eq!(position_id_1, Some(PositionId::new("BINANCE-1-1")));
        assert_eq!(position_id_2, Some(PositionId::new("BINANCE-1-2")));
    }

    #[rstest]
    fn test_generate_venue_position_id_random_uses_uuid4_seam() {
        // Pin that the use_random_ids branch routes through the UUID4 seam
        // (RFC 4122 v4) rather than a raw uuid::Uuid::new_v4 call. The seam
        // already swaps to madsim::rand::thread_rng() under cfg(madsim).
        let cache = Rc::new(RefCell::new(Cache::default()));

        let mut generator = IdsGenerator::new(
            Venue::from("BINANCE"),
            OmsType::Netting,
            1,
            true,
            true,
            cache,
        );

        let id = generator.generate_venue_position_id().expect("position id");
        let s = id.as_str();

        assert_eq!(s.len(), 36, "expected canonical UUID4 length");
        assert_eq!(s.as_bytes()[14], b'4', "expected UUID v4 version digit");
        assert!(
            matches!(s.as_bytes()[19], b'8' | b'9' | b'a' | b'b'),
            "expected RFC 4122 variant byte",
        );
    }

    #[rstest]
    fn get_venue_position_id(market_order_buy: OrderAny, market_order_sell: OrderAny) {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let mut ids_generator = get_ids_generator(cache, true, OmsType::Netting);

        let venue_order_id1 = ids_generator.get_venue_order_id(&market_order_buy).unwrap();
        let venue_order_id2 = ids_generator
            .get_venue_order_id(&market_order_sell)
            .unwrap();
        assert_eq!(venue_order_id1, VenueOrderId::from("BINANCE-1-1"));
        assert_eq!(venue_order_id2, VenueOrderId::from("BINANCE-1-2"));

        // check if venue order id is cached again
        let venue_order_id3 = ids_generator.get_venue_order_id(&market_order_buy).unwrap();
        assert_eq!(venue_order_id3, VenueOrderId::from("BINANCE-1-1"));
    }

    #[rstest]
    fn test_get_venue_order_id_probes_past_preclaimed_candidates(market_order_buy: OrderAny) {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let owner_id = ClientOrderId::from("O-OWNER");

        for suffix in 1..=3 {
            cache
                .borrow_mut()
                .add_venue_order_id(
                    &owner_id,
                    &VenueOrderId::from(format!("BINANCE-1-{suffix}")),
                    true,
                )
                .unwrap();
        }

        let mut ids_generator = get_ids_generator(Rc::clone(&cache), true, OmsType::Netting);

        let venue_order_id = ids_generator.get_venue_order_id(&market_order_buy).unwrap();

        assert_eq!(venue_order_id, VenueOrderId::from("BINANCE-1-4"));
        assert_eq!(
            cache
                .borrow()
                .venue_order_id(&market_order_buy.client_order_id()),
            Some(&venue_order_id)
        );

        for suffix in 1..=3 {
            assert_eq!(
                cache
                    .borrow()
                    .client_order_id(&VenueOrderId::from(format!("BINANCE-1-{suffix}"))),
                Some(&owner_id)
            );
        }
    }

    #[rstest]
    fn test_get_venue_order_id_fails_when_counter_is_exhausted(market_order_buy: OrderAny) {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let mut ids_generator = get_ids_generator(Rc::clone(&cache), true, OmsType::Netting);
        ids_generator.order_count = usize::MAX;

        let error = ids_generator
            .get_venue_order_id(&market_order_buy)
            .unwrap_err();

        assert!(error.to_string().contains("counter exhausted"));
        assert_eq!(
            cache
                .borrow()
                .venue_order_id(&market_order_buy.client_order_id()),
            None
        );
    }

    #[rstest]
    fn test_get_venue_order_id_does_not_replace_authoritative_id(mut market_order_buy: OrderAny) {
        let cache = Rc::new(RefCell::new(Cache::default()));
        let venue_order_id = VenueOrderId::from("V-AUTHORITATIVE");
        let owner_id = ClientOrderId::from("O-OWNER");
        cache
            .borrow_mut()
            .add_venue_order_id(&owner_id, &venue_order_id, false)
            .unwrap();
        let accepted = TestOrderEventStubs::accepted(
            &market_order_buy,
            AccountId::from("ACCOUNT-001"),
            venue_order_id,
        );
        market_order_buy.apply(accepted).unwrap();
        let mut ids_generator = get_ids_generator(Rc::clone(&cache), true, OmsType::Netting);

        let returned_id = ids_generator.get_venue_order_id(&market_order_buy).unwrap();
        let error = cache
            .borrow_mut()
            .add_venue_order_id(&market_order_buy.client_order_id(), &returned_id, false)
            .unwrap_err();

        assert_eq!(returned_id, venue_order_id);
        assert!(error.is::<VenueOrderIdOwnershipError>());
        assert_eq!(
            cache.borrow().client_order_id(&venue_order_id),
            Some(&owner_id)
        );
        assert_eq!(
            cache
                .borrow()
                .venue_order_id(&market_order_buy.client_order_id()),
            None
        );
    }

    fn build_ids_generator(venue: Venue, raw_id: u32) -> IdsGenerator {
        let cache = Rc::new(RefCell::new(Cache::default()));
        IdsGenerator::new(venue, OmsType::Netting, raw_id, false, true, cache)
    }

    #[rstest]
    fn test_generate_trade_id_format_and_length_bound() {
        let mut generator =
            build_ids_generator(Venue::from("SOMETHING_VERY_LONG_FOR_SAFETY"), 4_294_967_295);
        let ts = UnixNanos::from(u64::MAX);

        let trade_id = generator.generate_trade_id(ts);
        let value = trade_id.as_str();

        assert!(value.len() <= 36);
        assert!(value.starts_with("T-"));
        assert_eq!(value.len(), "T-0123456789abcdef-001".len());
    }

    #[rstest]
    fn test_generate_trade_id_is_deterministic_across_reset_for_same_ts() {
        let mut generator = build_ids_generator(Venue::from("BINANCE"), 1);
        let ts = UnixNanos::from(1_700_000_000_000_000_000_u64);

        let first = generator.generate_trade_id(ts);
        generator.reset();
        let second = generator.generate_trade_id(ts);
        assert_eq!(
            first, second,
            "same ts_init and reset execution_count must reproduce the same id"
        );
    }

    #[rstest]
    fn test_generate_trade_id_differs_when_ts_init_changes() {
        let mut generator = build_ids_generator(Venue::from("BINANCE"), 1);
        let ts = UnixNanos::from(1_700_000_000_000_000_000_u64);

        let first = generator.generate_trade_id(ts);
        generator.reset();
        let second = generator.generate_trade_id(ts + DurationNanos::new(1));
        assert_ne!(
            first, second,
            "distinct ts_init must produce distinct ids across a reset"
        );
    }

    #[rstest]
    #[case(8, "T-5c080ffb681dc0d4-009")]
    #[case(9, "T-5c080ffb681dc0d4-010")]
    #[case(98, "T-5c080ffb681dc0d4-099")]
    #[case(99, "T-5c080ffb681dc0d4-100")]
    #[case(998, "T-5c080ffb681dc0d4-999")]
    #[case(999, "T-5c080ffb681dc0d4-1000")]
    fn test_generate_trade_id_counter_width(
        #[case] execution_count: usize,
        #[case] expected: &str,
    ) {
        let mut generator = build_ids_generator(Venue::from("BINANCE"), 1);
        generator.execution_count = execution_count;

        let trade_id = generator.generate_trade_id(UnixNanos::from(1_700_000_000_000_000_000_u64));

        assert_eq!(trade_id.as_str(), expected);
    }

    #[rstest]
    fn test_generate_trade_id_preserves_full_lowercase_hash_width() {
        let mut generator = build_ids_generator(Venue::from("BINANCE"), 0);

        let trade_id = generator.generate_trade_id(UnixNanos::from(3));

        assert_eq!(trade_id.as_str(), "T-0114760c17a06c2c-001");
    }

    #[cfg(target_pointer_width = "64")]
    #[rstest]
    fn test_generate_trade_id_accepts_maximum_length() {
        let mut generator = build_ids_generator(Venue::from("BINANCE"), 1);
        generator.execution_count = 99_999_999_999_999_998;

        let trade_id = generator.generate_trade_id(UnixNanos::from(1_700_000_000_000_000_000_u64));

        assert_eq!(trade_id.as_str(), "T-5c080ffb681dc0d4-99999999999999999");
        assert_eq!(trade_id.as_str().len(), 36);
    }

    #[cfg(target_pointer_width = "64")]
    #[rstest]
    #[case(99_999_999_999_999_999, 37)]
    #[case(9_999_999_999_999_999_998, 38)]
    #[case(usize::MAX - 1, 39)]
    fn test_generate_trade_id_preserves_length_validation(
        #[case] execution_count: usize,
        #[case] expected_length: usize,
    ) {
        let mut generator = build_ids_generator(Venue::from("BINANCE"), 1);
        generator.execution_count = execution_count;
        let panic = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            generator.generate_trade_id(UnixNanos::from(1_700_000_000_000_000_000_u64));
        }))
        .expect_err("an oversized trade ID should fail validation");

        let message = panic
            .downcast_ref::<String>()
            .map(String::as_str)
            .or_else(|| panic.downcast_ref::<&str>().copied())
            .expect("trade ID validation should panic with a string message");

        assert!(
            message.contains(&format!(
                "String exceeds maximum length of 36 characters, was {expected_length}"
            )),
            "unexpected trade ID validation panic: {message}",
        );
        assert_eq!(generator.execution_count, execution_count + 1);

        generator.reset();
        let trade_id = generator.generate_trade_id(UnixNanos::from(1_700_000_000_000_000_000_u64));
        assert_eq!(trade_id.as_str(), "T-5c080ffb681dc0d4-001");
    }

    #[rstest]
    fn test_skip_trade_id_matches_a_generated_trade_id() {
        let ts_init = UnixNanos::from(1_700_000_000_000_000_000_u64);
        let mut generated = build_ids_generator(Venue::from("BINANCE"), 1);
        let mut skipped = build_ids_generator(Venue::from("BINANCE"), 1);

        generated.generate_trade_id(ts_init);
        skipped.skip_trade_id();

        assert_eq!(
            skipped.generate_trade_id(ts_init),
            generated.generate_trade_id(ts_init)
        );
    }

    #[rstest]
    fn test_generate_trade_id_preserves_counter_overflow_semantics() {
        let expected = std::panic::catch_unwind(|| {
            let mut counter = std::hint::black_box(usize::MAX);
            counter += 1;
            counter
        });

        let mut generator = build_ids_generator(Venue::from("BINANCE"), 1);
        generator.execution_count = usize::MAX;
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            generator.generate_trade_id(UnixNanos::from(1_700_000_000_000_000_000_u64))
        }));

        match (expected, result) {
            (Ok(expected_count), Ok(trade_id)) => {
                assert_eq!(trade_id.as_str(), "T-5c080ffb681dc0d4-000");
                assert_eq!(generator.execution_count, expected_count);
            }
            (Err(_), Err(panic)) => {
                let message = panic
                    .downcast_ref::<String>()
                    .map(String::as_str)
                    .or_else(|| panic.downcast_ref::<&str>().copied())
                    .expect("counter overflow should panic with a string message");

                assert!(
                    message.contains("attempt to add with overflow"),
                    "unexpected execution counter overflow panic: {message}",
                );
                assert_eq!(generator.execution_count, usize::MAX);
            }
            (Ok(_), Err(_)) => panic!("execution counter unexpectedly used checked overflow"),
            (Err(_), Ok(_)) => panic!("execution counter unexpectedly used unchecked overflow"),
        }
    }

    #[rstest]
    fn test_generate_trade_id_differs_when_venue_or_raw_id_changes() {
        let ts = UnixNanos::from(1_700_000_000_000_000_000_u64);

        let mut gen_a = build_ids_generator(Venue::from("BINANCE"), 1);
        let mut gen_b = build_ids_generator(Venue::from("BYBIT"), 1);
        let mut gen_c = build_ids_generator(Venue::from("BINANCE"), 2);

        let a = gen_a.generate_trade_id(ts);
        let b = gen_b.generate_trade_id(ts);
        let c = gen_c.generate_trade_id(ts);
        assert_ne!(a, b, "venue must distinguish ids");
        assert_ne!(a, c, "raw_id must distinguish ids");
    }

    // Parity fixtures: if either Rust or Python changes the hashing scheme,
    // one of these assertions will fail and flag the drift.
    // The Python mirror lives at python/tests/unit/backtest/test_trade_id_parity.py
    #[rstest]
    #[case::zero("BINANCE", 1_u32, 0_u64, "T-59d6cf33c843f0cc-001")]
    #[case::nanos(
        "BINANCE",
        1_u32,
        1_700_000_000_000_000_000_u64,
        "T-5c080ffb681dc0d4-001"
    )]
    #[case::long_venue(
        "SOMETHING_VERY_LONG_FOR_SAFETY",
        42_u32,
        1_700_000_000_000_000_000_u64,
        "T-2a2238c5cc0cbaf2-001"
    )]
    fn test_generate_trade_id_matches_python_parity_fixture(
        #[case] venue: &str,
        #[case] raw_id: u32,
        #[case] ts_init: u64,
        #[case] expected: &str,
    ) {
        let mut generator = build_ids_generator(Venue::from(venue), raw_id);
        let trade_id = generator.generate_trade_id(UnixNanos::from(ts_init));
        assert_eq!(trade_id.as_str(), expected);
    }

    // Multi-tick parity: four consecutive bumps at the same ts_init (the
    // bar O/H/L/C pattern) must produce counters 001..004. Mirrored in
    // tests/unit_tests/backtest/test_trade_id_parity.py
    // (test_trade_id_multi_tick_counter_matches_rust_parity_fixture).
    #[rstest]
    fn test_generate_trade_id_multi_tick_matches_python_parity_fixture() {
        let mut generator = build_ids_generator(Venue::from("BINANCE"), 1);
        let ts = UnixNanos::from(1_700_000_000_000_000_000_u64);
        let sequence: Vec<String> = (0..4)
            .map(|_| generator.generate_trade_id(ts).as_str().to_string())
            .collect();

        assert_eq!(
            sequence,
            vec![
                "T-5c080ffb681dc0d4-001".to_string(),
                "T-5c080ffb681dc0d4-002".to_string(),
                "T-5c080ffb681dc0d4-003".to_string(),
                "T-5c080ffb681dc0d4-004".to_string(),
            ],
        );
    }
}