nautilus_model/types/

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

//! Represents a quantity with a non-negative value and specified precision.
//!
//! [`Quantity`] is an immutable value type for representing trade sizes, order quantities,
//! and position amounts. It enforces non-negative values and provides fixed-point arithmetic
//! for deterministic calculations.
//!
//! # Arithmetic behavior
//!
//! | Operation               | Result     | Notes                               |
//! |-------------------------|------------|-------------------------------------|
//! | `Quantity + Quantity`   | `Quantity` | Precision is max of both operands.  |
//! | `Quantity - Quantity`   | `Quantity` | Panics if result would be negative. |
//! | `Quantity * Quantity`   | `Quantity` | Scales back by `FIXED_SCALAR`.      |
//! | `Quantity + Decimal`    | `Decimal`  |                                     |
//! | `Quantity - Decimal`    | `Decimal`  |                                     |
//! | `Quantity * Decimal`    | `Decimal`  |                                     |
//! | `Quantity / Decimal`    | `Decimal`  |                                     |
//! | `Quantity + f64`        | `f64`      |                                     |
//! | `Quantity - f64`        | `f64`      |                                     |
//! | `Quantity * f64`        | `f64`      |                                     |
//! | `Quantity / f64`        | `f64`      |                                     |
//!
//! # Immutability
//!
//! `Quantity` is immutable. All arithmetic operations return new instances.

use std::{
    cmp::Ordering,
    fmt::{Debug, Display},
    hash::{Hash, Hasher},
    iter::Sum,
    ops::{Add, Deref, Div, Mul, Sub},
    str::FromStr,
};

#[cfg(feature = "defi")]
use alloy_primitives::U256;
use nautilus_core::{
    correctness::{
        CorrectnessError, CorrectnessResult, CorrectnessResultExt, FAILED,
        check_in_range_inclusive_f64, check_predicate_true,
    },
    string::formatting::Separable,
};
use rust_decimal::Decimal;
use serde::{Deserialize, Deserializer, Serialize};

use super::fixed::{
    FIXED_PRECISION, FIXED_SCALAR, FIXED_SCALAR_RAW, MAX_FLOAT_PRECISION, check_fixed_precision,
    checked_mul_div_fixed, mantissa_exponent_to_fixed_i128, mantissa_exponent_to_raw_checked,
    raw_scales_match, scaled_raw_to_decimal,
};
#[cfg(not(feature = "high-precision"))]
use super::fixed::{f64_to_fixed_u64, fixed_u64_to_f64};
#[cfg(feature = "high-precision")]
use super::fixed::{f64_to_fixed_u128, fixed_u128_to_f64};

// -----------------------------------------------------------------------------
// QuantityRaw
// -----------------------------------------------------------------------------

#[cfg(feature = "high-precision")]
pub type QuantityRaw = u128;

#[cfg(not(feature = "high-precision"))]
pub type QuantityRaw = u64;

// -----------------------------------------------------------------------------

/// The maximum raw quantity integer value.
///
/// `QUANTITY_MAX` and `FIXED_SCALAR` are cast to `QuantityRaw` before multiplying, so the
/// scaling uses exact integer arithmetic rather than a lossy `f64` product. The result
/// fits within `QuantityRaw`'s range in both high-precision (u128) and standard-precision
/// (u64) modes, so the multiplication cannot overflow.
#[unsafe(no_mangle)]
#[allow(unsafe_code)]
pub static QUANTITY_RAW_MAX: QuantityRaw =
    (QUANTITY_MAX as QuantityRaw) * (FIXED_SCALAR as QuantityRaw);

/// The sentinel value for an unset or null quantity.
pub const QUANTITY_UNDEF: QuantityRaw = QuantityRaw::MAX;

// -----------------------------------------------------------------------------
// QUANTITY_MAX
// -----------------------------------------------------------------------------

#[cfg(feature = "high-precision")]
/// The maximum valid quantity value that can be represented.
pub const QUANTITY_MAX: f64 = 34_028_236_692_093.0;

#[cfg(not(feature = "high-precision"))]
/// The maximum valid quantity value that can be represented.
pub const QUANTITY_MAX: f64 = 18_446_744_073.0;

// -----------------------------------------------------------------------------

/// The minimum valid quantity value that can be represented.
pub const QUANTITY_MIN: f64 = 0.0;

/// Represents a quantity with a non-negative value and specified precision.
///
/// Capable of storing either a whole number (no decimal places) of 'contracts'
/// or 'shares' (instruments denominated in whole units) or a decimal value
/// containing decimal places for instruments denominated in fractional units.
///
/// Handles up to [`FIXED_PRECISION`] decimals of precision.
///
/// - [`QUANTITY_MAX`] - Maximum representable quantity value.
/// - [`QUANTITY_MIN`] - 0 (non-negative values only).
#[repr(C)]
#[derive(Clone, Copy, Default, Eq)]
#[cfg_attr(
    feature = "python",
    pyo3::pyclass(module = "nautilus_trader.model", frozen, from_py_object)
)]
#[cfg_attr(
    feature = "python",
    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.model")
)]
pub struct Quantity {
    /// Represents the raw fixed-point value, with `precision` defining the number of decimal places.
    pub raw: QuantityRaw,
    /// The number of decimal places, with a maximum of [`FIXED_PRECISION`].
    pub precision: u8,
}

impl Quantity {
    /// Creates a new [`Quantity`] instance with correctness checking.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - `value` is invalid outside the representable range [0, `QUANTITY_MAX`].
    /// - `precision` is invalid outside the representable range [0, `FIXED_PRECISION`].
    ///
    /// # Notes
    ///
    /// PyO3 requires a `Result` type for proper error handling and stacktrace printing in Python.
    pub fn new_checked(value: f64, precision: u8) -> CorrectnessResult<Self> {
        check_in_range_inclusive_f64(value, QUANTITY_MIN, QUANTITY_MAX, "value")?;

        #[cfg(feature = "defi")]
        if precision > MAX_FLOAT_PRECISION {
            // Floats are only reliable up to ~16 decimal digits of precision regardless of feature flags
            return Err(CorrectnessError::PredicateViolation {
                message: format!(
                    "`precision` exceeded maximum float precision ({MAX_FLOAT_PRECISION}), use `Quantity::from_wei()` for wei values instead"
                ),
            });
        }

        check_fixed_precision(precision)?;

        #[cfg(feature = "high-precision")]
        let raw = f64_to_fixed_u128(value, precision);
        #[cfg(not(feature = "high-precision"))]
        let raw = f64_to_fixed_u64(value, precision);

        Ok(Self { raw, precision })
    }

    /// Creates a new [`Quantity`] instance with a guaranteed non zero value.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - `value` is zero.
    /// - `value` becomes zero after rounding to `precision`.
    /// - `value` is invalid outside the representable range [0, `QUANTITY_MAX`].
    /// - `precision` is invalid outside the representable range [0, `FIXED_PRECISION`].
    ///
    /// # Notes
    ///
    /// PyO3 requires a `Result` type for proper error handling and stacktrace printing in Python.
    pub fn non_zero_checked(value: f64, precision: u8) -> CorrectnessResult<Self> {
        check_predicate_true(value != 0.0, "value was zero")?;
        check_fixed_precision(precision)?;
        let rounded_value = (value * 10.0_f64.powi(i32::from(precision))).round()
            / 10.0_f64.powi(i32::from(precision));
        check_predicate_true(
            rounded_value != 0.0,
            &format!("value {value} was zero after rounding to precision {precision}"),
        )?;

        Self::new_checked(value, precision)
    }

    /// Creates a new [`Quantity`] instance.
    ///
    /// # Panics
    ///
    /// Panics if a correctness check fails. See [`Quantity::new_checked`] for more details.
    #[must_use]
    pub fn new(value: f64, precision: u8) -> Self {
        Self::new_checked(value, precision).expect_display(FAILED)
    }

    /// Creates a new [`Quantity`] instance with a guaranteed non zero value.
    ///
    /// # Panics
    ///
    /// Panics if a correctness check fails. See [`Quantity::non_zero_checked`] for more details.
    #[must_use]
    pub fn non_zero(value: f64, precision: u8) -> Self {
        Self::non_zero_checked(value, precision).expect_display(FAILED)
    }

    /// Creates a new [`Quantity`] instance from the given `raw` fixed-point value and `precision`.
    ///
    /// # Panics
    ///
    /// Panics if `raw` exceeds [`QUANTITY_RAW_MAX`] and is not a sentinel value.
    /// Panics if `precision` exceeds [`FIXED_PRECISION`].
    #[must_use]
    pub fn from_raw(raw: QuantityRaw, precision: u8) -> Self {
        assert!(
            raw == QUANTITY_UNDEF || raw <= QUANTITY_RAW_MAX,
            "`raw` value {raw} exceeds QUANTITY_RAW_MAX={QUANTITY_RAW_MAX} for Quantity"
        );

        if raw == QUANTITY_UNDEF {
            assert!(
                precision == 0,
                "`precision` must be 0 when `raw` is QUANTITY_UNDEF"
            );
        }
        check_fixed_precision(precision).expect_display(FAILED);

        // TODO: Enforce spurious bits validation in v2
        // if raw != QUANTITY_UNDEF && raw > 0 {
        //     #[cfg(feature = "high-precision")]
        //     super::fixed::check_fixed_raw_u128(raw, precision).expect(FAILED);
        //     #[cfg(not(feature = "high-precision"))]
        //     super::fixed::check_fixed_raw_u64(raw, precision).expect(FAILED);
        // }

        Self { raw, precision }
    }

    /// Creates a new [`Quantity`] instance from the given `raw` fixed-point value and `precision`
    /// with correctness checking.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - `precision` exceeds the maximum fixed precision.
    /// - `precision` is not 0 when `raw` is `QUANTITY_UNDEF`.
    /// - `raw` exceeds `QUANTITY_RAW_MAX` and is not a sentinel value.
    pub fn from_raw_checked(raw: QuantityRaw, precision: u8) -> CorrectnessResult<Self> {
        if raw == QUANTITY_UNDEF && precision != 0 {
            return Err(CorrectnessError::PredicateViolation {
                message: "`precision` must be 0 when `raw` is QUANTITY_UNDEF".to_string(),
            });
        }

        if raw != QUANTITY_UNDEF && raw > QUANTITY_RAW_MAX {
            return Err(CorrectnessError::PredicateViolation {
                message: format!("raw value {raw} exceeds QUANTITY_RAW_MAX={QUANTITY_RAW_MAX}"),
            });
        }

        check_fixed_precision(precision)?;

        Ok(Self { raw, precision })
    }

    /// Performs a checked addition, returning `None` on raw integer overflow, when the
    /// result exceeds `QUANTITY_RAW_MAX`, when either operand is `QUANTITY_UNDEF`, or
    /// when the operands have mixed raw scales (one at `FIXED_PRECISION` scale, the
    /// other at a defi `WEI_PRECISION` scale).
    ///
    /// Precision follows the `Add` implementation: uses the maximum precision of both operands.
    #[must_use]
    pub fn checked_add(self, rhs: Self) -> Option<Self> {
        if self.raw == QUANTITY_UNDEF || rhs.raw == QUANTITY_UNDEF {
            return None;
        }

        if !raw_scales_match(self.precision, rhs.precision) {
            return None;
        }
        let raw = self.raw.checked_add(rhs.raw)?;
        if raw > QUANTITY_RAW_MAX {
            return None;
        }
        Some(Self {
            raw,
            precision: self.precision.max(rhs.precision),
        })
    }

    /// Performs a checked subtraction, returning `None` if `rhs` is greater than `self`,
    /// when either operand is `QUANTITY_UNDEF`, or when the operands have mixed raw
    /// scales (one at `FIXED_PRECISION` scale, the other at a defi `WEI_PRECISION` scale).
    ///
    /// Precision follows the `Sub` implementation: uses the maximum precision of both operands.
    #[must_use]
    pub fn checked_sub(self, rhs: Self) -> Option<Self> {
        if self.raw == QUANTITY_UNDEF || rhs.raw == QUANTITY_UNDEF {
            return None;
        }

        if !raw_scales_match(self.precision, rhs.precision) {
            return None;
        }
        let raw = self.raw.checked_sub(rhs.raw)?;
        Some(Self {
            raw,
            precision: self.precision.max(rhs.precision),
        })
    }

    /// Computes a saturating subtraction between two quantities, logging when clamped.
    ///
    /// When `rhs` is greater than `self`, the result is clamped to zero and a warning is logged.
    /// Precision follows the `Sub` implementation: uses the maximum precision of both operands.
    #[must_use]
    pub fn saturating_sub(self, rhs: Self) -> Self {
        let precision = self.precision.max(rhs.precision);
        let raw = self.raw.saturating_sub(rhs.raw);
        if raw == 0 && self.raw < rhs.raw {
            log::warn!(
                "Saturating Quantity subtraction: {self} - {rhs} < 0, clamped to 0 (precision={precision})"
            );
        }

        Self { raw, precision }
    }

    /// Creates a new [`Quantity`] instance with a value of zero with the given `precision`.
    ///
    /// # Panics
    ///
    /// Panics if `precision` exceeds the maximum allowed by [`check_fixed_precision`].
    #[must_use]
    pub fn zero(precision: u8) -> Self {
        check_fixed_precision(precision).expect_display(FAILED);
        Self { raw: 0, precision }
    }

    /// Returns `true` if the value of this instance is undefined.
    #[must_use]
    pub fn is_undefined(&self) -> bool {
        self.raw == QUANTITY_UNDEF
    }

    /// Returns `true` if the value of this instance is zero.
    #[must_use]
    pub fn is_zero(&self) -> bool {
        self.raw == 0
    }

    /// Returns `true` if the value of this instance is position (> 0).
    #[must_use]
    pub fn is_positive(&self) -> bool {
        self.raw != QUANTITY_UNDEF && self.raw > 0
    }

    #[cfg(feature = "high-precision")]
    /// Returns the value of this instance as an `f64`.
    ///
    /// # Panics
    ///
    /// With the `defi` feature, panics if precision exceeds `MAX_FLOAT_PRECISION` (16).
    #[must_use]
    pub fn as_f64(&self) -> f64 {
        #[cfg(feature = "defi")]
        assert!(
            self.precision <= MAX_FLOAT_PRECISION,
            "Invalid f64 conversion beyond `MAX_FLOAT_PRECISION` (16)"
        );

        fixed_u128_to_f64(self.raw)
    }

    #[cfg(not(feature = "high-precision"))]
    /// Returns the value of this instance as an `f64`.
    #[must_use]
    pub fn as_f64(&self) -> f64 {
        fixed_u64_to_f64(self.raw)
    }

    /// Returns the value of this instance as a `Decimal`.
    #[must_use]
    pub fn as_decimal(&self) -> Decimal {
        // Scale down the raw value to match the precision
        let precision_diff = FIXED_PRECISION.saturating_sub(self.precision);
        let rescaled_raw = self.raw / QuantityRaw::pow(10, u32::from(precision_diff));

        // The raw value is guaranteed to be within i128 range after scaling
        // because our quantity constraints ensure the maximum raw value times the scaling
        // factor cannot exceed i128::MAX (high-precision) or i64::MAX (standard-precision).
        #[allow(
            clippy::unnecessary_cast,
            clippy::cast_lossless,
            reason = "cast is real when QuantityRaw is u64, no-op when u128"
        )]
        scaled_raw_to_decimal(rescaled_raw as i128, self.precision)
    }

    /// Returns a raw fixed-point quantity as a `Decimal`.
    #[must_use]
    #[allow(
        clippy::unnecessary_fallible_conversions,
        reason = "try_from is infallible when QuantityRaw is u64, fallible when u128"
    )]
    pub(crate) fn raw_as_decimal(raw: QuantityRaw) -> Decimal {
        let whole =
            i128::try_from(raw / FIXED_SCALAR_RAW).expect("Whole raw quantity must fit in Decimal");
        let fractional = i128::try_from(raw % FIXED_SCALAR_RAW)
            .expect("Fractional raw quantity must fit in Decimal");

        Decimal::from(whole) + Decimal::from_i128_with_scale(fractional, u32::from(FIXED_PRECISION))
    }

    /// Returns a formatted string representation of this instance.
    #[must_use]
    pub fn to_formatted_string(&self) -> String {
        format!("{self}").separate_with_underscores()
    }

    /// Creates a new [`Quantity`] from a `Decimal` value with specified precision.
    ///
    /// Uses pure integer arithmetic on the Decimal's mantissa and scale for fast conversion.
    /// The value is rounded to the specified precision using banker's rounding (round half to even).
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - `precision` exceeds [`FIXED_PRECISION`].
    /// - The decimal value is negative.
    /// - The decimal value cannot be converted to the raw representation.
    /// - Overflow occurs during scaling.
    pub fn from_decimal_dp(decimal: Decimal, precision: u8) -> CorrectnessResult<Self> {
        if decimal.mantissa() < 0 {
            return Err(CorrectnessError::PredicateViolation {
                message: format!(
                    "Decimal value '{decimal}' is negative, Quantity must be non-negative"
                ),
            });
        }

        let exponent = -(decimal.scale() as i8);
        let raw_i128 = mantissa_exponent_to_fixed_i128(decimal.mantissa(), exponent, precision)?;

        let raw: QuantityRaw =
            raw_i128
                .try_into()
                .map_err(|_| CorrectnessError::PredicateViolation {
                    message: format!(
                        "Decimal value exceeds QuantityRaw range [0, {QUANTITY_RAW_MAX}]"
                    ),
                })?;

        if raw > QUANTITY_RAW_MAX {
            return Err(CorrectnessError::PredicateViolation {
                message: format!(
                    "Raw value {raw} exceeds QUANTITY_RAW_MAX={QUANTITY_RAW_MAX} for Quantity"
                ),
            });
        }

        Ok(Self { raw, precision })
    }

    /// Creates a new [`Quantity`] from a [`Decimal`] value with precision inferred from the decimal's scale.
    ///
    /// The precision is determined by the scale of the decimal (number of decimal places).
    /// The value is rounded to the inferred precision using banker's rounding (round half to even).
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The inferred precision exceeds [`FIXED_PRECISION`].
    /// - The decimal value cannot be converted to the raw representation.
    /// - Overflow occurs during scaling.
    pub fn from_decimal(decimal: Decimal) -> CorrectnessResult<Self> {
        let precision = decimal.scale() as u8;
        Self::from_decimal_dp(decimal, precision)
    }

    /// Creates a new [`Quantity`] from a mantissa/exponent pair using pure integer arithmetic.
    ///
    /// The value is `mantissa * 10^exponent`. This avoids all floating-point and Decimal
    /// operations, making it ideal for exchange data that arrives as mantissa/exponent pairs.
    ///
    /// # Panics
    ///
    /// Panics if the resulting raw value exceeds [`QUANTITY_RAW_MAX`].
    #[must_use]
    pub fn from_mantissa_exponent(mantissa: u64, exponent: i8, precision: u8) -> Self {
        check_fixed_precision(precision).expect_display(FAILED);

        if mantissa == 0 {
            return Self { raw: 0, precision };
        }

        let raw_i128 = mantissa_exponent_to_fixed_i128(i128::from(mantissa), exponent, precision)
            .expect("Overflow in Quantity::from_mantissa_exponent");

        let raw: QuantityRaw = raw_i128
            .try_into()
            .expect("Raw value exceeds QuantityRaw range in Quantity::from_mantissa_exponent");
        assert!(
            raw <= QUANTITY_RAW_MAX,
            "`raw` value {raw} exceeded QUANTITY_RAW_MAX={QUANTITY_RAW_MAX} for Quantity"
        );

        Self { raw, precision }
    }

    /// Checked variant of [`Quantity::from_mantissa_exponent`].
    ///
    /// # Errors
    ///
    /// Returns an error if the precision is invalid or the resulting raw value
    /// exceeds [`QUANTITY_RAW_MAX`].
    pub fn from_mantissa_exponent_checked(
        mantissa: u64,
        exponent: i8,
        precision: u8,
    ) -> CorrectnessResult<Self> {
        let raw = mantissa_exponent_to_raw_checked::<QuantityRaw>(
            i128::from(mantissa),
            exponent,
            precision,
            "Quantity::from_mantissa_exponent",
            "QuantityRaw",
            "Quantity",
        )?;

        Self::from_raw_checked(raw, precision)
    }

    /// Creates a new [`Quantity`] from a U256 amount with specified precision.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Overflow occurs during scaling when precision is less than [`FIXED_PRECISION`].
    /// - The scaled U256 amount exceeds the `QuantityRaw` range.
    #[cfg(feature = "defi")]
    pub fn from_u256(amount: U256, precision: u8) -> CorrectnessResult<Self> {
        // Quantity expects raw values scaled to at least FIXED_PRECISION or higher(WEI)
        let scaled_amount = if precision < FIXED_PRECISION {
            amount
                .checked_mul(U256::from(
                    10u128.pow(u32::from(FIXED_PRECISION - precision)),
                ))
                .ok_or_else(|| CorrectnessError::PredicateViolation {
                    message: format!(
                        "Amount overflow during scaling to fixed precision: {} * 10^{}",
                        amount,
                        FIXED_PRECISION - precision
                    ),
                })?
        } else {
            amount
        };

        let raw = QuantityRaw::try_from(scaled_amount).map_err(|_| {
            CorrectnessError::PredicateViolation {
                message: format!("U256 scaled amount {scaled_amount} exceeds QuantityRaw range"),
            }
        })?;

        Self::from_raw_checked(raw, precision)
    }
}

impl From<Quantity> for f64 {
    fn from(qty: Quantity) -> Self {
        qty.as_f64()
    }
}

impl From<&Quantity> for f64 {
    fn from(qty: &Quantity) -> Self {
        qty.as_f64()
    }
}

impl From<i32> for Quantity {
    /// Creates a `Quantity` from an `i32` value.
    ///
    /// # Panics
    ///
    /// Panics if `value` is negative. Use `u32` for guaranteed non-negative values.
    fn from(value: i32) -> Self {
        assert!(
            value >= 0,
            "Cannot create Quantity from negative i32: {value}. Use u32 or check value is non-negative."
        );
        Self::from_mantissa_exponent(u64::from(value.cast_unsigned()), 0, 0)
    }
}

impl From<i64> for Quantity {
    /// Creates a `Quantity` from an `i64` value.
    ///
    /// # Panics
    ///
    /// Panics if `value` is negative. Use `u64` for guaranteed non-negative values.
    fn from(value: i64) -> Self {
        assert!(
            value >= 0,
            "Cannot create Quantity from negative i64: {value}. Use u64 or check value is non-negative."
        );
        Self::from_mantissa_exponent(value.cast_unsigned(), 0, 0)
    }
}

impl From<u32> for Quantity {
    fn from(value: u32) -> Self {
        Self::from_mantissa_exponent(u64::from(value), 0, 0)
    }
}

impl From<u64> for Quantity {
    fn from(value: u64) -> Self {
        Self::from_mantissa_exponent(value, 0, 0)
    }
}

impl Hash for Quantity {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.raw.hash(state);
    }
}

impl PartialEq for Quantity {
    fn eq(&self, other: &Self) -> bool {
        self.raw == other.raw
    }
}

impl PartialOrd for Quantity {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }

    fn lt(&self, other: &Self) -> bool {
        self.raw.lt(&other.raw)
    }

    fn le(&self, other: &Self) -> bool {
        self.raw.le(&other.raw)
    }

    fn gt(&self, other: &Self) -> bool {
        self.raw.gt(&other.raw)
    }

    fn ge(&self, other: &Self) -> bool {
        self.raw.ge(&other.raw)
    }
}

impl Ord for Quantity {
    fn cmp(&self, other: &Self) -> Ordering {
        self.raw.cmp(&other.raw)
    }
}

impl Deref for Quantity {
    type Target = QuantityRaw;

    fn deref(&self) -> &Self::Target {
        &self.raw
    }
}

impl Add for Quantity {
    type Output = Self;
    fn add(self, rhs: Self) -> Self::Output {
        Self {
            raw: self
                .raw
                .checked_add(rhs.raw)
                .expect("Overflow occurred when adding `Quantity`"),
            precision: self.precision.max(rhs.precision),
        }
    }
}

impl Sum for Quantity {
    fn sum<I: Iterator<Item = Self>>(iter: I) -> Self {
        iter.fold(Self::from(0), |acc, x| acc + x)
    }
}

impl<'a> Sum<&'a Self> for Quantity {
    fn sum<I: Iterator<Item = &'a Self>>(iter: I) -> Self {
        iter.fold(Self::from(0), |acc, x| acc + *x)
    }
}

impl Sub for Quantity {
    type Output = Self;
    fn sub(self, rhs: Self) -> Self::Output {
        Self {
            raw: self
                .raw
                .checked_sub(rhs.raw)
                .expect("Underflow occurred when subtracting `Quantity`"),
            precision: self.precision.max(rhs.precision),
        }
    }
}

impl Mul for Quantity {
    type Output = Self;
    fn mul(self, rhs: Self) -> Self::Output {
        let result_raw = if self.raw != QUANTITY_UNDEF
            && rhs.raw != QUANTITY_UNDEF
            && self.precision <= FIXED_PRECISION
            && rhs.precision <= FIXED_PRECISION
        {
            checked_mul_div_fixed(self.raw, rhs.raw).filter(|raw| *raw <= QUANTITY_RAW_MAX)
        } else {
            self.raw
                .checked_mul(rhs.raw)
                .map(|raw| raw / FIXED_SCALAR_RAW)
        }
        .expect("Overflow occurred when multiplying `Quantity`");

        Self {
            raw: result_raw,
            precision: self.precision.max(rhs.precision),
        }
    }
}

impl Add<Decimal> for Quantity {
    type Output = Decimal;
    fn add(self, rhs: Decimal) -> Self::Output {
        self.as_decimal() + rhs
    }
}

impl Sub<Decimal> for Quantity {
    type Output = Decimal;
    fn sub(self, rhs: Decimal) -> Self::Output {
        self.as_decimal() - rhs
    }
}

impl Mul<Decimal> for Quantity {
    type Output = Decimal;
    fn mul(self, rhs: Decimal) -> Self::Output {
        self.as_decimal() * rhs
    }
}

impl Div<Decimal> for Quantity {
    type Output = Decimal;
    fn div(self, rhs: Decimal) -> Self::Output {
        self.as_decimal() / rhs
    }
}

impl Add<f64> for Quantity {
    type Output = f64;
    fn add(self, rhs: f64) -> Self::Output {
        self.as_f64() + rhs
    }
}

impl Sub<f64> for Quantity {
    type Output = f64;
    fn sub(self, rhs: f64) -> Self::Output {
        self.as_f64() - rhs
    }
}

impl Mul<f64> for Quantity {
    type Output = f64;
    fn mul(self, rhs: f64) -> Self::Output {
        self.as_f64() * rhs
    }
}

impl Div<f64> for Quantity {
    type Output = f64;
    fn div(self, rhs: f64) -> Self::Output {
        self.as_f64() / rhs
    }
}

impl From<Quantity> for QuantityRaw {
    fn from(value: Quantity) -> Self {
        value.raw
    }
}

impl From<&Quantity> for QuantityRaw {
    fn from(value: &Quantity) -> Self {
        value.raw
    }
}

impl From<Quantity> for Decimal {
    fn from(value: Quantity) -> Self {
        value.as_decimal()
    }
}

impl From<&Quantity> for Decimal {
    fn from(value: &Quantity) -> Self {
        value.as_decimal()
    }
}

impl FromStr for Quantity {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        let clean_value = value.replace('_', "");

        let decimal = if clean_value.contains('e') || clean_value.contains('E') {
            Decimal::from_scientific(&clean_value)
                .map_err(|e| format!("Error parsing `input` string '{value}' as Decimal: {e}"))?
        } else {
            Decimal::from_str(&clean_value)
                .map_err(|e| format!("Error parsing `input` string '{value}' as Decimal: {e}"))?
        };

        // Use decimal scale to preserve caller-specified precision (including trailing zeros)
        let precision = decimal.scale() as u8;

        Self::from_decimal_dp(decimal, precision).map_err(|e| e.to_string())
    }
}

impl From<&str> for Quantity {
    fn from(value: &str) -> Self {
        Self::from_str(value).expect(FAILED)
    }
}

impl From<String> for Quantity {
    fn from(value: String) -> Self {
        Self::from_str(&value).expect(FAILED)
    }
}

impl From<&String> for Quantity {
    fn from(value: &String) -> Self {
        Self::from_str(value).expect(FAILED)
    }
}

impl Debug for Quantity {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.precision > MAX_FLOAT_PRECISION {
            write!(f, "{}({})", stringify!(Quantity), self.raw)
        } else {
            write!(f, "{}({})", stringify!(Quantity), self.as_decimal())
        }
    }
}

impl Display for Quantity {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.precision > MAX_FLOAT_PRECISION {
            write!(f, "{}", self.raw)
        } else {
            write!(f, "{}", self.as_decimal())
        }
    }
}

impl Serialize for Quantity {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(&self.to_string())
    }
}

impl<'de> Deserialize<'de> for Quantity {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let qty_str: std::borrow::Cow<'de, str> = Deserialize::deserialize(deserializer)?;
        Self::from_str(qty_str.as_ref()).map_err(serde::de::Error::custom)
    }
}

/// Checks if the quantity `value` is positive.
///
/// # Errors
///
/// Returns an error if `value` is not positive.
pub fn check_positive_quantity(value: Quantity, param: &str) -> CorrectnessResult<()> {
    if !value.is_positive() {
        return Err(CorrectnessError::NotPositive {
            param: param.to_string(),
            value: value.to_string(),
            type_name: "`Quantity`",
        });
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use std::str::FromStr;

    use nautilus_core::{approx_eq, correctness::CorrectnessError};
    use rstest::rstest;
    use rust_decimal_macros::dec;

    use super::*;

    #[rstest]
    fn test_max_quantity_round_trips_through_raw() {
        // Regression: a lossy `f64` scalar previously left `QUANTITY_RAW_MAX` below the raw
        // produced by `new` at the maximum, causing spurious panics and overflow errors.
        let qty = Quantity::new(QUANTITY_MAX, 0);

        assert_eq!(qty.raw, QUANTITY_RAW_MAX);
        assert!(Quantity::from_raw_checked(qty.raw, 0).is_ok());
        assert!(qty.checked_add(Quantity::zero(0)).is_some());
    }

    #[rstest]
    fn test_check_quantity_positive() {
        let qty = Quantity::new(0.0, 0);
        let error = check_positive_quantity(qty, "qty").unwrap_err();

        assert_eq!(
            error,
            CorrectnessError::NotPositive {
                param: "qty".to_string(),
                value: "0".to_string(),
                type_name: "`Quantity`",
            }
        );
        assert_eq!(
            error.to_string(),
            "invalid `Quantity` for 'qty' not positive, was 0"
        );
    }

    #[rstest]
    #[cfg(all(not(feature = "defi"), not(feature = "high-precision")))]
    #[should_panic(expected = "`precision` exceeded maximum `FIXED_PRECISION` (9), was 17")]
    fn test_invalid_precision_new() {
        // Precision 17 should fail due to DeFi validation
        let _ = Quantity::new(1.0, 17);
    }

    #[rstest]
    #[cfg(all(not(feature = "defi"), feature = "high-precision"))]
    #[should_panic(expected = "`precision` exceeded maximum `FIXED_PRECISION` (16), was 17")]
    fn test_invalid_precision_new() {
        // Precision 17 should fail due to DeFi validation
        let _ = Quantity::new(1.0, 17);
    }

    #[rstest]
    #[cfg(not(feature = "defi"))]
    #[should_panic(expected = "Condition failed: `precision` exceeded maximum `FIXED_PRECISION`")]
    fn test_invalid_precision_from_raw() {
        // Precision out of range for fixed
        let _ = Quantity::from_raw(1, FIXED_PRECISION + 1);
    }

    #[rstest]
    #[cfg(not(feature = "defi"))]
    #[should_panic(expected = "Condition failed: `precision` exceeded maximum `FIXED_PRECISION`")]
    fn test_invalid_precision_zero() {
        // Precision out of range for fixed
        let _ = Quantity::zero(FIXED_PRECISION + 1);
    }

    #[rstest]
    fn test_mixed_precision_add() {
        let q1 = Quantity::new(1.0, 1);
        let q2 = Quantity::new(1.0, 2);
        let result = q1 + q2;
        assert_eq!(result.precision, 2);
        assert_eq!(result.as_f64(), 2.0);
    }

    #[rstest]
    fn test_sum_owned_quantities() {
        let quantities = [Quantity::new(1.25, 2), Quantity::new(2.75, 2)];
        let result: Quantity = quantities.into_iter().sum();

        assert_eq!(result.as_decimal(), dec!(4.00));
        assert_eq!(result.precision, 2);
    }

    #[rstest]
    fn test_sum_borrowed_quantities() {
        let quantities = [Quantity::new(0.125, 3), Quantity::new(0.375, 3)];
        let result: Quantity = quantities.iter().sum();

        assert_eq!(result.as_decimal(), dec!(0.500));
        assert_eq!(result.precision, 3);
    }

    #[rstest]
    fn test_sum_mixed_precision_quantities() {
        let quantities = [
            Quantity::new(1.2, 1),
            Quantity::new(3.45, 2),
            Quantity::new(0.006, 3),
        ];
        let result: Quantity = quantities.into_iter().sum();

        assert_eq!(result.as_decimal(), dec!(4.656));
        assert_eq!(result.precision, 3);
    }

    #[rstest]
    fn test_sum_empty_quantity_iterator() {
        let result: Quantity = std::iter::empty::<Quantity>().sum();

        assert_eq!(result.as_decimal(), dec!(0));
        assert_eq!(result.precision, 0);
    }

    #[rstest]
    fn test_mixed_precision_sub() {
        let q1 = Quantity::new(2.0, 1);
        let q2 = Quantity::new(1.0, 2);
        let result = q1 - q2;
        assert_eq!(result.precision, 2);
        assert_eq!(result.as_f64(), 1.0);
    }

    #[rstest]
    fn test_mixed_precision_mul() {
        let q1 = Quantity::new(2.0, 1);
        let q2 = Quantity::new(3.0, 2);
        let result = q1 * q2;
        assert_eq!(result.precision, 2);
        assert_eq!(result.as_f64(), 6.0);
    }

    #[rstest]
    fn test_new_non_zero_ok() {
        let qty = Quantity::non_zero_checked(123.456, 3).unwrap();
        assert_eq!(qty.raw, Quantity::new(123.456, 3).raw);
        assert!(qty.is_positive());
    }

    #[rstest]
    fn test_new_non_zero_zero_input() {
        assert!(Quantity::non_zero_checked(0.0, 0).is_err());
    }

    #[rstest]
    fn test_new_non_zero_rounds_to_zero() {
        // 0.0004 rounded to 3 dp ⇒ 0.000
        assert!(Quantity::non_zero_checked(0.0004, 3).is_err());
    }

    #[rstest]
    fn test_new_non_zero_negative() {
        assert!(Quantity::non_zero_checked(-1.0, 0).is_err());
    }

    #[rstest]
    fn test_new_non_zero_exceeds_max() {
        assert!(Quantity::non_zero_checked(QUANTITY_MAX * 10.0, 0).is_err());
    }

    #[rstest]
    fn test_new_non_zero_invalid_precision() {
        assert!(Quantity::non_zero_checked(1.0, FIXED_PRECISION + 1).is_err());
    }

    #[rstest]
    fn test_new() {
        let value = 0.00812;
        let qty = Quantity::new(value, 8);
        assert_eq!(qty, qty);
        assert_eq!(qty.raw, Quantity::from(&format!("{value}")).raw);
        assert_eq!(qty.precision, 8);
        assert_eq!(qty, Quantity::from("0.00812000"));
        assert_eq!(qty.as_decimal(), dec!(0.00812000));
        assert_eq!(qty.to_string(), "0.00812000");
        assert!(!qty.is_zero());
        assert!(qty.is_positive());
        assert!(approx_eq!(f64, qty.as_f64(), 0.00812, epsilon = 0.000_001));
    }

    #[rstest]
    fn test_check_quantity_positive_ok() {
        let qty = Quantity::new(10.0, 0);
        check_positive_quantity(qty, "qty").unwrap();
    }

    #[rstest]
    fn test_negative_quantity_validation() {
        assert!(Quantity::new_checked(-1.0, FIXED_PRECISION).is_err());
    }

    #[rstest]
    fn test_new_checked_returns_typed_error_with_stable_display() {
        let error = Quantity::new_checked(QUANTITY_MAX + 1.0, FIXED_PRECISION).unwrap_err();

        assert!(matches!(error, CorrectnessError::OutOfRange { .. }));
        assert_eq!(
            error.to_string(),
            format!(
                "invalid f64 for 'value' not in range [{QUANTITY_MIN}, {QUANTITY_MAX}], was {}",
                QUANTITY_MAX + 1.0
            )
        );
    }

    #[rstest]
    fn test_from_raw_checked_returns_typed_error_with_stable_display() {
        let error = Quantity::from_raw_checked(QUANTITY_UNDEF, 3).unwrap_err();

        assert_eq!(
            error,
            CorrectnessError::PredicateViolation {
                message: "`precision` must be 0 when `raw` is QUANTITY_UNDEF".to_string(),
            }
        );
        assert_eq!(
            error.to_string(),
            "`precision` must be 0 when `raw` is QUANTITY_UNDEF"
        );
    }

    #[rstest]
    fn test_undefined() {
        let qty = Quantity::from_raw(QUANTITY_UNDEF, 0);
        assert_eq!(qty.raw, QUANTITY_UNDEF);
        assert!(qty.is_undefined());
    }

    #[rstest]
    fn test_zero() {
        let qty = Quantity::zero(8);
        assert_eq!(qty.raw, 0);
        assert_eq!(qty.precision, 8);
        assert!(qty.is_zero());
        assert!(!qty.is_positive());
    }

    #[rstest]
    fn test_from_i32_exact() {
        let values = [0, 1, i32::MAX];
        let quantities = values.map(Quantity::from);
        let expected =
            values.map(|value| (QuantityRaw::try_from(value).unwrap() * FIXED_SCALAR_RAW, 0));

        assert_eq!(
            quantities.map(|quantity| (quantity.raw, quantity.precision)),
            expected
        );
    }

    #[rstest]
    fn test_from_i64_exact() {
        let max = quantity_max_i64();
        let values = [0, 1, max];
        let quantities = values.map(Quantity::from);
        let expected =
            values.map(|value| (QuantityRaw::try_from(value).unwrap() * FIXED_SCALAR_RAW, 0));

        assert_eq!(
            quantities.map(|quantity| (quantity.raw, quantity.precision)),
            expected
        );
    }

    #[rstest]
    fn test_from_u32_exact() {
        let values = [0, 1, u32::MAX];
        let quantities = values.map(Quantity::from);
        let expected = values.map(|value| (QuantityRaw::from(value) * FIXED_SCALAR_RAW, 0));

        assert_eq!(
            quantities.map(|quantity| (quantity.raw, quantity.precision)),
            expected
        );
    }

    #[rstest]
    fn test_from_u64_exact() {
        let max = quantity_max_u64();
        let values = [0, 1, max];
        let quantities = values.map(Quantity::from);
        let expected = values.map(|value| (QuantityRaw::from(value) * FIXED_SCALAR_RAW, 0));

        assert_eq!(
            quantities.map(|quantity| (quantity.raw, quantity.precision)),
            expected
        );
    }

    #[rstest]
    #[should_panic(
        expected = "Cannot create Quantity from negative i32: -1. Use u32 or check value is non-negative."
    )]
    fn test_from_i32_negative_panics() {
        let _ = Quantity::from(-1_i32);
    }

    #[rstest]
    #[should_panic(
        expected = "Cannot create Quantity from negative i64: -1. Use u64 or check value is non-negative."
    )]
    fn test_from_i64_negative_panics() {
        let _ = Quantity::from(-1_i64);
    }

    #[rstest]
    #[cfg_attr(
        feature = "high-precision",
        should_panic(expected = "exceeded QUANTITY_RAW_MAX")
    )]
    #[cfg_attr(
        not(feature = "high-precision"),
        should_panic(expected = "Raw value exceeds QuantityRaw range")
    )]
    fn test_from_i64_overflow_panics() {
        let max = quantity_max_i64();

        let _ = Quantity::from(max + 1);
    }

    #[rstest]
    #[cfg_attr(
        feature = "high-precision",
        should_panic(expected = "exceeded QUANTITY_RAW_MAX")
    )]
    #[cfg_attr(
        not(feature = "high-precision"),
        should_panic(expected = "Raw value exceeds QuantityRaw range")
    )]
    fn test_from_u64_overflow_panics() {
        let max = quantity_max_u64();

        let _ = Quantity::from(max + 1);
    }

    fn quantity_max_i64() -> i64 {
        i64::try_from(QUANTITY_RAW_MAX / FIXED_SCALAR_RAW).unwrap()
    }

    #[allow(
        clippy::useless_conversion,
        reason = "try_from is a no-op when QuantityRaw is u64, and narrows when u128 (high-precision)"
    )]
    fn quantity_max_u64() -> u64 {
        u64::try_from(QUANTITY_RAW_MAX / FIXED_SCALAR_RAW).unwrap()
    }

    #[rstest] // Test does not panic rather than exact value
    fn test_with_maximum_value() {
        let qty = Quantity::new_checked(QUANTITY_MAX, 0);
        assert!(qty.is_ok());
    }

    #[rstest]
    fn test_with_minimum_positive_value() {
        let value = 0.000_000_001;
        let qty = Quantity::new(value, 9);
        assert_eq!(qty.raw, Quantity::from("0.000000001").raw);
        assert_eq!(qty.as_decimal(), dec!(0.000000001));
        assert_eq!(qty.to_string(), "0.000000001");
    }

    #[rstest]
    fn test_with_minimum_value() {
        let qty = Quantity::new(QUANTITY_MIN, 9);
        assert_eq!(qty.raw, 0);
        assert_eq!(qty.as_decimal(), dec!(0));
        assert_eq!(qty.to_string(), "0.000000000");
    }

    #[rstest]
    fn test_is_zero() {
        let qty = Quantity::zero(8);
        assert_eq!(qty, qty);
        assert_eq!(qty.raw, 0);
        assert_eq!(qty.precision, 8);
        assert_eq!(qty, Quantity::from("0.00000000"));
        assert_eq!(qty.as_decimal(), dec!(0));
        assert_eq!(qty.to_string(), "0.00000000");
        assert!(qty.is_zero());
    }

    #[rstest]
    fn test_precision() {
        let value = 1.001;
        let qty = Quantity::new(value, 2);
        assert_eq!(qty.to_string(), "1.00");
    }

    #[rstest]
    fn test_new_from_str() {
        let qty = Quantity::new(0.008_120_00, 8);
        assert_eq!(qty, qty);
        assert_eq!(qty.precision, 8);
        assert_eq!(qty, Quantity::from("0.00812000"));
        assert_eq!(qty.to_string(), "0.00812000");
    }

    #[rstest]
    #[case("0", 0)]
    #[case("1.1", 1)]
    #[case("1.123456789", 9)]
    fn test_from_str_valid_input(#[case] input: &str, #[case] expected_prec: u8) {
        let qty = Quantity::from(input);
        assert_eq!(qty.precision, expected_prec);
        assert_eq!(qty.as_decimal(), Decimal::from_str(input).unwrap());
    }

    #[rstest]
    #[should_panic(expected = "ParseFloatError")]
    fn test_from_str_invalid_input() {
        let input = "invalid";
        let _ = Quantity::new(f64::from_str(input).unwrap(), 8);
    }

    #[rstest]
    fn test_from_str_errors() {
        assert!(Quantity::from_str("invalid").is_err());
        assert!(Quantity::from_str("12.34.56").is_err());
        assert!(Quantity::from_str("").is_err());
        assert!(Quantity::from_str("-1").is_err()); // Negative values not allowed
        assert!(Quantity::from_str("-0.001").is_err());
    }

    #[rstest]
    #[case("1e7", 0, 10_000_000.0)]
    #[case("2.5e3", 0, 2_500.0)]
    #[case("1.234e-2", 5, 0.01234)]
    #[case("5E-3", 3, 0.005)]
    #[case("1.0e6", 0, 1_000_000.0)]
    fn test_from_str_scientific_notation(
        #[case] input: &str,
        #[case] expected_precision: u8,
        #[case] expected_value: f64,
    ) {
        let qty = Quantity::from_str(input).unwrap();
        assert_eq!(qty.precision, expected_precision);
        assert!(approx_eq!(
            f64,
            qty.as_f64(),
            expected_value,
            epsilon = 1e-10
        ));
    }

    #[rstest]
    #[case("1_234.56", 2, 1234.56)]
    #[case("1000000", 0, 1_000_000.0)]
    #[case("99_999.999_99", 5, 99_999.999_99)]
    fn test_from_str_with_underscores(
        #[case] input: &str,
        #[case] expected_precision: u8,
        #[case] expected_value: f64,
    ) {
        let qty = Quantity::from_str(input).unwrap();
        assert_eq!(qty.precision, expected_precision);
        assert!(approx_eq!(
            f64,
            qty.as_f64(),
            expected_value,
            epsilon = 1e-10
        ));
    }

    #[rstest]
    fn test_from_decimal_dp_preservation() {
        // Test that decimal conversion preserves exact values
        let decimal = dec!(123.456789);
        let qty = Quantity::from_decimal_dp(decimal, 6).unwrap();
        assert_eq!(qty.precision, 6);
        assert!(approx_eq!(f64, qty.as_f64(), 123.456_789, epsilon = 1e-10));

        // Verify raw value is exact
        let expected_raw = 123_456_789_u64 * 10_u64.pow(u32::from(FIXED_PRECISION - 6));
        assert_eq!(qty.raw, QuantityRaw::from(expected_raw));
    }

    #[rstest]
    fn test_from_decimal_dp_rounding() {
        // Test banker's rounding (round half to even)
        let decimal = dec!(1.005);
        let qty = Quantity::from_decimal_dp(decimal, 2).unwrap();
        assert_eq!(qty.as_f64(), 1.0); // 1.005 rounds to 1.00 (even)

        let decimal = dec!(1.015);
        let qty = Quantity::from_decimal_dp(decimal, 2).unwrap();
        assert_eq!(qty.as_f64(), 1.02); // 1.015 rounds to 1.02 (even)
    }

    #[rstest]
    fn test_from_decimal_infers_precision() {
        // Test that precision is inferred from decimal's scale
        let decimal = dec!(123.456);
        let qty = Quantity::from_decimal(decimal).unwrap();
        assert_eq!(qty.precision, 3);
        assert!(approx_eq!(f64, qty.as_f64(), 123.456, epsilon = 1e-10));

        // Test with integer (precision 0)
        let decimal = dec!(100);
        let qty = Quantity::from_decimal(decimal).unwrap();
        assert_eq!(qty.precision, 0);
        assert_eq!(qty.as_f64(), 100.0);

        // Test with high precision
        let decimal = dec!(1.23456789);
        let qty = Quantity::from_decimal(decimal).unwrap();
        assert_eq!(qty.precision, 8);
        assert!(approx_eq!(f64, qty.as_f64(), 1.234_567_89, epsilon = 1e-10));
    }

    #[rstest]
    fn test_from_decimal_trailing_zeros() {
        // Decimal preserves trailing zeros in scale
        let decimal = dec!(5.670);
        assert_eq!(decimal.scale(), 3); // Has 3 decimal places

        // from_decimal infers precision from scale (includes trailing zeros)
        let qty = Quantity::from_decimal(decimal).unwrap();
        assert_eq!(qty.precision, 3);
        assert!(approx_eq!(f64, qty.as_f64(), 5.67, epsilon = 1e-10));

        // Normalized removes trailing zeros
        let normalized = decimal.normalize();
        assert_eq!(normalized.scale(), 2);
        let qty_normalized = Quantity::from_decimal(normalized).unwrap();
        assert_eq!(qty_normalized.precision, 2);
    }

    #[rstest]
    #[case("1.00", 2)]
    #[case("1.0", 1)]
    #[case("1.000", 3)]
    #[case("100.00", 2)]
    #[case("0.10", 2)]
    #[case("0.100", 3)]
    fn test_from_str_preserves_trailing_zeros(#[case] input: &str, #[case] expected_precision: u8) {
        let qty = Quantity::from_str(input).unwrap();
        assert_eq!(qty.precision, expected_precision);
    }

    #[rstest]
    fn test_from_decimal_excessive_precision_inference() {
        // Create a decimal with more precision than FIXED_PRECISION
        // Decimal supports up to 28 decimal places
        let decimal = dec!(1.1234567890123456789012345678);

        // If scale exceeds FIXED_PRECISION, from_decimal should error
        if decimal.scale() > u32::from(FIXED_PRECISION) {
            assert!(Quantity::from_decimal(decimal).is_err());
        }
    }

    #[rstest]
    fn test_from_decimal_negative_quantity_errors() {
        // Negative quantities should error (Quantity must be non-negative)
        let decimal = dec!(-123.45);
        let result = Quantity::from_decimal(decimal);
        assert!(result.is_err());

        // Also test with explicit precision
        let result = Quantity::from_decimal_dp(decimal, 2);
        assert!(result.is_err());
    }

    #[rstest]
    fn test_from_decimal_dp_negative_returns_typed_error_with_stable_display() {
        let error = Quantity::from_decimal_dp(dec!(-1.5), 2).unwrap_err();
        assert_eq!(
            error,
            CorrectnessError::PredicateViolation {
                message: "Decimal value '-1.5' is negative, Quantity must be non-negative"
                    .to_string(),
            }
        );
        assert_eq!(
            error.to_string(),
            "Decimal value '-1.5' is negative, Quantity must be non-negative",
        );
    }

    #[cfg(not(feature = "high-precision"))]
    #[rstest]
    fn test_from_decimal_dp_rejects_quantity_raw_overflow() {
        let error = Quantity::from_decimal_dp(dec!(20_000_000_000), 0).unwrap_err();

        assert_eq!(
            error,
            CorrectnessError::PredicateViolation {
                message: format!("Decimal value exceeds QuantityRaw range [0, {QUANTITY_RAW_MAX}]"),
            }
        );
    }

    #[cfg(feature = "high-precision")]
    #[rstest]
    fn test_from_decimal_dp_rejects_value_above_quantity_max() {
        let value = 34_028_236_692_094_u64;
        let raw = u128::from(value) * FIXED_SCALAR_RAW;
        let error = Quantity::from_decimal_dp(Decimal::from(value), 0).unwrap_err();

        assert_eq!(
            error,
            CorrectnessError::PredicateViolation {
                message: format!(
                    "Raw value {raw} exceeds QUANTITY_RAW_MAX={QUANTITY_RAW_MAX} for Quantity"
                ),
            }
        );
    }

    #[rstest]
    fn test_add() {
        let a = 1.0;
        let b = 2.0;
        let quantity1 = Quantity::new(1.0, 0);
        let quantity2 = Quantity::new(2.0, 0);
        let quantity3 = quantity1 + quantity2;
        assert_eq!(quantity3.raw, Quantity::new(a + b, 0).raw);
    }

    #[rstest]
    fn test_sub() {
        let a = 3.0;
        let b = 2.0;
        let quantity1 = Quantity::new(a, 0);
        let quantity2 = Quantity::new(b, 0);
        let quantity3 = quantity1 - quantity2;
        assert_eq!(quantity3.raw, Quantity::new(a - b, 0).raw);
    }

    #[rstest]
    fn test_quantity_checked_add_within_bounds() {
        let a = Quantity::new(10.0, 2);
        let b = Quantity::new(5.0, 2);
        assert_eq!(a.checked_add(b), Some(Quantity::new(15.0, 2)));
    }

    #[rstest]
    fn test_quantity_checked_add_above_max_returns_none() {
        let near_max = Quantity::from_raw(QUANTITY_RAW_MAX, 0);
        let one = Quantity::new(1.0, 0);
        assert_eq!(near_max.checked_add(one), None);
    }

    #[rstest]
    fn test_quantity_checked_sub_within_bounds() {
        let a = Quantity::new(10.0, 2);
        let b = Quantity::new(3.0, 2);
        assert_eq!(a.checked_sub(b), Some(Quantity::new(7.0, 2)));
    }

    #[rstest]
    fn test_quantity_checked_sub_underflow_returns_none() {
        let a = Quantity::new(3.0, 2);
        let b = Quantity::new(10.0, 2);
        assert_eq!(a.checked_sub(b), None);
    }

    #[rstest]
    fn test_quantity_checked_sub_to_zero() {
        let a = Quantity::new(5.0, 2);
        assert_eq!(a.checked_sub(a), Some(Quantity::zero(2)));
    }

    #[rstest]
    fn test_quantity_checked_arith_rejects_undef() {
        let undef = Quantity::from_raw(QUANTITY_UNDEF, 0);
        let one = Quantity::new(1.0, 0);
        assert_eq!(undef.checked_add(one), None);
        assert_eq!(one.checked_add(undef), None);
        assert_eq!(undef.checked_sub(one), None);
        assert_eq!(one.checked_sub(undef), None);
    }

    #[rstest]
    fn test_quantity_checked_add_at_exact_max_returns_some() {
        let near_max = Quantity::from_raw(QUANTITY_RAW_MAX - 1, 0);
        let one_unit = Quantity::from_raw(1, 0);
        assert_eq!(
            near_max.checked_add(one_unit),
            Some(Quantity::from_raw(QUANTITY_RAW_MAX, 0)),
        );
    }

    #[rstest]
    fn test_quantity_checked_arith_uses_max_precision() {
        let a = Quantity::new(10.5, 1);
        let b = Quantity::new(2.25, 2);
        let sum = a.checked_add(b).unwrap();
        assert_eq!(sum.precision, 2);
        assert_eq!(sum.as_f64(), 12.75);

        let diff = a.checked_sub(b).unwrap();
        assert_eq!(diff.precision, 2);
        assert_eq!(diff.as_f64(), 8.25);
    }

    #[rstest]
    fn test_mul() {
        let value = 2.0;
        let quantity1 = Quantity::new(value, 1);
        let quantity2 = Quantity::new(value, 1);
        let quantity3 = quantity1 * quantity2;
        assert_eq!(quantity3.raw, Quantity::new(value * value, 0).raw);
    }

    #[rstest]
    fn test_mul_avoids_intermediate_raw_overflow() {
        let scalar = FIXED_SCALAR_RAW;
        #[cfg(feature = "high-precision")]
        let (lhs_raw, rhs_raw, expected_raw) =
            (100_000 * scalar, 100 * scalar, 10_000_000 * scalar);
        #[cfg(not(feature = "high-precision"))]
        let (lhs_raw, rhs_raw, expected_raw) = (
            9_000_000_000 * scalar,
            2 * scalar + 1,
            18_000_000_009 * scalar,
        );
        let lhs = Quantity::from_raw(lhs_raw, FIXED_PRECISION);
        let rhs = Quantity::from_raw(rhs_raw, FIXED_PRECISION);
        let result = lhs * rhs;

        assert_eq!(lhs_raw.checked_mul(rhs_raw), None);
        assert_eq!(result.raw, expected_raw);
        assert_eq!(result.precision, FIXED_PRECISION);
    }

    #[rstest]
    #[should_panic(expected = "Overflow occurred when multiplying `Quantity`")]
    fn test_mul_panics_when_scaled_result_exceeds_quantity_max() {
        let lhs = Quantity::from_raw(QUANTITY_RAW_MAX, FIXED_PRECISION);
        let rhs = Quantity::from(2);

        let _ = lhs * rhs;
    }

    #[rstest]
    fn test_comparisons() {
        assert_eq!(Quantity::new(1.0, 1), Quantity::new(1.0, 1));
        assert_eq!(Quantity::new(1.0, 1), Quantity::new(1.0, 2));
        assert_ne!(Quantity::new(1.1, 1), Quantity::new(1.0, 1));
        assert!(Quantity::new(1.0, 1) <= Quantity::new(1.0, 2));
        assert!(Quantity::new(1.1, 1) > Quantity::new(1.0, 1));
        assert!(Quantity::new(1.0, 1) >= Quantity::new(1.0, 1));
        assert!(Quantity::new(1.0, 1) >= Quantity::new(1.0, 2));
        assert!(Quantity::new(1.0, 1) >= Quantity::new(1.0, 2));
        assert!(Quantity::new(0.9, 1) < Quantity::new(1.0, 1));
        assert!(Quantity::new(0.9, 1) <= Quantity::new(1.0, 2));
        assert!(Quantity::new(0.9, 1) <= Quantity::new(1.0, 1));
    }

    #[rstest]
    fn test_debug() {
        let quantity = Quantity::from_str("44.12").unwrap();
        let result = format!("{quantity:?}");
        assert_eq!(result, "Quantity(44.12)");
    }

    #[rstest]
    fn test_display() {
        let quantity = Quantity::from_str("44.12").unwrap();
        let result = format!("{quantity}");
        assert_eq!(result, "44.12");
    }

    #[rstest]
    #[case(44.12, 2, "Quantity(44.12)", "44.12")] // Normal precision
    #[case(1234.567, 8, "Quantity(1234.56700000)", "1234.56700000")] // At max normal precision
    #[cfg_attr(
        feature = "defi",
        case(
            1_000_000_000_000_000_000.0,
            18,
            "Quantity(1000000000000000000)",
            "1000000000000000000"
        )
    )] // High precision
    fn test_debug_display_precision_handling(
        #[case] value: f64,
        #[case] precision: u8,
        #[case] expected_debug: &str,
        #[case] expected_display: &str,
    ) {
        let quantity = if precision > MAX_FLOAT_PRECISION {
            // For high precision, use from_raw to avoid f64 conversion issues
            Quantity::from_raw(value as QuantityRaw, precision)
        } else {
            Quantity::new(value, precision)
        };

        assert_eq!(format!("{quantity:?}"), expected_debug);
        assert_eq!(format!("{quantity}"), expected_display);
    }

    #[rstest]
    fn test_to_formatted_string() {
        let qty = Quantity::new(1234.5678, 4);
        let formatted = qty.to_formatted_string();
        assert_eq!(formatted, "1_234.5678");
        assert_eq!(qty.to_string(), "1234.5678");
    }

    #[rstest]
    fn test_saturating_sub() {
        let q1 = Quantity::new(100.0, 2);
        let q2 = Quantity::new(50.0, 2);
        let q3 = Quantity::new(150.0, 2);

        let result = q1.saturating_sub(q2);
        assert_eq!(result, Quantity::new(50.0, 2));

        let result = q1.saturating_sub(q3);
        assert_eq!(result, Quantity::zero(2));
        assert_eq!(result.raw, 0);
    }

    #[rstest]
    fn test_saturating_sub_overflow_bug() {
        // Reproduces original bug: subtracting a larger quantity from a smaller one
        // Raw values must be multiples of 10^(FIXED_PRECISION - precision)
        use crate::types::fixed::FIXED_PRECISION;
        let precision = 3;
        let scale = QuantityRaw::from(10u64.pow(u32::from(FIXED_PRECISION - precision)));

        // 79 * scale represents 0.079, 80 * scale represents 0.080
        let peak_qty = Quantity::from_raw(79 * scale, precision);
        let order_qty = Quantity::from_raw(80 * scale, precision);

        // This would have caused panic before fix due to underflow
        let result = peak_qty.saturating_sub(order_qty);
        assert_eq!(result.raw, 0);
        assert_eq!(result, Quantity::zero(precision));
    }

    #[rstest]
    fn test_hash() {
        use std::{
            collections::hash_map::DefaultHasher,
            hash::{Hash, Hasher},
        };

        let q1 = Quantity::new(100.0, 1);
        let q2 = Quantity::new(100.0, 1);
        let q3 = Quantity::new(200.0, 1);

        let mut s1 = DefaultHasher::new();
        let mut s2 = DefaultHasher::new();
        let mut s3 = DefaultHasher::new();

        q1.hash(&mut s1);
        q2.hash(&mut s2);
        q3.hash(&mut s3);

        assert_eq!(
            s1.finish(),
            s2.finish(),
            "Equal quantities must hash equally"
        );
        assert_ne!(
            s1.finish(),
            s3.finish(),
            "Different quantities must hash differently"
        );
    }

    #[rstest]
    fn test_quantity_serde_json_round_trip() {
        let original = Quantity::new(123.456, 3);
        let json_str = serde_json::to_string(&original).unwrap();
        assert_eq!(json_str, "\"123.456\"");

        let deserialized: Quantity = serde_json::from_str(&json_str).unwrap();
        assert_eq!(deserialized, original);
        assert_eq!(deserialized.precision, 3);
    }

    #[rstest]
    fn test_quantity_serde_json_from_value_round_trip() {
        let original = Quantity::new(123.456, 3);
        let value = serde_json::to_value(original).unwrap();
        assert_eq!(value, serde_json::json!("123.456"));

        let deserialized: Quantity = serde_json::from_value(value).unwrap();
        assert_eq!(deserialized, original);
        assert_eq!(deserialized.precision, 3);
    }

    #[rstest]
    fn test_quantity_deserialize_invalid_string_returns_error() {
        let result = serde_json::from_str::<Quantity>("\"not-a-quantity\"");
        let error = result.unwrap_err();
        assert!(
            error.to_string().contains("Error parsing"),
            "unexpected message: {error}"
        );
    }

    #[rstest]
    fn test_quantity_deserialize_negative_returns_error() {
        let result = serde_json::from_str::<Quantity>("\"-1.5\"");
        let error = result.unwrap_err();
        assert!(
            error.to_string().contains("negative"),
            "unexpected message: {error}"
        );
    }

    #[rstest]
    fn test_from_mantissa_exponent_exact_precision() {
        let qty = Quantity::from_mantissa_exponent(12345, -2, 2);
        assert_eq!(qty.as_f64(), 123.45);
    }

    #[rstest]
    fn test_from_mantissa_exponent_excess_rounds_down() {
        // 12.344 -> 12.34 (no rounding needed, truncation)
        // 12.345 rounds to 12.34 (4 is even, banker's rounding)
        let qty = Quantity::from_mantissa_exponent(12345, -3, 2);
        assert_eq!(qty.as_f64(), 12.34);
    }

    #[rstest]
    fn test_from_mantissa_exponent_excess_rounds_up() {
        // 12.355 rounds to 12.36 (5 is odd, banker's rounding)
        let qty = Quantity::from_mantissa_exponent(12355, -3, 2);
        assert_eq!(qty.as_f64(), 12.36);
    }

    #[rstest]
    fn test_from_mantissa_exponent_positive_exponent() {
        let qty = Quantity::from_mantissa_exponent(5, 2, 0);
        assert_eq!(qty.as_f64(), 500.0);
    }

    #[rstest]
    fn test_from_mantissa_exponent_zero() {
        let qty = Quantity::from_mantissa_exponent(0, 2, 2);
        assert_eq!(qty.as_f64(), 0.0);
    }

    #[cfg(feature = "high-precision")]
    #[rstest]
    #[case(QUANTITY_RAW_MAX, dec!(34028236692093))]
    #[case(80_000_000_000_000_000_000_000_000_000, dec!(8000000000000))]
    fn test_as_decimal_above_decimal_mantissa(#[case] raw: QuantityRaw, #[case] expected: Decimal) {
        // Regression: a precision-16 quantity above roughly 7.92e12 rescales to a raw value
        // beyond `Decimal`'s 96-bit mantissa, which used to panic during conversion.
        let qty = Quantity::from_raw(raw, 16);

        assert_eq!(qty.as_decimal(), expected);
    }

    #[rstest]
    fn test_from_mantissa_exponent_checked_exact_precision() {
        let qty = Quantity::from_mantissa_exponent_checked(12345, -2, 2).unwrap();
        assert_eq!(qty.as_decimal(), dec!(123.45));
    }

    #[rstest]
    fn test_from_mantissa_exponent_checked_zero_with_large_exponent() {
        let qty = Quantity::from_mantissa_exponent_checked(0, 119, 2).unwrap();
        assert_eq!(qty.as_decimal(), dec!(0.00));
    }

    #[rstest]
    fn test_from_mantissa_exponent_checked_invalid_precision() {
        #[cfg(feature = "defi")]
        let invalid_precision = crate::defi::WEI_PRECISION + 1;
        #[cfg(not(feature = "defi"))]
        let invalid_precision = FIXED_PRECISION + 1;

        let error = Quantity::from_mantissa_exponent_checked(1, 0, invalid_precision).unwrap_err();
        assert!(error.to_string().contains("`precision` exceeded maximum"));
    }

    #[rstest]
    fn test_from_mantissa_exponent_checked_overflow_returns_error() {
        let error = Quantity::from_mantissa_exponent_checked(u64::MAX, 100, 0).unwrap_err();
        assert!(
            error
                .to_string()
                .contains("Overflow in Quantity::from_mantissa_exponent")
        );
    }

    #[rstest]
    #[should_panic(expected = "Quantity::from_mantissa_exponent")]
    fn test_from_mantissa_exponent_overflow_panics() {
        let _ = Quantity::from_mantissa_exponent(u64::MAX, 9, 0);
    }

    #[rstest]
    #[should_panic(expected = "exceeds i128 range")]
    fn test_from_mantissa_exponent_large_exponent_panics() {
        let _ = Quantity::from_mantissa_exponent(1, 119, 0);
    }

    #[rstest]
    fn test_from_mantissa_exponent_zero_with_large_exponent() {
        let qty = Quantity::from_mantissa_exponent(0, 119, 0);
        assert_eq!(qty.as_f64(), 0.0);
    }

    #[rstest]
    fn test_from_mantissa_exponent_very_negative_exponent_rounds_to_zero() {
        let qty = Quantity::from_mantissa_exponent(12345, -120, 2);
        assert_eq!(qty.as_f64(), 0.0);
    }

    #[rstest]
    fn test_f64_operations() {
        let q = Quantity::new(10.5, 2);
        assert_eq!(q + 1.0, 11.5);
        assert_eq!(q - 1.0, 9.5);
        assert_eq!(q * 2.0, 21.0);
        assert_eq!(q / 2.0, 5.25);
    }

    #[rstest]
    fn test_decimal_arithmetic_operations() {
        let qty = Quantity::new(100.0, 2);
        assert_eq!(qty + dec!(50.25), dec!(150.25));
        assert_eq!(qty - dec!(30.50), dec!(69.50));
        assert_eq!(qty * dec!(1.5), dec!(150.00));
        assert_eq!(qty / dec!(4), dec!(25.00));
    }

    /// Tests `Quantity::from_u256` using real swap event data from Arbitrum transactions, result values sourced from `DexScreener`.
    /// Data sourced from:
    /// - Sell tx: <https://arbiscan.io/tx/0xb417009ce3bd9b9f2dde7d52277ffc9f1b1733ecedfcc7f8e3dedd5d87160325>
    #[rstest]
    #[cfg(feature = "defi")]
    #[case::sell_tx_rain_amount(
        U256::from_str_radix("42193532365637161405123", 10).unwrap(),
        18,
        "42193.532365637161405123"
    )]
    #[case::sell_tx_weth_amount(
        U256::from_str_radix("112633187203033110", 10).unwrap(),
        18,
        "0.112633187203033110"
    )]
    fn test_from_u256_real_swap_data(
        #[case] amount: U256,
        #[case] precision: u8,
        #[case] expected_str: &str,
    ) {
        let qty = Quantity::from_u256(amount, precision).unwrap();
        assert_eq!(qty.precision, precision);
        assert_eq!(qty.as_decimal().to_string(), expected_str);
    }

    #[rstest]
    #[cfg(feature = "defi")]
    fn test_from_u256_overflow_returns_typed_error_with_stable_display() {
        let error = Quantity::from_u256(U256::MAX, 0).unwrap_err();
        match error {
            CorrectnessError::PredicateViolation { ref message } => {
                assert!(
                    message.contains("Amount overflow during scaling to fixed precision"),
                    "unexpected message: {message:?}",
                );
            }
            _ => panic!("expected PredicateViolation, was {error:?}"),
        }
    }

    #[rstest]
    #[cfg(feature = "defi")]
    fn test_from_u256_rejects_amount_above_quantity_raw_range() {
        let amount = U256::from(u128::MAX) + U256::from(1_u8);
        let error = Quantity::from_u256(amount, 18).unwrap_err();

        assert_eq!(
            error,
            CorrectnessError::PredicateViolation {
                message: format!("U256 scaled amount {amount} exceeds QuantityRaw range"),
            }
        );
    }

    #[rstest]
    #[cfg(feature = "defi")]
    fn test_from_u256_invalid_precision_returns_typed_error() {
        let error = Quantity::from_u256(U256::from(1u8), 19).unwrap_err();
        match error {
            CorrectnessError::PredicateViolation { ref message } => {
                assert!(
                    message.contains("WEI_PRECISION"),
                    "unexpected message: {message:?}",
                );
            }
            _ => panic!("expected PredicateViolation, was {error:?}"),
        }
    }

    #[rstest]
    #[cfg(feature = "defi")]
    fn test_from_u256_raw_above_max_returns_typed_error() {
        // Pick a U256 value whose scaled raw lies between QUANTITY_RAW_MAX and
        // QuantityRaw::MAX so try_from succeeds but from_raw_checked rejects it.
        let raw = QUANTITY_RAW_MAX + 1;
        let error = Quantity::from_u256(U256::from(raw), FIXED_PRECISION).unwrap_err();
        match error {
            CorrectnessError::PredicateViolation { ref message } => {
                assert!(
                    message.contains("QUANTITY_RAW_MAX"),
                    "unexpected message: {message:?}",
                );
            }
            _ => panic!("expected PredicateViolation, was {error:?}"),
        }
    }
}

#[cfg(test)]
mod property_tests {
    use proptest::prelude::*;
    use rstest::rstest;

    use super::*;

    /// Strategy to generate valid quantity values (non-negative).
    fn quantity_value_strategy() -> impl Strategy<Value = f64> {
        // Use a reasonable range for quantities - must be non-negative
        prop_oneof![
            // Small positive values
            0.00001..1.0,
            // Normal trading range
            1.0..100_000.0,
            // Large values (but safe)
            100_000.0..1_000_000.0,
            // Include zero
            Just(0.0),
            // Boundary cases
            Just(QUANTITY_MAX / 2.0),
        ]
    }

    /// Strategy to generate valid precision values.
    fn precision_strategy() -> impl Strategy<Value = u8> {
        let upper = FIXED_PRECISION.min(MAX_FLOAT_PRECISION);
        prop_oneof![Just(0u8), 0u8..=upper, Just(FIXED_PRECISION),]
    }

    fn precision_strategy_non_zero() -> impl Strategy<Value = u8> {
        let upper = FIXED_PRECISION.clamp(1, MAX_FLOAT_PRECISION);
        prop_oneof![Just(upper), Just(FIXED_PRECISION.max(1)), 1u8..=upper,]
    }

    fn raw_for_precision_strategy() -> impl Strategy<Value = (QuantityRaw, u8)> {
        precision_strategy().prop_flat_map(|precision| {
            let step_u128 = 10u128.pow(u32::from(FIXED_PRECISION.saturating_sub(precision)));
            #[cfg(feature = "high-precision")]
            let max_steps_u128 = QUANTITY_RAW_MAX / step_u128;
            #[cfg(not(feature = "high-precision"))]
            let max_steps_u128 = u128::from(QUANTITY_RAW_MAX) / step_u128;

            (0u128..=max_steps_u128).prop_map(move |steps_u128| {
                let raw_u128 = steps_u128 * step_u128;
                #[cfg(feature = "high-precision")]
                let raw = raw_u128;
                #[cfg(not(feature = "high-precision"))]
                let raw = raw_u128
                    .try_into()
                    .expect("raw value should fit in QuantityRaw");
                (raw, precision)
            })
        })
    }

    const DECIMAL_MAX_MANTISSA: u128 = 79_228_162_514_264_337_593_543_950_335;

    fn decimal_compatible(raw: QuantityRaw, precision: u8) -> bool {
        if precision > MAX_FLOAT_PRECISION {
            return false;
        }
        let precision_diff = u32::from(FIXED_PRECISION.saturating_sub(precision));
        let divisor = 10u128.pow(precision_diff);
        #[cfg(feature = "high-precision")]
        let rescaled_raw = raw / divisor;
        #[cfg(not(feature = "high-precision"))]
        let rescaled_raw = u128::from(raw) / divisor;
        // rust_decimal stores the coefficient in 96 bits; this guard mirrors that bound so
        // proptests skip cases the runtime representation cannot encode.
        rescaled_raw <= DECIMAL_MAX_MANTISSA
    }

    proptest! {
        /// Property: Quantity string serialization round-trip should preserve value and precision
        #[rstest]
        fn prop_quantity_serde_round_trip(
            (raw, precision) in raw_for_precision_strategy()
        ) {
            // Only run string-based round-trip checks where decimal formatting is supported.
            prop_assume!(decimal_compatible(raw, precision));

            let original = Quantity::from_raw(raw, precision);

            // String round-trip (this should be exact and is the most important)
            let string_repr = original.to_string();
            let from_string: Quantity = string_repr.parse().unwrap();
            prop_assert_eq!(from_string.raw, original.raw);
            prop_assert_eq!(from_string.precision, original.precision);

            // JSON round-trip basic validation (just ensure it doesn't crash and preserves precision)
            let json = serde_json::to_string(&original).unwrap();
            let from_json: Quantity = serde_json::from_str(&json).unwrap();
            prop_assert_eq!(from_json.precision, original.precision);
            prop_assert_eq!(from_json.raw, original.raw);
        }

        /// Property: Quantity arithmetic should be associative for same precision
        #[rstest]
        fn prop_quantity_arithmetic_associative(
            a in quantity_value_strategy().prop_filter("Reasonable values", |&x| x > 1e-3 && x < 1e6),
            b in quantity_value_strategy().prop_filter("Reasonable values", |&x| x > 1e-3 && x < 1e6),
            c in quantity_value_strategy().prop_filter("Reasonable values", |&x| x > 1e-3 && x < 1e6),
            precision in precision_strategy()
        ) {
            let q_a = Quantity::new(a, precision);
            let q_b = Quantity::new(b, precision);
            let q_c = Quantity::new(c, precision);

            let expected = q_a
                .raw
                .checked_add(q_b.raw)
                .and_then(|sum| sum.checked_add(q_c.raw))
                .filter(|sum| *sum <= QUANTITY_RAW_MAX);

            if let Some(expected) = expected {
                let left = (q_a + q_b) + q_c;
                let right = q_a + (q_b + q_c);
                prop_assert_eq!(left.raw, expected);
                prop_assert_eq!(right.raw, expected);
            }
        }

        /// Property: Quantity addition/subtraction should be inverse operations (when valid)
        #[rstest]
        fn prop_quantity_addition_subtraction_inverse(
            base in quantity_value_strategy().prop_filter("Reasonable values", |&x| x < 1e6),
            delta in quantity_value_strategy().prop_filter("Reasonable values", |&x| x > 1e-3 && x < 1e6),
            precision in precision_strategy()
        ) {
            let q_base = Quantity::new(base, precision);
            let q_delta = Quantity::new(delta, precision);

            let expected = q_base
                .raw
                .checked_add(q_delta.raw)
                .filter(|sum| *sum <= QUANTITY_RAW_MAX);

            if expected.is_some() {
                prop_assert_eq!((q_base + q_delta) - q_delta, q_base);
            }
        }

        /// Property: checked_add agrees with raw checked_add when result is in bounds and
        /// no operand is QUANTITY_UNDEF; returns None otherwise.
        #[rstest]
        fn prop_quantity_checked_add_matches_spec(
            a in quantity_value_strategy(),
            b in quantity_value_strategy(),
            precision in precision_strategy()
        ) {
            let q_a = Quantity::new(a, precision);
            let q_b = Quantity::new(b, precision);
            let expected = q_a.raw
                .checked_add(q_b.raw)
                .filter(|r| *r <= QUANTITY_RAW_MAX)
                .filter(|_| q_a.raw != QUANTITY_UNDEF && q_b.raw != QUANTITY_UNDEF)
                .map(|raw| Quantity { raw, precision: q_a.precision.max(q_b.precision) });
            prop_assert_eq!(q_a.checked_add(q_b), expected);
        }

        /// Property: checked_sub agrees with raw checked_sub when no operand is
        /// QUANTITY_UNDEF; returns None otherwise.
        #[rstest]
        fn prop_quantity_checked_sub_matches_spec(
            a in quantity_value_strategy(),
            b in quantity_value_strategy(),
            precision in precision_strategy()
        ) {
            let q_a = Quantity::new(a, precision);
            let q_b = Quantity::new(b, precision);
            let expected = q_a.raw
                .checked_sub(q_b.raw)
                .filter(|_| q_a.raw != QUANTITY_UNDEF && q_b.raw != QUANTITY_UNDEF)
                .map(|raw| Quantity { raw, precision: q_a.precision.max(q_b.precision) });
            prop_assert_eq!(q_a.checked_sub(q_b), expected);
        }

        /// Property: Quantity ordering should be transitive
        #[rstest]
        fn prop_quantity_ordering_transitive(
            a in quantity_value_strategy(),
            b in quantity_value_strategy(),
            c in quantity_value_strategy(),
            precision in precision_strategy()
        ) {
            let q_a = Quantity::new(a, precision);
            let q_b = Quantity::new(b, precision);
            let q_c = Quantity::new(c, precision);

            // If a <= b and b <= c, then a <= c
            if q_a <= q_b && q_b <= q_c {
                prop_assert!(q_a <= q_c, "Transitivity failed: {} <= {} <= {} but {} > {}",
                    q_a.as_f64(), q_b.as_f64(), q_c.as_f64(), q_a.as_f64(), q_c.as_f64());
            }
        }

        /// Property: String parsing should be consistent with precision inference
        #[rstest]
        fn prop_quantity_string_parsing_precision(
            integral in 0u32..1_000_000,
            fractional in 0u32..1_000_000,
            precision in precision_strategy_non_zero()
        ) {
            // Create a decimal string with exactly 'precision' decimal places
            let pow = 10u128.pow(u32::from(precision));
            let fractional_mod = u128::from(fractional) % pow;
            let fractional_str = format!("{:0width$}", fractional_mod, width = precision as usize);
            let quantity_str = format!("{integral}.{fractional_str}");

            let parsed: Quantity = quantity_str.parse().unwrap();
            prop_assert_eq!(parsed.precision, precision);

            // Round-trip should preserve the original string (after normalization)
            let round_trip = parsed.to_string();
            let expected_value = format!("{integral}.{fractional_str}");
            prop_assert_eq!(round_trip, expected_value);
        }

        /// Property: Quantity arithmetic should never produce invalid values
        #[rstest]
        fn prop_quantity_arithmetic_bounds(
            a in quantity_value_strategy(),
            b in quantity_value_strategy(),
            precision in precision_strategy()
        ) {
            let q_a = Quantity::new(a, precision);
            let q_b = Quantity::new(b, precision);

            // Addition should either succeed or fail predictably
            let sum_f64 = q_a.as_f64() + q_b.as_f64();
            if sum_f64.is_finite() && (QUANTITY_MIN..=QUANTITY_MAX).contains(&sum_f64) {
                let sum = q_a + q_b;
                prop_assert!(sum.as_f64().is_finite());
                prop_assert!(!sum.is_undefined());
            }

            // Subtraction should either succeed or fail predictably
            let diff_f64 = q_a.as_f64() - q_b.as_f64();
            if diff_f64.is_finite() && (QUANTITY_MIN..=QUANTITY_MAX).contains(&diff_f64) {
                let diff = q_a - q_b;
                prop_assert!(diff.as_f64().is_finite());
                prop_assert!(!diff.is_undefined());
            }
        }

        /// Property: Multiplication should preserve non-negativity
        #[rstest]
        fn prop_quantity_multiplication_non_negative(
            a in quantity_value_strategy().prop_filter("Reasonable values", |&x| x > 0.0 && x < 10.0),
            b in quantity_value_strategy().prop_filter("Reasonable values", |&x| x > 0.0 && x < 10.0),
            precision in precision_strategy()
        ) {
            let q_a = Quantity::new(a, precision);
            let q_b = Quantity::new(b, precision);

            // Check if multiplication would overflow at the raw level before performing it
            let raw_product_check = q_a.raw.checked_mul(q_b.raw);

            if let Some(raw_product) = raw_product_check {
                // Additional check to ensure the scaled result won't overflow
                let scaled_raw = raw_product / FIXED_SCALAR_RAW;
                if scaled_raw <= QUANTITY_RAW_MAX {
                    // Multiplying two quantities should always result in a non-negative value
                    let product = q_a * q_b;
                    prop_assert!(product.as_f64() >= 0.0, "Quantity multiplication produced negative value: {}", product.as_f64());
                }
            }
        }

        /// Property: Zero quantity should be identity for addition
        #[rstest]
        fn prop_quantity_zero_addition_identity(
            value in quantity_value_strategy(),
            precision in precision_strategy()
        ) {
            let q = Quantity::new(value, precision);
            let zero = Quantity::zero(precision);

            // q + 0 = q and 0 + q = q
            prop_assert_eq!(q + zero, q);
            prop_assert_eq!(zero + q, q);
        }
    }

    proptest! {
        /// Property: as_decimal scale always matches precision
        #[rstest]
        fn prop_quantity_as_decimal_preserves_precision(
            (raw, precision) in raw_for_precision_strategy()
        ) {
            prop_assume!(decimal_compatible(raw, precision));
            let quantity = Quantity::from_raw(raw, precision);
            let decimal = quantity.as_decimal();
            prop_assert_eq!(decimal.scale(), u32::from(precision));
        }

        /// Property: as_decimal and Display produce the same string
        #[rstest]
        fn prop_quantity_as_decimal_matches_display(
            (raw, precision) in raw_for_precision_strategy()
        ) {
            prop_assume!(decimal_compatible(raw, precision));
            let quantity = Quantity::from_raw(raw, precision);
            let display_str = format!("{quantity}");
            let decimal_str = quantity.as_decimal().to_string();
            prop_assert_eq!(display_str, decimal_str);
        }

        /// Property: from_decimal roundtrip preserves exact value
        #[rstest]
        fn prop_quantity_from_decimal_roundtrip(
            (raw, precision) in raw_for_precision_strategy()
        ) {
            prop_assume!(decimal_compatible(raw, precision));
            let original = Quantity::from_raw(raw, precision);
            let decimal = original.as_decimal();
            let reconstructed = Quantity::from_decimal(decimal).unwrap();
            prop_assert_eq!(original.raw, reconstructed.raw);
            prop_assert_eq!(original.precision, reconstructed.precision);
        }

        /// Property: constructing from raw within bounds preserves raw/precision
        #[rstest]
        fn prop_quantity_from_raw_round_trip(
            (raw, precision) in raw_for_precision_strategy()
        ) {
            let quantity = Quantity::from_raw(raw, precision);
            prop_assert_eq!(quantity.raw, raw);
            prop_assert_eq!(quantity.precision, precision);
        }
    }
}