Skip to main content

nautilus_common/cache/
mod.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! In-memory cache for market and execution data, with optional persistent backing.
17//!
18//! Provides methods to load, query, and update cached data such as instruments, orders, and prices.
19//!
20//! # Persistence policy
21//!
22//! Cache operations complete valid in-memory changes independently of optional persistence. All cache
23//! writes, including indexes, snapshots, component state, heartbeats, and purge deletions, log
24//! persistence failures at `ERROR` without propagating them or interrupting event and command
25//! processing. Validation and in-memory errors still propagate, including DeFi currency integrity
26//! errors reported by a backing database. The cache also propagates read, restoration, and explicit
27//! database flush errors returned by its backing.
28//!
29//! A successful cache call confirms the cache operation, not queue admission or durable storage.
30//! For queued backings, database writes can fail after the cache call returns. Both enqueue and
31//! downstream write failures are logged as persistence failures.
32//!
33//! The node or backtest `shutdown_on_error` setting requests a normal shutdown on Rust error logs
34//! emitted after the runtime starts, including persistence failures. It does not abort the process
35//! or roll back the current operation. Error-triggered shutdown handling is disabled before final
36//! component-state saves, which still follow this best-effort policy.
37
38pub mod config;
39pub mod database;
40pub mod fifo;
41pub mod quote;
42pub mod refs;
43
44mod api;
45mod bounded;
46mod error;
47mod filter;
48mod index;
49mod position;
50mod view;
51
52#[cfg(test)]
53mod tests;
54
55use std::{
56    borrow::Cow,
57    cell::RefCell,
58    cmp::{Ordering, Reverse},
59    fmt::{Debug, Display},
60    rc::Rc,
61    time::{SystemTime, UNIX_EPOCH},
62};
63
64use ahash::{AHashMap, AHashSet};
65pub use api::CacheApi; // Re-export
66use bounded::BoundedVecDeque;
67use bytes::Bytes;
68pub use config::CacheConfig; // Re-export
69use database::{CacheDatabaseAdapter, CacheMap, register_loaded_currencies};
70pub use error::{
71    ACCOUNT_NOT_FOUND, AccountLookupError, CURRENCY_NOT_FOUND, CurrencyLookupError,
72    INSTRUMENT_NOT_FOUND, InstrumentLookupError, ORDER_BOOK_NOT_FOUND, ORDER_LIST_NOT_FOUND,
73    ORDER_NOT_FOUND, OWN_ORDER_BOOK_NOT_FOUND, OrderBookLookupError, OrderListLookupError,
74    OrderLookupError, OwnOrderBookLookupError, POSITION_NOT_FOUND, PositionLookupError,
75    SYNTHETIC_INSTRUMENT_NOT_FOUND, SyntheticInstrumentLookupError, VenueOrderIdOwnershipError,
76};
77use filter::{FilterSources, intersect_pair_or_many};
78use index::CacheIndex;
79use indexmap::IndexMap;
80use nautilus_core::{
81    DurationNanos, SharedCell, UnixNanos,
82    correctness::{
83        check_key_not_in_map, check_predicate_false, check_slice_not_empty, check_valid_string_utf8,
84    },
85};
86use nautilus_model::{
87    accounts::{Account, AccountAny},
88    data::{
89        Bar, BarType, FundingRateUpdate, GreeksData, IndexPriceUpdate, InstrumentClose,
90        InstrumentStatus, MarkPriceUpdate, QuoteTick, TradeTick, YieldCurve,
91        option_chain::OptionGreeks,
92    },
93    enums::{
94        AggregationSource, ContingencyType, InstrumentClass, OmsType, OrderSide, PositionSide,
95        PriceType,
96    },
97    events::{AccountState, OrderEventAny, OrderFilled, PositionAdjusted},
98    identifiers::{
99        AccountId, ActorId, ClientId, ClientOrderId, ExecAlgorithmId, InstrumentId, OrderListId,
100        PositionId, StrategyId, Venue, VenueOrderId,
101    },
102    instruments::{Instrument, InstrumentAny, SyntheticInstrument},
103    orderbook::{
104        OrderBook,
105        own::{OwnOrderBook, should_handle_own_book_order},
106    },
107    orders::{Order, OrderAny, OrderError, OrderList},
108    position::{Position, PositionReplayEvent},
109    types::{
110        Currency, Money, Price, Quantity,
111        fixed::{FIXED_PRECISION, MAX_FLOAT_PRECISION, check_fixed_precision},
112        price::PriceRaw,
113    },
114};
115pub use position::CacheSnapshotRef;
116use position::PositionSnapshotFrame;
117pub use refs::{AccountRef, AccountRefMut, OrderRef, OrderRefMut, PositionRef, PositionRefMut};
118use rust_decimal::Decimal;
119use ustr::Ustr;
120pub use view::CacheView; // Re-export
121
122#[cfg(feature = "defi")]
123use crate::defi::cache::IntegrityError;
124use crate::xrate::{get_exchange_rate, get_exchange_rate_with_alternates};
125
126/// A common in-memory `Cache` for market and execution related data.
127#[cfg_attr(
128    feature = "python",
129    pyo3::pyclass(module = "nautilus_trader.common", unsendable)
130)]
131pub struct Cache {
132    config: CacheConfig,
133    index: CacheIndex,
134    database: Option<Box<dyn CacheDatabaseAdapter>>,
135    general: AHashMap<String, Bytes>,
136    currencies: AHashMap<Ustr, Currency>,
137    instruments: AHashMap<InstrumentId, InstrumentAny>,
138    instrument_closes: AHashMap<InstrumentId, InstrumentClose>,
139    synthetics: AHashMap<InstrumentId, SyntheticInstrument>,
140    books: AHashMap<InstrumentId, OrderBook>,
141    own_books: AHashMap<InstrumentId, OwnOrderBook>,
142    quotes: AHashMap<InstrumentId, BoundedVecDeque<QuoteTick>>,
143    trades: AHashMap<InstrumentId, BoundedVecDeque<TradeTick>>,
144    mark_xrates: AHashMap<(Currency, Currency), f64>,
145    mark_prices: AHashMap<InstrumentId, BoundedVecDeque<MarkPriceUpdate>>,
146    index_prices: AHashMap<InstrumentId, BoundedVecDeque<IndexPriceUpdate>>,
147    funding_rates: AHashMap<InstrumentId, BoundedVecDeque<FundingRateUpdate>>,
148    instrument_statuses: AHashMap<InstrumentId, BoundedVecDeque<InstrumentStatus>>,
149    bars: AHashMap<BarType, BoundedVecDeque<Bar>>,
150    greeks: AHashMap<InstrumentId, GreeksData>,
151    option_greeks: AHashMap<InstrumentId, OptionGreeks>,
152    yield_curves: AHashMap<String, YieldCurve>,
153    external_order_claims: AHashMap<InstrumentId, StrategyId>,
154    client_accounts: AHashMap<ClientId, AccountId>,
155    client_routes: AHashMap<Venue, ClientId>,
156    default_client_id: Option<ClientId>,
157    external_data_clients: AHashSet<ClientId>,
158    external_exec_clients: AHashSet<ClientId>,
159    accounts: AHashMap<AccountId, SharedCell<AccountAny>>,
160    orders: AHashMap<ClientOrderId, SharedCell<OrderAny>>,
161    orders_dispatched: AHashSet<ClientOrderId>,
162    order_lists: AHashMap<OrderListId, OrderList>,
163    positions: AHashMap<PositionId, SharedCell<Position>>,
164    position_snapshots: AHashMap<PositionId, Vec<PositionSnapshotFrame>>,
165    position_snapshot_revisions: AHashMap<PositionId, u64>,
166    #[cfg(feature = "defi")]
167    pub(crate) defi: crate::defi::cache::DefiCache,
168}
169
170impl Debug for Cache {
171    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
172        f.debug_struct(stringify!(Cache))
173            .field("config", &self.config)
174            .field("index", &self.index)
175            .field("general", &self.general)
176            .field("currencies", &self.currencies)
177            .field("instruments", &self.instruments)
178            .field("synthetics", &self.synthetics)
179            .field("books", &self.books)
180            .field("own_books", &self.own_books)
181            .field("quotes", &self.quotes)
182            .field("trades", &self.trades)
183            .field("mark_xrates", &self.mark_xrates)
184            .field("mark_prices", &self.mark_prices)
185            .field("index_prices", &self.index_prices)
186            .field("funding_rates", &self.funding_rates)
187            .field("instrument_statuses", &self.instrument_statuses)
188            .field("instrument_closes", &self.instrument_closes)
189            .field("bars", &self.bars)
190            .field("greeks", &self.greeks)
191            .field("option_greeks", &self.option_greeks)
192            .field("yield_curves", &self.yield_curves)
193            .field("external_order_claims", &self.external_order_claims)
194            .field("client_accounts", &self.client_accounts)
195            .field("client_routes", &self.client_routes)
196            .field("default_client_id", &self.default_client_id)
197            .field("external_data_clients", &self.external_data_clients)
198            .field("external_exec_clients", &self.external_exec_clients)
199            .field("accounts", &self.accounts)
200            .field("orders", &self.orders)
201            .field("orders_dispatched", &self.orders_dispatched)
202            .field("order_lists", &self.order_lists)
203            .field("positions", &self.positions)
204            .field("position_snapshots", &self.position_snapshots)
205            .finish()
206    }
207}
208
209impl Default for Cache {
210    /// Creates a new default [`Cache`] instance.
211    fn default() -> Self {
212        Self::new(Some(CacheConfig::default()), None)
213    }
214}
215
216impl Cache {
217    /// Creates a new [`Cache`] instance with optional configuration and database adapter.
218    #[must_use]
219    /// # Note
220    ///
221    /// Uses provided `CacheConfig` or defaults, and optional `CacheDatabaseAdapter` for persistence.
222    ///
223    /// # Panics
224    ///
225    /// Panics if the cache config has a tick or bar capacity outside `[1, 1_000_000]`.
226    pub fn new(
227        config: Option<CacheConfig>,
228        database: Option<Box<dyn CacheDatabaseAdapter>>,
229    ) -> Self {
230        Self::try_new(config, database).expect("invalid `CacheConfig`")
231    }
232
233    /// Creates a new [`Cache`] instance with optional configuration and database adapter.
234    ///
235    /// # Errors
236    ///
237    /// Returns an error if the cache configuration is invalid.
238    pub fn try_new(
239        config: Option<CacheConfig>,
240        database: Option<Box<dyn CacheDatabaseAdapter>>,
241    ) -> crate::config::ConfigResult<Self> {
242        let config = config.unwrap_or_default();
243        config.validate()?;
244
245        Ok(Self {
246            config,
247            index: CacheIndex::default(),
248            database,
249            general: AHashMap::new(),
250            currencies: AHashMap::new(),
251            instruments: AHashMap::new(),
252            instrument_closes: AHashMap::new(),
253            synthetics: AHashMap::new(),
254            books: AHashMap::new(),
255            own_books: AHashMap::new(),
256            quotes: AHashMap::new(),
257            trades: AHashMap::new(),
258            mark_xrates: AHashMap::new(),
259            mark_prices: AHashMap::new(),
260            index_prices: AHashMap::new(),
261            funding_rates: AHashMap::new(),
262            instrument_statuses: AHashMap::new(),
263            bars: AHashMap::new(),
264            greeks: AHashMap::new(),
265            option_greeks: AHashMap::new(),
266            yield_curves: AHashMap::new(),
267            external_order_claims: AHashMap::new(),
268            client_accounts: AHashMap::new(),
269            client_routes: AHashMap::new(),
270            default_client_id: None,
271            external_data_clients: AHashSet::new(),
272            external_exec_clients: AHashSet::new(),
273            accounts: AHashMap::new(),
274            orders: AHashMap::new(),
275            orders_dispatched: AHashSet::new(),
276            order_lists: AHashMap::new(),
277            positions: AHashMap::new(),
278            position_snapshots: AHashMap::new(),
279            position_snapshot_revisions: AHashMap::new(),
280            #[cfg(feature = "defi")]
281            defi: crate::defi::cache::DefiCache::default(),
282        })
283    }
284
285    /// Returns the cache instances memory address.
286    #[must_use]
287    pub fn memory_address(&self) -> String {
288        format!("{:?}", std::ptr::from_ref(self))
289    }
290
291    /// Returns the strategy claiming external orders for `instrument_id`.
292    #[must_use]
293    pub fn external_order_claim(&self, instrument_id: &InstrumentId) -> Option<StrategyId> {
294        self.external_order_claims.get(instrument_id).copied()
295    }
296
297    /// Returns instrument IDs with an external order claim.
298    ///
299    /// Passing `Some(strategy_id)` filters the result to claims owned by that strategy. Passing
300    /// `None` returns every claimed instrument ID.
301    #[must_use]
302    pub fn external_order_claim_instrument_ids(
303        &self,
304        strategy_id: Option<StrategyId>,
305    ) -> AHashSet<InstrumentId> {
306        self.external_order_claims
307            .iter()
308            .filter_map(|(instrument_id, owner)| {
309                strategy_id
310                    .is_none_or(|strategy_id| *owner == strategy_id)
311                    .then_some(*instrument_id)
312            })
313            .collect()
314    }
315
316    /// Replaces the external order claims owned by `strategy_id`.
317    ///
318    /// External orders, fills, and materialized reconciliation activity for matching instrument
319    /// IDs are assigned to the strategy. Existing claims owned by other strategies are preserved.
320    ///
321    /// The operation is atomic: either every requested instrument is claimed or the cache is
322    /// unchanged. Passing an empty slice clears all claims owned by the strategy.
323    ///
324    /// # Errors
325    ///
326    /// Returns an error if an instrument is repeated or claimed by another strategy.
327    pub fn set_external_order_claims(
328        &mut self,
329        strategy_id: StrategyId,
330        instrument_ids: &[InstrumentId],
331    ) -> anyhow::Result<()> {
332        let mut requested = AHashSet::with_capacity(instrument_ids.len());
333
334        for instrument_id in instrument_ids {
335            if !requested.insert(*instrument_id) {
336                anyhow::bail!(
337                    "External order claim for {instrument_id} appears more than once for {strategy_id}"
338                );
339            }
340
341            if let Some(existing) = self.external_order_claims.get(instrument_id)
342                && *existing != strategy_id
343            {
344                anyhow::bail!(
345                    "External order claim for {instrument_id} already exists for {existing}"
346                );
347            }
348        }
349
350        self.external_order_claims
351            .retain(|_, owner| *owner != strategy_id);
352        self.external_order_claims.extend(
353            requested
354                .into_iter()
355                .map(|instrument_id| (instrument_id, strategy_id)),
356        );
357
358        Ok(())
359    }
360
361    /// Adds external order claims for `strategy_id` without replacing its existing claims.
362    ///
363    /// # Errors
364    ///
365    /// Returns an error if an instrument is repeated or already has a claim.
366    pub fn register_external_order_claims(
367        &mut self,
368        strategy_id: StrategyId,
369        instrument_ids: &[InstrumentId],
370    ) -> anyhow::Result<()> {
371        let mut requested = AHashSet::with_capacity(instrument_ids.len());
372
373        for instrument_id in instrument_ids {
374            if !requested.insert(*instrument_id) {
375                anyhow::bail!(
376                    "External order claim for {instrument_id} appears more than once for {strategy_id}"
377                );
378            }
379
380            if let Some(existing) = self.external_order_claims.get(instrument_id) {
381                anyhow::bail!(
382                    "External order claim for {instrument_id} already exists for {existing}"
383                );
384            }
385        }
386
387        self.external_order_claims.extend(
388            requested
389                .into_iter()
390                .map(|instrument_id| (instrument_id, strategy_id)),
391        );
392
393        Ok(())
394    }
395
396    /// Returns the account ID registered for the execution client `client_id`.
397    ///
398    /// The registration does not depend on account issuers or client names. The account itself
399    /// may not be cached yet, for example before the client reports its first account state.
400    #[must_use]
401    pub fn account_id_for_client(&self, client_id: &ClientId) -> Option<&AccountId> {
402        self.client_accounts.get(client_id)
403    }
404
405    /// Registers `account_id` as the account of the execution client `client_id`, replacing any
406    /// previous registration for the client.
407    ///
408    /// Registrations survive [`Self::clear_index`] and [`Self::reset`].
409    pub fn add_client_account(&mut self, client_id: ClientId, account_id: AccountId) {
410        self.client_accounts.insert(client_id, account_id);
411    }
412
413    /// Removes the account registration of the execution client `client_id`.
414    pub fn remove_client_account(&mut self, client_id: &ClientId) {
415        self.client_accounts.remove(client_id);
416    }
417
418    /// Returns the execution client registered as the route for `venue`, else the default client.
419    #[must_use]
420    pub fn client_id_for_venue(&self, venue: &Venue) -> Option<&ClientId> {
421        self.client_routes
422            .get(venue)
423            .or(self.default_client_id.as_ref())
424    }
425
426    /// Registers the execution client `client_id` as the route for commands on `venue`, replacing
427    /// any previous route for the venue.
428    ///
429    /// Routes and the default client survive [`Self::clear_index`] and [`Self::reset`].
430    pub fn add_client_route(&mut self, client_id: ClientId, venue: Venue) {
431        self.client_routes.insert(venue, client_id);
432    }
433
434    /// Registers the execution client `client_id` as the default route for venues without a
435    /// route, replacing any previous default.
436    pub fn set_default_client(&mut self, client_id: ClientId) {
437        self.default_client_id = Some(client_id);
438    }
439
440    /// Removes the venue routes and default route of the execution client `client_id`.
441    pub fn remove_client_routes(&mut self, client_id: &ClientId) {
442        self.client_routes.retain(|_, routed| routed != client_id);
443
444        if self.default_client_id.as_ref() == Some(client_id) {
445            self.default_client_id = None;
446        }
447    }
448
449    /// Returns whether `client_id` is registered as an external data client, whose commands
450    /// are published for another process to execute.
451    #[must_use]
452    pub fn is_external_data_client(&self, client_id: &ClientId) -> bool {
453        self.external_data_clients.contains(client_id)
454    }
455
456    /// Returns whether any external data clients are registered.
457    #[must_use]
458    pub fn has_external_data_clients(&self) -> bool {
459        !self.external_data_clients.is_empty()
460    }
461
462    /// Registers `client_id` as an external data client.
463    ///
464    /// Registrations survive [`Self::clear_index`] and [`Self::reset`].
465    pub fn add_external_data_client(&mut self, client_id: ClientId) {
466        self.external_data_clients.insert(client_id);
467    }
468
469    /// Returns whether `client_id` is registered as an external execution client, whose commands
470    /// are published for another process to execute.
471    #[must_use]
472    pub fn is_external_exec_client(&self, client_id: &ClientId) -> bool {
473        self.external_exec_clients.contains(client_id)
474    }
475
476    /// Registers `client_id` as an external execution client.
477    ///
478    /// Registrations survive [`Self::clear_index`] and [`Self::reset`].
479    pub fn add_external_exec_client(&mut self, client_id: ClientId) {
480        self.external_exec_clients.insert(client_id);
481    }
482
483    /// Sets the cache database adapter for persistence.
484    ///
485    /// This allows setting or replacing the database adapter after cache construction.
486    pub fn set_database(&mut self, database: Box<dyn CacheDatabaseAdapter>) {
487        let type_name = std::any::type_name_of_val(&*database);
488        log::info!("Cache database adapter set: {type_name}");
489        self.database = Some(database);
490    }
491
492    // -- COMMANDS --------------------------------------------------------------------------------
493
494    /// Clears and reloads general entries from the database into the cache.
495    ///
496    /// # Errors
497    ///
498    /// Returns an error if loading general cache data fails.
499    pub fn cache_general(&mut self) -> anyhow::Result<()> {
500        self.general = match &mut self.database {
501            Some(db) => db.load()?,
502            None => AHashMap::new(),
503        };
504
505        log::info!(
506            "Cached {} general object(s) from database",
507            self.general.len()
508        );
509        Ok(())
510    }
511
512    /// Loads all core caches from the database.
513    ///
514    /// The loaded instrument closes, Greeks, and yield curves replace their corresponding maps in
515    /// memory, including values added directly before the persistent cache is loaded.
516    ///
517    /// # Errors
518    ///
519    /// Returns an error if loading cache data fails or a loaded yield curve fails
520    /// [`YieldCurve::validate`].
521    pub async fn cache_all(&mut self) -> anyhow::Result<()> {
522        let mut cache_map = match &self.database {
523            Some(db) => db.load_all().await?,
524            None => CacheMap::default(),
525        };
526
527        for curve in cache_map.yield_curves.values() {
528            curve.validate()?;
529        }
530
531        // An adapter registers the loaded currencies before decoding their dependents; repeating
532        // it here keeps the cached map consistent with the registry whatever the adapter did.
533        register_loaded_currencies(&mut cache_map.currencies)?;
534        #[cfg(feature = "defi")]
535        self.defi.restore_currencies(&cache_map.currencies);
536
537        self.currencies = cache_map.currencies;
538        self.instruments = cache_map.instruments;
539        self.instrument_closes = cache_map.instrument_closes;
540        self.synthetics = cache_map.synthetics;
541        self.greeks = cache_map.greeks;
542        self.yield_curves = cache_map.yield_curves;
543        self.accounts = cache_map
544            .accounts
545            .into_iter()
546            .map(|(id, account)| (id, SharedCell::new(account)))
547            .collect();
548        self.orders = cache_map
549            .orders
550            .into_iter()
551            .map(|(id, order)| (id, SharedCell::new(order)))
552            .collect();
553        self.positions = cache_map
554            .positions
555            .into_iter()
556            .map(|(id, position)| (id, SharedCell::new(position)))
557            .collect();
558
559        if let Some(db) = &self.database {
560            let order_position = db.load_index_order_position()?;
561            self.index.order_position = self.sanitize_order_position_index(order_position);
562            self.index.order_client = db.load_index_order_client()?;
563        }
564
565        self.cache_position_oms()?;
566        self.assign_position_ids_to_contingencies();
567        Ok(())
568    }
569
570    /// Clears and reloads the currency cache from the database.
571    ///
572    /// # Errors
573    ///
574    /// Returns an error if loading currencies cache fails.
575    pub async fn cache_currencies(&mut self) -> anyhow::Result<()> {
576        let mut currencies = match &mut self.database {
577            Some(db) => db.load_currencies().await?,
578            None => AHashMap::new(),
579        };
580
581        register_loaded_currencies(&mut currencies)?;
582        #[cfg(feature = "defi")]
583        self.defi.restore_currencies(&currencies);
584
585        self.currencies = currencies;
586
587        log::info!("Cached {} currencies from database", self.currencies.len());
588        Ok(())
589    }
590
591    /// Clears and reloads the instrument cache from the database.
592    ///
593    /// # Errors
594    ///
595    /// Returns an error if loading instruments cache fails.
596    pub async fn cache_instruments(&mut self) -> anyhow::Result<()> {
597        self.instruments = match &mut self.database {
598            Some(db) => db.load_instruments().await?,
599            None => AHashMap::new(),
600        };
601
602        log::info!("Cached {} instruments from database", self.general.len());
603        Ok(())
604    }
605
606    /// Clears and reloads the synthetic instrument cache from the database.
607    ///
608    /// # Errors
609    ///
610    /// Returns an error if loading synthetic instruments cache fails.
611    pub async fn cache_synthetics(&mut self) -> anyhow::Result<()> {
612        self.synthetics = match &mut self.database {
613            Some(db) => db.load_synthetics().await?,
614            None => AHashMap::new(),
615        };
616
617        log::info!(
618            "Cached {} synthetic instruments from database",
619            self.general.len()
620        );
621        Ok(())
622    }
623
624    /// Clears and reloads the account cache from the database.
625    ///
626    /// # Errors
627    ///
628    /// Returns an error if loading accounts cache fails.
629    pub async fn cache_accounts(&mut self) -> anyhow::Result<()> {
630        self.accounts = match &mut self.database {
631            Some(db) => db
632                .load_accounts()
633                .await?
634                .into_iter()
635                .map(|(id, account)| (id, SharedCell::new(account)))
636                .collect(),
637            None => AHashMap::new(),
638        };
639
640        log::info!(
641            "Cached {} synthetic instruments from database",
642            self.general.len()
643        );
644        Ok(())
645    }
646
647    /// Clears and reloads the order cache from the database.
648    ///
649    /// # Errors
650    ///
651    /// Returns an error if loading orders cache fails.
652    pub async fn cache_orders(&mut self) -> anyhow::Result<()> {
653        self.orders = match &mut self.database {
654            Some(db) => db
655                .load_orders()
656                .await?
657                .into_iter()
658                .map(|(id, order)| (id, SharedCell::new(order)))
659                .collect(),
660            None => AHashMap::new(),
661        };
662
663        if let Some(db) = &self.database {
664            let order_position = db.load_index_order_position()?;
665            self.index.order_position = self.sanitize_order_position_index(order_position);
666            self.index.order_client = db.load_index_order_client()?;
667        }
668
669        log::info!("Cached {} orders from database", self.general.len());
670
671        self.assign_position_ids_to_contingencies();
672        Ok(())
673    }
674
675    fn sanitize_order_position_index(
676        &self,
677        mut order_position: AHashMap<ClientOrderId, PositionId>,
678    ) -> AHashMap<ClientOrderId, PositionId> {
679        let original_len = order_position.len();
680        order_position.retain(|client_order_id, _| self.orders.contains_key(client_order_id));
681        let removed = original_len - order_position.len();
682
683        if removed > 0 {
684            log::warn!(
685                "Filtered {removed} stale order-position index entries without backing orders during cache load"
686            );
687        }
688
689        order_position
690    }
691
692    /// Clears and reloads the position cache from the database.
693    ///
694    /// # Errors
695    ///
696    /// Returns an error if loading positions cache fails.
697    pub async fn cache_positions(&mut self) -> anyhow::Result<()> {
698        self.positions = match &mut self.database {
699            Some(db) => db
700                .load_positions()
701                .await?
702                .into_iter()
703                .map(|(id, position)| (id, SharedCell::new(position)))
704                .collect(),
705            None => AHashMap::new(),
706        };
707
708        self.cache_position_oms()?;
709        log::info!("Cached {} positions from database", self.general.len());
710        Ok(())
711    }
712
713    fn cache_position_oms(&mut self) -> anyhow::Result<()> {
714        let persisted = match &self.database {
715            Some(database) => database.load()?,
716            None => self.general.clone(),
717        };
718
719        self.general
720            .retain(|key, _| !key.starts_with(POSITION_OMS_KEY_PREFIX));
721
722        for (key, value) in persisted {
723            if !key.starts_with(POSITION_OMS_KEY_PREFIX) {
724                continue;
725            }
726            self.general.insert(key, value);
727        }
728
729        self.index_position_oms();
730        Ok(())
731    }
732
733    /// Rebuilds entity-derived indexes from cached accounts, orders, and positions.
734    ///
735    /// Retains venue-order-ID aliases, order-position and order-client mappings, and local
736    /// pending-cancel state only for cached orders. Rebuilding can update mappings from order
737    /// state. Position OMS entries are rebuilt from the general cache.
738    /// Reverse venue-order-ID lookups include historical IDs; forward lookups use the current ID.
739    /// To discard independently maintained index state, call [`Self::clear_index`] before
740    /// reloading entities.
741    pub fn build_index(&mut self) {
742        log::debug!("Building index");
743
744        self.index.clear_entities();
745        self.index
746            .venue_order_ids
747            .retain(|_, client_order_id| self.orders.contains_key(client_order_id));
748        self.index
749            .client_order_ids
750            .retain(|client_order_id, _| self.orders.contains_key(client_order_id));
751        self.index
752            .order_position
753            .retain(|client_order_id, _| self.orders.contains_key(client_order_id));
754        self.index
755            .order_client
756            .retain(|client_order_id, _| self.orders.contains_key(client_order_id));
757        self.index
758            .orders_pending_cancel
759            .retain(|client_order_id| self.orders.contains_key(client_order_id));
760
761        // Index accounts
762        for account_id in self.accounts.keys() {
763            self.index.add_venue_account(*account_id);
764        }
765
766        // Index orders
767        for (client_order_id, order_cell) in &self.orders {
768            let order = order_cell.borrow();
769            let instrument_id = order.instrument_id();
770            let venue = instrument_id.venue;
771            let strategy_id = order.strategy_id();
772
773            // 1: Build index.venue_orders -> {Venue, {ClientOrderId}}
774            self.index
775                .venue_orders
776                .entry(venue)
777                .or_default()
778                .insert(*client_order_id);
779
780            // 2: Build index.venue_order_ids -> {VenueOrderId, ClientOrderId}
781            //    and index.client_order_ids -> {ClientOrderId, VenueOrderId}
782            for venue_order_id in order.venue_order_ids() {
783                self.index
784                    .venue_order_ids
785                    .insert(*venue_order_id, *client_order_id);
786            }
787
788            if let Some(venue_order_id) = order.venue_order_id() {
789                self.index
790                    .client_order_ids
791                    .insert(*client_order_id, venue_order_id);
792            }
793
794            // 3: Build index.order_position -> {ClientOrderId, PositionId}
795            self.index.order_position.extend(
796                order
797                    .position_id()
798                    .map(|position_id| (*client_order_id, position_id)),
799            );
800
801            // 4: Build index.order_strategy -> {ClientOrderId, StrategyId}
802            self.index
803                .order_strategy
804                .insert(*client_order_id, strategy_id);
805
806            // 5: Build index.instrument_orders -> {InstrumentId, {ClientOrderId}}
807            self.index
808                .instrument_orders
809                .entry(instrument_id)
810                .or_default()
811                .insert(*client_order_id);
812
813            // 6: Build index.strategy_orders -> {StrategyId, {ClientOrderId}}
814            self.index
815                .strategy_orders
816                .entry(strategy_id)
817                .or_default()
818                .insert(*client_order_id);
819
820            // 7: Build index.account_orders -> {AccountId, {ClientOrderId}}
821            if let Some(account_id) = order.account_id() {
822                self.index
823                    .account_orders
824                    .entry(account_id)
825                    .or_default()
826                    .insert(*client_order_id);
827            }
828
829            // 8: Build index.exec_algorithm_orders -> {ExecAlgorithmId, {ClientOrderId}}
830            if let Some(exec_algorithm_id) = order.exec_algorithm_id() {
831                self.index
832                    .exec_algorithm_orders
833                    .entry(exec_algorithm_id)
834                    .or_default()
835                    .insert(*client_order_id);
836                self.index.exec_algorithms.insert(exec_algorithm_id);
837            }
838
839            // 9: Build index.exec_spawn_orders -> {ClientOrderId, {ClientOrderId}}
840            if let Some(exec_spawn_id) = order.exec_spawn_id() {
841                self.index
842                    .exec_spawn_orders
843                    .entry(exec_spawn_id)
844                    .or_default()
845                    .insert(*client_order_id);
846            }
847
848            // 10: Build index.orders -> {ClientOrderId}
849            self.index.orders.insert(*client_order_id);
850
851            // 11: Build index.orders_active_local -> {ClientOrderId}
852            if order.is_active_local() {
853                self.index.orders_active_local.insert(*client_order_id);
854            }
855
856            // 12: Build index.orders_open -> {ClientOrderId}
857            if order.is_open() {
858                self.index.orders_open.insert(*client_order_id);
859            }
860
861            // 13: Build index.orders_closed -> {ClientOrderId}
862            if order.is_closed() {
863                self.index.orders_closed.insert(*client_order_id);
864            }
865
866            // 14: Build index.orders_emulated -> {ClientOrderId}
867            if order.emulation_trigger().is_some() && !order.is_closed() {
868                self.index.orders_emulated.insert(*client_order_id);
869            }
870
871            // 15: Build index.orders_inflight -> {ClientOrderId}
872            if order.is_inflight() {
873                self.index.orders_inflight.insert(*client_order_id);
874            }
875
876            // 16: Build index.strategies -> {StrategyId}
877            self.index.strategies.insert(strategy_id);
878        }
879
880        // Index positions
881        for (position_id, position_cell) in &self.positions {
882            let position = position_cell.borrow();
883            let instrument_id = position.instrument_id;
884            let venue = instrument_id.venue;
885            let strategy_id = position.strategy_id;
886
887            // 1: Build index.venue_positions -> {Venue, {PositionId}}
888            self.index
889                .venue_positions
890                .entry(venue)
891                .or_default()
892                .insert(*position_id);
893
894            // 2: Build index.position_strategy -> {PositionId, StrategyId}
895            self.index
896                .position_strategy
897                .insert(*position_id, strategy_id);
898
899            // 3: Build index.position_orders -> {PositionId, {ClientOrderId}}
900            let position_orders = self.index.position_orders.entry(*position_id).or_default();
901            position_orders.extend(
902                position
903                    .client_order_ids()
904                    .into_iter()
905                    .filter(|client_order_id| self.orders.contains_key(client_order_id)),
906            );
907
908            // 4: Build index.instrument_positions -> {InstrumentId, {PositionId}}
909            self.index
910                .instrument_positions
911                .entry(instrument_id)
912                .or_default()
913                .insert(*position_id);
914            self.index
915                .instrument_orders
916                .entry(instrument_id)
917                .or_default();
918
919            // 5: Build index.strategy_positions -> {StrategyId, {PositionId}}
920            self.index
921                .strategy_positions
922                .entry(strategy_id)
923                .or_default()
924                .insert(*position_id);
925            self.index.strategy_orders.entry(strategy_id).or_default();
926
927            // 6: Build index.account_positions -> {AccountId, {PositionId}}
928            self.index
929                .account_positions
930                .entry(position.account_id)
931                .or_default()
932                .insert(*position_id);
933
934            // 7: Build index.positions -> {PositionId}
935            self.index.positions.insert(*position_id);
936
937            // 8: Build index.positions_open -> {PositionId}
938            if position.is_open() {
939                self.index.positions_open.insert(*position_id);
940            }
941
942            // 9: Build index.positions_closed -> {PositionId}
943            if position.is_closed() {
944                self.index.positions_closed.insert(*position_id);
945            }
946
947            // 10: Build index.strategies -> {StrategyId}
948            self.index.strategies.insert(strategy_id);
949        }
950
951        self.index_position_oms();
952        let client_order_ids: Vec<_> = self.orders.keys().copied().collect();
953        for client_order_id in client_order_ids {
954            self.reindex_hedging_position(client_order_id);
955        }
956    }
957
958    fn index_position_oms(&mut self) {
959        self.index.position_oms.clear();
960
961        for (key, value) in &self.general {
962            let Some(position_id) = key.strip_prefix(POSITION_OMS_KEY_PREFIX) else {
963                continue;
964            };
965            let position_id = PositionId::new(position_id);
966            if !self.positions.contains_key(&position_id) {
967                continue;
968            }
969
970            match serde_json::from_slice::<OmsType>(value) {
971                Ok(oms_type) => {
972                    self.index.position_oms.insert(position_id, oms_type);
973                }
974                Err(e) => {
975                    log::error!("Failed to decode position OMS for {position_id}: {e}");
976                }
977            }
978        }
979
980        for position in self.positions.values().map(|cell| cell.borrow()) {
981            if !self.index.position_oms.contains_key(&position.id)
982                && resolve_position_oms(&position, OmsType::Unspecified) == OmsType::Netting
983            {
984                self.index
985                    .position_oms
986                    .insert(position.id, OmsType::Netting);
987            }
988        }
989    }
990
991    /// Returns whether the cache has a backing database.
992    #[must_use]
993    pub const fn has_backing(&self) -> bool {
994        self.database.is_some()
995    }
996
997    /// Loads an instrument from memory, falling back to the database and caching the result.
998    ///
999    /// # Errors
1000    ///
1001    /// Returns an error if loading the instrument fails.
1002    pub fn load_instrument(
1003        &mut self,
1004        instrument_id: &InstrumentId,
1005    ) -> anyhow::Result<Option<InstrumentAny>> {
1006        if let Some(instrument) = self.instruments.get(instrument_id) {
1007            return Ok(Some(instrument.clone()));
1008        }
1009
1010        let Some(database) = &self.database else {
1011            return Ok(None);
1012        };
1013
1014        let instrument = database.load_instrument_sync(instrument_id)?;
1015        if let Some(instrument) = &instrument {
1016            self.instruments.insert(instrument.id(), instrument.clone());
1017        }
1018
1019        Ok(instrument)
1020    }
1021
1022    /// Loads a synthetic from memory, falling back to the database and caching the result.
1023    ///
1024    /// # Errors
1025    ///
1026    /// Returns an error if the ID is not synthetic or loading the instrument fails.
1027    pub fn load_synthetic(
1028        &mut self,
1029        instrument_id: &InstrumentId,
1030    ) -> anyhow::Result<Option<SyntheticInstrument>> {
1031        anyhow::ensure!(
1032            instrument_id.is_synthetic(),
1033            "Instrument ID is not synthetic: {instrument_id}"
1034        );
1035
1036        if let Some(synthetic) = self.synthetics.get(instrument_id) {
1037            return Ok(Some(synthetic.clone()));
1038        }
1039
1040        let Some(database) = &self.database else {
1041            return Ok(None);
1042        };
1043
1044        let synthetic = database.load_synthetic_sync(instrument_id)?;
1045        if let Some(synthetic) = &synthetic {
1046            self.synthetics.insert(synthetic.id, synthetic.clone());
1047        }
1048
1049        Ok(synthetic)
1050    }
1051
1052    /// Deletes persisted actor state. Does nothing without a database.
1053    ///
1054    /// Persistence failures are logged without failing the operation.
1055    ///
1056    /// # Errors
1057    ///
1058    /// Returns an error if the backing reports a DeFi currency integrity error.
1059    pub fn delete_actor(&self, actor_id: &ActorId) -> anyhow::Result<()> {
1060        if let Some(database) = &self.database {
1061            handle_persistence_result(
1062                format_args!("delete actor state {actor_id}"),
1063                database.delete_actor(actor_id),
1064            )?;
1065        }
1066
1067        Ok(())
1068    }
1069
1070    /// Deletes persisted strategy state. Does nothing without a database.
1071    ///
1072    /// Persistence failures are logged without failing the operation.
1073    ///
1074    /// # Errors
1075    ///
1076    /// Returns an error if the backing reports a DeFi currency integrity error.
1077    pub fn delete_strategy(&self, strategy_id: &StrategyId) -> anyhow::Result<()> {
1078        if let Some(database) = &self.database {
1079            handle_persistence_result(
1080                format_args!("delete strategy state {strategy_id}"),
1081                database.delete_strategy(strategy_id),
1082            )?;
1083        }
1084
1085        Ok(())
1086    }
1087
1088    /// Persists the heartbeat timestamp. Does nothing without a database.
1089    ///
1090    /// Persistence failures are logged without failing the operation.
1091    ///
1092    /// # Errors
1093    ///
1094    /// Returns an error if the backing reports a DeFi currency integrity error.
1095    pub fn heartbeat(&self, timestamp: UnixNanos) -> anyhow::Result<()> {
1096        if let Some(database) = &self.database {
1097            handle_persistence_result(
1098                format_args!("persist heartbeat {timestamp}"),
1099                database.heartbeat(timestamp),
1100            )?;
1101        }
1102
1103        Ok(())
1104    }
1105
1106    /// Loads persisted actor state.
1107    ///
1108    /// Returns `None` when the cache has no backing database.
1109    ///
1110    /// # Errors
1111    ///
1112    /// Returns an error if loading actor state fails.
1113    pub fn load_actor_state(
1114        &self,
1115        actor_id: &ActorId,
1116    ) -> anyhow::Result<Option<IndexMap<String, Vec<u8>>>> {
1117        self.database
1118            .as_ref()
1119            .map(|database| database.load_actor(actor_id))
1120            .transpose()
1121            .map(|state| state.map(Self::decode_component_state))
1122    }
1123
1124    /// Loads persisted strategy state.
1125    ///
1126    /// Returns `None` when the cache has no backing database.
1127    ///
1128    /// # Errors
1129    ///
1130    /// Returns an error if loading strategy state fails.
1131    pub fn load_strategy_state(
1132        &self,
1133        strategy_id: &StrategyId,
1134    ) -> anyhow::Result<Option<IndexMap<String, Vec<u8>>>> {
1135        self.database
1136            .as_ref()
1137            .map(|database| database.load_strategy(strategy_id))
1138            .transpose()
1139            .map(|state| state.map(Self::decode_component_state))
1140    }
1141
1142    /// Persists actor state when the cache has a backing database.
1143    ///
1144    /// Persistence failures are logged without failing the operation.
1145    ///
1146    /// # Errors
1147    ///
1148    /// Returns an error if the backing reports a DeFi currency integrity error.
1149    pub fn update_actor_state(
1150        &self,
1151        actor_id: &ActorId,
1152        state: &IndexMap<String, Vec<u8>>,
1153    ) -> anyhow::Result<()> {
1154        if let Some(database) = &self.database {
1155            handle_persistence_result(
1156                format_args!("persist actor state {actor_id}"),
1157                database.update_actor(actor_id, &Self::encode_component_state(state)),
1158            )?;
1159        }
1160        Ok(())
1161    }
1162
1163    /// Persists strategy state when the cache has a backing database.
1164    ///
1165    /// Persistence failures are logged without failing the operation.
1166    ///
1167    /// # Errors
1168    ///
1169    /// Returns an error if the backing reports a DeFi currency integrity error.
1170    pub fn update_strategy_state(
1171        &self,
1172        strategy_id: &StrategyId,
1173        state: &IndexMap<String, Vec<u8>>,
1174    ) -> anyhow::Result<()> {
1175        if let Some(database) = &self.database {
1176            handle_persistence_result(
1177                format_args!("persist strategy state {strategy_id}"),
1178                database.update_strategy(strategy_id, &Self::encode_component_state(state)),
1179            )?;
1180        }
1181        Ok(())
1182    }
1183
1184    fn decode_component_state(state: AHashMap<String, Bytes>) -> IndexMap<String, Vec<u8>> {
1185        state
1186            .into_iter()
1187            .map(|(key, value)| (key, value.to_vec()))
1188            .collect()
1189    }
1190
1191    fn encode_component_state(state: &IndexMap<String, Vec<u8>>) -> AHashMap<String, Bytes> {
1192        state
1193            .iter()
1194            .map(|(key, value)| (key.clone(), Bytes::copy_from_slice(value)))
1195            .collect()
1196    }
1197
1198    // Calculate the unrealized profit and loss (PnL) for `position`.
1199    #[must_use]
1200    pub fn calculate_unrealized_pnl(&self, position: &Position) -> Option<Money> {
1201        let Some(quote) = self.quote(&position.instrument_id) else {
1202            log::warn!(
1203                "Cannot calculate unrealized PnL for {}, no quotes for {}",
1204                position.id,
1205                position.instrument_id
1206            );
1207            return None;
1208        };
1209
1210        // Use exit price for mark-to-market: longs exit at bid, shorts exit at ask
1211        let last = match position.side {
1212            PositionSide::Flat => {
1213                return Some(Money::zero(position.settlement_currency));
1214            }
1215            PositionSide::Long => quote.bid_price,
1216            PositionSide::Short => quote.ask_price,
1217        };
1218
1219        position
1220            .try_unrealized_pnl(last)
1221            .inspect_err(|e| {
1222                log::error!("Cannot calculate unrealized PnL for {}: {e}", position.id);
1223            })
1224            .ok()
1225    }
1226
1227    /// Checks integrity of data within the cache.
1228    ///
1229    /// All data should be loaded from the database prior to this call.
1230    /// If an error is found then a log error message will also be produced.
1231    ///
1232    /// # Panics
1233    ///
1234    /// Panics if failure calling system clock.
1235    #[must_use]
1236    pub fn check_integrity(&mut self) -> bool {
1237        let mut error_count = 0;
1238        let failure = "Integrity failure";
1239
1240        // Get current timestamp in microseconds
1241        let timestamp_us = SystemTime::now()
1242            .duration_since(UNIX_EPOCH)
1243            .expect("Time went backwards")
1244            .as_micros();
1245
1246        log::info!("Checking data integrity");
1247
1248        // Check object caches
1249        for account_id in self.accounts.keys() {
1250            if !self
1251                .index
1252                .venue_accounts
1253                .get(&account_id.get_issuer())
1254                .is_some_and(|account_ids| account_ids.contains(account_id))
1255            {
1256                log::error!(
1257                    "{failure} in accounts: {account_id} not found in `self.index.venue_accounts`",
1258                );
1259                error_count += 1;
1260            }
1261        }
1262
1263        for (client_order_id, order_cell) in &self.orders {
1264            let order = order_cell.borrow();
1265
1266            if !self.index.order_strategy.contains_key(client_order_id) {
1267                log::error!(
1268                    "{failure} in orders: {client_order_id} not found in `self.index.order_strategy`"
1269                );
1270                error_count += 1;
1271            }
1272
1273            if !self.index.orders.contains(client_order_id) {
1274                log::error!(
1275                    "{failure} in orders: {client_order_id} not found in `self.index.orders`",
1276                );
1277                error_count += 1;
1278            }
1279
1280            if order.is_inflight() && !self.index.orders_inflight.contains(client_order_id) {
1281                log::error!(
1282                    "{failure} in orders: {client_order_id} not found in `self.index.orders_inflight`",
1283                );
1284                error_count += 1;
1285            }
1286
1287            if order.is_active_local() && !self.index.orders_active_local.contains(client_order_id)
1288            {
1289                log::error!(
1290                    "{failure} in orders: {client_order_id} not found in `self.index.orders_active_local`",
1291                );
1292                error_count += 1;
1293            }
1294
1295            if order.is_open() && !self.index.orders_open.contains(client_order_id) {
1296                log::error!(
1297                    "{failure} in orders: {client_order_id} not found in `self.index.orders_open`",
1298                );
1299                error_count += 1;
1300            }
1301
1302            if order.is_closed() && !self.index.orders_closed.contains(client_order_id) {
1303                log::error!(
1304                    "{failure} in orders: {client_order_id} not found in `self.index.orders_closed`",
1305                );
1306                error_count += 1;
1307            }
1308
1309            if let Some(exec_algorithm_id) = order.exec_algorithm_id() {
1310                if !self
1311                    .index
1312                    .exec_algorithm_orders
1313                    .contains_key(&exec_algorithm_id)
1314                {
1315                    log::error!(
1316                        "{failure} in orders: {client_order_id} not found in `self.index.exec_algorithm_orders`",
1317                    );
1318                    error_count += 1;
1319                }
1320
1321                if order.exec_spawn_id().is_none()
1322                    && !self.index.exec_spawn_orders.contains_key(client_order_id)
1323                {
1324                    log::error!(
1325                        "{failure} in orders: {client_order_id} not found in `self.index.exec_spawn_orders`",
1326                    );
1327                    error_count += 1;
1328                }
1329            }
1330        }
1331
1332        for (position_id, position_cell) in &self.positions {
1333            let position = position_cell.borrow();
1334
1335            if !self.index.position_strategy.contains_key(position_id) {
1336                log::error!(
1337                    "{failure} in positions: {position_id} not found in `self.index.position_strategy`",
1338                );
1339                error_count += 1;
1340            }
1341
1342            if !self.index.position_orders.contains_key(position_id) {
1343                log::error!(
1344                    "{failure} in positions: {position_id} not found in `self.index.position_orders`",
1345                );
1346                error_count += 1;
1347            }
1348
1349            if !self.index.positions.contains(position_id) {
1350                log::error!(
1351                    "{failure} in positions: {position_id} not found in `self.index.positions`",
1352                );
1353                error_count += 1;
1354            }
1355
1356            if position.is_open() && !self.index.positions_open.contains(position_id) {
1357                log::error!(
1358                    "{failure} in positions: {position_id} not found in `self.index.positions_open`",
1359                );
1360                error_count += 1;
1361            }
1362
1363            if position.is_closed() && !self.index.positions_closed.contains(position_id) {
1364                log::error!(
1365                    "{failure} in positions: {position_id} not found in `self.index.positions_closed`",
1366                );
1367                error_count += 1;
1368            }
1369        }
1370
1371        // Check indexes
1372        for account_id in self.index.venue_accounts.values().flatten() {
1373            if !self.accounts.contains_key(account_id) {
1374                log::error!(
1375                    "{failure} in `index.venue_accounts`: {account_id} not found in `self.accounts`",
1376                );
1377                error_count += 1;
1378            }
1379        }
1380
1381        for client_order_id in self.index.venue_order_ids.values() {
1382            if !self.orders.contains_key(client_order_id) {
1383                log::error!(
1384                    "{failure} in `index.venue_order_ids`: {client_order_id} not found in `self.orders`",
1385                );
1386                error_count += 1;
1387            }
1388        }
1389
1390        for client_order_id in self.index.client_order_ids.keys() {
1391            if !self.orders.contains_key(client_order_id) {
1392                log::error!(
1393                    "{failure} in `index.client_order_ids`: {client_order_id} not found in `self.orders`",
1394                );
1395                error_count += 1;
1396            }
1397        }
1398
1399        for client_order_id in self.index.order_position.keys() {
1400            if !self.orders.contains_key(client_order_id) {
1401                log::error!(
1402                    "{failure} in `index.order_position`: {client_order_id} not found in `self.orders`",
1403                );
1404                error_count += 1;
1405            }
1406        }
1407
1408        // Check indexes
1409        for client_order_id in self.index.order_strategy.keys() {
1410            if !self.orders.contains_key(client_order_id) {
1411                log::error!(
1412                    "{failure} in `index.order_strategy`: {client_order_id} not found in `self.orders`",
1413                );
1414                error_count += 1;
1415            }
1416        }
1417
1418        for position_id in self.index.position_strategy.keys() {
1419            if !self.positions.contains_key(position_id) {
1420                log::error!(
1421                    "{failure} in `index.position_strategy`: {position_id} not found in `self.positions`",
1422                );
1423                error_count += 1;
1424            }
1425        }
1426
1427        for position_id in self.index.position_orders.keys() {
1428            if !self.positions.contains_key(position_id) {
1429                log::error!(
1430                    "{failure} in `index.position_orders`: {position_id} not found in `self.positions`",
1431                );
1432                error_count += 1;
1433            }
1434        }
1435
1436        for (instrument_id, client_order_ids) in &self.index.instrument_orders {
1437            for client_order_id in client_order_ids {
1438                if !self.orders.contains_key(client_order_id) {
1439                    log::error!(
1440                        "{failure} in `index.instrument_orders`: {instrument_id} not found in `self.orders`",
1441                    );
1442                    error_count += 1;
1443                }
1444            }
1445        }
1446
1447        for instrument_id in self.index.instrument_positions.keys() {
1448            if !self.index.instrument_orders.contains_key(instrument_id) {
1449                log::error!(
1450                    "{failure} in `index.instrument_positions`: {instrument_id} not found in `index.instrument_orders`",
1451                );
1452                error_count += 1;
1453            }
1454        }
1455
1456        for client_order_ids in self.index.strategy_orders.values() {
1457            for client_order_id in client_order_ids {
1458                if !self.orders.contains_key(client_order_id) {
1459                    log::error!(
1460                        "{failure} in `index.strategy_orders`: {client_order_id} not found in `self.orders`",
1461                    );
1462                    error_count += 1;
1463                }
1464            }
1465        }
1466
1467        for position_ids in self.index.strategy_positions.values() {
1468            for position_id in position_ids {
1469                if !self.positions.contains_key(position_id) {
1470                    log::error!(
1471                        "{failure} in `index.strategy_positions`: {position_id} not found in `self.positions`",
1472                    );
1473                    error_count += 1;
1474                }
1475            }
1476        }
1477
1478        for client_order_id in &self.index.orders {
1479            if !self.orders.contains_key(client_order_id) {
1480                log::error!(
1481                    "{failure} in `index.orders`: {client_order_id} not found in `self.orders`",
1482                );
1483                error_count += 1;
1484            }
1485        }
1486
1487        for client_order_id in &self.index.orders_emulated {
1488            if !self.orders.contains_key(client_order_id) {
1489                log::error!(
1490                    "{failure} in `index.orders_emulated`: {client_order_id} not found in `self.orders`",
1491                );
1492                error_count += 1;
1493            }
1494        }
1495
1496        for client_order_id in &self.index.orders_active_local {
1497            if !self.orders.contains_key(client_order_id) {
1498                log::error!(
1499                    "{failure} in `index.orders_active_local`: {client_order_id} not found in `self.orders`",
1500                );
1501                error_count += 1;
1502            }
1503        }
1504
1505        for client_order_id in &self.index.orders_inflight {
1506            if !self.orders.contains_key(client_order_id) {
1507                log::error!(
1508                    "{failure} in `index.orders_inflight`: {client_order_id} not found in `self.orders`",
1509                );
1510                error_count += 1;
1511            }
1512        }
1513
1514        for client_order_id in &self.index.orders_open {
1515            if !self.orders.contains_key(client_order_id) {
1516                log::error!(
1517                    "{failure} in `index.orders_open`: {client_order_id} not found in `self.orders`",
1518                );
1519                error_count += 1;
1520            }
1521        }
1522
1523        for client_order_id in &self.index.orders_closed {
1524            if !self.orders.contains_key(client_order_id) {
1525                log::error!(
1526                    "{failure} in `index.orders_closed`: {client_order_id} not found in `self.orders`",
1527                );
1528                error_count += 1;
1529            }
1530        }
1531
1532        for position_id in &self.index.positions {
1533            if !self.positions.contains_key(position_id) {
1534                log::error!(
1535                    "{failure} in `index.positions`: {position_id} not found in `self.positions`",
1536                );
1537                error_count += 1;
1538            }
1539        }
1540
1541        for position_id in &self.index.positions_open {
1542            if !self.positions.contains_key(position_id) {
1543                log::error!(
1544                    "{failure} in `index.positions_open`: {position_id} not found in `self.positions`",
1545                );
1546                error_count += 1;
1547            }
1548        }
1549
1550        for position_id in &self.index.positions_closed {
1551            if !self.positions.contains_key(position_id) {
1552                log::error!(
1553                    "{failure} in `index.positions_closed`: {position_id} not found in `self.positions`",
1554                );
1555                error_count += 1;
1556            }
1557        }
1558
1559        for strategy_id in &self.index.strategies {
1560            if !self.index.strategy_orders.contains_key(strategy_id) {
1561                log::error!(
1562                    "{failure} in `index.strategies`: {strategy_id} not found in `index.strategy_orders`",
1563                );
1564                error_count += 1;
1565            }
1566        }
1567
1568        for exec_algorithm_id in &self.index.exec_algorithms {
1569            if !self
1570                .index
1571                .exec_algorithm_orders
1572                .contains_key(exec_algorithm_id)
1573            {
1574                log::error!(
1575                    "{failure} in `index.exec_algorithms`: {exec_algorithm_id} not found in `index.exec_algorithm_orders`",
1576                );
1577                error_count += 1;
1578            }
1579        }
1580
1581        let total_us = SystemTime::now()
1582            .duration_since(UNIX_EPOCH)
1583            .expect("Time went backwards")
1584            .as_micros()
1585            - timestamp_us;
1586
1587        if error_count == 0 {
1588            log::info!("Integrity check passed in {total_us}μs");
1589            true
1590        } else {
1591            log::error!(
1592                "Integrity check failed with {error_count} error{} in {total_us}μs",
1593                if error_count == 1 { "" } else { "s" },
1594            );
1595            false
1596        }
1597    }
1598
1599    /// Checks for any residual open state and log warnings if any are found.
1600    ///
1601    ///'Open state' is considered to be open orders and open positions.
1602    #[must_use]
1603    pub fn check_residuals(&self) -> bool {
1604        log::debug!("Checking residuals");
1605
1606        let mut residuals = false;
1607
1608        // Check for any open orders
1609        for order in self.orders_open(None, None, None, None, None) {
1610            residuals = true;
1611            log::warn!("Residual {order}");
1612        }
1613
1614        // Check for any open positions
1615        for position in self.positions_open(None, None, None, None, None) {
1616            residuals = true;
1617            log::warn!("Residual {position}");
1618        }
1619
1620        residuals
1621    }
1622
1623    /// Purges all closed orders from the cache that are older than `buffer_secs`.
1624    ///
1625    ///
1626    /// Only orders that have been closed for at least this amount of time will be purged.
1627    /// A value of 0 means purge all closed orders regardless of when they were closed.
1628    ///
1629    /// When `purge_from_database` is true, also requests deletion from the backing database.
1630    ///
1631    /// Persistence failures are logged without failing the operation.
1632    ///
1633    /// # Errors
1634    ///
1635    /// Returns an error if the backing reports a DeFi currency integrity error.
1636    pub fn purge_closed_orders(
1637        &mut self,
1638        ts_now: UnixNanos,
1639        buffer_secs: u64,
1640        purge_from_database: bool,
1641    ) -> anyhow::Result<()> {
1642        log::debug!(
1643            "Purging closed orders{}",
1644            if buffer_secs > 0 {
1645                format!(" with buffer_secs={buffer_secs}")
1646            } else {
1647                String::new()
1648            }
1649        );
1650
1651        let Ok(buffer_ns) = DurationNanos::try_from_secs(buffer_secs) else {
1652            log::warn!(
1653                "Cannot purge closed orders: buffer_secs {buffer_secs} is not representable in `u64` nanoseconds"
1654            );
1655            return Ok(());
1656        };
1657        let purge_cutoff = ts_now.checked_sub(buffer_ns);
1658
1659        let mut affected_order_list_ids: AHashSet<OrderListId> = AHashSet::new();
1660        let mut purged_client_order_ids: AHashSet<ClientOrderId> = AHashSet::new();
1661        let mut result = Ok(());
1662
1663        'outer: for client_order_id in self.index.orders_closed.clone() {
1664            let purge_target = self.orders.get(&client_order_id).and_then(|order_cell| {
1665                let order = order_cell.borrow();
1666                if order.is_closed()
1667                    && let Some(ts_closed) = order.ts_closed()
1668                    && purge_cutoff.is_some_and(|cutoff| ts_closed <= cutoff)
1669                {
1670                    let linked = order.linked_order_ids().map(<[_]>::to_vec);
1671                    let order_list_id = order.order_list_id();
1672                    Some((linked, order_list_id))
1673                } else {
1674                    None
1675                }
1676            });
1677
1678            let Some((linked, order_list_id)) = purge_target else {
1679                continue;
1680            };
1681
1682            // Check any linked orders (contingency orders)
1683            if let Some(linked_order_ids) = linked {
1684                for linked_order_id in &linked_order_ids {
1685                    if let Some(linked_order_cell) = self.orders.get(linked_order_id)
1686                        && linked_order_cell.borrow().is_open()
1687                    {
1688                        // Do not purge if linked order still open
1689                        continue 'outer;
1690                    }
1691                }
1692            }
1693
1694            if let Some(order_list_id) = order_list_id {
1695                affected_order_list_ids.insert(order_list_id);
1696            }
1697
1698            match self.purge_order_checked(client_order_id, purge_from_database) {
1699                Ok(true) => {
1700                    purged_client_order_ids.insert(client_order_id);
1701                }
1702                Ok(false) => {}
1703                Err(e) => {
1704                    result = Err(e);
1705                    break;
1706                }
1707            }
1708        }
1709
1710        if !purged_client_order_ids.is_empty() {
1711            self.index
1712                .venue_order_ids
1713                .retain(|_, owner| !purged_client_order_ids.contains(owner));
1714        }
1715
1716        for order_list_id in affected_order_list_ids {
1717            if let Some(order_list) = self.order_lists.get(&order_list_id) {
1718                let all_purged = order_list
1719                    .client_order_ids
1720                    .iter()
1721                    .all(|id| !self.orders.contains_key(id));
1722
1723                if all_purged {
1724                    self.order_lists.remove(&order_list_id);
1725                    log::info!("Purged {order_list_id}");
1726                }
1727            }
1728        }
1729
1730        result
1731    }
1732
1733    /// Purges all closed positions from the cache that are older than `buffer_secs`.
1734    ///
1735    /// When `purge_from_database` is true, also requests deletion from the backing database.
1736    ///
1737    /// Persistence failures are logged without failing the operation.
1738    ///
1739    /// # Errors
1740    ///
1741    /// Returns an error if the backing reports a DeFi currency integrity error.
1742    pub fn purge_closed_positions(
1743        &mut self,
1744        ts_now: UnixNanos,
1745        buffer_secs: u64,
1746        purge_from_database: bool,
1747    ) -> anyhow::Result<()> {
1748        log::debug!(
1749            "Purging closed positions{}",
1750            if buffer_secs > 0 {
1751                format!(" with buffer_secs={buffer_secs}")
1752            } else {
1753                String::new()
1754            }
1755        );
1756
1757        let Ok(buffer_ns) = DurationNanos::try_from_secs(buffer_secs) else {
1758            log::warn!(
1759                "Cannot purge closed positions: buffer_secs {buffer_secs} is not representable in `u64` nanoseconds"
1760            );
1761            return Ok(());
1762        };
1763        let purge_cutoff = ts_now.checked_sub(buffer_ns);
1764
1765        for position_id in self.index.positions_closed.clone() {
1766            let should_purge = self.positions.get(&position_id).is_some_and(|cell| {
1767                let position = cell.borrow();
1768                position.is_closed()
1769                    && position.ts_closed.is_some_and(|ts_closed| {
1770                        purge_cutoff.is_some_and(|cutoff| ts_closed <= cutoff)
1771                    })
1772            });
1773
1774            if should_purge {
1775                self.purge_position(position_id, purge_from_database)?;
1776            }
1777        }
1778
1779        Ok(())
1780    }
1781
1782    /// Purges the order with the `client_order_id` from the cache (if found).
1783    ///
1784    /// For safety, an order is prevented from being purged if it's open.
1785    ///
1786    /// When `purge_from_database` is true, also requests deletion from the backing database.
1787    ///
1788    /// Persistence failures are logged without failing the operation.
1789    ///
1790    /// # Errors
1791    ///
1792    /// Returns an error if the backing reports a DeFi currency integrity error.
1793    pub fn purge_order(
1794        &mut self,
1795        client_order_id: ClientOrderId,
1796        purge_from_database: bool,
1797    ) -> anyhow::Result<()> {
1798        if self.purge_order_checked(client_order_id, purge_from_database)? {
1799            self.index
1800                .venue_order_ids
1801                .retain(|_, owner| owner != &client_order_id);
1802        }
1803
1804        Ok(())
1805    }
1806
1807    fn purge_order_checked(
1808        &mut self,
1809        client_order_id: ClientOrderId,
1810        purge_from_database: bool,
1811    ) -> anyhow::Result<bool> {
1812        if purge_from_database
1813            && let Some(database) = &self.database
1814            && self
1815                .orders
1816                .get(&client_order_id)
1817                .is_none_or(|order| !order.borrow().is_open())
1818        {
1819            handle_persistence_result(
1820                format_args!("delete order {client_order_id}"),
1821                database.delete_order(&client_order_id),
1822            )?;
1823        }
1824
1825        Ok(self.purge_order_except_aliases(client_order_id))
1826    }
1827
1828    /// Removes the order and its indexes, leaving the reverse venue order ID aliases for the
1829    /// caller to sweep by owner, so a bulk purge pays for one pass rather than one pass per order.
1830    ///
1831    /// Returns whether the order was purged, so a skipped purge leaves its aliases intact.
1832    fn purge_order_except_aliases(&mut self, client_order_id: ClientOrderId) -> bool {
1833        struct OrderDetails {
1834            is_open: bool,
1835            instrument_id: InstrumentId,
1836            strategy_id: StrategyId,
1837            account_id: Option<AccountId>,
1838            exec_algorithm_id: Option<ExecAlgorithmId>,
1839            exec_spawn_id: Option<ClientOrderId>,
1840            position_id: Option<PositionId>,
1841        }
1842
1843        let order_cell = self.orders.get(&client_order_id).cloned();
1844        let order_details = order_cell.as_ref().map(|cell| {
1845            let order = cell.borrow();
1846            OrderDetails {
1847                is_open: order.is_open(),
1848                instrument_id: order.instrument_id(),
1849                strategy_id: order.strategy_id(),
1850                account_id: order.account_id(),
1851                exec_algorithm_id: order.exec_algorithm_id(),
1852                exec_spawn_id: order.exec_spawn_id(),
1853                position_id: order.position_id(),
1854            }
1855        });
1856
1857        if order_details
1858            .as_ref()
1859            .is_some_and(|details| details.is_open)
1860        {
1861            log::warn!("Order {client_order_id} found open when purging, skipping purge");
1862            return false;
1863        }
1864
1865        if order_details.is_some() {
1866            self.orders.remove(&client_order_id);
1867        } else {
1868            log::warn!("Order {client_order_id} not found when purging");
1869        }
1870
1871        let indexed_position_id = self.index.order_position.remove(&client_order_id);
1872        let indexed_strategy_id = self.index.order_strategy.remove(&client_order_id);
1873        self.index.order_client.remove(&client_order_id);
1874        self.index.client_order_ids.remove(&client_order_id);
1875
1876        if let Some(details) = &order_details {
1877            if let Some(venue_orders) = self
1878                .index
1879                .venue_orders
1880                .get_mut(&details.instrument_id.venue)
1881            {
1882                venue_orders.remove(&client_order_id);
1883                if venue_orders.is_empty() {
1884                    self.index.venue_orders.remove(&details.instrument_id.venue);
1885                }
1886            }
1887
1888            // As with the strategy buckets below, an absent bucket is left absent: recreating
1889            // it would suppress the `index.instrument_positions` integrity check.
1890            // As with the strategy buckets below, an absent bucket is left absent: recreating
1891            // it would suppress the `index.instrument_positions` integrity check.
1892            let instrument_orders_became_empty = self
1893                .index
1894                .instrument_orders
1895                .get_mut(&details.instrument_id)
1896                .is_some_and(|instrument_orders| {
1897                    instrument_orders.remove(&client_order_id);
1898                    instrument_orders.is_empty()
1899                });
1900
1901            let has_instrument_positions = self
1902                .index
1903                .instrument_positions
1904                .get(&details.instrument_id)
1905                .is_some_and(|positions| !positions.is_empty());
1906
1907            if instrument_orders_became_empty && !has_instrument_positions {
1908                self.index.instrument_orders.remove(&details.instrument_id);
1909            }
1910
1911            if let Some(exec_algorithm_id) = details.exec_algorithm_id {
1912                let became_empty = self
1913                    .index
1914                    .exec_algorithm_orders
1915                    .get_mut(&exec_algorithm_id)
1916                    .is_some_and(|orders| {
1917                        orders.remove(&client_order_id);
1918                        orders.is_empty()
1919                    });
1920
1921                if became_empty {
1922                    self.index.exec_algorithm_orders.remove(&exec_algorithm_id);
1923                    self.index.exec_algorithms.remove(&exec_algorithm_id);
1924                }
1925            }
1926
1927            if let Some(account_id) = details.account_id
1928                && let Some(account_orders) = self.index.account_orders.get_mut(&account_id)
1929            {
1930                account_orders.remove(&client_order_id);
1931                if account_orders.is_empty() {
1932                    self.index.account_orders.remove(&account_id);
1933                }
1934            }
1935
1936            if let Some(exec_spawn_id) = details.exec_spawn_id
1937                && let Some(spawn_orders) = self.index.exec_spawn_orders.get_mut(&exec_spawn_id)
1938            {
1939                spawn_orders.remove(&client_order_id);
1940                if spawn_orders.is_empty() {
1941                    self.index.exec_spawn_orders.remove(&exec_spawn_id);
1942                }
1943            }
1944        }
1945
1946        let mut position_ids = AHashSet::new();
1947        if let Some(position_id) = indexed_position_id {
1948            position_ids.insert(position_id);
1949        }
1950
1951        if let Some(position_id) = order_details
1952            .as_ref()
1953            .and_then(|details| details.position_id)
1954        {
1955            position_ids.insert(position_id);
1956        }
1957
1958        let mut strategy_ids = AHashSet::new();
1959        if let Some(strategy_id) = indexed_strategy_id {
1960            strategy_ids.insert(strategy_id);
1961        }
1962
1963        if let Some(details) = &order_details {
1964            strategy_ids.insert(details.strategy_id);
1965        }
1966
1967        for position_id in position_ids {
1968            if self.positions.contains_key(&position_id) {
1969                if let Some(position_orders) = self.index.position_orders.get_mut(&position_id) {
1970                    position_orders.remove(&client_order_id);
1971                }
1972                continue;
1973            }
1974
1975            let has_other_orders =
1976                if let Some(position_orders) = self.index.position_orders.get_mut(&position_id) {
1977                    position_orders.remove(&client_order_id);
1978                    !position_orders.is_empty()
1979                } else {
1980                    self.index
1981                        .order_position
1982                        .values()
1983                        .any(|candidate| *candidate == position_id)
1984                };
1985
1986            if has_other_orders {
1987                continue;
1988            }
1989
1990            self.index.position_orders.remove(&position_id);
1991            if let Some(strategy_id) = self.index.position_strategy.remove(&position_id) {
1992                strategy_ids.insert(strategy_id);
1993                if let Some(strategy_positions) =
1994                    self.index.strategy_positions.get_mut(&strategy_id)
1995                {
1996                    strategy_positions.remove(&position_id);
1997                    if strategy_positions.is_empty() {
1998                        self.index.strategy_positions.remove(&strategy_id);
1999                    }
2000                }
2001            }
2002
2003            if let Some(details) = &order_details
2004                && let Some(venue_positions) = self
2005                    .index
2006                    .venue_positions
2007                    .get_mut(&details.instrument_id.venue)
2008            {
2009                venue_positions.remove(&position_id);
2010                if venue_positions.is_empty() {
2011                    self.index
2012                        .venue_positions
2013                        .remove(&details.instrument_id.venue);
2014                }
2015            }
2016        }
2017
2018        for strategy_id in strategy_ids {
2019            // An absent reverse bucket is not an empty one: it means the index is already
2020            // inconsistent, possibly while another cached order still uses this strategy.
2021            // Retiring the registry entry here would both drop a live strategy from
2022            // `strategy_ids` and stop `check_integrity` reporting the missing bucket, so the
2023            // absent case is left exactly as found.
2024            let strategy_orders_became_empty = self
2025                .index
2026                .strategy_orders
2027                .get_mut(&strategy_id)
2028                .is_some_and(|strategy_orders| {
2029                    strategy_orders.remove(&client_order_id);
2030                    strategy_orders.is_empty()
2031                });
2032
2033            let has_positions = self
2034                .index
2035                .strategy_positions
2036                .get(&strategy_id)
2037                .is_some_and(|strategy_positions| !strategy_positions.is_empty());
2038
2039            if strategy_orders_became_empty && !has_positions {
2040                self.index.strategy_orders.remove(&strategy_id);
2041                self.index.strategies.remove(&strategy_id);
2042            }
2043        }
2044
2045        self.index.exec_spawn_orders.remove(&client_order_id);
2046
2047        self.index.orders.remove(&client_order_id);
2048        self.index.orders_active_local.remove(&client_order_id);
2049        self.index.orders_open.remove(&client_order_id);
2050        self.index.orders_closed.remove(&client_order_id);
2051        self.index.orders_emulated.remove(&client_order_id);
2052        self.index.orders_inflight.remove(&client_order_id);
2053        self.index.orders_pending_cancel.remove(&client_order_id);
2054
2055        if order_details.is_some() {
2056            log::info!("Purged order {client_order_id}");
2057        }
2058
2059        true
2060    }
2061
2062    /// Purges the position with the `position_id` from the cache (if found).
2063    ///
2064    /// For safety, a position is prevented from being purged if it's open.
2065    ///
2066    /// When `purge_from_database` is true, also requests deletion from the backing database.
2067    ///
2068    /// Persistence failures are logged without failing the operation.
2069    ///
2070    /// # Errors
2071    ///
2072    /// Returns an error if the backing reports a DeFi currency integrity error.
2073    pub fn purge_position(
2074        &mut self,
2075        position_id: PositionId,
2076        purge_from_database: bool,
2077    ) -> anyhow::Result<()> {
2078        // Keep the cell alive during index cleanup without cloning position history
2079        let position_cell = self.positions.get(&position_id).cloned();
2080        let position = position_cell.as_ref().map(|cell| cell.borrow());
2081
2082        // Prevent purging open positions
2083        if let Some(ref pos) = position
2084            && pos.is_open()
2085        {
2086            log::warn!("Position {position_id} found open when purging, skipping purge");
2087            return Ok(());
2088        }
2089
2090        self.delete_position_from_database(position_id, purge_from_database)?;
2091
2092        // If position exists in cache, remove it and clean up position-specific indices
2093        if let Some(ref pos) = position {
2094            self.positions.remove(&position_id);
2095
2096            // Remove from venue positions index
2097            if let Some(venue_positions) =
2098                self.index.venue_positions.get_mut(&pos.instrument_id.venue)
2099            {
2100                venue_positions.remove(&position_id);
2101                if venue_positions.is_empty() {
2102                    self.index.venue_positions.remove(&pos.instrument_id.venue);
2103                }
2104            }
2105
2106            // Remove from instrument positions index
2107            let instrument_positions_became_empty = self
2108                .index
2109                .instrument_positions
2110                .get_mut(&pos.instrument_id)
2111                .is_some_and(|positions| {
2112                    positions.remove(&position_id);
2113                    positions.is_empty()
2114                });
2115
2116            if instrument_positions_became_empty {
2117                self.index.instrument_positions.remove(&pos.instrument_id);
2118                let instrument_orders_empty = self
2119                    .index
2120                    .instrument_orders
2121                    .get(&pos.instrument_id)
2122                    .is_some_and(|orders| orders.is_empty());
2123
2124                if instrument_orders_empty {
2125                    self.index.instrument_orders.remove(&pos.instrument_id);
2126                }
2127            }
2128
2129            // Remove from strategy positions index
2130            let strategy_positions_became_empty = self
2131                .index
2132                .strategy_positions
2133                .get_mut(&pos.strategy_id)
2134                .is_some_and(|positions| {
2135                    positions.remove(&position_id);
2136                    positions.is_empty()
2137                });
2138
2139            if strategy_positions_became_empty {
2140                self.index.strategy_positions.remove(&pos.strategy_id);
2141                let strategy_orders_empty = self
2142                    .index
2143                    .strategy_orders
2144                    .get(&pos.strategy_id)
2145                    .is_some_and(|orders| orders.is_empty());
2146
2147                if strategy_orders_empty {
2148                    self.index.strategy_orders.remove(&pos.strategy_id);
2149                    self.index.strategies.remove(&pos.strategy_id);
2150                }
2151            }
2152
2153            // Remove from account positions index
2154            if let Some(account_positions) = self.index.account_positions.get_mut(&pos.account_id) {
2155                account_positions.remove(&position_id);
2156                if account_positions.is_empty() {
2157                    self.index.account_positions.remove(&pos.account_id);
2158                }
2159            }
2160
2161            // Remove position ID from orders that reference it
2162            for client_order_id in pos.client_order_ids() {
2163                self.index.order_position.remove(&client_order_id);
2164            }
2165
2166            log::info!("Purged position {position_id}");
2167        } else {
2168            log::warn!("Position {position_id} not found when purging");
2169        }
2170
2171        // Always clean up position indices (even if position not in cache)
2172        self.index.position_strategy.remove(&position_id);
2173        self.index.position_oms.remove(&position_id);
2174        self.index.position_orders.remove(&position_id);
2175        self.index.positions.remove(&position_id);
2176        self.index.positions_open.remove(&position_id);
2177        self.index.positions_closed.remove(&position_id);
2178
2179        // Always clean up position snapshots (even if position not in cache)
2180        self.position_snapshots.remove(&position_id);
2181        self.bump_position_snapshot_revision(position_id);
2182        Ok(())
2183    }
2184
2185    fn delete_position_from_database(
2186        &self,
2187        position_id: PositionId,
2188        requested: bool,
2189    ) -> anyhow::Result<()> {
2190        if requested && let Some(database) = &self.database {
2191            handle_persistence_result(
2192                format_args!("delete position {position_id}"),
2193                database.delete_position(&position_id),
2194            )?;
2195        }
2196
2197        Ok(())
2198    }
2199
2200    /// Purges the instrument with the `instrument_id` from the cache (if found).
2201    ///
2202    /// The instrument record and its market data are removed:
2203    /// any synthetic with the same id, order book and own-order-book state, quote/trade
2204    /// histories, mark/index/funding price histories, instrument status and close, bars
2205    /// for any `BarType` referencing the instrument. Order and position indexes remain
2206    /// while their records are retained, preserving historical queries and realized PnL.
2207    ///
2208    /// For safety, an instrument is prevented from being purged while any associated
2209    /// order is non-terminal (anything not in `orders_closed`, including
2210    /// initialized, submitted, accepted, emulated, released, or inflight states) or
2211    /// any associated position is non-closed.
2212    ///
2213    /// Active subscriptions and other live data-engine state are not touched here;
2214    /// those belong to the data and execution engines.
2215    ///
2216    /// # Warning
2217    ///
2218    /// Intended for actors and strategies that have their own lifecycle logic for
2219    /// deciding when an instrument is no longer needed. Purging an instrument that any
2220    /// other actor, strategy, or engine still relies on may cause incorrect behavior
2221    /// (missing instrument lookups, lost market-data history). The caller is
2222    /// responsible for ensuring the instrument is no longer in use before purging.
2223    fn purge_instrument_inner(&mut self, instrument_id: InstrumentId, skip_order_guard: bool) {
2224        #[cfg(feature = "defi")]
2225        let defi_found =
2226            self.pool(&instrument_id).is_some() || self.pool_profiler(&instrument_id).is_some();
2227        #[cfg(not(feature = "defi"))]
2228        let defi_found = false;
2229
2230        let found = self.instruments.contains_key(&instrument_id)
2231            || self.synthetics.contains_key(&instrument_id)
2232            || defi_found;
2233
2234        if !found {
2235            log::warn!("Instrument {instrument_id} not found when purging");
2236            return;
2237        }
2238
2239        if !skip_order_guard && let Some(orders) = self.index.instrument_orders.get(&instrument_id)
2240        {
2241            let has_non_terminal = orders
2242                .iter()
2243                .any(|client_order_id| !self.index.orders_closed.contains(client_order_id));
2244
2245            if has_non_terminal {
2246                log::warn!(
2247                    "Instrument {instrument_id} has non-terminal orders when purging, skipping purge"
2248                );
2249                return;
2250            }
2251        }
2252
2253        if let Some(positions) = self.index.instrument_positions.get(&instrument_id) {
2254            let has_non_closed = positions
2255                .iter()
2256                .any(|position_id| !self.index.positions_closed.contains(position_id));
2257
2258            if has_non_closed {
2259                log::warn!(
2260                    "Instrument {instrument_id} has non-closed positions when purging, skipping purge"
2261                );
2262                return;
2263            }
2264        }
2265
2266        self.instruments.remove(&instrument_id);
2267        self.synthetics.remove(&instrument_id);
2268        self.books.remove(&instrument_id);
2269        self.own_books.remove(&instrument_id);
2270        self.quotes.remove(&instrument_id);
2271        self.trades.remove(&instrument_id);
2272        self.mark_prices.remove(&instrument_id);
2273        self.index_prices.remove(&instrument_id);
2274        self.funding_rates.remove(&instrument_id);
2275        self.instrument_statuses.remove(&instrument_id);
2276        self.instrument_closes.remove(&instrument_id);
2277        self.greeks.remove(&instrument_id);
2278        self.option_greeks.remove(&instrument_id);
2279
2280        self.bars
2281            .retain(|bar_type, _| bar_type.instrument_id() != instrument_id);
2282
2283        #[cfg(feature = "defi")]
2284        self.defi.remove_instrument(&instrument_id);
2285
2286        log::info!("Purged instrument {instrument_id}");
2287    }
2288
2289    /// Purges the instrument with the `instrument_id` from the cache.
2290    ///
2291    /// This refuses to purge when associated orders or positions remain in
2292    /// non-terminal state.
2293    pub fn purge_instrument(&mut self, instrument_id: InstrumentId) {
2294        self.purge_instrument_inner(instrument_id, false);
2295    }
2296
2297    /// Purges the instrument with the `instrument_id` from the cache while skipping the
2298    /// non-terminal order guard.
2299    ///
2300    /// This still refuses to purge when any associated position is non-closed. Intended
2301    /// for actors which own an instrument-expiration lifecycle and have already invalidated
2302    /// any remaining order state externally, but may still observe order-terminal events
2303    /// arriving later than the cleanup decision. Order objects and their indexes remain
2304    /// available even after the instrument record is removed.
2305    pub fn purge_instrument_skip_order_guard(&mut self, instrument_id: InstrumentId) {
2306        self.purge_instrument_inner(instrument_id, true);
2307    }
2308
2309    /// Purges all account state events which are outside the lookback window.
2310    ///
2311    /// Only events which are outside the lookback window will be purged.
2312    /// A value of 0 purges all but the latest account state event.
2313    ///
2314    /// When `purge_from_database` is true, also requests deletion from the backing database.
2315    /// Redis and PostgreSQL log the request and retain the full account history for replay.
2316    ///
2317    /// Persistence failures are logged without failing the operation.
2318    ///
2319    /// # Errors
2320    ///
2321    /// Returns an error if the backing reports a DeFi currency integrity error.
2322    pub fn purge_account_events(
2323        &mut self,
2324        ts_now: UnixNanos,
2325        lookback_secs: u64,
2326        purge_from_database: bool,
2327    ) -> anyhow::Result<()> {
2328        log::debug!(
2329            "Purging account events{}",
2330            if lookback_secs > 0 {
2331                format!(" with lookback_secs={lookback_secs}")
2332            } else {
2333                String::new()
2334            }
2335        );
2336
2337        for account_cell in self.accounts.values() {
2338            let mut account = account_cell.borrow_mut();
2339            let event_count = account.event_count();
2340            let events_before =
2341                (purge_from_database && self.database.is_some()).then(|| account.events());
2342            account.purge_account_events(ts_now, lookback_secs);
2343            let count_diff = event_count - account.event_count();
2344            if count_diff > 0 {
2345                log::info!(
2346                    "Purged {} event(s) from account {}",
2347                    count_diff,
2348                    account.id()
2349                );
2350
2351                if let Some(database) = &self.database
2352                    && let Some(events_before) = events_before
2353                {
2354                    Self::delete_purged_account_events(
2355                        database.as_ref(),
2356                        &account,
2357                        &events_before,
2358                    )?;
2359                }
2360            }
2361        }
2362
2363        Ok(())
2364    }
2365
2366    fn delete_purged_account_events(
2367        database: &dyn CacheDatabaseAdapter,
2368        account: &AccountAny,
2369        events_before: &[AccountState],
2370    ) -> anyhow::Result<()> {
2371        let retained: AHashSet<_> = account
2372            .events()
2373            .iter()
2374            .map(|event| event.event_id)
2375            .collect();
2376
2377        for event in events_before {
2378            if retained.contains(&event.event_id) {
2379                continue;
2380            }
2381
2382            handle_persistence_result(
2383                format_args!("delete account event {}", event.event_id),
2384                database.delete_account_event(&account.id(), &event.event_id.to_string()),
2385            )?;
2386        }
2387
2388        Ok(())
2389    }
2390
2391    /// Clears the caches index.
2392    pub fn clear_index(&mut self) {
2393        self.index.clear();
2394        log::debug!("Cleared index");
2395    }
2396
2397    /// Resets the cache.
2398    ///
2399    /// All stateful fields are reset to their initial value. Instruments,
2400    /// currencies, and synthetics are retained when `drop_instruments_on_reset`
2401    /// is `false` so that repeated backtest runs can reuse the same dataset. External order claims
2402    /// and execution client account, route, and external client registrations are retained so
2403    /// registered strategy and client routing remain configured across resets.
2404    pub fn reset(&mut self) {
2405        log::debug!("Resetting cache");
2406
2407        self.general.clear();
2408        self.books.clear();
2409        self.own_books.clear();
2410        self.quotes.clear();
2411        self.trades.clear();
2412        self.mark_xrates.clear();
2413        self.mark_prices.clear();
2414        self.index_prices.clear();
2415        self.funding_rates.clear();
2416        self.instrument_statuses.clear();
2417        self.instrument_closes.clear();
2418        self.bars.clear();
2419        self.accounts.clear();
2420        self.orders.clear();
2421        self.orders_dispatched.clear();
2422        self.order_lists.clear();
2423        self.positions.clear();
2424        self.position_snapshots.clear();
2425        self.position_snapshot_revisions.clear();
2426        self.greeks.clear();
2427        self.option_greeks.clear();
2428        self.yield_curves.clear();
2429
2430        if self.config.drop_instruments_on_reset {
2431            #[cfg(feature = "defi")]
2432            self.defi.clear_currencies();
2433            self.currencies.clear();
2434            self.instruments.clear();
2435            self.synthetics.clear();
2436        }
2437
2438        #[cfg(feature = "defi")]
2439        self.defi.clear_pools();
2440
2441        self.clear_index();
2442
2443        log::info!("Reset cache");
2444    }
2445
2446    /// Dispose of the cache which will close any underlying database adapter.
2447    ///
2448    /// If closing the database connection fails, an error is logged.
2449    pub fn dispose(&mut self) {
2450        self.reset();
2451
2452        if let Some(database) = &mut self.database
2453            && let Err(e) = database.close()
2454        {
2455            log::error!("Failed to close database during dispose: {e}");
2456        }
2457    }
2458
2459    /// Flushes the cache database, permanently removing the data the backing owns.
2460    ///
2461    /// Does nothing when no database is configured.
2462    ///
2463    /// # Errors
2464    ///
2465    /// Returns an error if flushing the database fails.
2466    pub fn flush_db(&mut self) -> anyhow::Result<()> {
2467        match &mut self.database {
2468            Some(database) => database.flush(),
2469            None => Ok(()),
2470        }
2471    }
2472
2473    /// Adds a raw bytes `value` to the cache under the `key`.
2474    ///
2475    /// The cache stores only raw bytes; interpretation is the caller's responsibility.
2476    ///
2477    /// Persistence failures are logged without failing the operation.
2478    ///
2479    /// # Errors
2480    ///
2481    /// Returns an error if the key is invalid, the value is empty, or the backing reports a DeFi
2482    /// currency integrity conflict.
2483    pub fn add(&mut self, key: &str, value: Bytes) -> anyhow::Result<()> {
2484        // Keys are opaque and may embed exchange symbols, which need not be ASCII
2485        check_valid_string_utf8(key, stringify!(key))?;
2486        check_predicate_false(value.is_empty(), stringify!(value))?;
2487
2488        log::debug!("Adding general {key}");
2489        self.general.insert(key.to_string(), value.clone());
2490
2491        if let Some(database) = &mut self.database {
2492            handle_persistence_result(
2493                format_args!("persist entry {key}"),
2494                database.add(key.to_string(), value),
2495            )?;
2496        }
2497        Ok(())
2498    }
2499
2500    /// Adds an `OrderBook` to the cache.
2501    ///
2502    /// Persistence failures are logged without failing the operation.
2503    ///
2504    /// # Errors
2505    ///
2506    /// Returns an error if the backing reports a DeFi currency integrity error.
2507    pub fn add_order_book(&mut self, book: OrderBook) -> anyhow::Result<()> {
2508        log::debug!("Adding `OrderBook` {}", book.instrument_id);
2509
2510        if self.config.save_market_data
2511            && let Some(database) = &mut self.database
2512        {
2513            handle_persistence_result(
2514                format_args!("persist order book {}", book.instrument_id),
2515                database.add_order_book(&book),
2516            )?;
2517        }
2518
2519        self.books.insert(book.instrument_id, book);
2520        Ok(())
2521    }
2522
2523    /// Adds an `OwnOrderBook` to the cache.
2524    ///
2525    /// This operation updates memory only.
2526    #[expect(
2527        clippy::missing_errors_doc,
2528        reason = "infallible operation retains its existing public signature"
2529    )]
2530    pub fn add_own_order_book(&mut self, own_book: OwnOrderBook) -> anyhow::Result<()> {
2531        log::debug!("Adding `OwnOrderBook` {}", own_book.instrument_id);
2532
2533        self.own_books.insert(own_book.instrument_id, own_book);
2534        Ok(())
2535    }
2536
2537    /// Adds the `mark_price` update to the cache.
2538    ///
2539    /// This operation updates memory only.
2540    #[expect(
2541        clippy::missing_errors_doc,
2542        reason = "infallible operation retains its existing public signature"
2543    )]
2544    pub fn add_mark_price(&mut self, mark_price: MarkPriceUpdate) -> anyhow::Result<()> {
2545        log::debug!("Adding `MarkPriceUpdate` for {}", mark_price.instrument_id);
2546
2547        if self.config.save_market_data {
2548            // TODO: Placeholder and return Result for consistency
2549        }
2550
2551        let mark_prices_deque = self
2552            .mark_prices
2553            .entry(mark_price.instrument_id)
2554            .or_insert_with(|| BoundedVecDeque::new(self.config.tick_capacity));
2555        mark_prices_deque.push_front(mark_price);
2556        Ok(())
2557    }
2558
2559    /// Adds the `index_price` update to the cache.
2560    ///
2561    /// This operation updates memory only.
2562    #[expect(
2563        clippy::missing_errors_doc,
2564        reason = "infallible operation retains its existing public signature"
2565    )]
2566    pub fn add_index_price(&mut self, index_price: IndexPriceUpdate) -> anyhow::Result<()> {
2567        log::debug!(
2568            "Adding `IndexPriceUpdate` for {}",
2569            index_price.instrument_id
2570        );
2571
2572        if self.config.save_market_data {
2573            // TODO: Placeholder and return Result for consistency
2574        }
2575
2576        let index_prices_deque = self
2577            .index_prices
2578            .entry(index_price.instrument_id)
2579            .or_insert_with(|| BoundedVecDeque::new(self.config.tick_capacity));
2580        index_prices_deque.push_front(index_price);
2581        Ok(())
2582    }
2583
2584    /// Adds the `funding_rate` update to the cache.
2585    ///
2586    /// This operation updates memory only.
2587    #[expect(
2588        clippy::missing_errors_doc,
2589        reason = "infallible operation retains its existing public signature"
2590    )]
2591    pub fn add_funding_rate(&mut self, funding_rate: FundingRateUpdate) -> anyhow::Result<()> {
2592        log::debug!(
2593            "Adding `FundingRateUpdate` for {}",
2594            funding_rate.instrument_id
2595        );
2596
2597        if self.config.save_market_data {
2598            // TODO: Placeholder and return Result for consistency
2599        }
2600
2601        let funding_rates_deque = self
2602            .funding_rates
2603            .entry(funding_rate.instrument_id)
2604            .or_insert_with(|| BoundedVecDeque::new(self.config.tick_capacity));
2605        funding_rates_deque.push_front(funding_rate);
2606        Ok(())
2607    }
2608
2609    /// Adds the given `funding rates` to the cache.
2610    ///
2611    /// Persistence failures are logged without failing the operation.
2612    ///
2613    /// # Errors
2614    ///
2615    /// Returns an error if the slice is empty or the backing reports a DeFi currency integrity error.
2616    pub fn add_funding_rates(&mut self, funding_rates: &[FundingRateUpdate]) -> anyhow::Result<()> {
2617        check_slice_not_empty(funding_rates, stringify!(funding_rates))?;
2618
2619        log::debug!("Adding `FundingRateUpdate`[{}]", funding_rates.len());
2620
2621        if self.config.save_market_data
2622            && let Some(database) = &mut self.database
2623        {
2624            for funding_rate in funding_rates {
2625                handle_persistence_result(
2626                    format_args!("persist funding rate {}", funding_rate.instrument_id),
2627                    database.add_funding_rate(funding_rate),
2628                )?;
2629            }
2630        }
2631
2632        for funding_rate in funding_rates {
2633            let funding_rate_deque = self
2634                .funding_rates
2635                .entry(funding_rate.instrument_id)
2636                .or_insert_with(|| BoundedVecDeque::new(self.config.tick_capacity));
2637            funding_rate_deque.push_front(*funding_rate);
2638        }
2639        Ok(())
2640    }
2641
2642    /// Adds the `instrument_status` update to the cache.
2643    ///
2644    /// This operation updates memory only.
2645    #[expect(
2646        clippy::missing_errors_doc,
2647        reason = "infallible operation retains its existing public signature"
2648    )]
2649    pub fn add_instrument_status(&mut self, status: InstrumentStatus) -> anyhow::Result<()> {
2650        log::debug!("Adding `InstrumentStatus` for {}", status.instrument_id);
2651
2652        if self.config.save_market_data {
2653            // TODO: Placeholder and return Result for consistency
2654        }
2655
2656        let statuses_deque = self
2657            .instrument_statuses
2658            .entry(status.instrument_id)
2659            .or_insert_with(|| BoundedVecDeque::new(self.config.tick_capacity));
2660        statuses_deque.push_front(status);
2661        Ok(())
2662    }
2663
2664    /// Adds an instrument close to the cache.
2665    ///
2666    /// A close already cached for the same instrument is overwritten.
2667    ///
2668    /// Persistence failures are logged without failing the operation.
2669    ///
2670    /// # Errors
2671    ///
2672    /// Returns an error if the backing reports a DeFi currency integrity error.
2673    pub fn add_instrument_close(&mut self, close: InstrumentClose) -> anyhow::Result<()> {
2674        log::debug!("Adding `InstrumentClose` for {}", close.instrument_id);
2675
2676        if let Some(database) = &self.database {
2677            handle_persistence_result(
2678                format_args!("persist instrument close {}", close.instrument_id),
2679                database.add_instrument_close(&close),
2680            )?;
2681        }
2682
2683        self.instrument_closes.insert(close.instrument_id, close);
2684        Ok(())
2685    }
2686
2687    /// Adds the `quote` tick to the cache.
2688    ///
2689    /// Persistence failures are logged without failing the operation.
2690    ///
2691    /// # Errors
2692    ///
2693    /// Returns an error if the backing reports a DeFi currency integrity error.
2694    pub fn add_quote(&mut self, quote: QuoteTick) -> anyhow::Result<()> {
2695        log::debug!("Adding `QuoteTick` {}", quote.instrument_id);
2696
2697        if self.config.save_market_data
2698            && let Some(database) = &mut self.database
2699        {
2700            handle_persistence_result(
2701                format_args!("persist quote {}", quote.instrument_id),
2702                database.add_quote(&quote),
2703            )?;
2704        }
2705
2706        let quotes_deque = self
2707            .quotes
2708            .entry(quote.instrument_id)
2709            .or_insert_with(|| BoundedVecDeque::new(self.config.tick_capacity));
2710        quotes_deque.push_front(quote);
2711        Ok(())
2712    }
2713
2714    /// Adds the `quotes` to the cache.
2715    ///
2716    /// Persistence failures are logged without failing the operation.
2717    ///
2718    /// # Errors
2719    ///
2720    /// Returns an error if the slice is empty or the backing reports a DeFi currency integrity error.
2721    pub fn add_quotes(&mut self, quotes: &[QuoteTick]) -> anyhow::Result<()> {
2722        check_slice_not_empty(quotes, stringify!(quotes))?;
2723
2724        log::debug!("Adding `QuoteTick`[{}]", quotes.len());
2725
2726        if self.config.save_market_data
2727            && let Some(database) = &mut self.database
2728        {
2729            for quote in quotes {
2730                handle_persistence_result(
2731                    format_args!("persist quote {}", quote.instrument_id),
2732                    database.add_quote(quote),
2733                )?;
2734            }
2735        }
2736
2737        for quote in quotes {
2738            let quotes_deque = self
2739                .quotes
2740                .entry(quote.instrument_id)
2741                .or_insert_with(|| BoundedVecDeque::new(self.config.tick_capacity));
2742            quotes_deque.push_front(*quote);
2743        }
2744        Ok(())
2745    }
2746
2747    /// Adds the `trade` tick to the cache.
2748    ///
2749    /// Persistence failures are logged without failing the operation.
2750    ///
2751    /// # Errors
2752    ///
2753    /// Returns an error if the backing reports a DeFi currency integrity error.
2754    pub fn add_trade(&mut self, trade: TradeTick) -> anyhow::Result<()> {
2755        log::debug!("Adding `TradeTick` {}", trade.instrument_id);
2756
2757        if self.config.save_market_data
2758            && let Some(database) = &mut self.database
2759        {
2760            handle_persistence_result(
2761                format_args!("persist trade {}", trade.instrument_id),
2762                database.add_trade(&trade),
2763            )?;
2764        }
2765
2766        let trades_deque = self
2767            .trades
2768            .entry(trade.instrument_id)
2769            .or_insert_with(|| BoundedVecDeque::new(self.config.tick_capacity));
2770        trades_deque.push_front(trade);
2771        Ok(())
2772    }
2773
2774    /// Adds the give `trades` to the cache.
2775    ///
2776    /// Persistence failures are logged without failing the operation.
2777    ///
2778    /// # Errors
2779    ///
2780    /// Returns an error if the slice is empty or the backing reports a DeFi currency integrity error.
2781    pub fn add_trades(&mut self, trades: &[TradeTick]) -> anyhow::Result<()> {
2782        check_slice_not_empty(trades, stringify!(trades))?;
2783
2784        log::debug!("Adding `TradeTick`[{}]", trades.len());
2785
2786        if self.config.save_market_data
2787            && let Some(database) = &mut self.database
2788        {
2789            for trade in trades {
2790                handle_persistence_result(
2791                    format_args!("persist trade {}", trade.instrument_id),
2792                    database.add_trade(trade),
2793                )?;
2794            }
2795        }
2796
2797        for trade in trades {
2798            let trades_deque = self
2799                .trades
2800                .entry(trade.instrument_id)
2801                .or_insert_with(|| BoundedVecDeque::new(self.config.tick_capacity));
2802            trades_deque.push_front(*trade);
2803        }
2804        Ok(())
2805    }
2806
2807    /// Adds the `bar` to the cache, keeping the per-`bar_type` series newest-first.
2808    ///
2809    /// A newer bar is pushed, an older `ts_event` is skipped, and an equal
2810    /// `ts_event` replaces the front bar for time bars.
2811    ///
2812    /// Persistence failures are logged without failing the operation.
2813    ///
2814    /// # Errors
2815    ///
2816    /// Returns an error if the backing reports a DeFi currency integrity error.
2817    pub fn add_bar(&mut self, bar: Bar) -> anyhow::Result<()> {
2818        log::debug!("Adding `Bar` {}", bar.bar_type);
2819
2820        if self.config.save_market_data
2821            && let Some(database) = &mut self.database
2822        {
2823            handle_persistence_result(
2824                format_args!("persist bar {}", bar.bar_type),
2825                database.add_bar(&bar),
2826            )?;
2827        }
2828
2829        let bars = self
2830            .bars
2831            .entry(bar.bar_type)
2832            .or_insert_with(|| BoundedVecDeque::new(self.config.bar_capacity));
2833        insert_bar(bars, bar);
2834        Ok(())
2835    }
2836
2837    /// Adds the `bars` to the cache, each following [`Cache::add_bar`].
2838    ///
2839    /// Persistence failures are logged without failing the operation.
2840    ///
2841    /// # Errors
2842    ///
2843    /// Returns an error if the slice is empty or the backing reports a DeFi currency integrity error.
2844    pub fn add_bars(&mut self, bars: &[Bar]) -> anyhow::Result<()> {
2845        check_slice_not_empty(bars, stringify!(bars))?;
2846
2847        log::debug!("Adding `Bar`[{}]", bars.len());
2848
2849        if self.config.save_market_data
2850            && let Some(database) = &mut self.database
2851        {
2852            for bar in bars {
2853                handle_persistence_result(
2854                    format_args!("persist bar {}", bar.bar_type),
2855                    database.add_bar(bar),
2856                )?;
2857            }
2858        }
2859
2860        for bar in bars {
2861            let bars_deque = self
2862                .bars
2863                .entry(bar.bar_type)
2864                .or_insert_with(|| BoundedVecDeque::new(self.config.bar_capacity));
2865            insert_bar(bars_deque, *bar);
2866        }
2867        Ok(())
2868    }
2869
2870    /// Adds the historical `bar` at its ordered position in the series.
2871    ///
2872    /// Request-generated bars are added this way, since the cache is their only
2873    /// delivery path: bars older than the front are kept rather than skipped.
2874    ///
2875    /// Persistence failures are logged without failing the operation.
2876    ///
2877    /// # Errors
2878    ///
2879    /// Returns an error if the backing reports a DeFi currency integrity error.
2880    pub fn add_bar_historical(&mut self, bar: Bar) -> anyhow::Result<()> {
2881        log::debug!("Adding historical `Bar` {}", bar.bar_type);
2882
2883        if self.config.save_market_data
2884            && let Some(database) = &mut self.database
2885        {
2886            handle_persistence_result(
2887                format_args!("persist bar {}", bar.bar_type),
2888                database.add_bar(&bar),
2889            )?;
2890        }
2891
2892        let bars = self
2893            .bars
2894            .entry(bar.bar_type)
2895            .or_insert_with(|| BoundedVecDeque::new(self.config.bar_capacity));
2896        insert_bar_historical(bars, bar);
2897        Ok(())
2898    }
2899
2900    /// Adds the `greeks` data to the cache.
2901    ///
2902    /// Persistence failures are logged without failing the operation.
2903    ///
2904    /// # Errors
2905    ///
2906    /// Returns an error if the backing reports a DeFi currency integrity error.
2907    pub fn add_greeks(&mut self, greeks: GreeksData) -> anyhow::Result<()> {
2908        log::debug!("Adding `GreeksData` {}", greeks.instrument_id);
2909
2910        if self.config.save_market_data
2911            && let Some(database) = &mut self.database
2912        {
2913            handle_persistence_result(
2914                format_args!("persist Greeks {}", greeks.instrument_id),
2915                database.add_greeks(&greeks),
2916            )?;
2917        }
2918
2919        self.greeks.insert(greeks.instrument_id, greeks);
2920        Ok(())
2921    }
2922
2923    /// Gets the greeks data for the `instrument_id`.
2924    pub fn greeks(&self, instrument_id: &InstrumentId) -> Option<GreeksData> {
2925        self.greeks.get(instrument_id).cloned()
2926    }
2927
2928    /// Adds exchange-provided option greeks to the cache.
2929    pub fn add_option_greeks(&mut self, greeks: OptionGreeks) {
2930        log::debug!("Adding `OptionGreeks` {}", greeks.instrument_id);
2931        self.option_greeks.insert(greeks.instrument_id, greeks);
2932    }
2933
2934    /// Gets a reference to the exchange-provided option greeks for the `instrument_id`.
2935    #[must_use]
2936    pub fn option_greeks(&self, instrument_id: &InstrumentId) -> Option<&OptionGreeks> {
2937        self.option_greeks.get(instrument_id)
2938    }
2939
2940    /// Adds the `yield_curve` data to the cache.
2941    ///
2942    /// Persistence failures are logged without failing the operation.
2943    ///
2944    /// # Errors
2945    ///
2946    /// Returns an error if:
2947    /// - The yield curve fails [`YieldCurve::validate`].
2948    /// - The backing reports a DeFi currency integrity error.
2949    pub fn add_yield_curve(&mut self, yield_curve: YieldCurve) -> anyhow::Result<()> {
2950        yield_curve.validate()?;
2951
2952        log::debug!("Adding `YieldCurve` {}", yield_curve.curve_name);
2953
2954        if self.config.save_market_data
2955            && let Some(database) = &mut self.database
2956        {
2957            handle_persistence_result(
2958                format_args!("persist yield curve {}", yield_curve.curve_name),
2959                database.add_yield_curve(&yield_curve),
2960            )?;
2961        }
2962
2963        self.yield_curves
2964            .insert(yield_curve.curve_name.clone(), yield_curve);
2965        Ok(())
2966    }
2967
2968    /// Gets the yield curve for the `key`.
2969    pub fn yield_curve(&self, key: &str) -> Option<Box<dyn Fn(f64) -> f64>> {
2970        self.yield_curves.get(key).map(|curve| {
2971            let curve_clone = curve.clone();
2972            Box::new(move |expiry_in_years: f64| curve_clone.get_rate(expiry_in_years))
2973                as Box<dyn Fn(f64) -> f64>
2974        })
2975    }
2976
2977    /// Adds the `currency` to the cache.
2978    ///
2979    /// Persistence failures are logged without failing the operation.
2980    ///
2981    /// # Errors
2982    ///
2983    /// Returns an error if the currency definition conflicts with existing state or the backing
2984    /// reports a DeFi currency integrity error.
2985    pub fn add_currency(&mut self, currency: Currency) -> anyhow::Result<()> {
2986        #[cfg(feature = "defi")]
2987        let token = nautilus_model::defi::currency::check(currency)?.is_some();
2988        #[cfg(feature = "defi")]
2989        if token {
2990            if let Some(existing) = self.currencies.get(&currency.code) {
2991                if !self.defi.contains_currency(&currency.code) {
2992                    anyhow::bail!("Legacy currency occupies token code {}", currency.code);
2993                }
2994
2995                nautilus_model::defi::currency::check(*existing)?;
2996            }
2997
2998            Currency::register(currency, false)?;
2999        }
3000
3001        if self.currencies.contains_key(&currency.code) {
3002            return Ok(());
3003        }
3004        log::debug!("Adding `Currency` {}", currency.code);
3005
3006        if let Some(database) = &mut self.database {
3007            handle_persistence_result(
3008                format_args!("persist currency {}", currency.code),
3009                database.add_currency(&currency),
3010            )?;
3011        }
3012
3013        self.currencies.insert(currency.code, currency);
3014
3015        #[cfg(feature = "defi")]
3016        if token {
3017            self.defi.add_currency(currency.code);
3018        }
3019
3020        Ok(())
3021    }
3022
3023    /// Adds the `instrument` to the cache.
3024    ///
3025    /// Persistence failures are logged without failing the operation.
3026    ///
3027    /// # Errors
3028    ///
3029    /// Returns an error if the instrument or its currency identities conflict with existing state,
3030    /// or the backing reports a DeFi currency integrity error.
3031    pub fn add_instrument(&mut self, instrument: InstrumentAny) -> anyhow::Result<()> {
3032        log::debug!("Adding `Instrument` {}", instrument.id());
3033
3034        #[cfg(feature = "defi")]
3035        let migration = self.check_instrument_migration(&instrument)?;
3036
3037        // Ensure currencies exist in cache - safe to call repeatedly as add_currency is idempotent
3038        if let Some(base_currency) = instrument.base_currency() {
3039            self.add_currency(base_currency)?;
3040        }
3041        self.add_currency(instrument.quote_currency())?;
3042        self.add_currency(instrument.settlement_currency())?;
3043
3044        if let Some(database) = &mut self.database {
3045            #[cfg(feature = "defi")]
3046            if let Some(migration) = migration {
3047                handle_persistence_result(
3048                    format_args!("persist instrument {}", instrument.id()),
3049                    database.add_defi_instrument(&instrument, migration),
3050                )?;
3051            } else {
3052                handle_persistence_result(
3053                    format_args!("persist instrument {}", instrument.id()),
3054                    database.add_instrument(&instrument),
3055                )?;
3056            }
3057
3058            #[cfg(not(feature = "defi"))]
3059            handle_persistence_result(
3060                format_args!("persist instrument {}", instrument.id()),
3061                database.add_instrument(&instrument),
3062            )?;
3063        }
3064
3065        self.instruments.insert(instrument.id(), instrument);
3066        Ok(())
3067    }
3068
3069    /// Adds the `synthetic` instrument to the cache.
3070    ///
3071    /// Persistence failures are logged without failing the operation.
3072    ///
3073    /// # Errors
3074    ///
3075    /// Returns an error if the backing reports a DeFi currency integrity error.
3076    pub fn add_synthetic(&mut self, synthetic: SyntheticInstrument) -> anyhow::Result<()> {
3077        log::debug!("Adding `SyntheticInstrument` {}", synthetic.id);
3078
3079        if let Some(database) = &mut self.database {
3080            handle_persistence_result(
3081                format_args!("persist synthetic {}", synthetic.id),
3082                database.add_synthetic(&synthetic),
3083            )?;
3084        }
3085
3086        self.synthetics.insert(synthetic.id, synthetic);
3087        Ok(())
3088    }
3089
3090    /// The currencies an account state references: its balances, its margins and its base currency.
3091    fn state_currencies(state: &AccountState) -> impl Iterator<Item = Currency> + '_ {
3092        state
3093            .balances
3094            .iter()
3095            .map(|balance| balance.currency)
3096            .chain(state.margins.iter().map(|margin| margin.currency))
3097            .chain(state.base_currency)
3098    }
3099
3100    /// Persists the currencies an account references, so a restart can restore them.
3101    ///
3102    /// An account can hold collateral in a currency no instrument carries, and a `Currency`
3103    /// persists as its bare code, so without this the account cannot be decoded in a process
3104    /// where that code was never registered. Mirrors what [`Self::add_instrument`] does for an
3105    /// instrument's base, quote and settlement currencies.
3106    fn add_account_currencies(&mut self, account: &AccountAny) -> anyhow::Result<()> {
3107        let Some(state) = account.last_event() else {
3108            return Ok(());
3109        };
3110
3111        for currency in Self::state_currencies(&state) {
3112            self.add_currency(currency)?;
3113        }
3114        Ok(())
3115    }
3116
3117    /// Adds the `account` to the cache.
3118    ///
3119    /// Persistence failures are logged without failing the operation.
3120    ///
3121    /// # Errors
3122    ///
3123    /// Returns an error if a referenced currency conflicts with existing state or the backing
3124    /// reports a DeFi currency integrity error.
3125    pub fn add_account(&mut self, account: AccountAny) -> anyhow::Result<()> {
3126        log::debug!("Adding `Account` {}", account.id());
3127
3128        self.add_account_currencies(&account)?;
3129
3130        if let Some(database) = &mut self.database {
3131            handle_persistence_result(
3132                format_args!("persist account {}", account.id()),
3133                database.add_account(&account),
3134            )?;
3135        }
3136
3137        let account_id = account.id();
3138        self.accounts.insert(account_id, SharedCell::new(account));
3139        self.index.add_venue_account(account_id);
3140        Ok(())
3141    }
3142
3143    /// Indexes the `client_order_id` with the `venue_order_id`.
3144    ///
3145    /// The `overwrite` parameter determines whether to overwrite any existing cached identifier.
3146    ///
3147    /// # Errors
3148    ///
3149    /// Returns an error if the client already has a different venue order ID and `overwrite` is
3150    /// false, or if the venue order ID is owned by a different client order.
3151    pub fn add_venue_order_id(
3152        &mut self,
3153        client_order_id: &ClientOrderId,
3154        venue_order_id: &VenueOrderId,
3155        overwrite: bool,
3156    ) -> anyhow::Result<()> {
3157        self.validate_venue_order_id_claim(client_order_id, venue_order_id, overwrite)?;
3158
3159        self.index
3160            .client_order_ids
3161            .insert(*client_order_id, *venue_order_id);
3162        self.index
3163            .venue_order_ids
3164            .insert(*venue_order_id, *client_order_id);
3165
3166        Ok(())
3167    }
3168
3169    /// Indexes the reverse alias `venue_order_id` to `client_order_id` for routing.
3170    ///
3171    /// Unlike [`Cache::add_venue_order_id`], an existing forward mapping for the client
3172    /// order is never moved, so superseded venue order ID generations from mass status
3173    /// reports register idempotently. The forward mapping's authority stays with order
3174    /// event application via [`Cache::update_order`].
3175    ///
3176    /// # Errors
3177    ///
3178    /// Returns an error if the venue order ID is owned by a different client order.
3179    pub fn index_venue_order_id(
3180        &mut self,
3181        client_order_id: &ClientOrderId,
3182        venue_order_id: &VenueOrderId,
3183    ) -> anyhow::Result<()> {
3184        self.validate_venue_order_id_ownership(client_order_id, venue_order_id)?;
3185
3186        self.index
3187            .venue_order_ids
3188            .insert(*venue_order_id, *client_order_id);
3189        self.index
3190            .client_order_ids
3191            .entry(*client_order_id)
3192            .or_insert(*venue_order_id);
3193
3194        Ok(())
3195    }
3196
3197    fn validate_venue_order_id_claim(
3198        &self,
3199        client_order_id: &ClientOrderId,
3200        venue_order_id: &VenueOrderId,
3201        overwrite: bool,
3202    ) -> anyhow::Result<()> {
3203        self.validate_venue_order_id_ownership(client_order_id, venue_order_id)?;
3204
3205        if let Some(existing_venue_order_id) = self.index.client_order_ids.get(client_order_id)
3206            && !overwrite
3207            && existing_venue_order_id != venue_order_id
3208        {
3209            anyhow::bail!(
3210                "Existing {existing_venue_order_id} for {client_order_id}
3211                    did not match the given {venue_order_id}.
3212                    If you are writing a test then try a different `venue_order_id`,
3213                    otherwise this is probably a bug."
3214            );
3215        }
3216
3217        Ok(())
3218    }
3219
3220    fn validate_venue_order_id_ownership(
3221        &self,
3222        client_order_id: &ClientOrderId,
3223        venue_order_id: &VenueOrderId,
3224    ) -> anyhow::Result<()> {
3225        if let Some(existing_client_order_id) = self.index.venue_order_ids.get(venue_order_id)
3226            && existing_client_order_id != client_order_id
3227        {
3228            return Err(VenueOrderIdOwnershipError {
3229                venue_order_id: *venue_order_id,
3230                existing_client_order_id: *existing_client_order_id,
3231                claimant_client_order_id: *client_order_id,
3232            }
3233            .into());
3234        }
3235
3236        Ok(())
3237    }
3238
3239    /// Adds the `order` to the cache indexed with any given identifiers.
3240    ///
3241    /// Persistence failures are logged without failing the operation.
3242    ///
3243    /// # Parameters
3244    ///
3245    /// `replace_existing`: Replaces an existing order with the same client order ID. Emulated
3246    /// orders use this when release transforms them into another order type.
3247    ///
3248    /// # Errors
3249    ///
3250    /// Returns an error if the client order ID exists and `replace_existing` is false, a
3251    /// replacement claims another order's venue order ID, or the backing reports a DeFi currency
3252    /// integrity error.
3253    pub fn add_order(
3254        &mut self,
3255        order: OrderAny,
3256        position_id: Option<PositionId>,
3257        client_id: Option<ClientId>,
3258        replace_existing: bool,
3259    ) -> anyhow::Result<()> {
3260        let instrument_id = order.instrument_id();
3261        let venue = instrument_id.venue;
3262        let client_order_id = order.client_order_id();
3263        let strategy_id = order.strategy_id();
3264        let exec_algorithm_id = order.exec_algorithm_id();
3265        let exec_spawn_id = order.exec_spawn_id();
3266
3267        if !replace_existing {
3268            check_key_not_in_map(
3269                &client_order_id,
3270                &self.orders,
3271                stringify!(client_order_id),
3272                stringify!(orders),
3273            )?;
3274        }
3275
3276        log::debug!("Adding {order:?}");
3277
3278        let old_order_cell = self.orders.get(&client_order_id).cloned();
3279        let replacing = old_order_cell.is_some();
3280        if let Some(old_order_cell) = &old_order_cell {
3281            self.reindex_replaced_order(old_order_cell, &order, position_id)?;
3282        }
3283
3284        self.index.orders.insert(client_order_id);
3285
3286        if order.is_active_local() {
3287            self.index.orders_active_local.insert(client_order_id);
3288        }
3289
3290        if order.emulation_trigger().is_some() && (!replacing || !order.is_closed()) {
3291            self.index.orders_emulated.insert(client_order_id);
3292        }
3293
3294        self.index
3295            .order_strategy
3296            .insert(client_order_id, strategy_id);
3297        self.index.strategies.insert(strategy_id);
3298
3299        // Update venue -> orders index
3300        self.index
3301            .venue_orders
3302            .entry(venue)
3303            .or_default()
3304            .insert(client_order_id);
3305
3306        // Update instrument -> orders index
3307        self.index
3308            .instrument_orders
3309            .entry(instrument_id)
3310            .or_default()
3311            .insert(client_order_id);
3312
3313        // Update strategy -> orders index
3314        self.index
3315            .strategy_orders
3316            .entry(strategy_id)
3317            .or_default()
3318            .insert(client_order_id);
3319
3320        // Update account -> orders index (if account_id known at creation)
3321        if let Some(account_id) = order.account_id() {
3322            self.index
3323                .account_orders
3324                .entry(account_id)
3325                .or_default()
3326                .insert(client_order_id);
3327        }
3328
3329        // Update exec_algorithm -> orders index
3330        if let Some(exec_algorithm_id) = exec_algorithm_id {
3331            self.index.exec_algorithms.insert(exec_algorithm_id);
3332
3333            self.index
3334                .exec_algorithm_orders
3335                .entry(exec_algorithm_id)
3336                .or_default()
3337                .insert(client_order_id);
3338        }
3339
3340        // Update exec_spawn -> orders index
3341        if let Some(exec_spawn_id) = exec_spawn_id {
3342            self.index
3343                .exec_spawn_orders
3344                .entry(exec_spawn_id)
3345                .or_default()
3346                .insert(client_order_id);
3347        }
3348
3349        // Index position ID if provided
3350        if let Some(position_id) = position_id {
3351            self.index_position_id_in_memory(&position_id, &venue, &client_order_id, &strategy_id);
3352        }
3353
3354        // Index client ID if provided
3355        if let Some(client_id) = client_id {
3356            self.index.order_client.insert(client_order_id, client_id);
3357            log::debug!("Indexed {client_id:?}");
3358        }
3359
3360        // Reuse the existing cell on replace so the canonical entry stays in place
3361        // rather than orphaning a stale cell.
3362        let order_cell = if let Some(order_cell) = old_order_cell {
3363            *order_cell.borrow_mut() = order;
3364            order_cell
3365        } else {
3366            let order_cell = SharedCell::new(order);
3367            self.orders.insert(client_order_id, order_cell.clone());
3368            order_cell
3369        };
3370
3371        if let Some(position_id) = position_id {
3372            self.persist_position_id(&position_id, &client_order_id)?;
3373        }
3374
3375        if let Some(database) = &mut self.database {
3376            handle_persistence_result(
3377                format_args!("persist order {client_order_id}"),
3378                database.add_order(&order_cell.borrow(), client_id),
3379            )?;
3380            // TODO: Implement
3381            // if self.config.snapshot_orders {
3382            //     database.snapshot_order_state(order)?;
3383            // }
3384        }
3385
3386        Ok(())
3387    }
3388
3389    fn reindex_replaced_order(
3390        &mut self,
3391        old_order_cell: &SharedCell<OrderAny>,
3392        order: &OrderAny,
3393        position_id: Option<PositionId>,
3394    ) -> anyhow::Result<()> {
3395        let client_order_id = order.client_order_id();
3396        let current_venue_order_id = order.venue_order_id();
3397        let venue_order_ids = order.venue_order_ids();
3398
3399        if let Some(venue_order_id) = current_venue_order_id {
3400            self.validate_venue_order_id_ownership(&client_order_id, &venue_order_id)?;
3401        }
3402
3403        for venue_order_id in &venue_order_ids {
3404            if current_venue_order_id == Some(**venue_order_id) {
3405                continue;
3406            }
3407
3408            self.validate_venue_order_id_ownership(&client_order_id, venue_order_id)?;
3409        }
3410
3411        {
3412            let old_order = old_order_cell.borrow();
3413
3414            if let Some(position_id) = position_id {
3415                Self::remove_replaced_order_position_memberships(
3416                    &mut self.index,
3417                    &self.positions,
3418                    &old_order,
3419                    position_id,
3420                );
3421            }
3422
3423            Self::remove_replaced_order_filter_memberships(&mut self.index, &old_order, order);
3424        }
3425
3426        self.index.orders_active_local.remove(&client_order_id);
3427        self.index.orders_open.remove(&client_order_id);
3428        self.index.orders_closed.remove(&client_order_id);
3429        self.index.orders_emulated.remove(&client_order_id);
3430        self.index.orders_inflight.remove(&client_order_id);
3431        if order.is_open() {
3432            self.index.orders_open.insert(client_order_id);
3433        }
3434
3435        if order.is_closed() {
3436            self.index.orders_pending_cancel.remove(&client_order_id);
3437            self.index.orders_closed.insert(client_order_id);
3438        }
3439
3440        if order.is_inflight() {
3441            self.index.orders_inflight.insert(client_order_id);
3442        }
3443
3444        self.index.client_order_ids.remove(&client_order_id);
3445
3446        if let Some(venue_order_id) = current_venue_order_id {
3447            self.index
3448                .client_order_ids
3449                .insert(client_order_id, venue_order_id);
3450            self.index
3451                .venue_order_ids
3452                .insert(venue_order_id, client_order_id);
3453        }
3454
3455        for venue_order_id in venue_order_ids {
3456            if current_venue_order_id != Some(*venue_order_id) {
3457                self.index
3458                    .venue_order_ids
3459                    .insert(*venue_order_id, client_order_id);
3460            }
3461        }
3462
3463        Ok(())
3464    }
3465
3466    fn remove_replaced_order_filter_memberships(
3467        index: &mut CacheIndex,
3468        old_order: &OrderAny,
3469        replacement: &OrderAny,
3470    ) {
3471        let client_order_id = old_order.client_order_id();
3472        let old_instrument_id = old_order.instrument_id();
3473        let new_instrument_id = replacement.instrument_id();
3474        let old_venue = old_instrument_id.venue;
3475        let old_strategy_id = old_order.strategy_id();
3476
3477        if old_venue != new_instrument_id.venue
3478            && Self::remove_order_from_bucket(&mut index.venue_orders, &old_venue, &client_order_id)
3479        {
3480            index.venue_orders.remove(&old_venue);
3481        }
3482
3483        if old_instrument_id != new_instrument_id {
3484            let became_empty = Self::remove_order_from_bucket(
3485                &mut index.instrument_orders,
3486                &old_instrument_id,
3487                &client_order_id,
3488            );
3489            let has_positions = index
3490                .instrument_positions
3491                .get(&old_instrument_id)
3492                .is_some_and(|positions| !positions.is_empty());
3493
3494            if became_empty && !has_positions {
3495                index.instrument_orders.remove(&old_instrument_id);
3496            }
3497        }
3498
3499        if old_strategy_id != replacement.strategy_id() {
3500            let became_empty = Self::remove_order_from_bucket(
3501                &mut index.strategy_orders,
3502                &old_strategy_id,
3503                &client_order_id,
3504            );
3505            let has_positions = index
3506                .strategy_positions
3507                .get(&old_strategy_id)
3508                .is_some_and(|positions| !positions.is_empty());
3509
3510            if became_empty && !has_positions {
3511                index.strategy_orders.remove(&old_strategy_id);
3512                index.strategies.remove(&old_strategy_id);
3513            }
3514        }
3515
3516        if let Some(account_id) = old_order.account_id()
3517            && Some(account_id) != replacement.account_id()
3518            && Self::remove_order_from_bucket(
3519                &mut index.account_orders,
3520                &account_id,
3521                &client_order_id,
3522            )
3523        {
3524            index.account_orders.remove(&account_id);
3525        }
3526
3527        if let Some(exec_algorithm_id) = old_order.exec_algorithm_id()
3528            && Some(exec_algorithm_id) != replacement.exec_algorithm_id()
3529            && Self::remove_order_from_bucket(
3530                &mut index.exec_algorithm_orders,
3531                &exec_algorithm_id,
3532                &client_order_id,
3533            )
3534        {
3535            index.exec_algorithm_orders.remove(&exec_algorithm_id);
3536            index.exec_algorithms.remove(&exec_algorithm_id);
3537        }
3538
3539        if let Some(exec_spawn_id) = old_order.exec_spawn_id()
3540            && Some(exec_spawn_id) != replacement.exec_spawn_id()
3541            && Self::remove_order_from_bucket(
3542                &mut index.exec_spawn_orders,
3543                &exec_spawn_id,
3544                &client_order_id,
3545            )
3546        {
3547            index.exec_spawn_orders.remove(&exec_spawn_id);
3548        }
3549    }
3550
3551    fn remove_replaced_order_position_memberships(
3552        index: &mut CacheIndex,
3553        positions: &AHashMap<PositionId, SharedCell<Position>>,
3554        old_order: &OrderAny,
3555        new_position_id: PositionId,
3556    ) {
3557        let client_order_id = old_order.client_order_id();
3558        let indexed_position_id = index.order_position.get(&client_order_id).copied();
3559        let mut removed_position_id = None;
3560        for old_position_id in [indexed_position_id, old_order.position_id()]
3561            .into_iter()
3562            .flatten()
3563        {
3564            if old_position_id == new_position_id || removed_position_id == Some(old_position_id) {
3565                continue;
3566            }
3567
3568            removed_position_id = Some(old_position_id);
3569            Self::remove_replaced_order_position_membership(
3570                index,
3571                positions,
3572                client_order_id,
3573                old_position_id,
3574                old_order.instrument_id().venue,
3575            );
3576        }
3577    }
3578
3579    fn remove_replaced_order_position_membership(
3580        index: &mut CacheIndex,
3581        positions: &AHashMap<PositionId, SharedCell<Position>>,
3582        client_order_id: ClientOrderId,
3583        old_position_id: PositionId,
3584        old_venue: Venue,
3585    ) {
3586        let has_other_orders = if let Some(orders) = index.position_orders.get_mut(&old_position_id)
3587        {
3588            orders.remove(&client_order_id);
3589            !orders.is_empty()
3590        } else {
3591            index
3592                .order_position
3593                .iter()
3594                .any(|(candidate_id, candidate)| {
3595                    *candidate_id != client_order_id && *candidate == old_position_id
3596                })
3597        };
3598
3599        if positions.contains_key(&old_position_id) || has_other_orders {
3600            return;
3601        }
3602
3603        index.position_orders.remove(&old_position_id);
3604        if let Some(strategy_id) = index.position_strategy.remove(&old_position_id)
3605            && let Some(strategy_positions) = index.strategy_positions.get_mut(&strategy_id)
3606        {
3607            strategy_positions.remove(&old_position_id);
3608            if strategy_positions.is_empty() {
3609                index.strategy_positions.remove(&strategy_id);
3610            }
3611        }
3612
3613        if let Some(venue_positions) = index.venue_positions.get_mut(&old_venue) {
3614            venue_positions.remove(&old_position_id);
3615            if venue_positions.is_empty() {
3616                index.venue_positions.remove(&old_venue);
3617            }
3618        }
3619    }
3620
3621    fn remove_order_from_bucket<K: Eq + std::hash::Hash>(
3622        buckets: &mut AHashMap<K, AHashSet<ClientOrderId>>,
3623        key: &K,
3624        client_order_id: &ClientOrderId,
3625    ) -> bool {
3626        buckets.get_mut(key).is_some_and(|orders| {
3627            orders.remove(client_order_id);
3628            orders.is_empty()
3629        })
3630    }
3631
3632    /// Claims the execution-client origin for one or more cached orders.
3633    ///
3634    /// Claims are write-once: an unclaimed order is assigned to `client_id`, a matching existing
3635    /// claim is idempotent, and a conflicting claim is rejected. The complete batch is validated
3636    /// before any in-memory index is changed.
3637    ///
3638    /// Persistence failures are logged without failing the operation.
3639    ///
3640    /// # Errors
3641    ///
3642    /// Returns an error if:
3643    /// - An order is missing from the cache.
3644    /// - The batch requests conflicting clients for the same order.
3645    /// - An existing claim names another client.
3646    /// - The backing reports a DeFi currency integrity error.
3647    pub fn claim_order_clients(
3648        &mut self,
3649        claims: &[(ClientOrderId, ClientId)],
3650    ) -> anyhow::Result<()> {
3651        let mut requested = AHashMap::with_capacity(claims.len());
3652        let mut ordered_claims = Vec::with_capacity(claims.len());
3653
3654        for (client_order_id, client_id) in claims {
3655            if let Some(existing_client_id) = requested.get(client_order_id) {
3656                if existing_client_id != client_id {
3657                    anyhow::bail!(
3658                        "Conflicting execution client claims for {client_order_id}: \
3659                         {existing_client_id} and {client_id}"
3660                    );
3661                }
3662                continue;
3663            }
3664
3665            requested.insert(*client_order_id, *client_id);
3666            ordered_claims.push((*client_order_id, *client_id));
3667        }
3668
3669        let mut pending_claims = Vec::with_capacity(ordered_claims.len());
3670        for (client_order_id, client_id) in ordered_claims {
3671            if !self.orders.contains_key(&client_order_id) {
3672                return Err(OrderLookupError::not_found(client_order_id).into());
3673            }
3674
3675            match self.index.order_client.get(&client_order_id) {
3676                Some(existing_client_id) if *existing_client_id == client_id => {}
3677                Some(existing_client_id) => {
3678                    anyhow::bail!(
3679                        "Order {client_order_id} is already claimed by execution client \
3680                         {existing_client_id} and cannot be claimed by {client_id}"
3681                    );
3682                }
3683                None => pending_claims.push((client_order_id, client_id)),
3684            }
3685        }
3686
3687        if pending_claims.is_empty() {
3688            return Ok(());
3689        }
3690
3691        if let Some(database) = &self.database {
3692            handle_persistence_result(
3693                "persist execution client claims",
3694                database.index_order_clients(&pending_claims),
3695            )?;
3696        }
3697
3698        for (client_order_id, client_id) in pending_claims {
3699            self.index.order_client.insert(client_order_id, client_id);
3700            log::debug!("Claimed {client_order_id} for execution client {client_id}");
3701        }
3702
3703        Ok(())
3704    }
3705
3706    /// Adds the `order_list` to the cache.
3707    ///
3708    /// # Errors
3709    ///
3710    /// Returns an error if the order list ID is already contained in the cache.
3711    pub fn add_order_list(&mut self, order_list: OrderList) -> anyhow::Result<()> {
3712        let order_list_id = order_list.id;
3713        check_key_not_in_map(
3714            &order_list_id,
3715            &self.order_lists,
3716            stringify!(order_list_id),
3717            stringify!(order_lists),
3718        )?;
3719
3720        log::debug!("Adding {order_list}");
3721        self.order_lists.insert(order_list_id, order_list);
3722        Ok(())
3723    }
3724
3725    /// Indexes the `position_id` with the other given IDs.
3726    ///
3727    /// A cached `EXTERNAL` position retains its ownership when an order from another strategy
3728    /// is linked to it. Otherwise, the supplied `strategy_id` applies.
3729    ///
3730    /// Persistence failures are logged without failing the operation.
3731    ///
3732    /// # Errors
3733    ///
3734    /// Returns an error if the backing reports a DeFi currency integrity error.
3735    pub fn add_position_id(
3736        &mut self,
3737        position_id: &PositionId,
3738        venue: &Venue,
3739        client_order_id: &ClientOrderId,
3740        strategy_id: &StrategyId,
3741    ) -> anyhow::Result<()> {
3742        self.index_position_id_in_memory(position_id, venue, client_order_id, strategy_id);
3743        self.persist_position_id(position_id, client_order_id)
3744    }
3745
3746    fn index_position_id_in_memory(
3747        &mut self,
3748        position_id: &PositionId,
3749        venue: &Venue,
3750        client_order_id: &ClientOrderId,
3751        strategy_id: &StrategyId,
3752    ) {
3753        self.index
3754            .order_position
3755            .insert(*client_order_id, *position_id);
3756        self.index_position(position_id, venue, strategy_id);
3757        self.index
3758            .position_orders
3759            .entry(*position_id)
3760            .or_default()
3761            .insert(*client_order_id);
3762    }
3763
3764    fn persist_position_id(
3765        &mut self,
3766        position_id: &PositionId,
3767        client_order_id: &ClientOrderId,
3768    ) -> anyhow::Result<()> {
3769        if let Some(database) = &mut self.database {
3770            handle_persistence_result(
3771                format_args!("persist order position {client_order_id}"),
3772                database.index_order_position(*client_order_id, *position_id),
3773            )?;
3774        }
3775
3776        Ok(())
3777    }
3778
3779    fn index_position(
3780        &mut self,
3781        position_id: &PositionId,
3782        venue: &Venue,
3783        strategy_id: &StrategyId,
3784    ) {
3785        let strategy_id = self
3786            .positions
3787            .get(position_id)
3788            .map(|position| position.borrow().strategy_id)
3789            .filter(StrategyId::is_external)
3790            .unwrap_or(*strategy_id);
3791
3792        // Index: PositionId -> StrategyId
3793        self.index
3794            .position_strategy
3795            .insert(*position_id, strategy_id);
3796
3797        // Every position has a reverse-order bucket, including orderless positions.
3798        self.index.position_orders.entry(*position_id).or_default();
3799
3800        // Index: StrategyId -> set[PositionId]
3801        self.index
3802            .strategy_positions
3803            .entry(strategy_id)
3804            .or_default()
3805            .insert(*position_id);
3806
3807        // Index: Venue -> set[PositionId]
3808        self.index
3809            .venue_positions
3810            .entry(*venue)
3811            .or_default()
3812            .insert(*position_id);
3813    }
3814
3815    // Propagates parent OTO `position_id` to contingent children that are missing one.
3816    //
3817    // Recovers from a partial-write window during fill handling: the fill-time path in the
3818    // execution engine assigns `position_id` to each contingent child in a non-atomic loop
3819    // (`set_position_id` then `add_position_id`), so a crash mid-loop can leave the database
3820    // with the parent updated and some children un-updated. This pass re-applies any missing
3821    // assignments after load.
3822    fn assign_position_ids_to_contingencies(&mut self) {
3823        let mut assignments: Vec<(PositionId, ClientOrderId)> = Vec::new();
3824
3825        for parent_order_cell in self.orders.values() {
3826            let parent = parent_order_cell.borrow();
3827            if parent.contingency_type() != Some(ContingencyType::Oto) {
3828                continue;
3829            }
3830            let Some(parent_position_id) = parent.position_id() else {
3831                continue;
3832            };
3833            let Some(linked_order_ids) = parent.linked_order_ids() else {
3834                continue;
3835            };
3836
3837            for client_order_id in linked_order_ids {
3838                match self.orders.get(client_order_id) {
3839                    None => {
3840                        log::error!("Contingency order {client_order_id} not found");
3841                    }
3842                    Some(contingent_order_cell) => {
3843                        if contingent_order_cell.borrow().position_id().is_none() {
3844                            assignments.push((parent_position_id, *client_order_id));
3845                        }
3846                    }
3847                }
3848            }
3849        }
3850
3851        for (position_id, client_order_id) in assignments {
3852            let Some((venue, strategy_id)) = self.orders.get(&client_order_id).map(|order_cell| {
3853                let mut contingent = order_cell.borrow_mut();
3854                contingent.set_position_id(Some(position_id));
3855                (contingent.instrument_id().venue, contingent.strategy_id())
3856            }) else {
3857                continue;
3858            };
3859
3860            // Re-indexing through `add_position_id` also retries the best-effort backing write
3861            if let Err(e) =
3862                self.add_position_id(&position_id, &venue, &client_order_id, &strategy_id)
3863            {
3864                log::error!("Failed to re-index {client_order_id} -> {position_id}: {e}");
3865            }
3866        }
3867    }
3868
3869    /// Adds the `position` to the cache.
3870    ///
3871    /// For [`OmsType::Unspecified`], IDs matching `{instrument_id}-{strategy_id}` resolve to
3872    /// [`OmsType::Netting`]. Other IDs retain the supplied OMS type.
3873    ///
3874    /// Persistence failures are logged without failing the operation.
3875    ///
3876    /// # Errors
3877    ///
3878    /// Returns an error if validating or serializing the position metadata fails, or the backing
3879    /// reports a DeFi currency integrity error.
3880    pub fn add_position(&mut self, position: &Position, oms_type: OmsType) -> anyhow::Result<()> {
3881        self.add_position_inner(position.clone(), oms_type, true, false)
3882    }
3883
3884    /// Adds a position whose opening fill intentionally has no backing order.
3885    ///
3886    /// Resolves unspecified OMS types as [`Self::add_position`] does.
3887    ///
3888    /// Persistence failures are logged without failing the operation.
3889    ///
3890    /// # Errors
3891    ///
3892    /// Returns an error if validating or serializing the position metadata fails, or the backing
3893    /// reports a DeFi currency integrity error.
3894    pub fn add_position_without_order(
3895        &mut self,
3896        position: &Position,
3897        oms_type: OmsType,
3898    ) -> anyhow::Result<()> {
3899        self.add_position_inner(position.clone(), oms_type, false, false)
3900    }
3901
3902    /// Replaces the cached position holding `position.id`, optionally moving the prior cycle's
3903    /// durable replay state into it.
3904    ///
3905    /// Pass `index_order` false when the opening fill intentionally has no backing order, matching
3906    /// [`Self::add_position_without_order`]. The carry runs under the same borrow as the swap, so a
3907    /// validation failure cannot leave the prior position stripped of its replay history.
3908    ///
3909    /// Resolves unspecified OMS types as [`Self::add_position`] does.
3910    ///
3911    /// Persistence failures are logged without failing the operation.
3912    ///
3913    /// # Errors
3914    ///
3915    /// Returns an error if validating or serializing the position metadata fails, or the backing
3916    /// reports a DeFi currency integrity error.
3917    pub fn replace_position(
3918        &mut self,
3919        position: &Position,
3920        oms_type: OmsType,
3921        index_order: bool,
3922        carry_replay_state: bool,
3923    ) -> anyhow::Result<()> {
3924        self.add_position_inner(position.clone(), oms_type, index_order, carry_replay_state)
3925    }
3926
3927    fn add_position_inner(
3928        &mut self,
3929        mut position: Position,
3930        oms_type: OmsType,
3931        index_order: bool,
3932        carry_replay_state: bool,
3933    ) -> anyhow::Result<()> {
3934        let oms_type = resolve_position_oms(&position, oms_type);
3935
3936        // Validate and serialize the OMS entry up front: both are construction failures, and
3937        // committing the position before they run would leave the cache mutated by one.
3938        // The key embeds the position ID, which embeds the instrument ID and venue
3939        // symbol, and exchange symbols may contain non-ASCII characters.
3940        let key = position_oms_key(position.id);
3941        check_valid_string_utf8(&key, stringify!(key))?;
3942        let value = Bytes::from(serde_json::to_vec(&oms_type)?);
3943        check_predicate_false(value.is_empty(), stringify!(value))?;
3944
3945        let position_id = position.id;
3946        let strategy_id = position.strategy_id;
3947        let instrument_id = position.instrument_id;
3948        let account_id = position.account_id;
3949        let opening_order_id = position.opening_order_id;
3950
3951        log::debug!("Adding {position}");
3952
3953        // Reuse the existing cell on a NETTING reopen so the prior value is replaced in place,
3954        // which also lets the carried replay state move out of it instead of being copied. The
3955        // transfer and the swap share one borrow, so a failure above cannot strip the prior.
3956        let position_cell = if let Some(position_cell) = self.positions.get(&position_id).cloned() {
3957            let mut prior = position_cell.borrow_mut();
3958            if carry_replay_state {
3959                position.transfer_replay_state_from(&mut prior);
3960            }
3961            *prior = position;
3962            drop(prior);
3963            position_cell
3964        } else {
3965            let position_cell = SharedCell::new(position);
3966            self.positions.insert(position_id, position_cell.clone());
3967            position_cell
3968        };
3969
3970        self.index.position_oms.insert(position_id, oms_type);
3971        self.index.positions.insert(position_id);
3972        self.refresh_position_indexes(&position_cell.borrow());
3973        self.index.strategies.insert(strategy_id);
3974        self.index.strategy_orders.entry(strategy_id).or_default();
3975
3976        if index_order {
3977            self.index_position_id_in_memory(
3978                &position_id,
3979                &instrument_id.venue,
3980                &opening_order_id,
3981                &strategy_id,
3982            );
3983        } else {
3984            self.index_position(&position_id, &instrument_id.venue, &strategy_id);
3985        }
3986
3987        // Index: InstrumentId -> AHashSet
3988        let instrument_positions = self
3989            .index
3990            .instrument_positions
3991            .entry(instrument_id)
3992            .or_default();
3993        instrument_positions.insert(position_id);
3994        self.index
3995            .instrument_orders
3996            .entry(instrument_id)
3997            .or_default();
3998
3999        // Index: AccountId -> AHashSet<PositionId>
4000        self.index
4001            .account_positions
4002            .entry(account_id)
4003            .or_default()
4004            .insert(position_id);
4005
4006        log::debug!("Adding general {key}");
4007        self.general.insert(key.clone(), value.clone());
4008
4009        if index_order {
4010            self.persist_position_id(&position_id, &opening_order_id)?;
4011        }
4012
4013        if let Some(database) = &mut self.database {
4014            handle_persistence_result(
4015                format_args!("persist position {position_id}"),
4016                database.add_position(&position_cell.borrow()),
4017            )?;
4018            // TODO: Implement position snapshots
4019            // if self.snapshot_positions {
4020            //     database.snapshot_position_state(
4021            //         position,
4022            //         position.ts_last,
4023            //         self.calculate_unrealized_pnl(&position),
4024            //     )?;
4025            // }
4026            handle_persistence_result(
4027                format_args!("persist OMS metadata for position {position_id}"),
4028                database.add(key, value),
4029            )?;
4030        }
4031
4032        Ok(())
4033    }
4034
4035    /// Updates the `account` in the cache.
4036    ///
4037    /// Reuses the existing cell when present so any held [`AccountRef`] handles continue to point
4038    /// at the canonical entry; only inserts a new cell when the account is unknown.
4039    ///
4040    /// Persistence failures are logged without failing the operation.
4041    ///
4042    /// # Errors
4043    ///
4044    /// Returns an error if a referenced currency conflicts with existing state or the backing
4045    /// reports a DeFi currency integrity error.
4046    pub fn update_account(&mut self, account: &AccountAny) -> anyhow::Result<()> {
4047        let account_id = account.id();
4048        match self.accounts.get(&account_id) {
4049            Some(account_cell) => *account_cell.borrow_mut() = account.clone(),
4050            None => {
4051                self.accounts
4052                    .insert(account_id, SharedCell::new(account.clone()));
4053            }
4054        }
4055
4056        self.add_account_currencies(account)?;
4057
4058        if let Some(database) = &mut self.database {
4059            handle_persistence_result(
4060                format_args!("persist account {account_id}"),
4061                database.update_account(account),
4062            )?;
4063        }
4064        Ok(())
4065    }
4066
4067    /// Returns an owned `account`, removing its cache entry when ownership is exclusive.
4068    ///
4069    /// This supports hot paths which need owned account mutation without
4070    /// cloning the account event history. The cache is the sole owner of the
4071    /// account cell (the field is private and accessors only hand out
4072    /// lifetime-scoped [`AccountRef`] borrows). When the cache is the sole owner, the value is
4073    /// moved out of its cell rather than cloned.
4074    ///
4075    /// If another strong handle exists, the canonical entry remains cached and this returns
4076    /// `None`.
4077    #[must_use]
4078    pub fn take_account(&mut self, account_id: &AccountId) -> Option<AccountAny> {
4079        let cell = self.accounts.remove(account_id)?;
4080        let rc: Rc<RefCell<AccountAny>> = cell.into();
4081
4082        match Rc::try_unwrap(rc) {
4083            Ok(cell) => Some(cell.into_inner()),
4084            Err(rc) => {
4085                log::error!(
4086                    "Cannot move account {account_id} out of cache: account cell has an outstanding owner"
4087                );
4088                self.accounts.insert(*account_id, rc.into());
4089                None
4090            }
4091        }
4092    }
4093
4094    /// Caches the `account` in memory without updating the database.
4095    pub fn cache_account_owned(&mut self, account: AccountAny) {
4096        let account_id = account.id();
4097        self.index.add_venue_account(account_id);
4098        match self.accounts.get(&account_id) {
4099            Some(account_cell) => *account_cell.borrow_mut() = account,
4100            None => {
4101                self.accounts.insert(account_id, SharedCell::new(account));
4102            }
4103        }
4104    }
4105
4106    /// Updates the `account` in the cache, taking ownership of the updated account.
4107    ///
4108    /// Persistence failures are logged without failing the operation.
4109    ///
4110    /// # Errors
4111    ///
4112    /// Returns an error if the account is missing after insertion, a currency conflicts with
4113    /// existing state, or the backing reports a DeFi currency integrity error.
4114    pub fn update_account_owned(&mut self, account: AccountAny) -> anyhow::Result<()> {
4115        let account_id = account.id();
4116        // Retain an account taken out by the caller even if a referenced currency fails validation
4117        let currencies: Vec<Currency> = account
4118            .last_event()
4119            .map(|state| Self::state_currencies(&state).collect())
4120            .unwrap_or_default();
4121        self.cache_account_owned(account);
4122
4123        for currency in currencies {
4124            self.add_currency(currency)?;
4125        }
4126
4127        if let Some(database) = &mut self.database {
4128            let Some(account_cell) = self.accounts.get(&account_id) else {
4129                anyhow::bail!("Account {account_id} not found after cache update");
4130            };
4131
4132            handle_persistence_result(
4133                format_args!("persist account {account_id}"),
4134                database.update_account(&account_cell.borrow()),
4135            )?;
4136        }
4137        Ok(())
4138    }
4139
4140    /// Applies an account state event to the cached account.
4141    ///
4142    /// Mutates the cached account in place to avoid cloning the account event
4143    /// history on the hot path; long-running sessions accumulate many events
4144    /// per account, so a snapshot-clone here would be O(history) per update.
4145    ///
4146    /// Persistence failures are logged without failing the operation.
4147    ///
4148    /// # Errors
4149    ///
4150    /// Returns an error if the account rejects the event, a currency conflicts with existing state,
4151    /// or the backing reports a DeFi currency integrity error.
4152    pub fn update_account_state(&mut self, event: &AccountState) -> anyhow::Result<()> {
4153        let Some(cell) = self.accounts.get(&event.account_id) else {
4154            return self.add_account(AccountAny::from_events(std::slice::from_ref(event))?);
4155        };
4156
4157        // Keep the account current even if a referenced currency subsequently fails validation
4158        cell.borrow_mut().apply(event.clone())?;
4159
4160        // The event carries every currency the account references after it, so the account
4161        // itself is not cloned on this path.
4162        for currency in Self::state_currencies(event) {
4163            self.add_currency(currency)?;
4164        }
4165
4166        let Some(cell) = self.accounts.get(&event.account_id) else {
4167            anyhow::bail!("Account {} not found after apply", event.account_id);
4168        };
4169
4170        if let Some(database) = &mut self.database {
4171            handle_persistence_result(
4172                format_args!("persist account {}", event.account_id),
4173                database.update_account(&cell.borrow()),
4174            )?;
4175        }
4176        Ok(())
4177    }
4178
4179    /// Replaces the cached `order` from a non-event snapshot.
4180    ///
4181    /// Prefer [`Self::update_order`] for lifecycle state changes. Use this only for order state
4182    /// that is not represented by [`OrderEventAny`].
4183    ///
4184    /// Persistence failures are logged without failing the operation.
4185    ///
4186    /// # Errors
4187    ///
4188    /// Returns an error if validating the replacement or its index ownership fails, or the backing
4189    /// reports a DeFi currency integrity error.
4190    pub fn replace_order(&mut self, order: &OrderAny) -> anyhow::Result<()> {
4191        let client_order_id = order.client_order_id();
4192        if let Some(venue_order_id) = order.venue_order_id() {
4193            self.validate_venue_order_id_ownership(&client_order_id, &venue_order_id)?;
4194        }
4195
4196        match self.orders.get(&client_order_id) {
4197            // Reuse the existing cell so the canonical entry stays in place rather than
4198            // orphaning a stale cell.
4199            Some(order_cell) => *order_cell.borrow_mut() = order.clone(),
4200            None => {
4201                self.orders
4202                    .insert(client_order_id, SharedCell::new(order.clone()));
4203            }
4204        }
4205
4206        self.refresh_order(order)
4207    }
4208
4209    /// Updates the cached order by applying an event and refreshing derived cache state.
4210    ///
4211    /// Persistence failures are logged without failing the operation.
4212    ///
4213    /// # Errors
4214    ///
4215    /// Returns an error if:
4216    /// - The order is missing.
4217    /// - The order rejects the event.
4218    /// - The order claims another order's venue order ID.
4219    /// - The backing reports a DeFi currency integrity error.
4220    pub fn update_order(&mut self, event: &OrderEventAny) -> anyhow::Result<OrderAny> {
4221        let event_client_order_id = event.client_order_id();
4222        let client_order_id = if self.order_exists(&event_client_order_id) {
4223            event_client_order_id
4224        } else if let Some(venue_order_id) = event.venue_order_id() {
4225            self.index
4226                .venue_order_ids
4227                .get(&venue_order_id)
4228                .copied()
4229                .ok_or(OrderError::NotFound(event_client_order_id))?
4230        } else {
4231            return Err(OrderError::NotFound(event_client_order_id).into());
4232        };
4233
4234        let order_cell = self
4235            .orders
4236            .get(&client_order_id)
4237            .cloned()
4238            .ok_or(OrderError::NotFound(client_order_id))?;
4239
4240        // Apply on a snapshot first so a fallible `apply` (e.g. invalid state
4241        // transition) leaves the canonical cell untouched. On success we swap the
4242        // post-event value back into the cell so subsequent reads see the new state.
4243        let mut snapshot = order_cell.borrow().clone();
4244        snapshot.apply(event.clone())?;
4245
4246        // Preflight only reverse ownership. A same-client forward mismatch remains a logged
4247        // refresh inconsistency, while other refresh failures, such as a backing database error,
4248        // remain logged after the canonical state is committed.
4249        if let Some(venue_order_id) = snapshot.venue_order_id() {
4250            self.validate_venue_order_id_ownership(&client_order_id, &venue_order_id)?;
4251        }
4252
4253        *order_cell.borrow_mut() = snapshot.clone();
4254
4255        if matches!(event, OrderEventAny::FillVoided(_)) {
4256            self.reindex_hedging_position(client_order_id);
4257        }
4258
4259        if let Err(e) = self.refresh_order(&snapshot) {
4260            log::error!("Error updating order in cache: {e}");
4261        }
4262
4263        Ok(snapshot)
4264    }
4265
4266    fn refresh_order(&mut self, order: &OrderAny) -> anyhow::Result<()> {
4267        let client_order_id = order.client_order_id();
4268
4269        // Claim the venue order ID before mutating any other derived state. An updated event may
4270        // change the current ID for the same client order, while historical reverse aliases remain.
4271        if let Some(venue_order_id) = order.venue_order_id() {
4272            let overwrite = matches!(order.last_event(), OrderEventAny::Updated(_));
4273            if let Err(e) = self.add_venue_order_id(&client_order_id, &venue_order_id, overwrite) {
4274                if e.is::<VenueOrderIdOwnershipError>() {
4275                    return Err(e);
4276                }
4277                log::error!("Error indexing venue order ID in cache: {e}");
4278            }
4279        }
4280
4281        if order.is_active_local() {
4282            self.index.orders_active_local.insert(client_order_id);
4283        } else {
4284            self.index.orders_active_local.remove(&client_order_id);
4285        }
4286
4287        // Update in-flight state
4288        if order.is_inflight() {
4289            self.index.orders_inflight.insert(client_order_id);
4290        } else {
4291            self.index.orders_inflight.remove(&client_order_id);
4292        }
4293
4294        // Update open/closed state
4295        if order.is_open() {
4296            self.index.orders_closed.remove(&client_order_id);
4297            self.index.orders_open.insert(client_order_id);
4298        } else {
4299            self.index.orders_open.remove(&client_order_id);
4300        }
4301
4302        if order.is_closed() {
4303            self.index.orders_pending_cancel.remove(&client_order_id);
4304            self.index.orders_closed.insert(client_order_id);
4305        }
4306
4307        self.refresh_order_pending_cancel(order);
4308
4309        // Update emulation index
4310        if order.emulation_trigger().is_some() && !order.is_closed() {
4311            self.index.orders_emulated.insert(client_order_id);
4312        } else {
4313            self.index.orders_emulated.remove(&client_order_id);
4314        }
4315
4316        // Update account orders index when account_id becomes available
4317        if let Some(account_id) = order.account_id() {
4318            self.index
4319                .account_orders
4320                .entry(account_id)
4321                .or_default()
4322                .insert(client_order_id);
4323        }
4324
4325        // Update own book
4326        if !self.own_books.is_empty() {
4327            let own_book = self.own_order_book(&order.instrument_id());
4328            if (own_book.is_some() && order.is_closed()) || should_handle_own_book_order(order) {
4329                self.update_own_order_book(order);
4330            }
4331        }
4332
4333        if let Some(database) = &mut self.database {
4334            handle_persistence_result(
4335                format_args!("persist order {}", order.client_order_id()),
4336                database.update_order(order.last_event()),
4337            )?;
4338            // TODO: Implement order snapshots
4339            // if self.snapshot_orders {
4340            //     database.snapshot_order_state(order)?;
4341            // }
4342        }
4343
4344        Ok(())
4345    }
4346
4347    fn refresh_order_pending_cancel(&mut self, order: &OrderAny) {
4348        if matches!(
4349            order.last_event(),
4350            OrderEventAny::CancelDenied(_) | OrderEventAny::CancelRejected(_)
4351        ) && !order.has_pending_cancel_command()
4352        {
4353            self.index
4354                .orders_pending_cancel
4355                .remove(&order.client_order_id());
4356        }
4357    }
4358
4359    /// Updates the `order` as pending cancel locally.
4360    pub fn update_order_pending_cancel_local(&mut self, order: &OrderAny) {
4361        self.index
4362            .orders_pending_cancel
4363            .insert(order.client_order_id());
4364    }
4365
4366    /// Updates a `position` already held in the cache.
4367    ///
4368    /// Reuses the existing cell so any held [`PositionRef`] handles continue to point at the
4369    /// canonical entry.
4370    ///
4371    /// Persistence failures are logged without failing the operation.
4372    ///
4373    /// # Errors
4374    ///
4375    /// Returns an error if the position is not already held in the cache or the backing reports a
4376    /// DeFi currency integrity error.
4377    pub fn update_position(&mut self, position: &Position) -> anyhow::Result<()> {
4378        let Some(position_cell) = self.positions.get(&position.id).cloned() else {
4379            anyhow::bail!("Cannot update position {}: not found in cache", position.id);
4380        };
4381
4382        self.refresh_position_indexes(position);
4383
4384        *position_cell.borrow_mut() = position.clone();
4385
4386        if let Some(database) = &mut self.database {
4387            handle_persistence_result(
4388                format_args!("persist position {}", position.id),
4389                database.update_position(position),
4390            )?;
4391            // TODO: Implement order snapshots
4392            // if self.snapshot_orders {
4393            //     database.snapshot_order_state(order)?;
4394            // }
4395        }
4396
4397        Ok(())
4398    }
4399
4400    /// Updates a cached position by applying an order fill in place.
4401    ///
4402    /// Returns a transient copy of the updated state without stored history. The canonical cached
4403    /// position retains its complete history. A fill without a position ID uses `position_id`.
4404    ///
4405    /// Persistence failures are logged without failing the operation.
4406    ///
4407    /// # Errors
4408    ///
4409    /// Returns an error if the position is missing, the fill fails accounting validation, or the
4410    /// backing reports a DeFi currency integrity error.
4411    pub fn update_position_from_fill(
4412        &mut self,
4413        position_id: PositionId,
4414        fill: &OrderFilled,
4415    ) -> anyhow::Result<Position> {
4416        let Some(position_cell) = self.positions.get(&position_id).cloned() else {
4417            anyhow::bail!("Cannot update position {position_id}: not found in cache");
4418        };
4419
4420        let mut resolved_fill;
4421        let fill = if fill.position_id.is_none() {
4422            resolved_fill = fill.clone();
4423            resolved_fill.position_id = Some(position_id);
4424            &resolved_fill
4425        } else {
4426            fill
4427        };
4428
4429        let position = {
4430            let mut position = position_cell.borrow_mut();
4431            position.try_apply(fill)?;
4432            position.clone_without_events()
4433        };
4434
4435        self.refresh_position_indexes(&position);
4436
4437        if let Some(database) = &mut self.database {
4438            handle_persistence_result(
4439                format_args!("persist position {position_id}"),
4440                database.update_position(&position_cell.borrow()),
4441            )?;
4442        }
4443
4444        Ok(position)
4445    }
4446
4447    /// Updates a cached position by applying an adjustment in place.
4448    ///
4449    /// The canonical cached position retains its complete history. A backing integrity rejection
4450    /// leaves the adjustment applied. Use [`Self::revert_position_adjustment`] to undo the adjustment
4451    /// after that rejection or a later settlement failure.
4452    ///
4453    /// Persistence failures are logged without failing the operation.
4454    ///
4455    /// # Errors
4456    ///
4457    /// Returns an error if the position is missing, the adjustment fails validation, or the backing
4458    /// reports a DeFi currency integrity error.
4459    pub fn update_position_from_adjustment(
4460        &mut self,
4461        position_id: PositionId,
4462        adjustment: PositionAdjusted,
4463    ) -> anyhow::Result<()> {
4464        let Some(position_cell) = self.positions.get(&position_id).cloned() else {
4465            anyhow::bail!("Cannot update position {position_id}: not found in cache");
4466        };
4467
4468        position_cell.borrow_mut().apply_adjustment(adjustment)?;
4469        self.refresh_position_indexes(&position_cell.borrow());
4470
4471        if let Some(database) = &mut self.database {
4472            handle_persistence_result(
4473                format_args!("persist position {position_id}"),
4474                database.update_position(&position_cell.borrow()),
4475            )?;
4476        }
4477
4478        Ok(())
4479    }
4480
4481    /// Reverts the last adjustment applied to a cached position in place.
4482    ///
4483    /// Restores the position state from `prior`, the snapshot taken before the adjustment was
4484    /// applied, then refreshes the position indexes and persists the restored position.
4485    ///
4486    /// Persistence failures are logged without failing the operation.
4487    ///
4488    /// # Errors
4489    ///
4490    /// Returns an error if the position is missing, the adjustment cannot be reverted, or the backing
4491    /// reports a DeFi currency integrity error.
4492    pub fn revert_position_adjustment(&mut self, prior: &Position) -> anyhow::Result<()> {
4493        let Some(position_cell) = self.positions.get(&prior.id).cloned() else {
4494            anyhow::bail!("Cannot revert position {}: not found in cache", prior.id);
4495        };
4496
4497        position_cell.borrow_mut().revert_last_adjustment(prior)?;
4498        self.refresh_position_indexes(&position_cell.borrow());
4499
4500        if let Some(database) = &mut self.database {
4501            handle_persistence_result(
4502                format_args!("persist position {}", prior.id),
4503                database.update_position(&position_cell.borrow()),
4504            )?;
4505        }
4506
4507        Ok(())
4508    }
4509
4510    /// Updates a cached position by applying an authoritative instrument close in place.
4511    ///
4512    /// Returns a transient copy of the settled state without stored history. The canonical cached
4513    /// position retains its complete history, including the close. Ordinary persistence failures
4514    /// are logged without failing the operation.
4515    ///
4516    /// # Errors
4517    ///
4518    /// Returns an error if the position is missing, the close cannot be applied, or the backing
4519    /// reports a DeFi currency integrity error.
4520    /// A missing position or invalid close leaves the cache unchanged.
4521    pub fn update_position_from_instrument_close(
4522        &mut self,
4523        position_id: PositionId,
4524        close: InstrumentClose,
4525    ) -> anyhow::Result<Position> {
4526        let Some(position_cell) = self.positions.get(&position_id).cloned() else {
4527            anyhow::bail!("Cannot update position {position_id}: not found in cache");
4528        };
4529
4530        let position = {
4531            let mut position = position_cell.borrow_mut();
4532            position.apply_instrument_close(close)?;
4533            position.clone_without_events()
4534        };
4535
4536        self.refresh_position_indexes(&position);
4537
4538        if let Some(database) = &mut self.database {
4539            handle_persistence_result(
4540                format_args!("persist instrument close for position {position_id}"),
4541                database.update_position(&position_cell.borrow()),
4542            )?;
4543        }
4544
4545        Ok(position)
4546    }
4547
4548    fn refresh_position_indexes(&mut self, position: &Position) {
4549        if position.is_open() {
4550            self.index.positions_open.insert(position.id);
4551            self.index.positions_closed.remove(&position.id);
4552        } else {
4553            self.index.positions_closed.insert(position.id);
4554            self.index.positions_open.remove(&position.id);
4555        }
4556    }
4557
4558    /// Gets the OMS type for the `position_id`.
4559    #[must_use]
4560    pub fn oms_type(&self, position_id: &PositionId) -> Option<OmsType> {
4561        self.index.position_oms.get(position_id).copied()
4562    }
4563
4564    /// Snapshots the `order` state in the database.
4565    ///
4566    /// Persistence failures are logged without failing the operation.
4567    ///
4568    /// # Errors
4569    ///
4570    /// Returns an error if the backing reports a DeFi currency integrity error.
4571    pub fn snapshot_order_state(&self, order: &OrderAny) -> anyhow::Result<()> {
4572        let Some(database) = &self.database else {
4573            log::warn!(
4574                "Cannot snapshot order state for {} (no database configured)",
4575                order.client_order_id()
4576            );
4577            return Ok(());
4578        };
4579
4580        handle_persistence_result(
4581            format_args!("snapshot order {}", order.client_order_id()),
4582            database.snapshot_order_state(order),
4583        )
4584    }
4585
4586    // -- IDENTIFIER QUERIES ----------------------------------------------------------------------
4587
4588    // Collects references to the index sets that constrain an order query.
4589    //
4590    // Returns:
4591    // - `FilterSources::Unfiltered` when no filter is provided (the caller should iterate
4592    //   the full bucket).
4593    // - `FilterSources::Empty` when a filter is provided but the index has no entry for it
4594    //   (the resolved set is unconditionally empty, no further work needed).
4595    // - `FilterSources::Sets` with borrowed references to each filter source set.
4596    fn collect_order_filter_sources<'a>(
4597        &'a self,
4598        venue: Option<&Venue>,
4599        instrument_id: Option<&InstrumentId>,
4600        strategy_id: Option<&StrategyId>,
4601        account_id: Option<&AccountId>,
4602    ) -> FilterSources<'a, ClientOrderId> {
4603        let mut sources: Vec<&AHashSet<ClientOrderId>> = Vec::with_capacity(4);
4604
4605        if let Some(venue) = venue {
4606            match self.index.venue_orders.get(venue) {
4607                Some(set) => sources.push(set),
4608                None => return FilterSources::Empty,
4609            }
4610        }
4611
4612        if let Some(instrument_id) = instrument_id {
4613            match self.index.instrument_orders.get(instrument_id) {
4614                Some(set) => sources.push(set),
4615                None => return FilterSources::Empty,
4616            }
4617        }
4618
4619        if let Some(strategy_id) = strategy_id {
4620            match self.index.strategy_orders.get(strategy_id) {
4621                Some(set) => sources.push(set),
4622                None => return FilterSources::Empty,
4623            }
4624        }
4625
4626        if let Some(account_id) = account_id {
4627            match self.index.account_orders.get(account_id) {
4628                Some(set) => sources.push(set),
4629                None => return FilterSources::Empty,
4630            }
4631        }
4632
4633        if sources.is_empty() {
4634            FilterSources::Unfiltered
4635        } else {
4636            FilterSources::Sets(sources)
4637        }
4638    }
4639
4640    fn collect_position_filter_sources<'a>(
4641        &'a self,
4642        venue: Option<&Venue>,
4643        instrument_id: Option<&InstrumentId>,
4644        strategy_id: Option<&StrategyId>,
4645        account_id: Option<&AccountId>,
4646    ) -> FilterSources<'a, PositionId> {
4647        let mut sources: Vec<&AHashSet<PositionId>> = Vec::with_capacity(4);
4648
4649        if let Some(venue) = venue {
4650            match self.index.venue_positions.get(venue) {
4651                Some(set) => sources.push(set),
4652                None => return FilterSources::Empty,
4653            }
4654        }
4655
4656        if let Some(instrument_id) = instrument_id {
4657            match self.index.instrument_positions.get(instrument_id) {
4658                Some(set) => sources.push(set),
4659                None => return FilterSources::Empty,
4660            }
4661        }
4662
4663        if let Some(strategy_id) = strategy_id {
4664            match self.index.strategy_positions.get(strategy_id) {
4665                Some(set) => sources.push(set),
4666                None => return FilterSources::Empty,
4667            }
4668        }
4669
4670        if let Some(account_id) = account_id {
4671            match self.index.account_positions.get(account_id) {
4672                Some(set) => sources.push(set),
4673                None => return FilterSources::Empty,
4674            }
4675        }
4676
4677        if sources.is_empty() {
4678            FilterSources::Unfiltered
4679        } else {
4680            FilterSources::Sets(sources)
4681        }
4682    }
4683
4684    // Materializes the `ClientOrderId`s in `bucket` matching the optional filter parameters.
4685    //
4686    // Folds the bucket into the filter sources and runs a single size-ordered intersection,
4687    // avoiding the legacy two-step build-filter-set + bucket-intersection that allocated and
4688    // rehashed twice.
4689    fn query_orders_in_bucket(
4690        &self,
4691        bucket: &AHashSet<ClientOrderId>,
4692        venue: Option<&Venue>,
4693        instrument_id: Option<&InstrumentId>,
4694        strategy_id: Option<&StrategyId>,
4695        account_id: Option<&AccountId>,
4696    ) -> AHashSet<ClientOrderId> {
4697        match self.collect_order_filter_sources(venue, instrument_id, strategy_id, account_id) {
4698            FilterSources::Empty => AHashSet::new(),
4699            FilterSources::Unfiltered => bucket.clone(),
4700            FilterSources::Sets(sources) => intersect_pair_or_many(bucket, sources),
4701        }
4702    }
4703
4704    fn query_positions_in_bucket(
4705        &self,
4706        bucket: &AHashSet<PositionId>,
4707        venue: Option<&Venue>,
4708        instrument_id: Option<&InstrumentId>,
4709        strategy_id: Option<&StrategyId>,
4710        account_id: Option<&AccountId>,
4711    ) -> AHashSet<PositionId> {
4712        match self.collect_position_filter_sources(venue, instrument_id, strategy_id, account_id) {
4713            FilterSources::Empty => AHashSet::new(),
4714            FilterSources::Unfiltered => bucket.clone(),
4715            FilterSources::Sets(sources) => intersect_pair_or_many(bucket, sources),
4716        }
4717    }
4718
4719    // Returns a borrowed or owned view of the orders in `bucket` matching the optional filter
4720    // parameters. Avoids cloning the bucket when no filter narrows it.
4721    fn view_orders_in_bucket<'a>(
4722        &'a self,
4723        bucket: &'a AHashSet<ClientOrderId>,
4724        venue: Option<&Venue>,
4725        instrument_id: Option<&InstrumentId>,
4726        strategy_id: Option<&StrategyId>,
4727        account_id: Option<&AccountId>,
4728    ) -> Cow<'a, AHashSet<ClientOrderId>> {
4729        match self.collect_order_filter_sources(venue, instrument_id, strategy_id, account_id) {
4730            FilterSources::Empty => Cow::Owned(AHashSet::new()),
4731            FilterSources::Unfiltered => Cow::Borrowed(bucket),
4732            FilterSources::Sets(sources) => Cow::Owned(intersect_pair_or_many(bucket, sources)),
4733        }
4734    }
4735
4736    fn view_positions_in_bucket<'a>(
4737        &'a self,
4738        bucket: &'a AHashSet<PositionId>,
4739        venue: Option<&Venue>,
4740        instrument_id: Option<&InstrumentId>,
4741        strategy_id: Option<&StrategyId>,
4742        account_id: Option<&AccountId>,
4743    ) -> Cow<'a, AHashSet<PositionId>> {
4744        match self.collect_position_filter_sources(venue, instrument_id, strategy_id, account_id) {
4745            FilterSources::Empty => Cow::Owned(AHashSet::new()),
4746            FilterSources::Unfiltered => Cow::Borrowed(bucket),
4747            FilterSources::Sets(sources) => Cow::Owned(intersect_pair_or_many(bucket, sources)),
4748        }
4749    }
4750
4751    // Returns a lazy iterator yielding the [`ClientOrderId`]s in `bucket` matching the optional
4752    // filter parameters. Avoids any [`Vec`] or [`AHashSet`] materialization in the result path,
4753    // and (for multi-filter calls) drives intersection from the smallest source while looking
4754    // up membership in the rest.
4755    fn iter_orders_in_bucket<'a>(
4756        &'a self,
4757        bucket: &'a AHashSet<ClientOrderId>,
4758        venue: Option<&Venue>,
4759        instrument_id: Option<&InstrumentId>,
4760        strategy_id: Option<&StrategyId>,
4761        account_id: Option<&AccountId>,
4762    ) -> Box<dyn Iterator<Item = ClientOrderId> + 'a> {
4763        match self.collect_order_filter_sources(venue, instrument_id, strategy_id, account_id) {
4764            FilterSources::Empty => Box::new(std::iter::empty()),
4765            FilterSources::Unfiltered => Box::new(bucket.iter().copied()),
4766            FilterSources::Sets(mut sources) => {
4767                sources.push(bucket);
4768                sources.sort_unstable_by_key(|s| s.len());
4769                let driver = sources[0];
4770                let rest: Vec<&'a AHashSet<ClientOrderId>> = sources[1..].to_vec();
4771                Box::new(
4772                    driver
4773                        .iter()
4774                        .copied()
4775                        .filter(move |id| rest.iter().all(|s| s.contains(id))),
4776                )
4777            }
4778        }
4779    }
4780
4781    fn iter_positions_in_bucket<'a>(
4782        &'a self,
4783        bucket: &'a AHashSet<PositionId>,
4784        venue: Option<&Venue>,
4785        instrument_id: Option<&InstrumentId>,
4786        strategy_id: Option<&StrategyId>,
4787        account_id: Option<&AccountId>,
4788    ) -> Box<dyn Iterator<Item = PositionId> + 'a> {
4789        match self.collect_position_filter_sources(venue, instrument_id, strategy_id, account_id) {
4790            FilterSources::Empty => Box::new(std::iter::empty()),
4791            FilterSources::Unfiltered => Box::new(bucket.iter().copied()),
4792            FilterSources::Sets(mut sources) => {
4793                sources.push(bucket);
4794                sources.sort_unstable_by_key(|s| s.len());
4795                let driver = sources[0];
4796                let rest: Vec<&'a AHashSet<PositionId>> = sources[1..].to_vec();
4797                Box::new(
4798                    driver
4799                        .iter()
4800                        .copied()
4801                        .filter(move |id| rest.iter().all(|s| s.contains(id))),
4802                )
4803            }
4804        }
4805    }
4806
4807    // Counts orders in `bucket` matching the optional filter parameters.
4808    //
4809    // Drives intersection from the smallest filter source (or the bucket itself when no filter
4810    // is provided) and short-circuits by counting rather than collecting. With a side filter,
4811    // each candidate order is borrowed via its cell only long enough to inspect the side.
4812    fn count_orders_in_bucket(
4813        &self,
4814        bucket: &AHashSet<ClientOrderId>,
4815        venue: Option<&Venue>,
4816        instrument_id: Option<&InstrumentId>,
4817        strategy_id: Option<&StrategyId>,
4818        account_id: Option<&AccountId>,
4819        side: Option<OrderSide>,
4820    ) -> usize {
4821        match self.collect_order_filter_sources(venue, instrument_id, strategy_id, account_id) {
4822            FilterSources::Empty => 0,
4823            FilterSources::Unfiltered => side.map_or_else(
4824                || bucket.len(),
4825                |side| {
4826                    bucket
4827                        .iter()
4828                        .filter(|id| self.order_side_matches(id, side))
4829                        .count()
4830                },
4831            ),
4832            FilterSources::Sets(mut sources) => {
4833                sources.push(bucket);
4834                sources.sort_unstable_by_key(|s| s.len());
4835                let driver = sources[0];
4836                let rest = &sources[1..];
4837
4838                driver
4839                    .iter()
4840                    .filter(|id| rest.iter().all(|s| s.contains(id)))
4841                    .filter(|id| side.is_none_or(|side| self.order_side_matches(id, side)))
4842                    .count()
4843            }
4844        }
4845    }
4846
4847    fn count_positions_in_bucket(
4848        &self,
4849        bucket: &AHashSet<PositionId>,
4850        venue: Option<&Venue>,
4851        instrument_id: Option<&InstrumentId>,
4852        strategy_id: Option<&StrategyId>,
4853        account_id: Option<&AccountId>,
4854        side: Option<PositionSide>,
4855    ) -> usize {
4856        match self.collect_position_filter_sources(venue, instrument_id, strategy_id, account_id) {
4857            FilterSources::Empty => 0,
4858            FilterSources::Unfiltered => side.map_or_else(
4859                || bucket.len(),
4860                |side| {
4861                    bucket
4862                        .iter()
4863                        .filter(|id| self.position_side_matches(id, side))
4864                        .count()
4865                },
4866            ),
4867            FilterSources::Sets(mut sources) => {
4868                sources.push(bucket);
4869                sources.sort_unstable_by_key(|s| s.len());
4870                let driver = sources[0];
4871                let rest = &sources[1..];
4872
4873                driver
4874                    .iter()
4875                    .filter(|id| rest.iter().all(|s| s.contains(id)))
4876                    .filter(|id| side.is_none_or(|side| self.position_side_matches(id, side)))
4877                    .count()
4878            }
4879        }
4880    }
4881
4882    // Returns whether any order in `bucket` matches the optional filter parameters.
4883    //
4884    // Mirrors `count_orders_in_bucket` but short-circuits on the first match. Useful for
4885    // `is_empty`-style gating in hot paths where the caller only needs to know whether at
4886    // least one matching order exists.
4887    fn any_orders_in_bucket(
4888        &self,
4889        bucket: &AHashSet<ClientOrderId>,
4890        venue: Option<&Venue>,
4891        instrument_id: Option<&InstrumentId>,
4892        strategy_id: Option<&StrategyId>,
4893        account_id: Option<&AccountId>,
4894        side: Option<OrderSide>,
4895    ) -> bool {
4896        match self.collect_order_filter_sources(venue, instrument_id, strategy_id, account_id) {
4897            FilterSources::Empty => false,
4898            FilterSources::Unfiltered => side.map_or_else(
4899                || !bucket.is_empty(),
4900                |side| bucket.iter().any(|id| self.order_side_matches(id, side)),
4901            ),
4902            FilterSources::Sets(mut sources) => {
4903                sources.push(bucket);
4904                sources.sort_unstable_by_key(|s| s.len());
4905                let driver = sources[0];
4906                let rest = &sources[1..];
4907
4908                driver
4909                    .iter()
4910                    .filter(|id| rest.iter().all(|s| s.contains(id)))
4911                    .any(|id| side.is_none_or(|side| self.order_side_matches(id, side)))
4912            }
4913        }
4914    }
4915
4916    fn any_positions_in_bucket(
4917        &self,
4918        bucket: &AHashSet<PositionId>,
4919        venue: Option<&Venue>,
4920        instrument_id: Option<&InstrumentId>,
4921        strategy_id: Option<&StrategyId>,
4922        account_id: Option<&AccountId>,
4923        side: Option<PositionSide>,
4924    ) -> bool {
4925        match self.collect_position_filter_sources(venue, instrument_id, strategy_id, account_id) {
4926            FilterSources::Empty => false,
4927            FilterSources::Unfiltered => side.map_or_else(
4928                || !bucket.is_empty(),
4929                |side| bucket.iter().any(|id| self.position_side_matches(id, side)),
4930            ),
4931            FilterSources::Sets(mut sources) => {
4932                sources.push(bucket);
4933                sources.sort_unstable_by_key(|s| s.len());
4934                let driver = sources[0];
4935                let rest = &sources[1..];
4936
4937                driver
4938                    .iter()
4939                    .filter(|id| rest.iter().all(|s| s.contains(id)))
4940                    .any(|id| side.is_none_or(|side| self.position_side_matches(id, side)))
4941            }
4942        }
4943    }
4944
4945    fn order_side_matches(&self, client_order_id: &ClientOrderId, side: OrderSide) -> bool {
4946        self.orders
4947            .get(client_order_id)
4948            .is_some_and(|cell| cell.borrow().order_side() == side)
4949    }
4950
4951    fn position_side_matches(&self, position_id: &PositionId, side: PositionSide) -> bool {
4952        self.positions
4953            .get(position_id)
4954            .is_some_and(|cell| cell.borrow().side == side)
4955    }
4956
4957    /// Retrieves orders corresponding to the `client_order_ids`, optionally filtering by `side`.
4958    ///
4959    /// # Panics
4960    ///
4961    /// Panics if any `client_order_id` in the input is not found in the cache.
4962    fn get_orders_for_ids(
4963        &self,
4964        client_order_ids: impl IntoIterator<Item = ClientOrderId>,
4965        side: Option<OrderSide>,
4966    ) -> Vec<OrderRef<'_>> {
4967        const UNCACHED_SORT_MAX_LEN: usize = 32;
4968
4969        let mut orders = Vec::new();
4970
4971        for client_order_id in client_order_ids {
4972            let order_cell = self
4973                .orders
4974                .get(&client_order_id)
4975                .unwrap_or_else(|| panic!("Order {client_order_id} not found"));
4976            let order = OrderRef::new(order_cell.borrow());
4977
4978            if side.is_none_or(|side| side == order.order_side()) {
4979                orders.push(order);
4980            }
4981        }
4982
4983        // Sort so callers receive a deterministic Vec across runs; the
4984        // underlying ID sources are AHash-backed.
4985        let key = |order: &OrderRef<'_>| order.client_order_id();
4986
4987        if orders.len() <= UNCACHED_SORT_MAX_LEN {
4988            orders.sort_by_key(key);
4989        } else {
4990            orders.sort_by_cached_key(key);
4991        }
4992
4993        orders
4994    }
4995
4996    /// Retrieves positions corresponding to the `position_ids`, optionally filtering by `side`.
4997    ///
4998    /// Each [`PositionRef`] in the returned vector borrows its underlying cell; mutating any of
4999    /// those positions while the vector is alive will panic at runtime. Drop the vector before
5000    /// issuing writes.
5001    ///
5002    /// # Panics
5003    ///
5004    /// Panics if any `position_id` in the set is not found in the cache.
5005    fn get_positions_for_ids(
5006        &self,
5007        position_ids: &AHashSet<PositionId>,
5008        side: Option<PositionSide>,
5009    ) -> Vec<PositionRef<'_>> {
5010        let mut positions = Vec::new();
5011
5012        for position_id in position_ids {
5013            let position_cell = self
5014                .positions
5015                .get(position_id)
5016                .unwrap_or_else(|| panic!("Position {position_id} not found"));
5017            let position = PositionRef::new(position_cell.borrow());
5018
5019            if side.is_none_or(|side| side == position.side) {
5020                positions.push(position);
5021            }
5022        }
5023
5024        // Sort so callers receive a deterministic Vec across runs; the
5025        // underlying position_ids set is AHash-backed.
5026        positions.sort_by_key(|p| p.id);
5027        positions
5028    }
5029
5030    /// Returns the `ClientOrderId`s of all orders.
5031    #[must_use]
5032    pub fn client_order_ids(
5033        &self,
5034        venue: Option<&Venue>,
5035        instrument_id: Option<&InstrumentId>,
5036        strategy_id: Option<&StrategyId>,
5037        account_id: Option<&AccountId>,
5038    ) -> AHashSet<ClientOrderId> {
5039        self.query_orders_in_bucket(
5040            &self.index.orders,
5041            venue,
5042            instrument_id,
5043            strategy_id,
5044            account_id,
5045        )
5046    }
5047
5048    /// Returns the `ClientOrderId`s of all open orders.
5049    #[must_use]
5050    pub fn client_order_ids_open(
5051        &self,
5052        venue: Option<&Venue>,
5053        instrument_id: Option<&InstrumentId>,
5054        strategy_id: Option<&StrategyId>,
5055        account_id: Option<&AccountId>,
5056    ) -> AHashSet<ClientOrderId> {
5057        self.query_orders_in_bucket(
5058            &self.index.orders_open,
5059            venue,
5060            instrument_id,
5061            strategy_id,
5062            account_id,
5063        )
5064    }
5065
5066    /// Returns the `ClientOrderId`s of all closed orders.
5067    #[must_use]
5068    pub fn client_order_ids_closed(
5069        &self,
5070        venue: Option<&Venue>,
5071        instrument_id: Option<&InstrumentId>,
5072        strategy_id: Option<&StrategyId>,
5073        account_id: Option<&AccountId>,
5074    ) -> AHashSet<ClientOrderId> {
5075        self.query_orders_in_bucket(
5076            &self.index.orders_closed,
5077            venue,
5078            instrument_id,
5079            strategy_id,
5080            account_id,
5081        )
5082    }
5083
5084    /// Returns the `ClientOrderId`s of all locally active orders.
5085    ///
5086    /// Locally active orders are in the `INITIALIZED`, `EMULATED`, or `RELEASED` state
5087    /// (a superset of emulated orders).
5088    #[must_use]
5089    pub fn client_order_ids_active_local(
5090        &self,
5091        venue: Option<&Venue>,
5092        instrument_id: Option<&InstrumentId>,
5093        strategy_id: Option<&StrategyId>,
5094        account_id: Option<&AccountId>,
5095    ) -> AHashSet<ClientOrderId> {
5096        self.query_orders_in_bucket(
5097            &self.index.orders_active_local,
5098            venue,
5099            instrument_id,
5100            strategy_id,
5101            account_id,
5102        )
5103    }
5104
5105    /// Returns the `ClientOrderId`s of all emulated orders.
5106    #[must_use]
5107    pub fn client_order_ids_emulated(
5108        &self,
5109        venue: Option<&Venue>,
5110        instrument_id: Option<&InstrumentId>,
5111        strategy_id: Option<&StrategyId>,
5112        account_id: Option<&AccountId>,
5113    ) -> AHashSet<ClientOrderId> {
5114        self.query_orders_in_bucket(
5115            &self.index.orders_emulated,
5116            venue,
5117            instrument_id,
5118            strategy_id,
5119            account_id,
5120        )
5121    }
5122
5123    /// Returns the `ClientOrderId`s of all in-flight orders.
5124    #[must_use]
5125    pub fn client_order_ids_inflight(
5126        &self,
5127        venue: Option<&Venue>,
5128        instrument_id: Option<&InstrumentId>,
5129        strategy_id: Option<&StrategyId>,
5130        account_id: Option<&AccountId>,
5131    ) -> AHashSet<ClientOrderId> {
5132        self.query_orders_in_bucket(
5133            &self.index.orders_inflight,
5134            venue,
5135            instrument_id,
5136            strategy_id,
5137            account_id,
5138        )
5139    }
5140
5141    /// Returns `PositionId`s of all positions.
5142    #[must_use]
5143    pub fn position_ids(
5144        &self,
5145        venue: Option<&Venue>,
5146        instrument_id: Option<&InstrumentId>,
5147        strategy_id: Option<&StrategyId>,
5148        account_id: Option<&AccountId>,
5149    ) -> AHashSet<PositionId> {
5150        self.query_positions_in_bucket(
5151            &self.index.positions,
5152            venue,
5153            instrument_id,
5154            strategy_id,
5155            account_id,
5156        )
5157    }
5158
5159    /// Returns the `PositionId`s of all open positions.
5160    #[must_use]
5161    pub fn position_open_ids(
5162        &self,
5163        venue: Option<&Venue>,
5164        instrument_id: Option<&InstrumentId>,
5165        strategy_id: Option<&StrategyId>,
5166        account_id: Option<&AccountId>,
5167    ) -> AHashSet<PositionId> {
5168        self.query_positions_in_bucket(
5169            &self.index.positions_open,
5170            venue,
5171            instrument_id,
5172            strategy_id,
5173            account_id,
5174        )
5175    }
5176
5177    /// Returns the `PositionId`s of all closed positions.
5178    #[must_use]
5179    pub fn position_closed_ids(
5180        &self,
5181        venue: Option<&Venue>,
5182        instrument_id: Option<&InstrumentId>,
5183        strategy_id: Option<&StrategyId>,
5184        account_id: Option<&AccountId>,
5185    ) -> AHashSet<PositionId> {
5186        self.query_positions_in_bucket(
5187            &self.index.positions_closed,
5188            venue,
5189            instrument_id,
5190            strategy_id,
5191            account_id,
5192        )
5193    }
5194
5195    /// Returns a borrowed view over the [`ClientOrderId`]s of all orders matching the optional
5196    /// filter parameters.
5197    ///
5198    /// The returned [`Cow`] borrows the underlying index when no filter is provided and only
5199    /// allocates an owned [`AHashSet`] when an intersection is required. Prefer this over
5200    /// [`Self::client_order_ids`] when the caller only needs to iterate or read membership.
5201    #[must_use]
5202    pub fn client_order_ids_view(
5203        &self,
5204        venue: Option<&Venue>,
5205        instrument_id: Option<&InstrumentId>,
5206        strategy_id: Option<&StrategyId>,
5207        account_id: Option<&AccountId>,
5208    ) -> Cow<'_, AHashSet<ClientOrderId>> {
5209        self.view_orders_in_bucket(
5210            &self.index.orders,
5211            venue,
5212            instrument_id,
5213            strategy_id,
5214            account_id,
5215        )
5216    }
5217
5218    /// Returns a borrowed view over the [`ClientOrderId`]s of all open orders.
5219    #[must_use]
5220    pub fn client_order_ids_open_view(
5221        &self,
5222        venue: Option<&Venue>,
5223        instrument_id: Option<&InstrumentId>,
5224        strategy_id: Option<&StrategyId>,
5225        account_id: Option<&AccountId>,
5226    ) -> Cow<'_, AHashSet<ClientOrderId>> {
5227        self.view_orders_in_bucket(
5228            &self.index.orders_open,
5229            venue,
5230            instrument_id,
5231            strategy_id,
5232            account_id,
5233        )
5234    }
5235
5236    /// Returns a borrowed view over the [`ClientOrderId`]s of all closed orders.
5237    #[must_use]
5238    pub fn client_order_ids_closed_view(
5239        &self,
5240        venue: Option<&Venue>,
5241        instrument_id: Option<&InstrumentId>,
5242        strategy_id: Option<&StrategyId>,
5243        account_id: Option<&AccountId>,
5244    ) -> Cow<'_, AHashSet<ClientOrderId>> {
5245        self.view_orders_in_bucket(
5246            &self.index.orders_closed,
5247            venue,
5248            instrument_id,
5249            strategy_id,
5250            account_id,
5251        )
5252    }
5253
5254    /// Returns a borrowed view over the [`ClientOrderId`]s of all locally active orders.
5255    #[must_use]
5256    pub fn client_order_ids_active_local_view(
5257        &self,
5258        venue: Option<&Venue>,
5259        instrument_id: Option<&InstrumentId>,
5260        strategy_id: Option<&StrategyId>,
5261        account_id: Option<&AccountId>,
5262    ) -> Cow<'_, AHashSet<ClientOrderId>> {
5263        self.view_orders_in_bucket(
5264            &self.index.orders_active_local,
5265            venue,
5266            instrument_id,
5267            strategy_id,
5268            account_id,
5269        )
5270    }
5271
5272    /// Returns a borrowed view over the [`ClientOrderId`]s of all emulated orders.
5273    #[must_use]
5274    pub fn client_order_ids_emulated_view(
5275        &self,
5276        venue: Option<&Venue>,
5277        instrument_id: Option<&InstrumentId>,
5278        strategy_id: Option<&StrategyId>,
5279        account_id: Option<&AccountId>,
5280    ) -> Cow<'_, AHashSet<ClientOrderId>> {
5281        self.view_orders_in_bucket(
5282            &self.index.orders_emulated,
5283            venue,
5284            instrument_id,
5285            strategy_id,
5286            account_id,
5287        )
5288    }
5289
5290    /// Returns a borrowed view over the [`ClientOrderId`]s of all in-flight orders.
5291    #[must_use]
5292    pub fn client_order_ids_inflight_view(
5293        &self,
5294        venue: Option<&Venue>,
5295        instrument_id: Option<&InstrumentId>,
5296        strategy_id: Option<&StrategyId>,
5297        account_id: Option<&AccountId>,
5298    ) -> Cow<'_, AHashSet<ClientOrderId>> {
5299        self.view_orders_in_bucket(
5300            &self.index.orders_inflight,
5301            venue,
5302            instrument_id,
5303            strategy_id,
5304            account_id,
5305        )
5306    }
5307
5308    /// Returns a borrowed view over the [`PositionId`]s of all positions.
5309    #[must_use]
5310    pub fn position_ids_view(
5311        &self,
5312        venue: Option<&Venue>,
5313        instrument_id: Option<&InstrumentId>,
5314        strategy_id: Option<&StrategyId>,
5315        account_id: Option<&AccountId>,
5316    ) -> Cow<'_, AHashSet<PositionId>> {
5317        self.view_positions_in_bucket(
5318            &self.index.positions,
5319            venue,
5320            instrument_id,
5321            strategy_id,
5322            account_id,
5323        )
5324    }
5325
5326    /// Returns a borrowed view over the [`PositionId`]s of all open positions.
5327    #[must_use]
5328    pub fn position_open_ids_view(
5329        &self,
5330        venue: Option<&Venue>,
5331        instrument_id: Option<&InstrumentId>,
5332        strategy_id: Option<&StrategyId>,
5333        account_id: Option<&AccountId>,
5334    ) -> Cow<'_, AHashSet<PositionId>> {
5335        self.view_positions_in_bucket(
5336            &self.index.positions_open,
5337            venue,
5338            instrument_id,
5339            strategy_id,
5340            account_id,
5341        )
5342    }
5343
5344    /// Returns a borrowed view over the [`PositionId`]s of all closed positions.
5345    #[must_use]
5346    pub fn position_closed_ids_view(
5347        &self,
5348        venue: Option<&Venue>,
5349        instrument_id: Option<&InstrumentId>,
5350        strategy_id: Option<&StrategyId>,
5351        account_id: Option<&AccountId>,
5352    ) -> Cow<'_, AHashSet<PositionId>> {
5353        self.view_positions_in_bucket(
5354            &self.index.positions_closed,
5355            venue,
5356            instrument_id,
5357            strategy_id,
5358            account_id,
5359        )
5360    }
5361
5362    /// Returns a lazy iterator yielding [`ClientOrderId`]s of all orders matching the optional
5363    /// filter parameters.
5364    ///
5365    /// Avoids the [`AHashSet`] allocation performed by [`Self::client_order_ids`]. Useful when
5366    /// the caller iterates the result once and discards it.
5367    pub fn iter_client_order_ids(
5368        &self,
5369        venue: Option<&Venue>,
5370        instrument_id: Option<&InstrumentId>,
5371        strategy_id: Option<&StrategyId>,
5372        account_id: Option<&AccountId>,
5373    ) -> Box<dyn Iterator<Item = ClientOrderId> + '_> {
5374        self.iter_orders_in_bucket(
5375            &self.index.orders,
5376            venue,
5377            instrument_id,
5378            strategy_id,
5379            account_id,
5380        )
5381    }
5382
5383    /// Returns a lazy iterator yielding [`ClientOrderId`]s of all open orders.
5384    pub fn iter_client_order_ids_open(
5385        &self,
5386        venue: Option<&Venue>,
5387        instrument_id: Option<&InstrumentId>,
5388        strategy_id: Option<&StrategyId>,
5389        account_id: Option<&AccountId>,
5390    ) -> Box<dyn Iterator<Item = ClientOrderId> + '_> {
5391        self.iter_orders_in_bucket(
5392            &self.index.orders_open,
5393            venue,
5394            instrument_id,
5395            strategy_id,
5396            account_id,
5397        )
5398    }
5399
5400    /// Returns a lazy iterator yielding [`ClientOrderId`]s of all closed orders.
5401    pub fn iter_client_order_ids_closed(
5402        &self,
5403        venue: Option<&Venue>,
5404        instrument_id: Option<&InstrumentId>,
5405        strategy_id: Option<&StrategyId>,
5406        account_id: Option<&AccountId>,
5407    ) -> Box<dyn Iterator<Item = ClientOrderId> + '_> {
5408        self.iter_orders_in_bucket(
5409            &self.index.orders_closed,
5410            venue,
5411            instrument_id,
5412            strategy_id,
5413            account_id,
5414        )
5415    }
5416
5417    /// Returns a lazy iterator yielding [`ClientOrderId`]s of all locally active orders.
5418    pub fn iter_client_order_ids_active_local(
5419        &self,
5420        venue: Option<&Venue>,
5421        instrument_id: Option<&InstrumentId>,
5422        strategy_id: Option<&StrategyId>,
5423        account_id: Option<&AccountId>,
5424    ) -> Box<dyn Iterator<Item = ClientOrderId> + '_> {
5425        self.iter_orders_in_bucket(
5426            &self.index.orders_active_local,
5427            venue,
5428            instrument_id,
5429            strategy_id,
5430            account_id,
5431        )
5432    }
5433
5434    /// Returns a lazy iterator yielding [`ClientOrderId`]s of all emulated orders.
5435    pub fn iter_client_order_ids_emulated(
5436        &self,
5437        venue: Option<&Venue>,
5438        instrument_id: Option<&InstrumentId>,
5439        strategy_id: Option<&StrategyId>,
5440        account_id: Option<&AccountId>,
5441    ) -> Box<dyn Iterator<Item = ClientOrderId> + '_> {
5442        self.iter_orders_in_bucket(
5443            &self.index.orders_emulated,
5444            venue,
5445            instrument_id,
5446            strategy_id,
5447            account_id,
5448        )
5449    }
5450
5451    /// Returns a lazy iterator yielding [`ClientOrderId`]s of all in-flight orders.
5452    pub fn iter_client_order_ids_inflight(
5453        &self,
5454        venue: Option<&Venue>,
5455        instrument_id: Option<&InstrumentId>,
5456        strategy_id: Option<&StrategyId>,
5457        account_id: Option<&AccountId>,
5458    ) -> Box<dyn Iterator<Item = ClientOrderId> + '_> {
5459        self.iter_orders_in_bucket(
5460            &self.index.orders_inflight,
5461            venue,
5462            instrument_id,
5463            strategy_id,
5464            account_id,
5465        )
5466    }
5467
5468    /// Returns a lazy iterator yielding [`PositionId`]s of all positions matching the filters.
5469    pub fn iter_position_ids(
5470        &self,
5471        venue: Option<&Venue>,
5472        instrument_id: Option<&InstrumentId>,
5473        strategy_id: Option<&StrategyId>,
5474        account_id: Option<&AccountId>,
5475    ) -> Box<dyn Iterator<Item = PositionId> + '_> {
5476        self.iter_positions_in_bucket(
5477            &self.index.positions,
5478            venue,
5479            instrument_id,
5480            strategy_id,
5481            account_id,
5482        )
5483    }
5484
5485    /// Returns a lazy iterator yielding [`PositionId`]s of all open positions.
5486    pub fn iter_position_open_ids(
5487        &self,
5488        venue: Option<&Venue>,
5489        instrument_id: Option<&InstrumentId>,
5490        strategy_id: Option<&StrategyId>,
5491        account_id: Option<&AccountId>,
5492    ) -> Box<dyn Iterator<Item = PositionId> + '_> {
5493        self.iter_positions_in_bucket(
5494            &self.index.positions_open,
5495            venue,
5496            instrument_id,
5497            strategy_id,
5498            account_id,
5499        )
5500    }
5501
5502    /// Returns a lazy iterator yielding [`PositionId`]s of all closed positions.
5503    pub fn iter_position_closed_ids(
5504        &self,
5505        venue: Option<&Venue>,
5506        instrument_id: Option<&InstrumentId>,
5507        strategy_id: Option<&StrategyId>,
5508        account_id: Option<&AccountId>,
5509    ) -> Box<dyn Iterator<Item = PositionId> + '_> {
5510        self.iter_positions_in_bucket(
5511            &self.index.positions_closed,
5512            venue,
5513            instrument_id,
5514            strategy_id,
5515            account_id,
5516        )
5517    }
5518
5519    /// Returns the `StrategyId`s of all strategies.
5520    #[must_use]
5521    pub fn strategy_ids(&self) -> AHashSet<StrategyId> {
5522        self.index.strategies.clone()
5523    }
5524
5525    /// Returns the `ExecAlgorithmId`s of all execution algorithms.
5526    #[must_use]
5527    pub fn exec_algorithm_ids(&self) -> AHashSet<ExecAlgorithmId> {
5528        self.index.exec_algorithms.clone()
5529    }
5530
5531    // -- ORDER QUERIES ---------------------------------------------------------------------------
5532
5533    /// Gets a borrow of the order with the `client_order_id` (if found).
5534    ///
5535    /// The returned [`OrderRef`] is tied to the cache borrow's scope and panics at runtime if
5536    /// held across a mutation of the same order. Drop the borrow before dispatching events; if
5537    /// post-event state is required, perform a fresh lookup. Use [`Self::order_owned`] when an
5538    /// owned snapshot is needed for a boundary handover.
5539    #[must_use]
5540    pub fn order_ref(&self, client_order_id: &ClientOrderId) -> Option<OrderRef<'_>> {
5541        self.orders
5542            .get(client_order_id)
5543            .map(|order_cell| OrderRef::new(order_cell.borrow()))
5544    }
5545
5546    /// Gets a borrow of the order with the `client_order_id` (if found).
5547    ///
5548    /// Prefer [`Self::order_ref`] in new native code.
5549    #[must_use]
5550    pub fn order(&self, client_order_id: &ClientOrderId) -> Option<OrderRef<'_>> {
5551        self.order_ref(client_order_id)
5552    }
5553
5554    /// Gets a borrow of the order with the `client_order_id`.
5555    ///
5556    /// # Errors
5557    ///
5558    /// Returns an error if the order is not present in the cache.
5559    pub fn try_order_ref(
5560        &self,
5561        client_order_id: &ClientOrderId,
5562    ) -> Result<OrderRef<'_>, OrderLookupError> {
5563        self.orders
5564            .get(client_order_id)
5565            .map(|order_cell| OrderRef::new(order_cell.borrow()))
5566            .ok_or_else(|| OrderLookupError::not_found(*client_order_id))
5567    }
5568
5569    /// Gets a borrow of the order with the `client_order_id`.
5570    ///
5571    /// Prefer [`Self::try_order_ref`] in new native code.
5572    ///
5573    /// # Errors
5574    ///
5575    /// Returns an error if the order is not present in the cache.
5576    pub fn try_order(
5577        &self,
5578        client_order_id: &ClientOrderId,
5579    ) -> Result<OrderRef<'_>, OrderLookupError> {
5580        self.try_order_ref(client_order_id)
5581    }
5582
5583    /// Gets an exclusive write borrow of the order with the `client_order_id` (if found).
5584    ///
5585    /// Requires `&mut Cache` so cache writes are reachable only by privileged crates that hold
5586    /// `Rc<RefCell<Cache>>` directly. Adapter-facing code receives [`CacheView`], which only
5587    /// exposes immutable cache borrows and therefore cannot reach this method.
5588    ///
5589    /// While the returned [`OrderRefMut`] is alive, no other read or write of the same order is
5590    /// permitted. Drop the borrow before dispatching events or taking any other cache borrow that
5591    /// may re-enter the same order.
5592    #[must_use]
5593    pub fn order_mut(&mut self, client_order_id: &ClientOrderId) -> Option<OrderRefMut<'_>> {
5594        self.orders
5595            .get(client_order_id)
5596            .map(|order_cell| OrderRefMut::new(order_cell.borrow_mut()))
5597    }
5598
5599    /// Gets an owned copy of the order with the `client_order_id` (if found).
5600    ///
5601    /// Use when downstream needs an owned [`OrderAny`] that crosses a boundary (for example, an
5602    /// adapter `get_order` API). The copy will not reflect later cache mutations.
5603    #[must_use]
5604    pub fn order_owned(&self, client_order_id: &ClientOrderId) -> Option<OrderAny> {
5605        self.orders
5606            .get(client_order_id)
5607            .map(|order_cell| order_cell.borrow().clone())
5608    }
5609
5610    /// Gets an owned snapshot of the order with the `client_order_id`.
5611    ///
5612    /// # Errors
5613    ///
5614    /// Returns an error if the order is not present in the cache.
5615    pub fn try_order_owned(
5616        &self,
5617        client_order_id: &ClientOrderId,
5618    ) -> Result<OrderAny, OrderLookupError> {
5619        self.try_order_ref(client_order_id)
5620            .map(|order| order.cloned())
5621    }
5622
5623    /// Gets cloned orders for the given `client_order_ids`, logging an error for any missing.
5624    #[must_use]
5625    pub fn orders_for_ids(
5626        &self,
5627        client_order_ids: &[ClientOrderId],
5628        context: &dyn Display,
5629    ) -> Vec<OrderAny> {
5630        let mut orders = Vec::with_capacity(client_order_ids.len());
5631        for id in client_order_ids {
5632            match self.orders.get(id) {
5633                Some(order_cell) => orders.push(order_cell.borrow().clone()),
5634                None => log::error!("Order {id} not found in cache for {context}"),
5635            }
5636        }
5637        orders
5638    }
5639
5640    /// Gets a reference to the client order ID for the `venue_order_id` (if found).
5641    #[must_use]
5642    pub fn client_order_id(&self, venue_order_id: &VenueOrderId) -> Option<&ClientOrderId> {
5643        self.index.venue_order_ids.get(venue_order_id)
5644    }
5645
5646    /// Gets a reference to the venue order ID for the `client_order_id` (if found).
5647    #[must_use]
5648    pub fn venue_order_id(&self, client_order_id: &ClientOrderId) -> Option<&VenueOrderId> {
5649        self.index.client_order_ids.get(client_order_id)
5650    }
5651
5652    /// Gets a reference to the client ID indexed for then `client_order_id` (if found).
5653    #[must_use]
5654    pub fn client_id(&self, client_order_id: &ClientOrderId) -> Option<&ClientId> {
5655        self.index.order_client.get(client_order_id)
5656    }
5657
5658    /// Returns borrows of all orders matching the optional filter parameters.
5659    ///
5660    /// Each [`OrderRef`] in the returned vector borrows its underlying cell; mutating any of
5661    /// those orders while the vector is alive will panic at runtime. Drop the vector
5662    /// before issuing writes.
5663    #[must_use]
5664    pub fn orders_refs(
5665        &self,
5666        venue: Option<&Venue>,
5667        instrument_id: Option<&InstrumentId>,
5668        strategy_id: Option<&StrategyId>,
5669        account_id: Option<&AccountId>,
5670        side: Option<OrderSide>,
5671    ) -> Vec<OrderRef<'_>> {
5672        if venue.is_none()
5673            && instrument_id.is_none()
5674            && strategy_id.is_none()
5675            && account_id.is_none()
5676        {
5677            return self.get_orders_for_ids(self.index.orders.iter().copied(), side);
5678        }
5679
5680        let client_order_ids =
5681            self.iter_client_order_ids(venue, instrument_id, strategy_id, account_id);
5682        self.get_orders_for_ids(client_order_ids, side)
5683    }
5684
5685    /// Returns borrows of all orders matching the optional filter parameters.
5686    ///
5687    /// Prefer [`Self::orders_refs`] in new native code.
5688    #[must_use]
5689    pub fn orders(
5690        &self,
5691        venue: Option<&Venue>,
5692        instrument_id: Option<&InstrumentId>,
5693        strategy_id: Option<&StrategyId>,
5694        account_id: Option<&AccountId>,
5695        side: Option<OrderSide>,
5696    ) -> Vec<OrderRef<'_>> {
5697        self.orders_refs(venue, instrument_id, strategy_id, account_id, side)
5698    }
5699
5700    /// Returns borrows of all open orders matching the optional filter parameters.
5701    #[must_use]
5702    pub fn orders_open_refs(
5703        &self,
5704        venue: Option<&Venue>,
5705        instrument_id: Option<&InstrumentId>,
5706        strategy_id: Option<&StrategyId>,
5707        account_id: Option<&AccountId>,
5708        side: Option<OrderSide>,
5709    ) -> Vec<OrderRef<'_>> {
5710        let client_order_ids =
5711            self.client_order_ids_open(venue, instrument_id, strategy_id, account_id);
5712        self.get_orders_for_ids(client_order_ids.iter().copied(), side)
5713    }
5714
5715    /// Returns borrows of all open orders matching the optional filter parameters.
5716    ///
5717    /// Prefer [`Self::orders_open_refs`] in new native code.
5718    #[must_use]
5719    pub fn orders_open(
5720        &self,
5721        venue: Option<&Venue>,
5722        instrument_id: Option<&InstrumentId>,
5723        strategy_id: Option<&StrategyId>,
5724        account_id: Option<&AccountId>,
5725        side: Option<OrderSide>,
5726    ) -> Vec<OrderRef<'_>> {
5727        self.orders_open_refs(venue, instrument_id, strategy_id, account_id, side)
5728    }
5729
5730    /// Returns borrows of all closed orders matching the optional filter parameters.
5731    #[must_use]
5732    pub fn orders_closed_refs(
5733        &self,
5734        venue: Option<&Venue>,
5735        instrument_id: Option<&InstrumentId>,
5736        strategy_id: Option<&StrategyId>,
5737        account_id: Option<&AccountId>,
5738        side: Option<OrderSide>,
5739    ) -> Vec<OrderRef<'_>> {
5740        let client_order_ids =
5741            self.client_order_ids_closed(venue, instrument_id, strategy_id, account_id);
5742        self.get_orders_for_ids(client_order_ids.iter().copied(), side)
5743    }
5744
5745    /// Returns borrows of all closed orders matching the optional filter parameters.
5746    ///
5747    /// Prefer [`Self::orders_closed_refs`] in new native code.
5748    #[must_use]
5749    pub fn orders_closed(
5750        &self,
5751        venue: Option<&Venue>,
5752        instrument_id: Option<&InstrumentId>,
5753        strategy_id: Option<&StrategyId>,
5754        account_id: Option<&AccountId>,
5755        side: Option<OrderSide>,
5756    ) -> Vec<OrderRef<'_>> {
5757        self.orders_closed_refs(venue, instrument_id, strategy_id, account_id, side)
5758    }
5759
5760    /// Returns borrows of all locally active orders matching the optional filter parameters.
5761    ///
5762    /// Locally active orders are in the `INITIALIZED`, `EMULATED`, or `RELEASED` state
5763    /// (a superset of emulated orders).
5764    #[must_use]
5765    pub fn orders_active_local_refs(
5766        &self,
5767        venue: Option<&Venue>,
5768        instrument_id: Option<&InstrumentId>,
5769        strategy_id: Option<&StrategyId>,
5770        account_id: Option<&AccountId>,
5771        side: Option<OrderSide>,
5772    ) -> Vec<OrderRef<'_>> {
5773        let client_order_ids =
5774            self.client_order_ids_active_local(venue, instrument_id, strategy_id, account_id);
5775        self.get_orders_for_ids(client_order_ids.iter().copied(), side)
5776    }
5777
5778    /// Returns borrows of all locally active orders matching the optional filter parameters.
5779    ///
5780    /// Prefer [`Self::orders_active_local_refs`] in new native code.
5781    #[must_use]
5782    pub fn orders_active_local(
5783        &self,
5784        venue: Option<&Venue>,
5785        instrument_id: Option<&InstrumentId>,
5786        strategy_id: Option<&StrategyId>,
5787        account_id: Option<&AccountId>,
5788        side: Option<OrderSide>,
5789    ) -> Vec<OrderRef<'_>> {
5790        self.orders_active_local_refs(venue, instrument_id, strategy_id, account_id, side)
5791    }
5792
5793    /// Returns borrows of all emulated orders matching the optional filter parameters.
5794    #[must_use]
5795    pub fn orders_emulated_refs(
5796        &self,
5797        venue: Option<&Venue>,
5798        instrument_id: Option<&InstrumentId>,
5799        strategy_id: Option<&StrategyId>,
5800        account_id: Option<&AccountId>,
5801        side: Option<OrderSide>,
5802    ) -> Vec<OrderRef<'_>> {
5803        let client_order_ids =
5804            self.client_order_ids_emulated(venue, instrument_id, strategy_id, account_id);
5805        self.get_orders_for_ids(client_order_ids.iter().copied(), side)
5806    }
5807
5808    /// Returns borrows of all emulated orders matching the optional filter parameters.
5809    ///
5810    /// Prefer [`Self::orders_emulated_refs`] in new native code.
5811    #[must_use]
5812    pub fn orders_emulated(
5813        &self,
5814        venue: Option<&Venue>,
5815        instrument_id: Option<&InstrumentId>,
5816        strategy_id: Option<&StrategyId>,
5817        account_id: Option<&AccountId>,
5818        side: Option<OrderSide>,
5819    ) -> Vec<OrderRef<'_>> {
5820        self.orders_emulated_refs(venue, instrument_id, strategy_id, account_id, side)
5821    }
5822
5823    /// Returns borrows of all in-flight orders matching the optional filter parameters.
5824    #[must_use]
5825    pub fn orders_inflight_refs(
5826        &self,
5827        venue: Option<&Venue>,
5828        instrument_id: Option<&InstrumentId>,
5829        strategy_id: Option<&StrategyId>,
5830        account_id: Option<&AccountId>,
5831        side: Option<OrderSide>,
5832    ) -> Vec<OrderRef<'_>> {
5833        let client_order_ids =
5834            self.client_order_ids_inflight(venue, instrument_id, strategy_id, account_id);
5835        self.get_orders_for_ids(client_order_ids.iter().copied(), side)
5836    }
5837
5838    /// Returns borrows of all in-flight orders matching the optional filter parameters.
5839    ///
5840    /// Prefer [`Self::orders_inflight_refs`] in new native code.
5841    #[must_use]
5842    pub fn orders_inflight(
5843        &self,
5844        venue: Option<&Venue>,
5845        instrument_id: Option<&InstrumentId>,
5846        strategy_id: Option<&StrategyId>,
5847        account_id: Option<&AccountId>,
5848        side: Option<OrderSide>,
5849    ) -> Vec<OrderRef<'_>> {
5850        self.orders_inflight_refs(venue, instrument_id, strategy_id, account_id, side)
5851    }
5852
5853    /// Returns borrows of all orders for the `position_id`.
5854    #[must_use]
5855    pub fn orders_for_position(&self, position_id: &PositionId) -> Vec<OrderRef<'_>> {
5856        match self.index.position_orders.get(position_id) {
5857            Some(client_order_ids) => {
5858                self.get_orders_for_ids(client_order_ids.iter().copied(), None)
5859            }
5860            None => Vec::new(),
5861        }
5862    }
5863
5864    /// Records execution client handoffs until their first status transitions.
5865    ///
5866    /// Records are process-local and may refer to uncached external orders.
5867    pub fn mark_orders_dispatched(
5868        &mut self,
5869        client_order_ids: impl IntoIterator<Item = ClientOrderId>,
5870    ) {
5871        self.orders_dispatched.extend(client_order_ids);
5872    }
5873
5874    /// Removes the execution dispatch record for an order.
5875    pub fn clear_order_dispatch(&mut self, client_order_id: &ClientOrderId) {
5876        self.orders_dispatched.remove(client_order_id);
5877    }
5878
5879    /// Returns whether an order was dispatched and awaits its first status transition.
5880    #[must_use]
5881    pub fn is_order_dispatched(&self, client_order_id: &ClientOrderId) -> bool {
5882        self.orders_dispatched.contains(client_order_id)
5883    }
5884
5885    /// Returns whether an order with the `client_order_id` exists.
5886    #[must_use]
5887    pub fn order_exists(&self, client_order_id: &ClientOrderId) -> bool {
5888        self.index.orders.contains(client_order_id)
5889    }
5890
5891    /// Returns whether an order with the `client_order_id` is open.
5892    #[must_use]
5893    pub fn is_order_open(&self, client_order_id: &ClientOrderId) -> bool {
5894        self.index.orders_open.contains(client_order_id)
5895    }
5896
5897    /// Returns whether an order with the `client_order_id` is closed.
5898    #[must_use]
5899    pub fn is_order_closed(&self, client_order_id: &ClientOrderId) -> bool {
5900        self.index.orders_closed.contains(client_order_id)
5901    }
5902
5903    /// Returns whether an order with the `client_order_id` is locally active.
5904    ///
5905    /// Locally active orders are in the `INITIALIZED`, `EMULATED`, or `RELEASED` state
5906    /// (a superset of emulated orders).
5907    #[must_use]
5908    pub fn is_order_active_local(&self, client_order_id: &ClientOrderId) -> bool {
5909        self.index.orders_active_local.contains(client_order_id)
5910    }
5911
5912    /// Returns whether an order with the `client_order_id` is emulated.
5913    #[must_use]
5914    pub fn is_order_emulated(&self, client_order_id: &ClientOrderId) -> bool {
5915        self.index.orders_emulated.contains(client_order_id)
5916    }
5917
5918    /// Returns whether an order with the `client_order_id` is in-flight.
5919    #[must_use]
5920    pub fn is_order_inflight(&self, client_order_id: &ClientOrderId) -> bool {
5921        self.index.orders_inflight.contains(client_order_id)
5922    }
5923
5924    /// Returns whether an order with the `client_order_id` is `PENDING_CANCEL` locally.
5925    #[must_use]
5926    pub fn is_order_pending_cancel_local(&self, client_order_id: &ClientOrderId) -> bool {
5927        self.index.orders_pending_cancel.contains(client_order_id)
5928    }
5929
5930    /// Returns the count of all open orders.
5931    #[must_use]
5932    pub fn orders_open_count(
5933        &self,
5934        venue: Option<&Venue>,
5935        instrument_id: Option<&InstrumentId>,
5936        strategy_id: Option<&StrategyId>,
5937        account_id: Option<&AccountId>,
5938        side: Option<OrderSide>,
5939    ) -> usize {
5940        self.count_orders_in_bucket(
5941            &self.index.orders_open,
5942            venue,
5943            instrument_id,
5944            strategy_id,
5945            account_id,
5946            side,
5947        )
5948    }
5949
5950    /// Returns the count of all closed orders.
5951    #[must_use]
5952    pub fn orders_closed_count(
5953        &self,
5954        venue: Option<&Venue>,
5955        instrument_id: Option<&InstrumentId>,
5956        strategy_id: Option<&StrategyId>,
5957        account_id: Option<&AccountId>,
5958        side: Option<OrderSide>,
5959    ) -> usize {
5960        self.count_orders_in_bucket(
5961            &self.index.orders_closed,
5962            venue,
5963            instrument_id,
5964            strategy_id,
5965            account_id,
5966            side,
5967        )
5968    }
5969
5970    /// Returns the count of all locally active orders.
5971    ///
5972    /// Locally active orders are in the `INITIALIZED`, `EMULATED`, or `RELEASED` state
5973    /// (a superset of emulated orders).
5974    #[must_use]
5975    pub fn orders_active_local_count(
5976        &self,
5977        venue: Option<&Venue>,
5978        instrument_id: Option<&InstrumentId>,
5979        strategy_id: Option<&StrategyId>,
5980        account_id: Option<&AccountId>,
5981        side: Option<OrderSide>,
5982    ) -> usize {
5983        self.count_orders_in_bucket(
5984            &self.index.orders_active_local,
5985            venue,
5986            instrument_id,
5987            strategy_id,
5988            account_id,
5989            side,
5990        )
5991    }
5992
5993    /// Returns the count of all emulated orders.
5994    #[must_use]
5995    pub fn orders_emulated_count(
5996        &self,
5997        venue: Option<&Venue>,
5998        instrument_id: Option<&InstrumentId>,
5999        strategy_id: Option<&StrategyId>,
6000        account_id: Option<&AccountId>,
6001        side: Option<OrderSide>,
6002    ) -> usize {
6003        self.count_orders_in_bucket(
6004            &self.index.orders_emulated,
6005            venue,
6006            instrument_id,
6007            strategy_id,
6008            account_id,
6009            side,
6010        )
6011    }
6012
6013    /// Returns the count of all in-flight orders.
6014    #[must_use]
6015    pub fn orders_inflight_count(
6016        &self,
6017        venue: Option<&Venue>,
6018        instrument_id: Option<&InstrumentId>,
6019        strategy_id: Option<&StrategyId>,
6020        account_id: Option<&AccountId>,
6021        side: Option<OrderSide>,
6022    ) -> usize {
6023        self.count_orders_in_bucket(
6024            &self.index.orders_inflight,
6025            venue,
6026            instrument_id,
6027            strategy_id,
6028            account_id,
6029            side,
6030        )
6031    }
6032
6033    /// Returns the count of all orders.
6034    #[must_use]
6035    pub fn orders_total_count(
6036        &self,
6037        venue: Option<&Venue>,
6038        instrument_id: Option<&InstrumentId>,
6039        strategy_id: Option<&StrategyId>,
6040        account_id: Option<&AccountId>,
6041        side: Option<OrderSide>,
6042    ) -> usize {
6043        self.count_orders_in_bucket(
6044            &self.index.orders,
6045            venue,
6046            instrument_id,
6047            strategy_id,
6048            account_id,
6049            side,
6050        )
6051    }
6052
6053    /// Returns whether any open order matches the optional filter parameters.
6054    ///
6055    /// Short-circuits on the first match, avoiding the full intersection walk performed by
6056    /// [`Self::orders_open_count`]. Prefer this over `orders_open_count(...) > 0` when only
6057    /// existence matters.
6058    #[must_use]
6059    pub fn has_orders_open(
6060        &self,
6061        venue: Option<&Venue>,
6062        instrument_id: Option<&InstrumentId>,
6063        strategy_id: Option<&StrategyId>,
6064        account_id: Option<&AccountId>,
6065        side: Option<OrderSide>,
6066    ) -> bool {
6067        self.any_orders_in_bucket(
6068            &self.index.orders_open,
6069            venue,
6070            instrument_id,
6071            strategy_id,
6072            account_id,
6073            side,
6074        )
6075    }
6076
6077    /// Returns whether any closed order matches the optional filter parameters.
6078    #[must_use]
6079    pub fn has_orders_closed(
6080        &self,
6081        venue: Option<&Venue>,
6082        instrument_id: Option<&InstrumentId>,
6083        strategy_id: Option<&StrategyId>,
6084        account_id: Option<&AccountId>,
6085        side: Option<OrderSide>,
6086    ) -> bool {
6087        self.any_orders_in_bucket(
6088            &self.index.orders_closed,
6089            venue,
6090            instrument_id,
6091            strategy_id,
6092            account_id,
6093            side,
6094        )
6095    }
6096
6097    /// Returns whether any locally active order matches the optional filter parameters.
6098    ///
6099    /// Locally active orders are in the `INITIALIZED`, `EMULATED`, or `RELEASED` state.
6100    #[must_use]
6101    pub fn has_orders_active_local(
6102        &self,
6103        venue: Option<&Venue>,
6104        instrument_id: Option<&InstrumentId>,
6105        strategy_id: Option<&StrategyId>,
6106        account_id: Option<&AccountId>,
6107        side: Option<OrderSide>,
6108    ) -> bool {
6109        self.any_orders_in_bucket(
6110            &self.index.orders_active_local,
6111            venue,
6112            instrument_id,
6113            strategy_id,
6114            account_id,
6115            side,
6116        )
6117    }
6118
6119    /// Returns whether any emulated order matches the optional filter parameters.
6120    #[must_use]
6121    pub fn has_orders_emulated(
6122        &self,
6123        venue: Option<&Venue>,
6124        instrument_id: Option<&InstrumentId>,
6125        strategy_id: Option<&StrategyId>,
6126        account_id: Option<&AccountId>,
6127        side: Option<OrderSide>,
6128    ) -> bool {
6129        self.any_orders_in_bucket(
6130            &self.index.orders_emulated,
6131            venue,
6132            instrument_id,
6133            strategy_id,
6134            account_id,
6135            side,
6136        )
6137    }
6138
6139    /// Returns whether any in-flight order matches the optional filter parameters.
6140    #[must_use]
6141    pub fn has_orders_inflight(
6142        &self,
6143        venue: Option<&Venue>,
6144        instrument_id: Option<&InstrumentId>,
6145        strategy_id: Option<&StrategyId>,
6146        account_id: Option<&AccountId>,
6147        side: Option<OrderSide>,
6148    ) -> bool {
6149        self.any_orders_in_bucket(
6150            &self.index.orders_inflight,
6151            venue,
6152            instrument_id,
6153            strategy_id,
6154            account_id,
6155            side,
6156        )
6157    }
6158
6159    /// Returns whether any order (in any state) matches the optional filter parameters.
6160    #[must_use]
6161    pub fn has_orders(
6162        &self,
6163        venue: Option<&Venue>,
6164        instrument_id: Option<&InstrumentId>,
6165        strategy_id: Option<&StrategyId>,
6166        account_id: Option<&AccountId>,
6167        side: Option<OrderSide>,
6168    ) -> bool {
6169        self.any_orders_in_bucket(
6170            &self.index.orders,
6171            venue,
6172            instrument_id,
6173            strategy_id,
6174            account_id,
6175            side,
6176        )
6177    }
6178
6179    /// Returns the order list for the `order_list_id`.
6180    #[must_use]
6181    pub fn order_list(&self, order_list_id: &OrderListId) -> Option<&OrderList> {
6182        self.order_lists.get(order_list_id)
6183    }
6184
6185    /// Returns the order list for the `order_list_id`.
6186    ///
6187    /// # Errors
6188    ///
6189    /// Returns an error if the order list is not present in the cache.
6190    pub fn try_order_list(
6191        &self,
6192        order_list_id: &OrderListId,
6193    ) -> Result<&OrderList, OrderListLookupError> {
6194        self.order_lists
6195            .get(order_list_id)
6196            .ok_or_else(|| OrderListLookupError::not_found(*order_list_id))
6197    }
6198
6199    /// Returns all order lists matching the optional filter parameters.
6200    #[must_use]
6201    pub fn order_lists(
6202        &self,
6203        venue: Option<&Venue>,
6204        instrument_id: Option<&InstrumentId>,
6205        strategy_id: Option<&StrategyId>,
6206        account_id: Option<&AccountId>,
6207    ) -> Vec<&OrderList> {
6208        let mut order_lists = self.order_lists.values().collect::<Vec<&OrderList>>();
6209
6210        if let Some(venue) = venue {
6211            order_lists.retain(|ol| &ol.instrument_id.venue == venue);
6212        }
6213
6214        if let Some(instrument_id) = instrument_id {
6215            order_lists.retain(|ol| &ol.instrument_id == instrument_id);
6216        }
6217
6218        if let Some(strategy_id) = strategy_id {
6219            order_lists.retain(|ol| &ol.strategy_id == strategy_id);
6220        }
6221
6222        if let Some(account_id) = account_id {
6223            order_lists.retain(|ol| {
6224                ol.client_order_ids.iter().any(|client_order_id| {
6225                    self.orders.get(client_order_id).is_some_and(|order_cell| {
6226                        order_cell.borrow().account_id().as_ref() == Some(account_id)
6227                    })
6228                })
6229            });
6230        }
6231
6232        order_lists
6233    }
6234
6235    /// Returns whether an order list with the `order_list_id` exists.
6236    #[must_use]
6237    pub fn order_list_exists(&self, order_list_id: &OrderListId) -> bool {
6238        self.order_lists.contains_key(order_list_id)
6239    }
6240
6241    // -- EXEC ALGORITHM QUERIES ------------------------------------------------------------------
6242
6243    /// Returns references to all orders associated with the `exec_algorithm_id` matching the
6244    /// optional filter parameters.
6245    #[must_use]
6246    pub fn orders_for_exec_algorithm(
6247        &self,
6248        exec_algorithm_id: &ExecAlgorithmId,
6249        venue: Option<&Venue>,
6250        instrument_id: Option<&InstrumentId>,
6251        strategy_id: Option<&StrategyId>,
6252        account_id: Option<&AccountId>,
6253        side: Option<OrderSide>,
6254    ) -> Vec<OrderRef<'_>> {
6255        let Some(exec_algorithm_order_ids) =
6256            self.index.exec_algorithm_orders.get(exec_algorithm_id)
6257        else {
6258            return Vec::new();
6259        };
6260
6261        let filtered = self.query_orders_in_bucket(
6262            exec_algorithm_order_ids,
6263            venue,
6264            instrument_id,
6265            strategy_id,
6266            account_id,
6267        );
6268        self.get_orders_for_ids(filtered.iter().copied(), side)
6269    }
6270
6271    /// Returns references to all orders with the `exec_spawn_id`.
6272    #[must_use]
6273    pub fn orders_for_exec_spawn(&self, exec_spawn_id: &ClientOrderId) -> Vec<OrderRef<'_>> {
6274        match self.index.exec_spawn_orders.get(exec_spawn_id) {
6275            Some(ids) => self.get_orders_for_ids(ids.iter().copied(), None),
6276            None => Vec::new(),
6277        }
6278    }
6279
6280    /// Returns the total order quantity for the `exec_spawn_id`.
6281    #[must_use]
6282    pub fn exec_spawn_total_quantity(
6283        &self,
6284        exec_spawn_id: &ClientOrderId,
6285        active_only: bool,
6286    ) -> Option<Quantity> {
6287        self.exec_spawn_total(exec_spawn_id, active_only, Order::quantity)
6288    }
6289
6290    /// Returns the total filled quantity for all orders with the `exec_spawn_id`.
6291    #[must_use]
6292    pub fn exec_spawn_total_filled_qty(
6293        &self,
6294        exec_spawn_id: &ClientOrderId,
6295        active_only: bool,
6296    ) -> Option<Quantity> {
6297        self.exec_spawn_total(exec_spawn_id, active_only, Order::filled_qty)
6298    }
6299
6300    /// Returns the total leaves quantity for all orders with the `exec_spawn_id`.
6301    #[must_use]
6302    pub fn exec_spawn_total_leaves_qty(
6303        &self,
6304        exec_spawn_id: &ClientOrderId,
6305        active_only: bool,
6306    ) -> Option<Quantity> {
6307        self.exec_spawn_total(exec_spawn_id, active_only, Order::leaves_qty)
6308    }
6309
6310    fn exec_spawn_total(
6311        &self,
6312        exec_spawn_id: &ClientOrderId,
6313        active_only: bool,
6314        quantity: impl Fn(&OrderAny) -> Quantity,
6315    ) -> Option<Quantity> {
6316        self.orders_for_exec_spawn(exec_spawn_id)
6317            .into_iter()
6318            .filter(|order| !active_only || !order.is_closed())
6319            .map(|order| quantity(&order))
6320            .reduce(|total, quantity| total + quantity)
6321    }
6322
6323    // -- POSITION QUERIES ------------------------------------------------------------------------
6324
6325    /// Returns a borrow of the position with the `position_id` (if found).
6326    #[must_use]
6327    pub fn position_ref(&self, position_id: &PositionId) -> Option<PositionRef<'_>> {
6328        self.positions
6329            .get(position_id)
6330            .map(|position_cell| PositionRef::new(position_cell.borrow()))
6331    }
6332
6333    /// Returns a borrow of the position with the `position_id` (if found).
6334    ///
6335    /// Prefer [`Self::position_ref`] in new native code.
6336    #[must_use]
6337    pub fn position(&self, position_id: &PositionId) -> Option<PositionRef<'_>> {
6338        self.position_ref(position_id)
6339    }
6340
6341    /// Returns a borrow of the position with the `position_id`.
6342    ///
6343    /// # Errors
6344    ///
6345    /// Returns an error if the position is not present in the cache.
6346    pub fn try_position_ref(
6347        &self,
6348        position_id: &PositionId,
6349    ) -> Result<PositionRef<'_>, PositionLookupError> {
6350        self.positions
6351            .get(position_id)
6352            .map(|position_cell| PositionRef::new(position_cell.borrow()))
6353            .ok_or_else(|| PositionLookupError::not_found(*position_id))
6354    }
6355
6356    /// Returns a borrow of the position with the `position_id`.
6357    ///
6358    /// Prefer [`Self::try_position_ref`] in new native code.
6359    ///
6360    /// # Errors
6361    ///
6362    /// Returns an error if the position is not present in the cache.
6363    pub fn try_position(
6364        &self,
6365        position_id: &PositionId,
6366    ) -> Result<PositionRef<'_>, PositionLookupError> {
6367        self.try_position_ref(position_id)
6368    }
6369
6370    /// Gets an exclusive write borrow of the position with the `position_id` (if found).
6371    ///
6372    /// Requires `&mut Cache` so cache writes are reachable only by privileged crates that hold
6373    /// `Rc<RefCell<Cache>>` directly. Adapter-facing code receives [`CacheView`], which only
6374    /// exposes immutable cache borrows and therefore cannot reach this method.
6375    ///
6376    /// While the returned [`PositionRefMut`] is alive, no other read or write of the same position
6377    /// is permitted. Drop the borrow before dispatching events or taking any other cache borrow
6378    /// that may re-enter the same position.
6379    #[must_use]
6380    pub fn position_mut(&mut self, position_id: &PositionId) -> Option<PositionRefMut<'_>> {
6381        self.positions
6382            .get(position_id)
6383            .map(|position_cell| PositionRefMut::new(position_cell.borrow_mut()))
6384    }
6385
6386    /// Gets an owned copy of the position with the `position_id` (if found).
6387    ///
6388    /// Use when downstream needs an owned [`Position`] that crosses a boundary. The copy will not
6389    /// reflect later cache mutations.
6390    #[must_use]
6391    pub fn position_owned(&self, position_id: &PositionId) -> Option<Position> {
6392        self.positions
6393            .get(position_id)
6394            .map(|position_cell| position_cell.borrow().clone())
6395    }
6396
6397    /// Returns a borrow of the position for the `client_order_id` (if found).
6398    #[must_use]
6399    pub fn position_for_order_ref(
6400        &self,
6401        client_order_id: &ClientOrderId,
6402    ) -> Option<PositionRef<'_>> {
6403        self.index
6404            .order_position
6405            .get(client_order_id)
6406            .and_then(|position_id| self.positions.get(position_id))
6407            .map(|position_cell| PositionRef::new(position_cell.borrow()))
6408    }
6409
6410    /// Returns a borrow of the position for the `client_order_id` (if found).
6411    ///
6412    /// Prefer [`Self::position_for_order_ref`] in new native code.
6413    #[must_use]
6414    pub fn position_for_order(&self, client_order_id: &ClientOrderId) -> Option<PositionRef<'_>> {
6415        self.position_for_order_ref(client_order_id)
6416    }
6417
6418    /// Returns a reference to the position ID for the `client_order_id` (if found).
6419    #[must_use]
6420    pub fn position_id(&self, client_order_id: &ClientOrderId) -> Option<&PositionId> {
6421        self.index.order_position.get(client_order_id)
6422    }
6423
6424    /// Returns the proven virtual HEDGING flip IDs, with the current destination second.
6425    ///
6426    /// The route comes from the original fill and its causal split fragments, independently of
6427    /// the order's mutable position ID. Returns `None` when no virtual split is recorded.
6428    ///
6429    /// # Errors
6430    ///
6431    /// Returns an error if split history is incomplete, conflicts, or a correction leaves both
6432    /// sides of a split open.
6433    pub fn hedging_flip_position_ids(
6434        &self,
6435        client_order_id: ClientOrderId,
6436    ) -> anyhow::Result<Option<[PositionId; 2]>> {
6437        let Some(order) = self.order_ref(&client_order_id) else {
6438            return Ok(None);
6439        };
6440
6441        let mut flip = None;
6442        let mut corrected_source = None;
6443
6444        // Keep ordered fill checks linear in each position's replay history
6445        let mut replay_offsets = AHashMap::new();
6446
6447        for event in order.events() {
6448            let OrderEventAny::Filled(fill) = event else {
6449                continue;
6450            };
6451
6452            let Some(source_id) = fill.position_id.filter(PositionId::is_virtual) else {
6453                continue;
6454            };
6455
6456            let source = self.position_ref(&source_id);
6457            if source.is_some() && self.oms_type(&source_id) != Some(OmsType::Hedging) {
6458                continue;
6459            }
6460
6461            if source.as_ref().is_some_and(|source| {
6462                let offset = replay_offsets.entry(source_id).or_default();
6463                Self::replay_contains_fill(&source.replay_events, fill, offset)
6464            }) {
6465                continue;
6466            }
6467
6468            let closing = source.as_ref().and_then(|source| {
6469                source
6470                    .fill_fragments(client_order_id, fill.trade_id)
6471                    .into_iter()
6472                    .find(|fragment| {
6473                        fragment.event_id == fill.event_id && fragment.last_qty < fill.last_qty
6474                    })
6475                    .map(|closing| (source, closing))
6476            });
6477
6478            let Some((source, closing)) = closing else {
6479                let has_opening = self
6480                    .positions_refs(
6481                        None,
6482                        Some(&fill.instrument_id),
6483                        Some(&fill.strategy_id),
6484                        Some(&fill.account_id),
6485                        None,
6486                    )
6487                    .iter()
6488                    .any(|position| {
6489                        position.id != source_id
6490                            && position.id.is_virtual()
6491                            && self.oms_type(&position.id) == Some(OmsType::Hedging)
6492                            && position.replay_events.iter().any(|event| {
6493                                matches!(event, PositionReplayEvent::Filled(opening)
6494                                if opening.causation_id == Some(fill.event_id)
6495                                    && opening.client_order_id == client_order_id
6496                                    && opening.trade_id == fill.trade_id)
6497                            })
6498                    });
6499
6500                anyhow::ensure!(
6501                    !has_opening,
6502                    "missing virtual flip source fragment for order {client_order_id}"
6503                );
6504                continue;
6505            };
6506
6507            let (positions, corrected_closing) =
6508                self.hedging_flip_destination(fill, source, closing)?;
6509            anyhow::ensure!(
6510                flip.is_none() || corrected_source == Some(source.id),
6511                "ambiguous virtual flip history for order {client_order_id}"
6512            );
6513            flip = Some(positions);
6514            corrected_source = corrected_closing.then_some(source.id);
6515        }
6516
6517        Ok(flip)
6518    }
6519
6520    fn replay_contains_fill(
6521        events: &[PositionReplayEvent],
6522        fill: &OrderFilled,
6523        offset: &mut usize,
6524    ) -> bool {
6525        let matches_fill = |event: &PositionReplayEvent| matches!(event, PositionReplayEvent::Filled(fragment) if fragment == fill);
6526
6527        if let Some(index) = events[*offset..].iter().position(matches_fill) {
6528            *offset += index + 1;
6529            return true;
6530        }
6531
6532        // Repeated or reordered fills can still match before the cursor
6533        events[..*offset].iter().any(matches_fill)
6534    }
6535
6536    fn hedging_flip_destination(
6537        &self,
6538        fill: &OrderFilled,
6539        source: &Position,
6540        closing: &OrderFilled,
6541    ) -> anyhow::Result<([PositionId; 2], bool)> {
6542        let positions = self.positions_refs(
6543            None,
6544            Some(&fill.instrument_id),
6545            Some(&fill.strategy_id),
6546            Some(&fill.account_id),
6547            None,
6548        );
6549
6550        let mut openings = positions.iter().flat_map(|position| {
6551            position
6552                .replay_events
6553                .iter()
6554                .filter_map(move |event| match event {
6555                    PositionReplayEvent::Filled(opening)
6556                        if opening.causation_id == Some(fill.event_id)
6557                            && position.id != source.id =>
6558                    {
6559                        Some((position, opening))
6560                    }
6561                    _ => None,
6562                })
6563        });
6564
6565        let (destination, opening) = openings.next().ok_or_else(|| {
6566            anyhow::anyhow!(
6567                "missing virtual flip fragment for order {}",
6568                fill.client_order_id
6569            )
6570        })?;
6571
6572        anyhow::ensure!(
6573            openings.next().is_none(),
6574            "ambiguous virtual flip fragments for order {}",
6575            fill.client_order_id
6576        );
6577        anyhow::ensure!(
6578            source.instrument_id == fill.instrument_id
6579                && source.account_id == fill.account_id
6580                && source.strategy_id == fill.strategy_id
6581                && destination.id.is_virtual()
6582                && self.oms_type(&destination.id) == Some(OmsType::Hedging),
6583            "conflicting virtual flip positions for order {}",
6584            fill.client_order_id
6585        );
6586        let (expected_closing, expected_opening) =
6587            fill.split_for_position_flip(closing.last_qty, Some(destination.id), opening.event_id)?;
6588        anyhow::ensure!(
6589            *closing == expected_closing && *opening == expected_opening,
6590            "conflicting virtual flip provenance for order {}",
6591            fill.client_order_id
6592        );
6593
6594        let corrected_closing = source.fill_voids.iter().any(|correction| {
6595            correction.event.client_order_id == fill.client_order_id
6596                && correction.event.trade_id == fill.trade_id
6597                && correction.voided_qty.non_zero()
6598        });
6599
6600        if corrected_closing && source.is_open() {
6601            anyhow::ensure!(
6602                !destination.is_open(),
6603                "ambiguous corrected virtual flip for order {}",
6604                fill.client_order_id
6605            );
6606            return Ok(([destination.id, source.id], corrected_closing));
6607        }
6608
6609        Ok(([source.id, destination.id], corrected_closing))
6610    }
6611
6612    fn reindex_hedging_position(&mut self, client_order_id: ClientOrderId) {
6613        match self.hedging_flip_position_ids(client_order_id) {
6614            Ok(Some([_, position_id])) => {
6615                let position = self
6616                    .position_ref(&position_id)
6617                    .expect("proven position is cached");
6618                let venue = position.instrument_id.venue;
6619                let strategy_id = position.strategy_id;
6620                drop(position);
6621
6622                if let Err(e) =
6623                    self.add_position_id(&position_id, &venue, &client_order_id, &strategy_id)
6624                {
6625                    log::error!("Failed to index virtual flip for order {client_order_id}: {e}");
6626                }
6627            }
6628            Ok(None) => {}
6629            Err(e) => {
6630                self.index.order_position.remove(&client_order_id);
6631
6632                log::error!("Cannot index virtual flip for order {client_order_id}: {e}");
6633            }
6634        }
6635    }
6636
6637    /// Returns borrows of all positions matching the optional filter parameters.
6638    ///
6639    /// Each [`PositionRef`] in the returned vector borrows its underlying cell; mutating any of
6640    /// those positions while the vector is alive will panic at runtime. Drop the vector before
6641    /// issuing writes.
6642    #[must_use]
6643    pub fn positions_refs(
6644        &self,
6645        venue: Option<&Venue>,
6646        instrument_id: Option<&InstrumentId>,
6647        strategy_id: Option<&StrategyId>,
6648        account_id: Option<&AccountId>,
6649        side: Option<PositionSide>,
6650    ) -> Vec<PositionRef<'_>> {
6651        let position_ids = self.position_ids(venue, instrument_id, strategy_id, account_id);
6652        self.get_positions_for_ids(&position_ids, side)
6653    }
6654
6655    /// Returns borrows of all positions matching the optional filter parameters.
6656    ///
6657    /// Prefer [`Self::positions_refs`] in new native code.
6658    #[must_use]
6659    pub fn positions(
6660        &self,
6661        venue: Option<&Venue>,
6662        instrument_id: Option<&InstrumentId>,
6663        strategy_id: Option<&StrategyId>,
6664        account_id: Option<&AccountId>,
6665        side: Option<PositionSide>,
6666    ) -> Vec<PositionRef<'_>> {
6667        self.positions_refs(venue, instrument_id, strategy_id, account_id, side)
6668    }
6669
6670    /// Returns borrows of all open positions matching the optional filter parameters.
6671    #[must_use]
6672    pub fn positions_open_refs(
6673        &self,
6674        venue: Option<&Venue>,
6675        instrument_id: Option<&InstrumentId>,
6676        strategy_id: Option<&StrategyId>,
6677        account_id: Option<&AccountId>,
6678        side: Option<PositionSide>,
6679    ) -> Vec<PositionRef<'_>> {
6680        let position_ids = self.position_open_ids(venue, instrument_id, strategy_id, account_id);
6681        self.get_positions_for_ids(&position_ids, side)
6682    }
6683
6684    /// Returns borrows of all open positions matching the optional filter parameters.
6685    ///
6686    /// Prefer [`Self::positions_open_refs`] in new native code.
6687    #[must_use]
6688    pub fn positions_open(
6689        &self,
6690        venue: Option<&Venue>,
6691        instrument_id: Option<&InstrumentId>,
6692        strategy_id: Option<&StrategyId>,
6693        account_id: Option<&AccountId>,
6694        side: Option<PositionSide>,
6695    ) -> Vec<PositionRef<'_>> {
6696        self.positions_open_refs(venue, instrument_id, strategy_id, account_id, side)
6697    }
6698
6699    /// Returns borrows of all closed positions matching the optional filter parameters.
6700    #[must_use]
6701    pub fn positions_closed_refs(
6702        &self,
6703        venue: Option<&Venue>,
6704        instrument_id: Option<&InstrumentId>,
6705        strategy_id: Option<&StrategyId>,
6706        account_id: Option<&AccountId>,
6707        side: Option<PositionSide>,
6708    ) -> Vec<PositionRef<'_>> {
6709        let position_ids = self.position_closed_ids(venue, instrument_id, strategy_id, account_id);
6710        self.get_positions_for_ids(&position_ids, side)
6711    }
6712
6713    /// Returns borrows of all closed positions matching the optional filter parameters.
6714    ///
6715    /// Prefer [`Self::positions_closed_refs`] in new native code.
6716    #[must_use]
6717    pub fn positions_closed(
6718        &self,
6719        venue: Option<&Venue>,
6720        instrument_id: Option<&InstrumentId>,
6721        strategy_id: Option<&StrategyId>,
6722        account_id: Option<&AccountId>,
6723        side: Option<PositionSide>,
6724    ) -> Vec<PositionRef<'_>> {
6725        self.positions_closed_refs(venue, instrument_id, strategy_id, account_id, side)
6726    }
6727
6728    /// Returns whether a position with the `position_id` exists.
6729    #[must_use]
6730    pub fn position_exists(&self, position_id: &PositionId) -> bool {
6731        self.index.positions.contains(position_id)
6732    }
6733
6734    /// Returns whether a position with the `position_id` is open.
6735    #[must_use]
6736    pub fn is_position_open(&self, position_id: &PositionId) -> bool {
6737        self.index.positions_open.contains(position_id)
6738    }
6739
6740    /// Returns whether a position with the `position_id` is closed.
6741    #[must_use]
6742    pub fn is_position_closed(&self, position_id: &PositionId) -> bool {
6743        self.index.positions_closed.contains(position_id)
6744    }
6745
6746    /// Returns the count of all open positions.
6747    #[must_use]
6748    pub fn positions_open_count(
6749        &self,
6750        venue: Option<&Venue>,
6751        instrument_id: Option<&InstrumentId>,
6752        strategy_id: Option<&StrategyId>,
6753        account_id: Option<&AccountId>,
6754        side: Option<PositionSide>,
6755    ) -> usize {
6756        self.count_positions_in_bucket(
6757            &self.index.positions_open,
6758            venue,
6759            instrument_id,
6760            strategy_id,
6761            account_id,
6762            side,
6763        )
6764    }
6765
6766    /// Returns the count of all closed positions.
6767    #[must_use]
6768    pub fn positions_closed_count(
6769        &self,
6770        venue: Option<&Venue>,
6771        instrument_id: Option<&InstrumentId>,
6772        strategy_id: Option<&StrategyId>,
6773        account_id: Option<&AccountId>,
6774        side: Option<PositionSide>,
6775    ) -> usize {
6776        self.count_positions_in_bucket(
6777            &self.index.positions_closed,
6778            venue,
6779            instrument_id,
6780            strategy_id,
6781            account_id,
6782            side,
6783        )
6784    }
6785
6786    /// Returns the count of all positions.
6787    #[must_use]
6788    pub fn positions_total_count(
6789        &self,
6790        venue: Option<&Venue>,
6791        instrument_id: Option<&InstrumentId>,
6792        strategy_id: Option<&StrategyId>,
6793        account_id: Option<&AccountId>,
6794        side: Option<PositionSide>,
6795    ) -> usize {
6796        self.count_positions_in_bucket(
6797            &self.index.positions,
6798            venue,
6799            instrument_id,
6800            strategy_id,
6801            account_id,
6802            side,
6803        )
6804    }
6805
6806    /// Returns whether any open position matches the optional filter parameters.
6807    ///
6808    /// Short-circuits on the first match, avoiding the full intersection walk performed by
6809    /// [`Self::positions_open_count`]. Prefer this over `positions_open_count(...) > 0` when
6810    /// only existence matters.
6811    #[must_use]
6812    pub fn has_positions_open(
6813        &self,
6814        venue: Option<&Venue>,
6815        instrument_id: Option<&InstrumentId>,
6816        strategy_id: Option<&StrategyId>,
6817        account_id: Option<&AccountId>,
6818        side: Option<PositionSide>,
6819    ) -> bool {
6820        self.any_positions_in_bucket(
6821            &self.index.positions_open,
6822            venue,
6823            instrument_id,
6824            strategy_id,
6825            account_id,
6826            side,
6827        )
6828    }
6829
6830    /// Returns whether any closed position matches the optional filter parameters.
6831    #[must_use]
6832    pub fn has_positions_closed(
6833        &self,
6834        venue: Option<&Venue>,
6835        instrument_id: Option<&InstrumentId>,
6836        strategy_id: Option<&StrategyId>,
6837        account_id: Option<&AccountId>,
6838        side: Option<PositionSide>,
6839    ) -> bool {
6840        self.any_positions_in_bucket(
6841            &self.index.positions_closed,
6842            venue,
6843            instrument_id,
6844            strategy_id,
6845            account_id,
6846            side,
6847        )
6848    }
6849
6850    /// Returns whether any position (open or closed) matches the optional filter parameters.
6851    #[must_use]
6852    pub fn has_positions(
6853        &self,
6854        venue: Option<&Venue>,
6855        instrument_id: Option<&InstrumentId>,
6856        strategy_id: Option<&StrategyId>,
6857        account_id: Option<&AccountId>,
6858        side: Option<PositionSide>,
6859    ) -> bool {
6860        self.any_positions_in_bucket(
6861            &self.index.positions,
6862            venue,
6863            instrument_id,
6864            strategy_id,
6865            account_id,
6866            side,
6867        )
6868    }
6869
6870    // -- STRATEGY QUERIES ------------------------------------------------------------------------
6871
6872    /// Gets a reference to the strategy ID for the `client_order_id` (if found).
6873    #[must_use]
6874    pub fn strategy_id_for_order(&self, client_order_id: &ClientOrderId) -> Option<&StrategyId> {
6875        self.index.order_strategy.get(client_order_id)
6876    }
6877
6878    /// Gets a reference to the strategy ID for the `position_id` (if found).
6879    #[must_use]
6880    pub fn strategy_id_for_position(&self, position_id: &PositionId) -> Option<&StrategyId> {
6881        self.index.position_strategy.get(position_id)
6882    }
6883
6884    // -- GENERAL ---------------------------------------------------------------------------------
6885
6886    /// Gets a reference to the general value for the `key` (if found).
6887    ///
6888    /// # Errors
6889    ///
6890    /// Returns an error if the `key` is invalid.
6891    pub fn get(&self, key: &str) -> anyhow::Result<Option<&Bytes>> {
6892        check_valid_string_utf8(key, stringify!(key))?;
6893
6894        Ok(self.general.get(key))
6895    }
6896
6897    // -- DATA QUERIES ----------------------------------------------------------------------------
6898
6899    /// Returns the price for the `instrument_id` and `price_type` (if found).
6900    ///
6901    /// For `Mid`, returns `None` if no quote is cached or either price is a sentinel.
6902    /// For quote precision `p`, the midpoint has precision `p + 1` when exactly representable,
6903    /// otherwise `p`, rounded half-even if necessary. The fallback applies when the precision
6904    /// limit or raw range rules out `p + 1`, and when `p` is the maximum float precision (16),
6905    /// so a midpoint of a float-convertible quote stays float-convertible.
6906    #[must_use]
6907    pub fn price(&self, instrument_id: &InstrumentId, price_type: PriceType) -> Option<Price> {
6908        match price_type {
6909            PriceType::Bid => self
6910                .quotes
6911                .get(instrument_id)
6912                .and_then(|quotes| quotes.front().map(|quote| quote.bid_price)),
6913            PriceType::Ask => self
6914                .quotes
6915                .get(instrument_id)
6916                .and_then(|quotes| quotes.front().map(|quote| quote.ask_price)),
6917            PriceType::Mid => self.quotes.get(instrument_id).and_then(|quotes| {
6918                let quote = quotes.front()?;
6919                let bid = quote.bid_price;
6920                let ask = quote.ask_price;
6921                if bid.is_undefined() || bid.is_error() || ask.is_undefined() || ask.is_error() {
6922                    return None;
6923                }
6924
6925                // Also rejects `ERROR_PRICE`, whose precision is 255
6926                let precision = bid.precision;
6927                check_fixed_precision(precision).ok()?;
6928
6929                #[allow(
6930                    clippy::useless_conversion,
6931                    reason = "i128::from is a widening conversion when PriceRaw is i64"
6932                )]
6933                let (mut bid_raw, mut ask_raw) = (i128::from(bid.raw()), i128::from(ask.raw()));
6934
6935                if precision < FIXED_PRECISION {
6936                    let factor = 10_i128.pow(u32::from(FIXED_PRECISION - precision));
6937                    bid_raw = (bid_raw / factor) * factor;
6938                    ask_raw = (ask_raw / factor) * factor;
6939                }
6940                let sum = bid_raw.checked_add(ask_raw)?;
6941
6942                if precision < FIXED_PRECISION {
6943                    let raw = PriceRaw::try_from(sum / 2).ok()?;
6944                    return Price::from_raw_checked(raw, precision + 1).ok();
6945                }
6946
6947                if precision != MAX_FLOAT_PRECISION
6948                    && let Some(price) = sum
6949                        .checked_mul(5)
6950                        .and_then(|raw| PriceRaw::try_from(raw).ok())
6951                        .and_then(|raw| Price::from_raw_checked(raw, precision + 1).ok())
6952                {
6953                    return Some(price);
6954                }
6955
6956                let mut raw = sum / 2;
6957                if sum % 2 != 0 && raw % 2 != 0 {
6958                    raw += sum.signum();
6959                }
6960                let raw = PriceRaw::try_from(raw).ok()?;
6961                Price::from_raw_checked(raw, precision).ok()
6962            }),
6963            PriceType::Last => self
6964                .trades
6965                .get(instrument_id)
6966                .and_then(|trades| trades.front().map(|trade| trade.price)),
6967            PriceType::Mark => self
6968                .mark_prices
6969                .get(instrument_id)
6970                .and_then(|marks| marks.front().map(|mark| mark.value)),
6971        }
6972    }
6973
6974    /// Returns cached quotes for the `instrument_id` in reverse insertion order.
6975    ///
6976    /// Index 0 is the most recently added quote. Entries are not sorted by timestamp.
6977    /// Returns `None` when no quotes are cached for the instrument.
6978    #[must_use]
6979    pub fn quotes(&self, instrument_id: &InstrumentId) -> Option<Vec<QuoteTick>> {
6980        self.quotes
6981            .get(instrument_id)
6982            .map(|quotes| quotes.iter().copied().collect())
6983    }
6984
6985    /// Returns cached trades for the `instrument_id` in reverse insertion order.
6986    ///
6987    /// Index 0 is the most recently added trade. Entries are not sorted by timestamp.
6988    /// Returns `None` when no trades are cached for the instrument.
6989    #[must_use]
6990    pub fn trades(&self, instrument_id: &InstrumentId) -> Option<Vec<TradeTick>> {
6991        self.trades
6992            .get(instrument_id)
6993            .map(|trades| trades.iter().copied().collect())
6994    }
6995
6996    /// Returns cached mark price updates for the `instrument_id` in reverse insertion order.
6997    ///
6998    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
6999    /// Returns `None` when no mark price updates are cached for the instrument.
7000    #[must_use]
7001    pub fn mark_prices(&self, instrument_id: &InstrumentId) -> Option<Vec<MarkPriceUpdate>> {
7002        self.mark_prices
7003            .get(instrument_id)
7004            .map(|mark_prices| mark_prices.iter().copied().collect())
7005    }
7006
7007    /// Returns cached index price updates for the `instrument_id` in reverse insertion order.
7008    ///
7009    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
7010    /// Returns `None` when no index price updates are cached for the instrument.
7011    #[must_use]
7012    pub fn index_prices(&self, instrument_id: &InstrumentId) -> Option<Vec<IndexPriceUpdate>> {
7013        self.index_prices
7014            .get(instrument_id)
7015            .map(|index_prices| index_prices.iter().copied().collect())
7016    }
7017
7018    /// Returns cached funding rate updates for the `instrument_id` in reverse insertion order.
7019    ///
7020    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
7021    /// Returns `None` when no funding rate updates are cached for the instrument.
7022    #[must_use]
7023    pub fn funding_rates(&self, instrument_id: &InstrumentId) -> Option<Vec<FundingRateUpdate>> {
7024        self.funding_rates
7025            .get(instrument_id)
7026            .map(|funding_rates| funding_rates.iter().copied().collect())
7027    }
7028
7029    /// Returns cached instrument status updates for the `instrument_id` in reverse insertion order.
7030    ///
7031    /// Index 0 is the most recently added update. Entries are not sorted by timestamp.
7032    /// Returns `None` when no instrument status updates are cached for the instrument.
7033    #[must_use]
7034    pub fn instrument_statuses(
7035        &self,
7036        instrument_id: &InstrumentId,
7037    ) -> Option<Vec<InstrumentStatus>> {
7038        self.instrument_statuses
7039            .get(instrument_id)
7040            .map(|statuses| statuses.iter().copied().collect())
7041    }
7042
7043    /// Returns cached bars for the `bar_type` in reverse chronological order by `ts_event`.
7044    ///
7045    /// Index 0 is the most recent bar. Returns `None` when no bars are cached for the bar type.
7046    #[must_use]
7047    pub fn bars(&self, bar_type: &BarType) -> Option<Vec<Bar>> {
7048        self.bars
7049            .get(bar_type)
7050            .map(|bars| bars.iter().copied().collect())
7051    }
7052
7053    /// Returns the current order book for the `instrument_id`, or `None` if absent.
7054    ///
7055    /// The cache holds the current book state, not a history of book updates.
7056    #[must_use]
7057    pub fn order_book(&self, instrument_id: &InstrumentId) -> Option<&OrderBook> {
7058        self.books.get(instrument_id)
7059    }
7060
7061    /// Gets a reference to the order book for the `instrument_id`.
7062    ///
7063    /// # Errors
7064    ///
7065    /// Returns an error if the order book is not present in the cache.
7066    pub fn try_order_book(
7067        &self,
7068        instrument_id: &InstrumentId,
7069    ) -> Result<&OrderBook, OrderBookLookupError> {
7070        self.books
7071            .get(instrument_id)
7072            .ok_or_else(|| OrderBookLookupError::not_found(*instrument_id))
7073    }
7074
7075    /// Gets a reference to the order book for the `instrument_id`.
7076    #[must_use]
7077    pub fn order_book_mut(&mut self, instrument_id: &InstrumentId) -> Option<&mut OrderBook> {
7078        self.books.get_mut(instrument_id)
7079    }
7080
7081    /// Gets a reference to the own order book for the `instrument_id`.
7082    #[must_use]
7083    pub fn own_order_book(&self, instrument_id: &InstrumentId) -> Option<&OwnOrderBook> {
7084        self.own_books.get(instrument_id)
7085    }
7086
7087    /// Gets a reference to the own order book for the `instrument_id`.
7088    ///
7089    /// # Errors
7090    ///
7091    /// Returns an error if the own order book is not present in the cache.
7092    pub fn try_own_order_book(
7093        &self,
7094        instrument_id: &InstrumentId,
7095    ) -> Result<&OwnOrderBook, OwnOrderBookLookupError> {
7096        self.own_books
7097            .get(instrument_id)
7098            .ok_or_else(|| OwnOrderBookLookupError::not_found(*instrument_id))
7099    }
7100
7101    /// Gets a reference to the own order book for the `instrument_id`.
7102    #[must_use]
7103    pub fn own_order_book_mut(
7104        &mut self,
7105        instrument_id: &InstrumentId,
7106    ) -> Option<&mut OwnOrderBook> {
7107        self.own_books.get_mut(instrument_id)
7108    }
7109
7110    /// Returns the most recently added quote for the `instrument_id`, or `None` if absent.
7111    #[must_use]
7112    pub fn quote(&self, instrument_id: &InstrumentId) -> Option<&QuoteTick> {
7113        self.quotes
7114            .get(instrument_id)
7115            .and_then(|quotes| quotes.front())
7116    }
7117
7118    /// Returns the quote at `index` for the `instrument_id`.
7119    ///
7120    /// Index 0 is the most recently added quote; index 1 is the previous insertion.
7121    /// Entries are not sorted by timestamp. Returns `None` when no quote exists at the index.
7122    #[must_use]
7123    pub fn quote_at_index(&self, instrument_id: &InstrumentId, index: usize) -> Option<&QuoteTick> {
7124        self.quotes
7125            .get(instrument_id)
7126            .and_then(|quotes| quotes.get(index))
7127    }
7128
7129    /// Returns the most recently added trade for the `instrument_id`, or `None` if absent.
7130    #[must_use]
7131    pub fn trade(&self, instrument_id: &InstrumentId) -> Option<&TradeTick> {
7132        self.trades
7133            .get(instrument_id)
7134            .and_then(|trades| trades.front())
7135    }
7136
7137    /// Returns the trade at `index` for the `instrument_id`.
7138    ///
7139    /// Index 0 is the most recently added trade; index 1 is the previous insertion.
7140    /// Entries are not sorted by timestamp. Returns `None` when no trade exists at the index.
7141    #[must_use]
7142    pub fn trade_at_index(&self, instrument_id: &InstrumentId, index: usize) -> Option<&TradeTick> {
7143        self.trades
7144            .get(instrument_id)
7145            .and_then(|trades| trades.get(index))
7146    }
7147
7148    /// Returns the most recently added mark price update for the `instrument_id`, or `None` if absent.
7149    #[must_use]
7150    pub fn mark_price(&self, instrument_id: &InstrumentId) -> Option<&MarkPriceUpdate> {
7151        self.mark_prices
7152            .get(instrument_id)
7153            .and_then(|mark_prices| mark_prices.front())
7154    }
7155
7156    /// Returns the mark price update at `index` for the `instrument_id`.
7157    ///
7158    /// Index 0 is the most recently added update; index 1 is the previous insertion.
7159    /// Entries are not sorted by timestamp. Returns `None` when no update exists at the index.
7160    #[must_use]
7161    pub fn mark_price_at_index(
7162        &self,
7163        instrument_id: &InstrumentId,
7164        index: usize,
7165    ) -> Option<&MarkPriceUpdate> {
7166        self.mark_prices
7167            .get(instrument_id)
7168            .and_then(|mark_prices| mark_prices.get(index))
7169    }
7170
7171    /// Returns the most recently added index price update for the `instrument_id`, or `None` if absent.
7172    #[must_use]
7173    pub fn index_price(&self, instrument_id: &InstrumentId) -> Option<&IndexPriceUpdate> {
7174        self.index_prices
7175            .get(instrument_id)
7176            .and_then(|index_prices| index_prices.front())
7177    }
7178
7179    /// Returns the index price update at `index` for the `instrument_id`.
7180    ///
7181    /// Index 0 is the most recently added update; index 1 is the previous insertion.
7182    /// Entries are not sorted by timestamp. Returns `None` when no update exists at the index.
7183    #[must_use]
7184    pub fn index_price_at_index(
7185        &self,
7186        instrument_id: &InstrumentId,
7187        index: usize,
7188    ) -> Option<&IndexPriceUpdate> {
7189        self.index_prices
7190            .get(instrument_id)
7191            .and_then(|index_prices| index_prices.get(index))
7192    }
7193
7194    /// Returns the most recently added funding rate update for the `instrument_id`, or `None` if absent.
7195    #[must_use]
7196    pub fn funding_rate(&self, instrument_id: &InstrumentId) -> Option<&FundingRateUpdate> {
7197        self.funding_rates
7198            .get(instrument_id)
7199            .and_then(|funding_rates| funding_rates.front())
7200    }
7201
7202    /// Returns the funding rate update at `index` for the `instrument_id`.
7203    ///
7204    /// Index 0 is the most recently added update; index 1 is the previous insertion.
7205    /// Entries are not sorted by timestamp. Returns `None` when no update exists at the index.
7206    #[must_use]
7207    pub fn funding_rate_at_index(
7208        &self,
7209        instrument_id: &InstrumentId,
7210        index: usize,
7211    ) -> Option<&FundingRateUpdate> {
7212        self.funding_rates
7213            .get(instrument_id)
7214            .and_then(|funding_rates| funding_rates.get(index))
7215    }
7216
7217    /// Returns the most recently added instrument status for the `instrument_id`, or `None` if absent.
7218    #[must_use]
7219    pub fn instrument_status(&self, instrument_id: &InstrumentId) -> Option<&InstrumentStatus> {
7220        self.instrument_statuses
7221            .get(instrument_id)
7222            .and_then(|statuses| statuses.front())
7223    }
7224
7225    /// Returns the close cached for `instrument_id`, if present.
7226    ///
7227    /// A later insertion replaces the cached close for the instrument; no history is kept.
7228    #[must_use]
7229    pub fn instrument_close(&self, instrument_id: &InstrumentId) -> Option<&InstrumentClose> {
7230        self.instrument_closes.get(instrument_id)
7231    }
7232
7233    /// Returns references to all instrument IDs with a cached close.
7234    #[must_use]
7235    pub fn instrument_close_ids(&self) -> Vec<&InstrumentId> {
7236        self.instrument_closes.keys().collect()
7237    }
7238
7239    /// Returns the most recent bar by `ts_event` for the `bar_type`, or `None` if absent.
7240    #[must_use]
7241    pub fn bar(&self, bar_type: &BarType) -> Option<&Bar> {
7242        self.bars.get(bar_type).and_then(|bars| bars.front())
7243    }
7244
7245    /// Returns the bar at `index` for the `bar_type`.
7246    ///
7247    /// Bars are ordered by `ts_event`, newest first. Index 0 is the most recent bar;
7248    /// index 1 is the previous bar. Returns `None` when no bar exists at the index.
7249    #[must_use]
7250    pub fn bar_at_index(&self, bar_type: &BarType, index: usize) -> Option<&Bar> {
7251        self.bars.get(bar_type).and_then(|bars| bars.get(index))
7252    }
7253
7254    /// Gets the order book update count for the `instrument_id`.
7255    #[must_use]
7256    pub fn book_update_count(&self, instrument_id: &InstrumentId) -> usize {
7257        self.books
7258            .get(instrument_id)
7259            .map_or(0, |book| book.update_count) as usize
7260    }
7261
7262    /// Gets the quote tick count for the `instrument_id`.
7263    #[must_use]
7264    pub fn quote_count(&self, instrument_id: &InstrumentId) -> usize {
7265        self.quotes
7266            .get(instrument_id)
7267            .map_or(0, BoundedVecDeque::len)
7268    }
7269
7270    /// Gets the trade tick count for the `instrument_id`.
7271    #[must_use]
7272    pub fn trade_count(&self, instrument_id: &InstrumentId) -> usize {
7273        self.trades
7274            .get(instrument_id)
7275            .map_or(0, BoundedVecDeque::len)
7276    }
7277
7278    /// Gets the mark price update count for the `instrument_id`.
7279    #[must_use]
7280    pub fn mark_price_count(&self, instrument_id: &InstrumentId) -> usize {
7281        self.mark_prices
7282            .get(instrument_id)
7283            .map_or(0, BoundedVecDeque::len)
7284    }
7285
7286    /// Gets the index price update count for the `instrument_id`.
7287    #[must_use]
7288    pub fn index_price_count(&self, instrument_id: &InstrumentId) -> usize {
7289        self.index_prices
7290            .get(instrument_id)
7291            .map_or(0, BoundedVecDeque::len)
7292    }
7293
7294    /// Gets the funding rate update count for the `instrument_id`.
7295    #[must_use]
7296    pub fn funding_rate_count(&self, instrument_id: &InstrumentId) -> usize {
7297        self.funding_rates
7298            .get(instrument_id)
7299            .map_or(0, BoundedVecDeque::len)
7300    }
7301
7302    /// Gets the instrument status update count for the `instrument_id`.
7303    #[must_use]
7304    pub fn instrument_status_count(&self, instrument_id: &InstrumentId) -> usize {
7305        self.instrument_statuses
7306            .get(instrument_id)
7307            .map_or(0, BoundedVecDeque::len)
7308    }
7309
7310    /// Gets the bar count for the `instrument_id`.
7311    #[must_use]
7312    pub fn bar_count(&self, bar_type: &BarType) -> usize {
7313        self.bars.get(bar_type).map_or(0, BoundedVecDeque::len)
7314    }
7315
7316    /// Returns whether the cache contains an order book for the `instrument_id`.
7317    #[must_use]
7318    pub fn has_order_book(&self, instrument_id: &InstrumentId) -> bool {
7319        self.books.contains_key(instrument_id)
7320    }
7321
7322    /// Returns whether the cache contains quotes for the `instrument_id`.
7323    #[must_use]
7324    pub fn has_quote_ticks(&self, instrument_id: &InstrumentId) -> bool {
7325        self.quote_count(instrument_id) > 0
7326    }
7327
7328    /// Returns whether the cache contains trades for the `instrument_id`.
7329    #[must_use]
7330    pub fn has_trade_ticks(&self, instrument_id: &InstrumentId) -> bool {
7331        self.trade_count(instrument_id) > 0
7332    }
7333
7334    /// Returns whether the cache contains mark price updates for the `instrument_id`.
7335    #[must_use]
7336    pub fn has_mark_prices(&self, instrument_id: &InstrumentId) -> bool {
7337        self.mark_price_count(instrument_id) > 0
7338    }
7339
7340    /// Returns whether the cache contains index price updates for the `instrument_id`.
7341    #[must_use]
7342    pub fn has_index_prices(&self, instrument_id: &InstrumentId) -> bool {
7343        self.index_price_count(instrument_id) > 0
7344    }
7345
7346    /// Returns whether the cache contains funding rate updates for the `instrument_id`.
7347    #[must_use]
7348    pub fn has_funding_rates(&self, instrument_id: &InstrumentId) -> bool {
7349        self.funding_rate_count(instrument_id) > 0
7350    }
7351
7352    /// Returns whether the cache contains instrument status updates for the `instrument_id`.
7353    #[must_use]
7354    pub fn has_instrument_statuses(&self, instrument_id: &InstrumentId) -> bool {
7355        self.instrument_status_count(instrument_id) > 0
7356    }
7357
7358    /// Returns whether the cache contains a close for the `instrument_id`.
7359    #[must_use]
7360    pub fn has_instrument_close(&self, instrument_id: &InstrumentId) -> bool {
7361        self.instrument_closes.contains_key(instrument_id)
7362    }
7363
7364    /// Returns whether the cache contains bars for the `bar_type`.
7365    #[must_use]
7366    pub fn has_bars(&self, bar_type: &BarType) -> bool {
7367        self.bar_count(bar_type) > 0
7368    }
7369
7370    #[must_use]
7371    pub fn get_xrate(
7372        &self,
7373        venue: Venue,
7374        from_currency: Currency,
7375        to_currency: Currency,
7376        price_type: PriceType,
7377    ) -> Option<Decimal> {
7378        match self.try_get_xrate(venue, from_currency, to_currency, price_type) {
7379            Ok(rate) => rate,
7380            Err(e) => {
7381                log::error!("Failed to calculate xrate: {e}");
7382                None
7383            }
7384        }
7385    }
7386
7387    /// Tries to calculate the exchange rate without logging calculation errors.
7388    ///
7389    /// If preferred quotes cannot form a rate, tries alternate quote selections by replacement
7390    /// count, then source preference. This can take exponential time in the number of alternates.
7391    ///
7392    /// # Errors
7393    ///
7394    /// Returns an error if the cached quotes cannot form a valid exchange rate calculation.
7395    pub fn try_get_xrate(
7396        &self,
7397        venue: Venue,
7398        from_currency: Currency,
7399        to_currency: Currency,
7400        price_type: PriceType,
7401    ) -> anyhow::Result<Option<Decimal>> {
7402        if from_currency == to_currency {
7403            // When the source and target currencies are identical,
7404            // no conversion is needed; return an exchange rate of one.
7405            return Ok(Some(Decimal::ONE));
7406        }
7407
7408        let (bid_quote, ask_quote, alternates) = self.build_quote_table(&venue);
7409
7410        if alternates.is_empty() {
7411            get_exchange_rate(
7412                from_currency.code,
7413                to_currency.code,
7414                price_type,
7415                bid_quote,
7416                ask_quote,
7417            )
7418        } else {
7419            get_exchange_rate_with_alternates(
7420                from_currency.code,
7421                to_currency.code,
7422                price_type,
7423                &bid_quote,
7424                &ask_quote,
7425                &alternates,
7426            )
7427        }
7428    }
7429
7430    fn build_quote_table(&self, venue: &Venue) -> QuoteTable {
7431        let mut bid_quotes = AHashMap::new();
7432        let mut ask_quotes = AHashMap::new();
7433        let mut quote_sources = AHashMap::new();
7434        let mut alternates = Vec::new();
7435        let mut bar_quotes = None;
7436        let mut pair_buffer = String::new();
7437
7438        for (instrument_id, instrument) in &self.instruments {
7439            if instrument_id.venue != *venue {
7440                continue;
7441            }
7442
7443            let Some(base_currency) = instrument.base_currency() else {
7444                continue;
7445            };
7446
7447            let (bid_price, ask_price) = if let Some(ticks) = self.quotes.get(instrument_id) {
7448                if let Some(tick) = ticks.front() {
7449                    (tick.bid_price, tick.ask_price)
7450                } else {
7451                    continue; // Empty ticks vector
7452                }
7453            } else {
7454                let quotes = bar_quotes.get_or_insert_with(|| self.build_bar_quote_table(venue));
7455                match (
7456                    quotes.get(&(*instrument_id, PriceType::Bid)),
7457                    quotes.get(&(*instrument_id, PriceType::Ask)),
7458                ) {
7459                    (Some((_, bid_bar)), Some((_, ask_bar))) => (bid_bar.close, ask_bar.close),
7460                    _ => continue,
7461                }
7462            };
7463
7464            let base = base_currency.code.as_str();
7465            let quote = instrument.quote_currency().code.as_str();
7466            pair_buffer.clear();
7467            pair_buffer.reserve(base.len() + 1 + quote.len());
7468            pair_buffer.push_str(base);
7469            pair_buffer.push('/');
7470            pair_buffer.push_str(quote);
7471            let pair = Ustr::from(pair_buffer.as_str());
7472            let preference = (
7473                bid_price.is_positive() && ask_price.is_positive(),
7474                instrument.instrument_class() == InstrumentClass::Spot,
7475                Reverse(*instrument_id),
7476            );
7477
7478            if quote_sources
7479                .get(&pair)
7480                .is_some_and(|current| current >= &preference)
7481            {
7482                alternates.push((
7483                    preference,
7484                    pair,
7485                    bid_price.as_decimal(),
7486                    ask_price.as_decimal(),
7487                ));
7488                continue;
7489            }
7490
7491            let previous = quote_sources.insert(pair, preference);
7492            if let (Some(preference), Some(bid), Some(ask)) = (
7493                previous,
7494                bid_quotes.insert(pair, bid_price.as_decimal()),
7495                ask_quotes.insert(pair, ask_price.as_decimal()),
7496            ) {
7497                alternates.push((preference, pair, bid, ask));
7498            }
7499        }
7500
7501        alternates.sort_unstable_by_key(|entry| Reverse(entry.0));
7502        let alternates = alternates
7503            .into_iter()
7504            .map(|(_, pair, bid, ask)| (pair, bid, ask))
7505            .collect();
7506
7507        (bid_quotes, ask_quotes, alternates)
7508    }
7509
7510    fn build_bar_quote_table(
7511        &self,
7512        venue: &Venue,
7513    ) -> AHashMap<(InstrumentId, PriceType), (&BarType, &Bar)> {
7514        let mut quotes: AHashMap<_, (&BarType, &Bar)> = AHashMap::new();
7515
7516        for (bar_type, bars) in &self.bars {
7517            let instrument_id = bar_type.instrument_id();
7518            let price_type = bar_type.spec().price_type;
7519
7520            if instrument_id.venue != *venue
7521                || !matches!(price_type, PriceType::Bid | PriceType::Ask)
7522            {
7523                continue;
7524            }
7525
7526            let Some(bar) = bars.front() else {
7527                continue;
7528            };
7529
7530            // Select the newest front bar per side, breaking timestamp ties by bar type
7531            quotes
7532                .entry((instrument_id, price_type))
7533                .and_modify(|current| {
7534                    if (current.1.ts_init, current.0) < (bar.ts_init, bar_type) {
7535                        *current = (bar_type, bar);
7536                    }
7537                })
7538                .or_insert((bar_type, bar));
7539        }
7540
7541        quotes
7542    }
7543
7544    /// Returns the mark exchange rate for the given currency pair, or `None` if not set.
7545    #[must_use]
7546    pub fn get_mark_xrate(&self, from_currency: Currency, to_currency: Currency) -> Option<f64> {
7547        self.mark_xrates.get(&(from_currency, to_currency)).copied()
7548    }
7549
7550    /// Sets the mark exchange rate for the given currency pair and automatically sets the inverse rate.
7551    ///
7552    /// # Panics
7553    ///
7554    /// Panics if `xrate` is not positive.
7555    pub fn set_mark_xrate(&mut self, from_currency: Currency, to_currency: Currency, xrate: f64) {
7556        assert!(xrate > 0.0, "xrate was zero");
7557        self.mark_xrates.insert((from_currency, to_currency), xrate);
7558        self.mark_xrates
7559            .insert((to_currency, from_currency), 1.0 / xrate);
7560    }
7561
7562    /// Clears the mark exchange rate for the given currency pair direction.
7563    ///
7564    /// Removes only the `(from_currency, to_currency)` entry; the inverse rate written
7565    /// by [`Self::set_mark_xrate`] is retained until cleared separately or
7566    /// [`Self::clear_mark_xrates`] is called.
7567    pub fn clear_mark_xrate(&mut self, from_currency: Currency, to_currency: Currency) {
7568        let _ = self.mark_xrates.remove(&(from_currency, to_currency));
7569    }
7570
7571    /// Clears all mark exchange rates.
7572    pub fn clear_mark_xrates(&mut self) {
7573        self.mark_xrates.clear();
7574    }
7575
7576    /// Returns a reference to the currency for the `code` (if found).
7577    #[must_use]
7578    pub fn currency(&self, code: &Ustr) -> Option<&Currency> {
7579        self.currencies.get(code)
7580    }
7581
7582    /// Returns a reference to the currency for the `code`.
7583    ///
7584    /// # Errors
7585    ///
7586    /// Returns an error if the currency is not present in the cache.
7587    pub fn try_currency(&self, code: &Ustr) -> Result<&Currency, CurrencyLookupError> {
7588        self.currencies
7589            .get(code)
7590            .ok_or_else(|| CurrencyLookupError::not_found(*code))
7591    }
7592
7593    // -- INSTRUMENT QUERIES ----------------------------------------------------------------------
7594
7595    /// Returns a reference to the instrument for the `instrument_id` (if found).
7596    #[must_use]
7597    pub fn instrument(&self, instrument_id: &InstrumentId) -> Option<&InstrumentAny> {
7598        self.instruments.get(instrument_id)
7599    }
7600
7601    /// Returns a reference to the instrument for the `instrument_id`.
7602    ///
7603    /// # Errors
7604    ///
7605    /// Returns an error if the instrument is not present in the cache.
7606    pub fn try_instrument(
7607        &self,
7608        instrument_id: &InstrumentId,
7609    ) -> Result<&InstrumentAny, InstrumentLookupError> {
7610        self.instruments
7611            .get(instrument_id)
7612            .ok_or_else(|| InstrumentLookupError::not_found(*instrument_id))
7613    }
7614
7615    /// Returns references to all instrument IDs for the `venue`.
7616    #[must_use]
7617    pub fn instrument_ids(&self, venue: Option<&Venue>) -> Vec<&InstrumentId> {
7618        match venue {
7619            Some(v) => self.instruments.keys().filter(|i| &i.venue == v).collect(),
7620            None => self.instruments.keys().collect(),
7621        }
7622    }
7623
7624    /// Returns references to all instruments for the `venue`.
7625    #[must_use]
7626    pub fn instruments(&self, venue: &Venue, underlying: Option<&Ustr>) -> Vec<&InstrumentAny> {
7627        self.instruments
7628            .values()
7629            .filter(|i| &i.id().venue == venue)
7630            .filter(|i| underlying.is_none_or(|u| i.underlying() == Some(*u)))
7631            .collect()
7632    }
7633
7634    /// Returns references to all instruments for the `venue` whose underlying
7635    /// equals `root` and whose [`InstrumentClass`] equals `class`.
7636    ///
7637    /// Use when expanding a parent-symbol subscription: filtering by class as
7638    /// well as root prevents leaves of a different class (e.g. options when
7639    /// the user asked for futures, or vice versa) from being pulled in.
7640    #[must_use]
7641    pub fn instruments_by_parent(
7642        &self,
7643        venue: &Venue,
7644        root: &Ustr,
7645        class: InstrumentClass,
7646    ) -> Vec<&InstrumentAny> {
7647        self.instruments
7648            .values()
7649            .filter(|i| &i.id().venue == venue)
7650            .filter(|i| i.underlying() == Some(*root))
7651            .filter(|i| i.instrument_class() == class)
7652            .collect()
7653    }
7654
7655    /// Returns references to all bar types contained in the cache.
7656    #[must_use]
7657    pub fn bar_types(
7658        &self,
7659        instrument_id: Option<&InstrumentId>,
7660        price_type: Option<&PriceType>,
7661        aggregation_source: AggregationSource,
7662    ) -> Vec<&BarType> {
7663        let mut bar_types = self
7664            .bars
7665            .keys()
7666            .filter(|bar_type| bar_type.aggregation_source() == aggregation_source)
7667            .collect::<Vec<&BarType>>();
7668
7669        if let Some(instrument_id) = instrument_id {
7670            bar_types.retain(|bar_type| bar_type.instrument_id() == *instrument_id);
7671        }
7672
7673        if let Some(price_type) = price_type {
7674            bar_types.retain(|bar_type| &bar_type.spec().price_type == price_type);
7675        }
7676
7677        bar_types
7678    }
7679
7680    // -- SYNTHETIC QUERIES -----------------------------------------------------------------------
7681
7682    /// Returns a reference to the synthetic instrument for the `instrument_id` (if found).
7683    #[must_use]
7684    pub fn synthetic(&self, instrument_id: &InstrumentId) -> Option<&SyntheticInstrument> {
7685        self.synthetics.get(instrument_id)
7686    }
7687
7688    /// Returns a reference to the synthetic instrument for the `instrument_id`.
7689    ///
7690    /// # Errors
7691    ///
7692    /// Returns an error if the synthetic instrument is not present in the cache.
7693    pub fn try_synthetic(
7694        &self,
7695        instrument_id: &InstrumentId,
7696    ) -> Result<&SyntheticInstrument, SyntheticInstrumentLookupError> {
7697        self.synthetics
7698            .get(instrument_id)
7699            .ok_or_else(|| SyntheticInstrumentLookupError::not_found(*instrument_id))
7700    }
7701
7702    /// Returns references to instrument IDs for all synthetic instruments contained in the cache.
7703    #[must_use]
7704    pub fn synthetic_ids(&self) -> Vec<&InstrumentId> {
7705        self.synthetics.keys().collect()
7706    }
7707
7708    /// Returns references to all synthetic instruments contained in the cache.
7709    #[must_use]
7710    pub fn synthetics(&self) -> Vec<&SyntheticInstrument> {
7711        self.synthetics.values().collect()
7712    }
7713
7714    // -- ACCOUNT QUERIES -----------------------------------------------------------------------
7715
7716    /// Returns a borrow of the account for the `account_id` (if found).
7717    #[must_use]
7718    pub fn account_ref(&self, account_id: &AccountId) -> Option<AccountRef<'_>> {
7719        self.accounts
7720            .get(account_id)
7721            .map(|account_cell| AccountRef::new(account_cell.borrow()))
7722    }
7723
7724    /// Returns a borrow of the account for the `account_id` (if found).
7725    ///
7726    /// Prefer [`Self::account_ref`] in new native code.
7727    #[must_use]
7728    pub fn account(&self, account_id: &AccountId) -> Option<AccountRef<'_>> {
7729        self.account_ref(account_id)
7730    }
7731
7732    /// Returns a borrow of the account for the `account_id`.
7733    ///
7734    /// # Errors
7735    ///
7736    /// Returns an error if the account is not present in the cache.
7737    pub fn try_account_ref(
7738        &self,
7739        account_id: &AccountId,
7740    ) -> Result<AccountRef<'_>, AccountLookupError> {
7741        self.accounts
7742            .get(account_id)
7743            .map(|account_cell| AccountRef::new(account_cell.borrow()))
7744            .ok_or_else(|| AccountLookupError::not_found(*account_id))
7745    }
7746
7747    /// Returns a borrow of the account for the `account_id`.
7748    ///
7749    /// Prefer [`Self::try_account_ref`] in new native code.
7750    ///
7751    /// # Errors
7752    ///
7753    /// Returns an error if the account is not present in the cache.
7754    pub fn try_account(
7755        &self,
7756        account_id: &AccountId,
7757    ) -> Result<AccountRef<'_>, AccountLookupError> {
7758        self.try_account_ref(account_id)
7759    }
7760
7761    /// Gets an exclusive write borrow of the account with the `account_id` (if found).
7762    ///
7763    /// Requires `&mut Cache` so cache writes are reachable only by privileged crates that hold
7764    /// `Rc<RefCell<Cache>>` directly. Adapter-facing code receives [`CacheView`], which only
7765    /// exposes immutable cache borrows and therefore cannot reach this method.
7766    ///
7767    /// While the returned [`AccountRefMut`] is alive, no other read or write of the same account
7768    /// is permitted. Drop the borrow before dispatching events or taking any other cache borrow
7769    /// that may re-enter the same account.
7770    #[must_use]
7771    pub fn account_mut(&mut self, account_id: &AccountId) -> Option<AccountRefMut<'_>> {
7772        self.accounts
7773            .get(account_id)
7774            .map(|account_cell| AccountRefMut::new(account_cell.borrow_mut()))
7775    }
7776
7777    /// Gets an owned snapshot of the account with the `account_id` when present and not mutably
7778    /// borrowed.
7779    ///
7780    /// Use when downstream needs an owned [`AccountAny`] that crosses a boundary. The snapshot
7781    /// will not reflect later cache mutations.
7782    #[must_use]
7783    pub fn account_owned(&self, account_id: &AccountId) -> Option<AccountAny> {
7784        self.accounts.get(account_id).and_then(|account_cell| {
7785            account_cell
7786                .try_borrow()
7787                .ok()
7788                .map(|account| account.clone())
7789        })
7790    }
7791
7792    /// Returns a borrow of the account for the `venue` (if found).
7793    ///
7794    /// Returns `None` when more than one account is issued under the `venue`; look those
7795    /// accounts up by account ID instead.
7796    #[must_use]
7797    pub fn account_for_venue(&self, venue: &Venue) -> Option<AccountRef<'_>> {
7798        self.account_id(venue)
7799            .and_then(|account_id| self.accounts.get(account_id))
7800            .map(|account_cell| AccountRef::new(account_cell.borrow()))
7801    }
7802
7803    /// Returns an owned snapshot of the account for the `venue` (if found).
7804    ///
7805    /// Use when downstream needs an owned [`AccountAny`] that crosses a boundary. The snapshot
7806    /// will not reflect later cache mutations. Returns `None` when more than one account is
7807    /// issued under the `venue`.
7808    #[must_use]
7809    pub fn account_for_venue_owned(&self, venue: &Venue) -> Option<AccountAny> {
7810        self.account_id(venue)
7811            .and_then(|account_id| self.accounts.get(account_id))
7812            .map(|account_cell| account_cell.borrow().clone())
7813    }
7814
7815    /// Returns a reference to the account ID for the `venue` (if found).
7816    ///
7817    /// Returns `None` when more than one account is issued under the `venue`.
7818    #[must_use]
7819    pub fn account_id(&self, venue: &Venue) -> Option<&AccountId> {
7820        let mut account_ids = self.index.venue_accounts.get(venue)?.iter();
7821        let account_id = account_ids.next()?;
7822        account_ids.next().is_none().then_some(account_id)
7823    }
7824
7825    /// Returns borrows of all accounts for the `account_id`.
7826    ///
7827    /// Each [`AccountRef`] in the returned vector borrows its underlying cell; mutating any of
7828    /// those accounts while the vector is alive will panic at runtime. Drop the vector before
7829    /// issuing writes.
7830    #[must_use]
7831    pub fn accounts(&self, account_id: &AccountId) -> Vec<AccountRef<'_>> {
7832        self.accounts
7833            .values()
7834            .filter(|account_cell| &account_cell.borrow().id() == account_id)
7835            .map(|account_cell| AccountRef::new(account_cell.borrow()))
7836            .collect()
7837    }
7838
7839    /// Returns owned copies of every account in the cache.
7840    #[must_use]
7841    pub fn accounts_all_owned(&self) -> Vec<AccountAny> {
7842        self.accounts
7843            .values()
7844            .map(|account_cell| account_cell.borrow().clone())
7845            .collect()
7846    }
7847
7848    /// Updates the own order book with an order.
7849    ///
7850    /// This method adds, updates, or removes an order from the own order book
7851    /// based on the order's current state.
7852    ///
7853    /// Orders without prices (MARKET, etc.) are skipped as they cannot be
7854    /// represented in own books.
7855    pub fn update_own_order_book(&mut self, order: &OrderAny) {
7856        if !order.has_price() {
7857            return;
7858        }
7859
7860        let instrument_id = order.instrument_id();
7861
7862        if !self.own_books.contains_key(&instrument_id) {
7863            if order.is_closed() {
7864                return;
7865            }
7866
7867            self.own_books
7868                .insert(instrument_id, OwnOrderBook::new(instrument_id));
7869        }
7870
7871        let Some(own_book) = self.own_books.get_mut(&instrument_id) else {
7872            return;
7873        };
7874
7875        let own_book_order = order.to_own_book_order();
7876
7877        if order.is_closed() {
7878            if let Err(e) = own_book.delete(own_book_order) {
7879                log::debug!(
7880                    "Failed to delete order {} from own book: {e}",
7881                    order.client_order_id(),
7882                );
7883            } else {
7884                log::debug!("Deleted order {} from own book", order.client_order_id());
7885            }
7886        } else {
7887            // Add or update the order in the own book
7888            if let Err(e) = own_book.update(own_book_order) {
7889                log::debug!(
7890                    "Failed to update order {} in own book: {e}; inserting instead",
7891                    order.client_order_id(),
7892                );
7893                own_book.add(own_book_order);
7894            }
7895            log::debug!("Updated order {} in own book", order.client_order_id());
7896        }
7897    }
7898
7899    /// Force removal of an order from own order books and clean up all indexes.
7900    ///
7901    /// This method is used when order event application fails and we need to ensure
7902    /// terminal orders are properly cleaned up from own books and all relevant indexes.
7903    /// Replicates the index cleanup that `update_order` performs for closed orders.
7904    pub fn force_remove_from_own_order_book(&mut self, client_order_id: &ClientOrderId) {
7905        let Some(order_cell) = self.orders.get(client_order_id) else {
7906            return;
7907        };
7908        let order = order_cell.borrow();
7909        let instrument_id = order.instrument_id();
7910        let own_book_order = if order.has_price() {
7911            Some(order.to_own_book_order())
7912        } else {
7913            None
7914        };
7915        drop(order);
7916
7917        self.index.orders_open.remove(client_order_id);
7918        self.index.orders_pending_cancel.remove(client_order_id);
7919        self.index.orders_inflight.remove(client_order_id);
7920        self.index.orders_emulated.remove(client_order_id);
7921        self.index.orders_active_local.remove(client_order_id);
7922
7923        if let Some(own_book) = self.own_books.get_mut(&instrument_id)
7924            && let Some(own_book_order) = own_book_order
7925        {
7926            if let Err(e) = own_book.delete(own_book_order) {
7927                log::debug!("Could not force delete {client_order_id} from own book: {e}");
7928            } else {
7929                log::debug!("Force deleted {client_order_id} from own book");
7930            }
7931        }
7932
7933        self.index.orders_closed.insert(*client_order_id);
7934    }
7935
7936    /// Audit all own order books against active order indexes.
7937    ///
7938    /// Ensures orders absent from the open, inflight, and active-local indexes are removed from
7939    /// own order books.
7940    pub fn audit_own_order_books(&mut self) {
7941        log::debug!("Starting own books audit");
7942        let start = std::time::Instant::now();
7943
7944        let valid_order_ids: AHashSet<ClientOrderId> = self
7945            .index
7946            .orders_open
7947            .iter()
7948            .chain(&self.index.orders_inflight)
7949            .chain(&self.index.orders_active_local)
7950            .copied()
7951            .collect();
7952
7953        for own_book in self.own_books.values_mut() {
7954            own_book.audit_open_orders(&valid_order_ids);
7955        }
7956
7957        log::debug!("Completed own books audit in {:?}", start.elapsed());
7958    }
7959}
7960
7961type QuoteTable = (
7962    AHashMap<Ustr, Decimal>,
7963    AHashMap<Ustr, Decimal>,
7964    Vec<(Ustr, Decimal, Decimal)>,
7965);
7966
7967const POSITION_OMS_KEY_PREFIX: &str = "position_oms:";
7968
7969#[cfg_attr(
7970    not(feature = "defi"),
7971    expect(
7972        clippy::unnecessary_wraps,
7973        reason = "only DeFi integrity rejections propagate"
7974    )
7975)]
7976fn handle_persistence_result(
7977    operation: impl Display,
7978    result: anyhow::Result<()>,
7979) -> anyhow::Result<()> {
7980    if let Err(e) = result {
7981        #[cfg(feature = "defi")]
7982        if e.is::<IntegrityError>() {
7983            return Err(e);
7984        }
7985
7986        log::error!("Failed to {operation}: {e:#}");
7987    }
7988
7989    Ok(())
7990}
7991
7992fn position_oms_key(position_id: PositionId) -> String {
7993    format!("{POSITION_OMS_KEY_PREFIX}{position_id}")
7994}
7995
7996fn resolve_position_oms(position: &Position, oms_type: OmsType) -> OmsType {
7997    if oms_type == OmsType::Unspecified
7998        && position.id.as_str() == format!("{}-{}", position.instrument_id, position.strategy_id)
7999    {
8000        OmsType::Netting
8001    } else {
8002        oms_type
8003    }
8004}
8005
8006/// Inserts `bar` into the newest-first bars deque for a `bar_type`.
8007///
8008/// A newer bar is pushed, an older `ts_event` is skipped, and an equal
8009/// `ts_event` replaces the front bar for time bars.
8010fn insert_bar(bars: &mut BoundedVecDeque<Bar>, bar: Bar) {
8011    match bars.front() {
8012        None => bars.push_front(bar),
8013        Some(front) => match bar.ts_event.cmp(&front.ts_event) {
8014            Ordering::Greater => bars.push_front(bar),
8015            Ordering::Equal => {
8016                if bar.bar_type.spec().is_time_aggregated() {
8017                    bars.replace_front(bar);
8018                } else {
8019                    bars.push_front(bar);
8020                }
8021            }
8022            Ordering::Less => log::debug!(
8023                "Skipping bar {bar} with `ts_event` older than last bar `ts_event` {}",
8024                front.ts_event,
8025            ),
8026        },
8027    }
8028}
8029
8030/// Inserts `bar` at its ordered position in the newest-first bars deque.
8031///
8032/// Bars older than the front are kept; a time bar replaces the cached bar
8033/// with an equal `ts_event`.
8034fn insert_bar_historical(bars: &mut BoundedVecDeque<Bar>, bar: Bar) {
8035    let index = bars.partition_point(|cached| cached.ts_event > bar.ts_event);
8036
8037    if bar.bar_type.spec().is_time_aggregated()
8038        && bars
8039            .get(index)
8040            .is_some_and(|cached| cached.ts_event == bar.ts_event)
8041    {
8042        bars.replace(index, bar);
8043    } else {
8044        bars.insert(index, bar);
8045    }
8046}