nautilus_model/types/

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

//! Functions for handling fixed-point arithmetic.
//!
//! This module provides constants and functions that enforce a fixed-point precision strategy,
//! ensuring consistent precision and scaling across various types and calculations.
//!
//! # Raw Value Requirements
//!
//! When constructing value types like [`Price`] or [`Quantity`] using `from_raw`, the raw value
//! **must** be a valid multiple of the scale factor for the given precision. Valid raw values
//! should ideally come from:
//!
//! - Accessing the `.raw` field of an existing value (e.g., `price.raw`)
//! - Using the fixed-point conversion functions in this module
//! - Values from Nautilus-produced Arrow data
//!
//! Raw values that are not valid multiples will cause a panic on construction in debug builds,
//! and may result in incorrect values in release builds.
//!
//! # Legacy Catalog Data and Floating-Point Errors
//!
//! Data written to catalogs using V2 wranglers before 16th December 2025 may contain raw values with
//! floating-point precision errors. This occurred because the wranglers used:
//!
//! ```text
//! int(value * FIXED_SCALAR)  # Introduces floating-point errors
//! ```
//!
//! instead of the correct precision-aware approach:
//!
//! ```text
//! round(value * 10^precision) * scale  # Correct
//! ```
//!
//! # Raw Value Correction
//!
//! To handle legacy data with floating-point errors, the Arrow decode path uses correction
//! functions ([`correct_raw_i64`], [`correct_raw_i128`], etc.) to round raw values to the
//! nearest valid multiple. This ensures backward compatibility with existing catalogs.
//!
//! **Note:** This correction adds a small amount of overhead during decoding. In a future
//! version, once catalogs have been repaired or migrated, this correction will become opt-in.
//!
//! [`Price`]: crate::types::Price
//! [`Quantity`]: crate::types::Quantity

use std::fmt::Display;

use nautilus_core::correctness::{
    CorrectnessError, CorrectnessResult, CorrectnessResultExt, FAILED,
};

use crate::types::{price::PriceRaw, quantity::QuantityRaw};

/// Indicates if high-precision mode is enabled.
///
/// # Safety
///
/// This static variable is initialized at compile time and never mutated,
/// making it safe to read from multiple threads without synchronization.
/// The value is determined by the "high-precision" feature flag.
#[unsafe(no_mangle)]
#[allow(unsafe_code)]
pub static HIGH_PRECISION_MODE: u8 = cfg!(feature = "high-precision") as u8;

// -----------------------------------------------------------------------------
// FIXED_PRECISION
// -----------------------------------------------------------------------------

#[cfg(feature = "high-precision")]
/// The maximum fixed-point precision.
pub const FIXED_PRECISION: u8 = 16;

#[cfg(not(feature = "high-precision"))]
/// The maximum fixed-point precision.
pub const FIXED_PRECISION: u8 = 9;

// -----------------------------------------------------------------------------
// PRECISION_BYTES (size of integer backing the fixed-point values)
// -----------------------------------------------------------------------------

#[cfg(feature = "high-precision")]
/// The width in bytes for fixed-point value types in high-precision mode (128-bit).
pub const PRECISION_BYTES: i32 = 16;

#[cfg(not(feature = "high-precision"))]
/// The width in bytes for fixed-point value types in standard-precision mode (64-bit).
pub const PRECISION_BYTES: i32 = 8;

// -----------------------------------------------------------------------------
// FIXED_BINARY_SIZE
// -----------------------------------------------------------------------------

#[cfg(feature = "high-precision")]
/// The data type name for the Arrow fixed-size binary representation.
pub const FIXED_SIZE_BINARY: &str = "FixedSizeBinary(16)";

#[cfg(not(feature = "high-precision"))]
/// The data type name for the Arrow fixed-size binary representation.
pub const FIXED_SIZE_BINARY: &str = "FixedSizeBinary(8)";

// -----------------------------------------------------------------------------
// FIXED_SCALAR
// -----------------------------------------------------------------------------

#[cfg(feature = "high-precision")]
/// The scalar value corresponding to the maximum precision (10^16).
pub const FIXED_SCALAR: f64 = 10_000_000_000_000_000.0;

#[cfg(not(feature = "high-precision"))]
/// The scalar value corresponding to the maximum precision (10^9).
pub const FIXED_SCALAR: f64 = 1_000_000_000.0;

// -----------------------------------------------------------------------------
// PRECISION_DIFF_SCALAR
// -----------------------------------------------------------------------------

#[cfg(feature = "high-precision")]
/// The scalar representing the difference between high-precision and standard-precision modes.
pub const PRECISION_DIFF_SCALAR: f64 = 10_000_000.0; // 10^(16-9)

#[cfg(not(feature = "high-precision"))]
/// The scalar representing the difference between high-precision and standard-precision modes.
pub const PRECISION_DIFF_SCALAR: f64 = 1.0;

// -----------------------------------------------------------------------------
// POWERS_OF_10 (lookup table for fast validation)
// -----------------------------------------------------------------------------

/// Precomputed powers of 10 for fast scale lookup.
///
/// Index i contains 10^i. Table covers 10^0 through 10^16 (sufficient for `FIXED_PRECISION`).
/// Used by `check_fixed_raw_*` functions to avoid runtime exponentiation.
const POWERS_OF_10: [u64; 17] = [
    1,                      // 10^0
    10,                     // 10^1
    100,                    // 10^2
    1_000,                  // 10^3
    10_000,                 // 10^4
    100_000,                // 10^5
    1_000_000,              // 10^6
    10_000_000,             // 10^7
    100_000_000,            // 10^8
    1_000_000_000,          // 10^9
    10_000_000_000,         // 10^10
    100_000_000_000,        // 10^11
    1_000_000_000_000,      // 10^12
    10_000_000_000_000,     // 10^13
    100_000_000_000_000,    // 10^14
    1_000_000_000_000_000,  // 10^15
    10_000_000_000_000_000, // 10^16
];

// Compile-time verification that FIXED_PRECISION is within table bounds.
// We index POWERS_OF_10[FIXED_PRECISION] when precision=0, so need strict `<`.
const _: () = assert!(
    (FIXED_PRECISION as usize) < POWERS_OF_10.len(),
    "FIXED_PRECISION exceeds POWERS_OF_10 table size"
);

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

/// The maximum precision that can be safely used with f64-based constructors.
///
/// This is a hard limit imposed by IEEE 754 double-precision floating-point representation,
/// which has approximately 15-17 significant decimal digits. Beyond 16 decimal places,
/// floating-point arithmetic becomes unreliable due to rounding errors.
///
/// For higher precision values (such as 18-decimal wei values in DeFi), specialized
/// constructors that work with integer representations should be used instead.
pub const MAX_FLOAT_PRECISION: u8 = 16;

/// Checks if a given `precision` value is within the allowed fixed-point precision range.
///
/// # Errors
///
/// Returns an error if `precision` exceeds the maximum allowed:
/// - With `defi` feature: [`WEI_PRECISION`](crate::defi::WEI_PRECISION) (18)
/// - Without `defi` feature: [`FIXED_PRECISION`]
pub fn check_fixed_precision(precision: u8) -> CorrectnessResult<()> {
    #[cfg(feature = "defi")]
    if precision > crate::defi::WEI_PRECISION {
        return Err(CorrectnessError::PredicateViolation {
            message: format!("`precision` exceeded maximum `WEI_PRECISION` (18), was {precision}"),
        });
    }

    #[cfg(not(feature = "defi"))]
    if precision > FIXED_PRECISION {
        return Err(CorrectnessError::PredicateViolation {
            message: format!(
                "`precision` exceeded maximum `FIXED_PRECISION` ({FIXED_PRECISION}), was {precision}"
            ),
        });
    }

    Ok(())
}

/// Returns `true` when two precisions encode their `raw` values at the same scale.
///
/// The effective scale for a given precision is `max(precision, FIXED_PRECISION)`:
/// - Standard precisions (`<= FIXED_PRECISION`) all store raw at `FIXED_SCALAR` scale.
/// - Defi precisions (`> FIXED_PRECISION`, e.g. 17 or 18) each store raw at their own
///   native `10^precision` scale via constructors like `Price::from_wei` /
///   `Quantity::from_u256`.
///
/// Two precisions match iff their effective scales are identical. Mixing different
/// scales in raw arithmetic produces wrong results.
#[inline]
#[must_use]
pub fn raw_scales_match(a: u8, b: u8) -> bool {
    a.max(FIXED_PRECISION) == b.max(FIXED_PRECISION)
}

// -----------------------------------------------------------------------------
// Raw value validation
// -----------------------------------------------------------------------------

/// Returns `true` if validation should be skipped, `false` to proceed.
///
/// Validation is skipped when precision >= `FIXED_PRECISION` because every bit of the raw
/// value is significant. For precision > `FIXED_PRECISION` without the defi feature,
/// a debug assertion fires to surface potential misuse during development.
#[inline(always)]
fn should_skip_validation(precision: u8) -> bool {
    if precision == FIXED_PRECISION {
        return true;
    }

    if precision > FIXED_PRECISION {
        // Only assert when defi feature is disabled - with defi, 18dp is legitimate
        #[cfg(not(feature = "defi"))]
        debug_assert!(
            false,
            "precision {precision} exceeds FIXED_PRECISION {FIXED_PRECISION}: \
             raw value validation is not possible at this precision"
        );
        return true;
    }

    false
}

/// Builds the error for invalid fixed-point raw values (cold path).
#[cold]
fn invalid_raw_error(
    raw: impl Display,
    precision: u8,
    remainder: impl Display,
    scale: impl Display,
) -> anyhow::Error {
    anyhow::anyhow!(
        "Invalid fixed-point raw value {raw} for precision {precision}: \
         remainder {remainder} when divided by scale {scale}. \
         Raw value should be a multiple of {scale}. \
         This indicates data corruption or incorrect precision/scaling upstream"
    )
}

/// Checks that a raw unsigned fixed-point value has no spurious bits beyond the precision scale.
///
/// For a given precision P where P < `FIXED_PRECISION`, valid raw values must be exact
/// multiples of `10^(FIXED_PRECISION` - P). Any non-zero remainder indicates data corruption
/// or incorrect scaling upstream.
///
/// # Precision Limits
///
/// This check only validates when `precision < FIXED_PRECISION`:
/// - When `precision == FIXED_PRECISION`, every bit of the raw value is significant and
///   the check passes trivially (no "extra" bits to validate).
/// - When `precision > FIXED_PRECISION` (possible with defi feature allowing up to 18dp),
///   validation is not possible because the requested precision exceeds our internal
///   representation. A debug assertion will fire to surface this during development.
///
/// **Important**: For defi 18dp values, this check provides NO protection against incorrectly scaled
/// raw values. The inherent limitation is that we cannot detect if a 16dp raw is incorrectly
/// labeled as 18dp, since both would appear valid at full internal precision.
///
/// # Example
///
/// With `FIXED_PRECISION=9` and precision=0:
/// - Valid: `raw=120_000_000_000` (120 * 10^9, divisible by 10^9)
/// - Invalid: `raw=119_582_001_968_421_736` (remainder `968_421_736` when divided by 10^9)
///
/// # Errors
///
/// Returns an error if the raw value has non-zero bits beyond the precision scale
/// (only when `precision < FIXED_PRECISION`).
#[inline(always)]
pub fn check_fixed_raw_u128(raw: u128, precision: u8) -> anyhow::Result<()> {
    if should_skip_validation(precision) {
        return Ok(());
    }

    let exp = usize::from(FIXED_PRECISION - precision);
    let scale = u128::from(POWERS_OF_10[exp]);
    let remainder = raw % scale;

    if remainder != 0 {
        return Err(invalid_raw_error(raw, precision, remainder, scale));
    }

    Ok(())
}

/// Checks that a raw unsigned fixed-point value (64-bit) has no spurious bits.
///
/// Uses direct u64 arithmetic for better performance than widening to u128.
/// See [`check_fixed_raw_u128`] for full documentation on precision limits and behavior.
///
/// # Errors
///
/// Returns an error if the raw value has non-zero bits beyond the precision scale.
#[inline(always)]
pub fn check_fixed_raw_u64(raw: u64, precision: u8) -> anyhow::Result<()> {
    if should_skip_validation(precision) {
        return Ok(());
    }

    let exp = usize::from(FIXED_PRECISION - precision);
    let scale = POWERS_OF_10[exp];
    let remainder = raw % scale;

    if remainder != 0 {
        return Err(invalid_raw_error(raw, precision, remainder, scale));
    }

    Ok(())
}

/// Checks that a raw signed fixed-point value has no spurious bits beyond the precision scale.
///
/// For a given precision P where P < `FIXED_PRECISION`, valid raw values must be exact
/// multiples of `10^(FIXED_PRECISION` - P). Any non-zero remainder indicates data corruption
/// or incorrect scaling upstream.
///
/// # Precision Limits
///
/// This check only validates when `precision < FIXED_PRECISION`:
/// - When `precision == FIXED_PRECISION`, every bit of the raw value is significant and
///   the check passes trivially (no "extra" bits to validate).
/// - When `precision > FIXED_PRECISION` (possible with defi feature allowing up to 18dp),
///   validation is not possible because the requested precision exceeds our internal
///   representation. A debug assertion will fire to surface this during development.
///
/// **Important**: For defi 18dp values, this check provides NO protection against incorrectly scaled
/// raw values. The inherent limitation is that we cannot detect if a 16dp raw is incorrectly
/// labeled as 18dp, since both would appear valid at full internal precision.
///
/// # Example
///
/// With `FIXED_PRECISION=9` and precision=0:
/// - Valid: `raw=120_000_000_000` (120 * 10^9, divisible by 10^9)
/// - Invalid: `raw=119_582_001_968_421_736` (remainder `968_421_736` when divided by 10^9)
///
/// # Errors
///
/// Returns an error if the raw value has non-zero bits beyond the precision scale
/// (only when `precision < FIXED_PRECISION`).
#[inline(always)]
pub fn check_fixed_raw_i128(raw: i128, precision: u8) -> anyhow::Result<()> {
    if should_skip_validation(precision) {
        return Ok(());
    }

    let exp = usize::from(FIXED_PRECISION - precision);
    let scale = i128::from(POWERS_OF_10[exp]);
    let remainder = raw % scale;

    if remainder != 0 {
        return Err(invalid_raw_error(raw, precision, remainder, scale));
    }

    Ok(())
}

/// Checks that a raw signed fixed-point value (64-bit) has no spurious bits.
///
/// Uses direct i64 arithmetic for better performance than widening to i128.
/// See [`check_fixed_raw_i128`] for full documentation on precision limits and behavior.
///
/// # Errors
///
/// Returns an error if the raw value has non-zero bits beyond the precision scale.
#[inline(always)]
pub fn check_fixed_raw_i64(raw: i64, precision: u8) -> anyhow::Result<()> {
    if should_skip_validation(precision) {
        return Ok(());
    }

    let exp = usize::from(FIXED_PRECISION - precision);
    let scale = POWERS_OF_10[exp].cast_signed();
    let remainder = raw % scale;

    if remainder != 0 {
        return Err(invalid_raw_error(raw, precision, remainder, scale));
    }

    Ok(())
}

// -----------------------------------------------------------------------------
// Raw value correction functions
// -----------------------------------------------------------------------------
// These functions round raw values to the nearest valid multiple of the scale
// factor for a given precision. This is needed when reading data from catalogs
// or other sources that may have been created with floating-point precision
// errors (e.g., `int(value * FIXED_SCALAR)` instead of the correct
// `round(value * 10^precision) * scale` approach).

/// Rounds a raw `u128` value to the nearest valid multiple of the scale for the given precision.
///
/// This corrects raw values that have spurious bits beyond the precision scale, which can occur
/// from floating-point conversion errors during data creation.
///
/// Rounds half away from zero; when rounding away would overflow the integer range,
/// rounds toward zero instead.
#[must_use]
pub fn correct_raw_u128(raw: u128, precision: u8) -> u128 {
    if precision >= FIXED_PRECISION {
        return raw;
    }
    let exp = usize::from(FIXED_PRECISION - precision);
    let scale = u128::from(POWERS_OF_10[exp]);
    let half_scale = scale / 2;
    let remainder = raw % scale;
    if remainder == 0 {
        raw
    } else if remainder >= half_scale {
        raw.checked_add(scale - remainder)
            .unwrap_or(raw - remainder)
    } else {
        raw - remainder
    }
}

/// Rounds a raw `u64` value to the nearest valid multiple of the scale for the given precision.
///
/// This corrects raw values that have spurious bits beyond the precision scale, which can occur
/// from floating-point conversion errors during data creation.
///
/// Rounds half away from zero; when rounding away would overflow the integer range,
/// rounds toward zero instead.
#[must_use]
pub fn correct_raw_u64(raw: u64, precision: u8) -> u64 {
    if precision >= FIXED_PRECISION {
        return raw;
    }
    let exp = usize::from(FIXED_PRECISION - precision);
    let scale = POWERS_OF_10[exp];
    let half_scale = scale / 2;
    let remainder = raw % scale;
    if remainder == 0 {
        raw
    } else if remainder >= half_scale {
        raw.checked_add(scale - remainder)
            .unwrap_or(raw - remainder)
    } else {
        raw - remainder
    }
}

/// Rounds a raw `i128` value to the nearest valid multiple of the scale for the given precision.
///
/// This corrects raw values that have spurious bits beyond the precision scale, which can occur
/// from floating-point conversion errors during data creation.
///
/// Rounds half away from zero; when rounding away would overflow the integer range,
/// rounds toward zero instead.
#[must_use]
pub fn correct_raw_i128(raw: i128, precision: u8) -> i128 {
    if precision >= FIXED_PRECISION {
        return raw;
    }
    let exp = usize::from(FIXED_PRECISION - precision);
    let scale = i128::from(POWERS_OF_10[exp]);
    let half_scale = scale / 2;
    let remainder = raw % scale;
    if remainder == 0 {
        raw
    } else if raw >= 0 {
        if remainder >= half_scale {
            raw.checked_add(scale - remainder)
                .unwrap_or(raw - remainder)
        } else {
            raw - remainder
        }
    } else {
        // For negative values, remainder is negative
        if remainder.abs() >= half_scale {
            raw.checked_sub(scale + remainder)
                .unwrap_or(raw - remainder)
        } else {
            raw - remainder
        }
    }
}

/// Rounds a raw `i64` value to the nearest valid multiple of the scale for the given precision.
///
/// This corrects raw values that have spurious bits beyond the precision scale, which can occur
/// from floating-point conversion errors during data creation.
///
/// Rounds half away from zero; when rounding away would overflow the integer range,
/// rounds toward zero instead.
#[must_use]
pub fn correct_raw_i64(raw: i64, precision: u8) -> i64 {
    if precision >= FIXED_PRECISION {
        return raw;
    }
    let exp = usize::from(FIXED_PRECISION - precision);
    let scale = POWERS_OF_10[exp].cast_signed();
    let half_scale = scale / 2;
    let remainder = raw % scale;
    if remainder == 0 {
        raw
    } else if raw >= 0 {
        if remainder >= half_scale {
            raw.checked_add(scale - remainder)
                .unwrap_or(raw - remainder)
        } else {
            raw - remainder
        }
    } else {
        // For negative values, remainder is negative
        if remainder.abs() >= half_scale {
            raw.checked_sub(scale + remainder)
                .unwrap_or(raw - remainder)
        } else {
            raw - remainder
        }
    }
}

/// Rounds a raw price value to the nearest valid multiple of the scale for the given precision.
///
/// This is a type-aliased wrapper that calls the appropriate underlying function based on
/// whether the `high-precision` feature is enabled. Use this when working with `PriceRaw` values
/// to ensure consistent feature-flag handling.
#[must_use]
#[inline]
pub fn correct_price_raw(raw: PriceRaw, precision: u8) -> PriceRaw {
    #[cfg(feature = "high-precision")]
    {
        correct_raw_i128(raw, precision)
    }
    #[cfg(not(feature = "high-precision"))]
    {
        correct_raw_i64(raw, precision)
    }
}

/// Rounds a raw quantity value to the nearest valid multiple of the scale for the given precision.
///
/// This is a type-aliased wrapper that calls the appropriate underlying function based on
/// whether the `high-precision` feature is enabled. Use this when working with `QuantityRaw` values
/// to ensure consistent feature-flag handling.
#[must_use]
#[inline]
pub fn correct_quantity_raw(raw: QuantityRaw, precision: u8) -> QuantityRaw {
    #[cfg(feature = "high-precision")]
    {
        correct_raw_u128(raw, precision)
    }
    #[cfg(not(feature = "high-precision"))]
    {
        correct_raw_u64(raw, precision)
    }
}

/// Rounds a mantissa by removing `excess` decimal digits using banker's rounding (half to even).
///
/// Given a mantissa representing a number with `excess` extra decimal places beyond the desired
/// precision, divides by `10^excess` and rounds the result using round-half-to-even semantics.
#[must_use]
#[inline]
pub fn bankers_round(mantissa: i128, excess: u32) -> i128 {
    if excess == 0 {
        return mantissa;
    }

    // 10^39 overflows i128, and any i64-origin mantissa divided by 10^39+ is 0
    if excess >= 39 {
        return 0;
    }

    let divisor = 10i128.pow(excess);
    let quotient = mantissa / divisor;
    let remainder = mantissa % divisor;
    let half = divisor / 2;

    if remainder.abs() > half || (remainder.abs() == half && quotient % 2 != 0) {
        quotient + mantissa.signum()
    } else {
        quotient
    }
}

/// Converts a mantissa/exponent pair to a raw fixed-point `i128` value at the given precision.
///
/// The value is `mantissa * 10^exponent`. Uses pure integer arithmetic with banker's rounding
/// when fractional digits exceed `precision`. The result is scaled to [`FIXED_PRECISION`].
///
/// This is the shared core for `from_decimal`, `from_decimal_dp`, and `from_mantissa_exponent`
/// across Money, Price, and Quantity.
///
/// # Errors
///
/// Returns an error if:
/// - `precision` exceeds the maximum allowed by [`check_fixed_precision`].
/// - The scale factor exceeds `10^38` (i128 range).
/// - Overflow occurs during multiplication.
pub fn mantissa_exponent_to_fixed_i128(
    mantissa: i128,
    exponent: i8,
    precision: u8,
) -> CorrectnessResult<i128> {
    check_fixed_precision(precision)?;

    let precision_i16 = i16::from(precision);
    let target_scale = i16::from(FIXED_PRECISION).max(precision_i16);
    let frac_digits = -i16::from(exponent);

    let mantissa = if frac_digits > precision_i16 {
        let excess = u32::from((frac_digits - precision_i16).cast_unsigned());
        bankers_round(mantissa, excess)
    } else {
        mantissa
    };

    let scale_after_rounding = frac_digits.min(precision_i16);
    let scale_exp = target_scale - scale_after_rounding;
    if scale_exp > 38 {
        return Err(CorrectnessError::PredicateViolation {
            message: format!(
                "Exponent {exponent} produces scale factor 10^{scale_exp} which exceeds i128 range"
            ),
        });
    }

    if scale_exp >= 0 {
        mantissa.checked_mul(10i128.pow(u32::from(scale_exp.cast_unsigned())))
    } else {
        Some(mantissa / 10i128.pow(u32::from((-scale_exp).cast_unsigned())))
    }
    .ok_or_else(|| CorrectnessError::PredicateViolation {
        message: "Overflow when scaling mantissa to fixed precision".to_string(),
    })
}

pub(crate) fn mantissa_exponent_to_raw_checked<R>(
    mantissa: i128,
    exponent: i8,
    precision: u8,
    context: &'static str,
    raw_type_name: &'static str,
    value_type_name: &'static str,
) -> CorrectnessResult<R>
where
    R: TryFrom<i128>,
{
    check_fixed_precision(precision)?;

    let raw_i128 = if mantissa == 0 {
        0
    } else {
        mantissa_exponent_to_fixed_i128(mantissa, exponent, precision).map_err(|_| {
            CorrectnessError::PredicateViolation {
                message: format!(
                    "Overflow in {context} (mantissa={mantissa}, exponent={exponent}, precision={precision})"
                ),
            }
        })?
    };

    raw_i128
        .try_into()
        .map_err(|_| CorrectnessError::PredicateViolation {
            message: format!(
                "Raw value {raw_i128} exceeds {raw_type_name} range for {value_type_name}"
            ),
        })
}

/// Converts an `f64` value to a raw fixed-point `i64` representation with a specified precision.
///
/// # Precision and Rounding
///
/// This function performs IEEE 754 "round half to even" rounding at the specified precision
/// before scaling to the fixed-point representation. The rounding is intentionally applied
/// at the user-specified precision level to ensure values are correctly represented
/// without accumulating floating-point errors during scaling.
///
/// Callers are expected to validate that `value` is finite and within range; non-finite
/// values saturate at the integer bounds during the float-to-integer cast.
///
/// # Panics
///
/// Panics if `precision` exceeds [`FIXED_PRECISION`], or if scaling the rounded value
/// overflows the raw integer range.
#[must_use]
#[expect(
    clippy::cast_precision_loss,
    clippy::cast_possible_truncation,
    reason = "f64 to fixed-point conversion is inherently lossy; callers validate range and finiteness"
)]
pub fn f64_to_fixed_i64(value: f64, precision: u8) -> i64 {
    check_fixed_precision(precision).expect_display(FAILED);
    let pow1 = 10_i64.pow(u32::from(precision));
    let pow2 = 10_i64.pow(u32::from(FIXED_PRECISION - precision));
    let rounded = (value * pow1 as f64).round() as i64;
    rounded
        .checked_mul(pow2)
        .expect("Overflow when scaling f64 to fixed-point i64")
}

/// Converts an `f64` value to a raw fixed-point `i128` representation with a specified precision.
///
/// Callers are expected to validate that `value` is finite and within range; non-finite
/// values saturate at the integer bounds during the float-to-integer cast.
///
/// # Panics
///
/// Panics if `precision` exceeds [`FIXED_PRECISION`], or if scaling the rounded value
/// overflows the raw integer range.
#[must_use]
#[expect(
    clippy::cast_precision_loss,
    clippy::cast_possible_truncation,
    reason = "f64 to fixed-point conversion is inherently lossy; callers validate range and finiteness"
)]
pub fn f64_to_fixed_i128(value: f64, precision: u8) -> i128 {
    check_fixed_precision(precision).expect_display(FAILED);
    let pow1 = 10_i128.pow(u32::from(precision));
    let pow2 = 10_i128.pow(u32::from(FIXED_PRECISION - precision));
    let rounded = (value * pow1 as f64).round() as i128;
    rounded
        .checked_mul(pow2)
        .expect("Overflow when scaling f64 to fixed-point i128")
}

/// Converts an `f64` value to a raw fixed-point `u64` representation with a specified precision.
///
/// Callers are expected to validate that `value` is finite and non-negative; non-finite
/// and negative values saturate at the integer bounds during the float-to-integer cast.
///
/// # Panics
///
/// Panics if `precision` exceeds [`FIXED_PRECISION`], or if scaling the rounded value
/// overflows the raw integer range.
#[must_use]
#[expect(
    clippy::cast_precision_loss,
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss,
    reason = "f64 to fixed-point conversion is inherently lossy; callers validate range and finiteness"
)]
pub fn f64_to_fixed_u64(value: f64, precision: u8) -> u64 {
    check_fixed_precision(precision).expect_display(FAILED);
    let pow1 = 10_u64.pow(u32::from(precision));
    let pow2 = 10_u64.pow(u32::from(FIXED_PRECISION - precision));
    let rounded = (value * pow1 as f64).round() as u64;
    rounded
        .checked_mul(pow2)
        .expect("Overflow when scaling f64 to fixed-point u64")
}

/// Converts an `f64` value to a raw fixed-point `u128` representation with a specified precision.
///
/// Callers are expected to validate that `value` is finite and non-negative; non-finite
/// and negative values saturate at the integer bounds during the float-to-integer cast.
///
/// # Panics
///
/// Panics if `precision` exceeds [`FIXED_PRECISION`], or if scaling the rounded value
/// overflows the raw integer range.
#[must_use]
#[expect(
    clippy::cast_precision_loss,
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss,
    reason = "f64 to fixed-point conversion is inherently lossy; callers validate range and finiteness"
)]
pub fn f64_to_fixed_u128(value: f64, precision: u8) -> u128 {
    check_fixed_precision(precision).expect_display(FAILED);
    let pow1 = 10_u128.pow(u32::from(precision));
    let pow2 = 10_u128.pow(u32::from(FIXED_PRECISION - precision));
    let rounded = (value * pow1 as f64).round() as u128;
    rounded
        .checked_mul(pow2)
        .expect("Overflow when scaling f64 to fixed-point u128")
}

/// Converts a raw fixed-point `i64` value back to an `f64` value.
#[must_use]
#[expect(
    clippy::cast_precision_loss,
    reason = "i64 to f64 is inherently lossy above 2^53; accepted for float interop"
)]
pub fn fixed_i64_to_f64(value: i64) -> f64 {
    (value as f64) / FIXED_SCALAR
}

/// Converts a raw fixed-point `i128` value back to an `f64` value.
#[must_use]
#[expect(
    clippy::cast_precision_loss,
    reason = "i128 to f64 is inherently lossy above 2^53; accepted for float interop"
)]
pub fn fixed_i128_to_f64(value: i128) -> f64 {
    (value as f64) / FIXED_SCALAR
}

/// Converts a raw fixed-point `u64` value back to an `f64` value.
#[must_use]
#[expect(
    clippy::cast_precision_loss,
    reason = "u64 to f64 is inherently lossy above 2^53; accepted for float interop"
)]
pub fn fixed_u64_to_f64(value: u64) -> f64 {
    (value as f64) / FIXED_SCALAR
}

/// Converts a raw fixed-point `u128` value back to an `f64` value.
#[must_use]
#[expect(
    clippy::cast_precision_loss,
    reason = "u128 to f64 is inherently lossy above 2^53; accepted for float interop"
)]
pub fn fixed_u128_to_f64(value: u128) -> f64 {
    (value as f64) / FIXED_SCALAR
}

#[cfg(feature = "high-precision")]
#[cfg(test)]
mod tests {
    use nautilus_core::approx_eq;
    use rstest::rstest;

    use super::*;

    #[cfg(not(feature = "defi"))]
    #[rstest]
    fn test_precision_boundaries() {
        assert!(check_fixed_precision(0).is_ok());
        assert!(check_fixed_precision(FIXED_PRECISION).is_ok());
        assert!(check_fixed_precision(FIXED_PRECISION + 1).is_err());
    }

    #[cfg(feature = "defi")]
    #[rstest]
    fn test_precision_boundaries() {
        use crate::defi::WEI_PRECISION;

        assert!(check_fixed_precision(0).is_ok());
        assert!(check_fixed_precision(WEI_PRECISION).is_ok());
        assert!(check_fixed_precision(WEI_PRECISION + 1).is_err());
    }

    #[rstest]
    #[case(0.0)]
    #[case(1.0)]
    #[case(-1.0)]
    fn test_basic_roundtrip(#[case] value: f64) {
        for precision in 0..=FIXED_PRECISION {
            let fixed = f64_to_fixed_i128(value, precision);
            let result = fixed_i128_to_f64(fixed);
            assert!(approx_eq!(f64, value, result, epsilon = 0.001));
        }
    }

    #[rstest]
    #[case(1_000_000.0)]
    #[case(-1_000_000.0)]
    fn test_large_value_roundtrip(#[case] value: f64) {
        for precision in 0..=FIXED_PRECISION {
            let fixed = f64_to_fixed_i128(value, precision);
            let result = fixed_i128_to_f64(fixed);
            assert!(approx_eq!(f64, value, result, epsilon = 0.000_1));
        }
    }

    #[rstest]
    #[case(0, 123_456.0)]
    #[case(0, 123_456.7)]
    #[case(1, 123_456.7)]
    #[case(2, 123_456.78)]
    #[case(8, 123_456.123_456_78)]
    fn test_precision_specific_values_basic(#[case] precision: u8, #[case] value: f64) {
        let result = f64_to_fixed_i128(value, precision);
        let back_converted = fixed_i128_to_f64(result);
        // Round-trip should preserve the value up to the specified precision
        let scale = 10.0_f64.powi(i32::from(precision));
        let expected_rounded = (value * scale).round() / scale;
        assert!((back_converted - expected_rounded).abs() < 1e-10);
    }

    #[rstest]
    fn test_max_precision_values() {
        // Test with maximum precision that the current feature set supports
        let test_value = 123_456.123_456_789;
        let result = f64_to_fixed_i128(test_value, FIXED_PRECISION);
        let back_converted = fixed_i128_to_f64(result);
        // For maximum precision, we expect some floating-point limitations
        assert!((back_converted - test_value).abs() < 1e-6);
    }

    #[rstest]
    #[case(0.0)]
    #[case(1.0)]
    #[case(1_000_000.0)]
    fn test_unsigned_basic_roundtrip(#[case] value: f64) {
        for precision in 0..=FIXED_PRECISION {
            let fixed = f64_to_fixed_u128(value, precision);
            let result = fixed_u128_to_f64(fixed);
            assert!(approx_eq!(f64, value, result, epsilon = 0.001));
        }
    }

    #[rstest]
    #[case(0)]
    #[case(FIXED_PRECISION)]
    fn test_valid_precision(#[case] precision: u8) {
        let result = check_fixed_precision(precision);
        assert!(result.is_ok());
    }

    #[cfg(not(feature = "defi"))]
    #[rstest]
    fn test_invalid_precision() {
        let precision = FIXED_PRECISION + 1;
        let result = check_fixed_precision(precision);
        assert!(result.is_err());
    }

    #[cfg(feature = "defi")]
    #[rstest]
    fn test_invalid_precision() {
        use crate::defi::WEI_PRECISION;
        let precision = WEI_PRECISION + 1;
        let result = check_fixed_precision(precision);
        assert!(result.is_err());
    }

    #[cfg(not(feature = "defi"))]
    #[rstest]
    fn test_check_fixed_precision_returns_typed_error_with_stable_display() {
        let error = check_fixed_precision(FIXED_PRECISION + 1).unwrap_err();

        assert_eq!(
            error,
            CorrectnessError::PredicateViolation {
                message: format!(
                    "`precision` exceeded maximum `FIXED_PRECISION` ({FIXED_PRECISION}), was {}",
                    FIXED_PRECISION + 1
                ),
            }
        );
        assert_eq!(
            error.to_string(),
            format!(
                "`precision` exceeded maximum `FIXED_PRECISION` ({FIXED_PRECISION}), was {}",
                FIXED_PRECISION + 1
            )
        );
    }

    #[cfg(feature = "defi")]
    #[rstest]
    fn test_check_fixed_precision_returns_typed_error_with_stable_display() {
        use crate::defi::WEI_PRECISION;

        let error = check_fixed_precision(WEI_PRECISION + 1).unwrap_err();

        assert_eq!(
            error,
            CorrectnessError::PredicateViolation {
                message: format!(
                    "`precision` exceeded maximum `WEI_PRECISION` (18), was {}",
                    WEI_PRECISION + 1
                ),
            }
        );
        assert_eq!(
            error.to_string(),
            format!(
                "`precision` exceeded maximum `WEI_PRECISION` (18), was {}",
                WEI_PRECISION + 1
            )
        );
    }

    #[rstest]
    #[case(0, 0.0)]
    #[case(1, 1.0)]
    #[case(1, 1.1)]
    #[case(9, 0.000_000_001)]
    #[case(16, 0.000_000_000_000_000_1)]
    #[case(0, -0.0)]
    #[case(1, -1.0)]
    #[case(1, -1.1)]
    #[case(9, -0.000_000_001)]
    #[case(16, -0.000_000_000_000_000_1)]
    fn test_f64_to_fixed_i128_to_fixed(#[case] precision: u8, #[case] value: f64) {
        let fixed = f64_to_fixed_i128(value, precision);
        let result = fixed_i128_to_f64(fixed);
        assert_eq!(result, value);
    }

    #[rstest]
    #[case(0, 0.0)]
    #[case(1, 1.0)]
    #[case(1, 1.1)]
    #[case(9, 0.000_000_001)]
    #[case(16, 0.000_000_000_000_000_1)]
    fn test_f64_to_fixed_u128_to_fixed(#[case] precision: u8, #[case] value: f64) {
        let fixed = f64_to_fixed_u128(value, precision);
        let result = fixed_u128_to_f64(fixed);
        assert_eq!(result, value);
    }

    #[rstest]
    #[case(0, 123_456.0)]
    #[case(0, 123_456.7)]
    #[case(0, 123_456.4)]
    #[case(1, 123_456.0)]
    #[case(1, 123_456.7)]
    #[case(1, 123_456.4)]
    #[case(2, 123_456.0)]
    #[case(2, 123_456.7)]
    #[case(2, 123_456.4)]
    fn test_f64_to_fixed_i128_with_precision(#[case] precision: u8, #[case] value: f64) {
        let result = f64_to_fixed_i128(value, precision);

        // Calculate expected value dynamically based on current FIXED_PRECISION
        let pow1 = 10_i128.pow(u32::from(precision));
        let pow2 = 10_i128.pow(u32::from(FIXED_PRECISION - precision));
        let rounded = (value * pow1 as f64).round() as i128;
        let expected = rounded * pow2;

        assert_eq!(
            result, expected,
            "Failed for precision {precision}, value {value}: got {result}, expected {expected}"
        );
    }

    #[rstest]
    #[case(0, 5.555_555_555_555_555)]
    #[case(1, 5.555_555_555_555_555)]
    #[case(2, 5.555_555_555_555_555)]
    #[case(3, 5.555_555_555_555_555)]
    #[case(4, 5.555_555_555_555_555)]
    #[case(5, 5.555_555_555_555_555)]
    #[case(6, 5.555_555_555_555_555)]
    #[case(7, 5.555_555_555_555_555)]
    #[case(8, 5.555_555_555_555_555)]
    #[case(9, 5.555_555_555_555_555)]
    #[case(10, 5.555_555_555_555_555)]
    #[case(11, 5.555_555_555_555_555)]
    #[case(12, 5.555_555_555_555_555)]
    #[case(13, 5.555_555_555_555_555)]
    #[case(14, 5.555_555_555_555_555)]
    #[case(15, 5.555_555_555_555_555)]
    #[case(0, -5.555_555_555_555_555)]
    #[case(1, -5.555_555_555_555_555)]
    #[case(2, -5.555_555_555_555_555)]
    #[case(3, -5.555_555_555_555_555)]
    #[case(4, -5.555_555_555_555_555)]
    #[case(5, -5.555_555_555_555_555)]
    #[case(6, -5.555_555_555_555_555)]
    #[case(7, -5.555_555_555_555_555)]
    #[case(8, -5.555_555_555_555_555)]
    #[case(9, -5.555_555_555_555_555)]
    #[case(10, -5.555_555_555_555_555)]
    #[case(11, -5.555_555_555_555_555)]
    #[case(12, -5.555_555_555_555_555)]
    #[case(13, -5.555_555_555_555_555)]
    #[case(14, -5.555_555_555_555_555)]
    #[case(15, -5.555_555_555_555_555)]
    fn test_f64_to_fixed_i128(#[case] precision: u8, #[case] value: f64) {
        // Only test up to the current FIXED_PRECISION
        if precision > FIXED_PRECISION {
            return;
        }

        let result = f64_to_fixed_i128(value, precision);

        // Calculate expected value dynamically based on current FIXED_PRECISION
        let pow1 = 10_i128.pow(u32::from(precision));
        let pow2 = 10_i128.pow(u32::from(FIXED_PRECISION - precision));
        let rounded = (value * pow1 as f64).round() as i128;
        let expected = rounded * pow2;

        assert_eq!(
            result, expected,
            "Failed for precision {precision}, value {value}: got {result}, expected {expected}"
        );
    }

    #[rstest]
    #[case(0, 5.555_555_555_555_555)]
    #[case(1, 5.555_555_555_555_555)]
    #[case(2, 5.555_555_555_555_555)]
    #[case(3, 5.555_555_555_555_555)]
    #[case(4, 5.555_555_555_555_555)]
    #[case(5, 5.555_555_555_555_555)]
    #[case(6, 5.555_555_555_555_555)]
    #[case(7, 5.555_555_555_555_555)]
    #[case(8, 5.555_555_555_555_555)]
    #[case(9, 5.555_555_555_555_555)]
    #[case(10, 5.555_555_555_555_555)]
    #[case(11, 5.555_555_555_555_555)]
    #[case(12, 5.555_555_555_555_555)]
    #[case(13, 5.555_555_555_555_555)]
    #[case(14, 5.555_555_555_555_555)]
    #[case(15, 5.555_555_555_555_555)]
    #[case(16, 5.555_555_555_555_555)]
    fn test_f64_to_fixed_u64(#[case] precision: u8, #[case] value: f64) {
        // Only test up to the current FIXED_PRECISION
        if precision > FIXED_PRECISION {
            return;
        }

        let result = f64_to_fixed_u128(value, precision);

        // Calculate expected value dynamically based on current FIXED_PRECISION
        let pow1 = 10_u128.pow(u32::from(precision));
        let pow2 = 10_u128.pow(u32::from(FIXED_PRECISION - precision));
        let rounded = (value * pow1 as f64).round() as u128;
        let expected = rounded * pow2;

        assert_eq!(
            result, expected,
            "Failed for precision {precision}, value {value}: got {result}, expected {expected}"
        );
    }

    #[rstest]
    fn test_fixed_i128_to_f64(
        #[values(1, -1, 2, -2, 10, -10, 100, -100, 1_000, -1_000, -10_000, -100_000)] value: i128,
    ) {
        assert_eq!(fixed_i128_to_f64(value), value as f64 / FIXED_SCALAR);
    }

    #[rstest]
    fn test_fixed_u128_to_f64(
        #[values(
            0,
            1,
            2,
            3,
            10,
            100,
            1_000,
            10_000,
            100_000,
            1_000_000,
            10_000_000,
            100_000_000,
            1_000_000_000,
            10_000_000_000,
            100_000_000_000,
            1_000_000_000_000,
            10_000_000_000_000,
            100_000_000_000_000,
            1_000_000_000_000_000,
            10_000_000_000_000_000,
            100_000_000_000_000_000,
            1_000_000_000_000_000_000,
            10_000_000_000_000_000_000,
            100_000_000_000_000_000_000
        )]
        value: u128,
    ) {
        let result = fixed_u128_to_f64(value);
        assert_eq!(result, (value as f64) / FIXED_SCALAR);
    }

    // -------------------------------------------------------------------------
    // Raw value validation tests (high-precision: FIXED_PRECISION = 16)
    // -------------------------------------------------------------------------

    #[rstest]
    #[case(0, 0)] // Zero is always valid
    #[case(0, 10_000_000_000_000_000)] // 1 * 10^16 at precision 0
    #[case(0, 1_200_000_000_000_000_000)] // 120 * 10^16 at precision 0
    #[case(8, 12_345_678_900_000_000)] // 123456789 * 10^8 at precision 8
    #[case(15, 1_234_567_890_123_450)] // Multiple of 10 at precision 15
    fn test_check_fixed_raw_u128_valid(#[case] precision: u8, #[case] raw: u128) {
        assert!(check_fixed_raw_u128(raw, precision).is_ok());
    }

    #[rstest]
    #[case(0, 1)] // Not multiple of 10^16
    #[case(0, 9_999_999_999_999_999)] // One less than scale
    #[case(0, 10_000_000_000_000_001)] // One more than 10^16
    #[case(8, 12_345_678_900_000_001)] // Not multiple of 10^8
    #[case(15, 1_234_567_890_123_451)] // Not multiple of 10
    fn test_check_fixed_raw_u128_invalid(#[case] precision: u8, #[case] raw: u128) {
        assert!(check_fixed_raw_u128(raw, precision).is_err());
    }

    #[rstest]
    fn test_check_fixed_raw_u128_at_max_precision() {
        // At FIXED_PRECISION (16), validation is skipped
        assert!(check_fixed_raw_u128(0, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_u128(1, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_u128(123_456_789, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_u128(u128::MAX, FIXED_PRECISION).is_ok());
    }

    #[rstest]
    #[case(0, 0)]
    #[case(0, 10_000_000_000_000_000)]
    #[case(0, -10_000_000_000_000_000)]
    #[case(8, 12_345_678_900_000_000)]
    #[case(8, -12_345_678_900_000_000)]
    fn test_check_fixed_raw_i128_valid(#[case] precision: u8, #[case] raw: i128) {
        assert!(check_fixed_raw_i128(raw, precision).is_ok());
    }

    #[rstest]
    #[case(0, 1)]
    #[case(0, -1)]
    #[case(0, 9_999_999_999_999_999)]
    #[case(0, -9_999_999_999_999_999)]
    fn test_check_fixed_raw_i128_invalid(#[case] precision: u8, #[case] raw: i128) {
        assert!(check_fixed_raw_i128(raw, precision).is_err());
    }

    #[rstest]
    fn test_check_fixed_raw_i128_at_max_precision() {
        assert!(check_fixed_raw_i128(0, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_i128(1, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_i128(-1, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_i128(i128::MAX, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_i128(i128::MIN, FIXED_PRECISION).is_ok());
    }

    #[rstest]
    #[should_panic(expected = "Overflow when scaling f64 to fixed-point i128")]
    fn test_f64_to_fixed_i128_overflow_panics() {
        let _ = f64_to_fixed_i128(1e30, 0);
    }

    #[rstest]
    #[should_panic(expected = "Overflow when scaling f64 to fixed-point u128")]
    fn test_f64_to_fixed_u128_overflow_panics() {
        let _ = f64_to_fixed_u128(1e30, 0);
    }
}

#[cfg(not(feature = "high-precision"))]
#[cfg(test)]
mod tests {
    use nautilus_core::approx_eq;
    use rstest::rstest;

    use super::*;

    #[rstest]
    fn test_precision_boundaries() {
        assert!(check_fixed_precision(0).is_ok());
        assert!(check_fixed_precision(FIXED_PRECISION).is_ok());
        assert!(check_fixed_precision(FIXED_PRECISION + 1).is_err());
    }

    #[rstest]
    #[case(0.0)]
    #[case(1.0)]
    #[case(-1.0)]
    fn test_basic_roundtrip(#[case] value: f64) {
        for precision in 0..=FIXED_PRECISION {
            let fixed = f64_to_fixed_i64(value, precision);
            let result = fixed_i64_to_f64(fixed);
            assert!(approx_eq!(f64, value, result, epsilon = 0.001));
        }
    }

    #[rstest]
    #[case(1000000.0)]
    #[case(-1000000.0)]
    fn test_large_value_roundtrip(#[case] value: f64) {
        for precision in 0..=FIXED_PRECISION {
            let fixed = f64_to_fixed_i64(value, precision);
            let result = fixed_i64_to_f64(fixed);
            assert!(approx_eq!(f64, value, result, epsilon = 0.000_1));
        }
    }

    #[rstest]
    #[case(0, 123456.0, 123_456_000_000_000)]
    #[case(0, 123456.7, 123_457_000_000_000)]
    #[case(1, 123456.7, 123_456_700_000_000)]
    #[case(2, 123456.78, 123_456_780_000_000)]
    #[case(8, 123456.123_456_78, 123_456_123_456_780)]
    #[case(9, 123456.123_456_789, 123_456_123_456_789)]
    fn test_precision_specific_values(
        #[case] precision: u8,
        #[case] value: f64,
        #[case] expected: i64,
    ) {
        assert_eq!(f64_to_fixed_i64(value, precision), expected);
    }

    #[rstest]
    #[case(0.0)]
    #[case(1.0)]
    #[case(1000000.0)]
    fn test_unsigned_basic_roundtrip(#[case] value: f64) {
        for precision in 0..=FIXED_PRECISION {
            let fixed = f64_to_fixed_u64(value, precision);
            let result = fixed_u64_to_f64(fixed);
            assert!(approx_eq!(f64, value, result, epsilon = 0.001));
        }
    }

    #[rstest]
    #[case(0, 1.4, 1.0)]
    #[case(0, 1.5, 2.0)]
    #[case(0, 1.6, 2.0)]
    #[case(1, 1.44, 1.4)]
    #[case(1, 1.45, 1.5)]
    #[case(1, 1.46, 1.5)]
    #[case(2, 1.444, 1.44)]
    #[case(2, 1.445, 1.45)]
    #[case(2, 1.446, 1.45)]
    fn test_rounding(#[case] precision: u8, #[case] input: f64, #[case] expected: f64) {
        let fixed = f64_to_fixed_i128(input, precision);
        assert!(approx_eq!(
            f64,
            fixed_i128_to_f64(fixed),
            expected,
            epsilon = 0.000_000_001
        ));
    }

    #[rstest]
    fn test_special_values() {
        // Zero handling
        assert_eq!(f64_to_fixed_i128(0.0, FIXED_PRECISION), 0);
        assert_eq!(f64_to_fixed_i128(-0.0, FIXED_PRECISION), 0);

        // Small values
        let smallest_positive = 1.0 / FIXED_SCALAR;
        let fixed_smallest = f64_to_fixed_i128(smallest_positive, FIXED_PRECISION);
        assert_eq!(fixed_smallest, 1);

        // Large integers
        let large_int = 1_000_000_000.0;
        let fixed_large = f64_to_fixed_i128(large_int, 0);
        assert_eq!(fixed_i128_to_f64(fixed_large), large_int);
    }

    #[rstest]
    #[case(0)]
    #[case(FIXED_PRECISION)]
    fn test_valid_precision(#[case] precision: u8) {
        let result = check_fixed_precision(precision);
        assert!(result.is_ok());
    }

    #[rstest]
    fn test_invalid_precision() {
        let precision = FIXED_PRECISION + 1;
        let result = check_fixed_precision(precision);
        assert!(result.is_err());
    }

    #[rstest]
    #[case(0, 0.0)]
    #[case(1, 1.0)]
    #[case(1, 1.1)]
    #[case(9, 0.000_000_001)]
    #[case(0, -0.0)]
    #[case(1, -1.0)]
    #[case(1, -1.1)]
    #[case(9, -0.000_000_001)]
    fn test_f64_to_fixed_i64_to_fixed(#[case] precision: u8, #[case] value: f64) {
        let fixed = f64_to_fixed_i64(value, precision);
        let result = fixed_i64_to_f64(fixed);
        assert_eq!(result, value);
    }

    #[rstest]
    #[case(0, 0.0)]
    #[case(1, 1.0)]
    #[case(1, 1.1)]
    #[case(9, 0.000_000_001)]
    fn test_f64_to_fixed_u64_to_fixed(#[case] precision: u8, #[case] value: f64) {
        let fixed = f64_to_fixed_u64(value, precision);
        let result = fixed_u64_to_f64(fixed);
        assert_eq!(result, value);
    }

    #[rstest]
    #[case(0, 123456.0, 123_456_000_000_000)]
    #[case(0, 123456.7, 123_457_000_000_000)]
    #[case(0, 123_456.4, 123_456_000_000_000)]
    #[case(1, 123456.0, 123_456_000_000_000)]
    #[case(1, 123456.7, 123_456_700_000_000)]
    #[case(1, 123_456.4, 123_456_400_000_000)]
    #[case(2, 123456.0, 123_456_000_000_000)]
    #[case(2, 123456.7, 123_456_700_000_000)]
    #[case(2, 123_456.4, 123_456_400_000_000)]
    fn test_f64_to_fixed_i64_with_precision(
        #[case] precision: u8,
        #[case] value: f64,
        #[case] expected: i64,
    ) {
        assert_eq!(f64_to_fixed_i64(value, precision), expected);
    }

    #[rstest]
    #[case(0, 5.5, 6_000_000_000)]
    #[case(1, 5.55, 5_600_000_000)]
    #[case(2, 5.555, 5_560_000_000)]
    #[case(3, 5.5555, 5_556_000_000)]
    #[case(4, 5.55555, 5_555_600_000)]
    #[case(5, 5.555_555, 5_555_560_000)]
    #[case(6, 5.555_555_5, 5_555_556_000)]
    #[case(7, 5.555_555_55, 5_555_555_600)]
    #[case(8, 5.555_555_555, 5_555_555_560)]
    #[case(9, 5.555_555_555_5, 5_555_555_556)]
    #[case(0, -5.5, -6_000_000_000)]
    #[case(1, -5.55, -5_600_000_000)]
    #[case(2, -5.555, -5_560_000_000)]
    #[case(3, -5.5555, -5_556_000_000)]
    #[case(4, -5.55555, -5_555_600_000)]
    #[case(5, -5.555_555, -5_555_560_000)]
    #[case(6, -5.555_555_5, -5_555_556_000)]
    #[case(7, -5.555_555_55, -5_555_555_600)]
    #[case(8, -5.555_555_555, -5_555_555_560)]
    #[case(9, -5.555_555_555_5, -5_555_555_556)]
    fn test_f64_to_fixed_i64(#[case] precision: u8, #[case] value: f64, #[case] expected: i64) {
        assert_eq!(f64_to_fixed_i64(value, precision), expected);
    }

    #[rstest]
    #[case(0, 5.5, 6_000_000_000)]
    #[case(1, 5.55, 5_600_000_000)]
    #[case(2, 5.555, 5_560_000_000)]
    #[case(3, 5.5555, 5_556_000_000)]
    #[case(4, 5.55555, 5_555_600_000)]
    #[case(5, 5.555_555, 5_555_560_000)]
    #[case(6, 5.555_555_5, 5_555_556_000)]
    #[case(7, 5.555_555_55, 5_555_555_600)]
    #[case(8, 5.555_555_555, 5_555_555_560)]
    #[case(9, 5.555_555_555_5, 5_555_555_556)]
    fn test_f64_to_fixed_u64(#[case] precision: u8, #[case] value: f64, #[case] expected: u64) {
        assert_eq!(f64_to_fixed_u64(value, precision), expected);
    }

    #[rstest]
    fn test_fixed_i64_to_f64(
        #[values(1, -1, 2, -2, 10, -10, 100, -100, 1_000, -1_000)] value: i64,
    ) {
        assert_eq!(fixed_i64_to_f64(value), value as f64 / FIXED_SCALAR);
    }

    #[rstest]
    fn test_fixed_u64_to_f64(
        #[values(
            0,
            1,
            2,
            3,
            10,
            100,
            1_000,
            10_000,
            100_000,
            1_000_000,
            10_000_000,
            100_000_000,
            1_000_000_000,
            10_000_000_000,
            100_000_000_000,
            1_000_000_000_000,
            10_000_000_000_000,
            100_000_000_000_000,
            1_000_000_000_000_000
        )]
        value: u64,
    ) {
        let result = fixed_u64_to_f64(value);
        assert_eq!(result, (value as f64) / FIXED_SCALAR);
    }

    #[rstest]
    #[case(0, 0)] // Zero is always valid
    #[case(0, 1_000_000_000)] // 1 * 10^9 at precision 0
    #[case(0, 120_000_000_000)] // 120 * 10^9 at precision 0
    #[case(2, 123_450_000_000)] // 12345 * 10^7 at precision 2
    #[case(8, 1_234_567_890)] // 123456789 * 10 at precision 8
    fn test_check_fixed_raw_u64_valid(#[case] precision: u8, #[case] raw: u64) {
        assert!(check_fixed_raw_u64(raw, precision).is_ok());
    }

    #[rstest]
    #[case(0, 1)] // Not multiple of 10^9
    #[case(0, 999_999_999)] // One less than scale
    #[case(0, 1_000_000_001)] // One more than 10^9
    #[case(0, 119_582_001_968_421_736)] // The original bug case
    #[case(2, 123_456_789_000)] // Not multiple of 10^7
    #[case(8, 1_234_567_891)] // Not multiple of 10
    fn test_check_fixed_raw_u64_invalid(#[case] precision: u8, #[case] raw: u64) {
        assert!(check_fixed_raw_u64(raw, precision).is_err());
    }

    #[rstest]
    fn test_check_fixed_raw_u64_at_max_precision() {
        // At FIXED_PRECISION, validation is skipped - any value is valid
        assert!(check_fixed_raw_u64(0, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_u64(1, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_u64(123_456_789, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_u64(u64::MAX, FIXED_PRECISION).is_ok());
    }

    #[rstest]
    #[case(0, 0)]
    #[case(0, 1_000_000_000)]
    #[case(0, -1_000_000_000)]
    #[case(2, 123_450_000_000)]
    #[case(2, -123_450_000_000)]
    fn test_check_fixed_raw_i64_valid(#[case] precision: u8, #[case] raw: i64) {
        assert!(check_fixed_raw_i64(raw, precision).is_ok());
    }

    #[rstest]
    #[case(0, 1)]
    #[case(0, -1)]
    #[case(0, 999_999_999)]
    #[case(0, -999_999_999)]
    fn test_check_fixed_raw_i64_invalid(#[case] precision: u8, #[case] raw: i64) {
        assert!(check_fixed_raw_i64(raw, precision).is_err());
    }

    #[rstest]
    fn test_check_fixed_raw_i64_at_max_precision() {
        assert!(check_fixed_raw_i64(0, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_i64(1, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_i64(-1, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_i64(i64::MAX, FIXED_PRECISION).is_ok());
        assert!(check_fixed_raw_i64(i64::MIN, FIXED_PRECISION).is_ok());
    }

    #[rstest]
    #[should_panic(expected = "Overflow when scaling f64 to fixed-point i64")]
    fn test_f64_to_fixed_i64_overflow_panics() {
        let _ = f64_to_fixed_i64(2e18, 0);
    }

    #[rstest]
    #[should_panic(expected = "Overflow when scaling f64 to fixed-point u64")]
    fn test_f64_to_fixed_u64_overflow_panics() {
        let _ = f64_to_fixed_u64(2e19, 0);
    }
}

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

    use rstest::rstest;
    use rust_decimal::{Decimal, RoundingStrategy};

    use super::*;

    #[rstest]
    // Excess=0: no rounding, identity
    #[case(0, 0, 0)]
    #[case(1, 0, 1)]
    #[case(5, 0, 5)]
    #[case(99, 0, 99)]
    #[case(-7, 0, -7)]
    // Excess >= 39: overflow guard returns 0
    #[case(12345, 39, 0)]
    #[case(i128::from(i64::MAX), 100, 0)]
    #[case(-99999, 50, 0)]
    // Excess=1: halfway cases (remainder == 5, half of 10)
    #[case(15, 1, 2)] // 1.5 -> 2 (round up to even)
    #[case(25, 1, 2)] // 2.5 -> 2 (round down to even)
    #[case(35, 1, 4)] // 3.5 -> 4 (round up to even)
    #[case(45, 1, 4)] // 4.5 -> 4 (round down to even)
    #[case(55, 1, 6)] // 5.5 -> 6 (round up to even)
    #[case(65, 1, 6)] // 6.5 -> 6 (round down to even)
    #[case(75, 1, 8)] // 7.5 -> 8 (round up to even)
    #[case(85, 1, 8)] // 8.5 -> 8 (round down to even)
    #[case(95, 1, 10)] // 9.5 -> 10 (round up to even)
    #[case(105, 1, 10)] // 10.5 -> 10 (round down to even)
    // Excess=1: non-halfway cases
    #[case(14, 1, 1)] // 1.4 -> 1 (truncate)
    #[case(16, 1, 2)] // 1.6 -> 2 (round up)
    #[case(24, 1, 2)] // 2.4 -> 2 (truncate)
    #[case(26, 1, 3)] // 2.6 -> 3 (round up)
    #[case(11, 1, 1)] // 1.1 -> 1 (truncate)
    #[case(19, 1, 2)] // 1.9 -> 2 (round up)
    // Excess=2: halfway cases (remainder == 50, half of 100)
    #[case(150, 2, 2)] // 1.50 -> 2 (round up to even)
    #[case(250, 2, 2)] // 2.50 -> 2 (round down to even)
    #[case(350, 2, 4)] // 3.50 -> 4 (round up to even)
    #[case(450, 2, 4)] // 4.50 -> 4 (round down to even)
    #[case(550, 2, 6)] // 5.50 -> 6 (round up to even)
    #[case(1050, 2, 10)] // 10.50 -> 10 (round down to even)
    #[case(1150, 2, 12)] // 11.50 -> 12 (round up to even)
    // Excess=2: non-halfway cases
    #[case(149, 2, 1)] // 1.49 -> 1 (truncate)
    #[case(151, 2, 2)] // 1.51 -> 2 (round up)
    #[case(199, 2, 2)] // 1.99 -> 2 (round up)
    #[case(101, 2, 1)] // 1.01 -> 1 (truncate)
    // Excess=3: halfway cases (remainder == 500, half of 1000)
    #[case(1500, 3, 2)] // 1.500 -> 2 (round up to even)
    #[case(2500, 3, 2)] // 2.500 -> 2 (round down to even)
    #[case(3500, 3, 4)] // 3.500 -> 4 (round up to even)
    #[case(10500, 3, 10)] // 10.500 -> 10 (round down to even)
    #[case(11500, 3, 12)] // 11.500 -> 12 (round up to even)
    // Excess=3: non-halfway cases
    #[case(1499, 3, 1)] // 1.499 -> 1 (truncate)
    #[case(1501, 3, 2)] // 1.501 -> 2 (round up)
    // Negative halfway cases
    #[case(-15, 1, -2)] // -1.5 -> -2 (round away from zero to even)
    #[case(-25, 1, -2)] // -2.5 -> -2 (round toward zero to even)
    #[case(-35, 1, -4)] // -3.5 -> -4 (round away from zero to even)
    #[case(-45, 1, -4)] // -4.5 -> -4 (round toward zero to even)
    #[case(-55, 1, -6)] // -5.5 -> -6 (round away from zero to even)
    #[case(-65, 1, -6)] // -6.5 -> -6 (round toward zero to even)
    #[case(-150, 2, -2)] // -1.50 -> -2 (round away from zero to even)
    #[case(-250, 2, -2)] // -2.50 -> -2 (round toward zero to even)
    #[case(-350, 2, -4)] // -3.50 -> -4 (round away from zero to even)
    // Negative non-halfway cases
    #[case(-14, 1, -1)] // -1.4 -> -1 (truncate toward zero)
    #[case(-16, 1, -2)] // -1.6 -> -2 (round away from zero)
    #[case(-24, 1, -2)] // -2.4 -> -2 (truncate toward zero)
    #[case(-26, 1, -3)] // -2.6 -> -3 (round away from zero)
    // Zero mantissa
    #[case(0, 1, 0)]
    #[case(0, 2, 0)]
    #[case(0, 5, 0)]
    // Large excess values
    #[case(123_456_789, 3, 123_457)] // 123456.789 -> 123457
    #[case(123_456_500, 3, 123_456)] // 123456.500 -> 123456 (half, even quotient)
    #[case(123_457_500, 3, 123_458)] // 123457.500 -> 123458 (half, odd quotient)
    #[case(100_005, 1, 10_000)] // 10000.5 -> 10000 (half, even quotient)
    #[case(100_015, 1, 10_002)] // 10001.5 -> 10002 (half, odd quotient)
    // Large mantissa values
    #[case(999_999_999_999_999_995, 1, 100_000_000_000_000_000)]
    #[case(1_000_000_000_000_000_005, 1, 100_000_000_000_000_000)]
    fn test_bankers_round(#[case] mantissa: i128, #[case] excess: u32, #[case] expected: i128) {
        assert_eq!(
            bankers_round(mantissa, excess),
            expected,
            "bankers_round({mantissa}, {excess}) expected {expected}"
        );
    }

    // Symmetry: bankers_round(-x, e) == -bankers_round(x, e) for all positive x
    #[rstest]
    #[case(15, 1)]
    #[case(25, 1)]
    #[case(35, 1)]
    #[case(150, 2)]
    #[case(250, 2)]
    #[case(1500, 3)]
    #[case(2500, 3)]
    #[case(123_456_789, 3)]
    #[case(14, 1)]
    #[case(16, 1)]
    fn test_bankers_round_negative_symmetry(#[case] mantissa: i128, #[case] excess: u32) {
        assert_eq!(
            bankers_round(-mantissa, excess),
            -bankers_round(mantissa, excess),
            "Negative symmetry failed for mantissa={mantissa}, excess={excess}"
        );
    }

    // Verify consistency with Rust Decimal's banker's rounding
    #[rstest]
    #[case("1.005", 2, "1.00")] // 0.005 remainder, even quotient -> truncate
    #[case("1.015", 2, "1.02")] // 0.005 remainder, odd quotient -> round up
    #[case("1.025", 2, "1.02")] // 0.005 remainder, even quotient -> truncate
    #[case("1.035", 2, "1.04")] // 0.005 remainder, odd quotient -> round up
    #[case("1.045", 2, "1.04")] // 0.005 remainder, even quotient -> truncate
    #[case("2.5", 0, "2")] // 0.5 remainder, even quotient -> truncate
    #[case("3.5", 0, "4")] // 0.5 remainder, odd quotient -> round up
    #[case("-2.5", 0, "-2")]
    #[case("-3.5", 0, "-4")]
    #[case("123.456", 2, "123.46")]
    #[case("123.455", 2, "123.46")] // Odd quotient at half
    #[case("123.445", 2, "123.44")] // Even quotient at half
    fn test_bankers_round_matches_decimal(
        #[case] input: &str,
        #[case] target_precision: u8,
        #[case] expected: &str,
    ) {
        let dec = Decimal::from_str(input).unwrap();
        let expected_dec = Decimal::from_str(expected).unwrap();

        let decimal_rounded = dec.round_dp_with_strategy(
            u32::from(target_precision),
            RoundingStrategy::MidpointNearestEven,
        );
        assert_eq!(
            decimal_rounded, expected_dec,
            "Decimal rounding sanity check failed for {input}"
        );

        let mantissa = dec.mantissa();
        let scale = dec.scale() as u8;
        let excess = u32::from(scale.saturating_sub(target_precision));
        if excess > 0 {
            let rounded = bankers_round(mantissa, excess);

            // Reconstruct expected mantissa at target precision
            let expected_mantissa = expected_dec.mantissa();
            let expected_scale = expected_dec.scale() as u8;
            let scale_diff = u32::from(target_precision.saturating_sub(expected_scale));
            let normalized_expected = expected_mantissa * 10i128.pow(scale_diff);

            assert_eq!(
                rounded, normalized_expected,
                "bankers_round disagrees with Decimal for {input} at precision {target_precision}"
            );
        }
    }
}

#[cfg(test)]
mod correct_raw_tests {
    use rstest::rstest;

    use super::*;

    // All cases use precision = FIXED_PRECISION - 1 so the scale is 10 in both
    // standard-precision and high-precision modes.

    #[rstest]
    #[case(0, 0)]
    #[case(10, 10)] // Already a multiple
    #[case(14, 10)] // Rounds down
    #[case(15, 20)] // Half rounds up
    #[case(16, 20)] // Rounds up
    #[case(u64::MAX, u64::MAX - 5)] // Rounding up would overflow; rounds down instead
    fn test_correct_raw_u64(#[case] raw: u64, #[case] expected: u64) {
        assert_eq!(correct_raw_u64(raw, FIXED_PRECISION - 1), expected);
    }

    #[rstest]
    #[case(0, 0)]
    #[case(14, 10)]
    #[case(15, 20)]
    #[case(-14, -10)] // Rounds toward zero
    #[case(-15, -20)] // Half rounds away from zero
    #[case(-16, -20)] // Rounds away from zero
    #[case(i64::MAX, i64::MAX - 7)] // Rounding up would overflow; rounds down instead
    #[case(i64::MIN, i64::MIN + 8)] // Rounding down would overflow; rounds toward zero instead
    fn test_correct_raw_i64(#[case] raw: i64, #[case] expected: i64) {
        assert_eq!(correct_raw_i64(raw, FIXED_PRECISION - 1), expected);
    }

    #[rstest]
    #[case(0, 0)]
    #[case(14, 10)]
    #[case(15, 20)]
    #[case(u128::MAX, u128::MAX - 5)] // Rounding up would overflow; rounds down instead
    fn test_correct_raw_u128(#[case] raw: u128, #[case] expected: u128) {
        assert_eq!(correct_raw_u128(raw, FIXED_PRECISION - 1), expected);
    }

    #[rstest]
    #[case(0, 0)]
    #[case(14, 10)]
    #[case(15, 20)]
    #[case(-15, -20)]
    #[case(i128::MAX, i128::MAX - 7)] // Rounding up would overflow; rounds down instead
    #[case(i128::MIN, i128::MIN + 8)] // Rounding down would overflow; rounds toward zero instead
    fn test_correct_raw_i128(#[case] raw: i128, #[case] expected: i128) {
        assert_eq!(correct_raw_i128(raw, FIXED_PRECISION - 1), expected);
    }

    #[rstest]
    fn test_correct_raw_identity_at_max_precision() {
        assert_eq!(correct_raw_u64(12_345, FIXED_PRECISION), 12_345);
        assert_eq!(correct_raw_i64(-12_345, FIXED_PRECISION), -12_345);
        assert_eq!(correct_raw_u128(12_345, FIXED_PRECISION), 12_345);
        assert_eq!(correct_raw_i128(-12_345, FIXED_PRECISION), -12_345);
    }
}