nautilus_derive/http/

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

//! HTTP response parsing utilities for the Derive execution client.

use anyhow::Context;
#[cfg(test)]
use nautilus_core::string::secret::SecretString;
use nautilus_core::{Params, UUID4, UnixNanos, datetime::NANOSECONDS_IN_MILLISECOND};
use nautilus_model::{
    enums::{AvgPxReconciliation, LiquiditySide, OrderType, PositionSide},
    identifiers::{AccountId, ClientOrderId, InstrumentId, TradeId, VenueOrderId},
    reports::{FillReport, OrderStatusReport, PositionStatusReport},
    types::{AccountBalance, Currency, MarginBalance, Money, Price, Quantity},
};
use rust_decimal::Decimal;
use serde_json::Value;
use thiserror::Error;

use crate::{
    common::{
        enums::{
            DeriveInstrumentType, DeriveLiquidityRole, DeriveOrderSide, DeriveOrderStatus,
            DeriveOrderType, DeriveTimeInForce, DeriveTriggerType,
        },
        parse::{
            derive_order_side_to_nautilus, derive_order_type_to_nautilus_for_order,
            derive_rejection_due_post_only, derive_status_to_nautilus, derive_tif_to_nautilus,
            derive_trigger_price_type_to_nautilus, format_instrument_id, strategy_rejection_reason,
        },
    },
    http::models::{DeriveOrder, DerivePosition, DeriveSubaccount, DeriveTrade},
};

/// Builds an [`OrderStatusReport`] from a Derive order record.
///
/// `client_order_id` is sourced from the `label` field on the order when the
/// label is a valid Nautilus identifier; callers that need a specific client_order_id should
/// override via `with_client_order_id` after this call.
/// Trailing zero padding is removed without changing the value.
///
/// # Errors
///
/// Returns an error if the venue order identifier is invalid or the amount or filled amount cannot
/// be converted to a Nautilus `Quantity`.
pub fn parse_derive_order_to_report(
    order: &DeriveOrder,
    account_id: AccountId,
    ts_init: UnixNanos,
) -> anyhow::Result<OrderStatusReport> {
    parse_derive_order_to_report_with_precision(order, account_id, None, None, ts_init)
}

pub(crate) fn parse_derive_order_to_report_with_precision(
    order: &DeriveOrder,
    account_id: AccountId,
    price_precision: Option<u8>,
    size_precision: Option<u8>,
    ts_init: UnixNanos,
) -> anyhow::Result<OrderStatusReport> {
    let instrument_id = format_instrument_id(order.instrument_name)?;
    let venue_order_id =
        VenueOrderId::new_checked(order.order_id.as_str()).context("invalid Derive order_id")?;
    let order_side = derive_order_side_to_nautilus(order.direction);
    let order_type = derive_order_type_to_nautilus_for_report(order)?;
    let post_only = matches!(order.time_in_force, DeriveTimeInForce::PostOnly);
    let time_in_force = derive_tif_to_nautilus(order.time_in_force)?;
    let order_status =
        derive_status_to_nautilus(order.order_status, order.filled_amount, order.amount)?;
    let quantity = quantity_from_decimal(order.amount, size_precision, "amount")?;
    let filled_qty = quantity_from_decimal(order.filled_amount, size_precision, "filled_amount")?;

    let ts_accepted = ms_to_nanos(order.creation_timestamp);
    let ts_last = ms_to_nanos(order.last_update_timestamp);

    let mut report = OrderStatusReport::new(
        account_id,
        instrument_id,
        None,
        venue_order_id,
        order_side.into(),
        order_type,
        time_in_force,
        order_status,
        quantity,
        filled_qty,
        ts_accepted,
        ts_last,
        ts_init,
        Some(UUID4::new()),
    );

    if let Some(client_order_id) =
        parse_client_order_id(order.label.as_str(), venue_order_id, instrument_id)
    {
        report = report.with_client_order_id(client_order_id);
    }

    if order_type_has_limit_price(order_type) {
        anyhow::ensure!(
            order.limit_price > Decimal::ZERO,
            "Derive limit_price must be positive"
        );
        report = report.with_price(price_from_decimal(
            order.limit_price,
            price_precision,
            "limit_price",
        )?);
    }

    if let Some(trigger_price) = order.trigger_price {
        anyhow::ensure!(
            trigger_price > Decimal::ZERO,
            "Derive trigger_price must be positive"
        );
        report = report.with_trigger_price(price_from_decimal(
            trigger_price,
            price_precision,
            "trigger_price",
        )?);
    }

    if let Some(trigger_price_type) = order.trigger_price_type {
        report =
            report.with_trigger_type(derive_trigger_price_type_to_nautilus(trigger_price_type)?);
    }

    if order.average_price > Decimal::ZERO {
        report.avg_px = Some(order.average_price);
    }

    report.post_only = post_only;
    let trigger_reject_message = order
        .trigger_reject_message
        .as_deref()
        .filter(|message| !message.is_empty())
        .map(str::to_string);
    let cancel_reason = trigger_reject_message
        .clone()
        .unwrap_or_else(|| order.cancel_reason.to_string());
    if order.order_status == DeriveOrderStatus::Cancelled
        || (order.order_status == DeriveOrderStatus::Rejected
            && (trigger_reject_message.is_some()
                || derive_rejection_due_post_only(None, &cancel_reason)))
    {
        report.cancel_reason = Some(if order.order_status == DeriveOrderStatus::Rejected {
            log::debug!(
                "Derive native rejection for {}: {cancel_reason}",
                order.order_id
            );
            strategy_rejection_reason(&cancel_reason)
        } else {
            cancel_reason
        });
    }

    Ok(report)
}

fn order_type_has_limit_price(order_type: OrderType) -> bool {
    matches!(
        order_type,
        OrderType::Limit | OrderType::StopLimit | OrderType::LimitIfTouched
    )
}

fn derive_order_type_to_nautilus_for_report(order: &DeriveOrder) -> anyhow::Result<OrderType> {
    let order_type = derive_order_type_to_nautilus_for_order(order.order_type, order.trigger_type)?;
    if order_type != OrderType::LimitIfTouched {
        return Ok(order_type);
    }

    Ok(
        match (order.order_type, order.trigger_type, order.trigger_price) {
            (DeriveOrderType::Limit, Some(DeriveTriggerType::Takeprofit), Some(trigger_price))
                if !limit_if_touched_prices_are_valid(
                    order.direction,
                    order.limit_price,
                    trigger_price,
                ) =>
            {
                OrderType::StopLimit
            }
            _ => order_type,
        },
    )
}

fn limit_if_touched_prices_are_valid(
    direction: DeriveOrderSide,
    limit_price: Decimal,
    trigger_price: Decimal,
) -> bool {
    match direction {
        DeriveOrderSide::Buy => trigger_price <= limit_price,
        DeriveOrderSide::Sell => trigger_price >= limit_price,
    }
}

/// Builds a [`FillReport`] from a Derive trade record.
///
/// Quote-currency commission is reported in the same currency as the
/// instrument's settlement (USDC for perps and options). `client_order_id`
/// is sourced from the trade `label` when it is a valid Nautilus identifier.
/// Trailing zero padding is removed without changing the value.
/// Returns `Ok(None)` with a warning when the trade or order identifier is empty.
///
/// # Errors
///
/// Returns an error if a nonempty required identifier is invalid or a decimal field cannot be
/// converted to a Nautilus `Price`, `Quantity`, or `Money`.
pub fn parse_derive_trade_to_fill_report(
    trade: &DeriveTrade,
    account_id: AccountId,
    fee_currency: Currency,
    ts_init: UnixNanos,
) -> anyhow::Result<Option<FillReport>> {
    parse_derive_trade_to_fill_report_with_precision(
        trade,
        account_id,
        fee_currency,
        None,
        None,
        ts_init,
    )
}

pub(crate) fn parse_derive_trade_to_fill_report_with_precision(
    trade: &DeriveTrade,
    account_id: AccountId,
    fee_currency: Currency,
    price_precision: Option<u8>,
    size_precision: Option<u8>,
    ts_init: UnixNanos,
) -> anyhow::Result<Option<FillReport>> {
    if trade.trade_id.is_empty() || trade.order_id.is_empty() {
        log::warn!(
            "Skipping Derive trade for {}: missing trade_id={}, missing order_id={}",
            trade.instrument_name,
            trade.trade_id.is_empty(),
            trade.order_id.is_empty(),
        );
        return Ok(None);
    }

    let instrument_id = format_instrument_id(trade.instrument_name)?;
    let venue_order_id =
        VenueOrderId::new_checked(trade.order_id.as_str()).context("invalid Derive order_id")?;
    let trade_id =
        TradeId::new_checked(trade.trade_id.as_str()).context("invalid Derive trade_id")?;
    let order_side = derive_order_side_to_nautilus(trade.direction);
    let last_qty = quantity_from_decimal(trade.trade_amount, size_precision, "trade_amount")?;
    anyhow::ensure!(
        !last_qty.is_zero(),
        "invalid Derive trade_amount: zero fill quantity after conversion (trade_id={trade_id}, instrument_id={instrument_id}, trade_amount={}, size_precision={})",
        trade.trade_amount,
        last_qty.precision,
    );
    let last_px = price_from_decimal(trade.trade_price, price_precision, "trade_price")?;
    let commission = commission_from_decimal(trade.trade_fee, fee_currency)?;

    let liquidity_side = match trade.liquidity_role {
        DeriveLiquidityRole::Maker => LiquiditySide::Maker,
        DeriveLiquidityRole::Taker => LiquiditySide::Taker,
        DeriveLiquidityRole::Unknown => LiquiditySide::NoLiquiditySide,
    };

    let client_order_id =
        parse_client_order_id(trade.label.as_str(), venue_order_id, instrument_id);

    let ts_event = ms_to_nanos(trade.timestamp);

    Ok(Some(FillReport::new(
        account_id,
        instrument_id,
        venue_order_id,
        trade_id,
        order_side,
        last_qty,
        last_px,
        commission,
        liquidity_side,
        client_order_id,
        None,
        ts_event,
        ts_init,
        Some(UUID4::new()),
    )))
}

/// Builds a [`PositionStatusReport`] from a Derive position record.
///
/// Trailing zero padding is removed without changing the value.
///
/// # Errors
///
/// Returns an error if the position amount cannot be converted to a Nautilus `Quantity` without
/// changing its value.
pub fn parse_derive_position_to_report(
    position: &DerivePosition,
    account_id: AccountId,
    ts_init: UnixNanos,
) -> anyhow::Result<PositionStatusReport> {
    parse_derive_position_to_report_with_precision(position, account_id, None, ts_init)
}

pub(crate) fn parse_derive_position_to_report_with_precision(
    position: &DerivePosition,
    account_id: AccountId,
    size_precision: Option<u8>,
    ts_init: UnixNanos,
) -> anyhow::Result<PositionStatusReport> {
    let instrument_id = format_instrument_id(position.instrument_name)?;
    let signed_amount = position.amount;

    let side = if signed_amount > Decimal::ZERO {
        PositionSide::Long
    } else if signed_amount < Decimal::ZERO {
        PositionSide::Short
    } else {
        PositionSide::Flat
    };

    let abs_amount = signed_amount.abs();
    let quantity = quantity_from_decimal(abs_amount, size_precision, "position.amount")?;
    anyhow::ensure!(
        quantity.as_decimal() == abs_amount,
        "Derive position.amount {signed_amount} cannot be represented exactly for {instrument_id}",
    );

    let report = PositionStatusReport::new(
        account_id,
        instrument_id,
        side,
        quantity,
        ts_init,
        ts_init,
        Some(UUID4::new()),
        None,
        Some(position.average_price),
    );

    // Perpetual averages include opening fees, which Nautilus books as fill commissions
    if position.instrument_type == DeriveInstrumentType::Perp {
        Ok(report.with_avg_px_open_reconciliation(AvgPxReconciliation::OpeningOnly))
    } else {
        Ok(report)
    }
}

/// Derives balances, margins, and supplemental info from a [`DeriveSubaccount`] snapshot.
///
/// Each collateral row becomes one [`AccountBalance`] in the collateral's own
/// units, rounded to its registered currency precision, with `total = amount`
/// and `locked = 0`. A subset of each collateral row remains in [`Params`]
/// with decimal strings exact within `Decimal` range and scale. The venue's
/// `collaterals[].initial_margin` is USD credit, not locked funds. Pending
/// vault-deposit holds remain metadata because their inclusion in
/// collateral amounts is not specified by the venue.
///
/// Portfolio requirements form one account-wide [`MarginBalance`] in USD:
/// `initial = positions_value - positions_initial_margin - open_orders_margin` and
/// `maintenance = positions_value - positions_maintenance_margin`. The source margin
/// fields are signed health contributions; position value removes their mark-to-market
/// credit, and open-order margin is a signed reservation. These aggregates preserve the
/// venue's portfolio offsets and round to native USD precision. Source margin
/// components and signed net health remain decimal strings in [`Params`] within
/// `Decimal` range and scale. Metadata also includes the manager, risk universe,
/// margin model, and liquidation status.
///
/// # Errors
///
/// Returns an error if the venue marks the snapshot `failed_to_fetch`, an embedded position cannot
/// be represented exactly, a balance exceeds the native range, or aggregate requirements overflow.
pub fn parse_derive_subaccount_to_balances(
    subaccount: &DeriveSubaccount,
) -> anyhow::Result<(Vec<AccountBalance>, Vec<MarginBalance>, Params)> {
    anyhow::ensure!(
        !subaccount.failed_to_fetch,
        "Derive subaccount snapshot is incomplete"
    );

    for position in &subaccount.positions {
        quantity_from_decimal(position.amount.abs(), None, "position.amount")?;
    }

    let mut balances = Vec::with_capacity(subaccount.collaterals.len());
    for collateral in &subaccount.collaterals {
        let currency = Currency::get_or_create_crypto(collateral.asset_name);

        let balance =
            AccountBalance::from_total_and_locked(collateral.amount, Decimal::ZERO, currency)
                .map_err(|e| {
                    anyhow::anyhow!(
                        "failed to build collateral balance for {} (total={}): {e}",
                        collateral.asset_name,
                        collateral.amount,
                    )
                })?;

        balances.push(balance);
    }

    let currency = Currency::USD();
    let initial_dec = subaccount
        .positions_value
        .checked_sub(subaccount.positions_initial_margin)
        .and_then(|value| value.checked_sub(subaccount.open_orders_margin))
        .context("Derive initial margin requirement exceeds Decimal range")?;
    let maintenance_dec = subaccount
        .positions_value
        .checked_sub(subaccount.positions_maintenance_margin)
        .context("Derive maintenance margin requirement exceeds Decimal range")?;

    let initial = Money::from_decimal(initial_dec, currency).with_context(|| {
        format!(
            "initial margin requirement {initial_dec} cannot be represented at {currency} precision",
        )
    })?;

    let maintenance =
        Money::from_decimal(maintenance_dec, currency).with_context(|| {
            format!(
                "maintenance margin requirement {maintenance_dec} cannot be represented at {currency} precision",
            )
        })?;

    let margins = vec![MarginBalance::new(initial, maintenance, None)];

    let mut info = Params::new();
    info.insert(
        "collaterals".to_string(),
        serde_json::to_value(&subaccount.collaterals)?,
    );
    info.insert(
        "currency".to_string(),
        serde_json::to_value(&subaccount.currency)?,
    );
    info.insert(
        "margin_type".to_string(),
        Value::String(subaccount.margin_type.clone()),
    );
    info.insert("manager_id".to_string(), Value::from(subaccount.manager_id));
    info.insert(
        "risk_universe_id".to_string(),
        Value::from(subaccount.risk_universe_id),
    );
    info.insert(
        "mm_credits".to_string(),
        Value::String(subaccount.mm_credits.to_string()),
    );
    info.insert(
        "projected_margin_change".to_string(),
        Value::String(subaccount.projected_margin_change.to_string()),
    );
    info.insert(
        "vault_deposit_holds".to_string(),
        serde_json::to_value(&subaccount.vault_deposit_holds)?,
    );
    info.insert(
        "net_initial_margin".to_string(),
        Value::String(subaccount.initial_margin.to_string()),
    );
    info.insert(
        "net_maintenance_margin".to_string(),
        Value::String(subaccount.maintenance_margin.to_string()),
    );
    info.insert(
        "positions_value".to_string(),
        Value::String(subaccount.positions_value.to_string()),
    );
    info.insert(
        "positions_initial_margin".to_string(),
        Value::String(subaccount.positions_initial_margin.to_string()),
    );
    info.insert(
        "positions_maintenance_margin".to_string(),
        Value::String(subaccount.positions_maintenance_margin.to_string()),
    );
    info.insert(
        "open_orders_margin".to_string(),
        Value::String(subaccount.open_orders_margin.to_string()),
    );
    info.insert(
        "is_under_liquidation".to_string(),
        Value::Bool(subaccount.is_under_liquidation),
    );

    Ok((balances, margins, info))
}

fn price_from_decimal(value: Decimal, precision: Option<u8>, field: &str) -> anyhow::Result<Price> {
    match precision {
        Some(precision) => Price::from_decimal_dp(value, precision),
        None => Price::from_decimal(value.normalize()),
    }
    .with_context(|| format!("invalid Derive {field}"))
}

fn quantity_from_decimal(
    value: Decimal,
    precision: Option<u8>,
    field: &str,
) -> anyhow::Result<Quantity> {
    match precision {
        Some(precision) => Quantity::from_decimal_dp(value, precision),
        None => Quantity::from_decimal(value.normalize()),
    }
    .with_context(|| format!("invalid Derive {field}"))
}

fn parse_client_order_id(
    label: &str,
    venue_order_id: VenueOrderId,
    instrument_id: InstrumentId,
) -> Option<ClientOrderId> {
    if label.is_empty() {
        return None;
    }

    match ClientOrderId::new_checked(label) {
        Ok(client_order_id) => Some(client_order_id),
        Err(_) => {
            log::warn!(
                "Ignoring unrepresentable Derive client label for order {:?} on {:?}",
                venue_order_id.as_str(),
                instrument_id.to_string(),
            );
            None
        }
    }
}

fn commission_from_decimal(value: Decimal, currency: Currency) -> anyhow::Result<Money> {
    Money::from_decimal(value, currency).with_context(|| CommissionError { value, currency })
}

#[derive(Debug, Error)]
#[error("trade_fee {value} cannot be represented at {currency} precision")]
pub(crate) struct CommissionError {
    value: Decimal,
    currency: Currency,
}

pub(crate) fn ms_to_nanos(value: i64) -> UnixNanos {
    let clamped = u64::try_from(value.max(0)).unwrap_or(0);
    UnixNanos::from(clamped.saturating_mul(NANOSECONDS_IN_MILLISECOND))
}

#[cfg(test)]
mod tests {
    use nautilus_model::enums::{OrderSide, OrderStatus, OrderType, TimeInForce, TriggerType};
    use rstest::rstest;
    use rust_decimal_macros::dec;

    use super::*;
    use crate::{
        common::{
            enums::{
                DeriveAssetType, DeriveLiquidityRole, DeriveOrderCancelReason, DeriveOrderSide,
                DeriveOrderStatus, DeriveOrderType, DeriveTimeInForce, DeriveTriggerPriceType,
                DeriveTriggerType,
            },
            parse::{
                derive_status_to_nautilus, order_side_to_derive, order_type_to_derive,
                time_in_force_to_derive,
            },
        },
        http::models::DeriveCollateral,
    };

    fn sample_order() -> DeriveOrder {
        DeriveOrder {
            amount: dec!(10),
            average_price: dec!(3500),
            cancel_reason: DeriveOrderCancelReason::Empty,
            creation_timestamp: 1_700_000_000_000,
            direction: DeriveOrderSide::Buy,
            filled_amount: dec!(4),
            instrument_name: "ETH-PERP".into(),
            is_transfer: false,
            label: "STRATEGY-1-O-1".into(),
            last_update_timestamp: 1_700_000_001_000,
            limit_price: dec!(3500),
            max_fee: dec!(1),
            mmp: false,
            nonce: 1,
            order_fee: dec!(0),
            order_id: "ord-1".to_string(),
            order_status: DeriveOrderStatus::Open,
            order_type: DeriveOrderType::Limit,
            quote_id: None,
            replaced_order_id: None,
            signature: SecretString::from("0x00"),
            signature_expiry_sec: 1_700_000_999,
            signer: "0xsigner".into(),
            subaccount_id: 30769,
            time_in_force: DeriveTimeInForce::Gtc,
            trigger_price: None,
            trigger_price_type: None,
            trigger_reject_message: None,
            trigger_type: None,
        }
    }

    fn sample_trade() -> DeriveTrade {
        DeriveTrade {
            direction: DeriveOrderSide::Sell,
            index_price: dec!(3500),
            instrument_name: "ETH-PERP".into(),
            is_transfer: false,
            label: "STRATEGY-1-O-2".into(),
            liquidity_role: DeriveLiquidityRole::Taker,
            mark_price: dec!(3500),
            order_id: "ord-2".to_string(),
            quote_id: None,
            realized_pnl: dec!(0),
            subaccount_id: 30769,
            timestamp: 1_700_000_002_000,
            trade_amount: dec!(2),
            trade_fee: dec!(0.5),
            trade_id: "tr-1".to_string(),
            trade_price: dec!(3505),
            tx_hash: Some("0xabc".to_string()),
            batch_status: Some("Settled".to_string()),
            op_uuid: None,
            wallet: Some("0xwallet".into()),
        }
    }

    #[rstest]
    fn test_order_side_round_trip() {
        assert_eq!(order_side_to_derive(OrderSide::Buy), DeriveOrderSide::Buy,);
        assert_eq!(order_side_to_derive(OrderSide::Sell), DeriveOrderSide::Sell,);
    }

    #[rstest]
    fn test_order_type_rejects_unsupported() {
        assert_eq!(
            order_type_to_derive(OrderType::Limit).unwrap(),
            DeriveOrderType::Limit,
        );
        assert_eq!(
            order_type_to_derive(OrderType::Market).unwrap(),
            DeriveOrderType::Market,
        );
        assert!(order_type_to_derive(OrderType::StopMarket).is_err());
    }

    #[rstest]
    #[case(TimeInForce::Gtc, false, DeriveTimeInForce::Gtc)]
    #[case(TimeInForce::Gtc, true, DeriveTimeInForce::PostOnly)]
    #[case(TimeInForce::Ioc, false, DeriveTimeInForce::Ioc)]
    #[case(TimeInForce::Fok, false, DeriveTimeInForce::Fok)]
    fn test_time_in_force_maps_supported_values(
        #[case] tif: TimeInForce,
        #[case] post_only: bool,
        #[case] expected: DeriveTimeInForce,
    ) {
        assert_eq!(time_in_force_to_derive(tif, post_only).unwrap(), expected);
    }

    #[rstest]
    #[case(TimeInForce::Ioc)]
    #[case(TimeInForce::Fok)]
    fn test_time_in_force_rejects_post_only_immediate_values(#[case] tif: TimeInForce) {
        let err = time_in_force_to_derive(tif, true)
            .expect_err("post-only immediate TIF must be rejected");

        assert!(
            err.to_string()
                .contains("post-only Derive orders only support GTC"),
            "unexpected error: {err}",
        );
    }

    #[rstest]
    #[case(TimeInForce::Gtd, false)]
    #[case(TimeInForce::Gtd, true)]
    #[case(TimeInForce::Day, false)]
    #[case(TimeInForce::Day, true)]
    #[case(TimeInForce::AtTheOpen, false)]
    #[case(TimeInForce::AtTheOpen, true)]
    #[case(TimeInForce::AtTheClose, false)]
    #[case(TimeInForce::AtTheClose, true)]
    fn test_time_in_force_rejects_unsupported(#[case] tif: TimeInForce, #[case] post_only: bool) {
        let err = time_in_force_to_derive(tif, post_only).expect_err("must reject unsupported TIF");

        assert!(
            err.to_string().contains("unsupported time in force"),
            "unexpected error: {err}",
        );
    }

    #[rstest]
    #[case("order_type")]
    #[case("time_in_force")]
    #[case("trigger_type")]
    #[case("trigger_price_type")]
    fn test_order_report_rejects_unknown_semantics(#[case] field: &str) {
        let mut value = serde_json::to_value(sample_order()).unwrap();
        value[field] = serde_json::json!("future-variant");
        let order: DeriveOrder = serde_json::from_value(value).unwrap();
        assert!(
            parse_derive_order_to_report(
                &order,
                AccountId::from("DERIVE-001"),
                UnixNanos::from(17)
            )
            .is_err()
        );
    }

    #[rstest]
    #[case(false)]
    #[case(true)]
    fn test_order_report_rejects_unrepresentable_price(#[case] trigger: bool) {
        let mut order = sample_order();
        if trigger {
            order.trigger_type = Some(DeriveTriggerType::Stoploss);
            order.trigger_price = Some(Decimal::MAX);
        } else {
            order.limit_price = Decimal::MAX;
        }

        assert!(
            parse_derive_order_to_report(
                &order,
                AccountId::from("DERIVE-001"),
                UnixNanos::from(17)
            )
            .is_err()
        );
    }

    #[rstest]
    fn test_derive_status_partial_fill_classification() {
        assert_eq!(
            derive_status_to_nautilus(DeriveOrderStatus::Open, dec!(0), dec!(10)).unwrap(),
            OrderStatus::Accepted,
        );
        assert_eq!(
            derive_status_to_nautilus(DeriveOrderStatus::Open, dec!(4), dec!(10)).unwrap(),
            OrderStatus::PartiallyFilled,
        );
        assert_eq!(
            derive_status_to_nautilus(DeriveOrderStatus::Filled, dec!(10), dec!(10)).unwrap(),
            OrderStatus::Filled,
        );
        assert_eq!(
            derive_status_to_nautilus(DeriveOrderStatus::Cancelled, dec!(0), dec!(10)).unwrap(),
            OrderStatus::Canceled,
        );
    }

    #[rstest]
    fn test_parse_order_report_assigns_partial_fill_status() {
        let account_id = AccountId::new("DERIVE-001");
        let report =
            parse_derive_order_to_report(&sample_order(), account_id, UnixNanos::from(1)).unwrap();
        assert_eq!(report.order_status, OrderStatus::PartiallyFilled);
        assert_eq!(report.quantity, Quantity::from("10"));
        assert_eq!(report.filled_qty, Quantity::from("4"));
        assert_eq!(report.client_order_id.unwrap().as_str(), "STRATEGY-1-O-1");
        assert_eq!(report.venue_order_id.as_str(), "ord-1");
    }

    #[rstest]
    fn test_parse_order_report_normalizes_without_instrument_precision() {
        let mut order = sample_order();
        order.amount = Decimal::from_str_exact("0.100000000000000000").unwrap();
        order.filled_amount = Decimal::from_str_exact("0.000000000000000000").unwrap();
        order.limit_price = Decimal::from_str_exact("0.100000000000000000").unwrap();
        order.average_price = Decimal::ZERO;
        order.order_status = DeriveOrderStatus::Cancelled;
        let account_id = AccountId::new("DERIVE-001");

        let report = parse_derive_order_to_report(&order, account_id, UnixNanos::from(1)).unwrap();

        assert_eq!(report.quantity, Quantity::from("0.1"));
        assert_eq!(report.filled_qty, Quantity::from("0"));
        assert_eq!(report.price, Some(Price::from("0.1")));
    }

    #[rstest]
    fn test_parse_order_report_uses_instrument_precision() {
        let mut order = sample_order();
        order.amount = Decimal::from_str_exact("25.000").unwrap();
        order.filled_amount = Decimal::from_str_exact("5.000").unwrap();
        order.limit_price = Decimal::from_str_exact("25.000").unwrap();

        let report = parse_derive_order_to_report_with_precision(
            &order,
            AccountId::new("DERIVE-001"),
            Some(2),
            Some(2),
            UnixNanos::from(1),
        )
        .unwrap();

        assert_eq!(report.quantity, Quantity::from("25.00"));
        assert_eq!(report.quantity.precision, 2);
        assert_eq!(report.filled_qty, Quantity::from("5.00"));
        assert_eq!(report.filled_qty.precision, 2);
        assert_eq!(report.price, Some(Price::from("25.00")));
        assert_eq!(report.price.unwrap().precision, 2);
    }

    #[rstest]
    fn test_parse_order_report_maps_untriggered_stop_market() {
        let mut order = sample_order();
        order.average_price = Decimal::ZERO;
        order.filled_amount = Decimal::ZERO;
        order.limit_price = dec!(3400);
        order.order_status = DeriveOrderStatus::Untriggered;
        order.order_type = DeriveOrderType::Market;
        order.trigger_price = Some(dec!(3450));
        order.trigger_price_type = Some(DeriveTriggerPriceType::Mark);
        order.trigger_type = Some(DeriveTriggerType::Stoploss);
        let account_id = AccountId::new("DERIVE-001");

        let report = parse_derive_order_to_report(&order, account_id, UnixNanos::from(1)).unwrap();

        assert_eq!(report.order_type, OrderType::StopMarket);
        assert_eq!(report.order_status, OrderStatus::Accepted);
        assert_eq!(report.price, None);
        assert_eq!(report.trigger_price, Some(Price::from("3450")));
        assert_eq!(report.trigger_type, Some(TriggerType::MarkPrice));
    }

    #[rstest]
    #[case(DeriveOrderSide::Buy, dec!(3700), dec!(3600))]
    #[case(DeriveOrderSide::Buy, dec!(3700), dec!(3700))]
    #[case(DeriveOrderSide::Sell, dec!(3700), dec!(3800))]
    #[case(DeriveOrderSide::Sell, dec!(3700), dec!(3700))]
    fn test_parse_order_report_maps_limit_if_touched_trigger(
        #[case] direction: DeriveOrderSide,
        #[case] limit_price: Decimal,
        #[case] trigger_price: Decimal,
    ) {
        let mut order = sample_order();
        order.average_price = Decimal::ZERO;
        order.direction = direction;
        order.filled_amount = Decimal::ZERO;
        order.limit_price = limit_price;
        order.order_status = DeriveOrderStatus::Untriggered;
        order.order_type = DeriveOrderType::Limit;
        order.trigger_price = Some(trigger_price);
        order.trigger_price_type = Some(DeriveTriggerPriceType::Index);
        order.trigger_type = Some(DeriveTriggerType::Takeprofit);
        let account_id = AccountId::new("DERIVE-001");

        let report = parse_derive_order_to_report(&order, account_id, UnixNanos::from(1)).unwrap();

        assert_eq!(report.order_type, OrderType::LimitIfTouched);
        assert_eq!(
            report.price,
            Some(Price::from_decimal(limit_price.normalize()).unwrap())
        );
        assert_eq!(
            report.trigger_price,
            Some(Price::from_decimal(trigger_price.normalize()).unwrap())
        );
        assert_eq!(report.trigger_type, Some(TriggerType::IndexPrice));
    }

    #[rstest]
    #[case(DeriveOrderSide::Buy, dec!(3700), dec!(3800))]
    #[case(DeriveOrderSide::Sell, dec!(3700), dec!(3600))]
    fn test_parse_order_report_maps_take_profit_limit_with_stop_shape(
        #[case] direction: DeriveOrderSide,
        #[case] limit_price: Decimal,
        #[case] trigger_price: Decimal,
    ) {
        let mut order = sample_order();
        order.average_price = Decimal::ZERO;
        order.direction = direction;
        order.filled_amount = Decimal::ZERO;
        order.limit_price = limit_price;
        order.order_status = DeriveOrderStatus::Untriggered;
        order.order_type = DeriveOrderType::Limit;
        order.trigger_price = Some(trigger_price);
        order.trigger_price_type = Some(DeriveTriggerPriceType::Index);
        order.trigger_type = Some(DeriveTriggerType::Takeprofit);
        let account_id = AccountId::new("DERIVE-001");

        let report = parse_derive_order_to_report(&order, account_id, UnixNanos::from(1)).unwrap();

        assert_eq!(report.order_type, OrderType::StopLimit);
        assert_eq!(
            report.price,
            Some(Price::from_decimal(limit_price.normalize()).unwrap())
        );
        assert_eq!(
            report.trigger_price,
            Some(Price::from_decimal(trigger_price.normalize()).unwrap())
        );
        assert_eq!(report.trigger_type, Some(TriggerType::IndexPrice));
    }

    #[rstest]
    fn test_parse_rejected_post_only_report_keeps_cross_market_reason() {
        let mut order = sample_order();
        order.cancel_reason = DeriveOrderCancelReason::PostOnlyCrossMarket;
        order.order_status = DeriveOrderStatus::Rejected;
        order.time_in_force = DeriveTimeInForce::PostOnly;
        let account_id = AccountId::new("DERIVE-001");

        let report = parse_derive_order_to_report(&order, account_id, UnixNanos::from(1)).unwrap();

        assert_eq!(report.order_status, OrderStatus::Rejected);
        assert!(report.post_only);
        assert_eq!(
            report.cancel_reason.as_deref(),
            Some("Post only order cannot cross the market")
        );
    }

    #[rstest]
    #[case(
        "trigger price moved through limit",
        "trigger price moved through limit"
    )]
    #[case(" <p>risk\t limit</p>\0\n exceeded ", "risk limit exceeded")]
    #[case("<p>\0</p>", "Order command rejected")]
    fn test_parse_rejected_trigger_report_uses_trigger_message(
        #[case] message: &str,
        #[case] expected: &str,
    ) {
        let mut order = sample_order();
        order.cancel_reason = DeriveOrderCancelReason::TriggerFailed;
        order.order_status = DeriveOrderStatus::Rejected;
        order.trigger_reject_message = Some(message.to_string());
        let account_id = AccountId::new("DERIVE-001");

        let report = parse_derive_order_to_report(&order, account_id, UnixNanos::from(1)).unwrap();

        assert_eq!(report.order_status, OrderStatus::Rejected);
        assert_eq!(report.cancel_reason.as_deref(), Some(expected));
    }

    #[rstest]
    fn test_parse_trade_report_emits_taker_fill() {
        let account_id = AccountId::new("DERIVE-001");
        let usdc = Currency::USDC();
        let report = parse_derive_trade_to_fill_report(
            &sample_trade(),
            account_id,
            usdc,
            UnixNanos::from(2),
        )
        .unwrap()
        .unwrap();
        assert_eq!(report.order_side, OrderSide::Sell);
        assert_eq!(report.last_qty, Quantity::from("2"));
        assert_eq!(report.last_px, Price::from("3505"));
        assert_eq!(report.liquidity_side, LiquiditySide::Taker);
        assert_eq!(report.commission.as_decimal(), dec!(0.5));
    }

    #[rstest]
    #[case::literal_zero(dec!(0), Some(2), true)]
    #[case::unconfigured_zero(dec!(0), None, true)]
    #[case::rounded_zero(dec!(0.004), Some(2), true)]
    #[case::half_even_zero(dec!(0.005), Some(2), true)]
    #[case::positive(dec!(0.006), Some(2), false)]
    fn test_parse_trade_report_zero_quantity(
        #[case] amount: Decimal,
        #[case] precision: Option<u8>,
        #[case] rejected: bool,
    ) {
        let mut trade = sample_trade();
        trade.trade_amount = amount;

        let result = parse_derive_trade_to_fill_report_with_precision(
            &trade,
            AccountId::new("DERIVE-001"),
            Currency::USDC(),
            None,
            precision,
            UnixNanos::from(2),
        );

        if rejected {
            let message = result.unwrap_err().to_string();
            assert!(message.contains(&format!("trade_id={}", trade.trade_id)));
            assert!(message.contains(&format!("instrument_id={}.DERIVE", trade.instrument_name)));
            assert!(message.contains(&format!("trade_amount={amount}")));
            assert!(message.contains(&format!("size_precision={}", precision.unwrap_or(0))));
        } else {
            assert_eq!(result.unwrap().unwrap().last_qty, Quantity::from("0.01"));
        }
    }

    #[rstest]
    #[case("")]
    #[case(" ")]
    #[case("external-\u{03bb}")]
    fn test_parse_reports_preserve_external_order_without_client_label(#[case] label: &str) {
        let mut order = sample_order();
        order.label = label.into();
        let mut trade = sample_trade();
        trade.label = label.into();
        let account_id = AccountId::from("DERIVE-001");
        let ts_init = UnixNanos::from(123);
        let order_report = parse_derive_order_to_report(&order, account_id, ts_init).unwrap();
        let fill_report =
            parse_derive_trade_to_fill_report(&trade, account_id, Currency::USDC(), ts_init)
                .unwrap()
                .unwrap();

        assert_eq!(order_report.client_order_id, None);
        assert_eq!(order_report.venue_order_id, VenueOrderId::from("ord-1"));
        assert_eq!(order_report.quantity.as_decimal(), dec!(10));
        assert_eq!(order_report.filled_qty.as_decimal(), dec!(4));
        assert_eq!(fill_report.client_order_id, None);
        assert_eq!(fill_report.venue_order_id, VenueOrderId::from("ord-2"));
        assert_eq!(fill_report.trade_id, TradeId::from("tr-1"));
        assert_eq!(fill_report.last_qty.as_decimal(), dec!(2));
        assert_eq!(fill_report.last_px.as_decimal(), dec!(3505));
        assert_eq!(fill_report.commission.as_decimal(), dec!(0.5));
        assert_eq!(fill_report.commission.currency, Currency::USDC());
    }

    #[rstest]
    #[case(" ")]
    #[case("external-\u{03bb}")]
    #[case("1234567890123456789012345678901234567")]
    fn test_parse_trade_report_rejects_invalid_trade_id(#[case] trade_id: &str) {
        let mut trade = sample_trade();
        trade.trade_id = trade_id.to_string();
        let result = parse_derive_trade_to_fill_report(
            &trade,
            AccountId::from("DERIVE-001"),
            Currency::USDC(),
            UnixNanos::default(),
        );

        assert_eq!(result.unwrap_err().to_string(), "invalid Derive trade_id");
    }

    #[rstest]
    #[case(" ")]
    #[case("external-\u{03bb}")]
    fn test_parse_reports_reject_invalid_venue_order_id(#[case] order_id: &str) {
        let mut order = sample_order();
        order.order_id = order_id.to_string();
        let mut trade = sample_trade();
        trade.order_id = order_id.to_string();
        let account_id = AccountId::from("DERIVE-001");
        let order_result = parse_derive_order_to_report(&order, account_id, UnixNanos::default());
        let fill_result = parse_derive_trade_to_fill_report(
            &trade,
            account_id,
            Currency::USDC(),
            UnixNanos::default(),
        );

        assert_eq!(
            order_result.unwrap_err().to_string(),
            "invalid Derive order_id"
        );
        assert_eq!(
            fill_result.unwrap_err().to_string(),
            "invalid Derive order_id"
        );
    }

    #[rstest]
    fn test_parse_reports_preserve_valid_identity_bytes() {
        let label = " external-label ";
        let order_id = " external-order ";
        let trade_id = "123456789012345678901234567890123456";
        let mut order = sample_order();
        order.label = label.into();
        order.order_id = order_id.to_string();
        let mut trade = sample_trade();
        trade.label = label.into();
        trade.order_id = order_id.to_string();
        trade.trade_id = trade_id.to_string();
        let account_id = AccountId::from("DERIVE-001");
        let order_report =
            parse_derive_order_to_report(&order, account_id, UnixNanos::default()).unwrap();
        let fill_report = parse_derive_trade_to_fill_report(
            &trade,
            account_id,
            Currency::USDC(),
            UnixNanos::default(),
        )
        .unwrap()
        .unwrap();

        assert_eq!(order_report.client_order_id.unwrap().as_str(), label);
        assert_eq!(order_report.venue_order_id.as_str(), order_id);
        assert_eq!(fill_report.client_order_id.unwrap().as_str(), label);
        assert_eq!(fill_report.venue_order_id.as_str(), order_id);
        assert_eq!(fill_report.trade_id.as_str(), trade_id);
        assert_eq!(fill_report.last_qty.as_decimal(), dec!(2));
        assert_eq!(fill_report.last_px.as_decimal(), dec!(3505));
        assert_eq!(fill_report.commission.as_decimal(), dec!(0.5));
    }

    #[rstest]
    fn test_parse_trade_report_uses_instrument_precision() {
        let mut trade = sample_trade();
        trade.trade_amount = Decimal::from_str_exact("25.000").unwrap();
        trade.trade_price = Decimal::from_str_exact("25.000").unwrap();

        let report = parse_derive_trade_to_fill_report_with_precision(
            &trade,
            AccountId::new("DERIVE-001"),
            Currency::USDC(),
            Some(2),
            Some(3),
            UnixNanos::from(2),
        )
        .unwrap()
        .unwrap();

        assert_eq!(report.last_px, Price::from("25.00"));
        assert_eq!(report.last_px.precision, 2);
        assert_eq!(report.last_qty, Quantity::from("25.000"));
        assert_eq!(report.last_qty.precision, 3);
    }

    #[rstest]
    #[case(DeriveLiquidityRole::Taker, LiquiditySide::Taker)]
    #[case(DeriveLiquidityRole::Maker, LiquiditySide::Maker)]
    fn test_parse_trade_report_preserves_exact_decimal_commission(
        #[case] liquidity_role: DeriveLiquidityRole,
        #[case] expected_liquidity_side: LiquiditySide,
    ) {
        let mut trade = sample_trade();
        trade.trade_fee = dec!(0.12345678);
        trade.liquidity_role = liquidity_role;
        let account_id = AccountId::new("DERIVE-001");
        let usdc = Currency::USDC();
        let report =
            parse_derive_trade_to_fill_report(&trade, account_id, usdc, UnixNanos::from(2))
                .unwrap()
                .expect("exact USDC-precision fee must emit the fill");
        assert_eq!(report.commission.as_decimal(), dec!(0.12345678));
        assert_eq!(report.commission.currency, usdc);
        assert_eq!(report.liquidity_side, expected_liquidity_side);
    }

    #[rstest]
    #[case(dec!(0.000000025), dec!(0.00000002))]
    #[case(dec!(0.000000015), dec!(0.00000002))]
    fn test_parse_trade_report_rounds_half_unit_commission_from_decimal(
        #[case] trade_fee: Decimal,
        #[case] expected: Decimal,
    ) {
        // These half-unit values are where the old f64 path diverged
        let mut trade = sample_trade();
        trade.trade_fee = trade_fee;
        let account_id = AccountId::new("DERIVE-001");
        let report = parse_derive_trade_to_fill_report(
            &trade,
            account_id,
            Currency::USDC(),
            UnixNanos::from(2),
        )
        .unwrap()
        .expect("sub-precision fee must still emit the fill");
        assert_eq!(report.commission.as_decimal(), expected);
    }

    #[rstest]
    fn test_parse_trade_report_errors_on_out_of_range_commission() {
        let mut trade = sample_trade();
        trade.trade_fee = Decimal::MAX;
        let account_id = AccountId::new("DERIVE-001");
        let err = parse_derive_trade_to_fill_report(
            &trade,
            account_id,
            Currency::USDC(),
            UnixNanos::from(2),
        )
        .expect_err("out-of-range fee must error instead of panicking");
        assert!(
            err.to_string().contains("trade_fee"),
            "unexpected error: {err}",
        );
    }

    #[rstest]
    fn test_v3_trade_reports_preserve_execution_across_batch_stages() {
        let stages: Vec<Option<String>> = serde_json::from_str(include_str!(
            "../../test_data/common/trade_batch_stages.json"
        ))
        .unwrap();
        let trades: Vec<DeriveTrade> = serde_json::from_str(include_str!(
            "../../test_data/perps/http_trades_v3_native.json"
        ))
        .unwrap();
        let account_id = AccountId::new("DERIVE-001");

        for stage in stages {
            for (i, original) in trades.iter().enumerate() {
                let mut trade = original.clone();
                trade.batch_status = stage.clone();
                trade.tx_hash = None;
                trade.op_uuid = None;
                let report = parse_derive_trade_to_fill_report_with_precision(
                    &trade,
                    account_id,
                    Currency::USDC(),
                    Some(2),
                    Some(3),
                    UnixNanos::from(91),
                )
                .unwrap()
                .unwrap();
                assert_eq!(report.account_id, account_id);
                assert_eq!(report.instrument_id, InstrumentId::from("ETH-PERP.DERIVE"));
                assert_eq!(report.venue_order_id, VenueOrderId::new(&trade.order_id));
                assert_eq!(report.trade_id, TradeId::new(&trade.trade_id));
                assert_eq!(
                    report.client_order_id,
                    Some(ClientOrderId::new(trade.label))
                );
                assert_eq!(report.venue_position_id, None);
                assert_eq!(report.order_side, [OrderSide::Sell, OrderSide::Buy][i]);
                assert_eq!(report.last_qty, Quantity::from("0.100"));
                assert_eq!(
                    report.last_px,
                    [Price::from("2568.50"), Price::from("2568.89")][i]
                );
                assert_eq!(report.commission.currency, Currency::USDC());
                assert_eq!(
                    report.commission.as_decimal(),
                    [dec!(0.08705248), dec!(0.08705274)][i]
                );
                assert_eq!(report.liquidity_side, LiquiditySide::Taker);
                assert_eq!(
                    report.ts_event,
                    UnixNanos::from([1_751_600_001_000_000_000, 1_751_600_000_000_000_000][i])
                );
                assert_eq!(report.ts_init, UnixNanos::from(91));
                assert_eq!(report.avg_px, None);
            }
        }
    }

    #[rstest]
    #[case("", "order-1")]
    #[case("trade-1", "")]
    fn test_trade_reports_require_execution_identities(
        #[case] trade_id: &str,
        #[case] order_id: &str,
    ) {
        let mut trade = sample_trade();
        trade.trade_id = trade_id.to_string();
        trade.order_id = order_id.to_string();
        let report = parse_derive_trade_to_fill_report(
            &trade,
            AccountId::new("DERIVE-001"),
            Currency::USDC(),
            UnixNanos::from(91),
        )
        .unwrap();
        assert_eq!(report, None);
    }

    #[rstest]
    fn test_parse_trade_report_preserves_batch_error_fill() {
        let mut trade = sample_trade();
        trade.batch_status = Some("SettlingError".to_string());
        let account_id = AccountId::new("DERIVE-001");
        let usdc = Currency::USDC();
        let report =
            parse_derive_trade_to_fill_report(&trade, account_id, usdc, UnixNanos::from(2))
                .unwrap();
        assert_eq!(report.unwrap().trade_id, TradeId::new("tr-1"));
    }

    #[rstest]
    fn test_parse_trade_report_degrades_unknown_liquidity_role() {
        let mut trade = sample_trade();
        trade.liquidity_role = DeriveLiquidityRole::Unknown;
        let account_id = AccountId::new("DERIVE-001");
        let usdc = Currency::USDC();

        let report =
            parse_derive_trade_to_fill_report(&trade, account_id, usdc, UnixNanos::from(2))
                .unwrap()
                .expect("unknown liquidity role must still emit the fill");

        assert_eq!(report.liquidity_side, LiquiditySide::NoLiquiditySide);
    }

    #[rstest]
    #[case("order")]
    #[case("trade")]
    #[case("position")]
    fn test_execution_parser_rejects_blank_symbol_without_panic(
        #[case] record: &str,
        #[values("", " ", "\t\n")] symbol: &str,
    ) {
        let account_id = AccountId::from("DERIVE-001");

        let result = std::panic::catch_unwind(|| match record {
            "order" => {
                let mut order = sample_order();
                order.instrument_name = symbol.into();
                parse_derive_order_to_report(&order, account_id, UnixNanos::from(17)).map(|_| ())
            }
            "trade" => {
                let mut trade = sample_trade();
                trade.instrument_name = symbol.into();
                parse_derive_trade_to_fill_report(
                    &trade,
                    account_id,
                    Currency::USDC(),
                    UnixNanos::from(17),
                )
                .map(|_| ())
            }
            "position" => {
                let mut position = sample_position();
                position.instrument_name = symbol.into();
                parse_derive_position_to_report(&position, account_id, UnixNanos::from(17))
                    .map(|_| ())
            }
            _ => unreachable!(),
        });

        assert!(result.is_ok(), "untrusted symbols must not panic");
        assert!(result.unwrap().is_err());
    }

    #[rstest]
    fn test_parse_position_long_short_flat() {
        let account_id = AccountId::new("DERIVE-001");

        let mut long_pos = sample_position();
        long_pos.amount = dec!(3);
        let report =
            parse_derive_position_to_report(&long_pos, account_id, UnixNanos::from(3)).unwrap();
        assert_eq!(report.position_side, PositionSide::Long);
        assert_eq!(report.quantity, Quantity::from("3"));

        let mut short_pos = sample_position();
        short_pos.amount = dec!(-2);
        let report =
            parse_derive_position_to_report(&short_pos, account_id, UnixNanos::from(3)).unwrap();
        assert_eq!(report.position_side, PositionSide::Short);
        assert_eq!(report.quantity, Quantity::from("2"));

        let mut flat_pos = sample_position();
        flat_pos.amount = dec!(0);
        let report =
            parse_derive_position_to_report(&flat_pos, account_id, UnixNanos::from(3)).unwrap();
        assert_eq!(report.position_side, PositionSide::Flat);
    }

    #[rstest]
    #[case::perp(DeriveInstrumentType::Perp, AvgPxReconciliation::OpeningOnly)]
    #[case::option(DeriveInstrumentType::Option, AvgPxReconciliation::Match)]
    #[case::spot(DeriveInstrumentType::Erc20, AvgPxReconciliation::Match)]
    fn test_parse_position_report_uses_instrument_precision(
        #[case] instrument_type: DeriveInstrumentType,
        #[case] reconciliation: AvgPxReconciliation,
    ) {
        let mut position = sample_position();
        position.amount = Decimal::from_str_exact("25.000").unwrap();
        position.average_price = dec!(2553.87589666777);
        position.instrument_type = instrument_type;

        let report = parse_derive_position_to_report_with_precision(
            &position,
            AccountId::new("DERIVE-001"),
            Some(3),
            UnixNanos::from(3),
        )
        .unwrap();

        assert_eq!(
            report,
            PositionStatusReport::new(
                AccountId::new("DERIVE-001"),
                InstrumentId::from("ETH-PERP.DERIVE"),
                PositionSide::Long,
                Quantity::from("25.000"),
                UnixNanos::from(3),
                UnixNanos::from(3),
                Some(report.report_id),
                None,
                Some(position.average_price),
            )
            .with_avg_px_open_reconciliation(reconciliation)
        );
        assert_eq!(report.quantity.precision, 3);
    }

    fn sample_position() -> DerivePosition {
        DerivePosition {
            amount: dec!(0),
            average_price: dec!(3500),
            creation_timestamp: 0,
            cumulative_funding: dec!(0),
            delta: dec!(0),
            gamma: dec!(0),
            index_price: dec!(3500),
            initial_margin: dec!(0),
            instrument_name: "ETH-PERP".into(),
            instrument_type: DeriveInstrumentType::Perp,
            leverage: None,
            liquidation_price: None,
            maintenance_margin: dec!(0),
            mark_price: dec!(3500),
            mark_value: dec!(0),
            net_settlements: dec!(0),
            open_orders_margin: dec!(0),
            pending_funding: dec!(0),
            realized_pnl: dec!(0),
            theta: dec!(0),
            unrealized_pnl: dec!(0),
            vega: dec!(0),
        }
    }

    #[rstest]
    #[case("order_type")]
    #[case("time_in_force")]
    #[case("order_status")]
    #[case("trigger_price_type")]
    fn test_parse_subaccount_balances_ignore_order_classification(#[case] field: &str) {
        let mut subaccount = sample_subaccount();
        let expected = parse_derive_subaccount_to_balances(&subaccount).unwrap();
        let mut order = serde_json::to_value(sample_order()).unwrap();
        order[field] = serde_json::json!("future-native-value");
        subaccount.open_orders = vec![serde_json::from_value(order).unwrap()];

        let actual = parse_derive_subaccount_to_balances(&subaccount).unwrap();

        assert_eq!(actual, expected);
    }

    #[rstest]
    fn test_parse_subaccount_emits_balances_margins_and_info() {
        let subaccount = sample_subaccount();
        let (balances, margins, info) = parse_derive_subaccount_to_balances(&subaccount).unwrap();
        assert_eq!(balances.len(), 1);
        assert_eq!(balances[0].total.as_decimal(), dec!(1000));
        assert_eq!(balances[0].locked.as_decimal(), dec!(0));
        assert_eq!(balances[0].free.as_decimal(), dec!(1000));
        assert_eq!(margins.len(), 1);
        assert_eq!(margins[0].initial.as_decimal(), dec!(0));
        assert_eq!(margins[0].maintenance.as_decimal(), dec!(0));
        assert_eq!(
            info.get("net_initial_margin"),
            Some(&serde_json::json!("100")),
        );
        assert_eq!(
            info.get("net_maintenance_margin"),
            Some(&serde_json::json!("50")),
        );
        assert_eq!(
            info.get("is_under_liquidation"),
            Some(&serde_json::json!(false)),
        );
    }

    #[rstest]
    fn test_parse_subaccount_preserves_multi_collateral_units() {
        // 2.5 ETH collateral reporting $1000 of credit stays 2.5 ETH total
        // with nothing locked: credit is not a reservation on the collateral,
        // so no mark-price conversion applies
        let mut subaccount = sample_subaccount();
        subaccount.collaterals = vec![
            DeriveCollateral {
                amount: dec!(2.5),
                asset_name: "ETH".into(),
                asset_type: DeriveAssetType::Erc20,
                cumulative_interest: dec!(0),
                currency: "ETH".into(),
                initial_margin: dec!(1000),
                maintenance_margin: dec!(500),
                mark_price: dec!(3500),
                mark_value: dec!(8750),
                pending_interest: dec!(0),
            },
            DeriveCollateral {
                amount: dec!(1000),
                asset_name: "USDC".into(),
                asset_type: DeriveAssetType::Erc20,
                cumulative_interest: dec!(0),
                currency: "USDC".into(),
                initial_margin: dec!(1000),
                maintenance_margin: dec!(1000),
                mark_price: dec!(1),
                mark_value: dec!(1000),
                pending_interest: dec!(0),
            },
        ];

        let (balances, _, _) = parse_derive_subaccount_to_balances(&subaccount).unwrap();
        assert_eq!(balances.len(), 2);
        assert_eq!(balances[0].total.currency, Currency::ETH());
        assert_eq!(balances[1].total.currency, Currency::USDC());
        assert_eq!(balances[0].total.as_decimal(), dec!(2.5));
        assert_eq!(balances[0].locked.as_decimal(), dec!(0));
        assert_eq!(balances[0].free.as_decimal(), dec!(2.5));
        assert_eq!(balances[1].total.as_decimal(), dec!(1000));
        assert_eq!(balances[1].locked.as_decimal(), dec!(0));
        assert_eq!(balances[1].free.as_decimal(), dec!(1000));
    }

    #[rstest]
    fn test_parse_subaccount_aggregates_requirements_and_keeps_health_in_info() {
        // Requirements aggregate position IM with open-order margin; the
        // signed net health values must not appear as requirements
        let mut subaccount = sample_subaccount();
        subaccount.positions_initial_margin = dec!(-350);
        subaccount.positions_maintenance_margin = dec!(-175);
        subaccount.open_orders_margin = dec!(-40);
        subaccount.initial_margin = dec!(650);
        subaccount.maintenance_margin = dec!(825);

        let (balances, margins, info) = parse_derive_subaccount_to_balances(&subaccount).unwrap();
        assert_eq!(balances[0].locked.as_decimal(), dec!(0));
        assert_eq!(margins.len(), 1);
        assert_eq!(margins[0].initial.as_decimal(), dec!(390));
        assert_eq!(margins[0].maintenance.as_decimal(), dec!(175));
        assert_eq!(
            info.get("positions_initial_margin"),
            Some(&serde_json::json!("-350")),
        );
        assert_eq!(
            info.get("positions_maintenance_margin"),
            Some(&serde_json::json!("-175")),
        );
        assert_eq!(
            info.get("open_orders_margin"),
            Some(&serde_json::json!("-40")),
        );
        assert_eq!(
            info.get("net_initial_margin"),
            Some(&serde_json::json!("650")),
        );
        assert_eq!(
            info.get("net_maintenance_margin"),
            Some(&serde_json::json!("825")),
        );
    }

    #[rstest]
    fn test_parse_subaccount_funded_positionless_fixture_reports_no_locked() {
        let (balances, margins, info) =
            parse_subaccount_fixture("common/http_subaccount_usdc.json");
        assert_eq!(balances.len(), 1);
        assert_eq!(balances[0].total.as_decimal(), dec!(1000));
        assert_eq!(balances[0].locked.as_decimal(), dec!(0));
        assert_eq!(balances[0].free.as_decimal(), dec!(1000));
        assert_eq!(margins.len(), 1);
        assert_eq!(margins[0].initial.as_decimal(), dec!(0));
        assert_eq!(margins[0].maintenance.as_decimal(), dec!(0));
        // Net health equals the collateral credit with no requirements,
        // matching observed mainnet responses for funded positionless accounts
        assert_eq!(
            info.get("net_initial_margin"),
            Some(&serde_json::json!("1000")),
        );
        assert_eq!(
            info.get("net_maintenance_margin"),
            Some(&serde_json::json!("1000")),
        );
    }

    #[rstest]
    fn test_parse_subaccount_positions_margin_fixture_maps_requirements() {
        let (balances, margins, info) =
            parse_subaccount_fixture("common/http_subaccount_positions_margin.json");
        assert_eq!(balances[0].locked.as_decimal(), dec!(0));
        assert_eq!(margins[0].initial.as_decimal(), dec!(350));
        assert_eq!(margins[0].maintenance.as_decimal(), dec!(175));
        assert_eq!(
            info.get("net_initial_margin"),
            Some(&serde_json::json!("655")),
        );
        assert_eq!(
            info.get("net_maintenance_margin"),
            Some(&serde_json::json!("830")),
        );
    }

    #[rstest]
    fn test_parse_subaccount_open_orders_margin_fixture_maps_reservation() {
        let (_, margins, info) =
            parse_subaccount_fixture("common/http_subaccount_open_orders_margin.json");
        assert_eq!(margins[0].initial.as_decimal(), dec!(40));
        assert_eq!(margins[0].maintenance.as_decimal(), dec!(0));
        assert_eq!(
            info.get("open_orders_margin"),
            Some(&serde_json::json!("-40")),
        );
    }

    #[rstest]
    fn test_parse_subaccount_negative_health_fixture_preserves_signs() {
        let (balances, margins, info) =
            parse_subaccount_fixture("common/http_subaccount_negative_health.json");
        assert_eq!(balances[0].locked.as_decimal(), dec!(0));
        assert_eq!(margins[0].initial.as_decimal(), dec!(1095));
        assert_eq!(margins[0].maintenance.as_decimal(), dec!(1025));
        assert_eq!(
            info.get("net_initial_margin"),
            Some(&serde_json::json!("-50")),
        );
        assert_eq!(
            info.get("net_maintenance_margin"),
            Some(&serde_json::json!("-20")),
        );
        assert_eq!(
            info.get("is_under_liquidation"),
            Some(&serde_json::json!(true)),
        );
    }

    #[rstest]
    fn test_parse_subaccount_with_no_collateral_emits_margins_only() {
        let mut subaccount = sample_subaccount();
        subaccount.collaterals = vec![];
        subaccount.positions_initial_margin = dec!(-350);
        subaccount.positions_maintenance_margin = dec!(-175);

        let (balances, margins, _) = parse_derive_subaccount_to_balances(&subaccount).unwrap();
        assert!(balances.is_empty());
        assert_eq!(margins.len(), 1);
        assert_eq!(margins[0].initial.as_decimal(), dec!(350));
        assert_eq!(margins[0].maintenance.as_decimal(), dec!(175));
    }

    #[rstest]
    fn test_parse_subaccount_errors_on_unrepresentable_amount() {
        let mut subaccount = sample_subaccount();
        subaccount.collaterals[0].amount = Decimal::MAX;

        let err = parse_derive_subaccount_to_balances(&subaccount)
            .expect_err("out-of-range collateral amount must error instead of panicking");
        assert!(
            err.to_string().contains("collateral balance"),
            "unexpected error: {err}",
        );
    }

    #[rstest]
    fn test_parse_subaccount_v3_preserves_exact_collaterals_and_portfolio_risk() {
        let mut subaccount = sample_subaccount();
        subaccount.margin_type = "PM2-next".into();
        subaccount.manager_id = 57;
        subaccount.risk_universe_id = 19;
        subaccount.collaterals[0].amount = dec!(1.234567895);
        subaccount.initial_margin = dec!(-7.123456789123);
        subaccount.maintenance_margin = dec!(-8.234567891234);
        subaccount.positions_initial_margin = dec!(3.125);
        subaccount.open_orders_margin = dec!(-0.01);
        subaccount.positions_maintenance_margin = dec!(3.905);
        subaccount.positions_value = dec!(6.25);
        subaccount.mm_credits = dec!(0.123456789123);
        subaccount.projected_margin_change = dec!(-0.987654321987);
        let mut position = sample_position();
        position.amount = dec!(-2.125);
        position.initial_margin = dec!(400.123);
        position.maintenance_margin = dec!(300.234);
        subaccount.positions = vec![position];
        subaccount.vault_deposit_holds = vec![crate::http::models::DeriveVaultDepositHold {
            amount: dec!(0.000000000123456789),
            asset_name: "ETH".into(),
            currency: "ETH".into(),
            vault_id: 123,
        }];

        let (balances, margins, info) = parse_derive_subaccount_to_balances(&subaccount).unwrap();

        assert_eq!(
            balances,
            vec![
                AccountBalance::from_total_and_locked(
                    dec!(1.23456790),
                    Decimal::ZERO,
                    Currency::USDC(),
                )
                .unwrap()
            ]
        );
        assert_eq!(
            margins,
            vec![MarginBalance::new(
                Money::from_decimal(dec!(3.14), Currency::USD()).unwrap(),
                Money::from_decimal(dec!(2.34), Currency::USD()).unwrap(),
                None,
            )]
        );
        assert_eq!(info, serde_json::from_value(serde_json::json!({
            "currency": ["ETH", "BTC"],
            "margin_type": "PM2-next",
            "manager_id": 57,
            "risk_universe_id": 19,
            "mm_credits": "0.123456789123",
            "projected_margin_change": "-0.987654321987",
            "vault_deposit_holds": [{"amount": "0.000000000123456789", "asset_name": "ETH", "currency": "ETH", "vault_id": 123}],
            "net_initial_margin": "-7.123456789123",
            "net_maintenance_margin": "-8.234567891234",
            "positions_initial_margin": "3.125",
            "positions_maintenance_margin": "3.905",
            "positions_value": "6.25",
            "open_orders_margin": "-0.01",
            "is_under_liquidation": false,
            "collaterals": [{"amount": "1.234567895", "asset_name": "USDC", "asset_type": "erc20", "cumulative_interest": "0", "currency": "USDC", "initial_margin": "100", "maintenance_margin": "50", "mark_price": "1", "mark_value": "1000", "pending_interest": "0"}],
        })).unwrap());
    }

    #[rstest]
    #[case(dec!(0.000000001), dec!(0))]
    #[case(dec!(0.123456785), dec!(0.12345678))]
    fn test_parse_subaccount_retains_collateral_below_native_precision(
        #[case] amount: Decimal,
        #[case] rounded: Decimal,
    ) {
        let mut subaccount = sample_subaccount();
        subaccount.collaterals[0].amount = amount;

        let (balances, _, info) = parse_derive_subaccount_to_balances(&subaccount).unwrap();

        assert_eq!(balances[0].total.as_decimal(), rounded);
        assert_eq!(balances[0].free.as_decimal(), rounded);
        assert_eq!(balances[0].locked.as_decimal(), Decimal::ZERO);
        assert_eq!(info["collaterals"][0]["amount"], amount.to_string());
    }

    #[rstest]
    fn test_parse_subaccount_rejects_failed_snapshot() {
        let mut subaccount = sample_subaccount();
        subaccount.failed_to_fetch = true;

        let err = parse_derive_subaccount_to_balances(&subaccount).unwrap_err();

        assert_eq!(err.to_string(), "Derive subaccount snapshot is incomplete");
    }

    #[rstest]
    #[case(Decimal::MAX, -Decimal::ONE, Decimal::ZERO, Decimal::ZERO, "initial")]
    #[case(Decimal::ZERO, Decimal::MIN, -Decimal::ONE, Decimal::ZERO, "initial")]
    #[case(Decimal::MAX, Decimal::ZERO, Decimal::ZERO, -Decimal::ONE, "maintenance")]
    fn test_parse_subaccount_rejects_requirement_overflow(
        #[case] value: Decimal,
        #[case] initial: Decimal,
        #[case] orders: Decimal,
        #[case] maintenance: Decimal,
        #[case] field: &str,
    ) {
        let mut subaccount = sample_subaccount();
        subaccount.positions_value = value;
        subaccount.positions_initial_margin = initial;
        subaccount.open_orders_margin = orders;
        subaccount.positions_maintenance_margin = maintenance;

        let err = parse_derive_subaccount_to_balances(&subaccount).unwrap_err();

        assert_eq!(
            err.to_string(),
            format!("Derive {field} margin requirement exceeds Decimal range")
        );
    }

    #[rstest]
    #[case(dec!(0.0000000000000000001))]
    #[case(Decimal::MAX)]
    fn test_parse_subaccount_rejects_unrepresentable_embedded_position(#[case] amount: Decimal) {
        let mut subaccount = sample_subaccount();
        let mut position = sample_position();
        position.amount = amount;
        subaccount.positions = vec![position];

        let expected = Quantity::from_decimal(amount).expect_err("unrepresentable test amount");
        let err = parse_derive_subaccount_to_balances(&subaccount).unwrap_err();

        assert_eq!(
            format!("{err:#}"),
            format!("invalid Derive position.amount: {expected}")
        );
    }

    #[rstest]
    #[case(dec!(0.0001))]
    #[case(dec!(-2.1234))]
    fn test_parse_position_rejects_rounding_at_instrument_precision(#[case] amount: Decimal) {
        let mut position = sample_position();
        position.amount = amount;

        let err = parse_derive_position_to_report_with_precision(
            &position,
            AccountId::new("DERIVE-001"),
            Some(3),
            UnixNanos::from(3),
        )
        .unwrap_err();

        assert!(err.to_string().contains("cannot be represented exactly"));
    }

    #[rstest]
    #[case(include_str!("../../test_data/common/http_subaccount_pm2_open_orders.json"), dec!(44.84), dec!(0), "0", "0", "0", "-44.842739996872")]
    #[case(include_str!("../../test_data/common/http_subaccount_pm2_positions.json"), dec!(44.95), dec!(34.81), "0.000318767368", "-44.951666892242", "-34.805466288178", "0")]
    fn test_parse_subaccount_live_pm2_requirements(
        #[case] fixture: &str,
        #[case] initial: Decimal,
        #[case] maintenance: Decimal,
        #[case] value: &str,
        #[case] contribution_initial: &str,
        #[case] contribution_maintenance: &str,
        #[case] orders: &str,
    ) {
        let body: Value = serde_json::from_str(fixture).unwrap();
        let subaccount: DeriveSubaccount = serde_json::from_str(fixture).unwrap();
        let (balances, margins, info) = parse_derive_subaccount_to_balances(&subaccount).unwrap();

        let total = if orders == "0" {
            dec!(45.89433238)
        } else {
            dec!(46.00000318)
        };

        let mut expected = Params::new();
        for name in [
            "collaterals",
            "currency",
            "margin_type",
            "manager_id",
            "risk_universe_id",
            "mm_credits",
            "projected_margin_change",
            "vault_deposit_holds",
            "positions_value",
            "positions_initial_margin",
            "positions_maintenance_margin",
            "open_orders_margin",
            "is_under_liquidation",
        ] {
            expected.insert(name.to_string(), body[name].clone());
        }

        expected.insert(
            "net_initial_margin".to_string(),
            body["initial_margin"].clone(),
        );
        expected.insert(
            "net_maintenance_margin".to_string(),
            body["maintenance_margin"].clone(),
        );

        assert_eq!(
            balances,
            vec![
                AccountBalance::from_total_and_locked(total, Decimal::ZERO, Currency::USDC())
                    .unwrap()
            ]
        );
        assert_eq!(
            margins,
            vec![MarginBalance::new(
                Money::from_decimal(initial, Currency::USD()).unwrap(),
                Money::from_decimal(maintenance, Currency::USD()).unwrap(),
                None
            )]
        );
        assert_eq!(info, expected);
        assert_eq!(info["positions_value"], value);
        assert_eq!(info["positions_initial_margin"], contribution_initial);
        assert_eq!(
            info["positions_maintenance_margin"],
            contribution_maintenance
        );
        assert_eq!(info["open_orders_margin"], orders);
        assert_eq!(info["margin_type"], "PM2");
        assert_eq!(info["manager_id"], 5);
        assert_eq!(info["risk_universe_id"], 1);
    }

    #[rstest]
    fn test_parse_subaccount_current_pm2_fixture() {
        let (balances, margins, info) = parse_subaccount_fixture("common/http_subaccount_pm2.json");

        assert_eq!(
            balances,
            vec![
                AccountBalance::from_total_and_locked(dec!(6), Decimal::ZERO, Currency::USDC())
                    .unwrap()
            ]
        );
        assert_eq!(
            margins,
            vec![MarginBalance::new(
                Money::from_decimal(Decimal::ZERO, Currency::USD()).unwrap(),
                Money::from_decimal(Decimal::ZERO, Currency::USD()).unwrap(),
                None
            )]
        );
        assert_eq!(info["currency"], serde_json::json!(["BTC", "ETH"]));
        assert_eq!(info["margin_type"], "PM2");
        assert_eq!(info["manager_id"], 5);
        assert_eq!(info["risk_universe_id"], 1);
        assert_eq!(info["net_initial_margin"], "6.000000127922");
        assert_eq!(info["net_maintenance_margin"], "6.000000127922");
        assert_eq!(info["collaterals"][0]["pending_interest"], "0.000000127922");
    }

    fn parse_subaccount_fixture(
        filename: &str,
    ) -> (Vec<AccountBalance>, Vec<MarginBalance>, Params) {
        let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("test_data")
            .join(filename);
        let content =
            std::fs::read_to_string(&path).unwrap_or_else(|_| panic!("failed to read {filename}"));
        let subaccount: DeriveSubaccount = serde_json::from_str(&content)
            .unwrap_or_else(|e| panic!("failed to parse {filename}: {e}"));
        parse_derive_subaccount_to_balances(&subaccount).expect("subaccount maps")
    }

    fn sample_subaccount() -> DeriveSubaccount {
        DeriveSubaccount {
            collaterals: vec![DeriveCollateral {
                amount: dec!(1000),
                asset_name: "USDC".into(),
                asset_type: DeriveAssetType::Erc20,
                cumulative_interest: dec!(0),
                currency: "USDC".into(),
                initial_margin: dec!(100),
                maintenance_margin: dec!(50),
                mark_price: dec!(1),
                mark_value: dec!(1000),
                pending_interest: dec!(0),
            }],
            collaterals_initial_margin: dec!(100),
            collaterals_maintenance_margin: dec!(50),
            collaterals_value: dec!(1000),
            currency: vec!["ETH".into(), "BTC".into()],
            failed_to_fetch: false,
            initial_margin: dec!(100),
            is_under_liquidation: false,
            label: None,
            maintenance_margin: dec!(50),
            manager_id: 3,
            margin_type: "SM".into(),
            mm_credits: dec!(0),
            open_orders: vec![],
            open_orders_margin: dec!(0),
            positions: vec![],
            positions_initial_margin: dec!(0),
            positions_maintenance_margin: dec!(0),
            positions_value: dec!(0),
            projected_margin_change: dec!(0),
            risk_universe_id: 1,
            subaccount_id: 30769,
            subaccount_value: dec!(1000),
            vault_deposit_holds: vec![],
        }
    }
}