Skip to main content

nautilus_event_store/
replay.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//! Bootstrap replay for restoring cache state after a cache-owned snapshot.
17//!
18//! This module is deliberately state-only: it consumes event-store entries, decodes the
19//! cache-affecting payloads, and mutates [`nautilus_common::cache::Cache`] directly. It
20//! does not publish to the live message bus, send commands, invoke adapters, or submit
21//! entries back into the event store.
22
23use std::{fmt::Display, path::PathBuf};
24
25use indexmap::IndexMap;
26use nautilus_common::{
27    cache::Cache,
28    messages::{
29        data::{
30            BarsResponse, FundingRatesResponse, InstrumentResponse, InstrumentsResponse,
31            QuotesResponse, TradesResponse,
32        },
33        execution::SubmitOrderList,
34    },
35};
36use nautilus_core::{DurationNanos, Params, UUID4, UnixNanos};
37use nautilus_execution::engine::settlement::{settle_instrument_close, settlement_close};
38use nautilus_model::{
39    data::{Bar, BatchView, InstrumentClose, QuoteTick, TradeTick},
40    enums::{OmsType, OrderSide, PositionSide},
41    events::{
42        AccountState, OrderEventAny, OrderFillVoided, OrderFilled, OrderInitialized,
43        PositionAdjusted, PositionChanged, PositionClosed, PositionOpened,
44    },
45    identifiers::{ClientId, InstrumentId, PositionId},
46    orders::{Order, OrderAny},
47    position::{Position, PositionReplayEvent},
48    types::{
49        Money, Quantity,
50        quantity::{QUANTITY_RAW_MAX, QuantityRaw},
51    },
52};
53use serde::{Deserialize, de::DeserializeOwned};
54
55#[cfg(test)]
56use crate::capture::builtins::{
57    PAYLOAD_TYPE_BATCH_CANCEL_ORDERS, PAYLOAD_TYPE_BATCH_MODIFY_ORDERS,
58    PAYLOAD_TYPE_BOOK_DELTAS_RESPONSE, PAYLOAD_TYPE_BOOK_DEPTH_RESPONSE,
59    PAYLOAD_TYPE_BOOK_RESPONSE, PAYLOAD_TYPE_CANCEL_ALL_ORDERS, PAYLOAD_TYPE_CANCEL_ORDER,
60    PAYLOAD_TYPE_CUSTOM_DATA_RESPONSE, PAYLOAD_TYPE_EXECUTION_MASS_STATUS,
61    PAYLOAD_TYPE_FILL_REPORT, PAYLOAD_TYPE_MODIFY_ORDER,
62    PAYLOAD_TYPE_OPTION_CHAIN_REFERENCE_PRICE_RESPONSE, PAYLOAD_TYPE_ORDER_STATUS_REPORT,
63    PAYLOAD_TYPE_ORDER_WITH_FILLS, PAYLOAD_TYPE_POSITION_STATUS_REPORT, PAYLOAD_TYPE_QUERY_ACCOUNT,
64    PAYLOAD_TYPE_QUERY_ORDER, PAYLOAD_TYPE_REQUEST_COMMAND, PAYLOAD_TYPE_SUBMIT_ORDER,
65    PAYLOAD_TYPE_SUBSCRIBE_COMMAND, PAYLOAD_TYPE_TIME_EVENT, PAYLOAD_TYPE_UNSUBSCRIBE_COMMAND,
66};
67#[cfg(all(test, feature = "defi"))]
68use crate::capture::builtins::{
69    PAYLOAD_TYPE_DEFI_REQUEST_COMMAND, PAYLOAD_TYPE_DEFI_SUBSCRIBE_COMMAND,
70    PAYLOAD_TYPE_DEFI_UNSUBSCRIBE_COMMAND,
71};
72use crate::{
73    RedbBackend,
74    backend::{EventStore, ScanDirection},
75    capture::builtins::{
76        PAYLOAD_TYPE_ACCOUNT_STATE, PAYLOAD_TYPE_BARS_RESPONSE,
77        PAYLOAD_TYPE_FUNDING_RATES_RESPONSE, PAYLOAD_TYPE_INSTRUMENT_CLOSE,
78        PAYLOAD_TYPE_INSTRUMENT_RESPONSE, PAYLOAD_TYPE_INSTRUMENTS_RESPONSE,
79        PAYLOAD_TYPE_ORDER_ACCEPTED, PAYLOAD_TYPE_ORDER_CANCEL_DENIED,
80        PAYLOAD_TYPE_ORDER_CANCEL_REJECTED, PAYLOAD_TYPE_ORDER_CANCELED, PAYLOAD_TYPE_ORDER_DENIED,
81        PAYLOAD_TYPE_ORDER_EMULATED, PAYLOAD_TYPE_ORDER_EXPIRED, PAYLOAD_TYPE_ORDER_FILL_VOIDED,
82        PAYLOAD_TYPE_ORDER_FILLED, PAYLOAD_TYPE_ORDER_INITIALIZED,
83        PAYLOAD_TYPE_ORDER_MODIFY_DENIED, PAYLOAD_TYPE_ORDER_MODIFY_REJECTED,
84        PAYLOAD_TYPE_ORDER_PENDING_CANCEL, PAYLOAD_TYPE_ORDER_PENDING_UPDATE,
85        PAYLOAD_TYPE_ORDER_REJECTED, PAYLOAD_TYPE_ORDER_RELEASED, PAYLOAD_TYPE_ORDER_SUBMITTED,
86        PAYLOAD_TYPE_ORDER_TRIGGERED, PAYLOAD_TYPE_ORDER_UPDATED, PAYLOAD_TYPE_POSITION_ADJUSTED,
87        PAYLOAD_TYPE_POSITION_CHANGED, PAYLOAD_TYPE_POSITION_CLOSED, PAYLOAD_TYPE_POSITION_OPENED,
88        PAYLOAD_TYPE_QUOTES_RESPONSE, PAYLOAD_TYPE_SUBMIT_ORDER_LIST, PAYLOAD_TYPE_TRADES_RESPONSE,
89    },
90    entry::EventStoreEntry,
91    error::EventStoreError,
92    manifest::{RunManifest, RunStatus},
93    reader::{EventStoreReader, SnapshotReplayPlan},
94    snapshot::{SnapshotAnchor, compute_snapshot_content_hash},
95};
96
97#[cfg(feature = "persistence")]
98mod catalog;
99
100#[cfg(feature = "persistence")]
101pub use catalog::ParquetReplayCatalog;
102
103/// Summary of a cache snapshot-tail replay.
104#[derive(Clone, Debug, PartialEq, Eq)]
105pub struct CacheReplayReport {
106    /// Replay bounds derived from the latest snapshot anchor.
107    pub plan: SnapshotReplayPlan,
108    /// Number of entries applied to cache state.
109    pub applied_entries: usize,
110    /// Number of event-store entries that do not have a cache replay rule yet.
111    pub ignored_entries: usize,
112}
113
114/// Summary of an event-store replay source and cache restore.
115#[derive(Clone, Debug, PartialEq, Eq)]
116pub struct EventStoreReplayReport {
117    /// Manifest of the sealed replay source.
118    pub manifest: RunManifest,
119    /// Cache snapshot-tail replay result.
120    pub cache: CacheReplayReport,
121}
122
123#[cfg(test)]
124pub(crate) const CACHE_REPLAY_CAPTURE_PAYLOAD_TYPES: &[&str] = &[
125    crate::capture::builtins::PAYLOAD_TYPE_DATA_RESPONSE_ENVELOPE,
126    PAYLOAD_TYPE_SUBMIT_ORDER_LIST,
127    PAYLOAD_TYPE_ACCOUNT_STATE,
128    PAYLOAD_TYPE_INSTRUMENT_CLOSE,
129    PAYLOAD_TYPE_INSTRUMENT_RESPONSE,
130    PAYLOAD_TYPE_INSTRUMENTS_RESPONSE,
131    PAYLOAD_TYPE_QUOTES_RESPONSE,
132    PAYLOAD_TYPE_TRADES_RESPONSE,
133    PAYLOAD_TYPE_FUNDING_RATES_RESPONSE,
134    PAYLOAD_TYPE_BARS_RESPONSE,
135    PAYLOAD_TYPE_ORDER_INITIALIZED,
136    PAYLOAD_TYPE_ORDER_DENIED,
137    PAYLOAD_TYPE_ORDER_EMULATED,
138    PAYLOAD_TYPE_ORDER_RELEASED,
139    PAYLOAD_TYPE_ORDER_SUBMITTED,
140    PAYLOAD_TYPE_ORDER_ACCEPTED,
141    PAYLOAD_TYPE_ORDER_REJECTED,
142    PAYLOAD_TYPE_ORDER_CANCELED,
143    PAYLOAD_TYPE_ORDER_EXPIRED,
144    PAYLOAD_TYPE_ORDER_TRIGGERED,
145    PAYLOAD_TYPE_ORDER_PENDING_UPDATE,
146    PAYLOAD_TYPE_ORDER_PENDING_CANCEL,
147    PAYLOAD_TYPE_ORDER_MODIFY_DENIED,
148    PAYLOAD_TYPE_ORDER_MODIFY_REJECTED,
149    PAYLOAD_TYPE_ORDER_CANCEL_DENIED,
150    PAYLOAD_TYPE_ORDER_CANCEL_REJECTED,
151    PAYLOAD_TYPE_ORDER_UPDATED,
152    PAYLOAD_TYPE_ORDER_FILLED,
153    PAYLOAD_TYPE_ORDER_FILL_VOIDED,
154    PAYLOAD_TYPE_POSITION_OPENED,
155    PAYLOAD_TYPE_POSITION_CHANGED,
156    PAYLOAD_TYPE_POSITION_CLOSED,
157    PAYLOAD_TYPE_POSITION_ADJUSTED,
158];
159
160#[cfg(test)]
161pub(crate) const FORENSIC_ONLY_CAPTURE_PAYLOAD_TYPES: &[&str] = &[
162    PAYLOAD_TYPE_SUBMIT_ORDER,
163    PAYLOAD_TYPE_MODIFY_ORDER,
164    PAYLOAD_TYPE_BATCH_MODIFY_ORDERS,
165    PAYLOAD_TYPE_CANCEL_ORDER,
166    PAYLOAD_TYPE_CANCEL_ALL_ORDERS,
167    PAYLOAD_TYPE_BATCH_CANCEL_ORDERS,
168    PAYLOAD_TYPE_QUERY_ORDER,
169    PAYLOAD_TYPE_QUERY_ACCOUNT,
170    PAYLOAD_TYPE_ORDER_STATUS_REPORT,
171    PAYLOAD_TYPE_FILL_REPORT,
172    PAYLOAD_TYPE_ORDER_WITH_FILLS,
173    PAYLOAD_TYPE_POSITION_STATUS_REPORT,
174    PAYLOAD_TYPE_EXECUTION_MASS_STATUS,
175    PAYLOAD_TYPE_TIME_EVENT,
176    PAYLOAD_TYPE_REQUEST_COMMAND,
177    PAYLOAD_TYPE_SUBSCRIBE_COMMAND,
178    PAYLOAD_TYPE_UNSUBSCRIBE_COMMAND,
179    #[cfg(feature = "defi")]
180    PAYLOAD_TYPE_DEFI_REQUEST_COMMAND,
181    #[cfg(feature = "defi")]
182    PAYLOAD_TYPE_DEFI_SUBSCRIBE_COMMAND,
183    #[cfg(feature = "defi")]
184    PAYLOAD_TYPE_DEFI_UNSUBSCRIBE_COMMAND,
185    PAYLOAD_TYPE_CUSTOM_DATA_RESPONSE,
186    PAYLOAD_TYPE_BOOK_RESPONSE,
187    PAYLOAD_TYPE_BOOK_DELTAS_RESPONSE,
188    PAYLOAD_TYPE_BOOK_DEPTH_RESPONSE,
189    PAYLOAD_TYPE_OPTION_CHAIN_REFERENCE_PRICE_RESPONSE,
190];
191
192/// Inclusive event-store `seq` bounds for replay input scans.
193#[derive(Clone, Copy, Debug, PartialEq, Eq)]
194pub struct ReplaySeqRange {
195    /// First event-store `seq` to scan.
196    pub from_seq: u64,
197    /// Last event-store `seq` to scan.
198    pub to_seq: u64,
199}
200
201impl ReplaySeqRange {
202    /// Builds inclusive event-store `seq` bounds.
203    #[must_use]
204    pub const fn new(from_seq: u64, to_seq: u64) -> Self {
205        Self { from_seq, to_seq }
206    }
207}
208
209/// Inclusive nanosecond time bounds for catalog slice selection.
210#[derive(Clone, Copy, Debug, PartialEq, Eq)]
211pub struct ReplayTimeRange {
212    /// First catalog timestamp to include.
213    pub start: UnixNanos,
214    /// Last catalog timestamp to include.
215    pub end: UnixNanos,
216}
217
218impl ReplayTimeRange {
219    /// Builds inclusive nanosecond time bounds.
220    #[must_use]
221    pub const fn new(start: UnixNanos, end: UnixNanos) -> Self {
222        Self { start, end }
223    }
224
225    fn from_entry(entry: &EventStoreEntry) -> Self {
226        Self {
227            start: entry.ts_init,
228            end: entry.ts_init,
229        }
230    }
231
232    fn include_entry(&mut self, entry: &EventStoreEntry) {
233        self.start = self.start.min(entry.ts_init);
234        self.end = self.end.max(entry.ts_init);
235    }
236}
237
238/// Caller-selected data catalog slice before replay window defaults are applied.
239#[derive(Clone, Debug, PartialEq, Eq)]
240pub struct CatalogSliceSelector {
241    /// Catalog data class or directory name, such as `quotes`, `trades`, or `bars`.
242    pub data_cls: String,
243    /// Optional catalog identifiers, such as instrument IDs or bar type strings.
244    pub identifiers: Vec<String>,
245    /// Optional lower timestamp bound. When absent, the event-store scan lower bound applies.
246    pub start: Option<UnixNanos>,
247    /// Optional upper timestamp bound. When absent, the event-store scan upper bound applies.
248    pub end: Option<UnixNanos>,
249    /// Whether loading should fail when the catalog reports no files for this slice.
250    pub required: bool,
251}
252
253impl CatalogSliceSelector {
254    /// Builds a selector for `data_cls` with no identifiers or explicit time bounds.
255    pub fn new(data_cls: impl Into<String>) -> Self {
256        Self {
257            data_cls: data_cls.into(),
258            identifiers: Vec::new(),
259            start: None,
260            end: None,
261            required: false,
262        }
263    }
264
265    /// Adds one catalog identifier to the selector.
266    #[must_use]
267    pub fn with_identifier(mut self, identifier: impl Into<String>) -> Self {
268        self.identifiers.push(identifier.into());
269        self
270    }
271
272    /// Sets explicit inclusive catalog time bounds.
273    #[must_use]
274    pub const fn with_time_bounds(mut self, start: UnixNanos, end: UnixNanos) -> Self {
275        self.start = Some(start);
276        self.end = Some(end);
277        self
278    }
279
280    /// Marks the selector as required.
281    #[must_use]
282    pub const fn require_coverage(mut self) -> Self {
283        self.required = true;
284        self
285    }
286}
287
288/// Resolved catalog query after replay time bounds have been applied.
289#[derive(Clone, Debug, PartialEq, Eq)]
290pub struct CatalogSliceQuery {
291    /// Catalog data class or directory name, such as `quotes`, `trades`, or `bars`.
292    pub data_cls: String,
293    /// Catalog identifiers, such as instrument IDs or bar type strings.
294    pub identifiers: Vec<String>,
295    /// Inclusive lower timestamp bound.
296    pub start: UnixNanos,
297    /// Inclusive upper timestamp bound.
298    pub end: UnixNanos,
299    /// Whether loading should fail when the catalog reports no files for this slice.
300    pub required: bool,
301}
302
303impl CatalogSliceQuery {
304    /// Returns identifiers in the shape expected by catalog APIs.
305    #[must_use]
306    pub fn identifiers_option(&self) -> Option<Vec<String>> {
307        if self.identifiers.is_empty() {
308            None
309        } else {
310            Some(self.identifiers.clone())
311        }
312    }
313}
314
315/// Catalog file and interval coverage for a planned slice.
316#[derive(Clone, Debug, Default, PartialEq, Eq)]
317pub struct CatalogSliceCoverage {
318    /// Catalog files selected for the slice.
319    pub files: Vec<String>,
320    /// Covered timestamp intervals reported by the catalog.
321    pub intervals: Vec<ReplayTimeRange>,
322}
323
324impl CatalogSliceCoverage {
325    /// Builds coverage from selected catalog files.
326    #[must_use]
327    pub fn from_files(files: Vec<String>) -> Self {
328        Self {
329            files,
330            intervals: Vec::new(),
331        }
332    }
333
334    /// Returns whether the catalog found no files for the slice.
335    #[must_use]
336    pub fn is_missing(&self) -> bool {
337        self.files.is_empty()
338    }
339}
340
341/// Planned catalog slice joined to a replay input scan.
342#[derive(Clone, Debug, PartialEq, Eq)]
343pub struct CatalogSlicePlan {
344    /// Resolved catalog query.
345    pub query: CatalogSliceQuery,
346    /// Catalog coverage reported during planning.
347    pub coverage: CatalogSliceCoverage,
348}
349
350impl CatalogSlicePlan {
351    /// Returns whether the catalog reported no files for this slice.
352    #[must_use]
353    pub fn is_missing(&self) -> bool {
354        self.coverage.is_missing()
355    }
356}
357
358/// Typed catalog data loaded for replay context.
359#[derive(Clone, Copy, Debug, PartialEq, Eq)]
360pub enum CatalogReplayData {
361    /// Quote tick loaded from the `quotes` catalog.
362    Quote(QuoteTick),
363    /// Trade tick loaded from the `trades` catalog.
364    Trade(TradeTick),
365    /// Bar loaded from the `bars` catalog.
366    Bar(Bar),
367}
368
369impl CatalogReplayData {
370    /// Returns the catalog data class for this record.
371    #[must_use]
372    pub const fn data_cls(&self) -> &'static str {
373        match self {
374            Self::Quote(_) => "quotes",
375            Self::Trade(_) => "trades",
376            Self::Bar(_) => "bars",
377        }
378    }
379
380    /// Returns the catalog identifier for this record.
381    #[must_use]
382    pub fn identifier(&self) -> String {
383        match self {
384            Self::Quote(quote) => quote.instrument_id.to_string(),
385            Self::Trade(trade) => trade.instrument_id.to_string(),
386            Self::Bar(bar) => bar.bar_type.to_string(),
387        }
388    }
389
390    /// Returns the initialization timestamp for this record.
391    #[must_use]
392    pub const fn ts_init(&self) -> UnixNanos {
393        match self {
394            Self::Quote(quote) => quote.ts_init,
395            Self::Trade(trade) => trade.ts_init,
396            Self::Bar(bar) => bar.ts_init,
397        }
398    }
399}
400
401impl From<QuoteTick> for CatalogReplayData {
402    fn from(value: QuoteTick) -> Self {
403        Self::Quote(value)
404    }
405}
406
407impl From<TradeTick> for CatalogReplayData {
408    fn from(value: TradeTick) -> Self {
409        Self::Trade(value)
410    }
411}
412
413impl From<Bar> for CatalogReplayData {
414    fn from(value: Bar) -> Self {
415        Self::Bar(value)
416    }
417}
418
419/// Catalog record loaded for replay context.
420#[derive(Clone, Debug, PartialEq, Eq)]
421pub struct CatalogReplayRecord {
422    /// Catalog data class or directory name for the record.
423    pub data_cls: String,
424    /// Optional catalog identifier for the record.
425    pub identifier: Option<String>,
426    /// Record timestamp used for contextual joins.
427    pub ts_init: UnixNanos,
428    /// Typed catalog data loaded for contextual analysis.
429    pub data: CatalogReplayData,
430}
431
432impl CatalogReplayRecord {
433    /// Builds a typed catalog replay record.
434    #[must_use]
435    pub fn from_data(data: CatalogReplayData) -> Self {
436        Self {
437            data_cls: data.data_cls().to_string(),
438            identifier: Some(data.identifier()),
439            ts_init: data.ts_init(),
440            data,
441        }
442    }
443}
444
445/// Loaded catalog records for one planned slice.
446#[derive(Clone, Debug, PartialEq, Eq)]
447pub struct CatalogReplaySlice {
448    /// Planned catalog slice metadata.
449    pub plan: CatalogSlicePlan,
450    /// Loaded catalog records.
451    pub records: Vec<CatalogReplayRecord>,
452}
453
454/// Planned replay inputs for an event-store scan with optional catalog context.
455#[derive(Clone, Debug, PartialEq, Eq)]
456pub struct ReplayInputPlan {
457    /// Requested event-store `seq` bounds.
458    pub requested_range: ReplaySeqRange,
459    /// Actual event-store range found inside the requested bounds.
460    pub event_range: Option<ReplaySeqRange>,
461    /// Number of event-store entries found inside the requested bounds.
462    pub event_count: usize,
463    /// Minimum and maximum event-store `ts_init` values inside the requested bounds.
464    pub event_time_range: Option<ReplayTimeRange>,
465    /// Catalog slices joined to the event-store scan.
466    pub catalog_slices: Vec<CatalogSlicePlan>,
467}
468
469impl ReplayInputPlan {
470    /// Returns all catalog slices that had no selected files.
471    #[must_use]
472    pub fn missing_catalog_slices(&self) -> Vec<&CatalogSlicePlan> {
473        self.catalog_slices
474            .iter()
475            .filter(|slice| slice.is_missing())
476            .collect()
477    }
478}
479
480/// Loaded replay inputs with event-store entries and optional catalog context.
481#[derive(Clone, Debug, PartialEq, Eq)]
482pub struct ReplayInputs {
483    /// Event-store entries in durable `seq` order.
484    pub entries: Vec<EventStoreEntry>,
485    /// Catalog slices loaded as contextual input.
486    pub catalog_slices: Vec<CatalogReplaySlice>,
487}
488
489/// Read-only catalog source used by catalog-joined replay input loaders.
490pub trait ReplayCatalog {
491    /// Catalog-specific error type.
492    type Error: Display;
493
494    /// Plans one catalog slice without mutating catalog state.
495    ///
496    /// # Errors
497    ///
498    /// Returns an error if slice planning fails (the catalog implementation's error).
499    fn plan_slice(
500        &mut self,
501        query: &CatalogSliceQuery,
502    ) -> Result<CatalogSliceCoverage, Self::Error>;
503
504    /// Loads records for one planned catalog slice without live venue access.
505    ///
506    /// Implementations return records in catalog order so marker cursor joins can take a
507    /// deterministic prefix from a cumulative stream slice.
508    ///
509    /// # Errors
510    ///
511    /// Returns an error if slice loading fails (the catalog implementation's error).
512    fn load_slice(
513        &mut self,
514        plan: &CatalogSlicePlan,
515    ) -> Result<Vec<CatalogReplayRecord>, Self::Error>;
516}
517
518/// Errors surfaced while planning or loading replay inputs.
519#[derive(Debug, thiserror::Error)]
520pub enum ReplayInputError {
521    /// The event-store reader failed.
522    #[error(transparent)]
523    EventStore(#[from] EventStoreError),
524    /// The requested event-store `seq` range is invalid.
525    #[error("invalid replay seq range {from_seq}..={to_seq}: {message}")]
526    InvalidSeqRange {
527        /// Requested lower `seq`.
528        from_seq: u64,
529        /// Requested upper `seq`.
530        to_seq: u64,
531        /// Validation failure.
532        message: String,
533    },
534    /// A catalog-joined replay plan had no selected catalog slices.
535    #[error("catalog replay requires at least one selected catalog slice")]
536    EmptyCatalogSelection,
537    /// A catalog slice needs time bounds, but neither selector nor event-store scan supplied them.
538    #[error(
539        "catalog slice {data_cls} requires explicit time bounds because the replay scan is empty"
540    )]
541    MissingCatalogTimeBounds {
542        /// Catalog data class or directory name.
543        data_cls: String,
544    },
545    /// A catalog slice has an invalid timestamp range.
546    #[error("invalid catalog time range for {data_cls}: {start}..={end}")]
547    InvalidCatalogTimeRange {
548        /// Catalog data class or directory name.
549        data_cls: String,
550        /// Lower timestamp bound.
551        start: u64,
552        /// Upper timestamp bound.
553        end: u64,
554    },
555    /// A required catalog slice had no files.
556    #[error("required catalog slice {data_cls} is missing for identifiers {identifiers:?}")]
557    MissingCatalogSlice {
558        /// Catalog data class or directory name.
559        data_cls: String,
560        /// Catalog identifiers.
561        identifiers: Vec<String>,
562    },
563    /// The catalog source failed.
564    #[error("catalog slice {data_cls}: {message}")]
565    Catalog {
566        /// Catalog data class or directory name.
567        data_cls: String,
568        /// Catalog error message.
569        message: String,
570    },
571}
572
573/// Errors surfaced while restoring a cache snapshot tail.
574#[derive(Debug, thiserror::Error)]
575pub enum CacheReplayError {
576    /// The event-store reader failed.
577    #[error(transparent)]
578    EventStore(#[from] EventStoreError),
579    /// The caller-provided snapshot restore hook failed.
580    #[error("restore cache snapshot {blob_ref}: {message}")]
581    SnapshotRestore {
582        /// Cache-owned snapshot blob reference.
583        blob_ref: String,
584        /// Error message returned by the restore hook.
585        message: String,
586    },
587    /// The replay scan yielded an entry outside the derived restore bounds.
588    #[error("entry seq {seq} is before replay start seq {from_seq}")]
589    UnexpectedSeq {
590        /// Entry sequence yielded by the scan.
591        seq: u64,
592        /// First sequence this replay is allowed to apply.
593        from_seq: u64,
594    },
595    /// A captured payload failed to decode.
596    #[error("decode seq {seq} payload_type {payload_type}: {message}")]
597    Decode {
598        /// Event-store sequence number.
599        seq: u64,
600        /// Captured payload type tag.
601        payload_type: String,
602        /// Decode error message.
603        message: String,
604    },
605    /// Applying a decoded payload to the cache failed.
606    #[error("apply seq {seq} payload_type {payload_type}: {message}")]
607    Apply {
608        /// Event-store sequence number.
609        seq: u64,
610        /// Captured payload type tag.
611        payload_type: String,
612        /// Apply error message.
613        message: String,
614    },
615}
616
617impl CacheReplayError {
618    /// Builds a snapshot-restore error for `anchor`.
619    #[must_use]
620    pub fn snapshot_restore(anchor: &SnapshotAnchor, error: impl Display) -> Self {
621        Self::SnapshotRestore {
622            blob_ref: anchor.blob_ref.clone(),
623            message: error.to_string(),
624        }
625    }
626}
627
628#[derive(Default)]
629struct CacheReplayContext {
630    allow_deferred_flips: bool,
631    pending_flips: Vec<PendingFlip>,
632}
633
634struct PendingFlip {
635    source_seq: u64,
636    source_position_id: PositionId,
637    oms_type: OmsType,
638    opening_fill: OrderFilled,
639}
640
641impl CacheReplayContext {
642    fn for_snapshot_tail() -> Self {
643        Self {
644            allow_deferred_flips: true,
645            pending_flips: Vec::new(),
646        }
647    }
648
649    fn contains_flip_source(&self, fill: &OrderFilled) -> bool {
650        self.pending_flips.iter().any(|pending| {
651            pending.opening_fill.client_order_id == fill.client_order_id
652                && pending.opening_fill.trade_id == fill.trade_id
653                && pending.opening_fill.causation_id == Some(fill.event_id)
654        })
655    }
656
657    fn push_flip(
658        &mut self,
659        source_seq: u64,
660        source_position_id: PositionId,
661        oms_type: OmsType,
662        opening_fill: OrderFilled,
663    ) {
664        self.pending_flips.push(PendingFlip {
665            source_seq,
666            source_position_id,
667            oms_type,
668            opening_fill,
669        });
670    }
671
672    fn take_opening_fill(
673        &mut self,
674        entry: &EventStoreEntry,
675        opened: &PositionOpened,
676    ) -> Result<Option<(OrderFilled, OmsType)>, CacheReplayError> {
677        let matching: Vec<usize> = self
678            .pending_flips
679            .iter()
680            .enumerate()
681            .filter_map(|(index, pending)| {
682                let fill = &pending.opening_fill;
683                (fill.trader_id == opened.trader_id
684                    && fill.strategy_id == opened.strategy_id
685                    && fill.instrument_id == opened.instrument_id
686                    && fill.account_id == opened.account_id
687                    && fill.client_order_id == opened.opening_order_id
688                    && fill.order_side == opened.entry
689                    && fill.last_qty == opened.last_qty
690                    && fill.last_px == opened.last_px
691                    && fill.currency == opened.currency)
692                    .then_some(index)
693            })
694            .collect();
695
696        if matching.len() > 1 {
697            return Err(apply_error(
698                entry,
699                format!(
700                    "ambiguous position flip recovery for position {}: {} pending fills match",
701                    opened.position_id,
702                    matching.len(),
703                ),
704            ));
705        }
706
707        let Some(index) = matching.first().copied() else {
708            return Ok(None);
709        };
710
711        let pending = self.pending_flips.remove(index);
712        let mut fill = pending.opening_fill;
713        let oms_type = if pending.source_position_id == opened.position_id {
714            pending.oms_type
715        } else {
716            // Replacement IDs identify HEDGING flips when no snapshot supplies OMS metadata
717            OmsType::Hedging
718        };
719        fill.position_id = Some(opened.position_id);
720        // The live opening fragment is not stored separately. The PositionOpened event ID is
721        // stable and identifies the recovered opening transition, while causation still points
722        // to the original unsplit venue fill.
723        fill.event_id = opened.event_id;
724        Ok(Some((fill, oms_type)))
725    }
726
727    fn ensure_complete(&self) -> Result<(), CacheReplayError> {
728        let Some(pending) = self.pending_flips.first() else {
729            return Ok(());
730        };
731
732        Err(CacheReplayError::Apply {
733            seq: pending.source_seq,
734            payload_type: PAYLOAD_TYPE_ORDER_FILLED.to_string(),
735            message: format!(
736                "position flip fill {} has no matching PositionOpened event",
737                pending.opening_fill.trade_id,
738            ),
739        })
740    }
741}
742
743/// Replays the cache snapshot tail after the caller restores the cache-owned snapshot blob.
744///
745/// The restore hook runs before the tail iterator is consumed. When `anchor` is `Some`,
746/// the hook should fetch and apply the cache-owned blob identified by
747/// [`SnapshotAnchor::blob_ref`] and validate it against
748/// [`SnapshotAnchor::content_hash`]. When `anchor` is `None`, restore starts from
749/// event-store seq `1` and the hook may be a no-op.
750///
751/// This is a bootstrap path: it mutates cache state directly and never publishes replay
752/// entries to the live message bus.
753///
754/// # Errors
755///
756/// Returns an error if:
757///
758/// - The reader fails.
759/// - The `restore_snapshot` hook fails.
760/// - A supported payload cannot be decoded.
761/// - The decoded payload cannot be applied to the cache.
762pub fn restore_cache_snapshot_and_replay_tail<B, F>(
763    cache: &mut Cache,
764    reader: &EventStoreReader<B>,
765    restore_snapshot: F,
766) -> Result<CacheReplayReport, CacheReplayError>
767where
768    B: EventStore,
769    F: FnOnce(&mut Cache, Option<&SnapshotAnchor>) -> Result<(), CacheReplayError>,
770{
771    let (plan, scan) = reader.scan_snapshot_replay_tail()?;
772    restore_snapshot(cache, plan.anchor.as_ref())?;
773
774    let mut applied_entries = 0;
775    let mut ignored_entries = 0;
776    let mut context = CacheReplayContext::for_snapshot_tail();
777
778    for entry in scan {
779        let entry = entry?;
780
781        if entry.seq < plan.from_seq {
782            return Err(CacheReplayError::UnexpectedSeq {
783                seq: entry.seq,
784                from_seq: plan.from_seq,
785            });
786        }
787
788        if apply_cache_replay_entry_with_context(cache, &entry, &mut context)? {
789            applied_entries += 1;
790        } else {
791            ignored_entries += 1;
792        }
793    }
794
795    context.ensure_complete()?;
796
797    Ok(CacheReplayReport {
798        plan,
799        applied_entries,
800        ignored_entries,
801    })
802}
803
804/// Replays the cache snapshot tail when the cache snapshot has already been restored.
805///
806/// This is a convenience wrapper for callers that load the cache-owned snapshot blob
807/// before entering the event-store replay path.
808///
809/// # Errors
810///
811/// Returns an error if [`restore_cache_snapshot_and_replay_tail`] fails.
812pub fn replay_cache_snapshot_tail<B>(
813    cache: &mut Cache,
814    reader: &EventStoreReader<B>,
815) -> Result<CacheReplayReport, CacheReplayError>
816where
817    B: EventStore,
818{
819    restore_cache_snapshot_and_replay_tail(cache, reader, |_, _| Ok(()))
820}
821
822/// Plans event-store-only forensics replay inputs.
823///
824/// The plan scans the requested range in durable `seq` order and records only summary
825/// metadata. Use [`load_forensics_replay_inputs`] to materialize the entries.
826///
827/// # Errors
828///
829/// Returns an error if `range` is invalid or the reader scan fails.
830pub fn plan_forensics_replay_inputs<B>(
831    reader: &EventStoreReader<B>,
832    range: ReplaySeqRange,
833) -> Result<ReplayInputPlan, ReplayInputError>
834where
835    B: EventStore,
836{
837    let span = collect_replay_entry_span(reader, range)?;
838    Ok(ReplayInputPlan {
839        requested_range: range,
840        event_range: span.event_range,
841        event_count: span.event_count,
842        event_time_range: span.time_range,
843        catalog_slices: Vec::new(),
844    })
845}
846
847/// Loads event-store-only forensics replay inputs.
848///
849/// Entries are returned in durable `seq` order. This function does not touch the data catalog,
850/// live venues, strategy code, reconciliation, or clocks.
851///
852/// # Errors
853///
854/// Returns an error if the reader scan fails.
855pub fn load_forensics_replay_inputs<B>(
856    reader: &EventStoreReader<B>,
857    plan: &ReplayInputPlan,
858) -> Result<ReplayInputs, ReplayInputError>
859where
860    B: EventStore,
861{
862    let entries = load_replay_entries(reader, plan.requested_range)?;
863    Ok(ReplayInputs {
864        entries,
865        catalog_slices: Vec::new(),
866    })
867}
868
869/// Plans replay inputs by joining event-store entries with selected catalog slices.
870///
871/// The event-store range supplies durable replay order. Catalog slices are contextual input
872/// selected by the caller; their timestamps bound data lookup but never replace `seq` ordering.
873///
874/// # Errors
875///
876/// Returns an error if:
877///
878/// - No catalog slices are selected.
879/// - `range` is invalid.
880/// - An unbounded selector cannot inherit bounds from an empty event-store scan.
881/// - A resolved slice has `start > end`.
882/// - Catalog planning fails.
883/// - The reader scan fails.
884pub fn plan_catalog_replay_inputs<B, C>(
885    reader: &EventStoreReader<B>,
886    catalog: &mut C,
887    range: ReplaySeqRange,
888    catalog_slices: &[CatalogSliceSelector],
889) -> Result<ReplayInputPlan, ReplayInputError>
890where
891    B: EventStore,
892    C: ReplayCatalog,
893{
894    plan_catalog_joined_replay_inputs(reader, catalog, range, catalog_slices)
895}
896
897/// Loads catalog replay inputs from an existing plan.
898///
899/// Event-store entries are returned in durable `seq` order. Catalog records are loaded through
900/// the caller-provided catalog source only; this function does not query live venues or run engine
901/// logic.
902///
903/// # Errors
904///
905/// Returns an error if a required slice is missing, if catalog loading fails, or if the reader scan
906/// fails.
907pub fn load_catalog_replay_inputs<B, C>(
908    reader: &EventStoreReader<B>,
909    catalog: &mut C,
910    plan: &ReplayInputPlan,
911) -> Result<ReplayInputs, ReplayInputError>
912where
913    B: EventStore,
914    C: ReplayCatalog,
915{
916    load_catalog_joined_replay_inputs(reader, catalog, plan)
917}
918
919/// Restores cache state from a sealed run without publishing to the bus or touching live venues.
920///
921/// The loader opens `<base_dir>/<instance_id>/<run_id>.redb` through the sealed-run reader path,
922/// rejects quarantined sources, restores the cache-owned snapshot blob when an anchor exists, and
923/// applies the event-store tail in `seq` order. It does not open adapters, reconcile against a
924/// venue, submit new entries, or query the data catalog.
925///
926/// # Errors
927///
928/// Returns an error if the run is missing, not sealed, quarantined, or unreadable; see
929/// [`restore_cache_snapshot_and_replay_tail`] for snapshot, decode, and apply failures.
930pub fn restore_cache_from_sealed_run(
931    cache: &mut Cache,
932    base_dir: impl Into<PathBuf>,
933    instance_id: &str,
934    run_id: &str,
935) -> Result<EventStoreReplayReport, CacheReplayError> {
936    let (manifest, reader) = open_event_store_replay_source(base_dir, instance_id, run_id)?;
937    let cache_report =
938        restore_cache_snapshot_and_replay_tail(cache, &reader, restore_cache_snapshot_blob)?;
939
940    Ok(EventStoreReplayReport {
941        manifest,
942        cache: cache_report,
943    })
944}
945
946/// Opens a sealed run for replay without touching live venues.
947///
948/// # Errors
949///
950/// Returns an error if the run is missing, not sealed, quarantined, or unreadable.
951pub fn open_event_store_replay_source(
952    base_dir: impl Into<PathBuf>,
953    instance_id: &str,
954    run_id: &str,
955) -> Result<(RunManifest, EventStoreReader<RedbBackend>), CacheReplayError> {
956    let backend = RedbBackend::open_sealed(base_dir, instance_id, run_id)?;
957    let manifest = backend.manifest()?;
958    reject_quarantined_replay_source(run_id, manifest.status)?;
959    Ok((manifest, EventStoreReader::new(backend)))
960}
961
962/// Validates that a configured replay source exists, is sealed, and is not quarantined.
963///
964/// # Errors
965///
966/// Returns an error if the run is missing, not sealed, quarantined, or unreadable.
967pub fn validate_event_store_replay_source(
968    base_dir: impl Into<PathBuf>,
969    instance_id: &str,
970    run_id: &str,
971) -> Result<RunManifest, CacheReplayError> {
972    let backend = RedbBackend::open_sealed(base_dir, instance_id, run_id)?;
973    let manifest = backend.manifest()?;
974    reject_quarantined_replay_source(run_id, manifest.status)?;
975    Ok(manifest)
976}
977
978#[derive(Clone, Copy, Debug, PartialEq, Eq)]
979struct ReplayEntrySpan {
980    event_range: Option<ReplaySeqRange>,
981    event_count: usize,
982    time_range: Option<ReplayTimeRange>,
983}
984
985fn plan_catalog_joined_replay_inputs<B, C>(
986    reader: &EventStoreReader<B>,
987    catalog: &mut C,
988    range: ReplaySeqRange,
989    catalog_slices: &[CatalogSliceSelector],
990) -> Result<ReplayInputPlan, ReplayInputError>
991where
992    B: EventStore,
993    C: ReplayCatalog,
994{
995    if catalog_slices.is_empty() {
996        return Err(ReplayInputError::EmptyCatalogSelection);
997    }
998
999    let span = collect_replay_entry_span(reader, range)?;
1000    let catalog_slices = plan_catalog_slices(catalog, catalog_slices, span.time_range)?;
1001
1002    Ok(ReplayInputPlan {
1003        requested_range: range,
1004        event_range: span.event_range,
1005        event_count: span.event_count,
1006        event_time_range: span.time_range,
1007        catalog_slices,
1008    })
1009}
1010
1011fn load_catalog_joined_replay_inputs<B, C>(
1012    reader: &EventStoreReader<B>,
1013    catalog: &mut C,
1014    plan: &ReplayInputPlan,
1015) -> Result<ReplayInputs, ReplayInputError>
1016where
1017    B: EventStore,
1018    C: ReplayCatalog,
1019{
1020    let entries = load_replay_entries(reader, plan.requested_range)?;
1021    let catalog_slices = load_catalog_slices(catalog, &plan.catalog_slices)?;
1022
1023    Ok(ReplayInputs {
1024        entries,
1025        catalog_slices,
1026    })
1027}
1028
1029fn collect_replay_entry_span<B>(
1030    reader: &EventStoreReader<B>,
1031    range: ReplaySeqRange,
1032) -> Result<ReplayEntrySpan, ReplayInputError>
1033where
1034    B: EventStore,
1035{
1036    validate_seq_range(range)?;
1037
1038    let mut first_seq = None;
1039    let mut last_seq = None;
1040    let mut event_count = 0;
1041    let mut time_range: Option<ReplayTimeRange> = None;
1042
1043    for entry in reader.scan_range(range.from_seq, range.to_seq, ScanDirection::Forward) {
1044        let entry = entry?;
1045        first_seq.get_or_insert(entry.seq);
1046        last_seq = Some(entry.seq);
1047        event_count += 1;
1048
1049        match time_range.as_mut() {
1050            Some(bounds) => bounds.include_entry(&entry),
1051            None => time_range = Some(ReplayTimeRange::from_entry(&entry)),
1052        }
1053    }
1054
1055    let event_range = match (first_seq, last_seq) {
1056        (Some(from_seq), Some(to_seq)) => Some(ReplaySeqRange::new(from_seq, to_seq)),
1057        _ => None,
1058    };
1059
1060    Ok(ReplayEntrySpan {
1061        event_range,
1062        event_count,
1063        time_range,
1064    })
1065}
1066
1067fn load_replay_entries<B>(
1068    reader: &EventStoreReader<B>,
1069    range: ReplaySeqRange,
1070) -> Result<Vec<EventStoreEntry>, ReplayInputError>
1071where
1072    B: EventStore,
1073{
1074    validate_seq_range(range)?;
1075
1076    reader
1077        .scan_range(range.from_seq, range.to_seq, ScanDirection::Forward)
1078        .collect::<Result<Vec<_>, _>>()
1079        .map_err(ReplayInputError::from)
1080}
1081
1082fn plan_catalog_slices<C>(
1083    catalog: &mut C,
1084    selectors: &[CatalogSliceSelector],
1085    event_time_range: Option<ReplayTimeRange>,
1086) -> Result<Vec<CatalogSlicePlan>, ReplayInputError>
1087where
1088    C: ReplayCatalog,
1089{
1090    let mut plans = Vec::with_capacity(selectors.len());
1091
1092    for selector in selectors {
1093        let query = resolve_catalog_slice_query(selector, event_time_range)?;
1094        let coverage = catalog
1095            .plan_slice(&query)
1096            .map_err(|e| ReplayInputError::Catalog {
1097                data_cls: query.data_cls.clone(),
1098                message: e.to_string(),
1099            })?;
1100        plans.push(CatalogSlicePlan { query, coverage });
1101    }
1102
1103    Ok(plans)
1104}
1105
1106fn load_catalog_slices<C>(
1107    catalog: &mut C,
1108    plans: &[CatalogSlicePlan],
1109) -> Result<Vec<CatalogReplaySlice>, ReplayInputError>
1110where
1111    C: ReplayCatalog,
1112{
1113    let mut slices = Vec::with_capacity(plans.len());
1114
1115    for plan in plans {
1116        if plan.is_missing() {
1117            if plan.query.required {
1118                return Err(ReplayInputError::MissingCatalogSlice {
1119                    data_cls: plan.query.data_cls.clone(),
1120                    identifiers: plan.query.identifiers.clone(),
1121                });
1122            }
1123
1124            slices.push(CatalogReplaySlice {
1125                plan: plan.clone(),
1126                records: Vec::new(),
1127            });
1128            continue;
1129        }
1130
1131        let records = catalog
1132            .load_slice(plan)
1133            .map_err(|e| ReplayInputError::Catalog {
1134                data_cls: plan.query.data_cls.clone(),
1135                message: e.to_string(),
1136            })?;
1137        slices.push(CatalogReplaySlice {
1138            plan: plan.clone(),
1139            records,
1140        });
1141    }
1142
1143    Ok(slices)
1144}
1145
1146fn resolve_catalog_slice_query(
1147    selector: &CatalogSliceSelector,
1148    event_time_range: Option<ReplayTimeRange>,
1149) -> Result<CatalogSliceQuery, ReplayInputError> {
1150    let Some(start) = selector
1151        .start
1152        .or(event_time_range.map(|bounds| bounds.start))
1153    else {
1154        return Err(ReplayInputError::MissingCatalogTimeBounds {
1155            data_cls: selector.data_cls.clone(),
1156        });
1157    };
1158    let Some(end) = selector.end.or(event_time_range.map(|bounds| bounds.end)) else {
1159        return Err(ReplayInputError::MissingCatalogTimeBounds {
1160            data_cls: selector.data_cls.clone(),
1161        });
1162    };
1163
1164    if start > end {
1165        return Err(ReplayInputError::InvalidCatalogTimeRange {
1166            data_cls: selector.data_cls.clone(),
1167            start: start.as_u64(),
1168            end: end.as_u64(),
1169        });
1170    }
1171
1172    Ok(CatalogSliceQuery {
1173        data_cls: selector.data_cls.clone(),
1174        identifiers: selector.identifiers.clone(),
1175        start,
1176        end,
1177        required: selector.required,
1178    })
1179}
1180
1181fn validate_seq_range(range: ReplaySeqRange) -> Result<(), ReplayInputError> {
1182    if range.from_seq == 0 {
1183        return Err(ReplayInputError::InvalidSeqRange {
1184            from_seq: range.from_seq,
1185            to_seq: range.to_seq,
1186            message: "seq is 1-based".to_string(),
1187        });
1188    }
1189
1190    if range.from_seq > range.to_seq {
1191        return Err(ReplayInputError::InvalidSeqRange {
1192            from_seq: range.from_seq,
1193            to_seq: range.to_seq,
1194            message: "from_seq exceeds to_seq".to_string(),
1195        });
1196    }
1197
1198    Ok(())
1199}
1200
1201/// Restores the cache-owned snapshot blob identified by `anchor`.
1202///
1203/// # Errors
1204///
1205/// Returns an error if the blob is missing, fails to load, fails its content hash check, or fails
1206/// to restore into the cache.
1207pub fn restore_cache_snapshot_blob(
1208    cache: &mut Cache,
1209    anchor: Option<&SnapshotAnchor>,
1210) -> Result<(), CacheReplayError> {
1211    let Some(anchor) = anchor else {
1212        return Ok(());
1213    };
1214
1215    let blob = cache
1216        .load_snapshot_blob(&anchor.blob_ref)
1217        .map_err(|e| CacheReplayError::snapshot_restore(anchor, e))?
1218        .ok_or_else(|| CacheReplayError::snapshot_restore(anchor, "snapshot blob not found"))?;
1219    let actual_hash = compute_snapshot_content_hash(blob.as_ref());
1220
1221    if actual_hash != anchor.content_hash {
1222        return Err(CacheReplayError::snapshot_restore(
1223            anchor,
1224            format!(
1225                "content_hash mismatch: expected {}, actual {actual_hash}",
1226                anchor.content_hash
1227            ),
1228        ));
1229    }
1230
1231    cache
1232        .restore_snapshot_blob(&anchor.blob_ref, blob)
1233        .map_err(|e| CacheReplayError::snapshot_restore(anchor, e))
1234}
1235
1236/// Applies one event-store entry to cache state when a replay rule exists.
1237///
1238/// Returns `Ok(true)` when the entry changed cache state and `Ok(false)` when the
1239/// payload is outside the current cache bootstrap replay surface, or when the entry's
1240/// position target cannot be established (a position event's target is absent, or a
1241/// fill's instrument is missing so the position cannot open). The latter paths log a
1242/// warning so the report's ignored count surfaces the divergence instead of claiming
1243/// a full apply.
1244///
1245/// # Errors
1246///
1247/// Returns an error if a supported payload cannot be decoded or the decoded payload cannot be
1248/// applied to the cache. Position reversals require [`replay_cache_snapshot_tail`] so the following
1249/// [`PositionOpened`] event can complete the transition.
1250pub fn apply_cache_replay_entry(
1251    cache: &mut Cache,
1252    entry: &EventStoreEntry,
1253) -> Result<bool, CacheReplayError> {
1254    let mut context = CacheReplayContext::default();
1255    let applied = apply_cache_replay_entry_with_context(cache, entry, &mut context)?;
1256    context.ensure_complete()?;
1257    Ok(applied)
1258}
1259
1260fn apply_cache_replay_entry_with_context(
1261    cache: &mut Cache,
1262    entry: &EventStoreEntry,
1263    context: &mut CacheReplayContext,
1264) -> Result<bool, CacheReplayError> {
1265    if apply_complete_cache_payload_entry(cache, entry)? {
1266        return Ok(true);
1267    }
1268
1269    match entry.payload_type.as_str() {
1270        PAYLOAD_TYPE_ACCOUNT_STATE => {
1271            let state = decode_payload::<AccountState>(entry)?;
1272            apply_result(entry, cache.update_account_state(&state))?;
1273        }
1274        PAYLOAD_TYPE_INSTRUMENT_CLOSE => {
1275            let close = decode_payload::<InstrumentClose>(entry)?;
1276            apply_result(entry, settle_instrument_close(cache, close))?;
1277        }
1278        PAYLOAD_TYPE_ORDER_INITIALIZED => {
1279            let event = decode_order_event::<OrderInitialized>(entry, OrderEventAny::Initialized)?;
1280            let order = OrderAny::from_events(vec![event]).map_err(|e| apply_error(entry, e))?;
1281            apply_result(entry, cache.add_order(order, None, None, false))?;
1282        }
1283        PAYLOAD_TYPE_ORDER_DENIED => {
1284            apply_order_event(cache, entry, OrderEventAny::Denied)?;
1285        }
1286        PAYLOAD_TYPE_ORDER_EMULATED => {
1287            apply_order_event(cache, entry, OrderEventAny::Emulated)?;
1288        }
1289        PAYLOAD_TYPE_ORDER_RELEASED => {
1290            apply_order_event(cache, entry, OrderEventAny::Released)?;
1291        }
1292        PAYLOAD_TYPE_ORDER_SUBMITTED => {
1293            apply_order_event(cache, entry, OrderEventAny::Submitted)?;
1294        }
1295        PAYLOAD_TYPE_ORDER_ACCEPTED => {
1296            apply_order_event(cache, entry, OrderEventAny::Accepted)?;
1297        }
1298        PAYLOAD_TYPE_ORDER_REJECTED => {
1299            apply_order_event(cache, entry, OrderEventAny::Rejected)?;
1300        }
1301        PAYLOAD_TYPE_ORDER_CANCELED => {
1302            apply_order_event(cache, entry, OrderEventAny::Canceled)?;
1303        }
1304        PAYLOAD_TYPE_ORDER_EXPIRED => {
1305            apply_order_event(cache, entry, OrderEventAny::Expired)?;
1306        }
1307        PAYLOAD_TYPE_ORDER_TRIGGERED => {
1308            apply_order_event(cache, entry, OrderEventAny::Triggered)?;
1309        }
1310        PAYLOAD_TYPE_ORDER_PENDING_UPDATE => {
1311            apply_order_event(cache, entry, OrderEventAny::PendingUpdate)?;
1312        }
1313        PAYLOAD_TYPE_ORDER_PENDING_CANCEL => {
1314            apply_order_event(cache, entry, OrderEventAny::PendingCancel)?;
1315        }
1316        PAYLOAD_TYPE_ORDER_MODIFY_DENIED => {
1317            return apply_order_event(cache, entry, OrderEventAny::ModifyDenied);
1318        }
1319        PAYLOAD_TYPE_ORDER_MODIFY_REJECTED => {
1320            apply_order_event(cache, entry, OrderEventAny::ModifyRejected)?;
1321        }
1322        PAYLOAD_TYPE_ORDER_CANCEL_DENIED => {
1323            return apply_order_event(cache, entry, OrderEventAny::CancelDenied);
1324        }
1325        PAYLOAD_TYPE_ORDER_CANCEL_REJECTED => {
1326            apply_order_event(cache, entry, OrderEventAny::CancelRejected)?;
1327        }
1328        PAYLOAD_TYPE_ORDER_UPDATED => {
1329            apply_order_event(cache, entry, OrderEventAny::Updated)?;
1330        }
1331        PAYLOAD_TYPE_ORDER_FILLED => return apply_order_filled(cache, entry, context),
1332        PAYLOAD_TYPE_ORDER_FILL_VOIDED => {
1333            let fill_voided = decode_payload::<OrderFillVoided>(entry)?;
1334            apply_fill_void_to_order_and_positions(cache, entry, &fill_voided)?;
1335        }
1336        PAYLOAD_TYPE_POSITION_OPENED => {
1337            let opened = decode_payload::<PositionOpened>(entry)?;
1338            if let Some(applied) = apply_pending_flip_opened(cache, entry, &opened, context)? {
1339                return Ok(applied);
1340            }
1341            return apply_position_opened(cache, entry, &opened);
1342        }
1343        PAYLOAD_TYPE_POSITION_CHANGED => {
1344            let changed = decode_payload::<PositionChanged>(entry)?;
1345            return apply_position_changed(cache, entry, &changed);
1346        }
1347        PAYLOAD_TYPE_POSITION_CLOSED => {
1348            let closed = decode_payload::<PositionClosed>(entry)?;
1349            return apply_position_closed(cache, entry, &closed);
1350        }
1351        PAYLOAD_TYPE_POSITION_ADJUSTED => {
1352            let adjustment = decode_payload::<PositionAdjusted>(entry)?;
1353            return apply_position_adjustment(cache, entry, adjustment);
1354        }
1355        _ => return Ok(false),
1356    }
1357
1358    Ok(true)
1359}
1360
1361fn apply_complete_cache_payload_entry(
1362    cache: &mut Cache,
1363    entry: &EventStoreEntry,
1364) -> Result<bool, CacheReplayError> {
1365    match entry.payload_type.as_str() {
1366        crate::capture::builtins::PAYLOAD_TYPE_DATA_RESPONSE_ENVELOPE => {
1367            let response =
1368                decode_payload::<crate::capture::builtins::ResponseEnvelopeCapture>(entry)?;
1369
1370            let (Some(payload_type), Some(payload)) = (response.payload_type, response.payload)
1371            else {
1372                return Ok(false);
1373            };
1374
1375            if payload_type.as_str()
1376                == crate::capture::builtins::PAYLOAD_TYPE_DATA_RESPONSE_ENVELOPE
1377            {
1378                return Err(apply_error(
1379                    entry,
1380                    "Historical response payload cannot contain another envelope",
1381                ));
1382            }
1383
1384            let payload_entry = EventStoreEntry {
1385                payload_type,
1386                payload,
1387                ..entry.clone()
1388            };
1389
1390            return apply_complete_cache_payload_entry(cache, &payload_entry);
1391        }
1392
1393        PAYLOAD_TYPE_SUBMIT_ORDER_LIST => {
1394            let command = decode_payload::<SubmitOrderList>(entry)?;
1395            apply_result(entry, cache.add_order_list(command.order_list))?;
1396        }
1397        PAYLOAD_TYPE_INSTRUMENT_RESPONSE => {
1398            let response = decode_payload::<InstrumentResponse>(entry)?;
1399            apply_result(entry, cache.add_instrument(response.data))?;
1400        }
1401        PAYLOAD_TYPE_INSTRUMENTS_RESPONSE => {
1402            let response = decode_payload::<InstrumentsResponse>(entry)?;
1403            for instrument in response.data {
1404                apply_result(entry, cache.add_instrument(instrument))?;
1405            }
1406        }
1407        PAYLOAD_TYPE_QUOTES_RESPONSE => {
1408            let data = decode_response_ticks(entry, |response: QuotesResponse| response.data)?;
1409            if !data.is_empty() {
1410                apply_result(entry, cache.add_quotes(&data))?;
1411            }
1412        }
1413        PAYLOAD_TYPE_TRADES_RESPONSE => {
1414            let data = decode_response_ticks(entry, |response: TradesResponse| response.data)?;
1415            if !data.is_empty() {
1416                apply_result(entry, cache.add_trades(&data))?;
1417            }
1418        }
1419        PAYLOAD_TYPE_FUNDING_RATES_RESPONSE => {
1420            let response = decode_payload::<FundingRatesResponse>(entry)?;
1421            if !response.data.is_empty() {
1422                apply_result(entry, cache.add_funding_rates(&response.data))?;
1423            }
1424        }
1425        PAYLOAD_TYPE_BARS_RESPONSE => {
1426            let response = decode_payload::<BarsResponse>(entry)?;
1427            if !response.data.is_empty() {
1428                apply_result(entry, cache.add_bars(&response.data))?;
1429            }
1430        }
1431        _ => return Ok(false),
1432    }
1433
1434    Ok(true)
1435}
1436
1437fn apply_order_event<T>(
1438    cache: &mut Cache,
1439    entry: &EventStoreEntry,
1440    wrap: impl FnOnce(T) -> OrderEventAny,
1441) -> Result<bool, CacheReplayError>
1442where
1443    T: DeserializeOwned,
1444{
1445    let event = decode_order_event(entry, wrap)?;
1446    if !cache.order_exists(&event.client_order_id())
1447        && matches!(
1448            event,
1449            OrderEventAny::ModifyDenied(_) | OrderEventAny::CancelDenied(_)
1450        )
1451    {
1452        return Ok(false);
1453    }
1454
1455    apply_result(entry, cache.update_order(&event))?;
1456    Ok(true)
1457}
1458
1459fn decode_order_event<T>(
1460    entry: &EventStoreEntry,
1461    wrap: impl FnOnce(T) -> OrderEventAny,
1462) -> Result<OrderEventAny, CacheReplayError>
1463where
1464    T: DeserializeOwned,
1465{
1466    Ok(wrap(decode_payload(entry)?))
1467}
1468
1469fn apply_order_filled(
1470    cache: &mut Cache,
1471    entry: &EventStoreEntry,
1472    context: &mut CacheReplayContext,
1473) -> Result<bool, CacheReplayError> {
1474    let replay_side = decode_payload::<OrderFilledReplaySide>(entry)?;
1475    if replay_side.order_side.is_none() {
1476        return Err(apply_error(
1477            entry,
1478            "OrderFilled.order_side must be Buy or Sell, was NoOrderSide",
1479        ));
1480    }
1481    let fill = decode_payload::<OrderFilled>(entry)?;
1482    let event = OrderEventAny::Filled(fill.clone());
1483    let orderless_leg_fill = is_orderless_leg_fill(cache, &fill);
1484    if !orderless_leg_fill {
1485        apply_result(entry, cache.update_order(&event))?;
1486    }
1487
1488    let flip_applied = apply_flip_fill(cache, entry, &fill, context)?;
1489
1490    if flip_applied {
1491        return Ok(true);
1492    }
1493
1494    apply_fill_to_position(cache, entry, &fill, orderless_leg_fill)
1495}
1496
1497#[derive(Deserialize)]
1498struct OrderFilledReplaySide {
1499    #[serde(with = "nautilus_model::enums::serde_option_order_side")]
1500    order_side: Option<OrderSide>,
1501}
1502
1503fn apply_flip_fill(
1504    cache: &mut Cache,
1505    entry: &EventStoreEntry,
1506    fill: &OrderFilled,
1507    context: &mut CacheReplayContext,
1508) -> Result<bool, CacheReplayError> {
1509    if context.contains_flip_source(fill) {
1510        return Ok(true);
1511    }
1512
1513    let Some(position_id) = fill.position_id else {
1514        return Ok(false);
1515    };
1516
1517    let mut position = {
1518        let Some(position) = cache.position(&position_id) else {
1519            return Ok(false);
1520        };
1521
1522        if !position.is_closed() && position.trade_ids.contains(&fill.trade_id) {
1523            return Ok(!position.accepts_price_restatement(fill));
1524        }
1525
1526        if position.is_closed()
1527            || !position.is_opposite_side(fill.order_side)
1528            || fill.last_qty <= position.quantity
1529        {
1530            return Ok(false);
1531        }
1532
1533        if !context.allow_deferred_flips {
1534            return Err(apply_error(
1535                entry,
1536                "position flip requires snapshot-tail replay context to match the following PositionOpened event",
1537            ));
1538        }
1539
1540        position.clone()
1541    };
1542
1543    let oms_type = cache.oms_type(&position_id).unwrap_or(OmsType::Unspecified);
1544    let (closing_fill, opening_fill) = fill
1545        .split_for_position_flip(position.quantity, None, fill.event_id)
1546        .map_err(|e| apply_error(entry, e))?;
1547    apply_result(entry, position.try_apply(&closing_fill))?;
1548    apply_result(entry, cache.update_position(&position))?;
1549    context.push_flip(entry.seq, position_id, oms_type, opening_fill);
1550    Ok(true)
1551}
1552
1553fn apply_pending_flip_opened(
1554    cache: &mut Cache,
1555    entry: &EventStoreEntry,
1556    opened: &PositionOpened,
1557    context: &mut CacheReplayContext,
1558) -> Result<Option<bool>, CacheReplayError> {
1559    let Some((opening_fill, oms_type)) = context.take_opening_fill(entry, opened)? else {
1560        return Ok(None);
1561    };
1562    let instrument = cache
1563        .instrument(&opening_fill.instrument_id)
1564        .cloned()
1565        .ok_or_else(|| {
1566            apply_error(
1567                entry,
1568                format!(
1569                    "instrument {} not found for flipped position {}",
1570                    opening_fill.instrument_id, opened.position_id,
1571                ),
1572            )
1573        })?;
1574
1575    let index_order = !is_orderless_leg_fill(cache, &opening_fill);
1576    let position = apply_result(entry, Position::new_checked(&instrument, opening_fill))?;
1577    validate_position_opened(entry, &position, opened)?;
1578    if oms_type == OmsType::Netting
1579        && let Some(prior) = cache.position_owned(&opened.position_id)
1580    {
1581        apply_result(entry, cache.snapshot_position(&prior))?;
1582    }
1583
1584    apply_result(
1585        entry,
1586        cache.replace_position(&position, oms_type, index_order, true),
1587    )?;
1588
1589    apply_position_opened(cache, entry, opened).map(Some)
1590}
1591
1592// Returns `Ok(true)` when the position side applied (no position association, or an
1593// idempotent replay no-op) and `Ok(false)` when the instrument needed to open the
1594// position is missing, so the report's ignored count surfaces the divergence.
1595fn apply_fill_to_position(
1596    cache: &mut Cache,
1597    entry: &EventStoreEntry,
1598    fill: &OrderFilled,
1599    orderless_leg_fill: bool,
1600) -> Result<bool, CacheReplayError> {
1601    let Some(position_id) = fill.position_id else {
1602        return Ok(true);
1603    };
1604
1605    // Live execution applies a fill after settlement to its order only
1606    if settlement_close(cache, &fill.instrument_id).is_some() {
1607        return Ok(true);
1608    }
1609
1610    if let Some(mut position) = cache.position_owned(&position_id) {
1611        // Mirror live `Position::apply_fill`: a duplicate inside an open episode is
1612        // the idempotent replay no-op; historical duplicates on a Flat position are
1613        // ignored inside `apply` itself from the carried replay history.
1614        if position.side != PositionSide::Flat
1615            && position.trade_ids.contains(&fill.trade_id)
1616            && !position.accepts_price_restatement(fill)
1617        {
1618            return Ok(true);
1619        }
1620
1621        apply_result(entry, position.try_apply(fill))?;
1622        apply_result(entry, cache.update_position(&position))?;
1623        return Ok(true);
1624    }
1625
1626    let Some(instrument) = cache.instrument(&fill.instrument_id).cloned() else {
1627        log::warn!(
1628            "Replay seq {} skipped opening position {position_id}: instrument {} not in cache",
1629            entry.seq,
1630            fill.instrument_id,
1631        );
1632        return Ok(false);
1633    };
1634
1635    let position = apply_result(entry, Position::new_checked(&instrument, fill.clone()))?;
1636
1637    if orderless_leg_fill {
1638        apply_result(
1639            entry,
1640            cache.add_position_without_order(&position, OmsType::Unspecified),
1641        )?;
1642    } else {
1643        apply_result(entry, cache.add_position(&position, OmsType::Unspecified))?;
1644    }
1645    Ok(true)
1646}
1647
1648fn is_orderless_leg_fill(cache: &Cache, fill: &OrderFilled) -> bool {
1649    if !fill.client_order_id.as_str().contains("-LEG-")
1650        && !fill.venue_order_id.as_str().contains("-LEG-")
1651    {
1652        return false;
1653    }
1654
1655    let is_non_spread_instrument = cache
1656        .instrument(&fill.instrument_id)
1657        .is_none_or(|instrument| !instrument.is_spread());
1658
1659    is_non_spread_instrument
1660        && !cache.order_exists(&fill.client_order_id)
1661        && cache.client_order_id(&fill.venue_order_id).is_none()
1662}
1663
1664fn apply_fill_void_to_order_and_positions(
1665    cache: &mut Cache,
1666    entry: &EventStoreEntry,
1667    fill_voided: &OrderFillVoided,
1668) -> Result<(), CacheReplayError> {
1669    let event = OrderEventAny::FillVoided(fill_voided.clone());
1670    let order = cache
1671        .order_owned(&fill_voided.client_order_id)
1672        .ok_or_else(|| {
1673            apply_error(
1674                entry,
1675                format!("order {} not found", fill_voided.client_order_id),
1676            )
1677        })?;
1678    let original_fill = order
1679        .events()
1680        .into_iter()
1681        .find_map(|candidate| match candidate {
1682            OrderEventAny::Filled(fill) if fill.trade_id == fill_voided.trade_id => Some(fill),
1683            _ => None,
1684        });
1685
1686    let mut validated_order = order.clone();
1687    apply_result(entry, validated_order.apply(event.clone()))?;
1688
1689    // Live execution applies a void after settlement to its order only
1690    let corrected_positions = match original_fill.filter(|fill| fill.position_id.is_some()) {
1691        Some(original_fill) if settlement_close(cache, &fill_voided.instrument_id).is_none() => {
1692            prepare_fill_void_positions(cache, entry, fill_voided, original_fill.event_id)?
1693        }
1694        _ => Vec::new(),
1695    };
1696
1697    apply_result(entry, cache.update_order(&event))?;
1698    for position in corrected_positions {
1699        apply_result(entry, cache.update_position(&position))?;
1700    }
1701    Ok(())
1702}
1703
1704fn prepare_fill_void_positions(
1705    cache: &Cache,
1706    entry: &EventStoreEntry,
1707    fill_voided: &OrderFillVoided,
1708    source_event_id: UUID4,
1709) -> Result<Vec<Position>, CacheReplayError> {
1710    let fragments = collect_fill_void_fragments(cache, entry, fill_voided, source_event_id)?;
1711    let allocations = allocate_fill_void_fragments(entry, fill_voided, &fragments)?;
1712    let mut corrected_positions = Vec::new();
1713
1714    for (position_id, (voided_qty, commission_voided)) in allocations {
1715        if voided_qty.is_zero() {
1716            return Err(apply_error(
1717                entry,
1718                format!(
1719                    "commission-only position correction requires authoritative reconciliation for fill {}",
1720                    fill_voided.trade_id
1721                ),
1722            ));
1723        }
1724        let mut position = cache
1725            .position_owned(&position_id)
1726            .ok_or_else(|| apply_error(entry, format!("position {position_id} not found")))?;
1727        let previous = position
1728            .fill_voids
1729            .iter()
1730            .rev()
1731            .find(|record| {
1732                record.event.client_order_id == fill_voided.client_order_id
1733                    && record.event.trade_id == fill_voided.trade_id
1734            })
1735            .map(|record| (record.voided_qty, record.commission_voided));
1736        if previous == Some((voided_qty, commission_voided)) {
1737            continue;
1738        }
1739        apply_result(
1740            entry,
1741            position.apply_fill_void(fill_voided.clone(), voided_qty, commission_voided),
1742        )?;
1743        corrected_positions.push(position);
1744    }
1745    Ok(corrected_positions)
1746}
1747
1748#[derive(Clone, Copy, Debug)]
1749struct FillVoidFragment {
1750    position_id: PositionId,
1751    split_rank: u8,
1752    quantity: Quantity,
1753    commission: Option<Money>,
1754}
1755
1756fn collect_fill_void_fragments(
1757    cache: &Cache,
1758    entry: &EventStoreEntry,
1759    fill_voided: &OrderFillVoided,
1760    source_event_id: UUID4,
1761) -> Result<Vec<FillVoidFragment>, CacheReplayError> {
1762    let positions: Vec<Position> = cache
1763        .positions(
1764            None,
1765            Some(&fill_voided.instrument_id),
1766            Some(&fill_voided.strategy_id),
1767            Some(&fill_voided.account_id),
1768            None,
1769        )
1770        .into_iter()
1771        .map(|position| position.cloned())
1772        .collect();
1773    let mut fragments = Vec::new();
1774
1775    for position in &positions {
1776        for replay_event in &position.replay_events {
1777            let PositionReplayEvent::Filled(fill) = replay_event else {
1778                continue;
1779            };
1780
1781            if fill.client_order_id != fill_voided.client_order_id
1782                || fill.trade_id != fill_voided.trade_id
1783            {
1784                continue;
1785            }
1786            let split_rank = if fill.event_id == source_event_id {
1787                0
1788            } else if fill.causation_id == Some(source_event_id) {
1789                1
1790            } else {
1791                continue;
1792            };
1793            fragments.push(FillVoidFragment {
1794                position_id: position.id,
1795                split_rank,
1796                quantity: fill.last_qty,
1797                commission: fill.commission,
1798            });
1799        }
1800    }
1801
1802    if fragments.is_empty() {
1803        return Err(apply_error(
1804            entry,
1805            format!(
1806                "no position fragments found for fill {}",
1807                fill_voided.trade_id
1808            ),
1809        ));
1810    }
1811    fragments.sort_by_key(|fragment| fragment.split_rank);
1812    Ok(fragments)
1813}
1814
1815fn allocate_fill_void_fragments(
1816    entry: &EventStoreEntry,
1817    fill_voided: &OrderFillVoided,
1818    fragments: &[FillVoidFragment],
1819) -> Result<IndexMap<PositionId, (Quantity, Option<Money>)>, CacheReplayError> {
1820    let mut allocations = IndexMap::<PositionId, (Quantity, Option<Money>)>::new();
1821    let mut remaining_qty = fill_voided.voided_qty;
1822    for fragment in fragments.iter().rev() {
1823        if remaining_qty.is_zero() {
1824            break;
1825        }
1826        let removed = remaining_qty.min(fragment.quantity);
1827        let allocation = allocations
1828            .entry(fragment.position_id)
1829            .or_insert((Quantity::zero(removed.precision), None));
1830        let precision = allocation.0.precision.max(removed.precision);
1831        let total = quantity_raw_at_precision(entry, allocation.0, precision)?
1832            .checked_add(quantity_raw_at_precision(entry, removed, precision)?)
1833            .ok_or_else(|| apply_error(entry, "voided quantity allocation overflow"))?;
1834        allocation.0 = apply_result(entry, Quantity::from_raw_checked(total, precision))?;
1835        let precision = remaining_qty.precision.max(removed.precision);
1836        let remaining = quantity_raw_at_precision(entry, remaining_qty, precision)?
1837            .checked_sub(quantity_raw_at_precision(entry, removed, precision)?)
1838            .ok_or_else(|| apply_error(entry, "voided quantity allocation underflow"))?;
1839        remaining_qty = apply_result(entry, Quantity::from_raw_checked(remaining, precision))?;
1840    }
1841
1842    if remaining_qty.non_zero() {
1843        return Err(apply_error(
1844            entry,
1845            format!(
1846                "position fragments do not cover voided quantity for fill {}",
1847                fill_voided.trade_id
1848            ),
1849        ));
1850    }
1851
1852    if let Some(mut remaining_commission) = fill_voided.commission_voided {
1853        for fragment in fragments.iter().rev() {
1854            if remaining_commission.is_zero() {
1855                break;
1856            }
1857            let Some(commission) = fragment.commission else {
1858                continue;
1859            };
1860
1861            if commission.currency != remaining_commission.currency {
1862                return Err(apply_error(
1863                    entry,
1864                    format!(
1865                        "position commission currency differs for fill {}",
1866                        fill_voided.trade_id
1867                    ),
1868                ));
1869            }
1870
1871            let magnitude = remaining_commission.abs().min(commission.abs());
1872
1873            let removed = if remaining_commission.is_negative() {
1874                -magnitude
1875            } else {
1876                magnitude
1877            };
1878
1879            allocations
1880                .entry(fragment.position_id)
1881                .and_modify(|allocation| {
1882                    allocation.1 = Some(
1883                        allocation
1884                            .1
1885                            .map_or(removed, |commission| commission + removed),
1886                    );
1887                })
1888                .or_insert((
1889                    Quantity::zero(fill_voided.voided_qty.precision),
1890                    Some(removed),
1891                ));
1892            remaining_commission = remaining_commission - removed;
1893        }
1894
1895        if !remaining_commission.is_zero() {
1896            return Err(apply_error(
1897                entry,
1898                format!(
1899                    "position fragments do not cover voided commission for fill {}",
1900                    fill_voided.trade_id
1901                ),
1902            ));
1903        }
1904    }
1905    Ok(allocations)
1906}
1907
1908fn quantity_raw_at_precision(
1909    entry: &EventStoreEntry,
1910    quantity: Quantity,
1911    precision: u8,
1912) -> Result<QuantityRaw, CacheReplayError> {
1913    if quantity.raw() > QUANTITY_RAW_MAX {
1914        return Err(apply_error(entry, "voided quantity exceeds native bounds"));
1915    }
1916
1917    quantity
1918        .checked_rescale(precision)
1919        .map(|qty| qty.raw())
1920        .ok_or_else(|| apply_error(entry, "voided quantity scale alignment overflow"))
1921}
1922
1923fn apply_position_opened(
1924    cache: &mut Cache,
1925    entry: &EventStoreEntry,
1926    opened: &PositionOpened,
1927) -> Result<bool, CacheReplayError> {
1928    let Some(mut position) = cache.position_owned(&opened.position_id) else {
1929        warn_position_skip(entry, opened.position_id);
1930        return Ok(false);
1931    };
1932
1933    validate_position_opened(entry, &position, opened)?;
1934
1935    position.trader_id = opened.trader_id;
1936    position.strategy_id = opened.strategy_id;
1937    position.id = opened.position_id;
1938    position.account_id = opened.account_id;
1939    position.opening_order_id = opened.opening_order_id;
1940    position.closing_order_id = None;
1941    position.ts_opened = opened.ts_event;
1942    position.ts_last = opened.ts_event;
1943    position.ts_closed = None;
1944    position.duration_ns = DurationNanos::default();
1945
1946    apply_result(entry, cache.update_position(&position))?;
1947    Ok(true)
1948}
1949
1950fn validate_position_opened(
1951    entry: &EventStoreEntry,
1952    position: &Position,
1953    opened: &PositionOpened,
1954) -> Result<(), CacheReplayError> {
1955    let journal = (
1956        position.instrument_id,
1957        position.entry,
1958        position.side,
1959        position.signed_qty,
1960        position.quantity,
1961        position.quote_currency,
1962        position.avg_px_open,
1963        position.realized_pnl,
1964    );
1965    let notification = (
1966        opened.instrument_id,
1967        opened.entry,
1968        opened.side,
1969        opened.signed_qty,
1970        opened.quantity,
1971        opened.currency,
1972        opened.avg_px_open,
1973        opened.realized_pnl,
1974    );
1975
1976    if journal != notification {
1977        return Err(apply_error(
1978            entry,
1979            format!(
1980                "position {} lifecycle accounting differs from journal: expected {journal:?}, received {notification:?}",
1981                position.id
1982            ),
1983        ));
1984    }
1985
1986    Ok(())
1987}
1988
1989fn apply_position_changed(
1990    cache: &mut Cache,
1991    entry: &EventStoreEntry,
1992    changed: &PositionChanged,
1993) -> Result<bool, CacheReplayError> {
1994    let Some(mut position) = cache.position_owned(&changed.position_id) else {
1995        warn_position_skip(entry, changed.position_id);
1996        return Ok(false);
1997    };
1998
1999    let journal = (
2000        position.instrument_id,
2001        position.entry,
2002        position.side,
2003        position.signed_qty,
2004        position.quantity,
2005        position.peak_qty,
2006        position.quote_currency,
2007        position.avg_px_open,
2008        position.avg_px_close,
2009        position.realized_return,
2010        position.realized_pnl,
2011    );
2012    let notification = (
2013        changed.instrument_id,
2014        changed.entry,
2015        changed.side,
2016        changed.signed_qty,
2017        changed.quantity,
2018        changed.peak_quantity,
2019        changed.currency,
2020        changed.avg_px_open,
2021        changed.avg_px_close,
2022        changed.realized_return,
2023        changed.realized_pnl,
2024    );
2025
2026    if journal != notification {
2027        return Err(apply_error(
2028            entry,
2029            format!(
2030                "position {} lifecycle accounting differs from journal: expected {journal:?}, received {notification:?}",
2031                position.id
2032            ),
2033        ));
2034    }
2035
2036    position.trader_id = changed.trader_id;
2037    position.strategy_id = changed.strategy_id;
2038    position.id = changed.position_id;
2039    position.account_id = changed.account_id;
2040    position.opening_order_id = changed.opening_order_id;
2041    position.ts_opened = changed.ts_opened;
2042    position.ts_last = changed.ts_event;
2043    position.ts_closed = None;
2044
2045    apply_result(entry, cache.update_position(&position))?;
2046    Ok(true)
2047}
2048
2049fn apply_position_closed(
2050    cache: &mut Cache,
2051    entry: &EventStoreEntry,
2052    closed: &PositionClosed,
2053) -> Result<bool, CacheReplayError> {
2054    let Some(mut position) = cache.position_owned(&closed.position_id) else {
2055        warn_position_skip(entry, closed.position_id);
2056        return Ok(false);
2057    };
2058
2059    let journal = (
2060        position.instrument_id,
2061        position.entry,
2062        position.side,
2063        position.signed_qty,
2064        position.quantity,
2065        position.peak_qty,
2066        position.quote_currency,
2067        position.avg_px_open,
2068        position.avg_px_close,
2069        position.realized_return,
2070        position.realized_pnl,
2071    );
2072    let notification = (
2073        closed.instrument_id,
2074        closed.entry,
2075        closed.side,
2076        closed.signed_qty,
2077        closed.quantity,
2078        closed.peak_quantity,
2079        closed.currency,
2080        closed.avg_px_open,
2081        closed.avg_px_close,
2082        closed.realized_return,
2083        closed.realized_pnl,
2084    );
2085
2086    if journal != notification {
2087        return Err(apply_error(
2088            entry,
2089            format!(
2090                "position {} lifecycle accounting differs from journal: expected {journal:?}, received {notification:?}",
2091                position.id
2092            ),
2093        ));
2094    }
2095
2096    position.trader_id = closed.trader_id;
2097    position.strategy_id = closed.strategy_id;
2098    position.id = closed.position_id;
2099    position.account_id = closed.account_id;
2100    position.opening_order_id = closed.opening_order_id;
2101    position.closing_order_id = closed.closing_order_id;
2102    position.ts_opened = closed.ts_opened;
2103    position.ts_last = closed.ts_event;
2104    position.ts_closed = closed.ts_closed;
2105    position.duration_ns = closed.duration;
2106
2107    apply_result(entry, cache.update_position(&position))?;
2108    Ok(true)
2109}
2110
2111fn apply_position_adjustment(
2112    cache: &mut Cache,
2113    entry: &EventStoreEntry,
2114    adjustment: PositionAdjusted,
2115) -> Result<bool, CacheReplayError> {
2116    let Some(mut position) = cache.position_owned(&adjustment.position_id) else {
2117        warn_position_skip(entry, adjustment.position_id);
2118        return Ok(false);
2119    };
2120
2121    apply_result(entry, position.apply_adjustment(adjustment))?;
2122    apply_result(entry, cache.update_position(&position))?;
2123    Ok(true)
2124}
2125
2126// A position event whose position is absent cannot apply; counting it as applied would
2127// let a restore report full success while an open position is missing from the cache.
2128fn warn_position_skip(entry: &EventStoreEntry, position_id: PositionId) {
2129    log::warn!(
2130        "Replay seq {} skipped {}: position {position_id} not in cache",
2131        entry.seq,
2132        entry.payload_type,
2133    );
2134}
2135
2136fn decode_payload<T>(entry: &EventStoreEntry) -> Result<T, CacheReplayError>
2137where
2138    T: DeserializeOwned,
2139{
2140    rmp_serde::from_slice(&entry.payload).map_err(|e| CacheReplayError::Decode {
2141        seq: entry.seq,
2142        payload_type: entry.payload_type.to_string(),
2143        message: e.to_string(),
2144    })
2145}
2146
2147fn decode_response_ticks<R, T>(
2148    entry: &EventStoreEntry,
2149    data: impl FnOnce(R) -> BatchView<T>,
2150) -> Result<BatchView<T>, CacheReplayError>
2151where
2152    R: DeserializeOwned,
2153    T: DeserializeOwned,
2154{
2155    decode_payload(entry).map(data).or_else(|original| {
2156        decode_payload::<ScalarTickResponse<T>>(entry)
2157            .map(|response| response.data.into())
2158            .map_err(|_| original)
2159    })
2160}
2161
2162#[derive(Deserialize)]
2163#[expect(
2164    dead_code,
2165    reason = "Metadata is decoded to preserve validation of the previous stored response schema"
2166)]
2167struct ScalarTickResponse<T> {
2168    correlation_id: UUID4,
2169    client_id: ClientId,
2170    instrument_id: InstrumentId,
2171    data: Vec<T>,
2172    start: Option<UnixNanos>,
2173    end: Option<UnixNanos>,
2174    ts_init: UnixNanos,
2175    params: Option<Params>,
2176}
2177
2178fn apply_result<T, E>(entry: &EventStoreEntry, result: Result<T, E>) -> Result<T, CacheReplayError>
2179where
2180    E: Display,
2181{
2182    result.map_err(|e| apply_error(entry, e))
2183}
2184
2185fn apply_error(entry: &EventStoreEntry, error: impl Display) -> CacheReplayError {
2186    CacheReplayError::Apply {
2187        seq: entry.seq,
2188        payload_type: entry.payload_type.to_string(),
2189        message: error.to_string(),
2190    }
2191}
2192
2193fn reject_quarantined_replay_source(
2194    run_id: &str,
2195    status: RunStatus,
2196) -> Result<(), CacheReplayError> {
2197    if matches!(status, RunStatus::Quarantined) {
2198        let error = EventStoreError::Backend(format!("replay source {run_id} is quarantined"));
2199        return Err(CacheReplayError::from(error));
2200    }
2201
2202    Ok(())
2203}
2204
2205#[cfg(test)]
2206mod tests {
2207    use std::{any::Any, cell::Cell, rc::Rc, sync::Arc};
2208
2209    use ahash::AHashSet;
2210    use bytes::Bytes;
2211    use indexmap::IndexMap;
2212    use nautilus_common::msgbus::{self, BusTap, Endpoint, MStr, Topic as BusTopic};
2213    use nautilus_core::{UUID4, UnixNanos};
2214    use nautilus_model::{
2215        accounts::AccountAny,
2216        data::{
2217            Bar, BarSpecification, BarType, FundingRateUpdate, InstrumentClose, QuoteTick,
2218            TradeTick,
2219        },
2220        enums::{
2221            AggregationSource, AggressorSide, BarAggregation, InstrumentCloseType, OrderSide,
2222            OrderStatus, OrderType, PositionAdjustmentType, PositionSide, PriceType,
2223        },
2224        events::{
2225            PositionEvent,
2226            account::stubs::{cash_account_state, cash_account_state_million_usd},
2227            order::spec::{
2228                OrderAcceptedSpec, OrderCancelDeniedSpec, OrderFillVoidedSpec, OrderFilledSpec,
2229                OrderInitializedSpec, OrderModifyDeniedSpec, OrderPendingCancelSpec,
2230                OrderPendingUpdateSpec, OrderSubmittedSpec,
2231            },
2232        },
2233        identifiers::{
2234            AccountId, ClientId, ClientOrderId, InstrumentId, OrderListId, PositionId, StrategyId,
2235            TradeId, VenueOrderId,
2236        },
2237        instruments::{
2238            Instrument, InstrumentAny,
2239            stubs::{audusd_sim, binary_option},
2240        },
2241        orders::{Order, OrderList},
2242        types::{Currency, Money, Price, Quantity},
2243    };
2244    use rstest::rstest;
2245    use serde::Serialize;
2246    use tempfile::TempDir;
2247    use ustr::Ustr;
2248
2249    use super::*;
2250    use crate::{
2251        backend::{AppendEntry, MemoryBackend, RedbBackend},
2252        capture::{
2253            builtins::{
2254                DEFAULT_CAPTURE_PAYLOAD_TYPES, encode_instrument_close, encode_order_event_any,
2255                encode_position_event,
2256            },
2257            encode_account_state,
2258        },
2259        entry::Topic as EntryTopic,
2260        hash::compute_entry_hash,
2261        headers::Headers,
2262        manifest::{RegisteredComponents, RunManifest, RunStatus},
2263        snapshot::SnapshotAnchor,
2264    };
2265
2266    fn manifest(run_id: &str) -> RunManifest {
2267        RunManifest {
2268            run_id: run_id.to_string(),
2269            parent_run_id: None,
2270            instance_id: "trader-001".to_string(),
2271            binary_hash: "deadbeef".to_string(),
2272            schema_version: 1,
2273            crate_versions: "feedface".to_string(),
2274            feature_flags: Vec::new(),
2275            adapter_versions: IndexMap::new(),
2276            config_hash: "cafebabe".to_string(),
2277            registered_components: RegisteredComponents::default(),
2278            seed: None,
2279            start_ts_init: UnixNanos::from(0),
2280            end_ts_init: None,
2281            high_watermark: 0,
2282            status: RunStatus::Running,
2283        }
2284    }
2285
2286    fn append_payload(seq: u64, payload_type: &str, payload: Bytes) -> AppendEntry {
2287        append_payload_with_ts(seq, seq, payload_type, payload)
2288    }
2289
2290    fn append_serde_payload<T: Serialize>(seq: u64, payload_type: &str, value: &T) -> AppendEntry {
2291        let payload = rmp_serde::to_vec_named(value).expect("encode replay payload");
2292        append_payload(seq, payload_type, Bytes::from(payload))
2293    }
2294
2295    fn append_payload_with_ts(
2296        seq: u64,
2297        ts_init: u64,
2298        payload_type: &str,
2299        payload: Bytes,
2300    ) -> AppendEntry {
2301        let topic = EntryTopic::from("events.account.SIM");
2302        let ts = UnixNanos::from(ts_init);
2303        let headers = Headers::empty();
2304        let hash = compute_entry_hash(
2305            seq,
2306            ts,
2307            ts,
2308            topic.as_ref(),
2309            payload_type,
2310            &payload,
2311            &headers,
2312        );
2313        let entry = EventStoreEntry::new(
2314            hash,
2315            seq,
2316            headers,
2317            topic,
2318            Ustr::from(payload_type),
2319            payload,
2320            ts,
2321            ts,
2322        );
2323        AppendEntry::without_indices(entry)
2324    }
2325
2326    fn append_account_state(seq: u64, state: &AccountState) -> AppendEntry {
2327        let encoded = encode_account_state(state).expect("encode account state");
2328        append_payload(seq, PAYLOAD_TYPE_ACCOUNT_STATE, encoded.payload)
2329    }
2330
2331    fn append_order_event(seq: u64, event: &OrderEventAny) -> AppendEntry {
2332        let encoded = encode_order_event_any(event).expect("encode order event");
2333        let payload_type = encoded.payload_type.expect("order payload type");
2334        append_payload(seq, payload_type.as_str(), encoded.payload)
2335    }
2336
2337    fn append_position_event(seq: u64, event: &PositionEvent) -> AppendEntry {
2338        let encoded = encode_position_event(event).expect("encode position event");
2339        let payload_type = encoded.payload_type.expect("position payload type");
2340        append_payload(seq, payload_type.as_str(), encoded.payload)
2341    }
2342
2343    fn reader_with_entries(
2344        run_id: &str,
2345        entries: &[AppendEntry],
2346    ) -> EventStoreReader<MemoryBackend> {
2347        let mut backend = MemoryBackend::new();
2348        backend.open_run(manifest(run_id)).expect("open");
2349        backend.append_batch(entries).expect("append");
2350        EventStoreReader::new(backend)
2351    }
2352
2353    fn reader_with_anchor(anchor_seq: u64) -> (EventStoreReader<MemoryBackend>, AccountState) {
2354        let anchored = cash_account_state();
2355        let replayed = cash_account_state_million_usd("200 USD", "0 USD", "200 USD");
2356        let mut backend = MemoryBackend::new();
2357        backend.open_run(manifest("run-replay")).expect("open");
2358        backend
2359            .append_batch(&[
2360                append_account_state(1, &anchored),
2361                append_account_state(2, &replayed),
2362            ])
2363            .expect("append");
2364        backend
2365            .record_snapshot_anchor(SnapshotAnchor::new(anchor_seq, "cache://account", "hash"))
2366            .expect("record anchor");
2367        (EventStoreReader::new(backend), replayed)
2368    }
2369
2370    fn catalog_quote_record(ts_init: u64) -> CatalogReplayRecord {
2371        let instrument_id = InstrumentId::from("AUD/USD.SIM");
2372        CatalogReplayRecord::from_data(CatalogReplayData::Quote(QuoteTick::new(
2373            instrument_id,
2374            Price::from("1.0001"),
2375            Price::from("1.0002"),
2376            Quantity::from("100"),
2377            Quantity::from("100"),
2378            UnixNanos::from(ts_init),
2379            UnixNanos::from(ts_init),
2380        )))
2381    }
2382
2383    fn catalog_trade_record(ts_init: u64) -> CatalogReplayRecord {
2384        let instrument_id = InstrumentId::from("AUD/USD.SIM");
2385        CatalogReplayRecord::from_data(CatalogReplayData::Trade(TradeTick::new(
2386            instrument_id,
2387            Price::from("1.0001"),
2388            Quantity::from("100"),
2389            AggressorSide::Buy,
2390            TradeId::from("T-1"),
2391            UnixNanos::from(ts_init),
2392            UnixNanos::from(ts_init),
2393        )))
2394    }
2395
2396    #[derive(Debug)]
2397    struct CountingTap {
2398        calls: Rc<Cell<usize>>,
2399    }
2400
2401    impl CountingTap {
2402        fn new(calls: Rc<Cell<usize>>) -> Self {
2403            Self { calls }
2404        }
2405
2406        fn increment(&self) {
2407            self.calls.set(self.calls.get() + 1);
2408        }
2409    }
2410
2411    impl BusTap for CountingTap {
2412        fn on_publish(&self, _topic: MStr<BusTopic>, _message: &dyn Any) {
2413            self.increment();
2414        }
2415
2416        fn on_send(&self, _endpoint: MStr<Endpoint>, _message: &dyn Any) {
2417            self.increment();
2418        }
2419    }
2420
2421    #[derive(Debug)]
2422    struct FakeReplayCatalog {
2423        coverage: CatalogSliceCoverage,
2424        records: Vec<CatalogReplayRecord>,
2425        plan_queries: Vec<CatalogSliceQuery>,
2426        load_plans: Vec<CatalogSlicePlan>,
2427    }
2428
2429    impl FakeReplayCatalog {
2430        fn new(coverage: CatalogSliceCoverage, records: Vec<CatalogReplayRecord>) -> Self {
2431            Self {
2432                coverage,
2433                records,
2434                plan_queries: Vec::new(),
2435                load_plans: Vec::new(),
2436            }
2437        }
2438    }
2439
2440    impl ReplayCatalog for FakeReplayCatalog {
2441        type Error = String;
2442
2443        fn plan_slice(
2444            &mut self,
2445            query: &CatalogSliceQuery,
2446        ) -> Result<CatalogSliceCoverage, Self::Error> {
2447            self.plan_queries.push(query.clone());
2448            Ok(self.coverage.clone())
2449        }
2450
2451        fn load_slice(
2452            &mut self,
2453            plan: &CatalogSlicePlan,
2454        ) -> Result<Vec<CatalogReplayRecord>, Self::Error> {
2455            self.load_plans.push(plan.clone());
2456            Ok(self.records.clone())
2457        }
2458    }
2459
2460    struct BusTapGuard;
2461
2462    impl Drop for BusTapGuard {
2463        fn drop(&mut self) {
2464            msgbus::clear_bus_tap();
2465        }
2466    }
2467
2468    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
2469    enum CacheMutationRecoveryClass {
2470        SnapshotOwned,
2471        EventStoreCapturedAndReplayed,
2472        ForensicOnly,
2473        MissingLiveRecovery,
2474    }
2475
2476    #[derive(Clone, Copy, Debug)]
2477    struct CacheMutationCoverage {
2478        method: &'static str,
2479        class: CacheMutationRecoveryClass,
2480        payload_types: &'static [&'static str],
2481    }
2482
2483    const CACHE_MUTATION_COVERAGE: &[CacheMutationCoverage] = &[
2484        cache_mutation(
2485            // Startup configuration is reapplied during strategy registration, but runtime claim
2486            // changes are not captured or persisted for recovery.
2487            "set_external_order_claims",
2488            CacheMutationRecoveryClass::MissingLiveRecovery,
2489            &[],
2490        ),
2491        cache_mutation(
2492            "register_external_order_claims",
2493            CacheMutationRecoveryClass::MissingLiveRecovery,
2494            &[],
2495        ),
2496        cache_mutation(
2497            // Reapplied by execution client registration on every node start
2498            "add_client_account",
2499            CacheMutationRecoveryClass::SnapshotOwned,
2500            &[],
2501        ),
2502        cache_mutation(
2503            "remove_client_account",
2504            CacheMutationRecoveryClass::SnapshotOwned,
2505            &[],
2506        ),
2507        cache_mutation(
2508            // Reapplied by execution client routing setup on every node start
2509            "add_client_route",
2510            CacheMutationRecoveryClass::SnapshotOwned,
2511            &[],
2512        ),
2513        cache_mutation(
2514            "set_default_client",
2515            CacheMutationRecoveryClass::SnapshotOwned,
2516            &[],
2517        ),
2518        cache_mutation(
2519            "remove_client_routes",
2520            CacheMutationRecoveryClass::SnapshotOwned,
2521            &[],
2522        ),
2523        cache_mutation(
2524            // Reapplied from data engine configuration on every node start
2525            "add_external_data_client",
2526            CacheMutationRecoveryClass::SnapshotOwned,
2527            &[],
2528        ),
2529        cache_mutation(
2530            // Reapplied from execution engine configuration on every node start
2531            "add_external_exec_client",
2532            CacheMutationRecoveryClass::SnapshotOwned,
2533            &[],
2534        ),
2535        cache_mutation(
2536            "set_database",
2537            CacheMutationRecoveryClass::SnapshotOwned,
2538            &[],
2539        ),
2540        cache_mutation(
2541            "cache_general",
2542            CacheMutationRecoveryClass::SnapshotOwned,
2543            &[],
2544        ),
2545        cache_mutation("cache_all", CacheMutationRecoveryClass::SnapshotOwned, &[]),
2546        cache_mutation(
2547            "cache_currencies",
2548            CacheMutationRecoveryClass::SnapshotOwned,
2549            &[],
2550        ),
2551        cache_mutation(
2552            "cache_instruments",
2553            CacheMutationRecoveryClass::SnapshotOwned,
2554            &[],
2555        ),
2556        cache_mutation(
2557            "cache_synthetics",
2558            CacheMutationRecoveryClass::SnapshotOwned,
2559            &[],
2560        ),
2561        cache_mutation(
2562            "load_instrument",
2563            CacheMutationRecoveryClass::SnapshotOwned,
2564            &[],
2565        ),
2566        cache_mutation(
2567            "load_synthetic",
2568            CacheMutationRecoveryClass::SnapshotOwned,
2569            &[],
2570        ),
2571        cache_mutation(
2572            "cache_accounts",
2573            CacheMutationRecoveryClass::SnapshotOwned,
2574            &[],
2575        ),
2576        cache_mutation(
2577            "cache_orders",
2578            CacheMutationRecoveryClass::SnapshotOwned,
2579            &[],
2580        ),
2581        cache_mutation(
2582            "cache_positions",
2583            CacheMutationRecoveryClass::SnapshotOwned,
2584            &[],
2585        ),
2586        cache_mutation(
2587            "build_index",
2588            CacheMutationRecoveryClass::SnapshotOwned,
2589            &[],
2590        ),
2591        cache_mutation(
2592            "purge_closed_orders",
2593            CacheMutationRecoveryClass::SnapshotOwned,
2594            &[],
2595        ),
2596        cache_mutation(
2597            "purge_closed_positions",
2598            CacheMutationRecoveryClass::SnapshotOwned,
2599            &[],
2600        ),
2601        cache_mutation(
2602            "purge_order",
2603            CacheMutationRecoveryClass::SnapshotOwned,
2604            &[],
2605        ),
2606        cache_mutation(
2607            "purge_position",
2608            CacheMutationRecoveryClass::SnapshotOwned,
2609            &[],
2610        ),
2611        cache_mutation(
2612            "settle_position_snapshots",
2613            CacheMutationRecoveryClass::SnapshotOwned,
2614            &[],
2615        ),
2616        cache_mutation(
2617            "purge_instrument",
2618            CacheMutationRecoveryClass::SnapshotOwned,
2619            &[],
2620        ),
2621        cache_mutation(
2622            "purge_instrument_skip_order_guard",
2623            CacheMutationRecoveryClass::SnapshotOwned,
2624            &[],
2625        ),
2626        cache_mutation(
2627            "purge_account_events",
2628            CacheMutationRecoveryClass::SnapshotOwned,
2629            &[],
2630        ),
2631        cache_mutation(
2632            "clear_index",
2633            CacheMutationRecoveryClass::SnapshotOwned,
2634            &[],
2635        ),
2636        cache_mutation("reset", CacheMutationRecoveryClass::SnapshotOwned, &[]),
2637        cache_mutation("dispose", CacheMutationRecoveryClass::SnapshotOwned, &[]),
2638        cache_mutation("flush_db", CacheMutationRecoveryClass::SnapshotOwned, &[]),
2639        cache_mutation("add", CacheMutationRecoveryClass::SnapshotOwned, &[]),
2640        cache_mutation(
2641            "add_order_book",
2642            CacheMutationRecoveryClass::ForensicOnly,
2643            &[PAYLOAD_TYPE_BOOK_RESPONSE],
2644        ),
2645        cache_mutation(
2646            "add_own_order_book",
2647            CacheMutationRecoveryClass::SnapshotOwned,
2648            &[],
2649        ),
2650        cache_mutation(
2651            "add_mark_price",
2652            CacheMutationRecoveryClass::MissingLiveRecovery,
2653            &[],
2654        ),
2655        cache_mutation(
2656            "add_index_price",
2657            CacheMutationRecoveryClass::MissingLiveRecovery,
2658            &[],
2659        ),
2660        cache_mutation(
2661            "add_funding_rate",
2662            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2663            &[PAYLOAD_TYPE_FUNDING_RATES_RESPONSE],
2664        ),
2665        cache_mutation(
2666            "add_funding_rates",
2667            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2668            &[PAYLOAD_TYPE_FUNDING_RATES_RESPONSE],
2669        ),
2670        cache_mutation(
2671            "add_instrument_status",
2672            CacheMutationRecoveryClass::MissingLiveRecovery,
2673            &[],
2674        ),
2675        cache_mutation(
2676            "add_instrument_close",
2677            CacheMutationRecoveryClass::SnapshotOwned,
2678            &[],
2679        ),
2680        cache_mutation(
2681            "add_quote",
2682            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2683            &[PAYLOAD_TYPE_QUOTES_RESPONSE],
2684        ),
2685        cache_mutation(
2686            "add_quotes",
2687            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2688            &[PAYLOAD_TYPE_QUOTES_RESPONSE],
2689        ),
2690        cache_mutation(
2691            "add_trade",
2692            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2693            &[PAYLOAD_TYPE_TRADES_RESPONSE],
2694        ),
2695        cache_mutation(
2696            "add_trades",
2697            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2698            &[PAYLOAD_TYPE_TRADES_RESPONSE],
2699        ),
2700        cache_mutation(
2701            "add_bar",
2702            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2703            &[PAYLOAD_TYPE_BARS_RESPONSE],
2704        ),
2705        cache_mutation(
2706            "add_bars",
2707            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2708            &[PAYLOAD_TYPE_BARS_RESPONSE],
2709        ),
2710        cache_mutation(
2711            "add_bar_historical",
2712            CacheMutationRecoveryClass::MissingLiveRecovery,
2713            &[],
2714        ),
2715        cache_mutation(
2716            "add_custom_data",
2717            CacheMutationRecoveryClass::MissingLiveRecovery,
2718            &[],
2719        ),
2720        cache_mutation(
2721            "add_greeks",
2722            CacheMutationRecoveryClass::MissingLiveRecovery,
2723            &[],
2724        ),
2725        cache_mutation(
2726            "add_option_greeks",
2727            CacheMutationRecoveryClass::MissingLiveRecovery,
2728            &[],
2729        ),
2730        cache_mutation(
2731            "add_yield_curve",
2732            CacheMutationRecoveryClass::MissingLiveRecovery,
2733            &[],
2734        ),
2735        cache_mutation(
2736            "add_currency",
2737            CacheMutationRecoveryClass::SnapshotOwned,
2738            &[],
2739        ),
2740        cache_mutation(
2741            "add_instrument",
2742            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2743            &[
2744                PAYLOAD_TYPE_INSTRUMENT_RESPONSE,
2745                PAYLOAD_TYPE_INSTRUMENTS_RESPONSE,
2746            ],
2747        ),
2748        cache_mutation(
2749            "add_synthetic",
2750            CacheMutationRecoveryClass::SnapshotOwned,
2751            &[],
2752        ),
2753        cache_mutation(
2754            "add_account",
2755            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2756            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2757        ),
2758        cache_mutation(
2759            "add_venue_order_id",
2760            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2761            &[PAYLOAD_TYPE_ORDER_ACCEPTED, PAYLOAD_TYPE_ORDER_UPDATED],
2762        ),
2763        cache_mutation(
2764            // Replay restores the current generation only; superseded reverse aliases are
2765            // re-registered by live mass-status reconciliation.
2766            "index_venue_order_id",
2767            CacheMutationRecoveryClass::MissingLiveRecovery,
2768            &[],
2769        ),
2770        cache_mutation(
2771            "add_order",
2772            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2773            &[PAYLOAD_TYPE_ORDER_INITIALIZED],
2774        ),
2775        cache_mutation(
2776            // Cache databases persist the resolved client index, but current EventStore
2777            // command payloads do not carry the client selected by runtime routing.
2778            "claim_order_clients",
2779            CacheMutationRecoveryClass::MissingLiveRecovery,
2780            &[],
2781        ),
2782        cache_mutation(
2783            "add_order_list",
2784            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2785            &[PAYLOAD_TYPE_SUBMIT_ORDER_LIST],
2786        ),
2787        cache_mutation(
2788            "add_position_id",
2789            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2790            &[
2791                PAYLOAD_TYPE_ORDER_FILLED,
2792                PAYLOAD_TYPE_POSITION_OPENED,
2793                PAYLOAD_TYPE_POSITION_CHANGED,
2794                PAYLOAD_TYPE_POSITION_CLOSED,
2795            ],
2796        ),
2797        cache_mutation(
2798            "add_position",
2799            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2800            &[PAYLOAD_TYPE_ORDER_FILLED],
2801        ),
2802        cache_mutation(
2803            "add_position_without_order",
2804            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2805            &[PAYLOAD_TYPE_ORDER_FILLED],
2806        ),
2807        cache_mutation(
2808            "replace_position",
2809            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2810            &[PAYLOAD_TYPE_ORDER_FILLED],
2811        ),
2812        cache_mutation(
2813            "update_account",
2814            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2815            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2816        ),
2817        cache_mutation(
2818            "take_account",
2819            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2820            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2821        ),
2822        cache_mutation(
2823            "cache_account_owned",
2824            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2825            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2826        ),
2827        cache_mutation(
2828            "update_account_owned",
2829            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2830            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2831        ),
2832        cache_mutation(
2833            "update_account_state",
2834            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2835            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2836        ),
2837        cache_mutation(
2838            "replace_order",
2839            CacheMutationRecoveryClass::ForensicOnly,
2840            &[
2841                PAYLOAD_TYPE_ORDER_STATUS_REPORT,
2842                PAYLOAD_TYPE_ORDER_WITH_FILLS,
2843                PAYLOAD_TYPE_EXECUTION_MASS_STATUS,
2844            ],
2845        ),
2846        cache_mutation(
2847            "update_order",
2848            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2849            &[
2850                PAYLOAD_TYPE_ORDER_DENIED,
2851                PAYLOAD_TYPE_ORDER_EMULATED,
2852                PAYLOAD_TYPE_ORDER_RELEASED,
2853                PAYLOAD_TYPE_ORDER_SUBMITTED,
2854                PAYLOAD_TYPE_ORDER_ACCEPTED,
2855                PAYLOAD_TYPE_ORDER_REJECTED,
2856                PAYLOAD_TYPE_ORDER_CANCELED,
2857                PAYLOAD_TYPE_ORDER_EXPIRED,
2858                PAYLOAD_TYPE_ORDER_TRIGGERED,
2859                PAYLOAD_TYPE_ORDER_PENDING_UPDATE,
2860                PAYLOAD_TYPE_ORDER_PENDING_CANCEL,
2861                PAYLOAD_TYPE_ORDER_MODIFY_DENIED,
2862                PAYLOAD_TYPE_ORDER_MODIFY_REJECTED,
2863                PAYLOAD_TYPE_ORDER_CANCEL_DENIED,
2864                PAYLOAD_TYPE_ORDER_CANCEL_REJECTED,
2865                PAYLOAD_TYPE_ORDER_UPDATED,
2866                PAYLOAD_TYPE_ORDER_FILLED,
2867                PAYLOAD_TYPE_ORDER_FILL_VOIDED,
2868            ],
2869        ),
2870        cache_mutation(
2871            "update_order_pending_cancel_local",
2872            CacheMutationRecoveryClass::MissingLiveRecovery,
2873            &[],
2874        ),
2875        cache_mutation(
2876            "update_position",
2877            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2878            &[
2879                PAYLOAD_TYPE_ORDER_FILLED,
2880                PAYLOAD_TYPE_ORDER_FILL_VOIDED,
2881                PAYLOAD_TYPE_POSITION_OPENED,
2882                PAYLOAD_TYPE_POSITION_CHANGED,
2883                PAYLOAD_TYPE_POSITION_CLOSED,
2884                PAYLOAD_TYPE_POSITION_ADJUSTED,
2885            ],
2886        ),
2887        cache_mutation(
2888            "update_position_from_fill",
2889            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2890            &[PAYLOAD_TYPE_ORDER_FILLED],
2891        ),
2892        cache_mutation(
2893            "update_position_from_instrument_close",
2894            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2895            &[PAYLOAD_TYPE_INSTRUMENT_CLOSE],
2896        ),
2897        cache_mutation(
2898            "update_position_from_adjustment",
2899            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2900            &[PAYLOAD_TYPE_POSITION_ADJUSTED],
2901        ),
2902        cache_mutation(
2903            // Rolls back an adjustment whose event was never published, so replay never applies it
2904            "revert_position_adjustment",
2905            CacheMutationRecoveryClass::MissingLiveRecovery,
2906            &[],
2907        ),
2908        cache_mutation(
2909            "snapshot_position",
2910            CacheMutationRecoveryClass::SnapshotOwned,
2911            &[],
2912        ),
2913        cache_mutation(
2914            "snapshot_position_encoded",
2915            CacheMutationRecoveryClass::SnapshotOwned,
2916            &[],
2917        ),
2918        cache_mutation(
2919            "snapshot_position_state",
2920            CacheMutationRecoveryClass::SnapshotOwned,
2921            &[],
2922        ),
2923        cache_mutation(
2924            "load_snapshot_blob",
2925            CacheMutationRecoveryClass::SnapshotOwned,
2926            &[],
2927        ),
2928        cache_mutation(
2929            "restore_snapshot_blob",
2930            CacheMutationRecoveryClass::SnapshotOwned,
2931            &[],
2932        ),
2933        cache_mutation(
2934            "mark_orders_dispatched",
2935            CacheMutationRecoveryClass::MissingLiveRecovery,
2936            &[],
2937        ),
2938        cache_mutation(
2939            "clear_order_dispatch",
2940            CacheMutationRecoveryClass::MissingLiveRecovery,
2941            &[],
2942        ),
2943        cache_mutation(
2944            "order_mut",
2945            CacheMutationRecoveryClass::MissingLiveRecovery,
2946            &[],
2947        ),
2948        cache_mutation(
2949            "position_mut",
2950            CacheMutationRecoveryClass::MissingLiveRecovery,
2951            &[],
2952        ),
2953        cache_mutation(
2954            "order_book_mut",
2955            CacheMutationRecoveryClass::ForensicOnly,
2956            &[
2957                PAYLOAD_TYPE_BOOK_DELTAS_RESPONSE,
2958                PAYLOAD_TYPE_BOOK_DEPTH_RESPONSE,
2959            ],
2960        ),
2961        cache_mutation(
2962            "own_order_book_mut",
2963            CacheMutationRecoveryClass::SnapshotOwned,
2964            &[],
2965        ),
2966        cache_mutation(
2967            "set_mark_xrate",
2968            CacheMutationRecoveryClass::MissingLiveRecovery,
2969            &[],
2970        ),
2971        cache_mutation(
2972            "clear_mark_xrate",
2973            CacheMutationRecoveryClass::MissingLiveRecovery,
2974            &[],
2975        ),
2976        cache_mutation(
2977            "clear_mark_xrates",
2978            CacheMutationRecoveryClass::MissingLiveRecovery,
2979            &[],
2980        ),
2981        cache_mutation(
2982            "account_mut",
2983            CacheMutationRecoveryClass::MissingLiveRecovery,
2984            &[],
2985        ),
2986        cache_mutation(
2987            "update_own_order_book",
2988            CacheMutationRecoveryClass::SnapshotOwned,
2989            &[],
2990        ),
2991        cache_mutation(
2992            "force_remove_from_own_order_book",
2993            CacheMutationRecoveryClass::SnapshotOwned,
2994            &[],
2995        ),
2996        cache_mutation(
2997            "audit_own_order_books",
2998            CacheMutationRecoveryClass::SnapshotOwned,
2999            &[],
3000        ),
3001    ];
3002
3003    const CACHE_MUTATION_EXCLUSIONS: &[&str] = &["check_integrity"];
3004
3005    const fn cache_mutation(
3006        method: &'static str,
3007        class: CacheMutationRecoveryClass,
3008        payload_types: &'static [&'static str],
3009    ) -> CacheMutationCoverage {
3010        CacheMutationCoverage {
3011            method,
3012            class,
3013            payload_types,
3014        }
3015    }
3016
3017    fn cache_public_methods() -> AHashSet<&'static str> {
3018        collect_cache_public_methods(false)
3019    }
3020
3021    fn cache_public_mutable_methods() -> AHashSet<&'static str> {
3022        collect_cache_public_methods(true)
3023    }
3024
3025    /// Every file carrying an `impl Cache` block, since `include_str!` cannot glob a directory.
3026    /// Add a file here when the cache module is split further, or its methods drop out of this
3027    /// classification guard.
3028    const CACHE_IMPL_SOURCES: &[&str] = &[
3029        include_str!("../../common/src/cache/mod.rs"),
3030        include_str!("../../common/src/cache/position.rs"),
3031    ];
3032
3033    fn collect_cache_public_methods(require_mut_self: bool) -> AHashSet<&'static str> {
3034        let mut methods = AHashSet::new();
3035        let mut pending_name: Option<&'static str> = None;
3036        let mut pending_signature = String::new();
3037
3038        for line in CACHE_IMPL_SOURCES.iter().flat_map(|source| source.lines()) {
3039            let trimmed = line.trim_start();
3040
3041            if pending_name.is_none() {
3042                let Some(rest) = trimmed
3043                    .strip_prefix("pub fn ")
3044                    .or_else(|| trimmed.strip_prefix("pub async fn "))
3045                else {
3046                    continue;
3047                };
3048                pending_name = rest.split('(').next();
3049                pending_signature.clear();
3050                pending_signature.push_str(trimmed);
3051            } else {
3052                pending_signature.push(' ');
3053                pending_signature.push_str(trimmed);
3054            }
3055
3056            if trimmed.contains('{') {
3057                if let Some(name) = pending_name.take()
3058                    && (!require_mut_self || pending_signature.contains("&mut self"))
3059                {
3060                    methods.insert(name);
3061                }
3062                pending_signature.clear();
3063            }
3064        }
3065
3066        methods
3067    }
3068
3069    fn sorted_missing_methods<'a>(
3070        actual: &'a AHashSet<&'static str>,
3071        classified: &'a AHashSet<&'static str>,
3072    ) -> Vec<&'static str> {
3073        let mut missing: Vec<_> = actual
3074            .iter()
3075            .copied()
3076            .filter(|method| !classified.contains(method))
3077            .collect();
3078        missing.sort_unstable();
3079        missing
3080    }
3081
3082    fn sorted_stale_methods<'a>(
3083        classified: &'a AHashSet<&'static str>,
3084        actual: &'a AHashSet<&'static str>,
3085    ) -> Vec<&'static str> {
3086        let mut stale: Vec<_> = classified
3087            .iter()
3088            .copied()
3089            .filter(|method| !actual.contains(method))
3090            .collect();
3091        stale.sort_unstable();
3092        stale
3093    }
3094
3095    #[rstest]
3096    fn catalog_replay_inputs_join_event_entries_with_selected_catalog_slice() {
3097        let reader = reader_with_entries(
3098            "run-catalog",
3099            &[
3100                append_payload_with_ts(1, 120, "RunStarted", Bytes::from_static(b"started")),
3101                append_payload_with_ts(2, 100, "SubmitOrder", Bytes::from_static(b"submit")),
3102            ],
3103        );
3104        let record = catalog_quote_record(110);
3105        let mut catalog = FakeReplayCatalog::new(
3106            CatalogSliceCoverage::from_files(vec!["quotes/AUDUSD.SIM/100_120.parquet".into()]),
3107            vec![record.clone()],
3108        );
3109
3110        let plan = plan_catalog_replay_inputs(
3111            &reader,
3112            &mut catalog,
3113            ReplaySeqRange::new(1, 2),
3114            &[CatalogSliceSelector::new("quotes").with_identifier("AUD/USD.SIM")],
3115        )
3116        .expect("plan catalog replay");
3117
3118        assert_eq!(plan.event_range, Some(ReplaySeqRange::new(1, 2)));
3119        assert_eq!(plan.event_count, 2);
3120        assert_eq!(
3121            plan.event_time_range,
3122            Some(ReplayTimeRange::new(
3123                UnixNanos::from(100),
3124                UnixNanos::from(120),
3125            )),
3126        );
3127        assert!(!plan.catalog_slices[0].is_missing());
3128        assert_eq!(catalog.plan_queries.len(), 1);
3129        assert_eq!(catalog.plan_queries[0].data_cls, "quotes");
3130        assert_eq!(
3131            catalog.plan_queries[0].identifiers,
3132            vec!["AUD/USD.SIM".to_string()],
3133        );
3134        assert_eq!(catalog.plan_queries[0].start, UnixNanos::from(100));
3135        assert_eq!(catalog.plan_queries[0].end, UnixNanos::from(120));
3136
3137        let loaded =
3138            load_catalog_replay_inputs(&reader, &mut catalog, &plan).expect("load catalog");
3139        let seqs: Vec<_> = loaded.entries.iter().map(|entry| entry.seq).collect();
3140
3141        assert_eq!(seqs, vec![1, 2]);
3142        assert_eq!(loaded.catalog_slices.len(), 1);
3143        assert_eq!(loaded.catalog_slices[0].records, vec![record]);
3144        assert_eq!(catalog.load_plans.len(), 1);
3145    }
3146
3147    #[rstest]
3148    fn catalog_plan_marks_missing_catalog_slice() {
3149        let reader = reader_with_entries(
3150            "run-missing-catalog",
3151            &[append_payload_with_ts(
3152                1,
3153                1_000,
3154                "RunStarted",
3155                Bytes::from_static(b"started"),
3156            )],
3157        );
3158        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3159
3160        let plan = plan_catalog_replay_inputs(
3161            &reader,
3162            &mut catalog,
3163            ReplaySeqRange::new(1, 1),
3164            &[CatalogSliceSelector::new("trades").with_identifier("AUD/USD.SIM")],
3165        )
3166        .expect("plan catalog replay");
3167        let missing = plan.missing_catalog_slices();
3168
3169        assert_eq!(missing.len(), 1);
3170        assert_eq!(missing[0].query.data_cls, "trades");
3171        assert_eq!(
3172            missing[0].query.identifiers,
3173            vec!["AUD/USD.SIM".to_string()],
3174        );
3175        assert_eq!(missing[0].query.start, UnixNanos::from(1_000));
3176        assert_eq!(missing[0].query.end, UnixNanos::from(1_000));
3177    }
3178
3179    #[rstest]
3180    fn required_missing_catalog_slice_rejects_load() {
3181        let reader = reader_with_entries(
3182            "run-required-missing",
3183            &[append_payload_with_ts(
3184                1,
3185                1_000,
3186                "RunStarted",
3187                Bytes::from_static(b"started"),
3188            )],
3189        );
3190        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3191        let plan = plan_catalog_replay_inputs(
3192            &reader,
3193            &mut catalog,
3194            ReplaySeqRange::new(1, 1),
3195            &[CatalogSliceSelector::new("quotes")
3196                .with_identifier("AUD/USD.SIM")
3197                .require_coverage()],
3198        )
3199        .expect("plan missing slice");
3200
3201        let err = load_catalog_replay_inputs(&reader, &mut catalog, &plan)
3202            .expect_err("required missing slice must fail");
3203
3204        match err {
3205            ReplayInputError::MissingCatalogSlice {
3206                data_cls,
3207                identifiers,
3208            } => {
3209                assert_eq!(data_cls, "quotes");
3210                assert_eq!(identifiers, vec!["AUD/USD.SIM".to_string()]);
3211            }
3212            other => panic!("expected MissingCatalogSlice, was {other:?}"),
3213        }
3214    }
3215
3216    #[rstest]
3217    fn optional_missing_catalog_slice_loads_as_empty_without_catalog_load() {
3218        let reader = reader_with_entries(
3219            "run-optional-missing",
3220            &[append_payload_with_ts(
3221                1,
3222                1_000,
3223                "RunStarted",
3224                Bytes::from_static(b"started"),
3225            )],
3226        );
3227        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3228        let plan = plan_catalog_replay_inputs(
3229            &reader,
3230            &mut catalog,
3231            ReplaySeqRange::new(1, 1),
3232            &[CatalogSliceSelector::new("quotes").with_identifier("AUD/USD.SIM")],
3233        )
3234        .expect("plan optional missing slice");
3235
3236        let loaded =
3237            load_catalog_replay_inputs(&reader, &mut catalog, &plan).expect("load optional");
3238
3239        assert_eq!(loaded.catalog_slices.len(), 1);
3240        assert!(loaded.catalog_slices[0].plan.is_missing());
3241        assert!(loaded.catalog_slices[0].records.is_empty());
3242        assert!(catalog.load_plans.is_empty());
3243    }
3244
3245    #[rstest]
3246    fn catalog_joined_planner_rejects_empty_catalog_selection() {
3247        let reader = reader_with_entries(
3248            "run-empty-selection",
3249            &[append_payload_with_ts(
3250                1,
3251                1_000,
3252                "RunStarted",
3253                Bytes::from_static(b"started"),
3254            )],
3255        );
3256        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3257
3258        let err = plan_catalog_replay_inputs(&reader, &mut catalog, ReplaySeqRange::new(1, 1), &[])
3259            .expect_err("empty catalog selection must fail");
3260
3261        match err {
3262            ReplayInputError::EmptyCatalogSelection => {}
3263            other => panic!("expected EmptyCatalogSelection, was {other:?}"),
3264        }
3265        assert!(catalog.plan_queries.is_empty());
3266    }
3267
3268    #[rstest]
3269    fn catalog_selector_explicit_time_bounds_override_event_span() {
3270        let reader = reader_with_entries(
3271            "run-explicit-bounds",
3272            &[append_payload_with_ts(
3273                1,
3274                1_000,
3275                "RunStarted",
3276                Bytes::from_static(b"started"),
3277            )],
3278        );
3279        let mut catalog = FakeReplayCatalog::new(
3280            CatalogSliceCoverage::from_files(vec!["bars/AUDUSD.SIM/900_950.parquet".into()]),
3281            Vec::new(),
3282        );
3283
3284        let plan = plan_catalog_replay_inputs(
3285            &reader,
3286            &mut catalog,
3287            ReplaySeqRange::new(1, 1),
3288            &[CatalogSliceSelector::new("bars")
3289                .with_identifier("AUD/USD.SIM-1-MINUTE-BID-EXTERNAL")
3290                .with_time_bounds(UnixNanos::from(900), UnixNanos::from(950))],
3291        )
3292        .expect("plan explicit bounds");
3293
3294        assert_eq!(plan.catalog_slices[0].query.start, UnixNanos::from(900));
3295        assert_eq!(plan.catalog_slices[0].query.end, UnixNanos::from(950));
3296        assert_eq!(catalog.plan_queries[0].start, UnixNanos::from(900));
3297        assert_eq!(catalog.plan_queries[0].end, UnixNanos::from(950));
3298    }
3299
3300    #[rstest]
3301    fn catalog_replay_inputs_load_catalog_records() {
3302        let reader = reader_with_entries(
3303            "run-catalog-load",
3304            &[
3305                append_payload_with_ts(1, 100, "RunStarted", Bytes::from_static(b"started")),
3306                append_payload_with_ts(2, 110, "OrderFilled", Bytes::from_static(b"filled")),
3307            ],
3308        );
3309        let record = catalog_trade_record(105);
3310        let mut catalog = FakeReplayCatalog::new(
3311            CatalogSliceCoverage::from_files(vec!["trades/AUDUSD.SIM/100_110.parquet".into()]),
3312            vec![record.clone()],
3313        );
3314        let plan = plan_catalog_replay_inputs(
3315            &reader,
3316            &mut catalog,
3317            ReplaySeqRange::new(1, 2),
3318            &[CatalogSliceSelector::new("trades").with_identifier("AUD/USD.SIM")],
3319        )
3320        .expect("plan catalog replay");
3321
3322        assert_eq!(
3323            plan.catalog_slices[0].query.identifiers_option(),
3324            Some(vec!["AUD/USD.SIM".to_string()]),
3325        );
3326
3327        let loaded =
3328            load_catalog_replay_inputs(&reader, &mut catalog, &plan).expect("load catalog");
3329        let seqs: Vec<_> = loaded.entries.iter().map(|entry| entry.seq).collect();
3330
3331        assert_eq!(seqs, vec![1, 2]);
3332        assert_eq!(loaded.catalog_slices[0].records, vec![record]);
3333        assert_eq!(catalog.load_plans.len(), 1);
3334    }
3335
3336    #[rstest]
3337    fn unbounded_catalog_selector_rejects_empty_event_scan() {
3338        let reader = reader_with_entries("run-empty", &[]);
3339        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3340
3341        let err = plan_catalog_replay_inputs(
3342            &reader,
3343            &mut catalog,
3344            ReplaySeqRange::new(1, 10),
3345            &[CatalogSliceSelector::new("quotes")],
3346        )
3347        .expect_err("empty replay scan must need explicit bounds");
3348
3349        match err {
3350            ReplayInputError::MissingCatalogTimeBounds { data_cls } => {
3351                assert_eq!(data_cls, "quotes");
3352            }
3353            other => panic!("expected MissingCatalogTimeBounds, was {other:?}"),
3354        }
3355    }
3356
3357    #[rstest]
3358    fn invalid_catalog_time_bounds_are_rejected_before_catalog_access() {
3359        let reader = reader_with_entries(
3360            "run-invalid-bounds",
3361            &[append_payload_with_ts(
3362                1,
3363                1_000,
3364                "RunStarted",
3365                Bytes::from_static(b"started"),
3366            )],
3367        );
3368        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3369
3370        let err = plan_catalog_replay_inputs(
3371            &reader,
3372            &mut catalog,
3373            ReplaySeqRange::new(1, 1),
3374            &[CatalogSliceSelector::new("quotes")
3375                .with_time_bounds(UnixNanos::from(200), UnixNanos::from(100))],
3376        )
3377        .expect_err("invalid catalog bounds must fail");
3378
3379        match err {
3380            ReplayInputError::InvalidCatalogTimeRange {
3381                data_cls,
3382                start,
3383                end,
3384            } => {
3385                assert_eq!(data_cls, "quotes");
3386                assert_eq!(start, 200);
3387                assert_eq!(end, 100);
3388            }
3389            other => panic!("expected InvalidCatalogTimeRange, was {other:?}"),
3390        }
3391        assert!(catalog.plan_queries.is_empty());
3392    }
3393
3394    #[rstest]
3395    fn forensics_replay_inputs_do_not_require_catalog_source() {
3396        let reader = reader_with_entries(
3397            "run-forensics",
3398            &[append_payload_with_ts(
3399                1,
3400                500,
3401                "RunStarted",
3402                Bytes::from_static(b"started"),
3403            )],
3404        );
3405
3406        let plan = plan_forensics_replay_inputs(&reader, ReplaySeqRange::new(1, 1))
3407            .expect("plan forensics");
3408        let loaded = load_forensics_replay_inputs(&reader, &plan).expect("load forensics");
3409
3410        assert!(plan.catalog_slices.is_empty());
3411        assert_eq!(loaded.entries.len(), 1);
3412        assert!(loaded.catalog_slices.is_empty());
3413    }
3414
3415    #[rstest]
3416    #[case::zero_start(ReplaySeqRange::new(0, 1), "seq is 1-based")]
3417    #[case::from_after_to(ReplaySeqRange::new(2, 1), "from_seq exceeds to_seq")]
3418    fn invalid_replay_seq_range_rejected(
3419        #[case] range: ReplaySeqRange,
3420        #[case] expected_message: &str,
3421    ) {
3422        let reader = reader_with_entries("run-invalid-seq", &[]);
3423
3424        let err =
3425            plan_forensics_replay_inputs(&reader, range).expect_err("invalid seq range must fail");
3426
3427        match err {
3428            ReplayInputError::InvalidSeqRange {
3429                from_seq,
3430                to_seq,
3431                message,
3432            } => {
3433                assert_eq!(from_seq, range.from_seq);
3434                assert_eq!(to_seq, range.to_seq);
3435                assert_eq!(message, expected_message);
3436            }
3437            other => panic!("expected InvalidSeqRange, was {other:?}"),
3438        }
3439    }
3440
3441    #[rstest]
3442    fn replay_restores_snapshot_before_applying_tail() {
3443        let (reader, replayed) = reader_with_anchor(1);
3444        let mut cache = Cache::default();
3445        let restored = cash_account_state_million_usd("100 USD", "0 USD", "100 USD");
3446        let restored_id = restored.account_id;
3447
3448        let report =
3449            restore_cache_snapshot_and_replay_tail(&mut cache, &reader, |cache, anchor| {
3450                assert_eq!(anchor.expect("anchor").high_watermark, 1);
3451                let account = AccountAny::from_events(std::slice::from_ref(&restored))
3452                    .map_err(|e| CacheReplayError::snapshot_restore(anchor.unwrap(), e))?;
3453                cache
3454                    .add_account(account)
3455                    .map_err(|e| CacheReplayError::snapshot_restore(anchor.unwrap(), e))
3456            })
3457            .expect("replay");
3458
3459        let account = cache.account_owned(&restored_id).expect("account restored");
3460        let events = account.events();
3461
3462        assert_eq!(report.plan.from_seq, 2);
3463        assert_eq!(report.applied_entries, 1);
3464        assert_eq!(report.ignored_entries, 0);
3465        assert_eq!(events, vec![restored, replayed]);
3466    }
3467
3468    #[rstest]
3469    fn replay_does_not_apply_entries_at_or_below_anchor_watermark() {
3470        let (reader, _) = reader_with_anchor(2);
3471        let mut cache = Cache::default();
3472        let restored = cash_account_state_million_usd("100 USD", "0 USD", "100 USD");
3473        let restored_id = restored.account_id;
3474
3475        let report =
3476            restore_cache_snapshot_and_replay_tail(&mut cache, &reader, |cache, anchor| {
3477                assert_eq!(anchor.expect("anchor").high_watermark, 2);
3478                let account = AccountAny::from_events(std::slice::from_ref(&restored))
3479                    .map_err(|e| CacheReplayError::snapshot_restore(anchor.unwrap(), e))?;
3480                cache
3481                    .add_account(account)
3482                    .map_err(|e| CacheReplayError::snapshot_restore(anchor.unwrap(), e))
3483            })
3484            .expect("replay");
3485
3486        let account = cache.account_owned(&restored_id).expect("account restored");
3487
3488        assert!(report.plan.is_empty());
3489        assert_eq!(report.applied_entries, 0);
3490        assert_eq!(report.ignored_entries, 0);
3491        assert_eq!(account.events(), vec![restored]);
3492    }
3493
3494    #[rstest]
3495    fn replay_from_start_applies_account_state_without_bus_publish() {
3496        let state = cash_account_state_million_usd("100 USD", "0 USD", "100 USD");
3497        let account_id = AccountId::from("SIM-001");
3498        let bus_calls = Rc::new(Cell::new(0));
3499        msgbus::set_bus_tap(Rc::new(CountingTap::new(Rc::clone(&bus_calls))));
3500        let _guard = BusTapGuard;
3501        let mut backend = MemoryBackend::new();
3502        backend.open_run(manifest("run-replay")).expect("open");
3503        backend
3504            .append_batch(&[append_account_state(1, &state)])
3505            .expect("append");
3506        let reader = EventStoreReader::new(backend);
3507        let mut cache = Cache::default();
3508
3509        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
3510        let account = cache.account_owned(&account_id).expect("account replayed");
3511
3512        assert_eq!(report.plan.anchor, None);
3513        assert_eq!(report.plan.from_seq, 1);
3514        assert_eq!(report.applied_entries, 1);
3515        assert_eq!(bus_calls.get(), 0);
3516        assert_eq!(account.last_event(), Some(state));
3517        assert_eq!(account.base_currency(), Some(Currency::USD()));
3518    }
3519
3520    #[rstest]
3521    fn unsupported_payload_is_ignored() {
3522        let mut backend = MemoryBackend::new();
3523        backend.open_run(manifest("run-replay")).expect("open");
3524        backend
3525            .append_batch(&[append_payload(
3526                1,
3527                "RunStarted",
3528                Bytes::copy_from_slice(UUID4::new().to_string().as_bytes()),
3529            )])
3530            .expect("append");
3531        let reader = EventStoreReader::new(backend);
3532        let mut cache = Cache::default();
3533
3534        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
3535
3536        assert_eq!(report.applied_entries, 0);
3537        assert_eq!(report.ignored_entries, 1);
3538    }
3539
3540    #[rstest]
3541    fn historical_envelope_replays_payload_without_actor_completion_state() {
3542        use nautilus_common::messages::data::{DataResponse, DataResponseEnvelope};
3543        let instrument_id = InstrumentId::from("AUD/USD.SIM");
3544
3545        let quote = QuoteTick::new(
3546            instrument_id,
3547            Price::from("1.00000"),
3548            Price::from("1.00010"),
3549            Quantity::from("11"),
3550            Quantity::from("13"),
3551            UnixNanos::from(17),
3552            UnixNanos::from(19),
3553        );
3554        let root = UUID4::new();
3555
3556        let response = QuotesResponse::new(
3557            root,
3558            ClientId::from("SOURCE"),
3559            instrument_id,
3560            vec![quote],
3561            None,
3562            None,
3563            UnixNanos::from(23),
3564            None,
3565        );
3566        let envelope =
3567            DataResponseEnvelope::new(DataResponse::Quotes(response), false, Some(UUID4::new()));
3568        let registry = crate::capture::builtins::default_registry();
3569        let (tag, encoded) = registry.encode(&envelope).unwrap().unwrap();
3570        let entry = append_payload(1, tag.as_str(), encoded.payload).entry;
3571        let mut cache = Cache::default();
3572        assert!(apply_cache_replay_entry(&mut cache, &entry).unwrap());
3573        let terminal = DataResponseEnvelope::terminal(root, Some("later source failed".to_owned()));
3574        let (tag, encoded) = registry.encode(&terminal).unwrap().unwrap();
3575        let entry = append_payload(2, tag.as_str(), encoded.payload).entry;
3576        assert!(!apply_cache_replay_entry(&mut cache, &entry).unwrap());
3577        assert_eq!(cache.quote(&instrument_id), Some(&quote));
3578    }
3579
3580    #[rstest]
3581    fn default_capture_payload_types_are_classified_for_cache_replay() {
3582        let mut classified = AHashSet::new();
3583        let mut overlap = Vec::new();
3584
3585        for payload_type in CACHE_REPLAY_CAPTURE_PAYLOAD_TYPES {
3586            classified.insert(*payload_type);
3587        }
3588
3589        for payload_type in FORENSIC_ONLY_CAPTURE_PAYLOAD_TYPES {
3590            if !classified.insert(*payload_type) {
3591                overlap.push(*payload_type);
3592            }
3593        }
3594
3595        let mut seen_defaults = AHashSet::new();
3596        let duplicate_defaults: Vec<_> = DEFAULT_CAPTURE_PAYLOAD_TYPES
3597            .iter()
3598            .copied()
3599            .filter(|payload_type| !seen_defaults.insert(*payload_type))
3600            .collect();
3601        let unclassified: Vec<_> = DEFAULT_CAPTURE_PAYLOAD_TYPES
3602            .iter()
3603            .copied()
3604            .filter(|payload_type| !classified.contains(payload_type))
3605            .collect();
3606        let extra: Vec<_> = classified
3607            .iter()
3608            .copied()
3609            .filter(|payload_type| !seen_defaults.contains(payload_type))
3610            .collect();
3611
3612        assert!(
3613            duplicate_defaults.is_empty(),
3614            "default capture payload types must be unique: {duplicate_defaults:?}",
3615        );
3616        assert!(
3617            overlap.is_empty(),
3618            "cache replay and forensic-only classes must not overlap: {overlap:?}",
3619        );
3620        assert!(
3621            unclassified.is_empty(),
3622            "default capture payload types must be cache replayed or forensic-only: {unclassified:?}",
3623        );
3624        assert!(
3625            extra.is_empty(),
3626            "cache replay classification must not list uncaptured payload types: {extra:?}",
3627        );
3628    }
3629
3630    #[rstest]
3631    fn cache_replay_capture_payload_types_have_replay_rules() {
3632        for payload_type in CACHE_REPLAY_CAPTURE_PAYLOAD_TYPES {
3633            let entry = append_payload(1, payload_type, Bytes::from_static(&[0xc1])).entry;
3634            let mut cache = Cache::default();
3635
3636            let err = apply_cache_replay_entry(&mut cache, &entry)
3637                .expect_err("cache replay payload type must have a decode rule");
3638
3639            match err {
3640                CacheReplayError::Decode {
3641                    payload_type: actual,
3642                    ..
3643                } => {
3644                    assert_eq!(actual, *payload_type);
3645                }
3646                other => panic!("expected Decode for {payload_type}, was {other:?}"),
3647            }
3648        }
3649    }
3650
3651    #[rstest]
3652    fn forensic_only_capture_payload_types_are_not_cache_replayed() {
3653        for payload_type in FORENSIC_ONLY_CAPTURE_PAYLOAD_TYPES {
3654            let entry = append_payload(1, payload_type, Bytes::from_static(&[0xc1])).entry;
3655            let mut cache = Cache::default();
3656
3657            let applied = apply_cache_replay_entry(&mut cache, &entry)
3658                .expect("forensic-only payload type must not be decoded by cache replay");
3659
3660            assert!(
3661                !applied,
3662                "forensic-only payload type must be ignored by cache replay: {payload_type}",
3663            );
3664        }
3665    }
3666
3667    #[rstest]
3668    fn legacy_forward_prices_response_is_ignored_by_cache_replay() {
3669        let entry = append_payload(1, "ForwardPricesResponse", Bytes::from_static(&[0xc1])).entry;
3670        let mut cache = Cache::default();
3671
3672        let applied = apply_cache_replay_entry(&mut cache, &entry)
3673            .expect("legacy forensic payload must not be decoded by cache replay");
3674
3675        assert!(!applied);
3676    }
3677
3678    #[rstest]
3679    fn cache_public_mutators_have_recovery_classification() {
3680        let mut classified = AHashSet::new();
3681        let mut duplicates = Vec::new();
3682
3683        for row in CACHE_MUTATION_COVERAGE {
3684            if !classified.insert(row.method) {
3685                duplicates.push(row.method);
3686            }
3687        }
3688
3689        for method in CACHE_MUTATION_EXCLUSIONS {
3690            if !classified.insert(*method) {
3691                duplicates.push(*method);
3692            }
3693        }
3694
3695        let public_methods = cache_public_methods();
3696        let mutable_methods = cache_public_mutable_methods();
3697        let missing = sorted_missing_methods(&mutable_methods, &classified);
3698        let stale = sorted_stale_methods(&classified, &public_methods);
3699
3700        assert!(
3701            duplicates.is_empty(),
3702            "cache mutation recovery classifications must be unique: {duplicates:?}",
3703        );
3704        assert!(
3705            missing.is_empty(),
3706            "public Cache mutators must be classified for recovery: {missing:?}",
3707        );
3708        assert!(
3709            stale.is_empty(),
3710            "cache mutation recovery classifications reference missing methods: {stale:?}",
3711        );
3712    }
3713
3714    #[rstest]
3715    fn cache_mutation_replay_classification_matches_payload_buckets() {
3716        for row in CACHE_MUTATION_COVERAGE {
3717            match row.class {
3718                CacheMutationRecoveryClass::EventStoreCapturedAndReplayed => {
3719                    assert!(
3720                        !row.payload_types.is_empty(),
3721                        "cache-replayed mutation must cite captured payloads: {}",
3722                        row.method,
3723                    );
3724
3725                    for payload_type in row.payload_types {
3726                        assert!(
3727                            CACHE_REPLAY_CAPTURE_PAYLOAD_TYPES.contains(payload_type),
3728                            "cache mutation {} cites non-replayed payload {payload_type}",
3729                            row.method,
3730                        );
3731                    }
3732                }
3733                CacheMutationRecoveryClass::ForensicOnly => {
3734                    assert!(
3735                        !row.payload_types.is_empty(),
3736                        "forensic-only mutation must cite forensic payloads: {}",
3737                        row.method,
3738                    );
3739
3740                    for payload_type in row.payload_types {
3741                        assert!(
3742                            FORENSIC_ONLY_CAPTURE_PAYLOAD_TYPES.contains(payload_type),
3743                            "cache mutation {} cites non-forensic payload {payload_type}",
3744                            row.method,
3745                        );
3746                    }
3747                }
3748                CacheMutationRecoveryClass::SnapshotOwned
3749                | CacheMutationRecoveryClass::MissingLiveRecovery => {
3750                    assert!(
3751                        row.payload_types.is_empty(),
3752                        "non-event-store cache mutation {} should not cite payloads",
3753                        row.method,
3754                    );
3755                }
3756            }
3757        }
3758    }
3759
3760    #[rstest]
3761    fn submit_order_list_replay_restores_order_list() {
3762        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
3763        let instrument_id = instrument.id();
3764        let first_init = OrderInitializedSpec::builder()
3765            .instrument_id(instrument_id)
3766            .client_order_id(ClientOrderId::from("O-LIST-001"))
3767            .build();
3768        let second_init = OrderInitializedSpec::builder()
3769            .instrument_id(instrument_id)
3770            .client_order_id(ClientOrderId::from("O-LIST-002"))
3771            .build();
3772        let order_list = OrderList::new(
3773            OrderListId::from("OL-001"),
3774            instrument_id,
3775            first_init.strategy_id,
3776            vec![first_init.client_order_id, second_init.client_order_id],
3777            UnixNanos::from(1),
3778        );
3779        let command = SubmitOrderList::new(
3780            first_init.trader_id,
3781            Some(ClientId::from("SIM")),
3782            first_init.strategy_id,
3783            order_list.clone(),
3784            vec![first_init, second_init],
3785            None,
3786            None,
3787            None,
3788            UUID4::new(),
3789            UnixNanos::from(2),
3790            None,
3791        );
3792        let entry = append_serde_payload(1, PAYLOAD_TYPE_SUBMIT_ORDER_LIST, &command).entry;
3793        let mut cache = Cache::default();
3794
3795        let applied = apply_cache_replay_entry(&mut cache, &entry).expect("apply order list");
3796        let replayed = cache
3797            .order_list(&order_list.id)
3798            .expect("order list replayed");
3799
3800        assert!(applied);
3801        assert_eq!(replayed, &order_list);
3802    }
3803
3804    #[rstest]
3805    fn data_response_replay_restores_instruments_and_market_data() {
3806        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
3807        let instrument_id = instrument.id();
3808        let client_id = ClientId::from("DATA");
3809        let quote = QuoteTick::new(
3810            instrument_id,
3811            Price::from("1.00000"),
3812            Price::from("1.00010"),
3813            Quantity::from("100000"),
3814            Quantity::from("100000"),
3815            UnixNanos::from(10),
3816            UnixNanos::from(11),
3817        );
3818        let trade = TradeTick::new(
3819            instrument_id,
3820            Price::from("1.00005"),
3821            Quantity::from("50000"),
3822            AggressorSide::Buy,
3823            TradeId::from("T-DATA-001"),
3824            UnixNanos::from(12),
3825            UnixNanos::from(13),
3826        );
3827        let funding_rate = FundingRateUpdate::new(
3828            instrument_id,
3829            "0.0001".parse().expect("funding rate"),
3830            Some(480),
3831            Some(UnixNanos::from(60)),
3832            UnixNanos::from(14),
3833            UnixNanos::from(15),
3834        );
3835        let bar_type = BarType::new(
3836            instrument_id,
3837            BarSpecification::new(1, BarAggregation::Minute, PriceType::Last),
3838            AggregationSource::External,
3839        );
3840        let bar = Bar::new(
3841            bar_type,
3842            Price::from("1.00000"),
3843            Price::from("1.00020"),
3844            Price::from("0.99990"),
3845            Price::from("1.00010"),
3846            Quantity::from("150000"),
3847            UnixNanos::from(16),
3848            UnixNanos::from(17),
3849        );
3850        let reader = reader_with_entries(
3851            "run-data-response-replay",
3852            &[
3853                append_serde_payload(
3854                    1,
3855                    PAYLOAD_TYPE_INSTRUMENT_RESPONSE,
3856                    &InstrumentResponse::new(
3857                        UUID4::new(),
3858                        client_id,
3859                        instrument_id,
3860                        instrument.clone(),
3861                        None,
3862                        None,
3863                        UnixNanos::from(1),
3864                        None,
3865                    ),
3866                ),
3867                append_serde_payload(
3868                    2,
3869                    PAYLOAD_TYPE_INSTRUMENTS_RESPONSE,
3870                    &InstrumentsResponse::new(
3871                        UUID4::new(),
3872                        client_id,
3873                        instrument_id.venue,
3874                        vec![instrument],
3875                        None,
3876                        None,
3877                        UnixNanos::from(2),
3878                        None,
3879                    ),
3880                ),
3881                append_serde_payload(
3882                    3,
3883                    PAYLOAD_TYPE_QUOTES_RESPONSE,
3884                    &QuotesResponse::new(
3885                        UUID4::new(),
3886                        client_id,
3887                        instrument_id,
3888                        vec![quote],
3889                        None,
3890                        None,
3891                        UnixNanos::from(3),
3892                        None,
3893                    ),
3894                ),
3895                append_serde_payload(
3896                    4,
3897                    PAYLOAD_TYPE_TRADES_RESPONSE,
3898                    &TradesResponse::new(
3899                        UUID4::new(),
3900                        client_id,
3901                        instrument_id,
3902                        vec![trade],
3903                        None,
3904                        None,
3905                        UnixNanos::from(4),
3906                        None,
3907                    ),
3908                ),
3909                append_serde_payload(
3910                    5,
3911                    PAYLOAD_TYPE_FUNDING_RATES_RESPONSE,
3912                    &FundingRatesResponse::new(
3913                        UUID4::new(),
3914                        client_id,
3915                        instrument_id,
3916                        vec![funding_rate],
3917                        None,
3918                        None,
3919                        UnixNanos::from(5),
3920                        None,
3921                    ),
3922                ),
3923                append_serde_payload(
3924                    6,
3925                    PAYLOAD_TYPE_BARS_RESPONSE,
3926                    &BarsResponse::new(
3927                        UUID4::new(),
3928                        client_id,
3929                        bar_type,
3930                        vec![bar],
3931                        None,
3932                        None,
3933                        UnixNanos::from(6),
3934                        None,
3935                    ),
3936                ),
3937            ],
3938        );
3939        let mut cache = Cache::default();
3940
3941        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
3942
3943        assert_eq!(report.applied_entries, 6);
3944        assert_eq!(report.ignored_entries, 0);
3945        assert_eq!(
3946            cache.instrument(&instrument_id).map(Instrument::id),
3947            Some(instrument_id)
3948        );
3949        assert_eq!(cache.quotes(&instrument_id), Some(vec![quote]));
3950        assert_eq!(cache.trades(&instrument_id), Some(vec![trade]));
3951        assert_eq!(
3952            cache.funding_rates(&instrument_id),
3953            Some(vec![funding_rate])
3954        );
3955        assert_eq!(cache.bars(&bar_type), Some(vec![bar]));
3956    }
3957
3958    #[rstest]
3959    #[case::quotes(true)]
3960    #[case::trades(false)]
3961    fn narrowed_response_envelope_capture_replays_only_visible_rows(
3962        #[case] quotes: bool,
3963        #[values(false, true)] empty: bool,
3964    ) {
3965        use nautilus_common::messages::data::{DataResponse, DataResponseEnvelope};
3966
3967        use crate::capture::builtins::{
3968            PAYLOAD_TYPE_DATA_RESPONSE_ENVELOPE, ResponseEnvelopeCapture, default_registry,
3969        };
3970
3971        let id = InstrumentId::from("AUD/USD.SIM");
3972        let root = UUID4::new();
3973        let child = UUID4::new();
3974
3975        let quote = QuoteTick {
3976            instrument_id: id,
3977            ts_init: UnixNanos::from(23),
3978            ..Default::default()
3979        };
3980
3981        let trade = TradeTick {
3982            instrument_id: id,
3983            ts_init: UnixNanos::from(29),
3984            ..Default::default()
3985        };
3986
3987        let end = if empty { 1 } else { 2 };
3988
3989        let response = if quotes {
3990            DataResponse::Quotes(QuotesResponse::new(
3991                child,
3992                ClientId::from("HISTORY"),
3993                id,
3994                BatchView::new(Arc::new(vec![quote, quote, quote]), 1..end),
3995                Some(UnixNanos::from(11)),
3996                Some(UnixNanos::from(37)),
3997                UnixNanos::from(41),
3998                None,
3999            ))
4000        } else {
4001            DataResponse::Trades(TradesResponse::new(
4002                child,
4003                ClientId::from("HISTORY"),
4004                id,
4005                BatchView::new(Arc::new(vec![trade, trade, trade]), 1..end),
4006                Some(UnixNanos::from(11)),
4007                Some(UnixNanos::from(37)),
4008                UnixNanos::from(43),
4009                None,
4010            ))
4011        };
4012
4013        let envelope =
4014            DataResponseEnvelope::new(response, true, Some(child)).with_correlation_id(root);
4015        let registry = default_registry();
4016        let (tag, encoded) = registry.encode(&envelope).unwrap().unwrap();
4017        let captured: ResponseEnvelopeCapture = rmp_serde::from_slice(&encoded.payload).unwrap();
4018        let reader = reader_with_entries(
4019            "narrowed-response-envelope",
4020            &[append_payload(1, tag.as_str(), encoded.payload)],
4021        );
4022        let mut cache = Cache::default();
4023
4024        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4025
4026        assert_eq!(tag.as_str(), PAYLOAD_TYPE_DATA_RESPONSE_ENVELOPE);
4027        assert_eq!(captured.correlation_id, root);
4028        assert_eq!(captured.sub_correlation_id, Some(child));
4029        assert!(captured.completed);
4030        assert_eq!(captured.failure_reason, None);
4031        assert_eq!(report.applied_entries, 1);
4032        assert_eq!(report.ignored_entries, 0);
4033        assert_eq!(cache.quotes(&id), (quotes && !empty).then(|| vec![quote]));
4034        assert_eq!(cache.trades(&id), (!quotes && !empty).then(|| vec![trade]));
4035    }
4036
4037    #[rstest]
4038    fn scalar_tick_response_replay_restores_previous_payload_schema() {
4039        #[derive(Serialize)]
4040        struct ScalarResponse<T> {
4041            correlation_id: UUID4,
4042            client_id: ClientId,
4043            instrument_id: InstrumentId,
4044            data: Vec<T>,
4045            start: Option<UnixNanos>,
4046            end: Option<UnixNanos>,
4047            ts_init: UnixNanos,
4048            params: Option<nautilus_core::Params>,
4049        }
4050
4051        let id = InstrumentId::from("AUD/USD.SIM");
4052
4053        let quote = QuoteTick::new(
4054            id,
4055            Price::from("1.00001"),
4056            Price::from("1.00023"),
4057            Quantity::from(17),
4058            Quantity::from(31),
4059            UnixNanos::from(43),
4060            UnixNanos::from(47),
4061        );
4062
4063        let trade = TradeTick::new(
4064            id,
4065            Price::from("1.00019"),
4066            Quantity::from(23),
4067            AggressorSide::Buy,
4068            TradeId::from("OLD-TRADE"),
4069            UnixNanos::from(53),
4070            UnixNanos::from(59),
4071        );
4072
4073        let quotes = ScalarResponse {
4074            correlation_id: UUID4::new(),
4075            client_id: ClientId::from("DATA"),
4076            instrument_id: id,
4077            data: vec![quote],
4078            start: Some(UnixNanos::from(37)),
4079            end: Some(UnixNanos::from(61)),
4080            ts_init: UnixNanos::from(67),
4081            params: None,
4082        };
4083
4084        let trades = ScalarResponse {
4085            correlation_id: UUID4::new(),
4086            client_id: ClientId::from("DATA"),
4087            instrument_id: id,
4088            data: vec![trade],
4089            start: Some(UnixNanos::from(41)),
4090            end: Some(UnixNanos::from(71)),
4091            ts_init: UnixNanos::from(73),
4092            params: None,
4093        };
4094
4095        let reader = reader_with_entries(
4096            "scalar-tick-responses",
4097            &[
4098                append_serde_payload(1, PAYLOAD_TYPE_QUOTES_RESPONSE, &quotes),
4099                append_serde_payload(2, PAYLOAD_TYPE_TRADES_RESPONSE, &trades),
4100            ],
4101        );
4102        let mut cache = Cache::default();
4103
4104        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4105
4106        assert_eq!(report.applied_entries, 2);
4107        assert_eq!(report.ignored_entries, 0);
4108        assert_eq!(cache.quotes(&id), Some(vec![quote]));
4109        assert_eq!(cache.trades(&id), Some(vec![trade]));
4110    }
4111
4112    #[rstest]
4113    fn scalar_tick_response_replay_rejects_incomplete_metadata() {
4114        #[derive(Serialize)]
4115        struct IncompleteResponse {
4116            instrument_id: InstrumentId,
4117            data: Vec<QuoteTick>,
4118        }
4119
4120        let id = InstrumentId::from("AUD/USD.SIM");
4121
4122        let response = IncompleteResponse {
4123            instrument_id: id,
4124            data: vec![QuoteTick {
4125                instrument_id: id,
4126                ..Default::default()
4127            }],
4128        };
4129
4130        let reader = reader_with_entries(
4131            "incomplete-scalar-response",
4132            &[append_serde_payload(
4133                1,
4134                PAYLOAD_TYPE_QUOTES_RESPONSE,
4135                &response,
4136            )],
4137        );
4138        let mut cache = Cache::default();
4139
4140        let error = replay_cache_snapshot_tail(&mut cache, &reader).unwrap_err();
4141
4142        let CacheReplayError::Decode {
4143            seq,
4144            payload_type,
4145            message,
4146        } = error
4147        else {
4148            panic!("Expected invalid response metadata");
4149        };
4150
4151        assert_eq!(seq, 1);
4152        assert_eq!(payload_type, PAYLOAD_TYPE_QUOTES_RESPONSE);
4153        assert_eq!(message, "missing field `correlation_id`");
4154        assert_eq!(cache.quotes(&id), None);
4155    }
4156
4157    #[rstest]
4158    fn empty_data_response_replay_is_noop() {
4159        let instrument_id = InstrumentAny::CurrencyPair(audusd_sim()).id();
4160        let client_id = ClientId::from("DATA");
4161        let bar_type = BarType::new(
4162            instrument_id,
4163            BarSpecification::new(1, BarAggregation::Minute, PriceType::Last),
4164            AggregationSource::External,
4165        );
4166        let reader = reader_with_entries(
4167            "run-empty-data-response-replay",
4168            &[
4169                append_serde_payload(
4170                    1,
4171                    PAYLOAD_TYPE_INSTRUMENTS_RESPONSE,
4172                    &InstrumentsResponse::new(
4173                        UUID4::new(),
4174                        client_id,
4175                        instrument_id.venue,
4176                        Vec::new(),
4177                        None,
4178                        None,
4179                        UnixNanos::from(1),
4180                        None,
4181                    ),
4182                ),
4183                append_serde_payload(
4184                    2,
4185                    PAYLOAD_TYPE_QUOTES_RESPONSE,
4186                    &QuotesResponse::new(
4187                        UUID4::new(),
4188                        client_id,
4189                        instrument_id,
4190                        Vec::new(),
4191                        None,
4192                        None,
4193                        UnixNanos::from(2),
4194                        None,
4195                    ),
4196                ),
4197                append_serde_payload(
4198                    3,
4199                    PAYLOAD_TYPE_TRADES_RESPONSE,
4200                    &TradesResponse::new(
4201                        UUID4::new(),
4202                        client_id,
4203                        instrument_id,
4204                        Vec::new(),
4205                        None,
4206                        None,
4207                        UnixNanos::from(3),
4208                        None,
4209                    ),
4210                ),
4211                append_serde_payload(
4212                    4,
4213                    PAYLOAD_TYPE_FUNDING_RATES_RESPONSE,
4214                    &FundingRatesResponse::new(
4215                        UUID4::new(),
4216                        client_id,
4217                        instrument_id,
4218                        Vec::new(),
4219                        None,
4220                        None,
4221                        UnixNanos::from(4),
4222                        None,
4223                    ),
4224                ),
4225                append_serde_payload(
4226                    5,
4227                    PAYLOAD_TYPE_BARS_RESPONSE,
4228                    &BarsResponse::new(
4229                        UUID4::new(),
4230                        client_id,
4231                        bar_type,
4232                        Vec::new(),
4233                        None,
4234                        None,
4235                        UnixNanos::from(5),
4236                        None,
4237                    ),
4238                ),
4239            ],
4240        );
4241        let mut cache = Cache::default();
4242
4243        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4244
4245        assert_eq!(report.applied_entries, 5);
4246        assert_eq!(report.ignored_entries, 0);
4247        assert!(cache.instrument(&instrument_id).is_none());
4248        assert_eq!(cache.quotes(&instrument_id), None);
4249        assert_eq!(cache.trades(&instrument_id), None);
4250        assert_eq!(cache.funding_rates(&instrument_id), None);
4251        assert_eq!(cache.bars(&bar_type), None);
4252    }
4253
4254    #[rstest]
4255    #[case(false)]
4256    #[case(true)]
4257    fn command_denial_replay_does_not_create_missing_order(#[case] cancel: bool) {
4258        let event = if cancel {
4259            OrderEventAny::CancelDenied(
4260                OrderCancelDeniedSpec::builder()
4261                    .causation_id(UUID4::new())
4262                    .build(),
4263            )
4264        } else {
4265            OrderEventAny::ModifyDenied(
4266                OrderModifyDeniedSpec::builder()
4267                    .causation_id(UUID4::new())
4268                    .build(),
4269            )
4270        };
4271
4272        let reader = reader_with_entries("run-command-only", &[append_order_event(1, &event)]);
4273        let mut cache = Cache::default();
4274        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4275        assert!(!cache.order_exists(&event.client_order_id()));
4276        assert_eq!(report.applied_entries, 0);
4277        assert_eq!(report.ignored_entries, 1);
4278    }
4279
4280    #[rstest]
4281    #[case(false)]
4282    #[case(true)]
4283    fn command_denial_replay_restores_correlated_pending_state(#[case] cancel_first: bool) {
4284        let initialized = OrderInitializedSpec::builder()
4285            .instrument_id(audusd_sim().id())
4286            .order_type(OrderType::Limit)
4287            .quantity(Quantity::from(5))
4288            .price(Price::from("0.90000"))
4289            .build();
4290        let client_order_id = initialized.client_order_id;
4291        let submitted = OrderSubmittedSpec::builder()
4292            .instrument_id(initialized.instrument_id)
4293            .client_order_id(client_order_id)
4294            .build();
4295        let accepted = OrderAcceptedSpec::builder()
4296            .instrument_id(initialized.instrument_id)
4297            .client_order_id(client_order_id)
4298            .account_id(submitted.account_id)
4299            .build();
4300        let modify = UUID4::new();
4301        let cancel = UUID4::new();
4302        let mut pending_modify = OrderPendingUpdateSpec::builder()
4303            .instrument_id(initialized.instrument_id)
4304            .client_order_id(client_order_id)
4305            .account_id(submitted.account_id)
4306            .venue_order_id(accepted.venue_order_id)
4307            .build();
4308        pending_modify.causation_id = Some(modify);
4309        let mut pending_cancel = OrderPendingCancelSpec::builder()
4310            .instrument_id(initialized.instrument_id)
4311            .client_order_id(client_order_id)
4312            .account_id(submitted.account_id)
4313            .venue_order_id(accepted.venue_order_id)
4314            .build();
4315        pending_cancel.causation_id = Some(cancel);
4316        let modify_denied = OrderEventAny::ModifyDenied(
4317            OrderModifyDeniedSpec::builder()
4318                .instrument_id(initialized.instrument_id)
4319                .client_order_id(client_order_id)
4320                .account_id(submitted.account_id)
4321                .venue_order_id(accepted.venue_order_id)
4322                .causation_id(modify)
4323                .build(),
4324        );
4325        let cancel_denied = OrderEventAny::CancelDenied(
4326            OrderCancelDeniedSpec::builder()
4327                .instrument_id(initialized.instrument_id)
4328                .client_order_id(client_order_id)
4329                .account_id(submitted.account_id)
4330                .venue_order_id(accepted.venue_order_id)
4331                .causation_id(cancel)
4332                .build(),
4333        );
4334
4335        let (first, second) = if cancel_first {
4336            (cancel_denied, modify_denied)
4337        } else {
4338            (modify_denied, cancel_denied)
4339        };
4340
4341        let events = [
4342            OrderEventAny::Initialized(initialized),
4343            OrderEventAny::Submitted(submitted),
4344            OrderEventAny::Accepted(accepted),
4345            OrderEventAny::PendingUpdate(pending_modify),
4346            OrderEventAny::PendingCancel(pending_cancel),
4347            first,
4348        ];
4349        let entries: Vec<_> = events
4350            .iter()
4351            .enumerate()
4352            .map(|(index, event)| append_order_event(index as u64 + 1, event))
4353            .collect();
4354        let reader = reader_with_entries("run-correlated-denials", &entries);
4355        let mut cache = Cache::default();
4356        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4357        let restored = cache.order_owned(&client_order_id).unwrap();
4358        assert_eq!(report.applied_entries, 6);
4359        assert_eq!(report.ignored_entries, 0);
4360        assert_eq!(
4361            restored.status(),
4362            if cancel_first {
4363                OrderStatus::PendingUpdate
4364            } else {
4365                OrderStatus::PendingCancel
4366            }
4367        );
4368        assert_eq!(restored.has_pending_cancel_command(), !cancel_first);
4369        assert_eq!(restored.has_pending_update_command(), cancel_first);
4370        assert_eq!(restored.quantity(), Quantity::from(5));
4371        assert_eq!(restored.price(), Some(Price::from("0.90000")));
4372        assert_eq!(restored.filled_qty(), Quantity::from(0));
4373        let tail = reader_with_entries("run-remaining-denial", &[append_order_event(1, &second)]);
4374        let report = replay_cache_snapshot_tail(&mut cache, &tail).unwrap();
4375        let restored = cache.order_owned(&client_order_id).unwrap();
4376        assert_eq!(report.applied_entries, 1);
4377        assert_eq!(report.ignored_entries, 0);
4378        assert_eq!(restored.status(), OrderStatus::Accepted);
4379        assert!(!restored.has_pending_cancel_command());
4380        assert!(!restored.has_pending_update_command());
4381        assert_eq!(restored.quantity(), Quantity::from(5));
4382        assert_eq!(restored.price(), Some(Price::from("0.90000")));
4383        assert_eq!(restored.filled_qty(), Quantity::from(0));
4384        assert_eq!(restored.last_event(), &second);
4385    }
4386
4387    #[rstest]
4388    fn order_fill_replay_updates_order_and_creates_position() {
4389        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4390        let position_id = PositionId::from("P-001");
4391        let initialized = OrderInitializedSpec::builder()
4392            .instrument_id(instrument.id())
4393            .build();
4394        let client_order_id = initialized.client_order_id;
4395        let submitted = OrderSubmittedSpec::builder()
4396            .instrument_id(instrument.id())
4397            .client_order_id(client_order_id)
4398            .build();
4399        let accepted = OrderAcceptedSpec::builder()
4400            .instrument_id(instrument.id())
4401            .client_order_id(client_order_id)
4402            .account_id(submitted.account_id)
4403            .build();
4404        let filled = OrderFilledSpec::builder()
4405            .instrument_id(instrument.id())
4406            .client_order_id(client_order_id)
4407            .venue_order_id(accepted.venue_order_id)
4408            .account_id(submitted.account_id)
4409            .position_id(position_id)
4410            .commission(Money::from("1 USD"))
4411            .build();
4412        let filled_event = OrderEventAny::Filled(filled.clone());
4413        let reader = reader_with_entries(
4414            "run-order-replay",
4415            &[
4416                append_order_event(1, &OrderEventAny::Initialized(initialized)),
4417                append_order_event(2, &OrderEventAny::Submitted(submitted)),
4418                append_order_event(3, &OrderEventAny::Accepted(accepted)),
4419                append_order_event(4, &filled_event),
4420            ],
4421        );
4422        let mut cache = Cache::default();
4423        cache.add_instrument(instrument).expect("add instrument");
4424
4425        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4426        let order = cache.order_owned(&client_order_id).expect("order replayed");
4427        let position = cache
4428            .position_owned(&position_id)
4429            .expect("position replayed");
4430
4431        assert_eq!(report.applied_entries, 4);
4432        assert_eq!(report.ignored_entries, 0);
4433        assert_eq!(order.status(), OrderStatus::Filled);
4434        assert_eq!(order.event_count(), 4);
4435        assert_eq!(order.last_event(), &filled_event);
4436        assert_eq!(position.event_count(), 1);
4437        assert_eq!(position.last_event(), Some(filled.clone()));
4438        assert_eq!(position.trade_ids(), vec![filled.trade_id]);
4439        assert_eq!(position.commissions(), vec![Money::from("1 USD")]);
4440    }
4441
4442    #[rstest]
4443    fn orderless_leg_fill_replay_creates_position_without_order_mapping() {
4444        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4445        let client_order_id = ClientOrderId::from("SPREAD-LEG-AUDUSD");
4446        let position_id = PositionId::from("P-ORDERLESS-LEG");
4447        let filled = OrderFilledSpec::builder()
4448            .instrument_id(instrument.id())
4449            .client_order_id(client_order_id)
4450            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-AUDUSD"))
4451            .position_id(position_id)
4452            .commission(Money::from("1 USD"))
4453            .build();
4454        let reader = reader_with_entries(
4455            "run-orderless-leg-fill-replay",
4456            &[append_order_event(
4457                1,
4458                &OrderEventAny::Filled(filled.clone()),
4459            )],
4460        );
4461        let mut cache = Cache::default();
4462        cache.add_instrument(instrument).expect("add instrument");
4463
4464        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4465        let position = cache
4466            .position_owned(&position_id)
4467            .expect("orderless leg position replayed");
4468
4469        assert_eq!(report.applied_entries, 1);
4470        assert_eq!(report.ignored_entries, 0);
4471        assert!(cache.order_owned(&client_order_id).is_none());
4472        assert_eq!(cache.position_id(&client_order_id), None);
4473        assert_eq!(position.event_count(), 1);
4474        assert_eq!(position.last_event(), Some(filled.clone()));
4475        assert_eq!(position.trade_ids(), vec![filled.trade_id]);
4476        assert_eq!(position.commissions(), vec![Money::from("1 USD")]);
4477        assert!(cache.check_integrity());
4478    }
4479
4480    #[rstest]
4481    #[case::netting(OmsType::Netting)]
4482    #[case::hedging(OmsType::Hedging)]
4483    fn order_backed_flip_replay_preserves_closed_and_opened_accounting(
4484        #[case] oms_type: OmsType,
4485        #[values(false, true)] empty_cache: bool,
4486    ) {
4487        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4488        let strategy_id = StrategyId::from("S-REPLAY-001");
4489
4490        let position_id = if oms_type == OmsType::Netting && empty_cache {
4491            PositionId::new(format!("{}-{strategy_id}", instrument.id()))
4492        } else {
4493            PositionId::from("P-REPLAY-FLIP")
4494        };
4495
4496        let replacement_id = if oms_type == OmsType::Netting {
4497            position_id
4498        } else {
4499            PositionId::from("P-REPLAY-REPLACEMENT")
4500        };
4501
4502        let opening = OrderFilledSpec::builder()
4503            .strategy_id(strategy_id)
4504            .instrument_id(instrument.id())
4505            .client_order_id(ClientOrderId::from("O-REPLAY-OPEN"))
4506            .venue_order_id(VenueOrderId::from("V-REPLAY-OPEN"))
4507            .position_id(position_id)
4508            .last_qty(Quantity::from(1))
4509            .last_px(Price::from("1.00000"))
4510            .commission(Money::from("0 USD"))
4511            .build();
4512        let original = Position::new(&instrument, opening.clone());
4513        let reversal = OrderFilledSpec::builder()
4514            .strategy_id(strategy_id)
4515            .instrument_id(instrument.id())
4516            .client_order_id(ClientOrderId::from("O-REPLAY-REVERSE"))
4517            .venue_order_id(VenueOrderId::from("V-REPLAY-REVERSE"))
4518            .trade_id(TradeId::from("T-REPLAY-REVERSE"))
4519            .position_id(position_id)
4520            .order_side(OrderSide::Sell)
4521            .last_qty(Quantity::from(2))
4522            .last_px(Price::from("2.00000"))
4523            .commission(Money::from_str_exact("0.006 USD").unwrap())
4524            .build();
4525        let (closing, opening_fragment) = reversal
4526            .split_for_position_flip(original.quantity, Some(replacement_id), UUID4::new())
4527            .unwrap();
4528        let mut closed = original.clone();
4529        closed.try_apply(&closing).unwrap();
4530        let closed_event = PositionClosed::create(&closed, &closing, UUID4::new(), closing.ts_init);
4531        let replacement = Position::new(&instrument, opening_fragment.clone());
4532        let opened_event = PositionOpened::create(
4533            &replacement,
4534            &opening_fragment,
4535            UUID4::new(),
4536            opening_fragment.ts_init,
4537        );
4538        let mut entries = Vec::new();
4539        if empty_cache {
4540            entries.extend(
4541                filled_order_events(&opening)
4542                    .iter()
4543                    .enumerate()
4544                    .map(|(index, event)| append_order_event(index as u64 + 1, event)),
4545            );
4546            let opened = PositionOpened::create(&original, &opening, UUID4::new(), opening.ts_init);
4547            entries.push(append_position_event(
4548                5,
4549                &PositionEvent::PositionOpened(opened),
4550            ));
4551        }
4552
4553        let offset = entries.len() as u64;
4554        entries.extend(
4555            filled_order_events(&reversal)
4556                .iter()
4557                .enumerate()
4558                .map(|(index, event)| append_order_event(offset + index as u64 + 1, event)),
4559        );
4560        entries.push(append_position_event(
4561            offset + 5,
4562            &PositionEvent::PositionClosed(closed_event),
4563        ));
4564        entries.push(append_position_event(
4565            offset + 6,
4566            &PositionEvent::PositionOpened(opened_event),
4567        ));
4568        let reader = reader_with_entries("run-order-backed-flip", &entries);
4569        let mut cache = Cache::default();
4570        cache.add_instrument(instrument).unwrap();
4571
4572        if !empty_cache {
4573            let order = OrderAny::from_events(filled_order_events(&opening).to_vec()).unwrap();
4574            cache
4575                .add_order(order, Some(position_id), None, false)
4576                .unwrap();
4577            cache.add_position(&original, oms_type).unwrap();
4578            cache.build_index();
4579        }
4580
4581        assert!(cache.check_integrity());
4582
4583        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4584        let replayed = cache.position_owned(&replacement_id).unwrap();
4585        let predecessor = if oms_type == OmsType::Netting {
4586            let mut snapshots = cache.position_snapshots(Some(&position_id), None);
4587            assert_eq!(snapshots.len(), 1);
4588            snapshots.remove(0)
4589        } else {
4590            cache.position_owned(&position_id).unwrap()
4591        };
4592
4593        assert_eq!(report.applied_entries, entries.len());
4594        assert_eq!(report.ignored_entries, 0);
4595        assert_eq!(predecessor.side, PositionSide::Flat);
4596        assert_eq!(
4597            predecessor.realized_pnl,
4598            Some(Money::from_str_exact("0.997 USD").unwrap())
4599        );
4600        assert_eq!(predecessor.cost_open, 0.into());
4601        assert_eq!(
4602            predecessor.commissions(),
4603            vec![Money::from_str_exact("0.003 USD").unwrap()]
4604        );
4605        assert_eq!(replayed.side, PositionSide::Short);
4606        assert_eq!(replayed.quantity, Quantity::from(1));
4607        assert_eq!(replayed.avg_px_open, 2.into());
4608        assert_eq!(replayed.cost_open, 2.into());
4609        assert_eq!(
4610            replayed.realized_pnl,
4611            Some(Money::from_str_exact("-0.003 USD").unwrap())
4612        );
4613        assert_eq!(
4614            replayed.commissions(),
4615            vec![Money::from_str_exact("0.003 USD").unwrap()]
4616        );
4617        assert_eq!(cache.oms_type(&replacement_id), Some(oms_type));
4618        assert_eq!(
4619            cache.position_id(&reversal.client_order_id),
4620            Some(&replacement_id)
4621        );
4622        assert_eq!(
4623            replayed.replay_events.len(),
4624            if oms_type == OmsType::Netting { 3 } else { 1 }
4625        );
4626        assert!(cache.check_integrity());
4627    }
4628
4629    #[rstest]
4630    #[case::matching_quantity("2", true, "9.47", "5.53 USD")]
4631    #[case::changed_quantity("1", false, "12", "3 USD")]
4632    fn price_restatement_replay_preserves_journal_accounting(
4633        #[case] restated_qty: &str,
4634        #[case] applied: bool,
4635        #[case] expected_px: &str,
4636        #[case] expected_pnl: &str,
4637    ) {
4638        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4639        let position_id = PositionId::from("P-REPLAY-RESTATEMENT");
4640        let opening = OrderFilledSpec::builder()
4641            .instrument_id(instrument.id())
4642            .client_order_id(ClientOrderId::from("O-REPLAY-RESTATEMENT"))
4643            .trade_id(TradeId::from("T-REPLAY-RESTATEMENT"))
4644            .position_id(position_id)
4645            .last_qty(Quantity::from(2))
4646            .last_px(Price::from("12.00000"))
4647            .commission(Money::from("0 USD"))
4648            .build();
4649        let mut live = Position::new(&instrument, opening.clone());
4650        let opened = PositionOpened::create(&live, &opening, UUID4::new(), opening.ts_init);
4651
4652        let restatement = OrderFilled {
4653            last_qty: Quantity::from(restated_qty),
4654            last_px: Price::from("9.47000"),
4655            event_id: UUID4::new(),
4656            ..opening.clone()
4657        };
4658
4659        let mut entries: Vec<_> = filled_order_events(&opening)
4660            .iter()
4661            .enumerate()
4662            .map(|(index, event)| append_order_event(index as u64 + 1, event))
4663            .collect();
4664        entries.push(append_position_event(
4665            5,
4666            &PositionEvent::PositionOpened(opened),
4667        ));
4668        entries.push(append_order_event(
4669            6,
4670            &OrderEventAny::Filled(restatement.clone()),
4671        ));
4672
4673        if applied {
4674            live.try_apply(&restatement).unwrap();
4675            let changed =
4676                PositionChanged::create(&live, &restatement, UUID4::new(), restatement.ts_init);
4677            entries.push(append_position_event(
4678                7,
4679                &PositionEvent::PositionChanged(changed),
4680            ));
4681        }
4682
4683        let reducing = OrderFilledSpec::builder()
4684            .instrument_id(instrument.id())
4685            .client_order_id(ClientOrderId::from("O-REPLAY-REDUCE"))
4686            .venue_order_id(VenueOrderId::from("V-REPLAY-REDUCE"))
4687            .trade_id(TradeId::from("T-REPLAY-REDUCE"))
4688            .position_id(position_id)
4689            .order_side(OrderSide::Sell)
4690            .last_qty(Quantity::from(1))
4691            .last_px(Price::from("15.00000"))
4692            .commission(Money::zero(Currency::USD()))
4693            .build();
4694        live.try_apply(&reducing).unwrap();
4695        let changed = PositionChanged::create(&live, &reducing, UUID4::new(), reducing.ts_init);
4696        let offset = entries.len() as u64;
4697        entries.extend(
4698            filled_order_events(&reducing)
4699                .iter()
4700                .enumerate()
4701                .map(|(index, event)| append_order_event(offset + index as u64 + 1, event)),
4702        );
4703        entries.push(append_position_event(
4704            offset + 5,
4705            &PositionEvent::PositionChanged(changed),
4706        ));
4707        let reader = reader_with_entries("run-price-restatement", &entries);
4708        let mut cache = Cache::default();
4709        cache.add_instrument(instrument).unwrap();
4710
4711        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4712        let replayed = cache.position_owned(&position_id).unwrap();
4713
4714        assert_eq!(report.applied_entries, entries.len());
4715        assert_eq!(report.ignored_entries, 0);
4716        assert_eq!(replayed.quantity, Quantity::from(1));
4717        assert_eq!(replayed.avg_px_open, Price::from(expected_px).as_decimal());
4718        assert_eq!(replayed.cost_open, Price::from(expected_px).as_decimal());
4719        assert_eq!(replayed.realized_pnl, Some(Money::from(expected_pnl)));
4720        assert_eq!(replayed.event_count(), 2);
4721        assert_eq!(replayed.replay_events.len(), if applied { 3 } else { 2 });
4722        assert_eq!(
4723            rmp_serde::to_vec_named(&replayed).unwrap(),
4724            rmp_serde::to_vec_named(&live).unwrap()
4725        );
4726        assert!(cache.check_integrity());
4727    }
4728
4729    fn filled_order_events(fill: &OrderFilled) -> [OrderEventAny; 4] {
4730        let initialized = OrderInitializedSpec::builder()
4731            .strategy_id(fill.strategy_id)
4732            .instrument_id(fill.instrument_id)
4733            .client_order_id(fill.client_order_id)
4734            .order_side(fill.order_side)
4735            .quantity(fill.last_qty)
4736            .build();
4737        let submitted = OrderSubmittedSpec::builder()
4738            .strategy_id(fill.strategy_id)
4739            .instrument_id(fill.instrument_id)
4740            .client_order_id(fill.client_order_id)
4741            .account_id(fill.account_id)
4742            .build();
4743        let accepted = OrderAcceptedSpec::builder()
4744            .strategy_id(fill.strategy_id)
4745            .instrument_id(fill.instrument_id)
4746            .client_order_id(fill.client_order_id)
4747            .venue_order_id(fill.venue_order_id)
4748            .account_id(fill.account_id)
4749            .build();
4750
4751        [
4752            OrderEventAny::Initialized(initialized),
4753            OrderEventAny::Submitted(submitted),
4754            OrderEventAny::Accepted(accepted),
4755            OrderEventAny::Filled(fill.clone()),
4756        ]
4757    }
4758
4759    #[rstest]
4760    fn orderless_netting_reopen_replay_does_not_treat_closed_position_as_flip() {
4761        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4762        let client_order_id = ClientOrderId::from("SPREAD-LEG-AUDUSD");
4763        let position_id = PositionId::from("P-ORDERLESS-NETTING");
4764        let opening_fill = OrderFilledSpec::builder()
4765            .instrument_id(instrument.id())
4766            .client_order_id(client_order_id)
4767            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-1"))
4768            .trade_id(TradeId::from("T-SPREAD-LEG-1"))
4769            .order_side(OrderSide::Buy)
4770            .last_qty(Quantity::from(1))
4771            .position_id(position_id)
4772            .build();
4773        let closing_fill = OrderFilledSpec::builder()
4774            .instrument_id(instrument.id())
4775            .client_order_id(client_order_id)
4776            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-2"))
4777            .trade_id(TradeId::from("T-SPREAD-LEG-2"))
4778            .order_side(OrderSide::Sell)
4779            .last_qty(Quantity::from(1))
4780            .position_id(position_id)
4781            .build();
4782        let mut closed_position = Position::new(&instrument, opening_fill);
4783        closed_position.apply(&closing_fill);
4784        assert!(closed_position.is_closed());
4785
4786        let reopening_fill = OrderFilledSpec::builder()
4787            .instrument_id(instrument.id())
4788            .client_order_id(client_order_id)
4789            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-3"))
4790            .trade_id(TradeId::from("T-SPREAD-LEG-3"))
4791            .order_side(OrderSide::Sell)
4792            .last_qty(Quantity::from(1))
4793            .position_id(position_id)
4794            .build();
4795        let mut reopened_position = closed_position.clone();
4796        reopened_position.apply(&reopening_fill);
4797        let reopened = PositionOpened::create(
4798            &reopened_position,
4799            &reopening_fill,
4800            UUID4::new(),
4801            reopening_fill.ts_init,
4802        );
4803        let reader = reader_with_entries(
4804            "run-orderless-netting-reopen-replay",
4805            &[
4806                append_order_event(1, &OrderEventAny::Filled(reopening_fill.clone())),
4807                append_position_event(2, &PositionEvent::PositionOpened(reopened)),
4808            ],
4809        );
4810        let mut cache = Cache::default();
4811        cache.add_instrument(instrument).expect("add instrument");
4812        cache
4813            .add_position_without_order(&closed_position, OmsType::Netting)
4814            .expect("seed closed orderless position");
4815
4816        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4817        let position = cache
4818            .position_owned(&position_id)
4819            .expect("netting position reopened");
4820
4821        assert_eq!(report.applied_entries, 2);
4822        assert_eq!(report.ignored_entries, 0);
4823        assert!(position.is_open());
4824        assert_eq!(position.side, PositionSide::Short);
4825        assert_eq!(position.entry, OrderSide::Sell);
4826        assert_eq!(position.quantity, Quantity::from(1));
4827        assert_eq!(position.opening_order_id, client_order_id);
4828        assert_eq!(position.closing_order_id, None);
4829        assert_eq!(position.event_count(), 1);
4830        assert_eq!(position.trade_ids(), vec![reopening_fill.trade_id]);
4831        assert_eq!(position.last_event(), Some(reopening_fill));
4832        assert_eq!(cache.oms_type(&position_id), Some(OmsType::Netting));
4833        assert!(cache.orders_for_position(&position_id).is_empty());
4834        assert_eq!(cache.position_id(&client_order_id), None);
4835        assert!(cache.check_integrity());
4836    }
4837
4838    #[rstest]
4839    fn orderless_hedging_flip_replay_recreates_replacement_position() {
4840        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4841        let client_order_id = ClientOrderId::from("SPREAD-LEG-AUDUSD");
4842        let first_position_id = PositionId::from("P-ORDERLESS-LEG-1");
4843        let replacement_position_id = PositionId::from("P-ORDERLESS-LEG-2");
4844        let opening_fill = OrderFilledSpec::builder()
4845            .instrument_id(instrument.id())
4846            .client_order_id(client_order_id)
4847            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-1"))
4848            .trade_id(TradeId::from("T-SPREAD-LEG-1"))
4849            .order_side(OrderSide::Buy)
4850            .last_qty(Quantity::from(1))
4851            .last_px(Price::from("1.00000"))
4852            .position_id(first_position_id)
4853            .commission(Money::from("1 USD"))
4854            .build();
4855        let first_position = Position::new(&instrument, opening_fill.clone());
4856        let first_opened = PositionOpened::create(
4857            &first_position,
4858            &opening_fill,
4859            UUID4::new(),
4860            opening_fill.ts_init,
4861        );
4862
4863        let flip_fill = OrderFilledSpec::builder()
4864            .instrument_id(instrument.id())
4865            .client_order_id(client_order_id)
4866            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-2"))
4867            .trade_id(TradeId::from("T-SPREAD-LEG-2"))
4868            .order_side(OrderSide::Sell)
4869            .last_qty(Quantity::from(2))
4870            .last_px(Price::from("1.10000"))
4871            .position_id(first_position_id)
4872            .commission(Money::from("2 USD"))
4873            .build();
4874        let mut closing_fragment = flip_fill.clone();
4875        closing_fragment.last_qty = Quantity::from(1);
4876        closing_fragment.commission = Some(Money::from("1 USD"));
4877        let mut closed_position = first_position;
4878        closed_position.apply(&closing_fragment);
4879        let first_closed = PositionClosed::create(
4880            &closed_position,
4881            &closing_fragment,
4882            UUID4::new(),
4883            flip_fill.ts_init,
4884        );
4885
4886        let mut opening_fragment = flip_fill.clone();
4887        opening_fragment.last_qty = Quantity::from(1);
4888        opening_fragment.position_id = Some(replacement_position_id);
4889        opening_fragment.commission = Some(Money::from("1 USD"));
4890        opening_fragment.event_id = UUID4::new();
4891        opening_fragment.causation_id = Some(flip_fill.event_id);
4892        let mut replacement_position = Position::new(&instrument, opening_fragment.clone());
4893        let replacement_opened = PositionOpened::create(
4894            &replacement_position,
4895            &opening_fragment,
4896            UUID4::new(),
4897            opening_fragment.ts_init,
4898        );
4899
4900        let subsequent_fill = OrderFilledSpec::builder()
4901            .instrument_id(instrument.id())
4902            .client_order_id(client_order_id)
4903            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-3"))
4904            .trade_id(TradeId::from("T-SPREAD-LEG-3"))
4905            .order_side(OrderSide::Sell)
4906            .last_qty(Quantity::from(1))
4907            .last_px(Price::from("1.20000"))
4908            .position_id(replacement_position_id)
4909            .commission(Money::from("1 USD"))
4910            .build();
4911        replacement_position.apply(&subsequent_fill);
4912        let replacement_changed = PositionChanged::create(
4913            &replacement_position,
4914            &subsequent_fill,
4915            UUID4::new(),
4916            subsequent_fill.ts_init,
4917        );
4918        let reader = reader_with_entries(
4919            "run-orderless-hedging-flip-replay",
4920            &[
4921                append_order_event(1, &OrderEventAny::Filled(opening_fill)),
4922                append_position_event(2, &PositionEvent::PositionOpened(first_opened)),
4923                append_order_event(3, &OrderEventAny::Filled(flip_fill.clone())),
4924                append_position_event(4, &PositionEvent::PositionClosed(first_closed)),
4925                append_position_event(5, &PositionEvent::PositionOpened(replacement_opened)),
4926                append_order_event(6, &OrderEventAny::Filled(subsequent_fill.clone())),
4927                append_position_event(7, &PositionEvent::PositionChanged(replacement_changed)),
4928            ],
4929        );
4930        let mut cache = Cache::default();
4931        cache.add_instrument(instrument).expect("add instrument");
4932
4933        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4934
4935        assert_eq!(report.applied_entries, 7);
4936        assert_eq!(report.ignored_entries, 0);
4937        let closed = cache
4938            .position_owned(&first_position_id)
4939            .expect("closed predecessor replayed");
4940        assert!(closed.is_closed());
4941        assert_eq!(closed.event_count(), 2);
4942        let closing_fragments = closed.fill_fragments(client_order_id, flip_fill.trade_id);
4943        assert_eq!(closing_fragments.len(), 1);
4944        assert_eq!(closing_fragments[0].last_qty, Quantity::from(1));
4945        assert_eq!(closing_fragments[0].commission, Some(Money::from("1 USD")));
4946        assert_eq!(closing_fragments[0].event_id, flip_fill.event_id);
4947
4948        let replacement = cache
4949            .position_owned(&replacement_position_id)
4950            .expect("open replacement replayed");
4951        assert!(replacement.is_open());
4952        assert_eq!(replacement.side, PositionSide::Short);
4953        assert_eq!(replacement.quantity, Quantity::from(2));
4954        assert_eq!(replacement.event_count(), 2);
4955        assert_eq!(
4956            cache.oms_type(&replacement_position_id),
4957            Some(OmsType::Hedging)
4958        );
4959        assert!(replacement.trade_ids().contains(&flip_fill.trade_id));
4960        assert!(replacement.trade_ids().contains(&subsequent_fill.trade_id));
4961        let opening_fragments = replacement.fill_fragments(client_order_id, flip_fill.trade_id);
4962        assert_eq!(opening_fragments.len(), 1);
4963        assert_eq!(opening_fragments[0].last_qty, Quantity::from(1));
4964        assert_eq!(opening_fragments[0].commission, Some(Money::from("1 USD")));
4965        assert_eq!(opening_fragments[0].causation_id, Some(flip_fill.event_id));
4966
4967        assert!(cache.orders_for_position(&first_position_id).is_empty());
4968        assert!(
4969            cache
4970                .orders_for_position(&replacement_position_id)
4971                .is_empty()
4972        );
4973        assert_eq!(cache.position_id(&client_order_id), None);
4974        assert!(cache.check_integrity());
4975    }
4976
4977    #[rstest]
4978    fn single_entry_orderless_flip_is_rejected_before_mutating_position() {
4979        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4980        let position_id = PositionId::from("P-ORDERLESS-SINGLE-ENTRY");
4981        let opening_fill = OrderFilledSpec::builder()
4982            .instrument_id(instrument.id())
4983            .client_order_id(ClientOrderId::from("SPREAD-LEG-SINGLE"))
4984            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-SINGLE-1"))
4985            .trade_id(TradeId::from("T-SPREAD-LEG-SINGLE-1"))
4986            .order_side(OrderSide::Buy)
4987            .last_qty(Quantity::from(1))
4988            .position_id(position_id)
4989            .build();
4990        let original = Position::new(&instrument, opening_fill.clone());
4991        let flip_fill = OrderFilledSpec::builder()
4992            .instrument_id(instrument.id())
4993            .client_order_id(opening_fill.client_order_id)
4994            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-SINGLE-2"))
4995            .trade_id(TradeId::from("T-SPREAD-LEG-SINGLE-2"))
4996            .order_side(OrderSide::Sell)
4997            .last_qty(Quantity::from(2))
4998            .position_id(position_id)
4999            .build();
5000        let entry = append_order_event(1, &OrderEventAny::Filled(flip_fill)).entry;
5001        let mut cache = Cache::default();
5002        cache
5003            .add_instrument(instrument)
5004            .expect("add replay instrument");
5005        cache
5006            .add_position_without_order(&original, OmsType::Hedging)
5007            .expect("seed orderless position");
5008
5009        let error = apply_cache_replay_entry(&mut cache, &entry)
5010            .expect_err("single-entry API cannot defer the opening fragment");
5011        let after = cache
5012            .position_owned(&position_id)
5013            .expect("position retained");
5014
5015        assert!(error.to_string().contains("snapshot-tail replay context"));
5016        assert_eq!(after.side, original.side);
5017        assert_eq!(after.quantity, original.quantity);
5018        assert_eq!(after.event_count(), original.event_count());
5019        assert_eq!(after.trade_ids(), original.trade_ids());
5020    }
5021
5022    #[rstest]
5023    fn duplicate_orderless_reducing_fill_is_not_replayed_as_flip() {
5024        // A replayed duplicate of an earlier reducing fill can exceed the remaining
5025        // quantity; its trade ID is already in the open episode, so it must be the
5026        // idempotent no-op rather than a flip.
5027        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5028        let position_id = PositionId::from("P-ORDERLESS-DUPLICATE");
5029        let opening_fill = OrderFilledSpec::builder()
5030            .instrument_id(instrument.id())
5031            .client_order_id(ClientOrderId::from("SPREAD-LEG-DUPLICATE"))
5032            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-DUPLICATE-1"))
5033            .trade_id(TradeId::from("T-SPREAD-LEG-DUPLICATE-1"))
5034            .order_side(OrderSide::Buy)
5035            .last_qty(Quantity::from(3))
5036            .position_id(position_id)
5037            .build();
5038        let reducing_fill = OrderFilledSpec::builder()
5039            .instrument_id(instrument.id())
5040            .client_order_id(opening_fill.client_order_id)
5041            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-DUPLICATE-2"))
5042            .trade_id(TradeId::from("T-SPREAD-LEG-DUPLICATE-2"))
5043            .order_side(OrderSide::Sell)
5044            .last_qty(Quantity::from(2))
5045            .position_id(position_id)
5046            .build();
5047        let mut original = Position::new(&instrument, opening_fill);
5048        original.apply(&reducing_fill);
5049        let entry = append_order_event(1, &OrderEventAny::Filled(reducing_fill)).entry;
5050        let mut cache = Cache::default();
5051        cache
5052            .add_instrument(instrument)
5053            .expect("add replay instrument");
5054        cache
5055            .add_position_without_order(&original, OmsType::Hedging)
5056            .expect("seed orderless position");
5057
5058        let applied = apply_cache_replay_entry(&mut cache, &entry)
5059            .expect("duplicate reducing fill is the idempotent no-op");
5060        let after = cache
5061            .position_owned(&position_id)
5062            .expect("position retained");
5063
5064        assert!(applied);
5065        assert_eq!(after.side, PositionSide::Long);
5066        assert_eq!(after.quantity, original.quantity);
5067        assert_eq!(after.event_count(), original.event_count());
5068        assert_eq!(after.trade_ids(), original.trade_ids());
5069    }
5070
5071    #[rstest]
5072    fn order_fill_replay_without_instrument_counts_fill_as_ignored() {
5073        // The position side cannot open without the instrument; the fill must count
5074        // as ignored rather than claim a full apply.
5075        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5076        let position_id = PositionId::from("P-NO-INSTR");
5077        let initialized = OrderInitializedSpec::builder()
5078            .instrument_id(instrument.id())
5079            .build();
5080        let client_order_id = initialized.client_order_id;
5081        let submitted = OrderSubmittedSpec::builder()
5082            .instrument_id(instrument.id())
5083            .client_order_id(client_order_id)
5084            .build();
5085        let accepted = OrderAcceptedSpec::builder()
5086            .instrument_id(instrument.id())
5087            .client_order_id(client_order_id)
5088            .account_id(submitted.account_id)
5089            .build();
5090        let filled = OrderFilledSpec::builder()
5091            .instrument_id(instrument.id())
5092            .client_order_id(client_order_id)
5093            .venue_order_id(accepted.venue_order_id)
5094            .account_id(submitted.account_id)
5095            .position_id(position_id)
5096            .build();
5097        let reader = reader_with_entries(
5098            "run-fill-no-instrument",
5099            &[
5100                append_order_event(1, &OrderEventAny::Initialized(initialized)),
5101                append_order_event(2, &OrderEventAny::Submitted(submitted)),
5102                append_order_event(3, &OrderEventAny::Accepted(accepted)),
5103                append_order_event(4, &OrderEventAny::Filled(filled)),
5104            ],
5105        );
5106        let mut cache = Cache::default();
5107
5108        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
5109
5110        assert_eq!(report.applied_entries, 3);
5111        assert_eq!(report.ignored_entries, 1);
5112        assert!(cache.position_owned(&position_id).is_none());
5113    }
5114
5115    #[rstest]
5116    fn order_fill_void_replay_updates_order_and_position() {
5117        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5118        let position_id = PositionId::from("P-VOID-001");
5119        let initialized = OrderInitializedSpec::builder()
5120            .instrument_id(instrument.id())
5121            .build();
5122        let client_order_id = initialized.client_order_id;
5123        let submitted = OrderSubmittedSpec::builder()
5124            .instrument_id(instrument.id())
5125            .client_order_id(client_order_id)
5126            .build();
5127        let accepted = OrderAcceptedSpec::builder()
5128            .instrument_id(instrument.id())
5129            .client_order_id(client_order_id)
5130            .account_id(submitted.account_id)
5131            .build();
5132        let filled = OrderFilledSpec::builder()
5133            .instrument_id(instrument.id())
5134            .client_order_id(client_order_id)
5135            .venue_order_id(accepted.venue_order_id)
5136            .account_id(submitted.account_id)
5137            .position_id(position_id)
5138            .commission(Money::from("1 USD"))
5139            .build();
5140        let fill_voided = OrderFillVoidedSpec::builder()
5141            .trader_id(filled.trader_id)
5142            .strategy_id(filled.strategy_id)
5143            .instrument_id(filled.instrument_id)
5144            .client_order_id(filled.client_order_id)
5145            .venue_order_id(filled.venue_order_id)
5146            .account_id(filled.account_id)
5147            .trade_id(filled.trade_id)
5148            .voided_qty(Quantity::from(50_000))
5149            .commission_voided(Money::from("0.40 USD"))
5150            .order_side(filled.order_side)
5151            .order_type(filled.order_type)
5152            .last_px(filled.last_px)
5153            .currency(filled.currency)
5154            .liquidity_side(filled.liquidity_side)
5155            .position_id(position_id)
5156            .is_reopened(true)
5157            .build();
5158        let reader = reader_with_entries(
5159            "run-fill-void-replay",
5160            &[
5161                append_order_event(1, &OrderEventAny::Initialized(initialized)),
5162                append_order_event(2, &OrderEventAny::Submitted(submitted)),
5163                append_order_event(3, &OrderEventAny::Accepted(accepted)),
5164                append_order_event(4, &OrderEventAny::Filled(filled)),
5165                append_order_event(5, &OrderEventAny::FillVoided(fill_voided.clone())),
5166            ],
5167        );
5168        let mut cache = Cache::default();
5169        cache.add_instrument(instrument).expect("add instrument");
5170
5171        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
5172        let order = cache.order_owned(&client_order_id).expect("order replayed");
5173        let position = cache
5174            .position_owned(&position_id)
5175            .expect("position replayed");
5176
5177        assert_eq!(report.applied_entries, 5);
5178        assert_eq!(report.ignored_entries, 0);
5179        assert_eq!(order.status(), OrderStatus::PartiallyFilled);
5180        assert_eq!(order.filled_qty(), Quantity::from(50_000));
5181        assert_eq!(order.voided_qty(), Quantity::from(50_000));
5182        assert_eq!(position.quantity, Quantity::from(50_000));
5183        assert_eq!(position.commissions(), vec![Money::from("0.60 USD")]);
5184        assert_eq!(position.fill_voids.len(), 1);
5185        assert_eq!(position.fill_voids[0].event, fill_voided);
5186    }
5187
5188    fn binary_order_events(
5189        instrument: &InstrumentAny,
5190        order_id: &str,
5191        quantity: &str,
5192        price: &str,
5193    ) -> [OrderEventAny; 4] {
5194        let position_id = PositionId::from("P-SETTLED");
5195        let filled = OrderFilledSpec::builder()
5196            .instrument_id(instrument.id())
5197            .client_order_id(ClientOrderId::from(order_id))
5198            .venue_order_id(VenueOrderId::from(format!("V-{order_id}").as_str()))
5199            .trade_id(TradeId::from(format!("T-{order_id}").as_str()))
5200            .last_qty(Quantity::from(quantity))
5201            .last_px(Price::from(price))
5202            .currency(Currency::USDC())
5203            .position_id(position_id)
5204            .build();
5205
5206        filled_order_events(&filled)
5207    }
5208
5209    #[rstest]
5210    fn instrument_close_replay_settles_position_and_keeps_later_changes_off_it() {
5211        let instrument = InstrumentAny::BinaryOption(binary_option());
5212        let opening = binary_order_events(&instrument, "O-OPEN", "10.00", "0.400");
5213        let late = binary_order_events(&instrument, "O-LATE", "5.00", "0.500");
5214
5215        let OrderEventAny::Filled(opening_fill) = &opening[3] else {
5216            unreachable!();
5217        };
5218
5219        let close = InstrumentClose::new(
5220            instrument.id(),
5221            Price::from("1.000"),
5222            InstrumentCloseType::ContractExpired,
5223            UnixNanos::from(300),
5224            UnixNanos::from(301),
5225        );
5226        let fill_voided = OrderFillVoidedSpec::builder()
5227            .trader_id(opening_fill.trader_id)
5228            .strategy_id(opening_fill.strategy_id)
5229            .instrument_id(opening_fill.instrument_id)
5230            .client_order_id(opening_fill.client_order_id)
5231            .venue_order_id(opening_fill.venue_order_id)
5232            .account_id(opening_fill.account_id)
5233            .trade_id(opening_fill.trade_id)
5234            .voided_qty(Quantity::from("4.00"))
5235            .order_side(opening_fill.order_side)
5236            .order_type(opening_fill.order_type)
5237            .last_px(opening_fill.last_px)
5238            .currency(opening_fill.currency)
5239            .liquidity_side(opening_fill.liquidity_side)
5240            .position_id(PositionId::from("P-SETTLED"))
5241            .build();
5242        let encoded_close = encode_instrument_close(&close).expect("encode instrument close");
5243        let mut entries: Vec<AppendEntry> = opening
5244            .iter()
5245            .enumerate()
5246            .map(|(index, event)| append_order_event(index as u64 + 1, event))
5247            .collect();
5248        entries.push(append_payload(
5249            5,
5250            PAYLOAD_TYPE_INSTRUMENT_CLOSE,
5251            encoded_close.payload,
5252        ));
5253        entries.extend(
5254            late.iter()
5255                .enumerate()
5256                .map(|(index, event)| append_order_event(index as u64 + 6, event)),
5257        );
5258        entries.push(append_order_event(
5259            10,
5260            &OrderEventAny::FillVoided(fill_voided),
5261        ));
5262        let reader = reader_with_entries("run-settlement-replay", &entries);
5263        let mut cache = Cache::default();
5264        cache.add_instrument(instrument).expect("add instrument");
5265
5266        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
5267        let position = cache
5268            .position_owned(&PositionId::from("P-SETTLED"))
5269            .expect("position replayed");
5270        let late_order = cache
5271            .order_owned(&ClientOrderId::from("O-LATE"))
5272            .expect("late order replayed");
5273        let opening_order = cache
5274            .order_owned(&ClientOrderId::from("O-OPEN"))
5275            .expect("opening order replayed");
5276
5277        assert_eq!(report.applied_entries, 10);
5278        assert_eq!(report.ignored_entries, 0);
5279        assert!(position.is_settled());
5280        assert!(position.is_closed());
5281        assert_eq!(position.quantity, Quantity::from("0.00"));
5282        assert_eq!(position.buy_qty, Quantity::from("10.00"));
5283        assert_eq!(position.realized_pnl, Some(Money::from("6.00 USDC")));
5284        assert!(position.fill_voids.is_empty());
5285        assert_eq!(late_order.status(), OrderStatus::Filled);
5286        assert_eq!(late_order.filled_qty(), Quantity::from("5.00"));
5287        assert_eq!(opening_order.voided_qty(), Quantity::from("4.00"));
5288        assert_eq!(cache.instrument_close(&close.instrument_id), Some(&close));
5289    }
5290
5291    #[rstest]
5292    fn order_fill_void_replay_updates_order_without_position() {
5293        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5294        let initialized = OrderInitializedSpec::builder()
5295            .instrument_id(instrument.id())
5296            .build();
5297        let client_order_id = initialized.client_order_id;
5298        let submitted = OrderSubmittedSpec::builder()
5299            .instrument_id(instrument.id())
5300            .client_order_id(client_order_id)
5301            .build();
5302        let accepted = OrderAcceptedSpec::builder()
5303            .instrument_id(instrument.id())
5304            .client_order_id(client_order_id)
5305            .account_id(submitted.account_id)
5306            .build();
5307        let filled = OrderFilledSpec::builder()
5308            .instrument_id(instrument.id())
5309            .client_order_id(client_order_id)
5310            .venue_order_id(accepted.venue_order_id)
5311            .account_id(submitted.account_id)
5312            .build();
5313        let fill_voided = OrderFillVoidedSpec::builder()
5314            .trader_id(filled.trader_id)
5315            .strategy_id(filled.strategy_id)
5316            .instrument_id(filled.instrument_id)
5317            .client_order_id(filled.client_order_id)
5318            .venue_order_id(filled.venue_order_id)
5319            .account_id(filled.account_id)
5320            .trade_id(filled.trade_id)
5321            .voided_qty(Quantity::from(50_000))
5322            .order_side(filled.order_side)
5323            .order_type(filled.order_type)
5324            .last_px(filled.last_px)
5325            .currency(filled.currency)
5326            .liquidity_side(filled.liquidity_side)
5327            .is_reopened(true)
5328            .build();
5329        let reader = reader_with_entries(
5330            "run-order-only-fill-void-replay",
5331            &[
5332                append_order_event(1, &OrderEventAny::Initialized(initialized)),
5333                append_order_event(2, &OrderEventAny::Submitted(submitted)),
5334                append_order_event(3, &OrderEventAny::Accepted(accepted)),
5335                append_order_event(4, &OrderEventAny::Filled(filled)),
5336                append_order_event(5, &OrderEventAny::FillVoided(fill_voided)),
5337            ],
5338        );
5339        let mut cache = Cache::default();
5340        cache.add_instrument(instrument).expect("add instrument");
5341
5342        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
5343        let order = cache.order_owned(&client_order_id).expect("order replayed");
5344
5345        assert_eq!(report.applied_entries, 5);
5346        assert_eq!(report.ignored_entries, 0);
5347        assert_eq!(order.status(), OrderStatus::PartiallyFilled);
5348        assert_eq!(order.filled_qty(), Quantity::from(50_000));
5349        assert_eq!(order.voided_qty(), Quantity::from(50_000));
5350        assert_eq!(cache.positions_total_count(None, None, None, None, None), 0);
5351    }
5352
5353    #[cfg(feature = "defi")]
5354    #[rstest]
5355    #[case::native_instrument(0, "1.000000000000000001", "0.500000000000000001")]
5356    #[case::wei_instrument(18, "1", "0.5")]
5357    #[case::large_native(0, "1000000000000", "999999999999.5")]
5358    fn fill_void_replay_accepts_mixed_qty_scales(
5359        #[case] precision: u8,
5360        #[case] qty: &str,
5361        #[case] remaining: &str,
5362    ) {
5363        let mut instrument = audusd_sim();
5364        instrument.size_precision = precision;
5365        let instrument = InstrumentAny::CurrencyPair(instrument);
5366        let events = binary_order_events(&instrument, "O-MIXED-VOID", qty, "1");
5367
5368        let OrderEventAny::Filled(fill) = &events[3] else {
5369            panic!("Expected fill");
5370        };
5371
5372        let voided_qty =
5373            Quantity::from_decimal_dp("0.5".parse().unwrap(), fill.last_qty.precision.max(1))
5374                .unwrap();
5375        let voided = OrderFillVoidedSpec::builder()
5376            .trader_id(fill.trader_id)
5377            .strategy_id(fill.strategy_id)
5378            .instrument_id(fill.instrument_id)
5379            .client_order_id(fill.client_order_id)
5380            .venue_order_id(fill.venue_order_id)
5381            .account_id(fill.account_id)
5382            .trade_id(fill.trade_id)
5383            .voided_qty(voided_qty)
5384            .order_side(fill.order_side)
5385            .order_type(fill.order_type)
5386            .last_px(fill.last_px)
5387            .currency(fill.currency)
5388            .liquidity_side(fill.liquidity_side)
5389            .maybe_position_id(fill.position_id)
5390            .is_reopened(true)
5391            .build();
5392        let entries = [
5393            append_order_event(1, &events[0]),
5394            append_order_event(2, &events[1]),
5395            append_order_event(3, &events[2]),
5396            append_order_event(4, &events[3]),
5397            append_order_event(5, &OrderEventAny::FillVoided(voided.clone())),
5398        ];
5399        let reader = reader_with_entries("run-mixed-fill-void", &entries);
5400        let mut cache = Cache::default();
5401        cache.add_instrument(instrument).unwrap();
5402
5403        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
5404
5405        let position = cache.position_owned(&fill.position_id.unwrap()).unwrap();
5406        let order = cache.order_owned(&fill.client_order_id).unwrap();
5407        assert_eq!(report.applied_entries, 5);
5408        assert_eq!(report.ignored_entries, 0);
5409        assert_eq!(position.quantity, Quantity::from(remaining));
5410        assert_eq!(position.signed_qty, Quantity::from(remaining).as_decimal());
5411        assert_eq!(position.realized_pnl, Some(Money::zero(Currency::USD())));
5412        assert_eq!(position.fill_voids.len(), 1);
5413        assert_eq!(position.fill_voids[0].event, voided);
5414        assert_eq!(order.filled_qty(), Quantity::from(remaining));
5415        assert_eq!(order.voided_qty(), voided_qty);
5416    }
5417
5418    #[cfg(feature = "defi")]
5419    #[rstest]
5420    #[case::covered("2", true)]
5421    #[case::uncovered("3", false)]
5422    fn fill_void_fragment_allocation_aligns_native_and_wei_scales(
5423        #[case] voided_qty: &str,
5424        #[case] covered: bool,
5425    ) {
5426        let closing_id = PositionId::from("P-CLOSING");
5427        let opening_id = PositionId::from("P-OPENING");
5428
5429        let fragments = [
5430            FillVoidFragment {
5431                position_id: closing_id,
5432                split_rank: 0,
5433                quantity: Quantity::from("1.00"),
5434                commission: None,
5435            },
5436            FillVoidFragment {
5437                position_id: opening_id,
5438                split_rank: 1,
5439                quantity: Quantity::from("1.000000000000000001"),
5440                commission: None,
5441            },
5442        ];
5443
5444        let event = OrderFillVoidedSpec::builder()
5445            .voided_qty(Quantity::from(voided_qty))
5446            .build();
5447        let entry = append_order_event(1, &OrderEventAny::FillVoided(event.clone())).entry;
5448
5449        let result = allocate_fill_void_fragments(&entry, &event, &fragments);
5450
5451        if covered {
5452            assert_eq!(
5453                result.unwrap(),
5454                IndexMap::from([
5455                    (opening_id, (Quantity::from("1.000000000000000001"), None)),
5456                    (closing_id, (Quantity::from("0.999999999999999999"), None)),
5457                ])
5458            );
5459        } else {
5460            assert!(
5461                matches!(result.unwrap_err(), CacheReplayError::Apply { message, .. } if message.contains("do not cover voided quantity"))
5462            );
5463        }
5464    }
5465
5466    #[rstest]
5467    fn position_lifecycle_replay_preserves_journal_accounting() {
5468        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5469        let position_id = PositionId::from("P-001");
5470        let opened_fill = OrderFilledSpec::builder()
5471            .instrument_id(instrument.id())
5472            .client_order_id(ClientOrderId::from("O-OPEN"))
5473            .venue_order_id(VenueOrderId::from("V-OPEN"))
5474            .trade_id(TradeId::from("T-OPEN"))
5475            .position_id(position_id)
5476            .last_qty(Quantity::from("1"))
5477            .last_px(Price::from("1.00000"))
5478            .build();
5479        let mut live_position = Position::new(&instrument, opened_fill.clone());
5480        let opened_position = live_position.clone();
5481        let opened = PositionOpened::create(
5482            &live_position,
5483            &opened_fill,
5484            UUID4::new(),
5485            UnixNanos::from(10),
5486        );
5487
5488        let changed_fill = OrderFilledSpec::builder()
5489            .instrument_id(instrument.id())
5490            .client_order_id(ClientOrderId::from("O-CHANGE"))
5491            .venue_order_id(VenueOrderId::from("V-CHANGE"))
5492            .trade_id(TradeId::from("T-CHANGE"))
5493            .position_id(position_id)
5494            .last_qty(Quantity::from("2"))
5495            .last_px(Price::from("1.10000"))
5496            .build();
5497        live_position.apply(&changed_fill);
5498        let changed_position = live_position.clone();
5499        let changed = PositionChanged::create(
5500            &live_position,
5501            &changed_fill,
5502            UUID4::new(),
5503            UnixNanos::from(20),
5504        );
5505
5506        let closed_fill = OrderFilledSpec::builder()
5507            .instrument_id(instrument.id())
5508            .client_order_id(ClientOrderId::from("O-CLOSE"))
5509            .venue_order_id(VenueOrderId::from("V-CLOSE"))
5510            .trade_id(TradeId::from("T-CLOSE"))
5511            .order_side(OrderSide::Sell)
5512            .position_id(position_id)
5513            .last_qty(Quantity::from("3"))
5514            .last_px(Price::from("1.20000"))
5515            .build();
5516        live_position.apply(&closed_fill);
5517        let closed = PositionClosed::create(
5518            &live_position,
5519            &closed_fill,
5520            UUID4::new(),
5521            UnixNanos::from(30),
5522        );
5523
5524        let mut cache = Cache::default();
5525        cache
5526            .add_position(&opened_position, OmsType::Unspecified)
5527            .expect("seed opened position");
5528
5529        let opened_entry =
5530            append_position_event(1, &PositionEvent::PositionOpened(opened.clone())).entry;
5531        let changed_entry =
5532            append_position_event(2, &PositionEvent::PositionChanged(changed.clone())).entry;
5533        let closed_entry =
5534            append_position_event(3, &PositionEvent::PositionClosed(closed.clone())).entry;
5535
5536        assert!(apply_cache_replay_entry(&mut cache, &opened_entry).expect("apply opened"));
5537        let replayed = cache
5538            .position_owned(&position_id)
5539            .expect("position after opened");
5540        assert_eq!(replayed.signed_qty, opened.signed_qty);
5541        assert_eq!(replayed.quantity, opened.quantity);
5542        assert_eq!(replayed.ts_last, opened.ts_event);
5543
5544        let fill_entry = append_order_event(2, &OrderEventAny::Filled(changed_fill.clone())).entry;
5545        assert!(apply_fill_to_position(&mut cache, &fill_entry, &changed_fill, false).unwrap());
5546        assert!(apply_cache_replay_entry(&mut cache, &changed_entry).expect("apply changed"));
5547        let replayed = cache
5548            .position_owned(&position_id)
5549            .expect("position after changed");
5550        assert_eq!(replayed.signed_qty, changed.signed_qty);
5551        assert_eq!(replayed.quantity, changed.quantity);
5552        assert_eq!(replayed.peak_qty, changed.peak_quantity);
5553        assert_eq!(replayed.avg_px_open, changed.avg_px_open);
5554        assert!(replayed.is_open());
5555
5556        assert_eq!(
5557            rmp_serde::to_vec_named(&replayed).unwrap(),
5558            rmp_serde::to_vec_named(&changed_position).unwrap()
5559        );
5560        let fill_entry = append_order_event(3, &OrderEventAny::Filled(closed_fill.clone())).entry;
5561        assert!(apply_fill_to_position(&mut cache, &fill_entry, &closed_fill, false).unwrap());
5562        assert!(apply_cache_replay_entry(&mut cache, &closed_entry).expect("apply closed"));
5563        let replayed = cache
5564            .position_owned(&position_id)
5565            .expect("position after closed");
5566        assert_eq!(replayed.signed_qty, closed.signed_qty);
5567        assert_eq!(replayed.quantity, closed.quantity);
5568        assert_eq!(replayed.closing_order_id, closed.closing_order_id);
5569        assert_eq!(replayed.duration_ns, closed.duration);
5570        assert!(replayed.is_closed());
5571        assert!(cache.is_position_closed(&position_id));
5572        assert_eq!(
5573            rmp_serde::to_vec_named(&replayed).unwrap(),
5574            rmp_serde::to_vec_named(&live_position).unwrap()
5575        );
5576    }
5577
5578    #[rstest]
5579    #[case::opened_quantity("opened", "quantity")]
5580    #[case::opened_average("opened", "average")]
5581    #[case::opened_pnl("opened", "pnl")]
5582    #[case::changed_quantity("changed", "quantity")]
5583    #[case::changed_average("changed", "average")]
5584    #[case::changed_pnl("changed", "pnl")]
5585    #[case::closed_quantity("closed", "quantity")]
5586    #[case::closed_average("closed", "average")]
5587    #[case::closed_pnl("closed", "pnl")]
5588    fn position_lifecycle_replay_rejects_inconsistent_accounting(
5589        #[case] kind: &str,
5590        #[case] field: &str,
5591    ) {
5592        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5593        let position_id = PositionId::from("P-001");
5594        let mut fill = OrderFilledSpec::builder()
5595            .instrument_id(instrument.id())
5596            .position_id(position_id)
5597            .last_qty(Quantity::from("1"))
5598            .last_px(Price::from("1.00000"))
5599            .commission(Money::from_str_exact("0.000001 USD").unwrap())
5600            .build();
5601        let mut position = Position::new(&instrument, fill.clone());
5602        if kind == "closed" {
5603            fill.event_id = UUID4::new();
5604            fill.trade_id = TradeId::from("T-CLOSE");
5605            fill.order_side = OrderSide::Sell;
5606            fill.last_px = Price::from("1.00001");
5607            position.try_apply(&fill).unwrap();
5608        }
5609
5610        let mut event = match kind {
5611            "opened" => PositionEvent::PositionOpened(PositionOpened::create(
5612                &position,
5613                &fill,
5614                UUID4::new(),
5615                UnixNanos::from(10),
5616            )),
5617            "changed" => PositionEvent::PositionChanged(PositionChanged::create(
5618                &position,
5619                &fill,
5620                UUID4::new(),
5621                UnixNanos::from(10),
5622            )),
5623            "closed" => PositionEvent::PositionClosed(PositionClosed::create(
5624                &position,
5625                &fill,
5626                UUID4::new(),
5627                UnixNanos::from(10),
5628            )),
5629            _ => unreachable!(),
5630        };
5631
5632        let (quantity, average, pnl) = match &mut event {
5633            PositionEvent::PositionOpened(event) => (
5634                &mut event.signed_qty,
5635                &mut event.avg_px_open,
5636                &mut event.realized_pnl,
5637            ),
5638            PositionEvent::PositionChanged(event) => (
5639                &mut event.signed_qty,
5640                &mut event.avg_px_open,
5641                &mut event.realized_pnl,
5642            ),
5643            PositionEvent::PositionClosed(event) => (
5644                &mut event.signed_qty,
5645                &mut event.avg_px_open,
5646                &mut event.realized_pnl,
5647            ),
5648            PositionEvent::PositionAdjusted(_) => unreachable!(),
5649        };
5650
5651        match field {
5652            "quantity" => *quantity = 9.into(),
5653            "average" => *average = 2.into(),
5654            "pnl" => *pnl = None,
5655            _ => unreachable!(),
5656        }
5657
5658        let mut cache = Cache::default();
5659        cache.add_position(&position, OmsType::Unspecified).unwrap();
5660        let before = rmp_serde::to_vec_named(&position).unwrap();
5661        let entry = append_position_event(1, &event).entry;
5662
5663        let error = apply_cache_replay_entry(&mut cache, &entry).unwrap_err();
5664        let restored = cache.position_owned(&position_id).unwrap();
5665
5666        assert!(
5667            matches!(error, CacheReplayError::Apply { message, .. } if message.contains("accounting differs from journal"))
5668        );
5669        assert_eq!(rmp_serde::to_vec_named(&restored).unwrap(), before);
5670    }
5671
5672    #[rstest]
5673    fn position_adjustment_replay_updates_existing_position() {
5674        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5675        let position_id = PositionId::from("P-001");
5676        let fill = OrderFilledSpec::builder()
5677            .instrument_id(instrument.id())
5678            .position_id(position_id)
5679            .build();
5680        let position = Position::new(&instrument, fill.clone());
5681        let adjustment = PositionAdjusted::new(
5682            fill.trader_id,
5683            fill.strategy_id,
5684            fill.instrument_id,
5685            position_id,
5686            fill.account_id,
5687            PositionAdjustmentType::Funding,
5688            None,
5689            Some(Money::from("2 USD")),
5690            Some(Ustr::from("funding")),
5691            UUID4::new(),
5692            UnixNanos::from(10),
5693            UnixNanos::from(11),
5694        );
5695        let entry = append_position_event(1, &PositionEvent::PositionAdjusted(adjustment)).entry;
5696        let mut cache = Cache::default();
5697        cache
5698            .add_position(&position, OmsType::Unspecified)
5699            .expect("seed position");
5700
5701        let applied = apply_cache_replay_entry(&mut cache, &entry).expect("apply");
5702        let position = cache
5703            .position_owned(&position_id)
5704            .expect("position updated");
5705
5706        assert!(applied);
5707        assert_eq!(position.adjustments, vec![adjustment]);
5708        assert_eq!(position.realized_pnl, Some(Money::from("2 USD")));
5709        assert_eq!(position.ts_last, adjustment.ts_event);
5710    }
5711
5712    #[rstest]
5713    fn position_event_for_unknown_position_is_counted_as_ignored() {
5714        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5715        let position_id = PositionId::from("P-MISSING");
5716        let fill = OrderFilledSpec::builder()
5717            .instrument_id(instrument.id())
5718            .position_id(position_id)
5719            .build();
5720        let position = Position::new(&instrument, fill.clone());
5721        let opened = PositionOpened::create(&position, &fill, UUID4::new(), UnixNanos::from(10));
5722        let entry = append_position_event(1, &PositionEvent::PositionOpened(opened)).entry;
5723        let mut cache = Cache::default();
5724
5725        let applied = apply_cache_replay_entry(&mut cache, &entry).expect("apply");
5726
5727        assert!(
5728            !applied,
5729            "missing position must count as ignored, not applied"
5730        );
5731    }
5732
5733    #[rstest]
5734    fn order_filled_with_no_order_side_is_an_apply_error_not_a_panic() {
5735        // The entry hash proves the stored bytes match what was written, not that the
5736        // producer wrote a valid fill; the legacy sentinel deserializes cleanly and
5737        // without the guard panics deep inside Position/Order application.
5738        let payload = IndexMap::from([("order_side", "NO_ORDER_SIDE")]);
5739        let entry = append_serde_payload(1, PAYLOAD_TYPE_ORDER_FILLED, &payload).entry;
5740        let mut cache = Cache::default();
5741
5742        let err = apply_cache_replay_entry(&mut cache, &entry).expect_err("must reject");
5743
5744        match err {
5745            CacheReplayError::Apply { seq, message, .. } => {
5746                assert_eq!(seq, 1);
5747                assert!(message.contains("NoOrderSide"), "message was: {message}");
5748            }
5749            other => panic!("expected Apply, was {other:?}"),
5750        }
5751    }
5752
5753    #[rstest]
5754    fn duplicate_position_fill_is_not_applied_twice() {
5755        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5756        let position_id = PositionId::from("P-001");
5757        let fill = OrderFilledSpec::builder()
5758            .instrument_id(instrument.id())
5759            .position_id(position_id)
5760            .commission(Money::from("1 USD"))
5761            .build();
5762        let position = Position::new(&instrument, fill.clone());
5763        let entry = append_order_event(1, &OrderEventAny::Filled(fill.clone())).entry;
5764        let mut cache = Cache::default();
5765        cache
5766            .add_position(&position, OmsType::Unspecified)
5767            .expect("seed position");
5768
5769        let applied = apply_fill_to_position(&mut cache, &entry, &fill, false).expect("apply fill");
5770        let position = cache
5771            .position_owned(&position_id)
5772            .expect("position updated");
5773
5774        assert!(
5775            applied,
5776            "duplicate trade within an open episode is the idempotent no-op and counts as applied"
5777        );
5778        assert_eq!(position.event_count(), 1);
5779        assert_eq!(position.trade_ids(), vec![fill.trade_id]);
5780        assert_eq!(position.commissions(), vec![Money::from("1 USD")]);
5781    }
5782
5783    #[rstest]
5784    fn flat_position_with_reused_trade_id_is_ignored_like_live() {
5785        // Live `Position::apply_fill` ignores a fill whose trade id already sits in
5786        // the position's carried replay history, so replay must not skip it early or
5787        // reopen the position either: `apply` ignores it and state matches live.
5788        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5789        let position_id = PositionId::from("P-REOPEN");
5790        let open_fill = OrderFilledSpec::builder()
5791            .instrument_id(instrument.id())
5792            .position_id(position_id)
5793            .order_side(OrderSide::Buy)
5794            .trade_id(TradeId::from("T-1"))
5795            .commission(Money::from("2 USD"))
5796            .build();
5797        let close_fill = OrderFilledSpec::builder()
5798            .instrument_id(instrument.id())
5799            .position_id(position_id)
5800            .order_side(OrderSide::Sell)
5801            .trade_id(TradeId::from("T-2"))
5802            .build();
5803        let mut position = Position::new(&instrument, open_fill);
5804        position.apply(&close_fill);
5805        assert_eq!(position.side, PositionSide::Flat);
5806
5807        let dup_fill = OrderFilledSpec::builder()
5808            .instrument_id(instrument.id())
5809            .position_id(position_id)
5810            .order_side(OrderSide::Buy)
5811            .trade_id(TradeId::from("T-1"))
5812            .commission(Money::from("1 USD"))
5813            .build();
5814        let entry = append_order_event(3, &OrderEventAny::Filled(dup_fill.clone())).entry;
5815        let mut cache = Cache::default();
5816        cache
5817            .add_position(&position, OmsType::Unspecified)
5818            .expect("seed position");
5819
5820        let applied = apply_fill_to_position(&mut cache, &entry, &dup_fill, false).expect("apply");
5821        let position = cache
5822            .position_owned(&position_id)
5823            .expect("position updated");
5824
5825        assert!(
5826            applied,
5827            "a historical duplicate is the idempotent no-op and counts as applied"
5828        );
5829        assert_eq!(position.side, PositionSide::Flat);
5830        assert_eq!(position.event_count(), 2);
5831        assert_eq!(position.trade_ids().len(), 2);
5832        assert_eq!(position.commissions(), vec![Money::from("2 USD")]);
5833    }
5834
5835    #[rstest]
5836    fn fill_for_missing_instrument_is_counted_as_ignored() {
5837        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5838        let position_id = PositionId::from("P-NO-INSTR");
5839        let fill = OrderFilledSpec::builder()
5840            .instrument_id(instrument.id())
5841            .position_id(position_id)
5842            .build();
5843        let entry = append_order_event(1, &OrderEventAny::Filled(fill.clone())).entry;
5844        let mut cache = Cache::default();
5845
5846        let applied = apply_fill_to_position(&mut cache, &entry, &fill, false).expect("apply");
5847
5848        assert!(
5849            !applied,
5850            "a position that cannot open must count as ignored, was claimed applied"
5851        );
5852        assert!(cache.position_owned(&position_id).is_none());
5853    }
5854
5855    #[rstest]
5856    fn corrupt_supported_payload_returns_decode_error() {
5857        let reader = reader_with_entries(
5858            "run-decode-error",
5859            &[append_payload(
5860                1,
5861                PAYLOAD_TYPE_ACCOUNT_STATE,
5862                Bytes::copy_from_slice(&[0xc1]),
5863            )],
5864        );
5865        let mut cache = Cache::default();
5866
5867        let err = replay_cache_snapshot_tail(&mut cache, &reader).expect_err("decode error");
5868
5869        match err {
5870            CacheReplayError::Decode {
5871                seq, payload_type, ..
5872            } => {
5873                assert_eq!(seq, 1);
5874                assert_eq!(payload_type, PAYLOAD_TYPE_ACCOUNT_STATE);
5875            }
5876            other => panic!("expected Decode, was {other:?}"),
5877        }
5878    }
5879
5880    #[rstest]
5881    fn missing_order_event_returns_apply_error() {
5882        let submitted = OrderSubmittedSpec::builder().build();
5883        let reader = reader_with_entries(
5884            "run-apply-error",
5885            &[append_order_event(1, &OrderEventAny::Submitted(submitted))],
5886        );
5887        let mut cache = Cache::default();
5888
5889        let err = replay_cache_snapshot_tail(&mut cache, &reader).expect_err("apply error");
5890
5891        match err {
5892            CacheReplayError::Apply {
5893                seq,
5894                payload_type,
5895                message,
5896            } => {
5897                assert_eq!(seq, 1);
5898                assert_eq!(payload_type, PAYLOAD_TYPE_ORDER_SUBMITTED);
5899                assert!(
5900                    message.contains("not found"),
5901                    "message should include cache apply failure: {message}",
5902                );
5903            }
5904            other => panic!("expected Apply, was {other:?}"),
5905        }
5906    }
5907
5908    #[rstest]
5909    fn restore_cache_from_sealed_run_restores_snapshot_and_tail() {
5910        let tmp = TempDir::new().expect("tempdir");
5911        let run_id = "sealed-replay";
5912        let instance_id = "trader-001";
5913        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5914        let fill = OrderFilledSpec::builder()
5915            .instrument_id(instrument.id())
5916            .position_id(PositionId::from("P-SEALED-REPLAY-1"))
5917            .build();
5918        let position = Position::new(&instrument, fill);
5919        let mut snapshot_cache = Cache::default();
5920        let snapshot_ref = snapshot_cache
5921            .snapshot_position_encoded(&position)
5922            .expect("snapshot position");
5923        let anchored_state = cash_account_state_million_usd("100 USD", "0 USD", "100 USD");
5924        let replayed_state = cash_account_state_million_usd("200 USD", "0 USD", "200 USD");
5925
5926        {
5927            let mut backend = RedbBackend::new(tmp.path().to_path_buf());
5928            backend.open_run(manifest(run_id)).expect("open run");
5929            backend
5930                .append_batch(&[append_account_state(1, &anchored_state)])
5931                .expect("append anchored state");
5932            backend
5933                .record_snapshot_anchor(SnapshotAnchor::new(
5934                    1,
5935                    snapshot_ref.blob_ref.clone(),
5936                    compute_snapshot_content_hash(snapshot_ref.blob.as_ref()),
5937                ))
5938                .expect("record snapshot anchor");
5939            backend
5940                .append_batch(&[append_account_state(2, &replayed_state)])
5941                .expect("append replay tail");
5942            backend.seal(RunStatus::Ended).expect("seal run");
5943        }
5944
5945        let mut cache = Cache::default();
5946        cache
5947            .add(&snapshot_ref.blob_ref, snapshot_ref.blob.clone())
5948            .expect("seed snapshot blob");
5949
5950        let report = restore_cache_from_sealed_run(
5951            &mut cache,
5952            tmp.path().to_path_buf(),
5953            instance_id,
5954            run_id,
5955        )
5956        .expect("restore sealed run");
5957
5958        let frames = cache
5959            .position_snapshot_bytes(&position.id)
5960            .expect("restored position snapshot");
5961        let account = cache
5962            .account_owned(&replayed_state.account_id)
5963            .expect("replayed account");
5964
5965        assert_eq!(report.manifest.run_id, run_id);
5966        assert_eq!(report.manifest.status, RunStatus::Ended);
5967        assert_eq!(report.cache.plan.from_seq, 2);
5968        assert_eq!(report.cache.applied_entries, 1);
5969        assert_eq!(report.cache.ignored_entries, 0);
5970        assert_eq!(frames.len(), 1);
5971        assert_eq!(frames[0].as_slice(), snapshot_ref.blob.as_ref());
5972        assert_eq!(account.events(), vec![replayed_state]);
5973    }
5974
5975    #[rstest]
5976    fn restore_cache_from_sealed_run_rejects_snapshot_hash_mismatch() {
5977        let tmp = TempDir::new().expect("tempdir");
5978        let run_id = "sealed-replay-bad-snapshot";
5979        let instance_id = "trader-001";
5980        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5981        let fill = OrderFilledSpec::builder()
5982            .instrument_id(instrument.id())
5983            .position_id(PositionId::from("P-SEALED-REPLAY-BAD-SNAPSHOT-1"))
5984            .build();
5985        let position = Position::new(&instrument, fill);
5986        let mut snapshot_cache = Cache::default();
5987        let snapshot_ref = snapshot_cache
5988            .snapshot_position_encoded(&position)
5989            .expect("snapshot position");
5990
5991        {
5992            let mut backend = RedbBackend::new(tmp.path().to_path_buf());
5993            backend.open_run(manifest(run_id)).expect("open run");
5994            backend
5995                .record_snapshot_anchor(SnapshotAnchor::new(
5996                    0,
5997                    snapshot_ref.blob_ref.clone(),
5998                    compute_snapshot_content_hash(snapshot_ref.blob.as_ref()),
5999                ))
6000                .expect("record snapshot anchor");
6001            backend.seal(RunStatus::Ended).expect("seal run");
6002        }
6003
6004        let mut cache = Cache::default();
6005        cache
6006            .add(
6007                &snapshot_ref.blob_ref,
6008                Bytes::from_static(b"tampered snapshot"),
6009            )
6010            .expect("seed tampered snapshot blob");
6011
6012        let err = restore_cache_from_sealed_run(
6013            &mut cache,
6014            tmp.path().to_path_buf(),
6015            instance_id,
6016            run_id,
6017        )
6018        .expect_err("hash mismatch");
6019
6020        match err {
6021            CacheReplayError::SnapshotRestore { blob_ref, message } => {
6022                assert_eq!(blob_ref, snapshot_ref.blob_ref);
6023                assert!(
6024                    message.contains("content_hash mismatch"),
6025                    "message should explain hash mismatch: {message}",
6026                );
6027            }
6028            other => panic!("expected SnapshotRestore, was {other:?}"),
6029        }
6030    }
6031
6032    #[rstest]
6033    fn open_event_store_replay_source_rejects_running_run() {
6034        let tmp = TempDir::new().expect("tempdir");
6035        let run_id = "running-replay";
6036        {
6037            let mut backend = RedbBackend::new(tmp.path().to_path_buf());
6038            backend.open_run(manifest(run_id)).expect("open run");
6039        }
6040
6041        let err = open_event_store_replay_source(tmp.path().to_path_buf(), "trader-001", run_id)
6042            .expect_err("running source must fail");
6043
6044        assert!(
6045            err.to_string().contains("not sealed"),
6046            "error should name sealed-run requirement: {err}",
6047        );
6048    }
6049
6050    #[rstest]
6051    fn validate_event_store_replay_source_rejects_quarantined_run() {
6052        let tmp = TempDir::new().expect("tempdir");
6053        let run_id = "quarantined-replay";
6054        {
6055            let mut backend = RedbBackend::new(tmp.path().to_path_buf());
6056            backend.open_run(manifest(run_id)).expect("open run");
6057            backend
6058                .append_batch(&[append_payload(1, "RunStarted", Bytes::new())])
6059                .expect("append");
6060            backend.seal(RunStatus::Quarantined).expect("seal run");
6061        }
6062
6063        let err =
6064            validate_event_store_replay_source(tmp.path().to_path_buf(), "trader-001", run_id)
6065                .expect_err("quarantined source must fail");
6066
6067        assert!(
6068            err.to_string().contains("quarantined"),
6069            "error should reject quarantined replay sources: {err}",
6070        );
6071    }
6072}