nautilus-model 0.62.0

// -------------------------------------------------------------------------------------------------
//  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.
// -------------------------------------------------------------------------------------------------

//! Standardized reasons for local order denial.
//!
//! [`OrderDeniedReason`] is the single source of truth for the `CATEGORY_CONDITION` codes
//! attached to [`OrderDenied`](super::denied::OrderDenied) events. Each variant renders, via
//! [`std::fmt::Display`], to a message whose leading token is the stable code, followed when
//! applicable by the diagnostic suffix documented on [`OrderDeniedReason`]. The companion
//! [`OrderDeniedCode`] enum (generated by `strum`) enumerates the codes without their per-denial
//! context, so documentation and grouping can iterate the closed set.

use rust_decimal::Decimal;
use strum::{AsRefStr, Display, EnumDiscriminants, EnumIter, EnumString};
use thiserror::Error;

use crate::{
    enums::{OrderSide, OrderType, TimeInForce, TrailingOffsetType},
    identifiers::{ClientId, InstrumentId, OrderListId, PositionId, Venue},
    types::{Money, Price, Quantity},
};

/// The order price field being validated.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Display)]
#[strum(serialize_all = "SCREAMING_SNAKE_CASE")]
pub enum OrderPriceField {
    /// The order's `price` field.
    Price,
    /// The order's `trigger_price` field.
    TriggerPrice,
}

/// A standardized reason an order was denied locally by the Nautilus system.
///
/// A denial is a local rejection: the order never reached a venue. Each variant carries the
/// context needed to render its message and maps to a stable [`OrderDeniedCode`].
///
/// Rendered messages use these forms:
///
/// - `CODE` when the denial needs no diagnostic suffix.
/// - `CODE: value` for one typed value or an opaque diagnostic detail.
/// - `CODE: key=value, key=value` when multiple typed values need disambiguation.
/// - `CODE: value; free text` when one typed value precedes an opaque detail.
///
/// Only the leading code is canonical. Consumers must not recover classification or control flow
/// from the diagnostic suffix.
///
/// Variants progress from direct field checks and required context through single-order,
/// cumulative, policy, routing, and downstream validation failures. Declaration order does not
/// define validation precedence.
#[derive(Debug, Clone, PartialEq, Eq, Error, EnumDiscriminants)]
#[strum_discriminants(
    name(OrderDeniedCode),
    derive(Display, AsRefStr, EnumIter, EnumString),
    strum(serialize_all = "SCREAMING_SNAKE_CASE")
)]
pub enum OrderDeniedReason {
    /// The price precision exceeds the instrument maximum.
    #[error(
        "PRICE_PRECISION_EXCEEDS_MAXIMUM: field={field}, price={price}, precision={price_precision}, max_precision={max_precision}"
    )]
    PricePrecisionExceedsMaximum {
        /// The price field being validated.
        field: OrderPriceField,
        /// The submitted price.
        price: Price,
        /// The submitted price precision.
        price_precision: u8,
        /// The instrument's maximum price precision.
        max_precision: u8,
    },
    /// The price is not positive for an instrument that disallows negative prices.
    #[error("PRICE_NOT_POSITIVE: field={field}, price={price}")]
    PriceNotPositive {
        /// The price field being validated.
        field: OrderPriceField,
        /// The submitted price.
        price: Price,
    },
    /// The quantity precision exceeds the instrument maximum.
    #[error(
        "QUANTITY_PRECISION_EXCEEDS_MAXIMUM: quantity={quantity}, precision={quantity_precision}, max_precision={max_precision}"
    )]
    QuantityPrecisionExceedsMaximum {
        /// The submitted quantity.
        quantity: Quantity,
        /// The submitted quantity precision.
        quantity_precision: u8,
        /// The instrument's maximum quantity precision.
        max_precision: u8,
    },
    /// The order quantity could not be converted for risk checks.
    #[error("QUANTITY_CONVERSION_FAILED: {detail}")]
    QuantityConversionFailed {
        /// The underlying conversion error.
        detail: String,
    },
    /// The effective order quantity exceeds the instrument maximum.
    #[error("QUANTITY_EXCEEDS_MAXIMUM: effective={effective_quantity}, max={max_quantity}")]
    QuantityExceedsMaximum {
        /// The order quantity after any quote-to-base conversion.
        effective_quantity: Quantity,
        /// The instrument's maximum tradable quantity.
        max_quantity: Quantity,
    },
    /// The effective order quantity is below the instrument minimum.
    #[error("QUANTITY_BELOW_MINIMUM: effective={effective_quantity}, min={min_quantity}")]
    QuantityBelowMinimum {
        /// The order quantity after any quote-to-base conversion.
        effective_quantity: Quantity,
        /// The instrument's minimum tradable quantity.
        min_quantity: Quantity,
    },

    /// The configured maximum notional per order is invalid.
    #[error("INVALID_MAX_NOTIONAL_PER_ORDER: instrument_id={instrument_id}, value={value}")]
    InvalidMaxNotionalPerOrder {
        /// The instrument the setting applies to.
        instrument_id: InstrumentId,
        /// The invalid configured value.
        value: Decimal,
    },
    /// The order side is invalid for this operation.
    #[error("INVALID_ORDER_SIDE: {order_side}")]
    InvalidOrderSide {
        /// The offending order side.
        order_side: OrderSide,
    },
    /// A GTD order is missing its expire time.
    #[error("MISSING_EXPIRE_TIME")]
    MissingExpireTime,
    /// The order's expire time is in the past.
    #[error("EXPIRE_TIME_IN_PAST: {expire_time}")]
    ExpireTimeInPast {
        /// The expire time that has already elapsed.
        expire_time: String,
    },
    /// The order is missing a required trailing offset type.
    #[error("MISSING_TRAILING_OFFSET_TYPE")]
    MissingTrailingOffsetType,
    /// The order's trailing offset type is not supported.
    #[error("UNSUPPORTED_TRAILING_OFFSET_TYPE: {offset_type}")]
    UnsupportedTrailingOffsetType {
        /// The unsupported trailing offset type.
        offset_type: TrailingOffsetType,
    },
    /// The order is missing a required trigger type.
    #[error("MISSING_TRIGGER_TYPE")]
    MissingTriggerType,
    /// The order is missing a required trailing offset.
    #[error("MISSING_TRAILING_OFFSET")]
    MissingTrailingOffset,

    /// The instrument was not found in the cache.
    #[error("INSTRUMENT_NOT_FOUND: {instrument_id}")]
    InstrumentNotFound {
        /// The instrument that was not found.
        instrument_id: InstrumentId,
    },
    /// The position for a reduce-only order was not found.
    #[error("POSITION_NOT_FOUND: {position_id}")]
    PositionNotFound {
        /// The position that was not found.
        position_id: PositionId,
    },
    /// No market price is available for the order risk check.
    #[error("MARKET_PRICE_UNAVAILABLE: order_type={order_type}, instrument_id={instrument_id}")]
    MarketPriceUnavailable {
        /// The order type requiring a market price.
        order_type: OrderType,
        /// The instrument with no available market price.
        instrument_id: InstrumentId,
    },

    /// The trailing stop trigger price could not be calculated.
    #[error("TRAILING_STOP_CALCULATION_FAILED: {detail}")]
    TrailingStopCalculationFailed {
        /// The underlying calculation error.
        detail: String,
    },
    /// The order notional value could not be calculated.
    #[error("NOTIONAL_CALCULATION_FAILED: {detail}")]
    NotionalCalculationFailed {
        /// The underlying calculation error.
        detail: String,
    },
    /// The order notional is below the instrument minimum.
    #[error("NOTIONAL_BELOW_MINIMUM: min={min_notional}, notional={notional}")]
    NotionalBelowMinimum {
        /// The instrument's minimum notional.
        min_notional: Money,
        /// The order's notional value.
        notional: Money,
    },
    /// The order notional exceeds the instrument maximum.
    #[error("NOTIONAL_EXCEEDS_MAXIMUM: max={max_notional}, notional={notional}")]
    NotionalExceedsMaximum {
        /// The instrument's maximum notional.
        max_notional: Money,
        /// The order's notional value.
        notional: Money,
    },
    /// The order notional exceeds the configured maximum per order.
    #[error("NOTIONAL_EXCEEDS_MAX_PER_ORDER: max={max_notional}, notional={notional}")]
    NotionalExceedsMaxPerOrder {
        /// The configured maximum notional per order.
        max_notional: Money,
        /// The order's notional value.
        notional: Money,
    },
    /// The order notional exceeds the account free balance.
    #[error("NOTIONAL_EXCEEDS_FREE_BALANCE: free={free_balance}, notional={notional}")]
    NotionalExceedsFreeBalance {
        /// The account's free balance.
        free_balance: Money,
        /// The order's notional value.
        notional: Money,
    },
    /// The order initial margin could not be calculated.
    #[error("INITIAL_MARGIN_CALCULATION_FAILED: {detail}")]
    InitialMarginCalculationFailed {
        /// The underlying calculation error.
        detail: String,
    },
    /// The order initial margin exceeds the account free balance.
    #[error("INITIAL_MARGIN_EXCEEDS_FREE_BALANCE: free={free_balance}, margin={initial_margin}")]
    InitialMarginExceedsFreeBalance {
        /// The account's free balance.
        free_balance: Money,
        /// The initial margin required for the order.
        initial_margin: Money,
    },
    /// The balance to lock for the betting order could not be calculated.
    #[error("BETTING_BALANCE_LOCKED_CALCULATION_FAILED: {detail}")]
    BettingBalanceLockedCalculationFailed {
        /// The underlying calculation error.
        detail: String,
    },

    /// The cumulative order notional exceeds the account free balance.
    #[error(
        "CUMULATIVE_NOTIONAL_EXCEEDS_FREE_BALANCE: free={free_balance}, notional={cumulative_notional}"
    )]
    CumulativeNotionalExceedsFreeBalance {
        /// The account's free balance.
        free_balance: Money,
        /// The cumulative notional across the checked orders.
        cumulative_notional: Money,
    },
    /// The cumulative initial margin could not be calculated.
    #[error("CUMULATIVE_INITIAL_MARGIN_CALCULATION_FAILED: {detail}")]
    CumulativeInitialMarginCalculationFailed {
        /// The underlying calculation error.
        detail: String,
    },
    /// The cumulative initial margin exceeds the account free balance.
    #[error(
        "CUMULATIVE_INITIAL_MARGIN_EXCEEDS_FREE_BALANCE: free={free_balance}, margin={cumulative_initial_margin}"
    )]
    CumulativeInitialMarginExceedsFreeBalance {
        /// The account's free balance.
        free_balance: Money,
        /// The cumulative initial margin across the checked orders.
        cumulative_initial_margin: Money,
    },

    /// A reduce-only order would increase the position.
    #[error("REDUCE_ONLY_WOULD_INCREASE_POSITION: {position_id}")]
    ReduceOnlyWouldIncreasePosition {
        /// The position the order would increase.
        position_id: PositionId,
    },
    /// The order list is missing orders in the cache.
    #[error("ORDER_LIST_INCOMPLETE: {order_list_id}")]
    OrderListIncomplete {
        /// The order list with missing orders.
        order_list_id: OrderListId,
    },
    /// The order was denied because its order list failed risk checks.
    #[error("ORDER_LIST_DENIED: {order_list_id}")]
    OrderListDenied {
        /// The order list that failed risk checks.
        order_list_id: OrderListId,
    },
    /// Trading is halted; new orders are denied.
    #[error("TRADING_HALTED")]
    TradingHalted,
    /// Trading is reducing; the order would increase exposure.
    #[error("TRADING_STATE_REDUCING: side={order_side}, instrument_id={instrument_id}")]
    TradingStateReducing {
        /// The side of the order that would increase exposure.
        order_side: OrderSide,
        /// The instrument the order applies to.
        instrument_id: InstrumentId,
    },
    /// The order submission rate limit was exceeded.
    #[error("RATE_LIMIT_EXCEEDED")]
    RateLimitExceeded,
    /// The execution stream is unavailable or recovering; retry after recovery.
    #[error("STREAM_RECONCILING: execution stream unavailable or recovering, retry after recovery")]
    StreamReconciling,

    /// No execution client was found for the routed command.
    #[error(
        "NO_EXECUTION_CLIENT: client_id={client}, {routing_context}",
        client = .client_id.as_ref().map_or("NONE", ClientId::as_str),
    )]
    NoExecutionClient {
        /// The explicitly requested client, if one was supplied.
        client_id: Option<ClientId>,
        /// The routing context used to look up an execution client.
        routing_context: String,
    },
    /// The execution client does not handle the order venue.
    #[error(
        "CLIENT_VENUE_MISMATCH: client_id={client_id}, order_venue={order_venue}, client_venue={client_venue}"
    )]
    ClientVenueMismatch {
        /// The routed execution client.
        client_id: ClientId,
        /// The order venue.
        order_venue: Venue,
        /// The execution client's venue.
        client_venue: Venue,
    },
    /// Submitting the order to the execution client failed.
    #[error("SUBMIT_FAILED: {detail}")]
    SubmitFailed {
        /// The underlying submission error.
        detail: String,
    },

    /// The client order ID is invalid for the venue.
    #[error("INVALID_CLIENT_ORDER_ID: {detail}")]
    InvalidClientOrderId {
        /// The validation failure detail.
        detail: String,
    },
    /// The supplied position ID is invalid for the order submission.
    #[error("INVALID_POSITION_ID: {position_id}; {detail}")]
    InvalidPositionId {
        /// The invalid position ID.
        position_id: PositionId,
        /// The validation failure detail.
        detail: String,
    },
    /// The venue does not support the requested order list.
    #[error("UNSUPPORTED_ORDER_LIST: {detail}")]
    UnsupportedOrderList {
        /// The reason the order list is unsupported.
        detail: String,
    },
    /// The order type is not supported.
    #[error("UNSUPPORTED_ORDER_TYPE: {order_type}")]
    UnsupportedOrderType {
        /// The unsupported order type.
        order_type: OrderType,
    },
    /// The order's time in force is not supported.
    #[error("UNSUPPORTED_TIME_IN_FORCE: {0}")]
    UnsupportedTimeInForce(TimeInForce),
    /// The venue does not support the requested take-profit/stop-loss parameters.
    #[error("UNSUPPORTED_TP_SL: {detail}")]
    UnsupportedTpSl {
        /// The reason the take-profit/stop-loss parameters are unsupported.
        detail: String,
    },
    /// The order failed validation before submission.
    #[error("VALIDATION_FAILED: {detail}")]
    ValidationFailed {
        /// The validation failure detail.
        detail: String,
    },
}

impl OrderDeniedCode {
    /// Returns a one-line description of this denial code.
    #[must_use]
    pub fn description(&self) -> &'static str {
        match self {
            Self::PricePrecisionExceedsMaximum => {
                "The price precision exceeds the instrument maximum."
            }
            Self::PriceNotPositive => "The price is not positive.",
            Self::QuantityPrecisionExceedsMaximum => {
                "The quantity precision exceeds the instrument maximum."
            }
            Self::QuantityConversionFailed => {
                "The order quantity could not be converted for risk checks."
            }
            Self::QuantityExceedsMaximum => {
                "The effective order quantity exceeds the instrument maximum."
            }
            Self::QuantityBelowMinimum => {
                "The effective order quantity is below the instrument minimum."
            }
            Self::InvalidMaxNotionalPerOrder => {
                "The configured maximum notional per order is invalid."
            }
            Self::InvalidOrderSide => "The order side is invalid for this operation.",
            Self::MissingExpireTime => "A GTD order is missing its expire time.",
            Self::ExpireTimeInPast => "The order's expire time is in the past.",
            Self::MissingTrailingOffsetType => {
                "The order is missing a required trailing offset type."
            }
            Self::UnsupportedTrailingOffsetType => {
                "The order's trailing offset type is not supported."
            }
            Self::MissingTriggerType => "The order is missing a required trigger type.",
            Self::MissingTrailingOffset => "The order is missing a required trailing offset.",
            Self::InstrumentNotFound => "The instrument was not found in the cache.",
            Self::PositionNotFound => "The position for a reduce‑only order was not found.",
            Self::MarketPriceUnavailable => {
                "No market price is available for the order risk check."
            }
            Self::TrailingStopCalculationFailed => {
                "The trailing stop trigger price could not be calculated."
            }
            Self::NotionalCalculationFailed => "The order notional value could not be calculated.",
            Self::NotionalBelowMinimum => "The order notional is below the instrument minimum.",
            Self::NotionalExceedsMaximum => "The order notional exceeds the instrument maximum.",
            Self::NotionalExceedsMaxPerOrder => {
                "The order notional exceeds the configured maximum per order."
            }
            Self::NotionalExceedsFreeBalance => {
                "The order notional exceeds the account free balance."
            }
            Self::InitialMarginCalculationFailed => {
                "The order initial margin could not be calculated."
            }
            Self::InitialMarginExceedsFreeBalance => {
                "The order initial margin exceeds the account free balance."
            }
            Self::BettingBalanceLockedCalculationFailed => {
                "The balance to lock for the betting order could not be calculated."
            }
            Self::CumulativeNotionalExceedsFreeBalance => {
                "The cumulative order notional exceeds the account free balance."
            }
            Self::CumulativeInitialMarginCalculationFailed => {
                "The cumulative initial margin could not be calculated."
            }
            Self::CumulativeInitialMarginExceedsFreeBalance => {
                "The cumulative initial margin exceeds the account free balance."
            }
            Self::ReduceOnlyWouldIncreasePosition => {
                "A reduce‑only order would increase the position."
            }
            Self::OrderListIncomplete => "The order list is missing orders in the cache.",
            Self::OrderListDenied => {
                "The order was denied because its order list failed risk checks."
            }
            Self::TradingHalted => "Trading is halted; new orders are denied.",
            Self::TradingStateReducing => "Trading is reducing; the order would increase exposure.",
            Self::RateLimitExceeded => "The order submission rate limit was exceeded.",
            Self::StreamReconciling => {
                "The execution stream is unavailable or recovering; retry after recovery."
            }
            Self::NoExecutionClient => "No execution client was found for the routed command.",
            Self::ClientVenueMismatch => "The execution client does not handle the order venue.",
            Self::SubmitFailed => "Submitting the order to the execution client failed.",
            Self::InvalidClientOrderId => "The client order ID is invalid for the venue.",
            Self::InvalidPositionId => {
                "The supplied position ID is invalid for the order submission."
            }
            Self::UnsupportedOrderList => "The venue does not support the requested order list.",
            Self::UnsupportedOrderType => "The order type is not supported.",
            Self::UnsupportedTimeInForce => "The order's time in force is not supported.",
            Self::UnsupportedTpSl => {
                "The venue does not support the requested take‑profit/stop‑loss parameters."
            }
            Self::ValidationFailed => "The order failed validation before submission.",
        }
    }
}

#[cfg(test)]
mod tests {
    use rstest::rstest;
    use strum::IntoEnumIterator;

    use super::*;

    const DOC_PATH: &str = concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../docs/concepts/execution.md"
    );
    const BLOCK_BEGIN: &str = "<!-- BEGIN GENERATED: order-denied-reasons -->";
    const BLOCK_END: &str = "<!-- END GENERATED: order-denied-reasons -->";

    #[rstest]
    fn renders_subject_led_messages() {
        let exceeds = OrderDeniedReason::QuantityExceedsMaximum {
            effective_quantity: Quantity::from("15"),
            max_quantity: Quantity::from("10"),
        };
        let below = OrderDeniedReason::QuantityBelowMinimum {
            effective_quantity: Quantity::from("1"),
            min_quantity: Quantity::from("5"),
        };
        let notional = OrderDeniedReason::NotionalBelowMinimum {
            min_notional: Money::from("1.00 USD"),
            notional: Money::from("0.90 USD"),
        };

        assert_eq!(
            exceeds.to_string(),
            "QUANTITY_EXCEEDS_MAXIMUM: effective=15, max=10"
        );
        assert_eq!(
            below.to_string(),
            "QUANTITY_BELOW_MINIMUM: effective=1, min=5"
        );
        assert_eq!(
            notional.to_string(),
            "NOTIONAL_BELOW_MINIMUM: min=1.00 USD, notional=0.90 USD"
        );
    }

    #[rstest]
    fn renders_standardized_risk_messages() {
        assert_eq!(
            OrderDeniedReason::PricePrecisionExceedsMaximum {
                field: OrderPriceField::Price,
                price: Price::from("1.234"),
                price_precision: 3,
                max_precision: 2,
            }
            .to_string(),
            "PRICE_PRECISION_EXCEEDS_MAXIMUM: field=PRICE, price=1.234, precision=3, max_precision=2"
        );
        assert_eq!(
            OrderDeniedReason::PriceNotPositive {
                field: OrderPriceField::TriggerPrice,
                price: Price::from("-0.1"),
            }
            .to_string(),
            "PRICE_NOT_POSITIVE: field=TRIGGER_PRICE, price=-0.1"
        );
        assert_eq!(
            OrderDeniedReason::QuantityConversionFailed {
                detail: "value exceeds MoneyRaw bounds".to_string(),
            }
            .to_string(),
            "QUANTITY_CONVERSION_FAILED: value exceeds MoneyRaw bounds"
        );
        assert_eq!(
            OrderDeniedReason::UnsupportedTrailingOffsetType {
                offset_type: TrailingOffsetType::PriceTier,
            }
            .to_string(),
            "UNSUPPORTED_TRAILING_OFFSET_TYPE: PRICE_TIER"
        );
        assert_eq!(
            OrderDeniedReason::NotionalCalculationFailed {
                detail: "value exceeds Money bounds".to_string(),
            }
            .to_string(),
            "NOTIONAL_CALCULATION_FAILED: value exceeds Money bounds"
        );
        assert_eq!(
            OrderDeniedReason::InitialMarginCalculationFailed {
                detail: "margin model unavailable".to_string(),
            }
            .to_string(),
            "INITIAL_MARGIN_CALCULATION_FAILED: margin model unavailable"
        );
        assert_eq!(
            OrderDeniedReason::NotionalExceedsMaxPerOrder {
                max_notional: Money::from("10.00 USD"),
                notional: Money::from("11.00 USD"),
            }
            .to_string(),
            "NOTIONAL_EXCEEDS_MAX_PER_ORDER: max=10.00 USD, notional=11.00 USD"
        );
        assert_eq!(
            OrderDeniedReason::NotionalExceedsMaximum {
                max_notional: Money::from("12.00 USD"),
                notional: Money::from("13.00 USD"),
            }
            .to_string(),
            "NOTIONAL_EXCEEDS_MAXIMUM: max=12.00 USD, notional=13.00 USD"
        );
        assert_eq!(
            OrderDeniedReason::NotionalExceedsFreeBalance {
                free_balance: Money::from("10.00 USD"),
                notional: Money::from("11.00 USD"),
            }
            .to_string(),
            "NOTIONAL_EXCEEDS_FREE_BALANCE: free=10.00 USD, notional=11.00 USD"
        );
        assert_eq!(
            OrderDeniedReason::CumulativeNotionalExceedsFreeBalance {
                free_balance: Money::from("10.00 USD"),
                cumulative_notional: Money::from("12.00 USD"),
            }
            .to_string(),
            "CUMULATIVE_NOTIONAL_EXCEEDS_FREE_BALANCE: free=10.00 USD, notional=12.00 USD"
        );
        assert_eq!(
            OrderDeniedReason::InitialMarginExceedsFreeBalance {
                free_balance: Money::from("10.00 USD"),
                initial_margin: Money::from("13.00 USD"),
            }
            .to_string(),
            "INITIAL_MARGIN_EXCEEDS_FREE_BALANCE: free=10.00 USD, margin=13.00 USD"
        );
        assert_eq!(
            OrderDeniedReason::CumulativeInitialMarginExceedsFreeBalance {
                free_balance: Money::from("10.00 USD"),
                cumulative_initial_margin: Money::from("14.00 USD"),
            }
            .to_string(),
            "CUMULATIVE_INITIAL_MARGIN_EXCEEDS_FREE_BALANCE: free=10.00 USD, margin=14.00 USD"
        );
        assert_eq!(
            OrderDeniedReason::CumulativeInitialMarginCalculationFailed {
                detail: "total exceeds Money bounds".to_string(),
            }
            .to_string(),
            "CUMULATIVE_INITIAL_MARGIN_CALCULATION_FAILED: total exceeds Money bounds"
        );
        assert_eq!(
            OrderDeniedReason::BettingBalanceLockedCalculationFailed {
                detail: "invalid liability".to_string(),
            }
            .to_string(),
            "BETTING_BALANCE_LOCKED_CALCULATION_FAILED: invalid liability"
        );
        assert_eq!(
            OrderDeniedReason::TrailingStopCalculationFailed {
                detail: "missing market price".to_string(),
            }
            .to_string(),
            "TRAILING_STOP_CALCULATION_FAILED: missing market price"
        );
    }

    #[rstest]
    fn renders_lifecycle_and_state_messages() {
        let not_found = OrderDeniedReason::InstrumentNotFound {
            instrument_id: InstrumentId::from("AUD/USD.SIM"),
        };
        let bad_side = OrderDeniedReason::InvalidOrderSide {
            order_side: OrderSide::NoOrderSide,
        };
        let reducing = OrderDeniedReason::TradingStateReducing {
            order_side: OrderSide::Buy,
            instrument_id: InstrumentId::from("AUD/USD.SIM"),
        };

        assert_eq!(not_found.to_string(), "INSTRUMENT_NOT_FOUND: AUD/USD.SIM");
        assert_eq!(
            OrderDeniedReason::ExpireTimeInPast {
                expire_time: "1970-01-01T00:00:00Z".to_string(),
            }
            .to_string(),
            "EXPIRE_TIME_IN_PAST: 1970-01-01T00:00:00Z"
        );
        assert_eq!(
            OrderDeniedReason::PositionNotFound {
                position_id: PositionId::from("P-1"),
            }
            .to_string(),
            "POSITION_NOT_FOUND: P-1"
        );
        assert_eq!(
            OrderDeniedReason::ReduceOnlyWouldIncreasePosition {
                position_id: PositionId::from("P-2"),
            }
            .to_string(),
            "REDUCE_ONLY_WOULD_INCREASE_POSITION: P-2"
        );
        assert_eq!(
            OrderDeniedReason::OrderListIncomplete {
                order_list_id: OrderListId::from("OL-1"),
            }
            .to_string(),
            "ORDER_LIST_INCOMPLETE: OL-1"
        );
        assert_eq!(
            OrderDeniedReason::OrderListDenied {
                order_list_id: OrderListId::from("OL-2"),
            }
            .to_string(),
            "ORDER_LIST_DENIED: OL-2"
        );
        assert_eq!(bad_side.to_string(), "INVALID_ORDER_SIDE: NO_ORDER_SIDE");
        assert_eq!(
            OrderDeniedReason::TradingHalted.to_string(),
            "TRADING_HALTED"
        );
        assert_eq!(
            OrderDeniedReason::RateLimitExceeded.to_string(),
            "RATE_LIMIT_EXCEEDED"
        );
        assert_eq!(
            reducing.to_string(),
            "TRADING_STATE_REDUCING: side=BUY, instrument_id=AUD/USD.SIM"
        );
    }

    #[rstest]
    fn renders_routing_messages() {
        let missing_client = OrderDeniedReason::NoExecutionClient {
            client_id: Some(ClientId::from("SIM")),
            routing_context: "venue=SIM".to_string(),
        };
        let mismatch = OrderDeniedReason::ClientVenueMismatch {
            client_id: ClientId::from("IB"),
            order_venue: Venue::from("XCME"),
            client_venue: Venue::from("IB"),
        };
        let submit_failed = OrderDeniedReason::SubmitFailed {
            detail: "transport closed".to_string(),
        };
        let invalid_position_id = OrderDeniedReason::InvalidPositionId {
            position_id: PositionId::from("P-1"),
            detail: "not valid for NETTING OMS".to_string(),
        };

        assert_eq!(
            missing_client.to_string(),
            "NO_EXECUTION_CLIENT: client_id=SIM, venue=SIM"
        );
        assert_eq!(
            mismatch.to_string(),
            "CLIENT_VENUE_MISMATCH: client_id=IB, order_venue=XCME, client_venue=IB"
        );
        assert_eq!(submit_failed.to_string(), "SUBMIT_FAILED: transport closed");
        assert_eq!(
            invalid_position_id.to_string(),
            "INVALID_POSITION_ID: P-1; not valid for NETTING OMS"
        );
    }

    #[rstest]
    fn renders_condition_led_message() {
        let reason = OrderDeniedReason::UnsupportedTimeInForce(TimeInForce::Gtd);
        assert_eq!(reason.to_string(), "UNSUPPORTED_TIME_IN_FORCE: GTD");
    }

    #[rstest]
    fn renders_adapter_messages() {
        let invalid_client_order_id = OrderDeniedReason::InvalidClientOrderId {
            detail: "clOrdId must be alphanumeric".to_string(),
        };
        let unsupported_order_list = OrderDeniedReason::UnsupportedOrderList {
            detail: "spread instruments are not supported in order lists".to_string(),
        };
        let unsupported_order_type = OrderDeniedReason::UnsupportedOrderType {
            order_type: OrderType::TrailingStopMarket,
        };
        let unsupported_tp_sl = OrderDeniedReason::UnsupportedTpSl {
            detail: "TP/SL trigger prices are not supported in demo mode".to_string(),
        };
        let validation_failed = OrderDeniedReason::ValidationFailed {
            detail: "`bbo_side_type` and `bbo_level` are only supported for linear products"
                .to_string(),
        };

        assert_eq!(
            invalid_client_order_id.to_string(),
            "INVALID_CLIENT_ORDER_ID: clOrdId must be alphanumeric"
        );
        assert_eq!(
            unsupported_order_list.to_string(),
            "UNSUPPORTED_ORDER_LIST: spread instruments are not supported in order lists"
        );
        assert_eq!(
            unsupported_order_type.to_string(),
            "UNSUPPORTED_ORDER_TYPE: TRAILING_STOP_MARKET"
        );
        assert_eq!(
            unsupported_tp_sl.to_string(),
            "UNSUPPORTED_TP_SL: TP/SL trigger prices are not supported in demo mode"
        );
        assert_eq!(
            validation_failed.to_string(),
            "VALIDATION_FAILED: `bbo_side_type` and `bbo_level` are only supported for linear products"
        );
        assert_eq!(
            OrderDeniedReason::StreamReconciling.to_string(),
            "STREAM_RECONCILING: execution stream unavailable or recovering, retry after recovery"
        );
    }

    // Drift pin: each variant's rendered message must start with its discriminant code, keeping
    // the hand-written `#[error]` prefix in sync with the strum-derived `OrderDeniedCode`.
    #[rstest]
    fn message_prefix_matches_code() {
        let usd = || Money::from("100.00 USD");
        let samples = [
            OrderDeniedReason::PricePrecisionExceedsMaximum {
                field: OrderPriceField::Price,
                price: Price::from("1.00"),
                price_precision: 2,
                max_precision: 1,
            },
            OrderDeniedReason::PriceNotPositive {
                field: OrderPriceField::TriggerPrice,
                price: Price::from("0.00"),
            },
            OrderDeniedReason::QuantityPrecisionExceedsMaximum {
                quantity: Quantity::from("1.00"),
                quantity_precision: 2,
                max_precision: 1,
            },
            OrderDeniedReason::QuantityConversionFailed {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::QuantityExceedsMaximum {
                effective_quantity: Quantity::from("15"),
                max_quantity: Quantity::from("10"),
            },
            OrderDeniedReason::QuantityBelowMinimum {
                effective_quantity: Quantity::from("1"),
                min_quantity: Quantity::from("5"),
            },
            OrderDeniedReason::InvalidMaxNotionalPerOrder {
                instrument_id: InstrumentId::from("AUD/USD.SIM"),
                value: Decimal::ONE,
            },
            OrderDeniedReason::InvalidOrderSide {
                order_side: OrderSide::NoOrderSide,
            },
            OrderDeniedReason::MissingExpireTime,
            OrderDeniedReason::ExpireTimeInPast {
                expire_time: "1970-01-01T00:00:00Z".to_string(),
            },
            OrderDeniedReason::MissingTrailingOffsetType,
            OrderDeniedReason::UnsupportedTrailingOffsetType {
                offset_type: TrailingOffsetType::Price,
            },
            OrderDeniedReason::MissingTriggerType,
            OrderDeniedReason::MissingTrailingOffset,
            OrderDeniedReason::InstrumentNotFound {
                instrument_id: InstrumentId::from("AUD/USD.SIM"),
            },
            OrderDeniedReason::PositionNotFound {
                position_id: PositionId::from("P-1"),
            },
            OrderDeniedReason::MarketPriceUnavailable {
                order_type: OrderType::Market,
                instrument_id: InstrumentId::from("AUD/USD.SIM"),
            },
            OrderDeniedReason::TrailingStopCalculationFailed {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::NotionalCalculationFailed {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::NotionalBelowMinimum {
                min_notional: usd(),
                notional: usd(),
            },
            OrderDeniedReason::NotionalExceedsMaximum {
                max_notional: usd(),
                notional: usd(),
            },
            OrderDeniedReason::NotionalExceedsMaxPerOrder {
                max_notional: usd(),
                notional: usd(),
            },
            OrderDeniedReason::NotionalExceedsFreeBalance {
                free_balance: usd(),
                notional: usd(),
            },
            OrderDeniedReason::InitialMarginCalculationFailed {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::InitialMarginExceedsFreeBalance {
                free_balance: usd(),
                initial_margin: usd(),
            },
            OrderDeniedReason::BettingBalanceLockedCalculationFailed {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::CumulativeNotionalExceedsFreeBalance {
                free_balance: usd(),
                cumulative_notional: usd(),
            },
            OrderDeniedReason::CumulativeInitialMarginCalculationFailed {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::CumulativeInitialMarginExceedsFreeBalance {
                free_balance: usd(),
                cumulative_initial_margin: usd(),
            },
            OrderDeniedReason::ReduceOnlyWouldIncreasePosition {
                position_id: PositionId::from("P-1"),
            },
            OrderDeniedReason::OrderListIncomplete {
                order_list_id: OrderListId::from("OL-1"),
            },
            OrderDeniedReason::OrderListDenied {
                order_list_id: OrderListId::from("OL-1"),
            },
            OrderDeniedReason::TradingHalted,
            OrderDeniedReason::TradingStateReducing {
                order_side: OrderSide::Buy,
                instrument_id: InstrumentId::from("AUD/USD.SIM"),
            },
            OrderDeniedReason::RateLimitExceeded,
            OrderDeniedReason::StreamReconciling,
            OrderDeniedReason::NoExecutionClient {
                client_id: Some(ClientId::from("SIM")),
                routing_context: "venue=SIM".to_string(),
            },
            OrderDeniedReason::ClientVenueMismatch {
                client_id: ClientId::from("IB"),
                order_venue: Venue::from("XCME"),
                client_venue: Venue::from("IB"),
            },
            OrderDeniedReason::SubmitFailed {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::InvalidClientOrderId {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::InvalidPositionId {
                position_id: PositionId::from("P-1"),
                detail: "boom".to_string(),
            },
            OrderDeniedReason::UnsupportedOrderList {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::UnsupportedOrderType {
                order_type: OrderType::TrailingStopMarket,
            },
            OrderDeniedReason::UnsupportedTimeInForce(TimeInForce::Gtd),
            OrderDeniedReason::UnsupportedTpSl {
                detail: "boom".to_string(),
            },
            OrderDeniedReason::ValidationFailed {
                detail: "boom".to_string(),
            },
        ];

        assert_eq!(samples.len(), OrderDeniedCode::iter().count());
        for reason in samples {
            let code = OrderDeniedCode::from(&reason).to_string();
            assert!(
                reason.to_string().starts_with(&code),
                "message `{reason}` must start with code `{code}`"
            );
        }
    }

    #[rstest]
    fn generated_table_is_in_sync() {
        let committed = std::fs::read_to_string(DOC_PATH).expect("execution.md should exist");
        assert!(
            committed.contains(&generated_block()),
            "the order-denied-reasons table in docs/concepts/execution.md is stale; regenerate \
             with `cargo test -p nautilus-model regenerate_order_denied_reasons_doc -- --ignored`"
        );
    }

    #[rstest]
    #[ignore = "rewrites the generated table in execution.md; run after changing OrderDeniedReason variants"]
    fn regenerate_order_denied_reasons_doc() {
        let doc = std::fs::read_to_string(DOC_PATH).expect("execution.md should exist");
        let start = doc.find(BLOCK_BEGIN).expect("begin marker present");
        let end = doc.find(BLOCK_END).expect("end marker present") + BLOCK_END.len();
        let updated = format!("{}{}{}", &doc[..start], generated_block(), &doc[end..]);
        std::fs::write(DOC_PATH, updated).expect("should write execution.md");
    }

    fn generated_block() -> String {
        format!("{BLOCK_BEGIN}\n\n{}\n\n{BLOCK_END}", markdown_table())
    }

    fn markdown_table() -> String {
        const CODE_HEADER: &str = "Code";
        const DESC_HEADER: &str = "Description";

        // Declaration order carries the public table's abstraction hierarchy
        let rows: Vec<(String, &'static str)> = OrderDeniedCode::iter()
            .map(|code| (format!("`{code}`"), code.description()))
            .collect();
        // Width counts characters, matching the padding applied by `format!` and the
        // column width the Markdown table hook normalizes to. Descriptions carry
        // non-breaking hyphens, so byte length would over-pad the column.
        let code_w = rows
            .iter()
            .map(|(code, _)| code.chars().count())
            .max()
            .unwrap_or(0)
            .max(CODE_HEADER.chars().count());
        let desc_w = rows
            .iter()
            .map(|(_, desc)| desc.chars().count())
            .max()
            .unwrap_or(0)
            .max(DESC_HEADER.chars().count());

        let mut lines = vec![
            format!("| {CODE_HEADER:<code_w$} | {DESC_HEADER:<desc_w$} |"),
            format!("| {:-<code_w$} | {:-<desc_w$} |", "", ""),
        ];

        for (code, desc) in rows {
            lines.push(format!("| {code:<code_w$} | {desc:<desc_w$} |"));
        }
        lines.join("\n")
    }
}