hypercall/rsm/

expiry_manager.rs

//! Expiry and settlement management.
//!
//! `ExpiryManager` owns the expiry schedules and implements the two-phase
//! settlement process: transition to pending → settle when TWAP is available.
//! The canonical `expired_instruments` map lives in `EngineCtx`, and
//! `reference_prices` lives in `EngineDeps` to avoid duplication.

use crate::observability::record_settlement;
use crate::rsm::apply::{
    ApplyOutput, ExpiryEffect, ExpirySettlementIntent, TickExpiryContext, TickExpiryDueGroup,
    TickExpiryPendingGroup, TickExpiryPmSettlement, TickExpirySettlementPrice,
    TickExpiryWalletMarginMode,
};
use crate::rsm::engine_deps::{EngineCtx, EngineDeps};
use crate::rsm::margin_manager::{expiry_date_to_timestamp, MarginManager};
use crate::rsm::margin_mode::MarginMode;
use crate::shared::order_types::ParsedSymbol;
use crate::shared::traits::MarkPriceOracle;
use hypercall_db::{InstrumentReader, InstrumentWriter, OrderWriter, TierReader};
use hypercall_db_diesel::DatabaseHandler;
use hypercall_engine::command::PmSettlementEventKey;
use hypercall_margin::portfolio::{
    classify_liquidity_gap, PmAccountSettlementFacts, PmLiquidityClassification,
    PmSettlementObligation,
};
use hypercall_settlement::{
    self, build_position_expired_message, plan_position_settlements,
    OptionType as SettlementOptionType, SettlementInstrument, SettlementPosition,
};
use hypercall_types::WalletAddress;
use hypercall_types::{
    EngineMessage, MarketUpdateMessage, MarketUpdateStatus, OptionType as MessageOptionType,
    OrderInfo, OrderUpdateMessage, OrderUpdateStatus,
};
use rust_decimal::Decimal;
use rust_decimal_macros::dec;
use sha2::{Digest, Sha256};
use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
use tracing::{debug, error, info, warn};

/// Manages instrument expiry schedules and settlement.
///
/// Owns the expiry schedules. The canonical `expired_instruments` map lives in
/// `EngineCtx`, and `reference_prices` lives in `EngineDeps` to avoid duplication.
pub struct ExpiryManager {
    /// expiry_timestamp → list of symbols
    pub expiry_schedules: BTreeMap<u64, Vec<String>>,
}

#[derive(Debug, Clone, Copy, Default)]
struct ExpireInstrumentApplyResult {
    settled: bool,
    blocked: bool,
}

fn to_settlement_option_type(ot: &crate::types::OptionType) -> SettlementOptionType {
    match ot {
        crate::types::OptionType::Call => SettlementOptionType::Call,
        crate::types::OptionType::Put => SettlementOptionType::Put,
    }
}

fn expiry_cash_delta_for_margin_mode(
    margin_mode: MarginMode,
    settlement_value: Decimal,
    net_pnl: Decimal,
) -> Decimal {
    hypercall_settlement::settlement_cash_delta_for_margin_mode(
        margin_mode,
        settlement_value,
        Some(net_pnl),
        "expiry apply intent",
    )
    .expect("net_pnl is present for expiry apply intent")
}

fn simulated_pm_liquid_after_settlement(
    current_liquid: Decimal,
    settlement_cash_delta: Decimal,
    pool_front_usdc: Decimal,
) -> Decimal {
    (current_liquid + settlement_cash_delta + pool_front_usdc).max(Decimal::ZERO)
}

fn initial_pm_liquid_with_precredit(balance: Decimal, precredited_cash: Decimal) -> Decimal {
    (balance + precredited_cash).max(Decimal::ZERO)
}

fn effective_pm_cash_delta_after_precredit(
    settlement_cash_delta: Decimal,
    remaining_precredited_cash: &mut Decimal,
) -> Decimal {
    if settlement_cash_delta <= Decimal::ZERO {
        return settlement_cash_delta;
    }

    let applied_precredit = (*remaining_precredited_cash).min(settlement_cash_delta);
    *remaining_precredited_cash -= applied_precredit;
    settlement_cash_delta - applied_precredit
}

fn simulated_recoverable_after_pm_front(
    current_recoverable: Decimal,
    pool_front_usdc: Decimal,
) -> Decimal {
    (current_recoverable - pool_front_usdc).max(Decimal::ZERO)
}

fn apply_engine_balance_update(
    ctx: &mut EngineCtx,
    output: Option<&mut ApplyOutput>,
    wallet: WalletAddress,
    delta: Decimal,
    reason: hypercall_types::BalanceUpdateReason,
    reference_id: Option<String>,
    timestamp_ms: u64,
) -> Decimal {
    let balance_after = ctx.balance_ledger.balance(&wallet) + delta;
    let update = hypercall_types::BalanceUpdate {
        balance_update_seq: ctx.balance_ledger.next_balance_update_seq(),
        wallet,
        delta,
        balance_after,
        reason,
        reference_id,
        source_command_id: None,
        timestamp_ms,
    };
    ctx.balance_ledger
        .apply_balance_update(&update)
        .unwrap_or_else(|error| {
            panic!(
                "CRITICAL: failed to apply engine balance update during expiry: {}",
                error
            )
        });
    if let Some(output) = output {
        output.balance_updates.push(update);
    }
    balance_after
}

fn parse_settlement_instrument_or_panic(symbol: &str, context: &str) -> SettlementInstrument {
    SettlementInstrument::from_symbol(symbol).unwrap_or_else(|e| {
        panic!(
            "CRITICAL_FAILURE: failed to parse canonical settlement symbol for {}: {} ({})",
            context, symbol, e
        )
    })
}

fn digest_pm_settlement_inputs(
    event_key: &PmSettlementEventKey,
    obligation: &PmSettlementObligation,
    liquid_usdc: Decimal,
    pm_facts: Option<&PmAccountSettlementFacts>,
    pool_snapshot: Option<&hypercall_margin::portfolio::PmSettlementPoolSnapshot>,
    policy_version: u32,
    unavailable_reason: Option<&str>,
) -> Result<String, String> {
    let payload = serde_json::json!({
        "event_key": event_key,
        "obligation": obligation,
        "liquid_usdc": liquid_usdc,
        "pm_facts": pm_facts,
        "pool_snapshot": pool_snapshot,
        "policy_version": policy_version,
        "unavailable_reason": unavailable_reason,
    });
    let bytes = serde_json::to_vec(&payload)
        .map_err(|error| format!("failed to serialize PM settlement facts digest: {error}"))?;
    let mut hasher = Sha256::new();
    hasher.update(bytes);
    Ok(format!("sha256:{}", hex::encode(hasher.finalize())))
}

fn deterministic_pm_settlement_request_id(event_key: &PmSettlementEventKey) -> uuid::Uuid {
    uuid::Uuid::new_v5(
        &uuid::Uuid::NAMESPACE_OID,
        format!(
            "pm-settlement:{}:{}:{}:{}:{}",
            event_key.wallet,
            event_key.market_id,
            event_key.expiry_ts_ms,
            event_key.margin_mode,
            event_key.settlement_event_sequence
        )
        .as_bytes(),
    )
}

fn margin_mode_for_settlement(
    ctx: &EngineCtx,
    wallet: WalletAddress,
) -> Result<MarginMode, String> {
    if let Some(margin_mode) = ctx.deps.wallet_margin_modes.get(&wallet).copied() {
        return Ok(margin_mode);
    }

    let Some(handler) = ctx.db.as_ref() else {
        return Ok(MarginMode::Standard);
    };
    let margin_mode = handler.get_margin_mode_sync(&wallet).map_err(|error| {
        format!(
            "missing durable margin mode for settlement wallet {}: {}",
            wallet, error
        )
    })?;
    Ok(margin_mode)
}

struct SettlementApplyInput<'a> {
    wallet: WalletAddress,
    symbol: &'a str,
    option_type: SettlementOptionType,
    strike: Decimal,
    reference_price: Decimal,
    position_size: Decimal,
    entry_price: Decimal,
    margin_mode: MarginMode,
    timestamp_ms: u64,
}

struct SettlementApplyIntent {
    message: hypercall_types::PositionExpiredMessage,
    cash_delta: Decimal,
}

fn build_settlement_apply_intent(input: SettlementApplyInput<'_>) -> SettlementApplyIntent {
    let instrument = parse_settlement_instrument_or_panic(input.symbol, "settlement apply intent");
    let position = SettlementPosition {
        wallet: input.wallet,
        position_size: input.position_size,
        entry_price: input.entry_price,
    };
    let settlement =
        hypercall_settlement::settle_position(&hypercall_settlement::SettlementInput {
            option_type: input.option_type,
            strike: input.strike,
            reference_price: input.reference_price,
            position_size: input.position_size,
            entry_price: input.entry_price,
        });
    let cash_delta = expiry_cash_delta_for_margin_mode(
        input.margin_mode,
        settlement.settlement_value,
        settlement.net_pnl,
    );

    SettlementApplyIntent {
        message: build_position_expired_message(
            &instrument,
            &position,
            &settlement,
            input.margin_mode,
            input.timestamp_ms,
        ),
        cash_delta,
    }
}

impl Default for ExpiryManager {
    fn default() -> Self {
        Self::new()
    }
}

impl ExpiryManager {
    /// Create an empty `ExpiryManager`.
    pub fn new() -> Self {
        Self {
            expiry_schedules: BTreeMap::new(),
        }
    }

    // ===== Query helpers =====

    /// Check if an instrument is expired using canonical orderbook expiry.
    pub fn is_instrument_expired(
        &self,
        symbol: &str,
        orderbooks: &HashMap<String, hypercall_engine::OrderBook>,
    ) -> bool {
        if !orderbooks.contains_key(symbol) {
            return false;
        };
        let parsed = ParsedSymbol::from_symbol(symbol).unwrap_or_else(|error| {
            panic!(
                "STATE_CORRUPTION: orderbook symbol {} cannot be parsed for expiry validation: {}",
                symbol, error
            )
        });
        let expiry_ts = expiry_date_to_timestamp(&parsed.underlying, parsed.expiry);
        if expiry_ts == 0 {
            panic!(
                "STATE_CORRUPTION: orderbook symbol {} has invalid expiry code {}",
                symbol, parsed.expiry
            );
        }
        let now = crate::shared::clock::unix_now_secs();
        now >= expiry_ts
    }

    /// Schedule an expiry for a symbol.
    pub fn schedule_expiry(&mut self, symbol: String, expiry_timestamp: u64) {
        self.expiry_schedules
            .entry(expiry_timestamp)
            .or_default()
            .push(symbol);
    }

    // ===== Settlement price =====

    /// Get settlement price from oracle for a specific expiry.
    pub async fn get_settlement_price(
        &self,
        deps: &EngineDeps,
        underlying: &str,
        expiry_ts: i64,
    ) -> Option<Decimal> {
        if let Some(oracle) = deps.mark_price_oracles.get(underlying) {
            if let Some(price) = oracle.get_settlement_price(expiry_ts).await {
                match Decimal::from_f64_retain(price) {
                    Some(decimal_price) => {
                        debug!(
                            "Got settlement price from oracle for {} expiry {}: {}",
                            underlying, expiry_ts, decimal_price
                        );
                        return Some(decimal_price);
                    }
                    None => {
                        error!(
                            "Invalid oracle settlement price for {} expiry {}: {} - cannot convert to Decimal",
                            underlying, expiry_ts, price
                        );
                        return None;
                    }
                }
            }
        }

        if let Some(&price) = deps.reference_prices.get(underlying) {
            match Decimal::from_f64_retain(price) {
                Some(decimal_price) => {
                    debug!(
                        "Using test reference price for {} expiry {}: {}",
                        underlying, expiry_ts, decimal_price
                    );
                    return Some(decimal_price);
                }
                None => {
                    error!(
                        "Invalid reference price for {} expiry {}: {} - cannot convert to Decimal",
                        underlying, expiry_ts, price
                    );
                    return None;
                }
            }
        }

        None
    }

    // ===== Settlement processing =====

    /// Transition instruments to EXPIRED_PENDING_PRICE status.
    ///
    /// Blocks new orders, cancels open orders, removes orderbooks.
    pub fn transition_to_pending_settlement(
        &mut self,
        symbols: &[String],
        now_ms: u64,
        ctx: &mut EngineCtx,
    ) {
        if symbols.is_empty() {
            return;
        }

        let timestamp = now_ms;
        let mut total_cancelled = 0;
        let mut cancelled_order_ids: Vec<i64> = Vec::new();

        for symbol in symbols {
            ctx.expired_instruments.insert(symbol.clone(), true);

            if let Some(orderbook) = ctx.orderbooks.get(symbol) {
                let open_orders = orderbook.get_all_orders();
                let order_count = open_orders.len();

                let underlying =
                    parse_settlement_instrument_or_panic(symbol, "expiry transition").underlying;

                for r in open_orders {
                    let (order_id, price, size, side, wallet) =
                        (r.order_id, r.price, r.quantity, r.side, r.wallet);
                    let cancel_message = OrderUpdateMessage {
                        timestamp,
                        info: OrderInfo {
                            symbol: symbol.clone(),
                            price,
                            size,
                            side,
                            tif: hypercall_types::TimeInForce::GTC,
                            client_id: None,
                            order_id: Some(order_id),
                            is_perp: false,
                            underlying: Some(underlying.clone()),
                            reduce_only: None,
                            nonce: None,
                            signature: None,
                            mmp_enabled: false,
                            builder_code_address: None,
                        },
                        status: OrderUpdateStatus::Canceled,
                        reason: Some("Instrument expired".to_string()),
                        filled_size: dec!(0),
                        order_id: Some(order_id),
                        wallet_address: wallet,
                        mmp_triggered: false,
                        request_id: None,
                    };

                    // Remove from order index so the engine snapshot no longer
                    // reports these as open orders.  Without this, the /orders
                    // API continues to serve them and users see un-cancellable
                    // ghost orders on expired instruments (CALL-553).
                    ctx.order_index.remove_order(&wallet, order_id);

                    cancelled_order_ids.push(order_id as i64);

                    ctx.deps
                        .event_sender
                        .send(EngineMessage::OrderUpdate(cancel_message))
                        .unwrap_or_else(|e| {
                            panic!(
                                "CRITICAL_FAILURE: Failed to send OrderUpdate (cancel) for order {} on symbol {}: {}. \
                                 Order cancellation event lost during expiry. Restart required.",
                                order_id, symbol, e
                            )
                        });
                }

                total_cancelled += order_count;
            }

            ctx.orderbooks.remove(symbol);
        }

        if let Some(handler) = ctx.db.as_ref() {
            if let Err(e) = handler.transition_active_instruments_to_expired_pending_sync(symbols) {
                panic!(
                    "CRITICAL_FAILURE: Failed to update instrument status to EXPIRED_PENDING_PRICE for {:?}: {}. \
                     Memory state shows instruments as expired but database disagrees. Restart required.",
                    symbols, e
                );
            }

            // Persist cancel status to order_infos so the DB reflects
            // the in-memory state. Without this, settlement cancels go
            // through the EventBus (WS delivery) but bypass the journal
            // batcher, leaving order_infos with stale OPEN/ACKED status.
            if !cancelled_order_ids.is_empty() {
                for chunk in cancelled_order_ids.chunks(5000) {
                    if let Err(e) =
                        handler.batch_cancel_orders_for_settlement_sync(chunk, now_ms as i64)
                    {
                        error!(
                            order_count = chunk.len(),
                            "Failed to persist settlement order cancels to order_infos: {}. \
                             Orders are cancelled in-memory but DB still shows them as open. \
                             Will appear as orphaned orders in integrity checks.",
                            e
                        );
                    }
                }
            }

            // Defensive cleanup: cancel any non-terminal order_infos rows on
            // these symbols that were NOT in the orderbook. This catches orders
            // whose cancel was lost across restarts (journal archived before
            // materialization). Without this, order_infos keeps stale OPEN
            // status and the orphaned-settlement-orders canary fires (CALL-1066).
            let symbol_list: Vec<String> = symbols.to_vec();
            match handler.cancel_orphaned_orders_by_symbols_sync(&symbol_list) {
                Ok(0) => {}
                Ok(n) => {
                    warn!(
                        "Settlement defensive cleanup: cancelled {} orphaned order_infos rows \
                         on {} settling instruments (these were not in the orderbook)",
                        n,
                        symbols.len()
                    );
                }
                Err(e) => {
                    error!(
                        "Failed settlement defensive cleanup for {:?}: {}. \
                         Orphaned orders may remain in order_infos.",
                        symbols, e
                    );
                }
            }
        }

        info!(
            "Transitioned {} instruments to EXPIRED_PENDING_PRICE, cancelled {} orders",
            symbols.len(),
            total_cancelled
        );
    }

    /// Update instrument status in database.
    pub fn update_instrument_status(
        &self,
        symbols: &[String],
        status: &str,
        db: Option<&DatabaseHandler>,
    ) {
        if symbols.is_empty() {
            return;
        }
        if let Some(handler) = db {
            let update_result = if status == "EXPIRED_PENDING_PRICE" {
                handler.transition_active_instruments_to_expired_pending_sync(symbols)
            } else {
                handler.update_instrument_status_sync(symbols, status)
            };
            if let Err(e) = update_result {
                panic!(
                    "CRITICAL_FAILURE: Failed to update instrument status to {} for {:?}: {}. \
                     Memory state and database are now inconsistent. Restart required.",
                    status, symbols, e
                );
            }
        }
        debug!("Updated {} instruments to status {}", symbols.len(), status);
    }

    /// Get all instruments pending settlement.
    pub fn get_pending_settlement_instruments(
        &self,
        db: Option<&DatabaseHandler>,
    ) -> Vec<(String, i64, Vec<String>)> {
        let Some(handler) = db else {
            return Vec::new();
        };

        let instruments = match handler.get_instruments_by_status_sync("EXPIRED_PENDING_PRICE") {
            Ok(instruments) => instruments,
            Err(e) => {
                error!("Failed to query pending settlement instruments: {}", e);
                return Vec::new();
            }
        };

        let mut grouped: HashMap<(String, u64), Vec<String>> = HashMap::new();
        for instrument in instruments {
            let parsed =
                parse_settlement_instrument_or_panic(&instrument.id, "pending settlement query");
            grouped
                .entry((parsed.underlying.clone(), parsed.expiry_ts as u64))
                .or_default()
                .push(instrument.id);
        }

        grouped
            .into_iter()
            .map(|((underlying, expiry_ts), symbols)| (underlying, expiry_ts as i64, symbols))
            .collect()
    }

    /// Prepare deterministic context for a TickExpiry command.
    ///
    /// This is the runtime side of the TickExpiry boundary. It may read DB
    /// state and settlement oracles; apply() must only consume the returned
    /// context.
    pub async fn prepare_tick_expiry_context(
        &self,
        now_ms: u64,
        ctx: &EngineCtx,
        margin_manager: &MarginManager,
    ) -> Result<TickExpiryContext, String> {
        let current_time = now_ms / 1000;
        let due_expiries = self.collect_due_expiries(current_time, ctx.db.as_ref())?;

        let pending_settlements: Vec<TickExpiryPendingGroup> = self
            .get_pending_settlement_instruments(ctx.db.as_ref())
            .into_iter()
            .map(|(underlying, expiry_ts, symbols)| TickExpiryPendingGroup {
                underlying,
                expiry_ts,
                symbols,
            })
            .collect();

        let mut price_keys: BTreeSet<(String, i64)> = BTreeSet::new();
        for group in &due_expiries {
            for symbol in &group.symbols {
                let parsed =
                    parse_settlement_instrument_or_panic(symbol, "tick expiry price lookup");
                price_keys.insert((parsed.underlying, group.expiry_ts));
            }
        }
        for group in &pending_settlements {
            price_keys.insert((group.underlying.clone(), group.expiry_ts));
        }

        let mut settlement_prices = Vec::new();
        for (underlying, expiry_ts) in &price_keys {
            if let Some(price) = self
                .get_settlement_price(&ctx.deps, underlying, *expiry_ts)
                .await
            {
                settlement_prices.push(TickExpirySettlementPrice {
                    underlying: underlying.clone(),
                    expiry_ts: *expiry_ts,
                    price,
                });
            }
        }

        let priced_symbols = Self::priced_symbols_for_context(
            &due_expiries,
            &pending_settlements,
            &settlement_prices,
        );

        let positions_requiring_margin_modes: Vec<(WalletAddress, String)> = ctx
            .engine_positions
            .iter()
            .filter_map(|((wallet, symbol), position)| {
                if priced_symbols.contains(symbol) && position.quantity != Decimal::ZERO {
                    Some((*wallet, symbol.clone()))
                } else {
                    None
                }
            })
            .collect();

        let mut margin_modes_by_wallet = BTreeMap::new();
        for (wallet, _symbol) in positions_requiring_margin_modes {
            let margin_mode =
                if let Some(margin_mode) = ctx.deps.wallet_margin_modes.get(&wallet).copied() {
                    margin_mode
                } else if let Some(handler) = ctx.db.as_ref() {
                    handler.get_margin_mode_sync(&wallet).map_err(|error| {
                        format!(
                            "failed to load margin mode for expiry settlement wallet {}: {}",
                            wallet, error
                        )
                    })?
                } else {
                    MarginMode::Standard
                };
            margin_modes_by_wallet.insert(wallet, margin_mode);
        }

        let margin_modes = margin_modes_by_wallet
            .into_iter()
            .map(|(wallet, margin_mode)| TickExpiryWalletMarginMode {
                pm_settlement_required: margin_mode == MarginMode::Portfolio
                    && ctx.deps.portfolio_margin_pool_enabled
                    && ctx
                        .deps
                        .portfolio_margin_settlement_allowlist
                        .contains(&wallet),
                wallet,
                margin_mode,
            })
            .collect::<Vec<_>>();
        let pm_settlements = self.prepare_pm_settlements(
            &due_expiries,
            &pending_settlements,
            &settlement_prices,
            &margin_modes,
            now_ms,
            ctx,
            margin_manager,
        )?;

        Ok(TickExpiryContext {
            due_expiries,
            pending_settlements,
            settlement_prices,
            margin_modes,
            pm_settlements,
        })
    }

    #[allow(clippy::too_many_arguments)]
    pub(crate) fn prepare_pm_settlements(
        &self,
        due_expiries: &[TickExpiryDueGroup],
        pending_settlements: &[TickExpiryPendingGroup],
        settlement_prices: &[TickExpirySettlementPrice],
        margin_modes: &[TickExpiryWalletMarginMode],
        now_ms: u64,
        ctx: &EngineCtx,
        margin_manager: &MarginManager,
    ) -> Result<Vec<TickExpiryPmSettlement>, String> {
        if !ctx.deps.portfolio_margin_pool_enabled
            || ctx.deps.portfolio_margin_settlement_allowlist.is_empty()
        {
            return Ok(Vec::new());
        }

        let margin_modes_by_wallet: HashMap<WalletAddress, MarginMode> = margin_modes
            .iter()
            .map(|mode| (mode.wallet, mode.margin_mode))
            .collect();
        let price_map: HashMap<(String, i64), Decimal> = settlement_prices
            .iter()
            .map(|price| ((price.underlying.clone(), price.expiry_ts), price.price))
            .collect();
        let mut symbol_expiries = Vec::new();
        let mut seen_symbols = HashSet::new();
        for group in due_expiries {
            for symbol in Self::ordered_due_group_symbols(group) {
                if seen_symbols.insert(symbol.clone()) {
                    symbol_expiries.push((symbol, group.expiry_ts));
                }
            }
        }
        for group in pending_settlements {
            for symbol in &group.symbols {
                if seen_symbols.insert(symbol.clone()) {
                    symbol_expiries.push((symbol.clone(), group.expiry_ts));
                }
            }
        }

        let mut precredited_positive_cash_by_wallet: HashMap<WalletAddress, Decimal> =
            HashMap::new();
        for (symbol, expiry_ts) in &symbol_expiries {
            let instrument =
                parse_settlement_instrument_or_panic(symbol, "PM settlement gain preparation");
            let Some(reference_price) = price_map
                .get(&(instrument.underlying.clone(), *expiry_ts))
                .copied()
            else {
                continue;
            };
            let mut positions = ctx
                .engine_positions
                .iter()
                .filter_map(|((wallet, position_symbol), position)| {
                    if position_symbol == symbol && position.quantity != Decimal::ZERO {
                        Some((*wallet, position.quantity, position.entry_price))
                    } else {
                        None
                    }
                })
                .collect::<Vec<_>>();
            positions.sort_by_key(|(wallet, _, _)| *wallet);

            for (wallet, quantity, entry_price) in positions {
                let margin_mode = margin_modes_by_wallet
                    .get(&wallet)
                    .copied()
                    .or_else(|| ctx.deps.wallet_margin_modes.get(&wallet).copied())
                    .unwrap_or(MarginMode::Standard);
                if margin_mode != MarginMode::Portfolio
                    || !ctx
                        .deps
                        .portfolio_margin_settlement_allowlist
                        .contains(&wallet)
                {
                    continue;
                }
                let settlements = plan_position_settlements(
                    &instrument,
                    reference_price,
                    &[SettlementPosition {
                        wallet,
                        position_size: quantity,
                        entry_price,
                    }],
                );
                let Some((_, settlement)) = settlements.into_iter().next() else {
                    continue;
                };
                let cash_delta = expiry_cash_delta_for_margin_mode(
                    MarginMode::Portfolio,
                    settlement.settlement_value,
                    settlement.net_pnl,
                );
                if cash_delta <= Decimal::ZERO {
                    continue;
                }
                let (_, _, _, unavailable_reason) = self.prepare_pm_settlement_fact_bundle(
                    wallet,
                    &instrument.underlying,
                    ctx.balance_ledger.balance(&wallet).max(Decimal::ZERO),
                    ctx.pm_settlement_state.pools.get(&instrument.underlying),
                    now_ms,
                    ctx,
                    margin_manager,
                );
                if unavailable_reason.is_none() {
                    *precredited_positive_cash_by_wallet
                        .entry(wallet)
                        .or_default() += cash_delta;
                }
            }
        }

        let mut remaining_precredited_cash_by_wallet = precredited_positive_cash_by_wallet.clone();
        let mut pm_settlements = Vec::new();
        let mut settlement_event_sequence = 0_u64;
        let mut available_liquid_by_wallet: HashMap<WalletAddress, Decimal> = HashMap::new();
        let mut recoverable_by_wallet: HashMap<WalletAddress, Decimal> = HashMap::new();
        let mut simulated_pools = ctx.pm_settlement_state.pools.clone();
        for (symbol, expiry_ts) in symbol_expiries {
            let instrument =
                parse_settlement_instrument_or_panic(&symbol, "PM settlement fact preparation");
            let Some(reference_price) = price_map
                .get(&(instrument.underlying.clone(), expiry_ts))
                .copied()
            else {
                continue;
            };

            let mut positions = ctx
                .engine_positions
                .iter()
                .filter_map(|((wallet, position_symbol), position)| {
                    if position_symbol == &symbol && position.quantity != Decimal::ZERO {
                        Some((*wallet, position.quantity, position.entry_price))
                    } else {
                        None
                    }
                })
                .collect::<Vec<_>>();
            positions.sort_by_key(|(wallet, _, _)| *wallet);

            for (wallet, quantity, entry_price) in positions {
                let margin_mode = margin_modes_by_wallet
                    .get(&wallet)
                    .copied()
                    .or_else(|| ctx.deps.wallet_margin_modes.get(&wallet).copied())
                    .unwrap_or(MarginMode::Standard);
                if margin_mode != MarginMode::Portfolio
                    || !ctx
                        .deps
                        .portfolio_margin_settlement_allowlist
                        .contains(&wallet)
                {
                    continue;
                }

                let settlements = plan_position_settlements(
                    &instrument,
                    reference_price,
                    &[SettlementPosition {
                        wallet,
                        position_size: quantity,
                        entry_price,
                    }],
                );
                let Some((_, settlement)) = settlements.into_iter().next() else {
                    continue;
                };
                let expiry_ts_ms = expiry_ts
                    .checked_mul(1000)
                    .ok_or_else(|| format!("expiry timestamp overflow for {symbol}"))?;
                let obligation = PmSettlementObligation {
                    wallet,
                    market_id: symbol.clone(),
                    expiry_ts_ms,
                    underlying: instrument.underlying.clone(),
                    net_pnl_usdc: settlement.net_pnl,
                    settlement_obligation_usdc: Decimal::ZERO.max(-settlement.net_pnl),
                };
                let liquid_usdc = *available_liquid_by_wallet.entry(wallet).or_insert_with(|| {
                    initial_pm_liquid_with_precredit(
                        ctx.balance_ledger.balance(&wallet),
                        precredited_positive_cash_by_wallet
                            .get(&wallet)
                            .copied()
                            .unwrap_or(Decimal::ZERO),
                    )
                });
                let event_key = PmSettlementEventKey {
                    wallet,
                    market_id: symbol.clone(),
                    expiry_ts_ms,
                    margin_mode: "portfolio".to_string(),
                    settlement_event_sequence,
                };
                settlement_event_sequence =
                    settlement_event_sequence.checked_add(1).ok_or_else(|| {
                        "PM settlement event sequence overflow during expiry preparation"
                            .to_string()
                    })?;
                let request_id = deterministic_pm_settlement_request_id(&event_key);
                let (mut pm_facts, pool_snapshot, policy_version, unavailable_reason) = self
                    .prepare_pm_settlement_fact_bundle(
                        wallet,
                        &instrument.underlying,
                        liquid_usdc,
                        simulated_pools.get(&instrument.underlying),
                        now_ms,
                        ctx,
                        margin_manager,
                    );
                if let Some(facts) = pm_facts.as_mut() {
                    let remaining_recoverable = recoverable_by_wallet
                        .entry(wallet)
                        .or_insert(facts.recoverable_collateral_usdc);
                    facts.recoverable_collateral_usdc = *remaining_recoverable;
                }
                let facts_digest = digest_pm_settlement_inputs(
                    &event_key,
                    &obligation,
                    liquid_usdc,
                    pm_facts.as_ref(),
                    pool_snapshot.as_ref(),
                    policy_version,
                    unavailable_reason.as_deref(),
                )?;
                let reserved_classification = match (
                    unavailable_reason.as_ref(),
                    pm_facts.as_ref(),
                    pool_snapshot.as_ref(),
                    simulated_pools.get(&instrument.underlying),
                ) {
                    (None, Some(facts), Some(snapshot), Some(pool)) => {
                        pool.config.as_ref().and_then(|config| {
                            classify_liquidity_gap(&obligation, facts, snapshot, config).ok()
                        })
                    }
                    _ => None,
                };
                if let Some(classification) = reserved_classification {
                    let planned_pool_front_usdc = if matches!(
                        classification,
                        PmLiquidityClassification::TimingBridge
                            | PmLiquidityClassification::SettlementDebt
                    ) {
                        (obligation.settlement_obligation_usdc - liquid_usdc).max(Decimal::ZERO)
                    } else {
                        Decimal::ZERO
                    };
                    if classification != PmLiquidityClassification::Unavailable {
                        if let Some(available) = available_liquid_by_wallet.get_mut(&wallet) {
                            let settlement_cash_delta = expiry_cash_delta_for_margin_mode(
                                MarginMode::Portfolio,
                                settlement.settlement_value,
                                settlement.net_pnl,
                            );
                            let effective_cash_delta = effective_pm_cash_delta_after_precredit(
                                settlement_cash_delta,
                                remaining_precredited_cash_by_wallet
                                    .entry(wallet)
                                    .or_default(),
                            );
                            *available = simulated_pm_liquid_after_settlement(
                                *available,
                                effective_cash_delta,
                                planned_pool_front_usdc,
                            );
                        }
                        if let Some(remaining_recoverable) = recoverable_by_wallet.get_mut(&wallet)
                        {
                            *remaining_recoverable = simulated_recoverable_after_pm_front(
                                *remaining_recoverable,
                                planned_pool_front_usdc,
                            );
                        }
                    }
                    if matches!(
                        classification,
                        PmLiquidityClassification::TimingBridge
                            | PmLiquidityClassification::SettlementDebt
                    ) {
                        if planned_pool_front_usdc > Decimal::ZERO {
                            if let Some(pool) = simulated_pools.get_mut(&instrument.underlying) {
                                pool.pool_available_usdc -= planned_pool_front_usdc;
                                match classification {
                                    PmLiquidityClassification::TimingBridge => {
                                        pool.active_timing_bridge_usdc += planned_pool_front_usdc;
                                    }
                                    PmLiquidityClassification::SettlementDebt => {
                                        pool.active_settlement_debt_usdc += planned_pool_front_usdc;
                                    }
                                    PmLiquidityClassification::Paid
                                    | PmLiquidityClassification::Unavailable => {}
                                }
                            }
                        }
                    }
                }

                pm_settlements.push(TickExpiryPmSettlement {
                    request_id,
                    event_key,
                    wallet,
                    market_id: symbol.clone(),
                    underlying: instrument.underlying.clone(),
                    expiry_ts_ms,
                    settlement_obligation_usdc: obligation.settlement_obligation_usdc,
                    liquid_usdc,
                    pm_facts,
                    pool_snapshot,
                    policy_version,
                    facts_digest,
                    unavailable_reason,
                    obligation,
                });
            }
        }
        Ok(pm_settlements)
    }

    fn ordered_due_group_symbols(group: &TickExpiryDueGroup) -> Vec<String> {
        let mut underlying_symbols: BTreeMap<String, Vec<String>> = BTreeMap::new();
        for symbol in &group.symbols {
            let parsed = parse_settlement_instrument_or_panic(symbol, "tick expiry grouping");
            underlying_symbols
                .entry(parsed.underlying)
                .or_default()
                .push(symbol.clone());
        }
        underlying_symbols.into_values().flatten().collect()
    }

    fn prepare_pm_settlement_fact_bundle(
        &self,
        wallet: WalletAddress,
        underlying: &str,
        liquid_usdc: Decimal,
        pool: Option<&crate::rsm::portfolio_margin::settlement_state::PmSettlementPoolState>,
        now_ms: u64,
        ctx: &EngineCtx,
        margin_manager: &MarginManager,
    ) -> (
        Option<PmAccountSettlementFacts>,
        Option<hypercall_margin::portfolio::PmSettlementPoolSnapshot>,
        u32,
        Option<String>,
    ) {
        let Some(pool) = pool else {
            return (
                None,
                None,
                0,
                Some(format!("missing PM settlement pool for {underlying}")),
            );
        };
        let Some(config) = pool.config.as_ref() else {
            return (
                None,
                Some(pool.snapshot()),
                pool.policy_version,
                Some(format!("missing PM settlement config for {underlying}")),
            );
        };
        let margin_details = match margin_manager.get_span_margin_for_wallet(
            &ctx.deps,
            &ctx.engine_positions,
            ctx.balance_ledger.balances(),
            &wallet,
        ) {
            Ok(Some(details)) => details,
            Ok(None) => {
                return (
                    None,
                    Some(pool.snapshot()),
                    config.policy_version,
                    Some(format!("missing PM margin details for {wallet}")),
                );
            }
            Err(error) => {
                return (
                    None,
                    Some(pool.snapshot()),
                    config.policy_version,
                    Some(format!("PM margin facts unavailable for {wallet}: {error}")),
                );
            }
        };
        let recoverable =
            (margin_details.equity - margin_details.maintenance_margin_required).max(Decimal::ZERO);
        (
            Some(PmAccountSettlementFacts {
                wallet,
                underlying: underlying.to_string(),
                liquid_usdc,
                pm_equity_usdc: margin_details.equity,
                pm_maintenance_requirement_usdc: margin_details.maintenance_margin_required,
                recoverable_collateral_usdc: recoverable,
                facts_as_of_ms: now_ms as i64,
                stale: false,
            }),
            Some(pool.snapshot()),
            config.policy_version,
            None,
        )
    }

    fn collect_due_expiries(
        &self,
        current_time: u64,
        db: Option<&DatabaseHandler>,
    ) -> Result<Vec<TickExpiryDueGroup>, String> {
        let mut grouped: BTreeMap<u64, Vec<String>> = self
            .expiry_schedules
            .range(..=current_time)
            .map(|(expiry_ts, symbols)| (*expiry_ts, symbols.clone()))
            .collect();
        let mut scheduled_symbols: HashSet<String> = grouped.values().flatten().cloned().collect();

        let Some(handler) = db else {
            return Ok(grouped
                .into_iter()
                .map(|(expiry_ts, symbols)| TickExpiryDueGroup {
                    expiry_ts: expiry_ts as i64,
                    symbols,
                })
                .collect());
        };

        let expired_active = handler
            .get_active_instruments_expired_by_sync(current_time)
            .map_err(|error| {
                format!(
                    "Failed to query expired ACTIVE instruments during expiry reconciliation: {}",
                    error
                )
            })?;

        let mut reconciled_count = 0usize;
        for instrument in expired_active {
            if !scheduled_symbols.insert(instrument.id.clone()) {
                continue;
            }

            let expiry_code = u64::try_from(instrument.expiry).map_err(|_| {
                format!(
                    "Invalid negative expiry {} for active instrument {}",
                    instrument.expiry, instrument.id
                )
            })?;
            let expiry_ts = expiry_date_to_timestamp(&instrument.underlying, expiry_code);
            if expiry_ts == 0 {
                return Err(format!(
                    "Invalid expiry {} for active instrument {}",
                    instrument.expiry, instrument.id
                ));
            }

            grouped.entry(expiry_ts).or_default().push(instrument.id);
            reconciled_count += 1;
        }

        if reconciled_count > 0 {
            warn!(
                reconciled_count,
                "Expiry tick found expired ACTIVE instruments missing from in-memory schedule; \
                 routing them through TickExpiry reconciliation"
            );
        }

        Ok(grouped
            .into_iter()
            .map(|(expiry_ts, symbols)| TickExpiryDueGroup {
                expiry_ts: expiry_ts as i64,
                symbols,
            })
            .collect())
    }

    /// Apply a TickExpiry command using only explicit command context.
    pub fn apply_tick_expiry(
        &mut self,
        now_ms: u64,
        context: TickExpiryContext,
        ctx: &mut EngineCtx,
        margin_manager: &MarginManager,
        output: &mut ApplyOutput,
    ) -> Result<(), String> {
        let margin_modes = self.effective_tick_expiry_margin_modes(&context, ctx)?;
        let mut pm_settlement_required_wallets: HashSet<WalletAddress> = context
            .margin_modes
            .iter()
            .filter_map(|mode| mode.pm_settlement_required.then_some(mode.wallet))
            .collect();
        pm_settlement_required_wallets.extend(margin_modes.iter().filter_map(
            |(wallet, margin_mode)| {
                (*margin_mode == MarginMode::Portfolio
                    && ctx.deps.portfolio_margin_pool_enabled
                    && ctx
                        .deps
                        .portfolio_margin_settlement_allowlist
                        .contains(wallet))
                .then_some(*wallet)
            },
        ));
        let price_map: HashMap<(String, i64), Decimal> = context
            .settlement_prices
            .iter()
            .map(|price| ((price.underlying.clone(), price.expiry_ts), price.price))
            .collect();
        self.validate_tick_expiry_pm_settlements(now_ms, &context, ctx, margin_manager)?;
        let expected_pm_settlement_count = context.pm_settlements.len() as u64;
        let pm_settlements: HashMap<(WalletAddress, String), TickExpiryPmSettlement> = context
            .pm_settlements
            .into_iter()
            .map(|settlement| {
                (
                    (settlement.wallet, settlement.market_id.clone()),
                    settlement,
                )
            })
            .collect();
        let mut next_pm_settlement_sequence = 0_u64;

        for group in context.due_expiries {
            let group_symbols: HashSet<&str> = group.symbols.iter().map(String::as_str).collect();
            let Some(schedule_expiry_ts) = u64::try_from(group.expiry_ts).ok() else {
                continue;
            };
            let remove_expiry_bucket = if let Some(scheduled_symbols) =
                self.expiry_schedules.get_mut(&schedule_expiry_ts)
            {
                scheduled_symbols.retain(|symbol| !group_symbols.contains(symbol.as_str()));
                scheduled_symbols.is_empty()
            } else {
                false
            };
            if remove_expiry_bucket {
                self.expiry_schedules.remove(&schedule_expiry_ts);
            }
            self.apply_transition_to_pending_settlement(&group.symbols, now_ms, ctx, output);

            let mut underlying_symbols: BTreeMap<String, Vec<String>> = BTreeMap::new();
            for symbol in Self::ordered_due_group_symbols(&group) {
                let parsed = parse_settlement_instrument_or_panic(&symbol, "tick expiry grouping");
                underlying_symbols
                    .entry(parsed.underlying)
                    .or_default()
                    .push(symbol);
            }

            let mut settled_symbols = Vec::new();
            for (underlying, symbols) in underlying_symbols {
                let expiry_ts = group.expiry_ts;
                let Some(price) = price_map.get(&(underlying.clone(), expiry_ts)).copied() else {
                    continue;
                };
                for symbol in &symbols {
                    let result = self.apply_expire_instrument(
                        symbol,
                        price,
                        now_ms,
                        ctx,
                        output,
                        &margin_modes,
                        &pm_settlement_required_wallets,
                        &pm_settlements,
                        &mut next_pm_settlement_sequence,
                    )?;
                    if result.settled && !result.blocked {
                        settled_symbols.push(symbol.clone());
                    }
                }
            }
            if !settled_symbols.is_empty() {
                output
                    .expiry_effects
                    .push(ExpiryEffect::UpdateInstrumentStatus {
                        symbols: settled_symbols,
                        status: "SETTLED".to_string(),
                    });
            }
        }

        for group in context.pending_settlements {
            let Some(price) = price_map
                .get(&(group.underlying.clone(), group.expiry_ts))
                .copied()
            else {
                continue;
            };

            let mut settled_symbols = Vec::new();
            for symbol in &group.symbols {
                let result = self.apply_expire_instrument(
                    symbol,
                    price,
                    now_ms,
                    ctx,
                    output,
                    &margin_modes,
                    &pm_settlement_required_wallets,
                    &pm_settlements,
                    &mut next_pm_settlement_sequence,
                )?;
                if result.settled && !result.blocked {
                    settled_symbols.push(symbol.clone());
                }
            }
            if !settled_symbols.is_empty() {
                output
                    .expiry_effects
                    .push(ExpiryEffect::CancelOrphanedOrdersBySymbols {
                        symbols: settled_symbols.clone(),
                    });
                output
                    .expiry_effects
                    .push(ExpiryEffect::UpdateInstrumentStatus {
                        symbols: settled_symbols,
                        status: "SETTLED".to_string(),
                    });
            }
        }

        if next_pm_settlement_sequence != expected_pm_settlement_count {
            return Err(format!(
                "TickExpiry applied {} PM settlement classifications but command carried {}",
                next_pm_settlement_sequence, expected_pm_settlement_count
            ));
        }

        Ok(())
    }

    fn validate_tick_expiry_pm_settlements(
        &self,
        now_ms: u64,
        context: &TickExpiryContext,
        ctx: &EngineCtx,
        margin_manager: &MarginManager,
    ) -> Result<(), String> {
        let expected = self.prepare_pm_settlements(
            &context.due_expiries,
            &context.pending_settlements,
            &context.settlement_prices,
            &context.margin_modes,
            now_ms,
            ctx,
            margin_manager,
        )?;
        let mut pm_settlement_state = ctx.pm_settlement_state.clone();

        let mut actual = HashMap::new();
        for settlement in &context.pm_settlements {
            let key = (settlement.wallet, settlement.market_id.clone());
            if actual.insert(key.clone(), settlement).is_some() {
                return Err(format!(
                    "duplicate PM settlement classification facts for wallet {} on {}",
                    key.0, key.1
                ));
            }
        }

        for expected_settlement in &expected {
            let wallet = expected_settlement.wallet;
            let symbol = expected_settlement.market_id.as_str();
            let Some(settlement) = actual.get(&(wallet, expected_settlement.market_id.clone()))
            else {
                return Err(format!(
                    "missing PM settlement classification facts for required wallet {wallet} on {symbol}"
                ));
            };
            let actual_sequence = settlement.event_key.settlement_event_sequence;
            if actual_sequence != expected_settlement.event_key.settlement_event_sequence {
                return Err(format!(
                    "PM settlement application order mismatch for {}/{}: expected sequence {}, got {}",
                    wallet, symbol, expected_settlement.event_key.settlement_event_sequence, actual_sequence
                ));
            }
            validate_pm_settlement_matches_expiry(
                settlement,
                wallet,
                symbol,
                &expected_settlement.underlying,
                expected_settlement.expiry_ts_ms,
                expected_settlement.obligation.net_pnl_usdc,
            )?;
            validate_pm_settlement_matches_prepared(
                settlement,
                expected_settlement,
                wallet,
                symbol,
            )?;
            pm_settlement_state.apply_classify_settlement((*settlement).clone(), now_ms)?;
        }

        if actual.len() != expected.len() {
            let expected_keys: HashSet<(WalletAddress, String)> = expected
                .iter()
                .map(|expected| (expected.wallet, expected.market_id.clone()))
                .collect();
            let mut extra = actual
                .keys()
                .filter(|key| !expected_keys.contains(*key))
                .collect::<Vec<_>>();
            extra.sort_by_key(|(wallet, symbol)| (*wallet, symbol.clone()));
            if let Some((wallet, symbol)) = extra.first() {
                return Err(format!(
                    "unexpected PM settlement classification facts for wallet {} on {}",
                    wallet, symbol
                ));
            }
            return Err(format!(
                "TickExpiry expected {} PM settlement classifications but command carried {}",
                expected.len(),
                actual.len()
            ));
        }

        Ok(())
    }

    fn effective_tick_expiry_margin_modes(
        &self,
        context: &TickExpiryContext,
        ctx: &EngineCtx,
    ) -> Result<HashMap<WalletAddress, MarginMode>, String> {
        let context_margin_modes: HashMap<WalletAddress, MarginMode> = context
            .margin_modes
            .iter()
            .map(|mode| (mode.wallet, mode.margin_mode))
            .collect();
        let mut margin_modes = HashMap::new();
        let priced_symbols = Self::priced_symbols_for_context(
            &context.due_expiries,
            &context.pending_settlements,
            &context.settlement_prices,
        );

        for ((wallet, symbol), position) in &ctx.engine_positions {
            if !priced_symbols.contains(symbol) || position.quantity == Decimal::ZERO {
                continue;
            }

            let engine_margin_mode = ctx.deps.wallet_margin_modes.get(wallet).copied();
            if let (Some(command_mode), Some(engine_mode)) = (
                context_margin_modes.get(wallet).copied(),
                engine_margin_mode,
            ) {
                if command_mode != engine_mode {
                    return Err(format!(
                        "TickExpiry margin mode mismatch for wallet {wallet}: command carried {command_mode:?}, engine state has {engine_mode:?}"
                    ));
                }
            }
            if margin_modes.contains_key(wallet) {
                continue;
            }

            let margin_mode = engine_margin_mode
                .or_else(|| context_margin_modes.get(wallet).copied())
                .unwrap_or(MarginMode::Standard);
            margin_modes.insert(*wallet, margin_mode);
        }

        Ok(margin_modes)
    }

    fn priced_symbols_for_context(
        due_expiries: &[TickExpiryDueGroup],
        pending_settlements: &[TickExpiryPendingGroup],
        settlement_prices: &[TickExpirySettlementPrice],
    ) -> HashSet<String> {
        let priced_keys: HashSet<(String, i64)> = settlement_prices
            .iter()
            .map(|price| (price.underlying.clone(), price.expiry_ts))
            .collect();
        let mut priced_symbols = HashSet::new();

        for group in due_expiries {
            for symbol in &group.symbols {
                let parsed = parse_settlement_instrument_or_panic(symbol, "priced expiry context");
                if priced_keys.contains(&(parsed.underlying, group.expiry_ts)) {
                    priced_symbols.insert(symbol.clone());
                }
            }
        }
        for group in pending_settlements {
            if priced_keys.contains(&(group.underlying.clone(), group.expiry_ts)) {
                priced_symbols.extend(group.symbols.iter().cloned());
            }
        }

        priced_symbols
    }

    fn apply_transition_to_pending_settlement(
        &mut self,
        symbols: &[String],
        now_ms: u64,
        ctx: &mut EngineCtx,
        output: &mut ApplyOutput,
    ) {
        if symbols.is_empty() {
            return;
        }

        let mut cancelled_order_ids = Vec::new();
        for symbol in symbols {
            ctx.expired_instruments.insert(symbol.clone(), true);

            if let Some(orderbook) = ctx.orderbooks.get(symbol) {
                let underlying =
                    parse_settlement_instrument_or_panic(symbol, "apply expiry transition")
                        .underlying;

                for r in orderbook.get_all_orders() {
                    let cancel_message = OrderUpdateMessage {
                        timestamp: now_ms,
                        info: OrderInfo {
                            symbol: symbol.clone(),
                            price: r.price,
                            size: r.quantity,
                            side: r.side,
                            tif: hypercall_types::TimeInForce::GTC,
                            client_id: None,
                            order_id: Some(r.order_id),
                            is_perp: false,
                            underlying: Some(underlying.clone()),
                            reduce_only: None,
                            nonce: None,
                            signature: None,
                            mmp_enabled: false,
                            builder_code_address: None,
                        },
                        status: OrderUpdateStatus::Canceled,
                        reason: Some("Instrument expired".to_string()),
                        filled_size: dec!(0),
                        order_id: Some(r.order_id),
                        wallet_address: r.wallet,
                        mmp_triggered: false,
                        request_id: None,
                    };
                    ctx.order_index.remove_order(&r.wallet, r.order_id);
                    cancelled_order_ids.push(r.order_id as i64);
                    output.push(EngineMessage::OrderUpdate(cancel_message));
                }
            }

            ctx.orderbooks.remove(symbol);
        }

        output
            .expiry_effects
            .push(ExpiryEffect::UpdateInstrumentStatus {
                symbols: symbols.to_vec(),
                status: "EXPIRED_PENDING_PRICE".to_string(),
            });
        if !cancelled_order_ids.is_empty() {
            output
                .expiry_effects
                .push(ExpiryEffect::BatchCancelOrdersForSettlement {
                    order_ids: cancelled_order_ids,
                    now_ms,
                });
        }
        output
            .expiry_effects
            .push(ExpiryEffect::CancelOrphanedOrdersBySymbols {
                symbols: symbols.to_vec(),
            });
    }

    fn apply_expire_instrument(
        &mut self,
        symbol: &str,
        reference_price: Decimal,
        now_ms: u64,
        ctx: &mut EngineCtx,
        output: &mut ApplyOutput,
        margin_modes: &HashMap<WalletAddress, MarginMode>,
        pm_settlement_required_wallets: &HashSet<WalletAddress>,
        pm_settlements: &HashMap<(WalletAddress, String), TickExpiryPmSettlement>,
        next_pm_settlement_sequence: &mut u64,
    ) -> Result<ExpireInstrumentApplyResult, String> {
        let instrument = SettlementInstrument::from_symbol(symbol)
            .map_err(|e| format!("Failed to parse symbol {}: {}", symbol, e))?;

        let mut settlements_to_apply: Vec<SettlementPosition> = Vec::new();
        for ((wallet, sym), pos) in &ctx.engine_positions {
            if sym == symbol && pos.quantity != Decimal::ZERO {
                settlements_to_apply.push(SettlementPosition {
                    wallet: *wallet,
                    position_size: pos.quantity,
                    entry_price: pos.entry_price,
                });
            }
        }
        settlements_to_apply.sort_by_key(|position| position.wallet);

        if settlements_to_apply.is_empty() && ctx.expired_instruments.get(symbol) == Some(&true) {
            return Ok(ExpireInstrumentApplyResult {
                settled: true,
                blocked: false,
            });
        }

        ctx.expired_instruments.insert(symbol.to_string(), true);

        let market = hypercall_types::Market {
            symbol: symbol.to_string(),
            underlying: instrument.underlying.clone(),
            expiry: instrument.expiry,
            strike: instrument.strike,
            option_type: match instrument.option_type {
                SettlementOptionType::Call => MessageOptionType::Call,
                SettlementOptionType::Put => MessageOptionType::Put,
            },
        };

        ctx.orderbooks.remove(symbol);

        let settlement_outputs =
            plan_position_settlements(&instrument, reference_price, &settlements_to_apply);
        let expiry_ts_ms = instrument
            .expiry_ts
            .checked_mul(1000)
            .ok_or_else(|| format!("expiry timestamp overflow for {symbol}"))?;

        let mut result = ExpireInstrumentApplyResult::default();
        if settlement_outputs.is_empty() {
            result.settled = true;
        }
        for (position, out) in settlement_outputs {
            let wallet = position.wallet;
            let margin_mode = margin_modes
                .get(&wallet)
                .copied()
                .or_else(|| ctx.deps.wallet_margin_modes.get(&wallet).copied())
                .unwrap_or(MarginMode::Standard);
            let settlement_value = out.settlement_value;
            let cost_basis = out.cost_basis;
            let net_pnl = out.net_pnl;
            let pm_settlement = if margin_mode == MarginMode::Portfolio {
                pm_settlements.get(&(wallet, symbol.to_string()))
            } else {
                None
            };
            if margin_mode == MarginMode::Portfolio
                && pm_settlement_required_wallets.contains(&wallet)
                && pm_settlement.is_none()
            {
                return Err(format!(
                    "missing PM settlement classification facts for required wallet {wallet} on {symbol}"
                ));
            }
            let mut pool_front_usdc = Decimal::ZERO;
            if let Some(pm_settlement) = pm_settlement {
                validate_pm_settlement_matches_expiry(
                    pm_settlement,
                    wallet,
                    symbol,
                    &instrument.underlying,
                    expiry_ts_ms,
                    net_pnl,
                )?;
                let actual_sequence = pm_settlement.event_key.settlement_event_sequence;
                if actual_sequence != *next_pm_settlement_sequence {
                    return Err(format!(
                        "PM settlement application order mismatch for {}/{}: expected sequence {}, got {}",
                        wallet, symbol, *next_pm_settlement_sequence, actual_sequence
                    ));
                }
                *next_pm_settlement_sequence = (*next_pm_settlement_sequence)
                    .checked_add(1)
                    .ok_or_else(|| {
                        "PM settlement event sequence overflow during expiry apply".to_string()
                    })?;
                let effects = ctx
                    .pm_settlement_state
                    .apply_classify_settlement(pm_settlement.clone(), now_ms)?;
                output.pm_settlement_effects.extend(effects);
                let status = ctx
                    .pm_settlement_state
                    .events
                    .get(&pm_settlement.event_key)
                    .map(|event| event.status.as_str())
                    .unwrap_or("Unavailable");
                match status {
                    "Unavailable" => {
                        result.blocked = true;
                        continue;
                    }
                    "TimingBridge" | "SettlementDebt" => {
                        pool_front_usdc = (pm_settlement.settlement_obligation_usdc
                            - pm_settlement.liquid_usdc)
                            .max(Decimal::ZERO);
                    }
                    "Paid" => {}
                    other => {
                        return Err(format!("unknown PM settlement classification {other}"));
                    }
                }
            }

            let cash_delta =
                expiry_cash_delta_for_margin_mode(margin_mode, settlement_value, net_pnl);
            apply_engine_balance_update(
                ctx,
                Some(output),
                wallet,
                cash_delta,
                hypercall_types::BalanceUpdateReason::Settlement,
                Some(symbol.to_string()),
                now_ms,
            );
            if pool_front_usdc > Decimal::ZERO {
                apply_engine_balance_update(
                    ctx,
                    Some(output),
                    wallet,
                    pool_front_usdc,
                    hypercall_types::BalanceUpdateReason::Settlement,
                    Some(format!("pm-settlement-pool-front:{symbol}")),
                    now_ms,
                );
            }

            output
                .expiry_effects
                .push(ExpiryEffect::ApplySettlement(ExpirySettlementIntent {
                    wallet,
                    symbol: symbol.to_string(),
                    position_size: position.position_size,
                    settlement_price: out.intrinsic_value,
                    settlement_value,
                    margin_mode,
                    event_ts_ms: now_ms as i64,
                    settlement_entry_price: Some(position.entry_price),
                    cost_basis: Some(cost_basis),
                    net_pnl: Some(net_pnl),
                }));

            output.push(EngineMessage::PositionExpired(
                build_position_expired_message(&instrument, &position, &out, margin_mode, now_ms),
            ));

            ctx.engine_positions.remove(&(wallet, symbol.to_string()));
            result.settled = true;
        }

        if result.settled && !result.blocked {
            output.push(EngineMessage::MarketUpdate(MarketUpdateMessage {
                market,
                status: MarketUpdateStatus::MarketExpired,
                timestamp: now_ms,
                reason: None,
            }));
        }

        Ok(result)
    }

    /// Check for expired instruments and process expiries.
    pub async fn check_and_process_expiries(&mut self, now_ms: u64, ctx: &mut EngineCtx) {
        let current_time = now_ms / 1000;

        // Phase 1: Process newly expired instruments
        let expired_times: Vec<u64> = self
            .expiry_schedules
            .range(..=current_time)
            .map(|(time, _)| *time)
            .collect();

        for expiry_time in expired_times {
            if let Some(symbols) = self.expiry_schedules.remove(&expiry_time) {
                info!(
                    "Processing expiry at {} for {} instruments",
                    expiry_time,
                    symbols.len()
                );

                self.transition_to_pending_settlement(&symbols, now_ms, ctx);

                let mut underlying_symbols: HashMap<String, Vec<String>> = HashMap::new();
                for symbol in &symbols {
                    let parsed =
                        parse_settlement_instrument_or_panic(symbol, "expiry price grouping");
                    underlying_symbols
                        .entry(parsed.underlying.clone())
                        .or_default()
                        .push(symbol.clone());
                }

                for (underlying, option_symbols) in underlying_symbols {
                    let expiry_ts_i64 = expiry_time as i64;
                    if let Some(price) = self
                        .get_settlement_price(&ctx.deps, &underlying, expiry_ts_i64)
                        .await
                    {
                        let mut settled_symbols = Vec::new();
                        for symbol in &option_symbols {
                            if let Err(e) = self.expire_instrument(symbol, price, now_ms, ctx).await
                            {
                                panic!(
                                    "CRITICAL_FAILURE: Failed to expire instrument {}: {}. \
                                     Partial settlement is worse than no settlement. Restart required.",
                                    symbol, e
                                );
                            } else {
                                settled_symbols.push(symbol.clone());
                                record_settlement(&underlying, true);
                            }
                        }
                        if !settled_symbols.is_empty() {
                            self.update_instrument_status(
                                &settled_symbols,
                                "SETTLED",
                                ctx.db.as_ref(),
                            );
                        }
                    } else {
                        warn!(
                            "Settlement price not yet available for {} expiry {}, will retry",
                            underlying, expiry_ts_i64
                        );
                    }
                }
            }
        }

        // Phase 2: Retry settlement for instruments pending from previous ticks/restarts
        let pending = self.get_pending_settlement_instruments(ctx.db.as_ref());
        for (underlying, expiry_ts, symbols) in pending {
            if let Some(price) = self
                .get_settlement_price(&ctx.deps, &underlying, expiry_ts)
                .await
            {
                info!(
                    "Retrying settlement for {} instruments of {} expiry {}",
                    symbols.len(),
                    underlying,
                    expiry_ts
                );

                let mut settled_symbols = Vec::new();
                for symbol in &symbols {
                    if let Err(e) = self.expire_instrument(symbol, price, now_ms, ctx).await {
                        panic!(
                            "CRITICAL_FAILURE: Failed to expire instrument {} during retry: {}. \
                             Partial settlement is worse than no settlement. Restart required.",
                            symbol, e
                        );
                    } else {
                        settled_symbols.push(symbol.clone());
                        record_settlement(&underlying, true);
                    }
                }
                if !settled_symbols.is_empty() {
                    if let Some(ref handler) = ctx.db {
                        match handler.cancel_orphaned_orders_by_symbols_sync(&settled_symbols) {
                            Ok(0) => {}
                            Ok(n) => {
                                warn!(
                                    "Settlement retry cleanup: cancelled {} orphaned order_infos \
                                     rows on {} instruments",
                                    n,
                                    settled_symbols.len()
                                );
                            }
                            Err(e) => {
                                error!(
                                    "Failed settlement retry cleanup for {:?}: {}",
                                    settled_symbols, e
                                );
                            }
                        }
                    }

                    self.update_instrument_status(&settled_symbols, "SETTLED", ctx.db.as_ref());
                }
            }
        }
    }

    /// Expire a specific instrument and settle all positions.
    pub async fn expire_instrument(
        &mut self,
        symbol: &str,
        reference_price: Decimal,
        now_ms: u64,
        ctx: &mut EngineCtx,
    ) -> Result<(), String> {
        let parsed = ParsedSymbol::from_symbol(symbol)
            .map_err(|e| format!("Failed to parse symbol {}: {}", symbol, e))?;

        let mut settlements_to_apply: Vec<(WalletAddress, Decimal, Decimal)> = Vec::new();
        for ((wallet, sym), pos) in &ctx.engine_positions {
            if sym == symbol && pos.quantity != Decimal::ZERO {
                settlements_to_apply.push((*wallet, pos.quantity, pos.entry_price));
            }
        }
        let has_positions = !settlements_to_apply.is_empty();
        let settlement_option_type = to_settlement_option_type(&parsed.option_type);
        let mut settlement_intents: Vec<(WalletAddress, SettlementApplyIntent)> = Vec::new();

        for (wallet, position_size, settlement_entry_price) in settlements_to_apply {
            let margin_mode = margin_mode_for_settlement(ctx, wallet)?;
            let intent = build_settlement_apply_intent(SettlementApplyInput {
                wallet,
                symbol,
                option_type: settlement_option_type,
                strike: parsed.strike,
                reference_price,
                position_size,
                entry_price: settlement_entry_price,
                margin_mode,
                timestamp_ms: now_ms,
            });
            settlement_intents.push((wallet, intent));
        }

        if !has_positions && ctx.expired_instruments.get(symbol) == Some(&true) {
            debug!(
                "Instrument {} already expired and settled (no positions), skipping",
                symbol
            );
            return Ok(());
        }

        ctx.expired_instruments.insert(symbol.to_string(), true);

        info!(
            "Expiring {} with reference price {}",
            symbol, reference_price
        );

        let market = hypercall_types::Market {
            symbol: symbol.to_string(),
            underlying: parsed.underlying.clone(),
            expiry: parsed.expiry,
            strike: parsed.strike,
            option_type: match parsed.option_type {
                crate::types::OptionType::Call => MessageOptionType::Call,
                crate::types::OptionType::Put => MessageOptionType::Put,
            },
        };

        let market_update = MarketUpdateMessage {
            market,
            status: MarketUpdateStatus::MarketExpired,
            timestamp: now_ms,
            reason: None,
        };

        ctx.deps
            .event_sender
            .send(EngineMessage::MarketUpdate(market_update))
            .unwrap_or_else(|e| {
                panic!(
                    "CRITICAL_FAILURE: Failed to send MarketUpdate (expired) for symbol {}: {}. \
                     Market expiry event lost. Restart required.",
                    symbol, e
                )
            });

        if ctx.orderbooks.contains_key(symbol) {
            ctx.orderbooks.remove(symbol);
        }

        for (wallet, intent) in settlement_intents {
            if let Some(ref handler) = ctx.db {
                let settlement: &dyn hypercall_db::SettlementWriter = handler;
                let outcome = settlement
                    .try_apply_settlement_sync(
                        &wallet,
                        symbol,
                        intent.message.position_size,
                        intent.message.settlement_price,
                        intent.message.settlement_value,
                        intent.message.margin_mode,
                        now_ms as i64,
                        intent.message.settlement_entry_price,
                        intent.message.cost_basis,
                        intent.message.net_pnl,
                    )
                    .map_err(|e| {
                        format!(
                            "Failed to persist settlement for {}/{}: {}",
                            wallet, symbol, e
                        )
                    })?;

                let balance_before = ctx.balance_ledger.balance(&wallet);
                let balance_after = apply_engine_balance_update(
                    ctx,
                    None,
                    wallet,
                    intent.cash_delta,
                    hypercall_types::BalanceUpdateReason::Settlement,
                    Some(symbol.to_string()),
                    now_ms,
                );
                debug!(
                    wallet = %wallet,
                    symbol = %symbol,
                    balance_before = %balance_before,
                    balance_after = %balance_after,
                    newly_persisted = outcome.newly_persisted,
                    "Applied settlement cashflow to balance_ledger after durable claim"
                );

                if !outcome.newly_persisted {
                    info!(
                        "Settlement for {}/{} already durably claimed; applying local expiry state",
                        wallet, symbol
                    );
                }
            } else {
                let balance_before = ctx.balance_ledger.balance(&wallet);
                let balance_after = apply_engine_balance_update(
                    ctx,
                    None,
                    wallet,
                    intent.cash_delta,
                    hypercall_types::BalanceUpdateReason::Settlement,
                    Some(symbol.to_string()),
                    now_ms,
                );
                debug!(
                    wallet = %wallet,
                    symbol = %symbol,
                    cash_delta = %intent.cash_delta,
                    balance_before = %balance_before,
                    balance_after = %balance_after,
                    "Applied in-memory settlement cashflow to balance_ledger"
                );
            }

            let expiry_msg = EngineMessage::PositionExpired(intent.message.clone());

            ctx.deps
                .event_sender
                .send(expiry_msg.clone())
                .unwrap_or_else(|e| {
                    panic!(
                        "CRITICAL_FAILURE: Failed to send PositionExpired event for {}/{}: {}. \
                     Settlement event lost. Restart required.",
                        wallet, symbol, e
                    )
                });
            // Also send to direct WS channel (best-effort)
            if let Some(ref ws_tx) = ctx.deps.ws_event_sender {
                let _ = ws_tx.send(expiry_msg);
            }

            ctx.engine_positions.remove(&(wallet, symbol.to_string()));

            info!(
                "Position expired for account {}: symbol={}, size={}, settlement_price={}, settlement_value={}, settlement_entry_price={}, cost_basis={}, net_pnl={}",
                wallet,
                symbol,
                intent.message.position_size,
                intent.message.settlement_price,
                intent.message.settlement_value,
                intent
                    .message
                    .settlement_entry_price
                    .expect("settlement intent includes entry price"),
                intent.message.cost_basis.expect("settlement intent includes cost_basis"),
                intent.message.net_pnl.expect("settlement intent includes net_pnl")
            );
        }

        info!("Successfully expired instrument: {}", symbol);
        Ok(())
    }

    /// Register TWAP settlement windows for all active instruments.
    pub fn register_settlements_for_existing_instruments(
        &self,
        deps: &EngineDeps,
        orderbooks: &HashMap<String, hypercall_engine::OrderBook>,
    ) {
        if deps.mark_price_oracles.is_empty() {
            debug!("No oracles configured, skipping settlement registration");
            return;
        }

        let mut registered = 0;
        for (symbol, orderbook) in orderbooks {
            let parsed =
                parse_settlement_instrument_or_panic(symbol, "existing settlement registration");
            let expiry_timestamp = expiry_date_to_timestamp(&parsed.underlying, orderbook.expiry);
            if let Some(oracle) = deps.mark_price_oracles.get(&parsed.underlying) {
                let expiry_ts_i64 = expiry_timestamp as i64;
                let oracle = oracle.clone();
                let symbol_clone = symbol.clone();
                tokio::spawn(async move {
                    oracle.register_settlement(expiry_ts_i64, 1800).await;
                    debug!(
                        "Registered TWAP settlement for {} at expiry {}",
                        symbol_clone, expiry_ts_i64
                    );
                });
                registered += 1;
            }
        }

        info!(
            "Registered TWAP settlements for {} existing instruments",
            registered
        );
    }
}

fn validate_pm_settlement_matches_expiry(
    pm_settlement: &TickExpiryPmSettlement,
    wallet: WalletAddress,
    symbol: &str,
    underlying: &str,
    expiry_ts_ms: i64,
    net_pnl_usdc: Decimal,
) -> Result<(), String> {
    let settlement_obligation_usdc = Decimal::ZERO.max(-net_pnl_usdc);
    if pm_settlement.wallet != wallet {
        return Err(format!(
            "PM settlement classification facts do not match expiry for {wallet}/{symbol}: wallet mismatch"
        ));
    }
    if pm_settlement.market_id != symbol {
        return Err(format!(
            "PM settlement classification facts do not match expiry for {wallet}/{symbol}: market_id mismatch"
        ));
    }
    if pm_settlement.underlying != underlying {
        return Err(format!(
            "PM settlement classification facts do not match expiry for {wallet}/{symbol}: underlying mismatch"
        ));
    }
    if pm_settlement.expiry_ts_ms != expiry_ts_ms {
        return Err(format!(
            "PM settlement classification facts do not match expiry for {wallet}/{symbol}: expiry_ts_ms mismatch"
        ));
    }
    if pm_settlement.settlement_obligation_usdc != settlement_obligation_usdc {
        return Err(format!(
            "PM settlement classification facts do not match expiry for {wallet}/{symbol}: settlement_obligation_usdc mismatch"
        ));
    }
    let obligation = &pm_settlement.obligation;
    if obligation.wallet != wallet
        || obligation.market_id != symbol
        || obligation.underlying != underlying
        || obligation.expiry_ts_ms != expiry_ts_ms
        || obligation.net_pnl_usdc != net_pnl_usdc
        || obligation.settlement_obligation_usdc != settlement_obligation_usdc
    {
        return Err(format!(
            "PM settlement classification facts do not match expiry for {wallet}/{symbol}: obligation mismatch"
        ));
    }
    if pm_settlement.event_key.wallet != wallet
        || pm_settlement.event_key.market_id != symbol
        || pm_settlement.event_key.expiry_ts_ms != expiry_ts_ms
    {
        return Err(format!(
            "PM settlement classification facts do not match expiry for {wallet}/{symbol}: event key mismatch"
        ));
    }
    Ok(())
}

fn validate_pm_settlement_matches_prepared(
    pm_settlement: &TickExpiryPmSettlement,
    expected: &TickExpiryPmSettlement,
    wallet: WalletAddress,
    symbol: &str,
) -> Result<(), String> {
    if pm_settlement != expected {
        return Err(format!(
            "PM settlement classification facts do not match prepared PM facts/digest for {wallet}/{symbol}"
        ));
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use hypercall_types::wallet_address::test_wallet;
    use rust_decimal_macros::dec;

    #[test]
    fn settlement_crate_matches_legacy_long() {
        let out = hypercall_settlement::settle_position(&hypercall_settlement::SettlementInput {
            option_type: SettlementOptionType::Call,
            strike: dec!(0),
            reference_price: dec!(130),
            position_size: dec!(2),
            entry_price: dec!(100),
        });
        assert_eq!(out.cost_basis, dec!(200));
        assert_eq!(out.net_pnl, dec!(60));
    }

    #[test]
    fn settlement_crate_matches_legacy_short() {
        let out = hypercall_settlement::settle_position(&hypercall_settlement::SettlementInput {
            option_type: SettlementOptionType::Put,
            strike: dec!(1000),
            reference_price: dec!(910),
            position_size: dec!(-3),
            entry_price: dec!(120),
        });
        assert_eq!(out.cost_basis, dec!(-360));
        assert_eq!(out.net_pnl, dec!(90));
    }

    #[test]
    fn settlement_apply_intent_uses_standard_terminal_cashflow() {
        let intent = build_settlement_apply_intent(SettlementApplyInput {
            wallet: test_wallet(1),
            symbol: "BTC-20261231-100000-C",
            option_type: SettlementOptionType::Call,
            strike: dec!(100000),
            reference_price: dec!(105000),
            position_size: dec!(1),
            entry_price: dec!(1000),
            margin_mode: MarginMode::Standard,
            timestamp_ms: 1777017633000,
        });

        assert_eq!(intent.message.settlement_price, dec!(5000));
        assert_eq!(intent.message.settlement_value, dec!(5000));
        assert_eq!(intent.message.cost_basis, Some(dec!(1000)));
        assert_eq!(intent.message.net_pnl, Some(dec!(4000)));
        assert_eq!(intent.cash_delta, dec!(5000));
    }

    #[test]
    fn settlement_apply_intent_uses_portfolio_net_pnl() {
        let intent = build_settlement_apply_intent(SettlementApplyInput {
            wallet: test_wallet(2),
            symbol: "BTC-20261231-100000-C",
            option_type: SettlementOptionType::Call,
            strike: dec!(100000),
            reference_price: dec!(99000),
            position_size: dec!(1),
            entry_price: dec!(1000),
            margin_mode: MarginMode::Portfolio,
            timestamp_ms: 1777017633000,
        });

        assert_eq!(intent.message.settlement_price, dec!(0));
        assert_eq!(intent.message.settlement_value, dec!(0));
        assert_eq!(intent.message.cost_basis, Some(dec!(1000)));
        assert_eq!(intent.message.net_pnl, Some(dec!(-1000)));
        assert_eq!(intent.cash_delta, dec!(-1000));
    }

    #[test]
    fn simulated_pm_liquid_reserves_same_tick_gains_for_later_losses() {
        let after_winner =
            simulated_pm_liquid_after_settlement(Decimal::ZERO, dec!(500), Decimal::ZERO);
        assert_eq!(after_winner, dec!(500));

        let after_paid_loss =
            simulated_pm_liquid_after_settlement(after_winner, dec!(-400), Decimal::ZERO);
        assert_eq!(after_paid_loss, dec!(100));
    }

    #[test]
    fn simulated_pm_liquid_includes_pool_front_for_bridge_and_debt() {
        let after_fronted_loss =
            simulated_pm_liquid_after_settlement(dec!(500), dec!(-900), dec!(400));
        assert_eq!(after_fronted_loss, Decimal::ZERO);
    }

    #[test]
    fn initial_pm_liquid_precredit_consumes_existing_negative_cash() {
        assert_eq!(
            initial_pm_liquid_with_precredit(dec!(-300), dec!(500)),
            dec!(200)
        );
        assert_eq!(
            initial_pm_liquid_with_precredit(dec!(-700), dec!(500)),
            Decimal::ZERO
        );
        assert_eq!(
            initial_pm_liquid_with_precredit(dec!(100), dec!(500)),
            dec!(600)
        );
    }

    #[test]
    fn precredited_pm_gain_nets_loss_when_losing_symbol_is_visited_first() {
        let mut remaining_precredited = dec!(500);
        let after_loss = simulated_pm_liquid_after_settlement(
            dec!(500),
            effective_pm_cash_delta_after_precredit(dec!(-400), &mut remaining_precredited),
            Decimal::ZERO,
        );
        assert_eq!(after_loss, dec!(100));
        assert_eq!(remaining_precredited, dec!(500));

        let after_winner = simulated_pm_liquid_after_settlement(
            after_loss,
            effective_pm_cash_delta_after_precredit(dec!(500), &mut remaining_precredited),
            Decimal::ZERO,
        );
        assert_eq!(after_winner, dec!(100));
        assert_eq!(remaining_precredited, Decimal::ZERO);
    }

    #[test]
    fn recoverable_reservation_uses_pool_front_not_gross_obligation() {
        assert_eq!(
            simulated_recoverable_after_pm_front(dec!(100), Decimal::ZERO),
            dec!(100)
        );
        assert_eq!(
            simulated_recoverable_after_pm_front(dec!(100), dec!(40)),
            dec!(60)
        );
        assert_eq!(
            simulated_recoverable_after_pm_front(dec!(100), dec!(140)),
            Decimal::ZERO
        );
    }
}