Skip to main content

nautilus_backtest/
engine.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//! The core `BacktestEngine` for backtesting on historical data.
17
18use std::{
19    any::Any,
20    cell::RefCell,
21    fmt::Debug,
22    rc::{Rc, Weak},
23    sync::Arc,
24};
25
26use ahash::{AHashMap, AHashSet};
27use indexmap::IndexMap;
28use nautilus_analysis::analyzer::PortfolioAnalyzer;
29use nautilus_common::{
30    actor::{self, CallbackDispatchError, DataActor, DataActorNative},
31    cache::Cache,
32    clients::ExecutionClient,
33    clock::{Clock, VirtualClock},
34    component::{Component, component_state},
35    enums::{ComponentState, LogColor},
36    log_info,
37    logging::{
38        logging_clock_set_realtime_mode, logging_clock_set_static_mode,
39        logging_clock_set_static_time,
40    },
41    runner::{
42        SyncDataCommandSender, SyncTradingCommandSender, clear_command_queues,
43        data_cmd_queue_is_empty, drain_data_cmd_queue, drain_trading_cmd_queue,
44        replace_data_cmd_sender, replace_exec_cmd_sender, trading_cmd_queue_is_empty,
45    },
46    timer::{TimeEvent, TimeEventCallback},
47};
48use nautilus_core::{
49    DurationNanos, UUID4, UnixNanos, datetime::unix_nanos_to_iso8601,
50    string::formatting::Separable, time::nanos_since_unix_epoch,
51};
52use nautilus_data::client::DataClientAdapter;
53use nautilus_execution::models::fill::FillModelHandle;
54use nautilus_model::{
55    accounts::{Account, AccountAny},
56    data::{Data, DataBatch, DataRef, HasTsInit},
57    enums::{AccountType, AggregationSource, BookType},
58    identifiers::{AccountId, ClientId, InstrumentId, StrategyId, TraderId, Venue},
59    instruments::{Instrument, InstrumentAny},
60    position::Position,
61};
62use nautilus_portfolio::portfolio::is_snapshot_timer;
63#[cfg(feature = "python")]
64use nautilus_system::trader::Trader;
65use nautilus_system::{config::NautilusKernelConfig, kernel::NautilusKernel};
66use nautilus_trading::{
67    ExecutionAlgorithm, ExecutionAlgorithmNative,
68    strategy::{Strategy, StrategyNative},
69};
70
71use crate::{
72    accumulator::TimeEventAccumulator,
73    config::{BacktestEngineConfig, SimulatedVenueConfig},
74    data_client::BacktestDataClient,
75    data_iterator::BacktestDataIterator,
76    exchange::{SettlementScope, SimulatedExchange},
77    execution_client::BacktestExecutionClient,
78    result::{
79        BacktestResult, CanonicalBacktestResult, CanonicalBacktestState, CanonicalDiagnostic,
80        CanonicalDiagnosticCode, CanonicalRunOutcome,
81    },
82};
83
84const CALLBACK_DRAIN_BUDGET: usize = 1024;
85
86/// Core backtesting engine for running event-driven strategy backtests on historical data.
87///
88/// The `BacktestEngine` provides a high-fidelity simulation environment that processes
89/// historical market data chronologically through an event-driven architecture. It maintains
90/// simulated exchanges with realistic order matching and execution, allowing strategies
91/// to be tested exactly as they would run in live trading:
92///
93/// - Event-driven data replay with configurable latency models.
94/// - Multi-venue and multi-asset support.
95/// - Realistic order matching and execution simulation.
96/// - Strategy and portfolio performance analysis.
97/// - Transition from backtesting to live trading.
98pub struct BacktestEngine {
99    kernel: NautilusKernel,
100    instance_id: UUID4,
101    config: BacktestEngineConfig,
102    accumulator: TimeEventAccumulator,
103    run_config_id: Option<String>,
104    run_id: Option<UUID4>,
105    venues: IndexMap<Venue, Rc<RefCell<SimulatedExchange>>>,
106    exec_clients: Vec<BacktestExecutionClient>,
107    has_data: AHashSet<InstrumentId>,
108    has_book_data: AHashSet<InstrumentId>,
109    has_book_processed: AHashSet<InstrumentId>,
110    data_iterator: BacktestDataIterator,
111    data_len: usize,
112    data_stream_counter: usize,
113    ts_first: Option<UnixNanos>,
114    ts_last_data: Option<UnixNanos>,
115    sorted: bool,
116    iteration: usize,
117    force_stop: bool,
118    last_ns: UnixNanos,
119    last_module_ns: Option<UnixNanos>,
120    last_liquidation_ns: Option<UnixNanos>,
121    end_ns: UnixNanos,
122    run_started: Option<UnixNanos>,
123    run_finished: Option<UnixNanos>,
124    backtest_start: Option<UnixNanos>,
125    backtest_end: Option<UnixNanos>,
126    funding_error: Option<String>,
127}
128
129impl Debug for BacktestEngine {
130    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
131        f.debug_struct(stringify!(BacktestEngine))
132            .field("instance_id", &self.instance_id)
133            .field("run_config_id", &self.run_config_id)
134            .field("run_id", &self.run_id)
135            .finish_non_exhaustive()
136    }
137}
138
139impl BacktestEngine {
140    /// Create a new [`BacktestEngine`] instance.
141    ///
142    /// # Errors
143    ///
144    /// Returns an error if the core `NautilusKernel` fails to initialize.
145    pub fn new(mut config: BacktestEngineConfig) -> anyhow::Result<Self> {
146        // The engine does not replay `add_instrument` on reset, so reruns rely
147        // on the cache retaining instruments regardless of the caller's config.
148        let mut cache_config = config.cache.unwrap_or_default();
149        cache_config.drop_instruments_on_reset = false;
150        config.cache = Some(cache_config);
151
152        let kernel = NautilusKernel::new("BacktestEngine".to_string(), config.clone())?;
153        let instance_id = kernel.instance_id;
154
155        #[cfg(feature = "python")]
156        if let Some(controller) = config.controller.as_ref() {
157            Trader::add_controller_from_importable_config(&kernel.trader, controller)?;
158        }
159        #[cfg(not(feature = "python"))]
160        if let Some(controller) = config.controller.as_ref() {
161            anyhow::bail!(
162                "BacktestEngineConfig.controller for importable controller '{}' requires the python feature",
163                controller.controller_path
164            );
165        }
166
167        Ok(Self {
168            kernel,
169            instance_id,
170            config,
171            accumulator: TimeEventAccumulator::new(),
172            run_config_id: None,
173            run_id: None,
174            venues: IndexMap::new(),
175            exec_clients: Vec::new(),
176            has_data: AHashSet::new(),
177            has_book_data: AHashSet::new(),
178            has_book_processed: AHashSet::new(),
179            data_iterator: BacktestDataIterator::new(),
180            data_len: 0,
181            data_stream_counter: 0,
182            ts_first: None,
183            ts_last_data: None,
184            sorted: true,
185            iteration: 0,
186            force_stop: false,
187            last_ns: UnixNanos::default(),
188            last_module_ns: None,
189            last_liquidation_ns: None,
190            end_ns: UnixNanos::default(),
191            run_started: None,
192            run_finished: None,
193            backtest_start: None,
194            backtest_end: None,
195            funding_error: None,
196        })
197    }
198
199    /// Returns a reference to the underlying kernel.
200    #[must_use]
201    pub const fn kernel(&self) -> &NautilusKernel {
202        &self.kernel
203    }
204
205    /// Returns a mutable reference to the underlying kernel.
206    pub fn kernel_mut(&mut self) -> &mut NautilusKernel {
207        &mut self.kernel
208    }
209
210    /// Returns the trader ID for this engine.
211    #[must_use]
212    pub fn trader_id(&self) -> TraderId {
213        self.kernel.trader_id()
214    }
215
216    /// Returns the machine ID for this engine.
217    #[must_use]
218    pub fn machine_id(&self) -> &str {
219        self.kernel.machine_id()
220    }
221
222    /// Returns the unique instance ID for this engine.
223    #[must_use]
224    pub fn instance_id(&self) -> UUID4 {
225        self.instance_id
226    }
227
228    /// Returns the current iteration count.
229    #[must_use]
230    pub fn iteration(&self) -> usize {
231        self.iteration
232    }
233
234    /// Returns the last run config ID, if any.
235    #[must_use]
236    pub fn run_config_id(&self) -> Option<&str> {
237        self.run_config_id.as_deref()
238    }
239
240    /// Returns the last run ID, if any.
241    #[must_use]
242    pub const fn run_id(&self) -> Option<UUID4> {
243        self.run_id
244    }
245
246    /// Returns when the last run started, if any.
247    #[must_use]
248    pub const fn run_started(&self) -> Option<UnixNanos> {
249        self.run_started
250    }
251
252    /// Returns when the last run finished, if any.
253    #[must_use]
254    pub const fn run_finished(&self) -> Option<UnixNanos> {
255        self.run_finished
256    }
257
258    /// Returns the last backtest range start, if any.
259    #[must_use]
260    pub const fn backtest_start(&self) -> Option<UnixNanos> {
261        self.backtest_start
262    }
263
264    /// Returns the last backtest range end, if any.
265    #[must_use]
266    pub const fn backtest_end(&self) -> Option<UnixNanos> {
267        self.backtest_end
268    }
269
270    /// Returns the list of registered venue identifiers.
271    #[must_use]
272    pub fn list_venues(&self) -> Vec<Venue> {
273        self.venues.keys().copied().collect()
274    }
275
276    /// # Errors
277    ///
278    /// Returns an error if the venue is already registered, initializing the simulated exchange
279    /// fails, or registering its execution client fails.
280    pub fn add_venue(&mut self, config: SimulatedVenueConfig) -> anyhow::Result<()> {
281        // `routing` and `frozen_account` flow to the exec client, so capture
282        // them before the config is consumed by the exchange constructor.
283        let venue = config.venue;
284        if self.venues.contains_key(&venue) {
285            anyhow::bail!("Venue {venue} is already registered");
286        }
287
288        let routing = Some(config.routing);
289        let frozen_account = Some(config.frozen_account);
290        let use_message_queue = config.use_message_queue;
291
292        let exchange =
293            SimulatedExchange::new(config, self.kernel.cache.clone(), self.kernel.clock.clone())?;
294        let exchange = Rc::new(RefCell::new(exchange));
295
296        let account_id = AccountId::from(format!("{venue}-001").as_str());
297
298        let exec_client = BacktestExecutionClient::new(
299            self.config.trader_id(),
300            account_id,
301            &exchange,
302            self.kernel.cache.clone(),
303            self.kernel.clock.clone(),
304            routing,
305            frozen_account,
306        );
307
308        if !use_message_queue {
309            exchange
310                .borrow_mut()
311                .set_event_handler(exec_client.order_event_handler());
312        }
313
314        exchange
315            .borrow_mut()
316            .register_client(Rc::new(exec_client.clone()));
317
318        {
319            let mut exec_engine = self.kernel.exec_engine.borrow_mut();
320            let client_id = exec_client.client_id();
321            exec_engine.register_client(Box::new(exec_client.clone()))?;
322            if let Err(e) = exec_engine.register_venue_routing(client_id, venue) {
323                exec_engine.deregister_client(client_id)?;
324                return Err(e);
325            }
326        }
327
328        SimulatedExchange::register_spread_quote_endpoint(&exchange);
329        self.venues.insert(venue, exchange);
330        self.exec_clients.push(exec_client);
331
332        log::info!("Adding exchange {venue} to engine");
333
334        Ok(())
335    }
336
337    /// Changes the fill model for the specified venue.
338    pub fn change_fill_model(&mut self, venue: Venue, fill_model: FillModelHandle) {
339        if let Some(exchange) = self.venues.get_mut(&venue) {
340            exchange.borrow_mut().set_fill_model(fill_model);
341        } else {
342            log::warn!(
343                "BacktestEngine::change_fill_model called for unknown venue {venue}, ignoring"
344            );
345        }
346    }
347
348    /// Adds an instrument to the backtest engine for the specified venue.
349    ///
350    /// Adding an instrument that is already registered with the same definition is a
351    /// no-op. Event timestamps are ignored when comparing definitions.
352    ///
353    /// # Errors
354    ///
355    /// Returns an error if:
356    /// - The instrument's associated venue has not been added via `add_venue`.
357    /// - An instrument with the same ID is already registered with a different definition.
358    /// - Attempting to add a `CurrencyPair` instrument for a single-currency CASH account.
359    pub fn add_instrument(&mut self, instrument: &InstrumentAny) -> anyhow::Result<()> {
360        let instrument_id = instrument.id();
361        if let Some(exchange) = self.venues.get(&instrument.id().venue) {
362            if exchange.borrow().is_instrument_registered(instrument)? {
363                log::debug!("Instrument {instrument_id} is already registered");
364                return Ok(());
365            }
366
367            if matches!(
368                instrument,
369                InstrumentAny::CurrencyPair(_) | InstrumentAny::TokenizedAsset(_)
370            ) && exchange.borrow().account_type != AccountType::Margin
371                && exchange.borrow().base_currency.is_some()
372            {
373                anyhow::bail!(
374                    "Cannot add a multi-currency spot instrument {instrument_id} for a venue with a single-currency CASH account"
375                )
376            }
377            exchange.borrow_mut().add_instrument(instrument.clone())?;
378            if let Some(expiration_ns) = instrument.expiration_ns() {
379                self.set_instrument_expiration_timer(exchange, instrument_id, expiration_ns)?;
380            }
381        } else {
382            anyhow::bail!(
383                "Cannot add an `Instrument` object without first adding its associated venue {}",
384                instrument.id().venue
385            )
386        }
387
388        self.add_market_data_client_if_not_exists(instrument.id().venue);
389
390        self.kernel
391            .data_engine
392            .borrow_mut()
393            .process(instrument as &dyn Any);
394        log::info!(
395            "Added instrument {} to exchange {}",
396            instrument_id,
397            instrument_id.venue
398        );
399        Ok(())
400    }
401
402    /// Adds data to the engine for replay during the backtest run.
403    ///
404    /// # Errors
405    ///
406    /// Returns an error if:
407    /// - `data` is empty.
408    /// - `data` contains DeFi data and this crate is built without its `defi` feature.
409    /// - `validate` is `true`, the first element is built-in market data (excluding
410    ///   custom and DeFi data), and its instrument has not been added to the cache via
411    ///   [`add_instrument`](Self::add_instrument).
412    /// - `validate` is `true` and the first element is a [`Data::Bar`] whose
413    ///   `aggregation_source` is not [`AggregationSource::External`].
414    pub fn add_data(
415        &mut self,
416        mut data: Vec<Data>,
417        client_id: Option<ClientId>,
418        validate: bool,
419        sort: bool,
420    ) -> anyhow::Result<()> {
421        if sort {
422            data.sort_by_key(HasTsInit::ts_init);
423        }
424
425        let stream_name =
426            self.register_added_data(data.iter().map(DataRef::from), client_id, validate)?;
427        self.data_iterator.add_data(&stream_name, data, true);
428        self.sorted = sort;
429
430        Ok(())
431    }
432
433    /// Adds a typed data batch to the engine for replay during the backtest run.
434    ///
435    /// The batch keeps its typed storage through replay, so no per-item [`Data`] value is
436    /// constructed. Items are ordered by replay key as the batch is added; `sort` records whether
437    /// the engine may run, matching [`add_data`](Self::add_data).
438    ///
439    /// # Errors
440    ///
441    /// Returns an error if [`add_data`](Self::add_data) fails.
442    pub fn add_data_batch(
443        &mut self,
444        data: DataBatch,
445        client_id: Option<ClientId>,
446        validate: bool,
447        sort: bool,
448    ) -> anyhow::Result<()> {
449        let stream_name = self.register_added_data(
450            (0..data.len()).filter_map(|index| data.get(index)),
451            client_id,
452            validate,
453        )?;
454        self.data_iterator.add_data_batch(&stream_name, data, true);
455        self.sorted = sort;
456
457        Ok(())
458    }
459
460    fn register_added_data<'a>(
461        &mut self,
462        items: impl Iterator<Item = DataRef<'a>> + Clone,
463        client_id: Option<ClientId>,
464        validate: bool,
465    ) -> anyhow::Result<String> {
466        #[cfg(not(feature = "defi"))]
467        let _ = client_id;
468
469        let Some(first) = items.clone().next() else {
470            anyhow::bail!("data was empty");
471        };
472
473        #[cfg(not(feature = "defi"))]
474        anyhow::ensure!(
475            !items.clone().any(is_defi),
476            "DeFi data requires the nautilus-backtest `defi` feature"
477        );
478
479        if validate {
480            // Validate against the first element only and assume the batch is
481            // homogeneous (documented contract on add_data).
482            if !is_defi(first) && !matches!(first, DataRef::Custom(_)) {
483                let first_instrument_id = first.instrument_id();
484                anyhow::ensure!(
485                    self.kernel
486                        .cache
487                        .borrow()
488                        .instrument(&first_instrument_id)
489                        .is_some(),
490                    "Instrument {first_instrument_id} for the given data not found in the cache. \
491                     Add the instrument through `add_instrument()` prior to adding related data."
492                );
493
494                if let DataRef::Bar(bar) = first {
495                    anyhow::ensure!(
496                        bar.bar_type.aggregation_source() == AggregationSource::External,
497                        "bar_type.aggregation_source must be External, was {:?}",
498                        bar.bar_type.aggregation_source(),
499                    );
500                }
501            }
502        }
503
504        // Track has_data / has_book_data unconditionally so the depth-vs-data
505        // run-time check still fires for callers that pass validate=false
506        // (e.g. node.rs run_oneshot loading from a catalog). Time bounds are
507        // also tracked here so start/end defaults are correct even when the
508        // batch was added with sort=false.
509        let mut count = 0;
510        let mut batch_min_ts: Option<UnixNanos> = None;
511        let mut batch_max_ts: Option<UnixNanos> = None;
512
513        #[cfg(feature = "defi")]
514        if items.clone().any(is_defi) {
515            self.add_defi_data_client_if_not_exists(client_id);
516        }
517
518        for item in items {
519            count += 1;
520            let ts = item.ts_init();
521            batch_min_ts = Some(batch_min_ts.map_or(ts, |cur| cur.min(ts)));
522            batch_max_ts = Some(batch_max_ts.map_or(ts, |cur| cur.max(ts)));
523
524            if is_defi(item) {
525                continue;
526            }
527
528            if matches!(item, DataRef::Custom(_)) {
529                // Custom data routes by DataType and is independent of market venue bookkeeping.
530                continue;
531            }
532
533            let instr_id = item.instrument_id();
534            self.has_data.insert(instr_id);
535
536            if item.is_order_book_data() {
537                self.has_book_data.insert(instr_id);
538            }
539
540            self.add_market_data_client_if_not_exists(instr_id.venue);
541        }
542
543        if let Some(ts) = batch_min_ts
544            && self.ts_first.is_none_or(|t| ts < t)
545        {
546            self.ts_first = Some(ts);
547        }
548
549        if let Some(ts) = batch_max_ts
550            && self.ts_last_data.is_none_or(|t| ts > t)
551        {
552            self.ts_last_data = Some(ts);
553        }
554
555        self.data_len += count;
556        let stream_name = format!("backtest_data_{}", self.data_stream_counter);
557        self.data_stream_counter += 1;
558
559        log::info!(
560            "Added {count} data element{} to BacktestEngine ({} total)",
561            if count == 1 { "" } else { "s" },
562            self.data_len,
563        );
564
565        Ok(stream_name)
566    }
567
568    /// Adds an actor to the backtest engine.
569    ///
570    /// # Errors
571    ///
572    /// Returns an error if the actor is already registered or the trader is in an invalid
573    /// state for actor registration.
574    pub fn add_actor<T>(&mut self, actor: T) -> anyhow::Result<()>
575    where
576        T: DataActor + DataActorNative + Component + Debug + 'static,
577    {
578        self.kernel.trader.borrow_mut().add_actor(actor)
579    }
580
581    /// Adds the given actors to the backtest engine. Stops at the first error.
582    ///
583    /// # Errors
584    ///
585    /// Returns an error if any actor fails to register; preceding actors remain registered.
586    pub fn add_actors<T>(&mut self, actors: Vec<T>) -> anyhow::Result<()>
587    where
588        T: DataActor + DataActorNative + Component + Debug + 'static,
589    {
590        for actor in actors {
591            self.add_actor(actor)?;
592        }
593        Ok(())
594    }
595
596    /// Adds a strategy to the backtest engine.
597    ///
598    /// # Errors
599    ///
600    /// Returns an error if the strategy is already registered or the trader is in an invalid
601    /// state for strategy registration.
602    pub fn add_strategy<T>(&mut self, mut strategy: T) -> anyhow::Result<()>
603    where
604        T: Strategy + StrategyNative + DataActorNative + Component + Debug + 'static,
605    {
606        let strategy_id = self
607            .kernel
608            .trader
609            .borrow()
610            .prepare_strategy_for_registration(&mut strategy)?;
611        let oms_type = StrategyNative::strategy_core(&strategy).config.oms_type;
612
613        self.kernel.trader.borrow_mut().add_strategy(strategy)?;
614
615        if let Some(oms_type) = oms_type {
616            self.kernel
617                .exec_engine
618                .borrow_mut()
619                .register_oms_type(strategy_id, oms_type);
620        }
621
622        Ok(())
623    }
624
625    /// Adds the given strategies to the backtest engine. Stops at the first error.
626    ///
627    /// # Errors
628    ///
629    /// Returns an error if any strategy fails to register; preceding strategies remain registered.
630    pub fn add_strategies<T>(&mut self, strategies: Vec<T>) -> anyhow::Result<()>
631    where
632        T: Strategy + StrategyNative + DataActorNative + Component + Debug + 'static,
633    {
634        for strategy in strategies {
635            self.add_strategy(strategy)?;
636        }
637        Ok(())
638    }
639
640    /// Adds an execution algorithm to the backtest engine.
641    ///
642    /// # Errors
643    ///
644    /// Returns an error if the algorithm is already registered or the trader is running.
645    pub fn add_exec_algorithm<T>(&mut self, exec_algorithm: T) -> anyhow::Result<()>
646    where
647        T: ExecutionAlgorithm + ExecutionAlgorithmNative + Component + Debug + 'static,
648    {
649        self.kernel
650            .trader
651            .borrow_mut()
652            .add_exec_algorithm(exec_algorithm)
653    }
654
655    /// Adds the given execution algorithms to the backtest engine. Stops at the first error.
656    ///
657    /// # Errors
658    ///
659    /// Returns an error if any execution algorithm fails to register; preceding algorithms remain
660    /// registered.
661    pub fn add_exec_algorithms<T>(&mut self, exec_algorithms: Vec<T>) -> anyhow::Result<()>
662    where
663        T: ExecutionAlgorithm + ExecutionAlgorithmNative + Component + Debug + 'static,
664    {
665        for exec_algorithm in exec_algorithms {
666            self.add_exec_algorithm(exec_algorithm)?;
667        }
668        Ok(())
669    }
670
671    /// Run a backtest.
672    ///
673    /// Processes all data chronologically. When `streaming` is false (default),
674    /// finalizes the run via [`end`](Self::end). When `streaming` is true, the
675    /// run pauses without finalizing so additional data batches can be loaded.
676    /// Timer advancement stops at data exhaustion to avoid producing synthetic
677    /// events (e.g. zero-volume bars) past the current batch.
678    ///
679    /// Each streaming batch must include every data item with its final `ts_init`;
680    /// splitting one replay timestamp across calls can finalize timers and venue
681    /// modules before later items at that timestamp. [`BacktestNode`](crate::node::BacktestNode)
682    /// aligns its chunks to this boundary.
683    ///
684    /// Streaming workflow:
685    /// 1. Add initial data and strategies
686    /// 2. Loop: call `run(streaming=true)`, `clear_data()`, `add_data(next_batch)`
687    /// 3. After all batches: call `end()` to finalize
688    ///
689    /// # Errors
690    ///
691    /// Returns an error if the backtest encounters an unrecoverable state.
692    /// Callback dispatch failures abort the run and stop the trader and engines, including when
693    /// a failure is already latched before entry. An account rejecting a fill's balance update,
694    /// such as a cash balance going negative without borrowing, also aborts the run.
695    pub fn run(
696        &mut self,
697        start: Option<UnixNanos>,
698        end: Option<UnixNanos>,
699        run_config_id: Option<String>,
700        streaming: bool,
701    ) -> anyhow::Result<()> {
702        if let Some(error) = actor::callback_failure() {
703            self.abort_run();
704            return Err(error.into());
705        }
706
707        if let Some(error) = &self.funding_error {
708            anyhow::bail!("{error}");
709        }
710
711        if let Err(e) = self.check_exchange_errors() {
712            self.abort_run();
713            return Err(e);
714        }
715
716        self.check_balance_error()?;
717
718        if let Err(e) = self.run_impl(start, end, run_config_id, streaming) {
719            let callback_error = actor::callback_failure();
720            if callback_error.is_some()
721                || e.is::<CallbackDispatchError>()
722                || self.funding_error.is_some()
723                || self.kernel.portfolio.borrow().balance_error().is_some()
724                || self
725                    .venues
726                    .values()
727                    .any(|exchange| exchange.borrow().has_callback_error())
728            {
729                self.abort_run();
730            }
731            return Err(match callback_error {
732                Some(callback_error) if !e.is::<CallbackDispatchError>() => {
733                    let message = format!("Callback dispatch failed: {callback_error}; {e:#}");
734                    e.context(message)
735                }
736                _ => e,
737            });
738        }
739
740        // Finalize on non-streaming runs, or when a shutdown was triggered
741        // at any point during the run (including the trailing settle, module,
742        // and flush callbacks that execute after the main data loop) so the
743        // trader and engines actually stop.
744        // Streaming batches retain commands deferred by other instruments,
745        // and end() performs the unrestricted drain after all batches are loaded.
746        if !streaming || self.force_stop || self.kernel.is_shutdown_requested() {
747            self.end()?;
748        }
749
750        Ok(())
751    }
752
753    fn run_impl(
754        &mut self,
755        start: Option<UnixNanos>,
756        end: Option<UnixNanos>,
757        run_config_id: Option<String>,
758        streaming: bool,
759    ) -> anyhow::Result<()> {
760        anyhow::ensure!(
761            self.sorted,
762            "Data has been added but not sorted, call `engine.sort_data()` or use \
763             `engine.add_data(..., sort=true)` before running"
764        );
765
766        for exchange in self.venues.values() {
767            let exchange = exchange.borrow();
768            let book_type_has_depth = exchange.book_type() as u8 > BookType::L1_MBP as u8;
769            if !book_type_has_depth {
770                continue;
771            }
772
773            for instrument_id in exchange.instrument_ids() {
774                let has_data = self.has_data.contains(instrument_id);
775                let missing_book_data = !self.has_book_data.contains(instrument_id)
776                    && !self.has_book_processed.contains(instrument_id);
777
778                if has_data && missing_book_data {
779                    anyhow::bail!(
780                        "No order book data found for instrument '{instrument_id}' when `book_type` \
781                         is '{:?}'. Set the venue `book_type` to 'L1_MBP' (for top-of-book data \
782                         like quotes, trades, and bars) or provide order book data for this \
783                         instrument.",
784                        exchange.book_type()
785                    );
786                }
787            }
788        }
789
790        // Determine time boundaries
791        let start_ns = start.unwrap_or_else(|| self.ts_first.unwrap_or_default());
792        let end_ns = end.unwrap_or_else(|| self.ts_last_data.unwrap_or(start_ns));
793        anyhow::ensure!(start_ns <= end_ns, "start was > end");
794        self.end_ns = end_ns;
795        self.last_ns = start_ns;
796        self.last_module_ns = None;
797
798        // Set all component clocks to start
799        let clocks = self.collect_all_clocks();
800        Self::set_all_clocks_time(&clocks, start_ns);
801
802        if self.run_id.is_none() {
803            self.set_instrument_expiration_timers()?;
804
805            self.run_config_id = run_config_id;
806            self.run_id = Some(UUID4::new());
807            self.run_started = Some(UnixNanos::from(nanos_since_unix_epoch()));
808            self.backtest_start = Some(start_ns);
809
810            for exchange in self.venues.values() {
811                let mut ex = exchange.borrow_mut();
812                ex.initialize_account();
813                ex.load_open_orders();
814            }
815
816            // Re-set clocks after account init
817            Self::set_all_clocks_time(&clocks, start_ns);
818
819            // Reset force stop flag
820            self.force_stop = false;
821            self.kernel.reset_shutdown_flag();
822
823            // Initialize sync command senders (once per thread)
824            Self::init_command_senders();
825
826            // Set logging to static clock mode for deterministic timestamps
827            logging_clock_set_static_mode();
828            logging_clock_set_static_time(start_ns.as_u64());
829
830            // Start kernel, then stop before trader startup for event-store replay
831            self.kernel.start();
832            if self.kernel.is_event_store_replay() {
833                self.log_pre_run();
834                return Ok(());
835            }
836
837            if self.kernel.is_event_store_replay_configured() {
838                anyhow::bail!("event-store replay did not start");
839            }
840
841            if let Err(e) = self.kernel.start_trader() {
842                // Callback failures use run's outer abort path
843                if actor::callback_failure().is_none() && !e.is::<CallbackDispatchError>() {
844                    self.abort_run();
845                }
846                return Err(e);
847            }
848
849            // Drain on_start data subscriptions so aggregators subscribe before the first data
850            // point, else internal aggregation drops the first tick. Trading/exec stay queued
851            loop {
852                drain_data_cmd_queue();
853                let callbacks_pending = actor::drain_callbacks(CALLBACK_DRAIN_BUDGET)?;
854                if data_cmd_queue_is_empty() && !callbacks_pending {
855                    break;
856                }
857            }
858
859            self.log_pre_run();
860        }
861
862        self.log_run();
863
864        // Skip data before start_ns
865        while let Some(d) = self.data_iterator.peek() {
866            if d.ts_init() >= start_ns {
867                break;
868            }
869            self.data_iterator.advance();
870        }
871
872        // Initialize last_ns before first data point
873        if let Some(d) = self.data_iterator.peek() {
874            let ts = d.ts_init();
875            self.last_ns = ts.saturating_sub(DurationNanos::new(1));
876        } else {
877            self.last_ns = start_ns;
878        }
879
880        loop {
881            if self.kernel.is_shutdown_requested() {
882                log::info!("Shutdown requested via ShutdownSystem, ending backtest");
883                self.force_stop = true;
884            }
885
886            if self.force_stop {
887                log::info!("Force stop triggered, ending backtest");
888                break;
889            }
890
891            let Some(data) = self.data_iterator.peek() else {
892                if streaming {
893                    // In streaming mode, don't advance timers past the
894                    // current batch. The next batch will provide more data
895                    // and timers will fire naturally as time advances.
896                    break;
897                }
898
899                let done = self.process_next_timer()?;
900                if self.data_iterator.peek().is_none() && done {
901                    break;
902                }
903                continue;
904            };
905
906            let ts_init = data.ts_init();
907
908            if ts_init > end_ns {
909                break;
910            }
911
912            if ts_init > self.last_ns {
913                self.advance_time_impl(ts_init)?;
914            }
915
916            // A timer fired during clock advance may have requested shutdown,
917            // skip delivering this data point in that case
918            if self.kernel.is_shutdown_requested() {
919                self.force_stop = true;
920                break;
921            }
922
923            let settlement_scope = {
924                let Some(mut data) = self.data_iterator.peek() else {
925                    continue;
926                };
927                let settlement_scope = Self::settlement_scope(data);
928
929                if let DataRef::Instrument(instrument) = data
930                    && let Some(exchange) = self.venues.get(&instrument.id().venue)
931                {
932                    let instrument_id = instrument.id();
933                    let mut exchange_ref = exchange.borrow_mut();
934                    let previous_expiration = exchange_ref
935                        .get_matching_engine(&instrument_id)
936                        .and_then(|engine| engine.instrument.expiration_ns());
937                    exchange_ref.set_clock_time(ts_init);
938                    exchange_ref.update_instrument(instrument)?;
939
940                    if let Some(previous) = previous_expiration
941                        && Some(previous) != instrument.expiration_ns()
942                        && !exchange_ref
943                            .instrument_expirations()
944                            .iter()
945                            .any(|(_, ns)| *ns == previous)
946                    {
947                        let name =
948                            Self::instrument_expiration_timer_name(instrument_id.venue, previous);
949                        self.kernel.clock.borrow_mut().cancel_timer(&name);
950                        self.accumulator.cancel_timer(&name);
951                    }
952
953                    if let Some(expiration_ns) = instrument.expiration_ns()
954                        && expiration_ns >= ts_init
955                        && let Some(engine) = exchange_ref.get_matching_engine(&instrument_id)
956                        && !engine.is_expiration_processed()
957                    {
958                        self.set_instrument_expiration_timer(
959                            exchange,
960                            instrument_id,
961                            expiration_ns,
962                        )?;
963                    }
964
965                    // End the iterator borrow while scheduling, then reborrow the same row
966                    data = self.data_iterator.peek().expect("replay row exists");
967                }
968
969                Self::route_data_to_exchange(
970                    &self.venues,
971                    &mut self.has_book_processed,
972                    &self.kernel.clock,
973                    data,
974                )?;
975                self.kernel.data_engine.borrow_mut().process_data_ref(data);
976                settlement_scope
977            };
978            self.data_iterator.advance();
979
980            // Drain deferred commands, then process exchange queues
981            self.drain_command_queues()?;
982            self.settle_venues(ts_init, settlement_scope)?;
983
984            let prev_last_ns = self.last_ns;
985
986            // If timestamp changed (or exhausted), flush timers then run modules
987            if self
988                .data_iterator
989                .peek()
990                .is_none_or(|next| next.ts_init() > prev_last_ns)
991            {
992                self.flush_accumulator_events(prev_last_ns)?;
993                self.finalize_timestamp(prev_last_ns, settlement_scope)?;
994            }
995
996            self.iteration += 1;
997        }
998
999        if !streaming || self.force_stop || self.kernel.is_shutdown_requested() {
1000            let ts_now = self.kernel.clock.borrow().timestamp_ns();
1001            self.finalize_timestamp(ts_now, SettlementScope::All)?;
1002        }
1003
1004        // Cap at last_ns when streaming or after shutdown to avoid firing
1005        // timers past the current batch or the graceful stop
1006        let flush_ts = if streaming || self.force_stop || self.kernel.is_shutdown_requested() {
1007            self.last_ns
1008        } else {
1009            end_ns
1010        };
1011
1012        self.flush_accumulator_events(flush_ts)?;
1013
1014        Ok(())
1015    }
1016
1017    fn settlement_scope(data: DataRef<'_>) -> SettlementScope {
1018        match data {
1019            DataRef::BookDelta(_)
1020            | DataRef::BookDeltas(_)
1021            | DataRef::BookDepth(_)
1022            | DataRef::Quote(_)
1023            | DataRef::Trade(_)
1024            | DataRef::Bar(_)
1025            | DataRef::MarkPrice(_) => SettlementScope::Data(Some(data.instrument_id())),
1026            DataRef::IndexPrice(_) => SettlementScope::Data(None),
1027            DataRef::FundingRate(_) => SettlementScope::Data(Some(data.instrument_id())),
1028            DataRef::OptionGreeks(_) => SettlementScope::Data(None),
1029            DataRef::InstrumentStatus(_) | DataRef::InstrumentClose(_) => {
1030                SettlementScope::Data(Some(data.instrument_id()))
1031            }
1032            DataRef::Instrument(_) | DataRef::Custom(_) => SettlementScope::Data(None),
1033            #[cfg(feature = "defi")]
1034            DataRef::Defi(_) => SettlementScope::Data(None),
1035            #[cfg(not(feature = "defi"))]
1036            #[allow(
1037                unreachable_patterns,
1038                reason = "DeFi variants can exist without this crate's defi feature"
1039            )]
1040            _ => SettlementScope::Data(None),
1041        }
1042    }
1043
1044    fn abort_run(&mut self) {
1045        self.force_stop = true;
1046        self.accumulator.clear();
1047        self.kernel.stop_trader();
1048        self.kernel.data_engine.borrow_mut().stop();
1049        self.kernel.risk_engine.borrow_mut().stop();
1050        self.kernel.exec_engine.borrow_mut().stop();
1051        clear_command_queues();
1052
1053        if let Err(e) = actor::clear_callbacks() {
1054            log::error!("Failed to clear callback dispatch while aborting backtest: {e}");
1055        }
1056        self.run_finished = Some(UnixNanos::from(nanos_since_unix_epoch()));
1057        self.backtest_end = Some(self.kernel.clock.borrow().timestamp_ns());
1058        logging_clock_set_realtime_mode();
1059    }
1060
1061    /// Manually ends the backtest.
1062    ///
1063    /// # Errors
1064    ///
1065    /// Returns an error if callback dispatch or ownership cleanup fails, an account rejects a
1066    /// fill's balance update, collecting component state fails, the cache backing reports a DeFi
1067    /// currency integrity error, or a simulation module cannot produce its diagnostics. Callback
1068    /// errors and balance rejections trigger abort cleanup, stopping the trader and engines.
1069    pub fn end(&mut self) -> anyhow::Result<()> {
1070        let result = self.end_impl();
1071        if let Err(e) = &result
1072            && (e.is::<CallbackDispatchError>()
1073                || self.kernel.portfolio.borrow().balance_error().is_some()
1074                || self
1075                    .venues
1076                    .values()
1077                    .any(|exchange| exchange.borrow().has_callback_error()))
1078        {
1079            self.abort_run();
1080        }
1081        result
1082    }
1083
1084    fn end_impl(&mut self) -> anyhow::Result<()> {
1085        if let Some(error) = actor::callback_failure() {
1086            return Err(error.into());
1087        }
1088
1089        if let Some(error) = &self.funding_error {
1090            anyhow::bail!("{error}");
1091        }
1092        self.check_balance_error()?;
1093
1094        // Flush remaining timer events to the backtest end boundary so that
1095        // tail alerts/expiries scheduled after the last data point still fire.
1096        // Must run before stopping engines since DataEngine::stop() cancels
1097        // bar aggregator timers. When a shutdown was requested, cap the flush
1098        // at the last processed timestamp so timers scheduled past the stop
1099        // point do not fire extra callbacks after the graceful stop request.
1100        if self.end_ns.as_u64() > 0 {
1101            let flush_ts = if self.force_stop || self.kernel.is_shutdown_requested() {
1102                self.last_ns
1103            } else {
1104                self.end_ns
1105            };
1106
1107            if let Err(e) = self.flush_accumulator_events(flush_ts) {
1108                if self.funding_error.is_some()
1109                    || self
1110                        .venues
1111                        .values()
1112                        .any(|exchange| exchange.borrow().has_callback_error())
1113                {
1114                    self.abort_run();
1115                }
1116                return Err(e);
1117            }
1118        }
1119
1120        // Settle commands already due at the final data timestamp while strategies
1121        // are still running, so callbacks and on_stop observe the final state.
1122        let mut ts_now = self.kernel.clock.borrow().timestamp_ns();
1123        self.settle_venues(ts_now, SettlementScope::All)?;
1124
1125        self.kernel.stop_trader();
1126
1127        // Settle residual on_stop commands before stopping engines. Venue modules are
1128        // not re-run; process_modules is once per timestamp.
1129
1130        // Drain first so latency-deferred commands reach venue inflight queues
1131        self.drain_command_queues()?;
1132
1133        // Advance the clock to the latest inflight arrival; otherwise commands deferred
1134        // by a LatencyModel sit past ts_now and never settle.
1135        if let Some(max_inflight_ts) = self.max_inflight_command_ts()
1136            && max_inflight_ts > ts_now
1137        {
1138            ts_now = max_inflight_ts;
1139            let clocks = self.collect_all_clocks();
1140            Self::set_all_clocks_time(&clocks, ts_now);
1141        }
1142
1143        self.settle_venues(ts_now, SettlementScope::All)?;
1144
1145        for strategy_id in self.running_strategy_ids() {
1146            log::error!(
1147                "Strategy {strategy_id} is still RUNNING after the backtest end sequence; its stop did not complete",
1148            );
1149        }
1150
1151        let save_result = self.kernel.save_trader_state();
1152        let callback_result = self.drain_command_queues();
1153        let diagnostics_result = self
1154            .venues
1155            .values()
1156            .try_for_each(|exchange| exchange.borrow().log_diagnostics());
1157        self.kernel.portfolio.borrow_mut().finalize_equity_curve();
1158
1159        // Stop engines
1160        self.kernel.data_engine.borrow_mut().stop();
1161        self.kernel.risk_engine.borrow_mut().stop();
1162        self.kernel.exec_engine.borrow_mut().stop();
1163
1164        let streaming_result = self.kernel.close_streaming_writer();
1165
1166        self.run_finished = Some(UnixNanos::from(nanos_since_unix_epoch()));
1167        self.backtest_end = Some(self.kernel.clock.borrow().timestamp_ns());
1168
1169        // Switch logging back to realtime mode
1170        logging_clock_set_realtime_mode();
1171
1172        self.log_post_run();
1173        callback_result?;
1174        actor::clear_callbacks()?;
1175        save_result?;
1176        diagnostics_result?;
1177        streaming_result
1178    }
1179
1180    /// Returns registered strategies whose state resolves to `Running` after the end sequence.
1181    ///
1182    /// Known causes include a stop deferred for a managed market exit that never completed,
1183    /// and an earlier component stop failure making `Trader::stop_components` return before
1184    /// reaching the strategy - so callers must report the state observed rather than
1185    /// attribute a cause.
1186    fn running_strategy_ids(&self) -> Vec<StrategyId> {
1187        self.kernel
1188            .trader
1189            .borrow()
1190            .strategy_ids()
1191            .into_iter()
1192            .filter(|strategy_id| match component_state(&strategy_id.inner()) {
1193                Ok(state) => matches!(state, ComponentState::Running),
1194                Err(e) => {
1195                    log::warn!("Cannot resolve stop state for strategy {strategy_id}: {e}");
1196                    false
1197                }
1198            })
1199            .collect()
1200    }
1201
1202    /// Resets the backtest engine.
1203    ///
1204    /// All stateful fields are reset to their initial value. Data and instruments
1205    /// persist across resets to enable repeated runs with different strategies.
1206    /// The trader must be initialized before reset, normally by running the engine.
1207    ///
1208    /// # Errors
1209    ///
1210    /// Returns an error if ending the run, resetting a venue or trader, reopening the streaming
1211    /// writer, or clearing callback ownership fails. The engine attempts the remaining cleanup
1212    /// steps before returning the first error.
1213    pub fn reset(&mut self) -> anyhow::Result<()> {
1214        log::debug!("Resetting");
1215
1216        let mut reset_error = None;
1217
1218        if self.kernel.trader.borrow().is_running()
1219            && let Err(e) = self.end()
1220        {
1221            reset_error = Some(e);
1222        }
1223
1224        // Stop and reset engines
1225        self.kernel.data_engine.borrow_mut().stop();
1226        self.kernel.data_engine.borrow_mut().reset();
1227
1228        self.kernel.exec_engine.borrow_mut().stop();
1229
1230        // Reset exchanges before the exec engine wipes the cache so
1231        // exchange.reset() can see the prior run's account.
1232        for exchange in self.venues.values() {
1233            if let Err(e) = exchange.borrow_mut().reset()
1234                && reset_error.is_none()
1235            {
1236                reset_error = Some(e);
1237            }
1238        }
1239        self.kernel.exec_engine.borrow_mut().reset();
1240
1241        self.kernel.risk_engine.borrow_mut().stop();
1242        self.kernel.risk_engine.borrow_mut().reset();
1243
1244        self.kernel.order_emulator.reset();
1245
1246        // Reset trader
1247        if let Err(e) = self.kernel.trader.borrow_mut().reset() {
1248            log::error!("Error resetting trader: {e:?}");
1249
1250            if reset_error.is_none() {
1251                reset_error = Some(e);
1252            }
1253        }
1254
1255        self.kernel.portfolio.borrow_mut().reset();
1256
1257        // Clear run state
1258        self.run_config_id = None;
1259        self.run_id = None;
1260        self.run_started = None;
1261        self.run_finished = None;
1262        self.backtest_start = None;
1263        self.backtest_end = None;
1264        self.funding_error = None;
1265        self.iteration = 0;
1266        self.force_stop = false;
1267        self.last_ns = UnixNanos::default();
1268        self.last_module_ns = None;
1269        self.last_liquidation_ns = None;
1270        self.end_ns = UnixNanos::default();
1271        self.has_book_processed.clear();
1272
1273        self.accumulator.clear();
1274        self.cancel_funding_settlement_timers();
1275
1276        // Reset all iterator cursors to beginning (data persists)
1277        self.data_iterator.reset_all_cursors();
1278
1279        // `end` closed the streaming writer, so the next run needs it open again
1280        if let Err(e) = self.kernel.reopen_streaming_writer()
1281            && reset_error.is_none()
1282        {
1283            reset_error = Some(e);
1284        }
1285
1286        clear_command_queues();
1287
1288        if let Err(e) = actor::clear_callbacks()
1289            && reset_error.is_none()
1290        {
1291            reset_error = Some(e.into());
1292        }
1293
1294        log::info!("Reset");
1295
1296        if let Some(e) = reset_error {
1297            return Err(e);
1298        }
1299        Ok(())
1300    }
1301
1302    /// Sort the engine's internal data stream by timestamp.
1303    ///
1304    /// Useful when data has been added with `sort=false` for batch performance,
1305    /// then sorted once before running.
1306    pub fn sort_data(&mut self) {
1307        // Each add call creates its own stream; the iterator merges streams by
1308        // replay timestamp across streams. Mark the engine as sorted so `run`
1309        // no longer rejects it.
1310        self.sorted = true;
1311        log::info!("Data sort requested (iterator merges streams by replay timestamp)");
1312    }
1313
1314    /// Clear the engine's internal data stream. Does not clear instruments.
1315    pub fn clear_data(&mut self) {
1316        self.has_data.clear();
1317        self.has_book_data.clear();
1318        self.data_iterator = BacktestDataIterator::new();
1319        self.data_len = 0;
1320        self.data_stream_counter = 0;
1321        self.ts_first = None;
1322        self.ts_last_data = None;
1323        self.sorted = true;
1324    }
1325
1326    /// Clear all actors from the engine's internal trader.
1327    ///
1328    /// # Errors
1329    ///
1330    /// Returns an error if any actor fails to dispose.
1331    pub fn clear_actors(&mut self) -> anyhow::Result<()> {
1332        self.kernel.trader.borrow_mut().clear_actors()
1333    }
1334
1335    /// Clear all trading strategies from the engine's internal trader.
1336    ///
1337    /// # Errors
1338    ///
1339    /// Returns an error if any strategy fails to dispose.
1340    pub fn clear_strategies(&mut self) -> anyhow::Result<()> {
1341        self.kernel.trader.borrow_mut().clear_strategies()
1342    }
1343
1344    /// Clear all execution algorithms from the engine's internal trader.
1345    ///
1346    /// # Errors
1347    ///
1348    /// Returns an error if any execution algorithm fails to dispose.
1349    pub fn clear_exec_algorithms(&mut self) -> anyhow::Result<()> {
1350        self.kernel.trader.borrow_mut().clear_exec_algorithms()
1351    }
1352
1353    /// Disposes of the backtest engine and releases its resources.
1354    ///
1355    /// Logs callback cleanup failures; externally retained callback work can prevent that cleanup.
1356    pub fn dispose(&mut self) {
1357        self.clear_data();
1358        self.accumulator.clear();
1359        self.kernel.dispose();
1360        clear_command_queues();
1361
1362        if let Err(e) = actor::clear_callbacks() {
1363            log::error!("Failed to clear callback dispatch during disposal: {e}");
1364        }
1365    }
1366
1367    /// Return the backtest result from the last run.
1368    #[must_use]
1369    pub fn get_result(&self) -> BacktestResult {
1370        let elapsed_time_secs = match (self.backtest_start, self.backtest_end) {
1371            (Some(start), Some(end)) => end.saturating_duration_since(start).as_secs_f64(),
1372            _ => 0.0,
1373        };
1374
1375        let cache = self.kernel.cache.borrow();
1376        let orders = cache.orders(None, None, None, None, None);
1377        let total_events = event_count_as_usize(self.kernel.exec_engine.borrow().event_count());
1378        let total_orders = orders.len();
1379        let positions: Vec<Position> = cache
1380            .positions(None, None, None, None, None)
1381            .into_iter()
1382            .map(|p| p.cloned())
1383            .collect();
1384        let cached_positions_count = positions.len();
1385        let snapshot_positions = cache.position_snapshots(None, None).len();
1386        let total_positions = Self::total_positions_with_snapshots(&cache, cached_positions_count);
1387        let summary = self.build_result_summary(
1388            &cache,
1389            total_events,
1390            total_orders,
1391            cached_positions_count,
1392            snapshot_positions,
1393        );
1394
1395        let stats = self.kernel.portfolio.borrow().statistics();
1396        let stats_pnls = stats.pnls;
1397        let stats_returns = stats.returns;
1398        let stats_general = stats.general;
1399        let returns_series = stats.returns_series;
1400
1401        BacktestResult {
1402            trader_id: self.config.trader_id().to_string(),
1403            machine_id: self.kernel.machine_id.clone(),
1404            instance_id: self.instance_id,
1405            run_config_id: self.run_config_id.clone(),
1406            run_id: self.run_id,
1407            run_started: self.run_started,
1408            run_finished: self.run_finished,
1409            backtest_start: self.backtest_start,
1410            backtest_end: self.backtest_end,
1411            elapsed_time_secs,
1412            iterations: self.iteration,
1413            total_events,
1414            total_orders,
1415            total_positions,
1416            summary,
1417            stats_pnls,
1418            stats_returns,
1419            stats_general,
1420            returns_series,
1421        }
1422    }
1423
1424    /// Returns the versioned deterministic projection of observable state from the last run.
1425    ///
1426    /// This projection excludes host, process, random identity, wall-clock, and elapsed-time noise.
1427    /// It retains deterministic references between domain events and includes the observable cache,
1428    /// account, portfolio, component, outcome, and diagnostic state available after the run ends.
1429    ///
1430    /// # Errors
1431    ///
1432    /// Returns an error if observable state cannot be projected into the canonical schema.
1433    pub fn get_canonical_result(&self) -> anyhow::Result<CanonicalBacktestResult> {
1434        let result = self.get_result();
1435        let cache = self.kernel.cache.borrow();
1436        let orders = cache
1437            .orders(None, None, None, None, None)
1438            .into_iter()
1439            .map(|order| order.cloned())
1440            .collect();
1441        let positions = cache
1442            .positions(None, None, None, None, None)
1443            .into_iter()
1444            .map(|position| position.cloned())
1445            .collect();
1446        let position_snapshots = cache.position_snapshots(None, None);
1447        let accounts = cache.accounts_all_owned();
1448        drop(cache);
1449
1450        let portfolio = self.kernel.portfolio.borrow();
1451        let mut portfolio_snapshots = Vec::new();
1452        for account in &accounts {
1453            portfolio_snapshots.extend(portfolio.snapshots(&account.id()));
1454        }
1455        drop(portfolio);
1456
1457        let trader = self.kernel.trader.borrow();
1458        let trader_state = trader.state().to_string();
1459        let actor_ids = trader
1460            .actor_ids()
1461            .into_iter()
1462            .map(|id| id.to_string())
1463            .collect();
1464        let strategy_ids = trader
1465            .strategy_ids()
1466            .into_iter()
1467            .map(|id| id.to_string())
1468            .collect();
1469        let exec_algorithm_ids = trader
1470            .exec_algorithm_ids()
1471            .into_iter()
1472            .map(|id| id.to_string())
1473            .collect();
1474        drop(trader);
1475
1476        let balance_error = self.kernel.portfolio.borrow().balance_error().is_some();
1477        let outcome = if self.funding_error.is_some() || balance_error {
1478            CanonicalRunOutcome::Failed
1479        } else if self.run_finished.is_none() {
1480            CanonicalRunOutcome::Incomplete
1481        } else if self.force_stop || self.kernel.is_shutdown_requested() {
1482            CanonicalRunOutcome::Stopped
1483        } else {
1484            CanonicalRunOutcome::Completed
1485        };
1486        let diagnostics = [
1487            self.funding_error
1488                .as_ref()
1489                .map(|_| CanonicalDiagnosticCode::FundingSettlementFailed),
1490            balance_error.then_some(CanonicalDiagnosticCode::AccountBalanceRejected),
1491        ]
1492        .into_iter()
1493        .flatten()
1494        .map(|code| CanonicalDiagnostic { code })
1495        .collect();
1496        let statistics = nautilus_analysis::PortfolioStatistics {
1497            pnls: result.stats_pnls,
1498            returns: result.stats_returns,
1499            general: result.stats_general,
1500            returns_series: result.returns_series,
1501        };
1502
1503        CanonicalBacktestResult::from_state(CanonicalBacktestState {
1504            trader_id: result.trader_id,
1505            run_config_id: result.run_config_id,
1506            backtest_start: result.backtest_start,
1507            backtest_end: result.backtest_end,
1508            iterations: result.iterations,
1509            total_events: result.total_events,
1510            total_orders: result.total_orders,
1511            total_positions: result.total_positions,
1512            outcome,
1513            diagnostics,
1514            trader_state,
1515            actor_ids,
1516            strategy_ids,
1517            exec_algorithm_ids,
1518            summary: result.summary.into_iter().collect(),
1519            orders,
1520            positions,
1521            position_snapshots,
1522            accounts,
1523            portfolio_snapshots,
1524            statistics,
1525        })
1526    }
1527
1528    fn build_result_summary(
1529        &self,
1530        cache: &Cache,
1531        total_events: usize,
1532        total_orders: usize,
1533        cached_positions_count: usize,
1534        snapshot_positions: usize,
1535    ) -> AHashMap<String, String> {
1536        let mut summary = AHashMap::new();
1537        summary.insert("iterations".to_string(), self.iteration.to_string());
1538        summary.insert("total_events".to_string(), total_events.to_string());
1539        summary.insert("orders.total".to_string(), total_orders.to_string());
1540        summary.insert(
1541            "orders.open".to_string(),
1542            cache
1543                .orders_open_count(None, None, None, None, None)
1544                .to_string(),
1545        );
1546        summary.insert(
1547            "orders.closed".to_string(),
1548            cache
1549                .orders_closed_count(None, None, None, None, None)
1550                .to_string(),
1551        );
1552        summary.insert(
1553            "orders.emulated".to_string(),
1554            cache
1555                .orders_emulated_count(None, None, None, None, None)
1556                .to_string(),
1557        );
1558        summary.insert(
1559            "orders.inflight".to_string(),
1560            cache
1561                .orders_inflight_count(None, None, None, None, None)
1562                .to_string(),
1563        );
1564        summary.insert(
1565            "positions.total".to_string(),
1566            cached_positions_count.to_string(),
1567        );
1568        summary.insert(
1569            "positions.open".to_string(),
1570            cache
1571                .positions_open_count(None, None, None, None, None)
1572                .to_string(),
1573        );
1574        summary.insert(
1575            "positions.closed".to_string(),
1576            cache
1577                .positions_closed_count(None, None, None, None, None)
1578                .to_string(),
1579        );
1580        summary.insert(
1581            "positions.snapshots".to_string(),
1582            snapshot_positions.to_string(),
1583        );
1584        summary.insert(
1585            "positions.total_with_snapshots".to_string(),
1586            (cached_positions_count + snapshot_positions).to_string(),
1587        );
1588
1589        let mut venues: Vec<Venue> = self.venues.keys().copied().collect();
1590        venues.sort_by_key(ToString::to_string);
1591        summary.insert("venues.total".to_string(), venues.len().to_string());
1592
1593        for venue in venues {
1594            let Some(account) = cache.account_for_venue(&venue) else {
1595                continue;
1596            };
1597
1598            let venue_key = venue.to_string();
1599            let account_key = format!("account.{venue_key}");
1600            summary.insert(format!("{account_key}.id"), account.id().to_string());
1601            summary.insert(
1602                format!("{account_key}.type"),
1603                account.account_type().to_string(),
1604            );
1605            summary.insert(
1606                format!("{account_key}.base_currency"),
1607                account
1608                    .base_currency()
1609                    .map_or_else(|| "None".to_string(), |currency| currency.code.to_string()),
1610            );
1611            summary.insert(
1612                format!("{account_key}.event_count"),
1613                account.event_count().to_string(),
1614            );
1615
1616            let mut balances: Vec<_> = account.balances().into_iter().collect();
1617            balances.sort_by_key(|(currency, _)| currency.code.to_string());
1618
1619            for (currency, balance) in balances {
1620                let balance_key = format!("{account_key}.balance.{}", currency.code);
1621                summary.insert(format!("{balance_key}.total"), balance.total.to_string());
1622                summary.insert(format!("{balance_key}.free"), balance.free.to_string());
1623                summary.insert(format!("{balance_key}.locked"), balance.locked.to_string());
1624            }
1625        }
1626
1627        summary
1628    }
1629
1630    fn route_data_to_exchange(
1631        venues: &IndexMap<Venue, Rc<RefCell<SimulatedExchange>>>,
1632        has_book_processed: &mut AHashSet<InstrumentId>,
1633        clock: &Rc<RefCell<dyn Clock>>,
1634        data: DataRef<'_>,
1635    ) -> anyhow::Result<()> {
1636        if matches!(
1637            data,
1638            DataRef::Instrument(_)
1639                | DataRef::IndexPrice(_)
1640                | DataRef::OptionGreeks(_)
1641                | DataRef::Custom(_)
1642        ) {
1643            return Ok(());
1644        }
1645
1646        if is_defi(data) {
1647            return Ok(());
1648        }
1649
1650        let venue = data.instrument_id().venue;
1651        if let Some(exchange) = venues.get(&venue) {
1652            let mut exchange_ref = exchange.borrow_mut();
1653            let mut processed_book_data = false;
1654
1655            match data {
1656                DataRef::BookDelta(delta) => {
1657                    exchange_ref.process_order_book_delta(*delta)?;
1658                    processed_book_data = true;
1659                }
1660                DataRef::BookDeltas(deltas) => {
1661                    exchange_ref.process_order_book_deltas(deltas)?;
1662                    processed_book_data = true;
1663                }
1664                DataRef::BookDepth(depth) => {
1665                    exchange_ref.process_order_book_depth(depth)?;
1666                    processed_book_data = true;
1667                }
1668                DataRef::Quote(quote) => exchange_ref.process_quote_tick(quote)?,
1669                DataRef::Trade(trade) => exchange_ref.process_trade_tick(trade)?,
1670                DataRef::Bar(bar) => exchange_ref.process_bar(*bar)?,
1671                DataRef::MarkPrice(mark) => exchange_ref.process_mark_price(mark)?,
1672                DataRef::IndexPrice(_) => {
1673                    unreachable!("filtered before exchange routing")
1674                }
1675                DataRef::FundingRate(funding) => {
1676                    let settlement_ns =
1677                        exchange_ref.process_funding_rate_deferred(*funding, data.ts_init())?;
1678                    Self::schedule_funding_settlement_if_required(clock, venue, settlement_ns);
1679                }
1680                DataRef::OptionGreeks(_) => unreachable!("filtered before exchange routing"),
1681                DataRef::InstrumentStatus(status) => {
1682                    exchange_ref.process_instrument_status(*status)?;
1683                }
1684                DataRef::InstrumentClose(close) => {
1685                    exchange_ref.process_instrument_close(*close)?;
1686                }
1687                DataRef::Instrument(_) | DataRef::Custom(_) => {
1688                    unreachable!("filtered before exchange routing")
1689                }
1690                #[cfg(feature = "defi")]
1691                DataRef::Defi(_) => unreachable!("filtered before exchange routing"),
1692                #[cfg(not(feature = "defi"))]
1693                #[allow(
1694                    unreachable_patterns,
1695                    reason = "DeFi variants can exist without this crate's defi feature"
1696                )]
1697                _ => unreachable!("filtered before exchange routing"),
1698            }
1699
1700            drop(exchange_ref);
1701
1702            if processed_book_data {
1703                has_book_processed.insert(data.instrument_id());
1704            }
1705        } else {
1706            log::warn!("No exchange found for venue {venue}, data not routed");
1707        }
1708        Ok(())
1709    }
1710
1711    fn check_exchange_errors(&self) -> anyhow::Result<()> {
1712        for exchange in self.venues.values() {
1713            exchange.borrow().check_callback_error()?;
1714        }
1715        Ok(())
1716    }
1717
1718    fn check_balance_error(&self) -> anyhow::Result<()> {
1719        if let Some(error) = self.kernel.portfolio.borrow().balance_error() {
1720            anyhow::bail!("{error}");
1721        }
1722        Ok(())
1723    }
1724
1725    fn advance_time_impl(&mut self, ts_now: UnixNanos) -> anyhow::Result<()> {
1726        self.accumulate_time_events(ts_now);
1727
1728        // Process events with ts_event < ts_now
1729        let ts_before = ts_now.saturating_sub(DurationNanos::new(1));
1730
1731        let mut shutdown_at: Option<UnixNanos> = None;
1732
1733        while let Some(ts_event) = self
1734            .accumulator
1735            .peek_next_time()
1736            .filter(|ts_event| *ts_event <= ts_before)
1737        {
1738            let settlement_scope = self.run_timer_handlers_at(ts_event)?;
1739
1740            if self.kernel.is_shutdown_requested() {
1741                self.accumulator.clear();
1742                shutdown_at = Some(ts_event);
1743                break;
1744            }
1745
1746            self.finalize_timestamp(ts_event, settlement_scope)?;
1747
1748            if self.kernel.is_shutdown_requested() {
1749                self.accumulator.clear();
1750                shutdown_at = Some(ts_event);
1751                break;
1752            }
1753
1754            self.accumulate_time_events(ts_now);
1755        }
1756
1757        // On a mid-drain shutdown, anchor state at the firing timer's ts so
1758        // post-run settlement and backtest_end reflect the graceful stop
1759        if let Some(ts_event) = shutdown_at {
1760            self.last_ns = ts_event;
1761        } else {
1762            self.last_ns = ts_now;
1763            Self::set_all_clocks_time(&self.collect_all_clocks(), ts_now);
1764            logging_clock_set_static_time(ts_now.as_u64());
1765        }
1766
1767        Ok(())
1768    }
1769
1770    fn flush_accumulator_events(&mut self, ts_now: UnixNanos) -> anyhow::Result<()> {
1771        // Bail after shutdown so handler-scheduled alerts do not fire post-stop
1772        if self.kernel.is_shutdown_requested() {
1773            self.accumulator.clear();
1774            return Ok(());
1775        }
1776
1777        let last_ns = self.last_ns;
1778
1779        self.accumulate_time_events(ts_now);
1780
1781        while let Some(ts_event) = self
1782            .accumulator
1783            .peek_next_time()
1784            .filter(|ts_event| *ts_event <= ts_now)
1785        {
1786            let settlement_scope = self.run_timer_handlers_at(ts_event)?;
1787
1788            if self.kernel.is_shutdown_requested() {
1789                self.accumulator.clear();
1790                break;
1791            }
1792
1793            self.finalize_timestamp(ts_event, settlement_scope)?;
1794
1795            if self.kernel.is_shutdown_requested() {
1796                self.accumulator.clear();
1797                break;
1798            }
1799
1800            self.accumulate_time_events(ts_now);
1801        }
1802
1803        if !self.kernel.is_shutdown_requested() {
1804            self.last_ns = last_ns;
1805        }
1806
1807        Ok(())
1808    }
1809
1810    fn process_next_timer(&mut self) -> anyhow::Result<bool> {
1811        self.flush_accumulator_events(self.last_ns)?;
1812
1813        let min_next_time =
1814            Self::next_timer_time(&self.collect_all_clocks()).filter(|time| *time > self.last_ns);
1815
1816        match min_next_time {
1817            None => Ok(true),
1818            Some(t) if t > self.end_ns => Ok(true),
1819            Some(t) => {
1820                self.last_ns = t;
1821                self.flush_accumulator_events(t)?;
1822                Ok(false)
1823            }
1824        }
1825    }
1826
1827    fn run_timer_handlers_at(&mut self, ts_event: UnixNanos) -> anyhow::Result<SettlementScope> {
1828        self.last_ns = ts_event;
1829        let mut settlement_scope = SettlementScope::Data(None);
1830
1831        while self.accumulator.peek_next_time() == Some(ts_event) {
1832            let handler = self
1833                .accumulator
1834                .pop_next_at_or_before(ts_event)
1835                .expect("timer exists at timestamp");
1836
1837            if !is_snapshot_timer(handler.event.name.as_str()) {
1838                settlement_scope = SettlementScope::All;
1839            }
1840
1841            Self::set_all_clocks_time(&self.collect_all_clocks(), ts_event);
1842            logging_clock_set_static_time(ts_event.as_u64());
1843            handler.run();
1844            self.drain_command_queues()?;
1845
1846            if self.kernel.is_shutdown_requested() {
1847                return Ok(settlement_scope);
1848            }
1849
1850            self.accumulate_time_events(ts_event);
1851        }
1852
1853        Ok(settlement_scope)
1854    }
1855
1856    fn finalize_timestamp(
1857        &mut self,
1858        ts_now: UnixNanos,
1859        mut settlement_scope: SettlementScope,
1860    ) -> anyhow::Result<()> {
1861        loop {
1862            self.settle_venues(ts_now, settlement_scope)?;
1863
1864            if self.kernel.is_shutdown_requested() {
1865                self.accumulator.clear();
1866                break;
1867            }
1868
1869            self.accumulate_time_events(ts_now);
1870
1871            if self.accumulator.peek_next_time() == Some(ts_now) {
1872                if matches!(self.run_timer_handlers_at(ts_now)?, SettlementScope::All) {
1873                    settlement_scope = SettlementScope::All;
1874                }
1875
1876                continue;
1877            }
1878
1879            if !self.settle_funding_rates(ts_now)? {
1880                break;
1881            }
1882            settlement_scope = SettlementScope::All;
1883        }
1884
1885        self.run_venue_modules(ts_now, settlement_scope)?;
1886        self.run_venue_liquidations(ts_now, settlement_scope)?;
1887        Ok(())
1888    }
1889
1890    fn settle_funding_rates(&mut self, ts_now: UnixNanos) -> anyhow::Result<bool> {
1891        let mut due = self
1892            .venues
1893            .iter()
1894            .flat_map(|(venue, exchange)| {
1895                exchange
1896                    .borrow()
1897                    .funding_boundaries_due(ts_now)
1898                    .into_iter()
1899                    .map(|(boundary, instrument_id)| (boundary, *venue, instrument_id))
1900                    .collect::<Vec<_>>()
1901            })
1902            .collect::<Vec<_>>();
1903        due.sort_unstable();
1904
1905        if let Some((boundary, venue, instrument_id)) = due
1906            .iter()
1907            .copied()
1908            .find(|(boundary, _, _)| *boundary < ts_now)
1909        {
1910            return self.fail_funding(format!(
1911                "Late funding boundary for {instrument_id} on {venue}: {boundary} < replay timestamp {ts_now}"
1912            ));
1913        }
1914
1915        if due.is_empty() {
1916            return Ok(false);
1917        }
1918
1919        for (boundary, venue, instrument_id) in due {
1920            if !self.venues[&venue]
1921                .borrow_mut()
1922                .settle_funding_boundary(boundary, instrument_id)
1923            {
1924                return self.fail_funding(format!(
1925                    "Funding settlement failed for {instrument_id} on {venue} at {boundary}"
1926                ));
1927            }
1928        }
1929
1930        let next_boundaries = self
1931            .venues
1932            .iter()
1933            .filter_map(|(venue, exchange)| {
1934                exchange
1935                    .borrow()
1936                    .next_funding_boundary()
1937                    .map(|boundary| (*venue, boundary))
1938            })
1939            .collect::<Vec<_>>();
1940
1941        for (venue, boundary) in next_boundaries {
1942            Self::schedule_funding_settlement_if_required(
1943                &self.kernel.clock,
1944                venue,
1945                Some(boundary),
1946            );
1947        }
1948
1949        Ok(true)
1950    }
1951
1952    fn fail_funding<T>(&mut self, error: String) -> anyhow::Result<T> {
1953        if self.funding_error.is_none() {
1954            self.funding_error = Some(error.clone());
1955        }
1956        Err(anyhow::anyhow!(error))
1957    }
1958
1959    fn set_instrument_expiration_timers(&self) -> anyhow::Result<()> {
1960        for exchange in self.venues.values() {
1961            let expirations = exchange.borrow().instrument_expirations();
1962            for (instrument_id, expiration_ns) in expirations {
1963                self.set_instrument_expiration_timer(exchange, instrument_id, expiration_ns)?;
1964            }
1965        }
1966
1967        Ok(())
1968    }
1969
1970    fn set_instrument_expiration_timer(
1971        &self,
1972        exchange: &Rc<RefCell<SimulatedExchange>>,
1973        instrument_id: InstrumentId,
1974        expiration_ns: UnixNanos,
1975    ) -> anyhow::Result<()> {
1976        if expiration_ns == UnixNanos::default() {
1977            return Ok(());
1978        }
1979
1980        let timer_name = Self::instrument_expiration_timer_name(instrument_id.venue, expiration_ns);
1981        let timer_key = ustr::Ustr::from(timer_name.as_str());
1982        if self.kernel.clock.borrow().timer_exists(&timer_key) {
1983            return Ok(());
1984        }
1985
1986        let exchange: Weak<RefCell<SimulatedExchange>> = Rc::downgrade(exchange);
1987        let callback: Rc<dyn Fn(TimeEvent)> = Rc::new(move |event: TimeEvent| {
1988            if let Some(exchange) = exchange.upgrade() {
1989                exchange
1990                    .borrow_mut()
1991                    .process_instrument_expirations(event.ts_event);
1992            }
1993        });
1994        let mut clock = self.kernel.clock.borrow_mut();
1995
1996        clock.set_time_alert_ns(
1997            &timer_name,
1998            expiration_ns,
1999            Some(TimeEventCallback::from(callback)),
2000            None,
2001        )?;
2002
2003        Ok(())
2004    }
2005
2006    fn instrument_expiration_timer_name(venue: Venue, expiration_ns: UnixNanos) -> String {
2007        format!("INSTRUMENT-EXPIRATION:{venue}:{expiration_ns}")
2008    }
2009
2010    fn schedule_funding_settlement_if_required(
2011        clock: &Rc<RefCell<dyn Clock>>,
2012        venue: Venue,
2013        settlement_ns: Option<UnixNanos>,
2014    ) {
2015        let Some(settlement_ns) = settlement_ns else {
2016            return;
2017        };
2018
2019        if let Err(e) = Self::set_funding_settlement_timer(clock, venue, settlement_ns) {
2020            log::error!("Cannot schedule funding settlement for {venue}: {e}");
2021        }
2022    }
2023
2024    fn set_funding_settlement_timer(
2025        clock: &Rc<RefCell<dyn Clock>>,
2026        venue: Venue,
2027        settlement_ns: UnixNanos,
2028    ) -> anyhow::Result<()> {
2029        let timer_name = Self::funding_settlement_timer_name(venue);
2030        let callback: Rc<dyn Fn(TimeEvent)> = Rc::new(|_| {});
2031        let mut clock = clock.borrow_mut();
2032
2033        clock.set_time_alert_ns(
2034            &timer_name,
2035            settlement_ns,
2036            Some(TimeEventCallback::from(callback)),
2037            None,
2038        )?;
2039
2040        Ok(())
2041    }
2042
2043    fn funding_settlement_timer_name(venue: Venue) -> String {
2044        format!("FUNDING-SETTLEMENT:{venue}")
2045    }
2046
2047    fn cancel_funding_settlement_timers(&self) {
2048        let mut clock = self.kernel.clock.borrow_mut();
2049        for venue in self.venues.keys() {
2050            clock.cancel_timer(&Self::funding_settlement_timer_name(*venue));
2051        }
2052    }
2053
2054    fn collect_all_clocks(&self) -> ClockSnapshot {
2055        ClockSnapshot {
2056            clock: self.kernel.clock.clone(),
2057            components: self.kernel.trader.borrow().get_component_clocks_snapshot(),
2058        }
2059    }
2060
2061    fn max_inflight_command_ts(&self) -> Option<UnixNanos> {
2062        self.venues
2063            .values()
2064            .filter_map(|v| v.borrow().max_inflight_command_ts())
2065            .max()
2066    }
2067
2068    fn settle_venues(
2069        &self,
2070        ts_now: UnixNanos,
2071        settlement_scope: SettlementScope,
2072    ) -> anyhow::Result<()> {
2073        // Advance venue clocks so modules and event generators see the
2074        // correct timestamp even when no commands are pending
2075        for exchange in self.venues.values() {
2076            exchange.borrow().set_clock_time(ts_now);
2077        }
2078
2079        // Drain commands then iterate matching engines to fill newly added
2080        // orders. Fills may enqueue further commands (e.g. hedge orders
2081        // submitted from on_order_filled), so loop until quiescent.
2082        // Only process and iterate venues that had pending commands each
2083        // pass, to avoid extra fill-model rolls on untouched venues.
2084        loop {
2085            // Drain first so commands buffered in the trading queue (e.g. from
2086            // on_stop handlers) reach the venues before we check for activity.
2087            self.drain_command_queues()?;
2088
2089            let active_venues: Vec<Venue> = self
2090                .venues
2091                .iter()
2092                .filter(|(_, ex)| {
2093                    ex.borrow()
2094                        .has_pending_commands_for_scope(ts_now, settlement_scope)
2095                })
2096                .map(|(id, _)| *id)
2097                .collect();
2098
2099            if active_venues.is_empty() {
2100                break;
2101            }
2102
2103            for venue_id in &active_venues {
2104                let mut exchange = self.venues[venue_id].borrow_mut();
2105                exchange.process_for_scope(ts_now, settlement_scope);
2106            }
2107            self.drain_command_queues()?;
2108
2109            for venue_id in &active_venues {
2110                self.venues[venue_id]
2111                    .borrow_mut()
2112                    .iterate_matching_engines(ts_now);
2113            }
2114
2115            // Drain again so fill-triggered commands (e.g. hedge orders
2116            // from on_order_filled) are visible to has_pending_commands
2117            self.drain_command_queues()?;
2118        }
2119        Ok(())
2120    }
2121
2122    fn run_venue_modules(
2123        &mut self,
2124        ts_now: UnixNanos,
2125        settlement_scope: SettlementScope,
2126    ) -> anyhow::Result<()> {
2127        if self.last_module_ns == Some(ts_now) {
2128            return Ok(());
2129        }
2130        self.last_module_ns = Some(ts_now);
2131
2132        if self
2133            .venues
2134            .values()
2135            .all(|exchange| !exchange.borrow().has_modules())
2136        {
2137            return Ok(());
2138        }
2139
2140        // Pre-settle handler-generated work so modules see final state
2141        self.drain_command_queues()?;
2142        self.settle_venues(ts_now, settlement_scope)?;
2143
2144        for exchange in self.venues.values() {
2145            exchange.borrow_mut().process_modules(ts_now)?;
2146        }
2147
2148        // Post-settle any commands emitted by modules
2149        self.drain_command_queues()?;
2150        self.settle_venues(ts_now, settlement_scope)?;
2151        Ok(())
2152    }
2153
2154    fn run_venue_liquidations(
2155        &mut self,
2156        ts_now: UnixNanos,
2157        settlement_scope: SettlementScope,
2158    ) -> anyhow::Result<()> {
2159        if self.last_liquidation_ns == Some(ts_now) {
2160            return Ok(());
2161        }
2162        self.last_liquidation_ns = Some(ts_now);
2163
2164        if self
2165            .venues
2166            .values()
2167            .all(|exchange| !exchange.borrow().liquidation_enabled())
2168        {
2169            return Ok(());
2170        }
2171
2172        for exchange in self.venues.values() {
2173            exchange.borrow_mut().process_liquidations(ts_now);
2174        }
2175
2176        self.drain_command_queues()?;
2177        self.settle_venues(ts_now, settlement_scope)?;
2178        Ok(())
2179    }
2180
2181    fn drain_exec_client_events(&self) {
2182        for client in &self.exec_clients {
2183            client.drain_queued_events();
2184        }
2185    }
2186
2187    fn drain_command_queues(&self) -> anyhow::Result<()> {
2188        if let Some(error) = actor::callback_failure() {
2189            return Err(error.into());
2190        }
2191
2192        // Drain trading commands, exec client events, data commands, and callbacks
2193        // until all queues settle. Handles cascading re-entrancy
2194        // (e.g. strategy submits order from on_order_filled).
2195        loop {
2196            drain_trading_cmd_queue();
2197            drain_data_cmd_queue();
2198            self.check_exchange_errors()?;
2199            self.drain_exec_client_events();
2200            self.check_balance_error()?;
2201
2202            let callbacks_pending = actor::drain_callbacks(CALLBACK_DRAIN_BUDGET)?;
2203
2204            if trading_cmd_queue_is_empty() && data_cmd_queue_is_empty() && !callbacks_pending {
2205                break;
2206            }
2207        }
2208        Ok(())
2209    }
2210
2211    fn init_command_senders() {
2212        replace_data_cmd_sender(Arc::new(SyncDataCommandSender));
2213        replace_exec_cmd_sender(Arc::new(SyncTradingCommandSender));
2214    }
2215
2216    fn accumulate_time_events(&mut self, until: UnixNanos) {
2217        let clocks = self.collect_all_clocks();
2218
2219        loop {
2220            let Some(next_time) = self
2221                .accumulator
2222                .peek_next_time()
2223                .into_iter()
2224                .chain(Self::next_timer_time(&clocks))
2225                .min()
2226            else {
2227                return;
2228            };
2229
2230            if next_time > until {
2231                return;
2232            }
2233
2234            for clock in clocks.iter() {
2235                Self::advance_clock_on_accumulator(&mut self.accumulator, clock, next_time);
2236            }
2237
2238            if self
2239                .accumulator
2240                .peek_next_time()
2241                .is_some_and(|time| time <= next_time)
2242            {
2243                return;
2244            }
2245        }
2246    }
2247
2248    fn next_timer_time(clocks: &ClockSnapshot) -> Option<UnixNanos> {
2249        clocks
2250            .iter()
2251            .filter_map(|clock| {
2252                let clock = clock.borrow();
2253                let clock = clock
2254                    .as_any()
2255                    .downcast_ref::<VirtualClock>()
2256                    .expect("BacktestEngine requires VirtualClock");
2257                clock.next_event_time_ns()
2258            })
2259            .min()
2260    }
2261
2262    fn advance_clock_on_accumulator(
2263        accumulator: &mut TimeEventAccumulator,
2264        clock: &Rc<RefCell<dyn Clock>>,
2265        to_time_ns: UnixNanos,
2266    ) {
2267        let mut clock_ref = clock.borrow_mut();
2268        let test_clock = clock_ref
2269            .as_any_mut()
2270            .downcast_mut::<VirtualClock>()
2271            .expect("BacktestEngine requires VirtualClock");
2272        let previous_time = test_clock.timestamp_ns();
2273        let rewind = to_time_ns < previous_time;
2274
2275        // Timers registered with allow_past can be due before the stored clock time
2276        if rewind {
2277            test_clock.set_time(to_time_ns);
2278        }
2279
2280        accumulator.advance_clock(test_clock, to_time_ns, false);
2281        if rewind {
2282            test_clock.set_time(previous_time);
2283        }
2284    }
2285
2286    fn set_all_clocks_time(clocks: &ClockSnapshot, time_ns: UnixNanos) {
2287        for clock in clocks.iter() {
2288            let mut clock_ref = clock.borrow_mut();
2289            let test_clock = clock_ref
2290                .as_any_mut()
2291                .downcast_mut::<VirtualClock>()
2292                .expect("BacktestEngine requires VirtualClock");
2293            test_clock.set_time(time_ns);
2294        }
2295    }
2296
2297    #[rustfmt::skip]
2298    fn log_pre_run(&self) {
2299        log_info!("=================================================================", color = LogColor::Cyan);
2300        log_info!(" BACKTEST PRE-RUN", color = LogColor::Cyan);
2301        log_info!("=================================================================", color = LogColor::Cyan);
2302
2303        let cache = self.kernel.cache.borrow();
2304        for exchange in self.venues.values() {
2305            let ex = exchange.borrow();
2306            log_info!("=================================================================", color = LogColor::Cyan);
2307            log::info!(" SimulatedVenue {} ({})", ex.id, ex.account_type);
2308            log_info!("-----------------------------------------------------------------", color = LogColor::Cyan);
2309
2310            if let Some(account) = cache.account_for_venue(&ex.id) {
2311                log::info!("Balances starting:");
2312                let account_ref: &dyn Account = match &*account {
2313                    AccountAny::Margin(margin) => margin,
2314                    AccountAny::Cash(cash) => cash,
2315                    AccountAny::Betting(betting) => betting,
2316                    AccountAny::Wallet(wallet) => wallet,
2317                };
2318
2319                for balance in account_ref.starting_balances().values() {
2320                    log::info!("  {balance}");
2321                }
2322            }
2323        }
2324
2325        log_info!("-----------------------------------------------------------------", color = LogColor::Cyan);
2326    }
2327
2328    #[rustfmt::skip]
2329    fn log_run(&self) {
2330        let config_id = self.run_config_id.as_deref().unwrap_or("None");
2331        let id = format_optional_uuid(self.run_id.as_ref());
2332        let start = format_optional_nanos(self.backtest_start);
2333
2334        log_info!("=================================================================", color = LogColor::Cyan);
2335        log_info!(" BACKTEST RUN", color = LogColor::Cyan);
2336        log_info!("=================================================================", color = LogColor::Cyan);
2337        log::info!("Run config ID:  {config_id}");
2338        log::info!("Run ID:         {id}");
2339        log::info!("Backtest start: {start}");
2340        log::info!("Data elements:  {}", self.data_len);
2341        log_info!("-----------------------------------------------------------------", color = LogColor::Cyan);
2342    }
2343
2344    #[rustfmt::skip]
2345    fn log_post_run(&self) {
2346        let cache = self.kernel.cache.borrow();
2347        let orders = cache.orders(None, None, None, None, None);
2348        let total_events = event_count_as_usize(self.kernel.exec_engine.borrow().event_count());
2349        let total_orders = orders.len();
2350        let positions: Vec<Position> = cache
2351            .positions(None, None, None, None, None)
2352            .into_iter()
2353            .map(|p| p.cloned())
2354            .collect();
2355        let total_positions = Self::total_positions_with_snapshots(&cache, positions.len());
2356
2357        let config_id = self.run_config_id.as_deref().unwrap_or("None");
2358        let id = format_optional_uuid(self.run_id.as_ref());
2359        let started = format_optional_nanos(self.run_started);
2360        let finished = format_optional_nanos(self.run_finished);
2361        let elapsed = format_optional_duration(self.run_started, self.run_finished);
2362        let bt_start = format_optional_nanos(self.backtest_start);
2363        let bt_end = format_optional_nanos(self.backtest_end);
2364        let bt_range = format_optional_duration(self.backtest_start, self.backtest_end);
2365        let iterations = self.iteration.separate_with_underscores();
2366        let events = total_events.separate_with_underscores();
2367        let num_orders = total_orders.separate_with_underscores();
2368        let num_positions = total_positions.separate_with_underscores();
2369
2370        log_info!("=================================================================", color = LogColor::Cyan);
2371        log_info!(" BACKTEST POST-RUN", color = LogColor::Cyan);
2372        log_info!("=================================================================", color = LogColor::Cyan);
2373        log::info!("Run config ID:  {config_id}");
2374        log::info!("Run ID:         {id}");
2375        log::info!("Run started:    {started}");
2376        log::info!("Run finished:   {finished}");
2377        log::info!("Elapsed time:   {elapsed}");
2378        log::info!("Backtest start: {bt_start}");
2379        log::info!("Backtest end:   {bt_end}");
2380        log::info!("Backtest range: {bt_range}");
2381        log::info!("Iterations: {iterations}");
2382        log::info!("Total events: {events}");
2383        log::info!("Total orders: {num_orders}");
2384        log::info!("Total positions: {num_positions}");
2385
2386        if !self.config.run_analysis {
2387            return;
2388        }
2389
2390        log_portfolio_performance(&self.kernel.portfolio.borrow().analyzer());
2391    }
2392
2393    fn total_positions_with_snapshots(cache: &Cache, cached_positions_count: usize) -> usize {
2394        cached_positions_count + cache.position_snapshots(None, None).len()
2395    }
2396
2397    /// Registers a data client for the given `client_id` if one does not already exist.
2398    pub fn add_data_client_if_not_exists(&mut self, client_id: ClientId) {
2399        if self
2400            .kernel
2401            .data_engine
2402            .borrow()
2403            .registered_clients()
2404            .contains(&client_id)
2405        {
2406            return;
2407        }
2408
2409        let venue = Venue::from(client_id.as_str());
2410        let backtest_client = BacktestDataClient::new(client_id, venue, self.kernel.cache.clone());
2411        let data_client_adapter = DataClientAdapter::new(
2412            backtest_client.client_id,
2413            None,
2414            false,
2415            false,
2416            Box::new(backtest_client),
2417        );
2418
2419        self.kernel
2420            .data_engine
2421            .borrow_mut()
2422            .register_client(data_client_adapter, None);
2423    }
2424
2425    /// Registers a market data client for the given `venue` if one does not already exist.
2426    pub fn add_market_data_client_if_not_exists(&mut self, venue: Venue) {
2427        let client_id = ClientId::from(venue.as_str());
2428
2429        if !self
2430            .kernel
2431            .data_engine
2432            .borrow()
2433            .registered_clients()
2434            .contains(&client_id)
2435        {
2436            let backtest_client =
2437                BacktestDataClient::new(client_id, venue, self.kernel.cache.clone());
2438            let data_client_adapter = DataClientAdapter::new(
2439                client_id,
2440                Some(venue),
2441                false,
2442                false,
2443                Box::new(backtest_client),
2444            );
2445            self.kernel
2446                .data_engine
2447                .borrow_mut()
2448                .register_client(data_client_adapter, Some(venue));
2449        }
2450    }
2451}
2452
2453#[derive(Debug)]
2454struct ClockSnapshot {
2455    clock: Rc<RefCell<dyn Clock>>,
2456    components: Rc<[Rc<RefCell<dyn Clock>>]>,
2457}
2458
2459impl ClockSnapshot {
2460    fn iter(&self) -> impl Iterator<Item = &Rc<RefCell<dyn Clock>>> {
2461        std::iter::once(&self.clock).chain(self.components.iter())
2462    }
2463}
2464
2465fn format_optional_nanos(nanos: Option<UnixNanos>) -> String {
2466    nanos.map_or("None".to_string(), unix_nanos_to_iso8601)
2467}
2468
2469fn format_optional_uuid(uuid: Option<&UUID4>) -> String {
2470    uuid.map_or("None".to_string(), ToString::to_string)
2471}
2472
2473fn event_count_as_usize(event_count: u64) -> usize {
2474    usize::try_from(event_count).expect("execution event count fits usize")
2475}
2476
2477fn format_optional_duration(start: Option<UnixNanos>, end: Option<UnixNanos>) -> String {
2478    match (start, end) {
2479        (Some(s), Some(e)) => {
2480            let delta = s.to_datetime_utc().duration_until(e.to_datetime_utc());
2481            let days = delta.as_hours().abs() / 24;
2482            let hours = delta.as_hours().abs() % 24;
2483            let minutes = delta.as_mins().abs() % 60;
2484            let seconds = delta.as_secs().abs() % 60;
2485            let micros = delta.subsec_nanos().unsigned_abs() / 1_000;
2486            format!("{days} days {hours:02}:{minutes:02}:{seconds:02}.{micros:06}")
2487        }
2488        _ => "None".to_string(),
2489    }
2490}
2491
2492#[rustfmt::skip]
2493fn log_portfolio_performance(analyzer: &PortfolioAnalyzer) {
2494    log_info!("=================================================================", color = LogColor::Cyan);
2495    log_info!(" PORTFOLIO PERFORMANCE", color = LogColor::Cyan);
2496    log_info!("=================================================================", color = LogColor::Cyan);
2497
2498    for currency in analyzer.currencies() {
2499        log::info!(" PnL Statistics ({})", currency.code);
2500        log_info!("-----------------------------------------------------------------", color = LogColor::Cyan);
2501
2502        if let Ok(pnl_lines) = analyzer.get_stats_pnls_formatted(Some(currency), None) {
2503            for line in &pnl_lines {
2504                log::info!("{line}");
2505            }
2506        }
2507
2508        log_info!("-----------------------------------------------------------------", color = LogColor::Cyan);
2509    }
2510
2511    log::info!(" Returns Statistics");
2512    log_info!("-----------------------------------------------------------------", color = LogColor::Cyan);
2513
2514    for line in &analyzer.get_stats_returns_formatted() {
2515        log::info!("{line}");
2516    }
2517    log_info!("-----------------------------------------------------------------", color = LogColor::Cyan);
2518
2519    log::info!(" General Statistics");
2520    log_info!("-----------------------------------------------------------------", color = LogColor::Cyan);
2521
2522    for line in &analyzer.get_stats_general_formatted() {
2523        log::info!("{line}");
2524    }
2525    log_info!("-----------------------------------------------------------------", color = LogColor::Cyan);
2526}
2527
2528fn is_defi(data: DataRef<'_>) -> bool {
2529    match data {
2530        DataRef::Instrument(_)
2531        | DataRef::BookDelta(_)
2532        | DataRef::BookDeltas(_)
2533        | DataRef::BookDepth(_)
2534        | DataRef::Quote(_)
2535        | DataRef::Trade(_)
2536        | DataRef::Bar(_)
2537        | DataRef::MarkPrice(_)
2538        | DataRef::IndexPrice(_)
2539        | DataRef::FundingRate(_)
2540        | DataRef::OptionGreeks(_)
2541        | DataRef::InstrumentStatus(_)
2542        | DataRef::InstrumentClose(_)
2543        | DataRef::Custom(_) => false,
2544        #[cfg(feature = "defi")]
2545        DataRef::Defi(_) => true,
2546        #[cfg(not(feature = "defi"))]
2547        #[allow(
2548            unreachable_patterns,
2549            reason = "DeFi variants can exist without this crate's defi feature"
2550        )]
2551        _ => true,
2552    }
2553}
2554
2555#[cfg(test)]
2556mod tests {
2557    use std::{cell::Cell, rc::Rc};
2558
2559    use indexmap::IndexMap;
2560    use nautilus_common::{
2561        actor::{DataActor, DataActorCore, data_actor::DataActorConfig},
2562        enums::Environment,
2563        messages::{
2564            data::{DataCommand, UnsubscribeCommand},
2565            execution::{
2566                BatchModifyOrders, CancelAllOrders, ModifyOrder, SubmitOrder, TradingCommand,
2567            },
2568        },
2569        msgbus::{
2570            self, MessagingSwitchboard, TypedHandler,
2571            stubs::{TypedIntoMessageSavingHandler, get_typed_into_message_saving_handler},
2572        },
2573        nautilus_actor,
2574    };
2575    #[cfg(feature = "streaming")]
2576    use nautilus_execution::matching_engine::config::OrderPriorityResetPolicy;
2577    use nautilus_execution::{
2578        engine::{SnapshotAnchorer, stubs::StubExecutionClient},
2579        models::{
2580            fee::{FeeModelAny, MakerTakerFeeModel},
2581            latency::{LatencyModelHandle, StaticLatencyModel},
2582        },
2583    };
2584    use nautilus_model::{
2585        data::{Data, IndexPriceUpdate, InstrumentClose, InstrumentStatus, QuoteTick},
2586        enums::{
2587            AccountType, BookType, ContingencyType, InstrumentCloseType, LiquiditySide,
2588            MarketStatus, MarketStatusAction, OmsType, OrderSide, OrderStatus, OrderType,
2589            PositionSide, TriggerType,
2590        },
2591        events::OrderEventAny,
2592        identifiers::{
2593            AccountId, ActorId, ClientId, ClientOrderId, PositionId, StrategyId, TraderId, Venue,
2594        },
2595        instruments::{
2596            BinaryOption, CryptoPerpetual, Instrument, InstrumentAny,
2597            stubs::{binary_option, crypto_perpetual_ethusdt},
2598        },
2599        orders::{
2600            Order, OrderAny, OrderTestBuilder,
2601            stubs::{OrderFilledTestBuilder, TestOrderEventStubs},
2602        },
2603        types::{Currency, Money, Price, Quantity},
2604    };
2605    use nautilus_system::{Controller, KernelEventStore, RegisteredComponents, trader::Trader};
2606    use nautilus_testkit::{
2607        cache::TestCacheDatabaseControl,
2608        components::{StateActor, StateStrategy},
2609    };
2610    use nautilus_trading::{
2611        nautilus_strategy,
2612        strategy::{config::StrategyConfig, core::StrategyCore},
2613    };
2614    #[cfg(feature = "python")]
2615    use pyo3::{prelude::*, types::PyDict};
2616    use rstest::*;
2617    #[cfg(feature = "python")]
2618    use rust_decimal::Decimal;
2619    use ustr::Ustr;
2620
2621    use super::*;
2622    use crate::modules::{
2623        AccountAdjustmentOutcome, ExchangeContext, SimulationModule, SimulationModuleHandle,
2624        SimulationModuleResult,
2625    };
2626    #[cfg(feature = "python")]
2627    use crate::python::engine::PyBacktestEngine;
2628    #[cfg(feature = "streaming")]
2629    use crate::{
2630        config::{BacktestRunConfig, BacktestVenueConfig},
2631        node::BacktestNode,
2632    };
2633
2634    #[derive(Debug)]
2635    struct BacktestReplayKernelEventStore {
2636        fail_restore: bool,
2637    }
2638
2639    impl KernelEventStore for BacktestReplayKernelEventStore {
2640        fn restore_parent_cache(
2641            &mut self,
2642            _instance_id: UUID4,
2643            _cache: &mut Cache,
2644        ) -> anyhow::Result<()> {
2645            if self.fail_restore {
2646                anyhow::bail!("replay restore failed");
2647            }
2648
2649            Ok(())
2650        }
2651
2652        fn open(
2653            &mut self,
2654            _instance_id: UUID4,
2655            _components: &RegisteredComponents,
2656            _environment: Environment,
2657        ) -> anyhow::Result<()> {
2658            Ok(())
2659        }
2660
2661        fn snapshot_anchorer(&self) -> Option<SnapshotAnchorer> {
2662            None
2663        }
2664
2665        fn seal(&mut self, _ts_init: UnixNanos) {}
2666
2667        fn run_id(&self) -> Option<&str> {
2668            Some("replay-child")
2669        }
2670
2671        fn parent_run_id(&self) -> Option<&str> {
2672            Some("seed-run")
2673        }
2674
2675        fn is_event_store_replay_configured(&self) -> bool {
2676            true
2677        }
2678
2679        fn is_halted(&self) -> bool {
2680            false
2681        }
2682    }
2683
2684    #[derive(Debug)]
2685    struct TestStrategy {
2686        core: StrategyCore,
2687    }
2688
2689    impl TestStrategy {
2690        fn new(config: StrategyConfig) -> Self {
2691            Self {
2692                core: StrategyCore::new(config),
2693            }
2694        }
2695    }
2696
2697    impl DataActor for TestStrategy {}
2698
2699    nautilus_strategy!(TestStrategy);
2700
2701    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
2702    enum ClockCreation {
2703        Start,
2704        Quote,
2705        Timer,
2706    }
2707
2708    type ClockEvents = Rc<RefCell<Vec<(u8, &'static str, u64)>>>;
2709
2710    #[derive(Debug)]
2711    struct DynamicClockActor {
2712        core: DataActorCore,
2713        events: ClockEvents,
2714        trader: Rc<RefCell<Trader>>,
2715        instrument_id: InstrumentId,
2716        creation: ClockCreation,
2717        generation: u8,
2718    }
2719
2720    impl DataActor for DynamicClockActor {
2721        fn on_start(&mut self) -> anyhow::Result<()> {
2722            self.subscribe_quotes(self.instrument_id, None, None);
2723            let now = self.clock().timestamp_ns().as_u64();
2724
2725            if self.generation == 0 {
2726                match self.creation {
2727                    ClockCreation::Start => self.spawn(1)?,
2728                    ClockCreation::Quote => {}
2729                    ClockCreation::Timer => {
2730                        self.clock().set_time_alert_ns(
2731                            "create-clock-actor",
2732                            UnixNanos::from(120),
2733                            None,
2734                            Some(false),
2735                        )?;
2736                    }
2737                }
2738            } else {
2739                self.events
2740                    .borrow_mut()
2741                    .push((self.generation, "start", now));
2742                let timer_name = format!("dynamic-clock-{}", self.generation);
2743
2744                let deadline = if self.generation == 1 { now + 20 } else { now };
2745                self.clock().set_time_alert_ns(
2746                    &timer_name,
2747                    UnixNanos::from(deadline),
2748                    None,
2749                    Some(false),
2750                )?;
2751            }
2752
2753            Ok(())
2754        }
2755
2756        fn on_quote(&mut self, quote: &QuoteTick) -> anyhow::Result<()> {
2757            if self.generation == 0 && self.creation == ClockCreation::Quote && quote.ts_init == 110
2758            {
2759                self.spawn(1)?;
2760            }
2761
2762            if self.generation == 1 && quote.ts_init == 160 {
2763                self.events.borrow_mut().push((
2764                    self.generation,
2765                    "quote",
2766                    self.clock().timestamp_ns().as_u64(),
2767                ));
2768            }
2769
2770            Ok(())
2771        }
2772
2773        fn on_time_event(&mut self, _event: &TimeEvent) -> anyhow::Result<()> {
2774            if self.generation == 0 {
2775                self.spawn(1)?;
2776            } else {
2777                self.events.borrow_mut().push((
2778                    self.generation,
2779                    "timer",
2780                    self.clock().timestamp_ns().as_u64(),
2781                ));
2782
2783                if self.generation == 1 {
2784                    self.spawn(2)?;
2785                }
2786            }
2787
2788            Ok(())
2789        }
2790
2791        fn on_stop(&mut self) -> anyhow::Result<()> {
2792            Ok(())
2793        }
2794    }
2795
2796    impl DynamicClockActor {
2797        fn spawn(&self, generation: u8) -> anyhow::Result<()> {
2798            let actor_id = ActorId::from(format!("DynamicClock-{generation}"));
2799
2800            let actor = Self {
2801                core: DataActorCore::new(DataActorConfig {
2802                    actor_id: Some(actor_id),
2803                    ..Default::default()
2804                }),
2805                events: self.events.clone(),
2806                trader: self.trader.clone(),
2807                instrument_id: self.instrument_id,
2808                creation: self.creation,
2809                generation,
2810            };
2811
2812            Controller::new(self.trader.clone(), None).create_actor(actor, true)?;
2813            Ok(())
2814        }
2815    }
2816
2817    nautilus_actor!(DynamicClockActor);
2818
2819    #[rstest]
2820    #[case::startup(ClockCreation::Start, false, 100)]
2821    #[case::quote(ClockCreation::Quote, false, 110)]
2822    #[case::timer(ClockCreation::Timer, false, 120)]
2823    #[case::tail(ClockCreation::Timer, true, 120)]
2824    fn test_dynamic_component_clocks_preserve_replay_order(
2825        #[case] creation: ClockCreation,
2826        #[case] tail: bool,
2827        #[case] creation_ns: u64,
2828        crypto_perpetual_ethusdt: CryptoPerpetual,
2829    ) {
2830        let mut engine = create_immediate_engine(&crypto_perpetual_ethusdt);
2831        let instrument_id = crypto_perpetual_ethusdt.id();
2832        let events = Rc::new(RefCell::new(Vec::new()));
2833        engine
2834            .add_actor(DynamicClockActor {
2835                core: DataActorCore::new(DataActorConfig {
2836                    actor_id: Some(ActorId::from("DynamicClock-0")),
2837                    ..Default::default()
2838                }),
2839                events: events.clone(),
2840                trader: engine.kernel.trader.clone(),
2841                instrument_id,
2842                creation,
2843                generation: 0,
2844            })
2845            .unwrap();
2846
2847        let quotes = if tail {
2848            vec![110u64]
2849        } else {
2850            vec![110u64, 160]
2851        };
2852
2853        let data = quotes
2854            .into_iter()
2855            .map(|timestamp| {
2856                let ts = UnixNanos::from(timestamp);
2857                Data::Quote(QuoteTick::new(
2858                    instrument_id,
2859                    Price::from("1000.00"),
2860                    Price::from("1001.00"),
2861                    Quantity::from("1.000"),
2862                    Quantity::from("2.000"),
2863                    ts,
2864                    ts,
2865                ))
2866            })
2867            .collect();
2868
2869        engine.add_data(data, None, true, true).unwrap();
2870
2871        engine
2872            .run(
2873                Some(UnixNanos::from(100)),
2874                Some(UnixNanos::from(200)),
2875                None,
2876                !tail,
2877            )
2878            .unwrap();
2879
2880        let mut expected = vec![
2881            (1, "start", creation_ns),
2882            (1, "timer", creation_ns + 20),
2883            (2, "start", creation_ns + 20),
2884            (2, "timer", creation_ns + 20),
2885        ];
2886
2887        if !tail {
2888            expected.push((1, "quote", 160));
2889        }
2890
2891        assert_eq!(*events.borrow(), expected);
2892        let clocks = engine.kernel.trader.borrow().get_component_clocks();
2893        assert_eq!(clocks.len(), 3);
2894
2895        for clock in clocks {
2896            let expected_ns = if tail { creation_ns + 20 } else { 160 };
2897            assert_eq!(clock.borrow().timestamp_ns().as_u64(), expected_ns);
2898        }
2899
2900        engine.dispose();
2901    }
2902
2903    // How the canceled order's submit and acceptance events come to be deferred
2904    #[derive(Clone, Copy, Debug)]
2905    enum DeferredAcceptance {
2906        // Limit order submitted earlier in the canceling handler
2907        Initialized,
2908        // Emulated stop-limit order released by the quote being handled
2909        Released,
2910        // OCO sibling of a leg submitted earlier in the canceling handler
2911        OcoSibling,
2912        // Take-profit and stop-loss parked by the venue until the bracket entry fills
2913        BracketChildren,
2914    }
2915
2916    // Cancels a resting order while its submit and acceptance events are deferred
2917    #[derive(Debug)]
2918    struct DeferredAcceptanceCancelStrategy {
2919        core: StrategyCore,
2920        instrument_id: InstrumentId,
2921        scenario: DeferredAcceptance,
2922        cancel_all: bool,
2923        quote_count: usize,
2924        target: Option<ClientOrderId>,
2925    }
2926
2927    impl DeferredAcceptanceCancelStrategy {
2928        const STRATEGY_ID: &str = "DEFERRED-CANCEL-001";
2929
2930        fn new(
2931            instrument_id: InstrumentId,
2932            scenario: DeferredAcceptance,
2933            cancel_all: bool,
2934        ) -> Self {
2935            Self {
2936                core: StrategyCore::new(StrategyConfig {
2937                    strategy_id: Some(StrategyId::from(Self::STRATEGY_ID)),
2938                    ..Default::default()
2939                }),
2940                instrument_id,
2941                scenario,
2942                cancel_all,
2943                quote_count: 0,
2944                target: None,
2945            }
2946        }
2947
2948        fn oco_leg(
2949            &self,
2950            client_order_id: &str,
2951            sibling_id: &str,
2952            side: OrderSide,
2953            price: &str,
2954        ) -> OrderAny {
2955            OrderTestBuilder::new(OrderType::Limit)
2956                .trader_id(self.trader_id().unwrap())
2957                .strategy_id(StrategyId::from(Self::STRATEGY_ID))
2958                .instrument_id(self.instrument_id)
2959                .client_order_id(ClientOrderId::from(client_order_id))
2960                .side(side)
2961                .quantity(Quantity::from("1.000"))
2962                .price(Price::from(price))
2963                .contingency_type(ContingencyType::Oco)
2964                .linked_order_ids(vec![ClientOrderId::from(sibling_id)])
2965                .build()
2966        }
2967
2968        fn submit(&mut self) -> anyhow::Result<()> {
2969            let instrument_id = self.instrument_id;
2970            let quantity = Quantity::from("1.000");
2971            let price = Price::from("900.00");
2972
2973            match self.scenario {
2974                DeferredAcceptance::Initialized => {
2975                    let order = self.order().limit(
2976                        instrument_id,
2977                        OrderSide::Buy,
2978                        quantity,
2979                        price,
2980                        None,
2981                        None,
2982                        None,
2983                        None,
2984                        None,
2985                        None,
2986                        None,
2987                        None,
2988                        None,
2989                        None,
2990                        None,
2991                        None,
2992                    );
2993                    self.target = Some(order.client_order_id());
2994                    self.submit_order(order, None, None, None)
2995                }
2996                DeferredAcceptance::Released => {
2997                    let order = self.order().stop_limit(
2998                        instrument_id,
2999                        OrderSide::Buy,
3000                        quantity,
3001                        price,
3002                        Price::from("1002.00"),
3003                        None,
3004                        None,
3005                        None,
3006                        None,
3007                        None,
3008                        None,
3009                        None,
3010                        Some(TriggerType::Default),
3011                        None,
3012                        None,
3013                        None,
3014                        None,
3015                        None,
3016                    );
3017                    self.target = Some(order.client_order_id());
3018                    self.submit_order(order, None, None, None)
3019                }
3020                DeferredAcceptance::OcoSibling => {
3021                    let leg = self.oco_leg("O-OCO-A", "O-OCO-B", OrderSide::Buy, "900.00");
3022                    let sibling = self.oco_leg("O-OCO-B", "O-OCO-A", OrderSide::Sell, "1100.00");
3023                    self.target = Some(leg.client_order_id());
3024                    self.submit_order_list(vec![leg, sibling], None, None, None)
3025                }
3026                DeferredAcceptance::BracketChildren => {
3027                    let orders = self
3028                        .order()
3029                        .bracket()
3030                        .instrument_id(instrument_id)
3031                        .order_side(OrderSide::Buy)
3032                        .quantity(quantity)
3033                        .entry_order_type(OrderType::Limit)
3034                        .entry_price(price)
3035                        .tp_price(Price::from("1100.00"))
3036                        .sl_trigger_price(Price::from("800.00"))
3037                        .call();
3038                    self.target = Some(orders[0].client_order_id());
3039                    self.submit_order_list(orders, None, None, None)
3040                }
3041            }
3042        }
3043    }
3044
3045    impl DataActor for DeferredAcceptanceCancelStrategy {
3046        fn on_start(&mut self) -> anyhow::Result<()> {
3047            self.subscribe_quotes(self.instrument_id, None, None);
3048            Ok(())
3049        }
3050
3051        fn on_quote(&mut self, _quote: &QuoteTick) -> anyhow::Result<()> {
3052            self.quote_count += 1;
3053
3054            if self.quote_count == 1 {
3055                self.submit()?;
3056            }
3057
3058            // The second quote triggers and releases the emulated order before this handler
3059            let cancel_quote = match self.scenario {
3060                DeferredAcceptance::Released => 2,
3061                DeferredAcceptance::Initialized
3062                | DeferredAcceptance::OcoSibling
3063                | DeferredAcceptance::BracketChildren => 1,
3064            };
3065
3066            if self.quote_count != cancel_quote {
3067                return Ok(());
3068            }
3069
3070            if self.cancel_all {
3071                self.cancel_all_orders(self.instrument_id, None, None, true, None)
3072            } else {
3073                self.cancel_order(self.target.unwrap(), None, None)
3074            }
3075        }
3076    }
3077
3078    nautilus_strategy!(DeferredAcceptanceCancelStrategy);
3079
3080    struct TestSimulationModule {
3081        process_count: Rc<Cell<u32>>,
3082    }
3083
3084    impl SimulationModule for TestSimulationModule {
3085        fn pre_process(&self, _data: &Data) -> anyhow::Result<()> {
3086            Ok(())
3087        }
3088
3089        fn process(
3090            &self,
3091            _ts_now: UnixNanos,
3092            _ctx: &ExchangeContext,
3093        ) -> anyhow::Result<SimulationModuleResult> {
3094            self.process_count.set(self.process_count.get() + 1);
3095            Ok(SimulationModuleResult::NotReady)
3096        }
3097
3098        fn acknowledge(&self, _outcomes: &[AccountAdjustmentOutcome]) -> anyhow::Result<()> {
3099            Ok(())
3100        }
3101
3102        fn log_diagnostics(&self) -> anyhow::Result<()> {
3103            Ok(())
3104        }
3105
3106        fn reset(&self) -> anyhow::Result<()> {
3107            Ok(())
3108        }
3109    }
3110
3111    fn create_engine() -> BacktestEngine {
3112        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
3113        let venue_config = SimulatedVenueConfig::builder()
3114            .venue(Venue::from("BINANCE"))
3115            .oms_type(OmsType::Netting)
3116            .account_type(AccountType::Margin)
3117            .book_type(BookType::L1_MBP)
3118            .starting_balances(vec![Money::from("1_000_000 USDT")])
3119            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
3120            .build()
3121            .unwrap();
3122        engine.add_venue(venue_config).unwrap();
3123        engine
3124    }
3125
3126    fn create_immediate_engine(instrument: &CryptoPerpetual) -> BacktestEngine {
3127        create_engine_with_message_queue(instrument, false)
3128    }
3129
3130    fn create_engine_with_message_queue(
3131        instrument: &CryptoPerpetual,
3132        use_message_queue: bool,
3133    ) -> BacktestEngine {
3134        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
3135        let venue_config = SimulatedVenueConfig::builder()
3136            .venue(instrument.id().venue)
3137            .oms_type(OmsType::Netting)
3138            .account_type(AccountType::Margin)
3139            .book_type(BookType::L1_MBP)
3140            .starting_balances(vec![Money::from("1_000_000 USDT")])
3141            .use_message_queue(use_message_queue)
3142            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
3143            .build()
3144            .unwrap();
3145        engine.add_venue(venue_config).unwrap();
3146        engine
3147            .add_instrument(&InstrumentAny::CryptoPerpetual(instrument.clone()))
3148            .unwrap();
3149        engine
3150            .venues
3151            .get(&instrument.id().venue)
3152            .unwrap()
3153            .borrow_mut()
3154            .initialize_account();
3155        engine
3156    }
3157
3158    fn create_engine_with_strategy(manage_stop: bool) -> (BacktestEngine, StrategyId) {
3159        let mut engine = create_engine();
3160        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt());
3161        let strategy_id = StrategyId::from(if manage_stop {
3162            "MANAGED-STOP-001"
3163        } else {
3164            "IMMEDIATE-STOP-001"
3165        });
3166        engine.add_instrument(&instrument).unwrap();
3167        engine
3168            .add_strategy(TestStrategy::new(StrategyConfig {
3169                strategy_id: Some(strategy_id),
3170                manage_stop,
3171                ..Default::default()
3172            }))
3173            .unwrap();
3174
3175        if manage_stop {
3176            let order = OrderTestBuilder::new(OrderType::Market)
3177                .trader_id(engine.trader_id())
3178                .strategy_id(strategy_id)
3179                .instrument_id(instrument.id())
3180                .side(OrderSide::Buy)
3181                .quantity(Quantity::from("1.000"))
3182                .build();
3183            let fill = OrderFilledTestBuilder::new(&order, &instrument).build();
3184            let OrderEventAny::Filled(fill) = fill else {
3185                unreachable!();
3186            };
3187            let position = Position::new(&instrument, fill);
3188            engine
3189                .kernel
3190                .cache
3191                .borrow_mut()
3192                .add_position_without_order(&position, OmsType::Netting)
3193                .unwrap();
3194        }
3195
3196        (engine, strategy_id)
3197    }
3198
3199    fn send_execution_command(command: TradingCommand) {
3200        msgbus::send_trading_command(MessagingSwitchboard::exec_engine_execute(), command);
3201    }
3202
3203    #[rstest]
3204    #[case(false, false, 0)]
3205    #[case(false, true, 1)]
3206    #[case(true, true, 1)]
3207    fn test_run_venue_modules_settles_only_when_enabled(
3208        #[case] first_enabled: bool,
3209        #[case] second_enabled: bool,
3210        #[case] expected_ns: u64,
3211    ) {
3212        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
3213        let process_count = Rc::new(Cell::new(0));
3214
3215        for (venue, enabled) in [
3216            (Venue::from("BINANCE"), first_enabled),
3217            (Venue::from("SIM"), second_enabled),
3218        ] {
3219            let modules = enabled
3220                .then(|| {
3221                    SimulationModuleHandle::new(TestSimulationModule {
3222                        process_count: Rc::clone(&process_count),
3223                    })
3224                })
3225                .into_iter()
3226                .collect();
3227            let venue_config = SimulatedVenueConfig::builder()
3228                .venue(venue)
3229                .oms_type(OmsType::Netting)
3230                .account_type(AccountType::Margin)
3231                .book_type(BookType::L1_MBP)
3232                .starting_balances(vec![Money::from("1_000_000 USDT")])
3233                .modules(modules)
3234                .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
3235                .build()
3236                .unwrap();
3237            engine.add_venue(venue_config).unwrap();
3238        }
3239
3240        engine
3241            .run_venue_modules(UnixNanos::from(1), SettlementScope::All)
3242            .unwrap();
3243
3244        assert_eq!(
3245            engine.kernel.clock.borrow().timestamp_ns(),
3246            UnixNanos::from(expected_ns)
3247        );
3248        assert_eq!(
3249            process_count.get(),
3250            u32::from(first_enabled) + u32::from(second_enabled)
3251        );
3252    }
3253
3254    #[rstest]
3255    #[case(false, false, 0)]
3256    #[case(false, true, 1)]
3257    #[case(true, true, 1)]
3258    fn test_run_venue_liquidations_settles_only_when_enabled(
3259        #[case] first_enabled: bool,
3260        #[case] second_enabled: bool,
3261        #[case] expected_ns: u64,
3262    ) {
3263        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
3264
3265        for (venue, enabled) in [
3266            (Venue::from("BINANCE"), first_enabled),
3267            (Venue::from("SIM"), second_enabled),
3268        ] {
3269            let venue_config = SimulatedVenueConfig::builder()
3270                .venue(venue)
3271                .oms_type(OmsType::Netting)
3272                .account_type(AccountType::Margin)
3273                .book_type(BookType::L1_MBP)
3274                .starting_balances(vec![Money::from("1_000_000 USDT")])
3275                .liquidation_enabled(enabled)
3276                .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
3277                .build()
3278                .unwrap();
3279            engine.add_venue(venue_config).unwrap();
3280        }
3281
3282        engine
3283            .run_venue_liquidations(UnixNanos::from(1), SettlementScope::All)
3284            .unwrap();
3285
3286        assert_eq!(
3287            engine.kernel.clock.borrow().timestamp_ns(),
3288            UnixNanos::from(expected_ns)
3289        );
3290    }
3291
3292    #[rstest]
3293    fn test_immediate_submit_defers_order_events(crypto_perpetual_ethusdt: CryptoPerpetual) {
3294        let engine = create_immediate_engine(&crypto_perpetual_ethusdt);
3295        let order = OrderTestBuilder::new(OrderType::Limit)
3296            .trader_id(engine.trader_id())
3297            .instrument_id(crypto_perpetual_ethusdt.id)
3298            .client_order_id(ClientOrderId::from("O-IMMEDIATE-SUBMIT"))
3299            .side(OrderSide::Buy)
3300            .quantity(Quantity::from("1.000"))
3301            .price(Price::from("1000.00"))
3302            .build();
3303        engine
3304            .kernel
3305            .cache
3306            .borrow_mut()
3307            .add_order(order.clone(), None, Some(ClientId::from("BINANCE")), false)
3308            .unwrap();
3309
3310        send_execution_command(TradingCommand::SubmitOrder(SubmitOrder::new(
3311            order.trader_id(),
3312            Some(ClientId::from("BINANCE")),
3313            order.strategy_id(),
3314            order.instrument_id(),
3315            order.client_order_id(),
3316            order.init_event().clone(),
3317            order.exec_algorithm_id(),
3318            None,
3319            None,
3320            UUID4::new(),
3321            UnixNanos::default(),
3322            None,
3323        )));
3324
3325        {
3326            let cache = engine.kernel.cache.borrow();
3327            let cached_order = cache.order(&order.client_order_id()).unwrap();
3328            assert_eq!(cached_order.status(), OrderStatus::Initialized);
3329            assert_eq!(cached_order.event_count(), 1);
3330        }
3331
3332        engine.drain_command_queues().unwrap();
3333
3334        let cache = engine.kernel.cache.borrow();
3335        let cached_order = cache.order(&order.client_order_id()).unwrap();
3336        let events = cached_order.events();
3337        assert!(matches!(events[1], OrderEventAny::Submitted(_)));
3338        assert!(matches!(events[2], OrderEventAny::Accepted(_)));
3339    }
3340
3341    #[rstest]
3342    fn test_immediate_modify_submitted_order_defers_updated_event(
3343        crypto_perpetual_ethusdt: CryptoPerpetual,
3344    ) {
3345        let engine = create_immediate_engine(&crypto_perpetual_ethusdt);
3346        let order = OrderTestBuilder::new(OrderType::Limit)
3347            .trader_id(engine.trader_id())
3348            .instrument_id(crypto_perpetual_ethusdt.id)
3349            .client_order_id(ClientOrderId::from("O-IMMEDIATE-MODIFY"))
3350            .side(OrderSide::Buy)
3351            .quantity(Quantity::from("1.000"))
3352            .price(Price::from("1000.00"))
3353            .build();
3354        let account_id = AccountId::from("BINANCE-001");
3355        engine
3356            .kernel
3357            .cache
3358            .borrow_mut()
3359            .add_order(order.clone(), None, Some(ClientId::from("BINANCE")), false)
3360            .unwrap();
3361        engine
3362            .kernel
3363            .cache
3364            .borrow_mut()
3365            .update_order(&TestOrderEventStubs::submitted(&order, account_id))
3366            .unwrap();
3367
3368        send_execution_command(TradingCommand::ModifyOrder(ModifyOrder::new(
3369            order.trader_id(),
3370            Some(ClientId::from("BINANCE")),
3371            order.strategy_id(),
3372            order.instrument_id(),
3373            order.client_order_id(),
3374            None,
3375            Some(Quantity::from("2.000")),
3376            None,
3377            None,
3378            UUID4::new(),
3379            UnixNanos::from(1),
3380            None,
3381            None,
3382        )));
3383
3384        {
3385            let cache = engine.kernel.cache.borrow();
3386            let cached_order = cache.order(&order.client_order_id()).unwrap();
3387            assert_eq!(cached_order.quantity(), Quantity::from("1.000"));
3388            assert!(matches!(
3389                cached_order.events().last(),
3390                Some(OrderEventAny::Submitted(_))
3391            ));
3392        }
3393
3394        engine.drain_command_queues().unwrap();
3395
3396        let cache = engine.kernel.cache.borrow();
3397        let order = cache.order(&order.client_order_id()).unwrap();
3398        assert_eq!(order.quantity(), Quantity::from("2.000"));
3399        assert!(matches!(
3400            order.events().last(),
3401            Some(OrderEventAny::Updated(_))
3402        ));
3403    }
3404
3405    #[rstest]
3406    fn test_immediate_modifies_preserve_pending_quantity_and_matching_price(
3407        crypto_perpetual_ethusdt: CryptoPerpetual,
3408    ) {
3409        let engine = create_immediate_engine(&crypto_perpetual_ethusdt);
3410        let order = OrderTestBuilder::new(OrderType::Limit)
3411            .trader_id(engine.trader_id())
3412            .instrument_id(crypto_perpetual_ethusdt.id)
3413            .client_order_id(ClientOrderId::from("O-IMMEDIATE-MODIFY-FILL"))
3414            .side(OrderSide::Buy)
3415            .quantity(Quantity::from("1.000"))
3416            .price(Price::from("1000.00"))
3417            .build();
3418        engine
3419            .kernel
3420            .cache
3421            .borrow_mut()
3422            .add_order(order.clone(), None, Some(ClientId::from("BINANCE")), false)
3423            .unwrap();
3424        send_execution_command(TradingCommand::SubmitOrder(SubmitOrder::new(
3425            order.trader_id(),
3426            Some(ClientId::from("BINANCE")),
3427            order.strategy_id(),
3428            order.instrument_id(),
3429            order.client_order_id(),
3430            order.init_event().clone(),
3431            order.exec_algorithm_id(),
3432            None,
3433            None,
3434            UUID4::new(),
3435            UnixNanos::default(),
3436            None,
3437        )));
3438        engine.drain_command_queues().unwrap();
3439
3440        for (quantity, price) in [
3441            (Some(Quantity::from("2.000")), None),
3442            (None, Some(Price::from("1005.00"))),
3443        ] {
3444            send_execution_command(TradingCommand::ModifyOrder(ModifyOrder::new(
3445                order.trader_id(),
3446                Some(ClientId::from("BINANCE")),
3447                order.strategy_id(),
3448                order.instrument_id(),
3449                order.client_order_id(),
3450                None,
3451                quantity,
3452                price,
3453                None,
3454                UUID4::new(),
3455                UnixNanos::from(1),
3456                None,
3457                None,
3458            )));
3459        }
3460        {
3461            let cache = engine.kernel.cache.borrow();
3462            let cached = cache.order(&order.client_order_id()).unwrap();
3463            assert_eq!(cached.quantity(), Quantity::from("1.000"));
3464            assert_eq!(cached.price(), Some(Price::from("1000.00")));
3465            assert_eq!(cached.event_count(), 3);
3466        }
3467        engine.drain_command_queues().unwrap();
3468        {
3469            let cache = engine.kernel.cache.borrow();
3470            let cached = cache.order(&order.client_order_id()).unwrap();
3471            assert_eq!(cached.quantity(), Quantity::from("2.000"));
3472            assert_eq!(cached.price(), Some(Price::from("1005.00")));
3473            assert_eq!(cached.event_count(), 5);
3474        }
3475
3476        let quote = QuoteTick::new(
3477            order.instrument_id(),
3478            Price::from("1003.00"),
3479            Price::from("1004.00"),
3480            Quantity::from("3.000"),
3481            Quantity::from("4.000"),
3482            UnixNanos::from(2),
3483            UnixNanos::from(2),
3484        );
3485        msgbus::send_quote(
3486            format!(
3487                "SimulatedExchange.process_new_quote.{}",
3488                order.instrument_id().venue
3489            )
3490            .into(),
3491            &quote,
3492        );
3493        let cache = engine.kernel.cache.borrow();
3494        let cached = cache.order(&order.client_order_id()).unwrap();
3495        assert_eq!(cached.status(), OrderStatus::Filled);
3496        assert_eq!(cached.quantity(), Quantity::from("2.000"));
3497        assert_eq!(cached.filled_qty(), Quantity::from("2.000"));
3498        assert_eq!(cached.leaves_qty(), Quantity::from("0.000"));
3499        assert_eq!(cached.event_count(), 6);
3500        let OrderEventAny::Filled(fill) = cached.last_event() else {
3501            panic!("Expected final fill");
3502        };
3503        assert_eq!(fill.last_px, Price::from("1005.00"));
3504        assert_eq!(fill.last_qty, Quantity::from("2.000"));
3505        assert_eq!(fill.liquidity_side, LiquiditySide::Maker);
3506    }
3507
3508    #[rstest]
3509    #[case::immediate(false)]
3510    #[case::queued(true)]
3511    fn test_batch_reduce_only_modifies_share_position_quantity(
3512        crypto_perpetual_ethusdt: CryptoPerpetual,
3513        #[case] use_message_queue: bool,
3514        #[values(false, true)] first_reduce_only: bool,
3515    ) {
3516        let instrument = crypto_perpetual_ethusdt;
3517        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
3518        let venue_config = SimulatedVenueConfig::builder()
3519            .venue(instrument.id().venue)
3520            .oms_type(OmsType::Netting)
3521            .account_type(AccountType::Margin)
3522            .book_type(BookType::L1_MBP)
3523            .starting_balances(vec![Money::from("1_000_000 USDT")])
3524            .use_message_queue(use_message_queue)
3525            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
3526            .build()
3527            .unwrap();
3528        engine.add_venue(venue_config).unwrap();
3529        engine
3530            .add_instrument(&InstrumentAny::CryptoPerpetual(instrument.clone()))
3531            .unwrap();
3532        let exchange = engine.venues.get(&instrument.id().venue).unwrap().clone();
3533        exchange.borrow_mut().initialize_account();
3534        msgbus::send_quote(
3535            format!(
3536                "SimulatedExchange.process_new_quote.{}",
3537                instrument.id().venue
3538            )
3539            .into(),
3540            &QuoteTick::new(
3541                instrument.id(),
3542                Price::from("1000.00"),
3543                Price::from("1001.00"),
3544                Quantity::from("1.000"),
3545                Quantity::from("1.000"),
3546                UnixNanos::default(),
3547                UnixNanos::default(),
3548            ),
3549        );
3550        let opening = OrderTestBuilder::new(OrderType::Market)
3551            .trader_id(engine.trader_id())
3552            .instrument_id(instrument.id())
3553            .client_order_id(ClientOrderId::from("O-OPEN-SHORT"))
3554            .side(OrderSide::Sell)
3555            .quantity(Quantity::from("0.500"))
3556            .build();
3557        let closing =
3558            [("O-CLOSE-FIRST", "0.400"), ("O-CLOSE-SECOND", "0.300")].map(|(id, quantity)| {
3559                OrderTestBuilder::new(OrderType::Limit)
3560                    .trader_id(engine.trader_id())
3561                    .instrument_id(instrument.id())
3562                    .client_order_id(ClientOrderId::from(id))
3563                    .side(OrderSide::Buy)
3564                    .quantity(Quantity::from(quantity))
3565                    .price(Price::from("999.00"))
3566                    .reduce_only(id != "O-CLOSE-FIRST" || first_reduce_only)
3567                    .build()
3568            });
3569
3570        for order in [&opening, &closing[0], &closing[1]] {
3571            engine
3572                .kernel
3573                .cache
3574                .borrow_mut()
3575                .add_order(order.clone(), None, Some(ClientId::from("BINANCE")), false)
3576                .unwrap();
3577            send_execution_command(TradingCommand::SubmitOrder(SubmitOrder::new(
3578                order.trader_id(),
3579                Some(ClientId::from("BINANCE")),
3580                order.strategy_id(),
3581                order.instrument_id(),
3582                order.client_order_id(),
3583                order.init_event().clone(),
3584                order.exec_algorithm_id(),
3585                None,
3586                None,
3587                UUID4::new(),
3588                UnixNanos::default(),
3589                None,
3590            )));
3591            engine.drain_command_queues().unwrap();
3592            exchange.borrow_mut().process(UnixNanos::default());
3593            engine.drain_command_queues().unwrap();
3594        }
3595        {
3596            let cache = engine.kernel.cache.borrow();
3597            let position = cache
3598                .position_for_order(&opening.client_order_id())
3599                .unwrap();
3600            assert!(position.is_short());
3601            assert_eq!(position.quantity, Quantity::from("0.500"));
3602
3603            for order in &closing {
3604                let cached = cache.order(&order.client_order_id()).unwrap();
3605                assert_eq!(cached.status(), OrderStatus::Accepted);
3606                assert_eq!(cached.quantity(), order.quantity());
3607                assert_eq!(cached.filled_qty(), Quantity::from("0.000"));
3608            }
3609        }
3610        let modifies = closing
3611            .iter()
3612            .map(|order| {
3613                ModifyOrder::new(
3614                    order.trader_id(),
3615                    Some(ClientId::from("BINANCE")),
3616                    order.strategy_id(),
3617                    order.instrument_id(),
3618                    order.client_order_id(),
3619                    None,
3620                    None,
3621                    Some(Price::from("1002.00")),
3622                    None,
3623                    UUID4::new(),
3624                    UnixNanos::from(1),
3625                    None,
3626                    None,
3627                )
3628            })
3629            .collect();
3630        exchange.borrow_mut().process(UnixNanos::from(1));
3631        send_execution_command(TradingCommand::ModifyOrders(BatchModifyOrders::new(
3632            opening.trader_id(),
3633            Some(ClientId::from("BINANCE")),
3634            opening.strategy_id(),
3635            opening.instrument_id(),
3636            modifies,
3637            UUID4::new(),
3638            UnixNanos::from(1),
3639            None,
3640            None,
3641        )));
3642        engine.drain_command_queues().unwrap();
3643        exchange.borrow_mut().process(UnixNanos::from(1));
3644        engine.drain_command_queues().unwrap();
3645
3646        let cache = engine.kernel.cache.borrow();
3647        let filled = closing
3648            .each_ref()
3649            .map(|order| cache.order(&order.client_order_id()).unwrap().filled_qty());
3650        let position = cache
3651            .position_for_order(&opening.client_order_id())
3652            .unwrap();
3653        assert_eq!(
3654            (filled, position.side, position.quantity),
3655            (
3656                [Quantity::from("0.400"), Quantity::from("0.100")],
3657                PositionSide::Flat,
3658                Quantity::from("0.000"),
3659            ),
3660        );
3661    }
3662
3663    #[rstest]
3664    fn test_immediate_market_data_dispatches_fill_synchronously(
3665        crypto_perpetual_ethusdt: CryptoPerpetual,
3666    ) {
3667        let engine = create_immediate_engine(&crypto_perpetual_ethusdt);
3668        let order = OrderTestBuilder::new(OrderType::Limit)
3669            .trader_id(engine.trader_id())
3670            .instrument_id(crypto_perpetual_ethusdt.id)
3671            .client_order_id(ClientOrderId::from("O-IMMEDIATE-QUOTE-FILL"))
3672            .side(OrderSide::Buy)
3673            .quantity(Quantity::from("1.000"))
3674            .price(Price::from("1000.00"))
3675            .build();
3676        engine
3677            .kernel
3678            .cache
3679            .borrow_mut()
3680            .add_order(order.clone(), None, Some(ClientId::from("BINANCE")), false)
3681            .unwrap();
3682
3683        send_execution_command(TradingCommand::SubmitOrder(SubmitOrder::new(
3684            order.trader_id(),
3685            Some(ClientId::from("BINANCE")),
3686            order.strategy_id(),
3687            order.instrument_id(),
3688            order.client_order_id(),
3689            order.init_event().clone(),
3690            order.exec_algorithm_id(),
3691            None,
3692            None,
3693            UUID4::new(),
3694            UnixNanos::default(),
3695            None,
3696        )));
3697        engine.drain_command_queues().unwrap();
3698
3699        let quote = QuoteTick::new(
3700            order.instrument_id(),
3701            Price::from("999.00"),
3702            Price::from("1000.00"),
3703            Quantity::from("1.000"),
3704            Quantity::from("1.000"),
3705            UnixNanos::from(1),
3706            UnixNanos::from(1),
3707        );
3708        msgbus::send_quote(
3709            format!(
3710                "SimulatedExchange.process_new_quote.{}",
3711                order.instrument_id().venue
3712            )
3713            .into(),
3714            &quote,
3715        );
3716
3717        let cache = engine.kernel.cache.borrow();
3718        let cached_order = cache.order(&order.client_order_id()).unwrap();
3719        assert_eq!(cached_order.status(), OrderStatus::Filled);
3720        assert!(matches!(
3721            cached_order.events().last(),
3722            Some(OrderEventAny::Filled(_))
3723        ));
3724    }
3725
3726    #[rstest]
3727    fn test_immediate_cancel_of_order_with_deferred_acceptance(
3728        #[values(
3729            DeferredAcceptance::Initialized,
3730            DeferredAcceptance::Released,
3731            DeferredAcceptance::OcoSibling,
3732            DeferredAcceptance::BracketChildren
3733        )]
3734        scenario: DeferredAcceptance,
3735        #[values(true, false)] cancel_all: bool,
3736        crypto_perpetual_ethusdt: CryptoPerpetual,
3737    ) {
3738        let mut engine = create_immediate_engine(&crypto_perpetual_ethusdt);
3739        let instrument_id = crypto_perpetual_ethusdt.id;
3740        engine
3741            .add_strategy(DeferredAcceptanceCancelStrategy::new(
3742                instrument_id,
3743                scenario,
3744                cancel_all,
3745            ))
3746            .unwrap();
3747        let quote = |bid: &str, ask: &str, ts: u64| {
3748            Data::Quote(QuoteTick::new(
3749                instrument_id,
3750                Price::from(bid),
3751                Price::from(ask),
3752                Quantity::from("1.000"),
3753                Quantity::from("1.000"),
3754                UnixNanos::from(ts),
3755                UnixNanos::from(ts),
3756            ))
3757        };
3758        engine
3759            .add_data(
3760                vec![
3761                    quote("1000.00", "1001.00", 1),
3762                    quote("1002.00", "1003.00", 2),
3763                ],
3764                None,
3765                true,
3766                true,
3767            )
3768            .unwrap();
3769
3770        engine.run(None, None, None, false).unwrap();
3771
3772        assert!(
3773            engine.venues[&instrument_id.venue]
3774                .borrow()
3775                .get_open_orders(Some(instrument_id))
3776                .is_empty()
3777        );
3778        let cache = engine.kernel.cache.borrow();
3779        let orders = cache.orders(None, Some(&instrument_id), None, None, None);
3780        let expected_orders = match scenario {
3781            DeferredAcceptance::BracketChildren => 3,
3782            DeferredAcceptance::OcoSibling => 2,
3783            DeferredAcceptance::Initialized | DeferredAcceptance::Released => 1,
3784        };
3785        assert_eq!(orders.len(), expected_orders);
3786
3787        for order in &orders {
3788            assert_eq!(order.status(), OrderStatus::Canceled);
3789            let events = order.events();
3790
3791            // Parked bracket children are canceled before the venue accepts them
3792            let matched = if order.parent_order_id().is_some() {
3793                matches!(
3794                    events.as_slice(),
3795                    [
3796                        OrderEventAny::Initialized(_),
3797                        OrderEventAny::Submitted(_),
3798                        OrderEventAny::Canceled(_),
3799                    ]
3800                )
3801            } else {
3802                matches!(
3803                    events.as_slice(),
3804                    [
3805                        ..,
3806                        OrderEventAny::Submitted(_),
3807                        OrderEventAny::Accepted(_),
3808                        OrderEventAny::Canceled(_),
3809                    ]
3810                )
3811            };
3812            assert!(matched, "unexpected events {events:?}");
3813        }
3814    }
3815
3816    // Cancels a bracket's parked take-profit, then lets the entry fill on a later quote
3817    #[derive(Debug)]
3818    struct CancelParkedChildStrategy {
3819        core: StrategyCore,
3820        instrument_id: InstrumentId,
3821        same_handler: bool,
3822        quote_count: usize,
3823        take_profit: Option<ClientOrderId>,
3824    }
3825
3826    impl CancelParkedChildStrategy {
3827        fn new(instrument_id: InstrumentId, same_handler: bool) -> Self {
3828            Self {
3829                core: StrategyCore::new(StrategyConfig {
3830                    strategy_id: Some(StrategyId::from("PARKED-CANCEL-001")),
3831                    ..Default::default()
3832                }),
3833                instrument_id,
3834                same_handler,
3835                quote_count: 0,
3836                take_profit: None,
3837            }
3838        }
3839    }
3840
3841    impl DataActor for CancelParkedChildStrategy {
3842        fn on_start(&mut self) -> anyhow::Result<()> {
3843            self.subscribe_quotes(self.instrument_id, None, None);
3844            Ok(())
3845        }
3846
3847        fn on_quote(&mut self, _quote: &QuoteTick) -> anyhow::Result<()> {
3848            self.quote_count += 1;
3849
3850            if self.quote_count == 1 {
3851                let instrument_id = self.instrument_id;
3852                let orders = self
3853                    .order()
3854                    .bracket()
3855                    .instrument_id(instrument_id)
3856                    .order_side(OrderSide::Buy)
3857                    .quantity(Quantity::from("1.000"))
3858                    .entry_order_type(OrderType::Limit)
3859                    .entry_price(Price::from("1000.00"))
3860                    .tp_price(Price::from("1100.00"))
3861                    .sl_trigger_price(Price::from("800.00"))
3862                    .call();
3863                self.take_profit = orders
3864                    .iter()
3865                    .find(|order| {
3866                        order.order_type() == OrderType::Limit && order.parent_order_id().is_some()
3867                    })
3868                    .map(Order::client_order_id);
3869                self.submit_order_list(orders, None, None, None)?;
3870            }
3871
3872            let cancel_quote = if self.same_handler { 1 } else { 2 };
3873
3874            if self.quote_count == cancel_quote {
3875                self.cancel_order(self.take_profit.unwrap(), None, None)?;
3876            }
3877            Ok(())
3878        }
3879    }
3880
3881    nautilus_strategy!(CancelParkedChildStrategy);
3882
3883    #[rstest]
3884    fn test_cancel_parked_oto_child_stays_canceled_after_entry_fills(
3885        #[values(false, true)] use_message_queue: bool,
3886        #[values(false, true)] same_handler: bool,
3887        crypto_perpetual_ethusdt: CryptoPerpetual,
3888    ) {
3889        let mut engine =
3890            create_engine_with_message_queue(&crypto_perpetual_ethusdt, use_message_queue);
3891        let instrument_id = crypto_perpetual_ethusdt.id;
3892        engine
3893            .add_strategy(CancelParkedChildStrategy::new(instrument_id, same_handler))
3894            .unwrap();
3895        let quote = |bid: &str, ask: &str, ts: u64| {
3896            Data::Quote(QuoteTick::new(
3897                instrument_id,
3898                Price::from(bid),
3899                Price::from(ask),
3900                Quantity::from("1.000"),
3901                Quantity::from("1.000"),
3902                UnixNanos::from(ts),
3903                UnixNanos::from(ts),
3904            ))
3905        };
3906        engine
3907            .add_data(
3908                vec![
3909                    quote("999.00", "1001.00", 1),
3910                    quote("999.00", "1001.00", 2),
3911                    quote("999.00", "1000.00", 3),
3912                ],
3913                None,
3914                true,
3915                true,
3916            )
3917            .unwrap();
3918
3919        engine.run(None, None, None, false).unwrap();
3920
3921        assert!(
3922            engine.venues[&instrument_id.venue]
3923                .borrow()
3924                .get_open_orders(Some(instrument_id))
3925                .is_empty()
3926        );
3927        let cache = engine.kernel.cache.borrow();
3928        let orders = cache.orders(None, Some(&instrument_id), None, None, None);
3929        assert_eq!(orders.len(), 3);
3930
3931        for order in &orders {
3932            // Canceling the take-profit also cancels its OUO stop-loss
3933            let expected = if order.parent_order_id().is_some() {
3934                OrderStatus::Canceled
3935            } else {
3936                OrderStatus::Filled
3937            };
3938            assert_eq!(
3939                order.status(),
3940                expected,
3941                "unexpected events {:?}",
3942                order.events()
3943            );
3944        }
3945    }
3946
3947    // Submits a bracket whose post-only entry crosses, then starts a market exit
3948    #[derive(Debug)]
3949    struct RejectedEntryExitStrategy {
3950        core: StrategyCore,
3951        instrument_id: InstrumentId,
3952        quote_count: usize,
3953        exits: Rc<Cell<usize>>,
3954    }
3955
3956    impl DataActor for RejectedEntryExitStrategy {
3957        fn on_start(&mut self) -> anyhow::Result<()> {
3958            self.subscribe_quotes(self.instrument_id, None, None);
3959            Ok(())
3960        }
3961
3962        fn on_quote(&mut self, _quote: &QuoteTick) -> anyhow::Result<()> {
3963            self.quote_count += 1;
3964
3965            match self.quote_count {
3966                1 => {
3967                    let instrument_id = self.instrument_id;
3968                    let orders = self
3969                        .order()
3970                        .bracket()
3971                        .instrument_id(instrument_id)
3972                        .order_side(OrderSide::Buy)
3973                        .quantity(Quantity::from("1.000"))
3974                        .entry_order_type(OrderType::Limit)
3975                        .entry_price(Price::from("1001.00"))
3976                        .entry_post_only(true)
3977                        .tp_price(Price::from("1100.00"))
3978                        .sl_trigger_price(Price::from("800.00"))
3979                        .call();
3980                    self.submit_order_list(orders, None, None, None)
3981                }
3982                2 => self.market_exit(),
3983                _ => Ok(()),
3984            }
3985        }
3986    }
3987
3988    nautilus_strategy!(RejectedEntryExitStrategy, {
3989        fn post_market_exit(&mut self) {
3990            self.exits.set(self.exits.get() + 1);
3991        }
3992    });
3993
3994    #[rstest]
3995    fn test_rejected_oto_parent_rejects_children_and_market_exit_completes(
3996        #[values(false, true)] use_message_queue: bool,
3997        crypto_perpetual_ethusdt: CryptoPerpetual,
3998    ) {
3999        let mut engine =
4000            create_engine_with_message_queue(&crypto_perpetual_ethusdt, use_message_queue);
4001        let instrument_id = crypto_perpetual_ethusdt.id;
4002        let exits = Rc::new(Cell::new(0));
4003        engine
4004            .add_strategy(RejectedEntryExitStrategy {
4005                core: StrategyCore::new(StrategyConfig {
4006                    strategy_id: Some(StrategyId::from("REJECTED-ENTRY-001")),
4007                    ..Default::default()
4008                }),
4009                instrument_id,
4010                quote_count: 0,
4011                exits: Rc::clone(&exits),
4012            })
4013            .unwrap();
4014        let quotes = [1, 2, 3]
4015            .into_iter()
4016            .map(|secs: u64| {
4017                let ts = UnixNanos::from(secs * 1_000_000_000);
4018                Data::Quote(QuoteTick::new(
4019                    instrument_id,
4020                    Price::from("1000.00"),
4021                    Price::from("1001.00"),
4022                    Quantity::from("1.000"),
4023                    Quantity::from("1.000"),
4024                    ts,
4025                    ts,
4026                ))
4027            })
4028            .collect();
4029        engine.add_data(quotes, None, true, true).unwrap();
4030
4031        engine.run(None, None, None, false).unwrap();
4032
4033        let cache = engine.kernel.cache.borrow();
4034        let orders = cache.orders(None, Some(&instrument_id), None, None, None);
4035        assert_eq!(orders.len(), 3);
4036
4037        for order in &orders {
4038            assert_eq!(
4039                order.status(),
4040                OrderStatus::Rejected,
4041                "unexpected events {:?}",
4042                order.events()
4043            );
4044        }
4045        assert_eq!(exits.get(), 1);
4046    }
4047
4048    // Submits a bracket whose market entry is larger than the top-of-book size
4049    #[derive(Debug)]
4050    struct MultiStepEntryStrategy {
4051        core: StrategyCore,
4052        instrument_id: InstrumentId,
4053        submitted: bool,
4054    }
4055
4056    impl DataActor for MultiStepEntryStrategy {
4057        fn on_start(&mut self) -> anyhow::Result<()> {
4058            self.subscribe_quotes(self.instrument_id, None, None);
4059            Ok(())
4060        }
4061
4062        fn on_quote(&mut self, _quote: &QuoteTick) -> anyhow::Result<()> {
4063            if self.submitted {
4064                return Ok(());
4065            }
4066            self.submitted = true;
4067            let orders = self
4068                .order()
4069                .bracket()
4070                .instrument_id(self.instrument_id)
4071                .order_side(OrderSide::Buy)
4072                .quantity(Quantity::from("2.000"))
4073                .tp_price(Price::from("1100.00"))
4074                .sl_trigger_price(Price::from("800.00"))
4075                .call();
4076            self.submit_order_list(orders, None, None, None)
4077        }
4078    }
4079
4080    nautilus_strategy!(MultiStepEntryStrategy);
4081
4082    #[rstest]
4083    fn test_full_trigger_market_entry_filling_in_steps_releases_children(
4084        crypto_perpetual_ethusdt: CryptoPerpetual,
4085    ) {
4086        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
4087        let instrument_id = crypto_perpetual_ethusdt.id;
4088        let venue_config = SimulatedVenueConfig::builder()
4089            .venue(instrument_id.venue)
4090            .oms_type(OmsType::Netting)
4091            .account_type(AccountType::Margin)
4092            .book_type(BookType::L1_MBP)
4093            .starting_balances(vec![Money::from("1_000_000 USDT")])
4094            .oto_full_trigger(true)
4095            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
4096            .build()
4097            .unwrap();
4098        engine.add_venue(venue_config).unwrap();
4099        engine
4100            .add_instrument(&InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt))
4101            .unwrap();
4102        engine
4103            .add_strategy(MultiStepEntryStrategy {
4104                core: StrategyCore::new(StrategyConfig {
4105                    strategy_id: Some(StrategyId::from("MULTI-STEP-001")),
4106                    ..Default::default()
4107                }),
4108                instrument_id,
4109                submitted: false,
4110            })
4111            .unwrap();
4112        let quotes = [1, 2]
4113            .into_iter()
4114            .map(|secs: u64| {
4115                let ts = UnixNanos::from(secs * 1_000_000_000);
4116                Data::Quote(QuoteTick::new(
4117                    instrument_id,
4118                    Price::from("1000.00"),
4119                    Price::from("1001.00"),
4120                    Quantity::from("1.000"),
4121                    Quantity::from("1.000"),
4122                    ts,
4123                    ts,
4124                ))
4125            })
4126            .collect();
4127        engine.add_data(quotes, None, true, true).unwrap();
4128
4129        engine.run(None, None, None, false).unwrap();
4130
4131        let cache = engine.kernel.cache.borrow();
4132        let orders = cache.orders(None, Some(&instrument_id), None, None, None);
4133        assert_eq!(orders.len(), 3);
4134
4135        for order in &orders {
4136            let fill_count = order
4137                .events()
4138                .iter()
4139                .filter(|event| matches!(event, OrderEventAny::Filled(_)))
4140                .count();
4141            let expected = if order.parent_order_id().is_none() {
4142                assert!(fill_count > 1, "entry filled in {fill_count} step(s)");
4143                OrderStatus::Filled
4144            } else {
4145                OrderStatus::Accepted
4146            };
4147            assert_eq!(
4148                order.status(),
4149                expected,
4150                "unexpected events {:?}",
4151                order.events()
4152            );
4153        }
4154    }
4155
4156    #[rstest]
4157    #[case::strategy(&["ROLL"], true)]
4158    #[case::snapshots(&["portfolio_equity_curve.SIM-001", "portfolio_snapshot.SIM-001"], false)]
4159    #[case::strategy_first(&["a_strategy", "portfolio_equity_curve.SIM-001"], true)]
4160    #[case::strategy_last(&["portfolio_equity_curve.SIM-001", "z_strategy"], true)]
4161    fn test_timer_handler_sets_last_ns_to_fire_time(
4162        #[case] timer_names: &[&str],
4163        #[case] settle_all: bool,
4164    ) {
4165        let mut engine = create_engine();
4166        engine.last_ns = UnixNanos::from(30);
4167        let fired = Rc::new(Cell::new(0));
4168        let fired_clone = Rc::clone(&fired);
4169        let callback = TimeEventCallback::RustLocal(Rc::new(move |_| {
4170            fired_clone.set(fired_clone.get() + 1);
4171        }));
4172
4173        for name in timer_names {
4174            engine
4175                .kernel
4176                .clock
4177                .borrow_mut()
4178                .set_timer_ns(
4179                    name,
4180                    DurationNanos::new(1),
4181                    Some(UnixNanos::from(20)),
4182                    None,
4183                    Some(callback.clone()),
4184                    Some(true),
4185                    Some(true),
4186                )
4187                .unwrap();
4188        }
4189
4190        let clocks = engine.collect_all_clocks();
4191
4192        for clock in clocks.iter() {
4193            BacktestEngine::advance_clock_on_accumulator(
4194                &mut engine.accumulator,
4195                clock,
4196                UnixNanos::from(30),
4197            );
4198        }
4199
4200        let settlement_scope = engine.run_timer_handlers_at(UnixNanos::from(20)).unwrap();
4201
4202        assert_eq!(fired.get(), timer_names.len());
4203        assert_eq!(engine.last_ns, UnixNanos::from(20));
4204        assert_eq!(matches!(settlement_scope, SettlementScope::All), settle_all);
4205        assert_eq!(
4206            matches!(settlement_scope, SettlementScope::Data(None)),
4207            !settle_all,
4208        );
4209    }
4210
4211    #[rstest]
4212    #[case::complete(false, 25)]
4213    #[case::shutdown(true, 20)]
4214    fn test_flush_accumulator_events_sets_last_ns_for_completion(
4215        #[case] shutdown: bool,
4216        #[case] expected_last_ns: u64,
4217    ) {
4218        let mut engine = create_engine();
4219        let last_ns = UnixNanos::from(25);
4220        let ts_now = UnixNanos::from(30);
4221        engine.last_ns = last_ns;
4222        let clocks = engine.collect_all_clocks();
4223        BacktestEngine::set_all_clocks_time(&clocks, last_ns);
4224        let fired = Rc::new(Cell::new(false));
4225        let fired_clone = Rc::clone(&fired);
4226        let observed_ns = Rc::new(Cell::new(UnixNanos::default()));
4227        let observed_ns_clone = Rc::clone(&observed_ns);
4228        let clock = Rc::clone(&engine.kernel.clock);
4229        let shutdown_requested = engine.kernel.shutdown_flag();
4230        let callback = TimeEventCallback::RustLocal(Rc::new(move |_| {
4231            fired_clone.set(true);
4232            observed_ns_clone.set(clock.borrow().timestamp_ns());
4233            shutdown_requested.set(shutdown);
4234        }));
4235        engine
4236            .kernel
4237            .clock
4238            .borrow_mut()
4239            .set_timer_ns(
4240                "ROLL",
4241                DurationNanos::new(100),
4242                Some(UnixNanos::from(20)),
4243                None,
4244                Some(callback),
4245                Some(true),
4246                Some(true),
4247            )
4248            .unwrap();
4249
4250        engine.flush_accumulator_events(ts_now).unwrap();
4251
4252        assert!(fired.get());
4253        assert_eq!(observed_ns.get(), UnixNanos::from(20));
4254        assert_eq!(engine.kernel.is_shutdown_requested(), shutdown);
4255        assert_eq!(engine.last_ns, UnixNanos::from(expected_last_ns));
4256    }
4257
4258    // Returns an engine with `instrument` registered and a quote in its book
4259    fn engine_with_quoted_instrument(instrument: &InstrumentAny) -> BacktestEngine {
4260        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
4261        let venue = instrument.id().venue;
4262        let venue_config = SimulatedVenueConfig::builder()
4263            .venue(venue)
4264            .oms_type(OmsType::Netting)
4265            .account_type(AccountType::Margin)
4266            .book_type(BookType::L1_MBP)
4267            .starting_balances(vec![Money::from("1_000_000 USDT")])
4268            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
4269            .build()
4270            .unwrap();
4271        engine.add_venue(venue_config).unwrap();
4272        engine.add_instrument(instrument).unwrap();
4273        let quote = QuoteTick::new(
4274            instrument.id(),
4275            Price::from("1000.00"),
4276            Price::from("1001.00"),
4277            Quantity::from("1.000"),
4278            Quantity::from("1.000"),
4279            UnixNanos::default(),
4280            UnixNanos::default(),
4281        );
4282        msgbus::send_quote(
4283            format!("SimulatedExchange.process_new_quote.{venue}").into(),
4284            &quote,
4285        );
4286        engine
4287    }
4288
4289    fn assert_original_registration_kept(engine: &BacktestEngine, instrument: &InstrumentAny) {
4290        let instrument_id = instrument.id();
4291        let exchange = engine.venues.get(&instrument_id.venue).unwrap().borrow();
4292        let matching_engine = exchange.get_matching_engine(&instrument_id).unwrap();
4293        assert_eq!(matching_engine.raw_id, 1);
4294        assert_eq!(
4295            exchange.best_bid_price(instrument_id),
4296            Some(Price::from("1000.00"))
4297        );
4298        assert_eq!(
4299            exchange.best_ask_price(instrument_id),
4300            Some(Price::from("1001.00"))
4301        );
4302        let cache = engine.kernel.cache.borrow();
4303        let cached = cache.instrument(&instrument_id).unwrap();
4304        assert_eq!(Instrument::ts_init(cached), Instrument::ts_init(instrument));
4305        assert_eq!(cached.max_quantity(), instrument.max_quantity());
4306    }
4307
4308    #[rstest]
4309    fn test_readd_identical_instrument_keeps_matching_engine(
4310        crypto_perpetual_ethusdt: CryptoPerpetual,
4311    ) {
4312        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt.clone());
4313        let mut engine = engine_with_quoted_instrument(&instrument);
4314        let mut restamped = crypto_perpetual_ethusdt;
4315        restamped.ts_event = UnixNanos::from(5);
4316        restamped.ts_init = UnixNanos::from(5);
4317
4318        engine
4319            .add_instrument(&InstrumentAny::CryptoPerpetual(restamped))
4320            .unwrap();
4321
4322        assert_original_registration_kept(&engine, &instrument);
4323    }
4324
4325    #[rstest]
4326    fn test_readd_changed_instrument_is_rejected_and_keeps_matching_engine(
4327        crypto_perpetual_ethusdt: CryptoPerpetual,
4328    ) {
4329        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt.clone());
4330        let mut engine = engine_with_quoted_instrument(&instrument);
4331        let mut changed = crypto_perpetual_ethusdt;
4332        changed.max_quantity = Some(Quantity::from("1.000"));
4333
4334        let result = engine.add_instrument(&InstrumentAny::CryptoPerpetual(changed));
4335
4336        assert_eq!(
4337            result.unwrap_err().to_string(),
4338            "Instrument ETHUSDT-PERP.BINANCE is already registered with a different definition"
4339        );
4340        assert_original_registration_kept(&engine, &instrument);
4341    }
4342
4343    #[rstest]
4344    #[case::unchanged("0.01", "0.01", false)]
4345    #[case::finer("0.10", "0.01", true)]
4346    #[case::coarser("0.01", "0.10", true)]
4347    #[case::precision("0.01", "0.001", true)]
4348    fn test_replay_instrument_updates_perpetual(
4349        mut crypto_perpetual_ethusdt: CryptoPerpetual,
4350        #[case] initial_tick: &str,
4351        #[case] revised_tick: &str,
4352        #[case] clears_book: bool,
4353    ) {
4354        crypto_perpetual_ethusdt.price_increment = Price::from(initial_tick);
4355        let original = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt.clone());
4356        let id = original.id();
4357        let mut engine = engine_with_quoted_instrument(&original);
4358        let cache = engine.kernel.cache();
4359        let exchange = Rc::clone(&engine.venues[&id.venue]);
4360        let observed = Rc::new(Cell::new(0));
4361        let received = Rc::clone(&observed);
4362        let updated_exchange = Rc::clone(&exchange);
4363        let order_id = ClientOrderId::from("O-REPLAY-UPDATE");
4364        let order = OrderTestBuilder::new(OrderType::Limit)
4365            .trader_id(engine.trader_id())
4366            .instrument_id(id)
4367            .client_order_id(order_id)
4368            .side(OrderSide::Buy)
4369            .quantity(Quantity::from("1.000"))
4370            .price(Price::from("1000.00") + original.price_increment())
4371            .build();
4372        let order_cache = Rc::clone(&cache);
4373        msgbus::subscribe_instruments(
4374            nautilus_common::msgbus::switchboard::get_instruments_pattern(id.venue),
4375            TypedHandler::from(move |instrument: &InstrumentAny| {
4376                let exchange = updated_exchange.borrow();
4377                let matching = exchange.get_matching_engine(&id).unwrap();
4378                let increment = instrument.price_increment();
4379                assert_eq!(matching.instrument.price_increment(), increment);
4380                assert_eq!(matching.get_core().price_increment, increment);
4381                drop(exchange);
4382
4383                if received.get() == 0 {
4384                    order_cache
4385                        .borrow_mut()
4386                        .add_order(order.clone(), None, None, false)
4387                        .unwrap();
4388                    send_execution_command(TradingCommand::SubmitOrder(
4389                        create_submit_order_command(&order),
4390                    ));
4391                }
4392
4393                received.set(received.get() + 1);
4394            }),
4395            None,
4396        );
4397
4398        let increment = Price::from(revised_tick);
4399        crypto_perpetual_ethusdt.price_precision = increment.precision;
4400        crypto_perpetual_ethusdt.price_increment = increment;
4401
4402        let quote = QuoteTick::new(
4403            id,
4404            Price::from("1000.00"),
4405            Price::from("1001.00"),
4406            Quantity::from("1.000"),
4407            Quantity::from("1.000"),
4408            1.into(),
4409            1.into(),
4410        );
4411        let mut data = vec![
4412            Data::Instrument(Box::new(original.clone())),
4413            Data::Quote(quote),
4414        ];
4415        data.extend([2, 3].map(|timestamp| {
4416            let mut revised = crypto_perpetual_ethusdt.clone();
4417            revised.ts_event = UnixNanos::from(timestamp);
4418            revised.ts_init = UnixNanos::from(timestamp);
4419            Data::Instrument(Box::new(InstrumentAny::CryptoPerpetual(revised)))
4420        }));
4421
4422        engine.add_data(data, None, true, true).unwrap();
4423        for _ in 0..2 {
4424            engine.run(None, None, None, false).unwrap();
4425            assert_eq!(observed.replace(0), 3);
4426            assert_eq!(
4427                cache.borrow().instrument(&id).unwrap().price_increment(),
4428                increment
4429            );
4430            assert_eq!(
4431                cache.borrow().order(&order_id).unwrap().status(),
4432                if revised_tick == "0.10" {
4433                    OrderStatus::Canceled
4434                } else {
4435                    OrderStatus::Accepted
4436                }
4437            );
4438            {
4439                let exchange = exchange.borrow();
4440                let matching = exchange.get_matching_engine(&id).unwrap();
4441                assert_eq!(matching.raw_id, 1);
4442                assert_eq!(matching.instrument.price_precision(), increment.precision);
4443                assert_eq!(exchange.best_bid_price(id).is_none(), clears_book);
4444            }
4445
4446            engine.reset().unwrap();
4447        }
4448
4449        assert_eq!(
4450            cache.borrow().instrument(&id).unwrap().price_increment(),
4451            original.price_increment()
4452        );
4453        let exchange = exchange.borrow();
4454        let matching = exchange.get_matching_engine(&id).unwrap();
4455        assert_eq!(
4456            matching.get_core().price_increment,
4457            original.price_increment()
4458        );
4459    }
4460
4461    #[rstest]
4462    fn test_replay_expiration_timer_preserves_latency(
4463        #[values(2, 5)] revision_ns: u64,
4464        #[values(false, true)] shared: bool,
4465        #[values(false, true)] settled: bool,
4466    ) {
4467        let mut binary_option = replay_binary_option(5, "0.01");
4468        let original = InstrumentAny::BinaryOption(binary_option.clone());
4469        let id = original.id();
4470        let mut engine = engine_with_quoted_instrument(&original);
4471        let exchange = Rc::clone(&engine.venues[&id.venue]);
4472        let mut traded = binary_option.clone();
4473        traded.id = InstrumentId::from("TRADED.POLYMARKET");
4474        traded.expiration_ns = UnixNanos::from(30);
4475        let traded_id = traded.id;
4476        engine
4477            .add_instrument(&InstrumentAny::BinaryOption(traded))
4478            .unwrap();
4479        exchange
4480            .borrow_mut()
4481            .set_latency_model(LatencyModelHandle::new(StaticLatencyModel::new(
4482                DurationNanos::default(),
4483                DurationNanos::new(if settled { 10 } else { 5 }),
4484                DurationNanos::default(),
4485                DurationNanos::default(),
4486            )));
4487
4488        if shared {
4489            let mut sibling = binary_option.clone();
4490            sibling.id = InstrumentId::from("SHARED.POLYMARKET");
4491            engine
4492                .add_instrument(&InstrumentAny::BinaryOption(sibling))
4493                .unwrap();
4494        }
4495
4496        let order = OrderTestBuilder::new(OrderType::Market)
4497            .trader_id(engine.trader_id())
4498            .instrument_id(traded_id)
4499            .side(OrderSide::Buy)
4500            .quantity(Quantity::from("1.000"))
4501            .build();
4502        let cache = engine.kernel.cache();
4503        cache
4504            .borrow_mut()
4505            .add_order(order.clone(), None, None, false)
4506            .unwrap();
4507        send_execution_command(TradingCommand::SubmitOrder(create_submit_order_command(
4508            &order,
4509        )));
4510        engine.drain_command_queues().unwrap();
4511        binary_option.expiration_ns = UnixNanos::from(10);
4512        binary_option.ts_init = UnixNanos::from(revision_ns);
4513        let quote = |price: &str, ts: u64| {
4514            Data::Quote(QuoteTick::new(
4515                traded_id,
4516                Price::from(price),
4517                Price::from(price),
4518                Quantity::from("1.000"),
4519                Quantity::from("1.000"),
4520                ts.into(),
4521                ts.into(),
4522            ))
4523        };
4524        let mut data = Vec::new();
4525
4526        if settled {
4527            data.push(Data::InstrumentClose(InstrumentClose::new(
4528                id,
4529                Price::from("1.00"),
4530                InstrumentCloseType::ContractExpired,
4531                0.into(),
4532                0.into(),
4533            )));
4534        }
4535        data.extend([
4536            quote("0.50", 1),
4537            Data::Instrument(Box::new(InstrumentAny::BinaryOption(binary_option))),
4538            quote("0.70", if settled { 11 } else { 6 }),
4539        ]);
4540        engine.add_data(data, None, true, true).unwrap();
4541
4542        engine.run(None, None, None, false).unwrap();
4543
4544        let exchange = exchange.borrow();
4545        let matching = exchange.get_matching_engine(&id).unwrap();
4546        assert_eq!(matching.is_expiration_processed(), settled);
4547        assert_eq!(
4548            matching.market_status,
4549            if settled {
4550                MarketStatus::Closed
4551            } else {
4552                MarketStatus::Open
4553            }
4554        );
4555        let cache = cache.borrow();
4556        let order = cache.order(&order.client_order_id()).unwrap();
4557        let filled = order
4558            .events()
4559            .into_iter()
4560            .find_map(|event| match event {
4561                OrderEventAny::Filled(fill) => Some(fill),
4562                _ => None,
4563            })
4564            .unwrap();
4565        assert_eq!(
4566            filled.last_px,
4567            Price::from(if shared && !settled { "0.50" } else { "0.70" })
4568        );
4569        assert_eq!(
4570            filled.ts_event,
4571            UnixNanos::from(if settled {
4572                11
4573            } else if shared {
4574                5
4575            } else {
4576                6
4577            })
4578        );
4579    }
4580
4581    #[rstest]
4582    #[case::unchanged("0.01", "0.01", 10, 10)]
4583    #[case::finer("0.10", "0.01", 10, 10)]
4584    #[case::coarser("0.01", "0.10", 10, 10)]
4585    #[case::precision("0.01", "0.001", 10, 10)]
4586    #[case::later("0.01", "0.01", 5, 10)]
4587    #[case::earlier("0.01", "0.01", 10, 5)]
4588    #[case::at_expiration("0.01", "0.01", 2, 10)]
4589    #[case::pending_resolution("0.01", "0.01", 1, 10)]
4590    #[case::past_due("0.01", "0.01", 10, 1)]
4591    #[case::due_now("0.01", "0.01", 10, 2)]
4592    #[case::no_expiration("0.01", "0.01", 1, 0)]
4593    fn test_replay_instrument_updates_binary_option(
4594        #[case] initial_tick: &str,
4595        #[case] revised_tick: &str,
4596        #[case] initial_expiration: u64,
4597        #[case] revised_expiration: u64,
4598        #[values(None, Some(MarketStatusAction::Close), Some(MarketStatusAction::Pause))]
4599        status: Option<MarketStatusAction>,
4600    ) {
4601        let mut binary_option = replay_binary_option(initial_expiration, initial_tick);
4602        let original = InstrumentAny::BinaryOption(binary_option.clone());
4603        let id = original.id();
4604        let mut engine = engine_with_quoted_instrument(&original);
4605        let cache = engine.kernel.cache();
4606        let exchange = Rc::clone(&engine.venues[&id.venue]);
4607        let mut sibling = binary_option.clone();
4608        sibling.id = InstrumentId::from("SHARED.POLYMARKET");
4609        let sibling_id = sibling.id;
4610        engine
4611            .add_instrument(&InstrumentAny::BinaryOption(sibling))
4612            .unwrap();
4613        let observed = Rc::new(Cell::new(0));
4614        let received = Rc::clone(&observed);
4615        let updated_exchange = Rc::clone(&exchange);
4616        let order_id = ClientOrderId::from("O-REPLAY-UPDATE");
4617        let order = OrderTestBuilder::new(OrderType::Limit)
4618            .trader_id(engine.trader_id())
4619            .instrument_id(id)
4620            .client_order_id(order_id)
4621            .side(OrderSide::Buy)
4622            .quantity(Quantity::from("1.000"))
4623            .price(Price::from("0.30") + original.price_increment())
4624            .build();
4625        let order_cache = Rc::clone(&cache);
4626        msgbus::subscribe_instruments(
4627            nautilus_common::msgbus::switchboard::get_instruments_pattern(id.venue),
4628            TypedHandler::from(move |instrument: &InstrumentAny| {
4629                let exchange = updated_exchange.borrow();
4630                let matching = exchange.get_matching_engine(&id).unwrap();
4631                let increment = instrument.price_increment();
4632                assert_eq!(matching.instrument.price_increment(), increment);
4633                assert_eq!(matching.get_core().price_increment, increment);
4634                assert_eq!(
4635                    matching.instrument.expiration_ns(),
4636                    instrument.expiration_ns()
4637                );
4638
4639                if revised_expiration == 1 && received.get() > 0 {
4640                    assert_eq!(matching.market_status, MarketStatus::Closed);
4641                }
4642                drop(exchange);
4643
4644                if received.get() == 0 {
4645                    order_cache
4646                        .borrow_mut()
4647                        .add_order(order.clone(), None, None, false)
4648                        .unwrap();
4649                    send_execution_command(TradingCommand::SubmitOrder(
4650                        create_submit_order_command(&order),
4651                    ));
4652                }
4653                received.set(received.get() + 1);
4654            }),
4655            None,
4656        );
4657        let increment = Price::from(revised_tick);
4658        binary_option.price_precision = increment.precision;
4659        binary_option.price_increment = increment;
4660        binary_option.expiration_ns = UnixNanos::from(revised_expiration);
4661        let quote = QuoteTick::new(
4662            id,
4663            Price::from("0.40"),
4664            Price::from("0.50"),
4665            Quantity::from("1.000"),
4666            Quantity::from("1.000"),
4667            1.into(),
4668            1.into(),
4669        );
4670        let mut data = vec![
4671            Data::Instrument(Box::new(original.clone())),
4672            Data::Quote(quote),
4673        ];
4674
4675        if let Some(status) = status {
4676            data.push(Data::InstrumentStatus(InstrumentStatus::new(
4677                id,
4678                status,
4679                1.into(),
4680                1.into(),
4681                None,
4682                None,
4683                None,
4684                None,
4685                None,
4686            )));
4687        }
4688        data.extend([2, 3].map(|timestamp| {
4689            let mut revised = binary_option.clone();
4690            revised.ts_event = UnixNanos::from(timestamp);
4691            revised.ts_init = UnixNanos::from(timestamp);
4692            Data::Instrument(Box::new(InstrumentAny::BinaryOption(revised)))
4693        }));
4694        data.push(Data::IndexPrice(IndexPriceUpdate::new(
4695            id,
4696            Price::from("0.40"),
4697            7.into(),
4698            7.into(),
4699        )));
4700        engine.add_data(data, None, true, true).unwrap();
4701
4702        for _ in 0..2 {
4703            let order = OrderTestBuilder::new(OrderType::Market)
4704                .trader_id(engine.trader_id())
4705                .instrument_id(id)
4706                .side(OrderSide::Buy)
4707                .quantity(Quantity::from("1.000"))
4708                .build();
4709            let fill = OrderFilledTestBuilder::new(&order, &original)
4710                .last_px(Price::from("0.40"))
4711                .account_id(AccountId::from("POLYMARKET-001"))
4712                .commission(Money::from("0 USDT"))
4713                .build();
4714            let position = Position::new(&original, fill.into());
4715            cache
4716                .borrow_mut()
4717                .add_position(&position, OmsType::Netting)
4718                .unwrap();
4719            engine.run(None, None, None, false).unwrap();
4720            assert_eq!(observed.replace(0), 3);
4721            assert_eq!(
4722                cache.borrow().instrument(&id).unwrap().price_increment(),
4723                increment
4724            );
4725            assert_eq!(
4726                cache.borrow().order(&order_id).unwrap().status(),
4727                if revised_tick == "0.10"
4728                    || initial_expiration == 1
4729                    || (revised_expiration != 0 && revised_expiration <= 7)
4730                {
4731                    OrderStatus::Canceled
4732                } else {
4733                    OrderStatus::Accepted
4734                }
4735            );
4736            {
4737                let exchange = exchange.borrow();
4738                let matching = exchange.get_matching_engine(&id).unwrap();
4739                assert_eq!(matching.raw_id, 1);
4740                assert_eq!(matching.instrument.price_precision(), increment.precision);
4741                assert_eq!(
4742                    exchange.best_bid_price(id).is_none(),
4743                    initial_tick != revised_tick
4744                );
4745                assert_eq!(
4746                    matching.market_status,
4747                    match status {
4748                        _ if revised_expiration != 0 && revised_expiration <= 7 =>
4749                            MarketStatus::Closed,
4750                        Some(MarketStatusAction::Close) => MarketStatus::Closed,
4751                        Some(MarketStatusAction::Pause) => MarketStatus::Paused,
4752                        _ => MarketStatus::Open,
4753                    }
4754                );
4755                let sibling = exchange.get_matching_engine(&sibling_id).unwrap();
4756                assert_eq!(
4757                    sibling.market_status,
4758                    if initial_expiration <= 7 {
4759                        MarketStatus::Closed
4760                    } else {
4761                        MarketStatus::Open
4762                    }
4763                );
4764            }
4765            assert!(cache.borrow().position(&position.id).unwrap().is_open());
4766            engine.reset().unwrap();
4767            assert!(engine.kernel.clock.borrow().timer_names().is_empty());
4768        }
4769        assert_eq!(
4770            cache.borrow().instrument(&id).unwrap().price_increment(),
4771            original.price_increment()
4772        );
4773        assert_eq!(
4774            cache.borrow().instrument(&id).unwrap().expiration_ns(),
4775            original.expiration_ns()
4776        );
4777        let exchange = exchange.borrow();
4778        let matching = exchange.get_matching_engine(&id).unwrap();
4779        assert_eq!(
4780            matching.get_core().price_increment,
4781            original.price_increment()
4782        );
4783        assert_eq!(
4784            matching.instrument.expiration_ns(),
4785            original.expiration_ns()
4786        );
4787    }
4788
4789    fn replay_binary_option(expiration_ns: u64, price_increment: &str) -> BinaryOption {
4790        let mut option = binary_option();
4791        option.currency = Currency::USDT();
4792        option.activation_ns = UnixNanos::default();
4793        option.expiration_ns = UnixNanos::from(expiration_ns);
4794        option.price_increment = Price::from(price_increment);
4795        option.price_precision = option.price_increment.precision;
4796        option.size_precision = 3;
4797        option
4798    }
4799
4800    #[cfg(feature = "streaming")]
4801    #[rstest]
4802    fn test_node_forwards_order_priority_reset_policy(
4803        crypto_perpetual_ethusdt: CryptoPerpetual,
4804        #[values(
4805            OrderPriorityResetPolicy::PriceChange,
4806            OrderPriorityResetPolicy::PriceOrQuantityIncrease,
4807            OrderPriorityResetPolicy::AnyModify
4808        )]
4809        policy: OrderPriorityResetPolicy,
4810    ) {
4811        let venue = BacktestVenueConfig::builder()
4812            .name("BINANCE")
4813            .oms_type(OmsType::Netting)
4814            .account_type(AccountType::Margin)
4815            .book_type(BookType::L1_MBP)
4816            .starting_balances(vec!["1_000_000 USDT".to_string()])
4817            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()))
4818            .order_priority_reset_policy(policy)
4819            .build()
4820            .unwrap();
4821        let config = BacktestRunConfig::builder()
4822            .venues(vec![venue])
4823            .data(Vec::new())
4824            .build()
4825            .unwrap();
4826        let config_id = config.id().to_string();
4827        let mut node = BacktestNode::new(vec![config]).unwrap();
4828        node.build().unwrap();
4829        let engine = node.get_engine_mut(&config_id).unwrap();
4830        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt);
4831        engine.add_instrument(&instrument).unwrap();
4832        let exchange = engine.venues.get(&Venue::from("BINANCE")).unwrap().borrow();
4833        let matching_engine = exchange.get_matching_engine(&instrument.id()).unwrap();
4834
4835        assert_eq!(matching_engine.config.order_priority_reset_policy, policy);
4836    }
4837
4838    #[cfg(feature = "python")]
4839    #[rstest]
4840    fn test_python_add_venue_forwards_order_priority_reset_policy(
4841        crypto_perpetual_ethusdt: CryptoPerpetual,
4842        #[values(
4843            OrderPriorityResetPolicy::PriceChange,
4844            OrderPriorityResetPolicy::PriceOrQuantityIncrease,
4845            OrderPriorityResetPolicy::AnyModify
4846        )]
4847        policy: OrderPriorityResetPolicy,
4848    ) {
4849        Python::initialize();
4850        Python::attach(|py| {
4851            let engine = py
4852                .get_type::<PyBacktestEngine>()
4853                .call1((BacktestEngineConfig::default(),))
4854                .unwrap();
4855            let kwargs = PyDict::new(py);
4856            let fee_model = py
4857                .get_type::<MakerTakerFeeModel>()
4858                .call1((Decimal::ZERO, Decimal::ZERO))
4859                .unwrap();
4860            kwargs.set_item("fee_model", fee_model).unwrap();
4861            kwargs
4862                .set_item("order_priority_reset_policy", policy)
4863                .unwrap();
4864            engine
4865                .call_method(
4866                    "add_venue",
4867                    (
4868                        Venue::from("BINANCE"),
4869                        OmsType::Netting,
4870                        AccountType::Margin,
4871                        vec![Money::from("1_000_000 USDT")],
4872                    ),
4873                    Some(&kwargs),
4874                )
4875                .unwrap();
4876            let mut engine = engine.extract::<PyRefMut<'_, PyBacktestEngine>>().unwrap();
4877            let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt);
4878            engine.inner_mut().add_instrument(&instrument).unwrap();
4879            let exchange = engine
4880                .inner()
4881                .venues
4882                .get(&Venue::from("BINANCE"))
4883                .unwrap()
4884                .borrow();
4885            let matching_engine = exchange.get_matching_engine(&instrument.id()).unwrap();
4886
4887            assert_eq!(matching_engine.config.order_priority_reset_policy, policy);
4888        });
4889    }
4890
4891    #[rstest]
4892    fn test_add_duplicate_venue_preserves_original_exchange(
4893        crypto_perpetual_ethusdt: CryptoPerpetual,
4894    ) {
4895        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
4896        let venue = Venue::from("BINANCE");
4897        let venue_config = SimulatedVenueConfig::builder()
4898            .venue(venue)
4899            .oms_type(OmsType::Netting)
4900            .account_type(AccountType::Margin)
4901            .book_type(BookType::L1_MBP)
4902            .starting_balances(vec![Money::from("1_000_000 USDT")])
4903            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
4904            .build()
4905            .unwrap();
4906        engine.add_venue(venue_config).unwrap();
4907
4908        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt);
4909        let instrument_id = instrument.id();
4910        engine.add_instrument(&instrument).unwrap();
4911
4912        let initial_quote = QuoteTick::new(
4913            instrument_id,
4914            Price::from("1000.00"),
4915            Price::from("1001.00"),
4916            Quantity::from("1.000"),
4917            Quantity::from("1.000"),
4918            UnixNanos::from(1),
4919            UnixNanos::from(1),
4920        );
4921        msgbus::send_quote(
4922            format!("SimulatedExchange.process_new_quote.{venue}").into(),
4923            &initial_quote,
4924        );
4925
4926        let best_bid_before = engine
4927            .venues
4928            .get(&venue)
4929            .unwrap()
4930            .borrow()
4931            .best_bid_price(instrument_id);
4932        let best_ask_before = engine
4933            .venues
4934            .get(&venue)
4935            .unwrap()
4936            .borrow()
4937            .best_ask_price(instrument_id);
4938        let original_exchange = Rc::downgrade(engine.venues.get(&venue).unwrap());
4939        let venues_before = engine.list_venues();
4940        let exec_clients_len_before = engine.exec_clients.len();
4941        let client_ids_before = engine.kernel.exec_engine.borrow().client_ids();
4942        let duplicate_config = SimulatedVenueConfig::builder()
4943            .venue(venue)
4944            .oms_type(OmsType::Netting)
4945            .account_type(AccountType::Margin)
4946            .book_type(BookType::L1_MBP)
4947            .starting_balances(vec![Money::from("1_000_000 USDT")])
4948            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
4949            .build()
4950            .unwrap();
4951        assert!(engine.add_venue(duplicate_config).is_err());
4952
4953        let original_exchange = original_exchange
4954            .upgrade()
4955            .expect("the original exchange must remain alive");
4956        assert!(Rc::ptr_eq(
4957            &original_exchange,
4958            engine.venues.get(&venue).unwrap()
4959        ));
4960        assert_eq!(engine.list_venues(), venues_before);
4961        assert_eq!(engine.exec_clients.len(), exec_clients_len_before);
4962        assert_eq!(
4963            engine.kernel.exec_engine.borrow().client_ids(),
4964            client_ids_before
4965        );
4966
4967        let distinct_quote = QuoteTick::new(
4968            instrument_id,
4969            Price::from("2000.00"),
4970            Price::from("2001.00"),
4971            Quantity::from("2.000"),
4972            Quantity::from("2.000"),
4973            UnixNanos::from(2),
4974            UnixNanos::from(2),
4975        );
4976        msgbus::send_quote(
4977            format!("SimulatedExchange.process_new_quote.{venue}").into(),
4978            &distinct_quote,
4979        );
4980
4981        let original_exchange = original_exchange.borrow();
4982        let best_bid_after = original_exchange.best_bid_price(instrument_id);
4983        let best_ask_after = original_exchange.best_ask_price(instrument_id);
4984        assert_ne!(best_bid_after, best_bid_before);
4985        assert_ne!(best_ask_after, best_ask_before);
4986        assert_eq!(best_bid_after, Some(Price::from("2000.00")));
4987        assert_eq!(best_ask_after, Some(Price::from("2001.00")));
4988    }
4989
4990    #[rstest]
4991    #[case::duplicate_client(false)]
4992    #[case::occupied_route(true)]
4993    fn test_add_venue_execution_registration_failure_publishes_nothing(
4994        #[case] occupied_route: bool,
4995    ) {
4996        let mut engine = BacktestEngine::new(BacktestEngineConfig::default()).unwrap();
4997        let venue = Venue::from("SIM");
4998        let client_id = ClientId::from(if occupied_route { "OTHER" } else { "SIM" });
4999        engine
5000            .kernel
5001            .exec_engine
5002            .borrow_mut()
5003            .register_client(Box::new(StubExecutionClient::new(
5004                client_id,
5005                AccountId::from("SIM-001"),
5006                venue,
5007                OmsType::Netting,
5008                None,
5009            )))
5010            .unwrap();
5011        engine
5012            .kernel
5013            .exec_engine
5014            .borrow_mut()
5015            .register_venue_routing(client_id, venue)
5016            .unwrap();
5017        let client_ids_before = engine.kernel.exec_engine.borrow().client_ids();
5018
5019        let endpoint = format!("SimulatedExchange.process_new_quote.{venue}");
5020        let received_quotes = Rc::new(RefCell::new(Vec::new()));
5021        let received_quotes_handler = Rc::clone(&received_quotes);
5022        let sentinel = TypedHandler::from_with_id("venue-setup-sentinel", move |quote| {
5023            received_quotes_handler.borrow_mut().push(*quote);
5024        });
5025        msgbus::register_quote_endpoint(endpoint.as_str().into(), sentinel);
5026
5027        let venue_config = SimulatedVenueConfig::builder()
5028            .venue(venue)
5029            .oms_type(OmsType::Netting)
5030            .account_type(AccountType::Margin)
5031            .book_type(BookType::L1_MBP)
5032            .starting_balances(vec![Money::from("1_000_000 USD")])
5033            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
5034            .build()
5035            .unwrap();
5036        assert!(engine.add_venue(venue_config).is_err());
5037
5038        assert!(!engine.venues.contains_key(&venue));
5039        assert!(engine.exec_clients.is_empty());
5040        assert_eq!(
5041            engine.kernel.exec_engine.borrow().client_ids(),
5042            client_ids_before
5043        );
5044
5045        let quote = QuoteTick::new(
5046            InstrumentId::from("TEST.SIM"),
5047            Price::from("100.00"),
5048            Price::from("101.00"),
5049            Quantity::from("1"),
5050            Quantity::from("1"),
5051            UnixNanos::from(1),
5052            UnixNanos::from(1),
5053        );
5054        msgbus::send_quote(endpoint.as_str().into(), &quote);
5055        assert_eq!(received_quotes.borrow().as_slice(), &[quote]);
5056    }
5057
5058    #[rstest]
5059    fn test_add_strategy_registers_configured_hedging_oms_type() {
5060        let mut engine = create_engine();
5061        let instrument = crypto_perpetual_ethusdt();
5062        let strategy_id = StrategyId::from("FUNDING_ARBITRAGE-001");
5063
5064        engine
5065            .add_instrument(&InstrumentAny::CryptoPerpetual(instrument.clone()))
5066            .unwrap();
5067        engine
5068            .add_strategy(TestStrategy::new(StrategyConfig {
5069                strategy_id: Some(strategy_id),
5070                oms_type: Some(OmsType::Hedging),
5071                ..Default::default()
5072            }))
5073            .unwrap();
5074
5075        let order = OrderTestBuilder::new(OrderType::Market)
5076            .trader_id(engine.trader_id())
5077            .strategy_id(strategy_id)
5078            .instrument_id(instrument.id())
5079            .quantity(Quantity::from("1.000"))
5080            .build();
5081        let position_id = PositionId::new("CUSTOM-POSITION-001");
5082
5083        engine
5084            .kernel
5085            .exec_engine
5086            .borrow()
5087            .cache()
5088            .borrow_mut()
5089            .add_order(
5090                order.clone(),
5091                Some(position_id),
5092                Some(ClientId::from("BINANCE")),
5093                true,
5094            )
5095            .unwrap();
5096
5097        let submit_order = SubmitOrder::new(
5098            order.trader_id(),
5099            Some(ClientId::from("BINANCE")),
5100            strategy_id,
5101            instrument.id(),
5102            order.client_order_id(),
5103            order.init_event().clone(),
5104            order.exec_algorithm_id(),
5105            Some(position_id),
5106            None,
5107            UUID4::new(),
5108            UnixNanos::default(),
5109            None,
5110        );
5111
5112        engine
5113            .kernel
5114            .exec_engine
5115            .borrow()
5116            .execute(TradingCommand::SubmitOrder(submit_order));
5117
5118        let exec_engine = engine.kernel.exec_engine.borrow();
5119        let cache = exec_engine.cache().borrow();
5120        let cached_order = cache
5121            .order(&order.client_order_id())
5122            .expect("Order should be cached");
5123
5124        assert_eq!(cached_order.status(), OrderStatus::Initialized);
5125    }
5126
5127    fn create_engine_with_replay_store(fail_restore: bool) -> BacktestEngine {
5128        let config = BacktestEngineConfig {
5129            load_state: true,
5130            run_analysis: false,
5131            ..Default::default()
5132        };
5133        let mut engine = BacktestEngine::new(config.clone()).unwrap();
5134        let event_store_factory = move |_instance_id: UUID4, _clock: Rc<RefCell<dyn Clock>>| {
5135            Ok::<_, anyhow::Error>(Box::new(BacktestReplayKernelEventStore { fail_restore })
5136                as Box<dyn KernelEventStore>)
5137        };
5138
5139        engine.kernel = NautilusKernel::new_with(
5140            "BacktestEngine".to_string(),
5141            config,
5142            None,
5143            Some(Box::new(event_store_factory)),
5144        )
5145        .unwrap();
5146        engine.instance_id = engine.kernel.instance_id;
5147        engine
5148    }
5149
5150    fn create_stop_market_order(instrument: &CryptoPerpetual) -> OrderAny {
5151        OrderTestBuilder::new(OrderType::StopMarket)
5152            .instrument_id(instrument.id())
5153            .side(OrderSide::Buy)
5154            .trigger_price(Price::from("5100.00"))
5155            .quantity(Quantity::from(1))
5156            .emulation_trigger(TriggerType::BidAsk)
5157            .build()
5158    }
5159
5160    fn create_submit_order_command(order: &OrderAny) -> SubmitOrder {
5161        SubmitOrder::new(
5162            order.trader_id(),
5163            None,
5164            order.strategy_id(),
5165            order.instrument_id(),
5166            order.client_order_id(),
5167            order.init_event().clone(),
5168            order.exec_algorithm_id(),
5169            None,
5170            None,
5171            UUID4::new(),
5172            0.into(),
5173            None, // correlation_id
5174        )
5175    }
5176
5177    fn register_data_command_handler(id: &str) -> TypedIntoMessageSavingHandler<DataCommand> {
5178        let (handler, saving_handler) =
5179            get_typed_into_message_saving_handler::<DataCommand>(Some(Ustr::from(id)));
5180        msgbus::register_data_command_endpoint(
5181            MessagingSwitchboard::data_engine_queue_execute(),
5182            handler,
5183        );
5184        saving_handler
5185    }
5186
5187    #[rstest]
5188    fn test_run_impl_event_store_replay_skips_trader_start() {
5189        let mut engine = create_engine_with_replay_store(false);
5190
5191        engine
5192            .run_impl(
5193                Some(UnixNanos::from(0)),
5194                Some(UnixNanos::from(1)),
5195                None,
5196                true,
5197            )
5198            .unwrap();
5199
5200        assert!(engine.kernel.is_event_store_replay_configured());
5201        assert!(engine.kernel.is_event_store_replay());
5202        assert!(!engine.kernel.trader.borrow().is_running());
5203    }
5204
5205    #[rstest]
5206    fn test_end_reports_strategy_stranded_by_managed_stop() {
5207        let (mut engine, strategy_id) = create_engine_with_strategy(true);
5208
5209        let result = engine.run(
5210            Some(UnixNanos::from(0)),
5211            Some(UnixNanos::from(1)),
5212            None,
5213            false,
5214        );
5215
5216        assert!(result.is_ok());
5217        assert_eq!(
5218            component_state(&strategy_id.inner()).unwrap(),
5219            ComponentState::Running
5220        );
5221        assert_eq!(engine.running_strategy_ids(), vec![strategy_id]);
5222    }
5223
5224    #[rstest]
5225    #[case::end(false)]
5226    #[case::streaming_resume(true)]
5227    fn test_latched_latency_failure_aborts_on_end_or_streaming_resume(#[case] resume: bool) {
5228        let mut engine = create_engine();
5229        let ts_now = UnixNanos::new(1);
5230        engine
5231            .run(Some(ts_now), Some(UnixNanos::new(2)), None, true)
5232            .unwrap();
5233        assert_eq!(engine.kernel.clock.borrow().timestamp_ns(), ts_now);
5234        assert!(engine.kernel.trader.borrow().is_running());
5235        let client_id = engine.exec_clients[0].client_id();
5236        let connected_before = engine
5237            .kernel
5238            .exec_engine
5239            .borrow()
5240            .get_client(&client_id)
5241            .unwrap()
5242            .is_connected();
5243        assert!(connected_before);
5244
5245        let venue = Venue::from("BINANCE");
5246        engine.venues[&venue]
5247            .borrow_mut()
5248            .set_latency_model(LatencyModelHandle::new(StaticLatencyModel::new(
5249                DurationNanos::ZERO,
5250                DurationNanos::ZERO,
5251                DurationNanos::ZERO,
5252                DurationNanos::MAX,
5253            )));
5254        engine
5255            .kernel
5256            .exec_engine
5257            .borrow()
5258            .execute(TradingCommand::CancelAllOrders(CancelAllOrders::new(
5259                TraderId::from("TRADER-001"),
5260                None,
5261                StrategyId::from("LATENCY-001"),
5262                InstrumentId::from("ETHUSDT-PERP.BINANCE"),
5263                None,
5264                UUID4::new(),
5265                ts_now,
5266                None,
5267                None,
5268            )));
5269
5270        let error = if resume {
5271            engine.run(None, None, None, true).unwrap_err()
5272        } else {
5273            engine.end().unwrap_err()
5274        };
5275
5276        assert!(
5277            error
5278                .to_string()
5279                .contains("Latency arrival timestamp exceeds u64 nanoseconds")
5280        );
5281        assert!(!engine.kernel.trader.borrow().is_running());
5282        let connected_after = engine
5283            .kernel
5284            .exec_engine
5285            .borrow()
5286            .get_client(&client_id)
5287            .unwrap()
5288            .is_connected();
5289        assert!(!connected_after);
5290        assert_eq!(engine.backtest_end(), Some(ts_now));
5291        engine.reset().unwrap();
5292        assert!(
5293            engine.venues[&venue]
5294                .borrow()
5295                .check_callback_error()
5296                .is_ok()
5297        );
5298    }
5299
5300    #[rstest]
5301    fn test_end_reports_no_cleanly_stopped_strategies() {
5302        let mut empty_engine = create_engine();
5303        let empty_result = empty_engine.run(
5304            Some(UnixNanos::from(0)),
5305            Some(UnixNanos::from(1)),
5306            None,
5307            false,
5308        );
5309        assert!(empty_result.is_ok());
5310        assert!(empty_engine.running_strategy_ids().is_empty());
5311
5312        let (mut engine, strategy_id) = create_engine_with_strategy(false);
5313        let result = engine.run(
5314            Some(UnixNanos::from(0)),
5315            Some(UnixNanos::from(1)),
5316            None,
5317            false,
5318        );
5319
5320        assert!(result.is_ok());
5321        assert_ne!(
5322            component_state(&strategy_id.inner()).unwrap(),
5323            ComponentState::Running
5324        );
5325        assert!(engine.running_strategy_ids().is_empty());
5326    }
5327
5328    #[rstest]
5329    fn test_run_impl_event_store_replay_config_failure_errors() {
5330        let mut engine = create_engine_with_replay_store(true);
5331
5332        let error = engine
5333            .run_impl(
5334                Some(UnixNanos::from(0)),
5335                Some(UnixNanos::from(1)),
5336                None,
5337                true,
5338            )
5339            .unwrap_err();
5340
5341        assert_eq!(error.to_string(), "event-store replay did not start");
5342        assert!(engine.kernel.is_event_store_replay_configured());
5343        assert!(!engine.kernel.is_event_store_replay());
5344        assert!(!engine.kernel.trader.borrow().is_running());
5345    }
5346
5347    #[rstest]
5348    fn test_backtest_state_persistence_loads_before_start_and_saves_after_settle() {
5349        let actor_id = ActorId::from("BACKTEST-STATE-ACTOR");
5350        let strategy_id = StrategyId::from("BACKTEST-STATE-STRATEGY-001");
5351        let actor_load = IndexMap::from([("actor-load".to_string(), b"actor-loaded".to_vec())]);
5352        let strategy_load =
5353            IndexMap::from([("strategy-load".to_string(), b"strategy-loaded".to_vec())]);
5354        let actor_save = IndexMap::from([("actor-save".to_string(), b"actor-saved".to_vec())]);
5355        let strategy_save =
5356            IndexMap::from([("strategy-save".to_string(), b"strategy-saved".to_vec())]);
5357        let (database, control) = TestCacheDatabaseControl::create();
5358        control.set_actor_state(actor_id, &actor_load);
5359        control.set_strategy_state(strategy_id, &strategy_load);
5360        let config = BacktestEngineConfig {
5361            load_state: true,
5362            save_state: true,
5363            run_analysis: false,
5364            ..Default::default()
5365        };
5366        let mut engine = BacktestEngine::new(config).unwrap();
5367        engine
5368            .kernel
5369            .cache
5370            .borrow_mut()
5371            .set_database(Box::new(database));
5372        engine
5373            .add_actor(StateActor::new(
5374                actor_id,
5375                control.clone(),
5376                actor_save.clone(),
5377            ))
5378            .unwrap();
5379        engine
5380            .add_strategy(StateStrategy::new(
5381                strategy_id,
5382                control.clone(),
5383                strategy_save.clone(),
5384            ))
5385            .unwrap();
5386
5387        engine
5388            .run(
5389                Some(UnixNanos::from(0)),
5390                Some(UnixNanos::from(1)),
5391                None,
5392                false,
5393            )
5394            .unwrap();
5395        engine.dispose();
5396
5397        assert_eq!(
5398            control.events(),
5399            vec![
5400                "actor.load:BACKTEST-STATE-ACTOR",
5401                "actor.on_load",
5402                "strategy.load:BACKTEST-STATE-STRATEGY-001",
5403                "strategy.on_load",
5404                "actor.on_start",
5405                "strategy.on_start",
5406                "actor.on_stop",
5407                "strategy.on_stop",
5408                "actor.on_save",
5409                "actor.update:BACKTEST-STATE-ACTOR",
5410                "strategy.on_save",
5411                "strategy.update:BACKTEST-STATE-STRATEGY-001",
5412                "database.close",
5413            ]
5414        );
5415        assert_eq!(control.actor_state(&actor_id), Some(actor_save));
5416        assert_eq!(control.strategy_state(&strategy_id), Some(strategy_save));
5417        assert_eq!(engine.backtest_end, Some(UnixNanos::from(0)));
5418    }
5419
5420    #[rstest]
5421    fn test_backtest_state_persistence_reports_callback_errors_after_shutdown() {
5422        let actor_id = ActorId::from("BACKTEST-FAIL-SAVE-ACTOR");
5423        let strategy_id = StrategyId::from("BACKTEST-FAIL-SAVE-STRATEGY-001");
5424        let (database, control) = TestCacheDatabaseControl::create();
5425        let config = BacktestEngineConfig {
5426            save_state: true,
5427            run_analysis: false,
5428            ..Default::default()
5429        };
5430        let mut engine = BacktestEngine::new(config).unwrap();
5431        engine
5432            .kernel
5433            .cache
5434            .borrow_mut()
5435            .set_database(Box::new(database));
5436        engine
5437            .add_actor(StateActor::new(actor_id, control.clone(), IndexMap::new()).with_fail_save())
5438            .unwrap();
5439        engine
5440            .add_strategy(
5441                StateStrategy::new(strategy_id, control.clone(), IndexMap::new()).with_fail_save(),
5442            )
5443            .unwrap();
5444
5445        let error = engine
5446            .run(
5447                Some(UnixNanos::from(0)),
5448                Some(UnixNanos::from(1)),
5449                None,
5450                false,
5451            )
5452            .unwrap_err();
5453        engine.dispose();
5454
5455        assert_eq!(
5456            error.to_string(),
5457            "Failed to save component state: actor BACKTEST-FAIL-SAVE-ACTOR callback: test actor \
5458             on_save failure; strategy BACKTEST-FAIL-SAVE-STRATEGY-001 callback: test strategy \
5459             on_save failure"
5460        );
5461        assert_eq!(
5462            control.events(),
5463            vec![
5464                "actor.on_start",
5465                "strategy.on_start",
5466                "actor.on_stop",
5467                "strategy.on_stop",
5468                "actor.on_save",
5469                "strategy.on_save",
5470                "database.close",
5471            ]
5472        );
5473        assert!(!engine.kernel.trader.borrow().is_running());
5474        assert_eq!(engine.backtest_end, Some(UnixNanos::from(0)));
5475    }
5476
5477    #[rstest]
5478    #[case(None)]
5479    #[case(Some(true))]
5480    #[case(Some(false))]
5481    fn test_new_forces_drop_instruments_on_reset_false(
5482        crypto_perpetual_ethusdt: CryptoPerpetual,
5483        #[case] user_value: Option<bool>,
5484    ) {
5485        use nautilus_common::cache::CacheConfig;
5486
5487        let config = match user_value {
5488            None => BacktestEngineConfig::builder().build(),
5489            Some(value) => BacktestEngineConfig::builder()
5490                .cache(
5491                    CacheConfig::builder()
5492                        .drop_instruments_on_reset(value)
5493                        .build()
5494                        .unwrap(),
5495                )
5496                .build(),
5497        };
5498        let mut engine = BacktestEngine::new(config).unwrap();
5499
5500        let venue_config = SimulatedVenueConfig::builder()
5501            .venue(Venue::from("BINANCE"))
5502            .oms_type(OmsType::Netting)
5503            .account_type(AccountType::Margin)
5504            .book_type(BookType::L1_MBP)
5505            .starting_balances(vec![Money::from("1_000_000 USDT")])
5506            .fee_model(FeeModelAny::MakerTaker(MakerTakerFeeModel::zero()).into())
5507            .build()
5508            .unwrap();
5509        engine.add_venue(venue_config).unwrap();
5510
5511        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt);
5512        let instrument_id = instrument.id();
5513        engine.add_instrument(&instrument).unwrap();
5514
5515        engine.kernel.trader.borrow_mut().initialize().unwrap();
5516        engine.reset().unwrap();
5517
5518        assert!(
5519            engine
5520                .kernel()
5521                .cache
5522                .borrow()
5523                .instrument(&instrument_id)
5524                .is_some(),
5525            "instrument must survive engine.reset(); user-supplied \
5526             drop_instruments_on_reset={user_value:?} must not leak through",
5527        );
5528    }
5529
5530    #[rstest]
5531    fn test_reset_resets_order_emulator_state(crypto_perpetual_ethusdt: CryptoPerpetual) {
5532        let mut engine = create_engine();
5533        let data_commands =
5534            register_data_command_handler("DataEngine.queue_execute.backtest_reset");
5535        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt.clone());
5536        let instrument_id = instrument.id();
5537        engine.add_instrument(&instrument).unwrap();
5538        let order = create_stop_market_order(&crypto_perpetual_ethusdt);
5539        let command = create_submit_order_command(&order);
5540        engine
5541            .kernel
5542            .cache
5543            .borrow_mut()
5544            .add_order(order, None, None, false)
5545            .unwrap();
5546        let order_emulator = engine.kernel.order_emulator.emulator();
5547        let mut order_emulator = order_emulator.borrow_mut();
5548        order_emulator.cache_submit_order_command(command.clone());
5549        order_emulator.handle_submit_order(&command);
5550        drop(order_emulator);
5551        data_commands.clear();
5552
5553        engine.kernel.trader.borrow_mut().initialize().unwrap();
5554        engine.reset().unwrap();
5555
5556        let commands = data_commands.get_messages();
5557        let emulator = engine.kernel.order_emulator.get_emulator();
5558        assert!(emulator.subscribed_quotes().is_empty());
5559        assert!(emulator.subscribed_trades().is_empty());
5560        assert!(emulator.get_matching_core(&instrument_id).is_none());
5561        assert!(commands.iter().any(|command| matches!(
5562            command,
5563            DataCommand::Unsubscribe(UnsubscribeCommand::Quotes(command))
5564                if command.instrument_ids == [instrument_id]
5565        )));
5566    }
5567
5568    #[rstest]
5569    #[case(false)]
5570    #[case(true)]
5571    fn test_reset_returns_component_failure_after_cleanup(
5572        crypto_perpetual_ethusdt: CryptoPerpetual,
5573        #[case] streaming: bool,
5574    ) {
5575        let mut engine = create_engine();
5576        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt);
5577        let instrument_id = instrument.id();
5578        engine.add_instrument(&instrument).unwrap();
5579        let actor_id = ActorId::from("ResetFailureActor");
5580
5581        let actor = ResetFailureActor {
5582            core: DataActorCore::new(DataActorConfig {
5583                actor_id: Some(actor_id),
5584                ..Default::default()
5585            }),
5586        };
5587
5588        engine.add_actor(actor).unwrap();
5589
5590        let quote = QuoteTick::new(
5591            instrument_id,
5592            Price::from("1003.00"),
5593            Price::from("1004.00"),
5594            Quantity::from("3.000"),
5595            Quantity::from("4.000"),
5596            UnixNanos::from(1_000_000_000),
5597            UnixNanos::from(1_000_000_001),
5598        );
5599        engine
5600            .add_data(vec![Data::Quote(quote)], None, true, true)
5601            .unwrap();
5602        engine
5603            .run(None, None, Some("reset-test".to_string()), streaming)
5604            .unwrap();
5605        assert_eq!(engine.iteration, 1);
5606        assert!(engine.data_iterator.is_done());
5607        assert_eq!(engine.run_config_id.as_deref(), Some("reset-test"));
5608
5609        let result = engine.reset();
5610
5611        assert_eq!(engine.run_config_id, None);
5612        assert_eq!(engine.run_id, None);
5613        assert_eq!(engine.run_started, None);
5614        assert_eq!(engine.run_finished, None);
5615        assert_eq!(engine.backtest_start, None);
5616        assert_eq!(engine.backtest_end, None);
5617        assert_eq!(engine.iteration, 0);
5618        assert_eq!(engine.last_ns, UnixNanos::default());
5619        assert_eq!(engine.end_ns, UnixNanos::default());
5620        assert_eq!(engine.data_iterator.next(), Some(Data::Quote(quote)));
5621        assert_eq!(
5622            component_state(&actor_id.inner()).unwrap(),
5623            ComponentState::Resetting
5624        );
5625        assert_eq!(
5626            engine.kernel.trader.borrow().state(),
5627            ComponentState::Resetting
5628        );
5629        assert_eq!(result.unwrap_err().to_string(), "synthetic reset failure");
5630    }
5631
5632    #[rstest]
5633    fn test_reset_preserves_error_from_end() {
5634        let mut engine = create_engine();
5635        engine.run(None, None, None, true).unwrap();
5636        engine
5637            .fail_funding::<()>("prior funding failure".to_string())
5638            .unwrap_err();
5639
5640        let e = engine.reset().unwrap_err();
5641
5642        assert_eq!(e.to_string(), "prior funding failure");
5643        assert_eq!(engine.funding_error, None);
5644        assert_eq!(engine.run_id, None);
5645        assert_eq!(engine.iteration, 0);
5646    }
5647
5648    #[derive(Debug)]
5649    struct ResetFailureActor {
5650        core: DataActorCore,
5651    }
5652
5653    nautilus_actor!(ResetFailureActor);
5654
5655    impl DataActor for ResetFailureActor {
5656        fn on_reset(&mut self) -> anyhow::Result<()> {
5657            anyhow::bail!("synthetic reset failure");
5658        }
5659    }
5660
5661    #[rstest]
5662    fn test_route_data_to_exchange_instrument_status(crypto_perpetual_ethusdt: CryptoPerpetual) {
5663        let mut engine = create_engine();
5664        let instrument = InstrumentAny::CryptoPerpetual(crypto_perpetual_ethusdt);
5665        let instrument_id = instrument.id();
5666        engine.add_instrument(&instrument).unwrap();
5667
5668        let status = InstrumentStatus::new(
5669            instrument_id,
5670            MarketStatusAction::Close,
5671            UnixNanos::from(1),
5672            UnixNanos::from(1),
5673            None,
5674            None,
5675            None,
5676            None,
5677            None,
5678        );
5679
5680        BacktestEngine::route_data_to_exchange(
5681            &engine.venues,
5682            &mut engine.has_book_processed,
5683            &engine.kernel.clock,
5684            DataRef::InstrumentStatus(&status),
5685        )
5686        .unwrap();
5687
5688        let exchange = engine.venues.get(&instrument_id.venue).unwrap().borrow();
5689        let market_status = exchange
5690            .get_matching_engine(&instrument_id)
5691            .unwrap()
5692            .market_status;
5693        assert_eq!(market_status, MarketStatus::Closed);
5694    }
5695}