nautilus-execution 0.67.0

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

//! Shared reconciliation value types.

use indexmap::{IndexMap, IndexSet};
use nautilus_model::{
    enums::{AvgPxReconciliation, OrderSide, PositionSide},
    identifiers::{AccountId, InstrumentId, TradeId, VenueOrderId},
    reports::{FillReport, OrderStatusReport},
};
use rust_decimal::Decimal;

/// Immutable snapshot of fill data for position simulation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) struct FillSnapshot {
    /// The venue order ID.
    pub venue_order_id: VenueOrderId,
    /// The order side (BUY or SELL).
    pub side: OrderSide,
    /// The fill quantity.
    pub qty: Decimal,
    /// The fill price.
    pub px: Decimal,
    /// The event timestamp (nanoseconds).
    pub ts_event: u64,
}

/// Represents a position snapshot from the venue.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) struct VenuePositionSnapshot {
    /// The position side (Long, Short, or Flat).
    pub side: PositionSide,
    /// The position quantity (always positive, even for Short).
    pub qty: Decimal,
    /// The average entry price (can be zero for Flat positions).
    pub avg_px: Decimal,
    /// How reconciliation may use the average entry price.
    pub avg_px_reconciliation: AvgPxReconciliation,
    /// The decimal places the venue kept for the average entry price, if it rounds or truncates.
    pub avg_px_precision: Option<u8>,
}

impl VenuePositionSnapshot {
    /// Returns the quantity signed by position side.
    pub(super) fn signed_qty(&self) -> Decimal {
        match self.side {
            PositionSide::Long => self.qty,
            PositionSide::Short => -self.qty,
            PositionSide::Flat => Decimal::ZERO,
        }
    }
}

/// Result of the fill adjustment process.
#[derive(Debug, Clone, PartialEq)]
pub(super) enum FillAdjustmentResult {
    /// No adjustment needed - return fills unchanged.
    NoAdjustment,
    /// Add synthetic opening fill to oldest lifecycle.
    AddSyntheticOpening {
        /// The synthetic fill to add at the beginning.
        synthetic_fill: FillSnapshot,
        /// All existing fills to keep.
        existing_fills: Vec<FillSnapshot>,
    },
    /// Replace entire current lifecycle with single synthetic fill.
    ReplaceCurrentLifecycle {
        /// The single synthetic fill representing the entire position.
        synthetic_fill: FillSnapshot,
    },
    /// Filter fills to current lifecycle only (after last zero-crossing).
    FilterToCurrentLifecycle {
        /// Timestamp of the last zero-crossing.
        last_zero_crossing_ts: u64,
        /// Fills from current lifecycle.
        current_lifecycle_fills: Vec<FillSnapshot>,
    },
}

impl FillSnapshot {
    /// Create a new fill snapshot.
    #[must_use]
    pub(super) fn new(
        venue_order_id: VenueOrderId,
        side: OrderSide,
        qty: Decimal,
        px: Decimal,
        ts_event: u64,
    ) -> Self {
        Self {
            venue_order_id,
            side,
            qty,
            px,
            ts_event,
        }
    }

    /// Return signed direction multiplier: +1 for BUY, -1 for SELL.
    #[must_use]
    pub(super) fn direction(&self) -> i8 {
        match self.side {
            OrderSide::Buy => 1,
            OrderSide::Sell => -1,
        }
    }
}

/// Result of processing fill reports for reconciliation.
#[derive(Debug, Clone)]
pub struct ReconciliationResult {
    /// Order status reports keyed by venue order ID.
    pub orders: IndexMap<VenueOrderId, OrderStatusReport>,
    /// Fill reports keyed by venue order ID.
    pub fills: IndexMap<VenueOrderId, Vec<FillReport>>,
    /// Orders whose fills recover order state only because synthetic fills replace their economics.
    pub order_only_ids: IndexSet<VenueOrderId>,
    /// Fills that recover order state only because they precede the current position lifecycle.
    pub order_only_fill_keys: IndexSet<(AccountId, InstrumentId, TradeId)>,
}