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