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_greeks",
2717            CacheMutationRecoveryClass::MissingLiveRecovery,
2718            &[],
2719        ),
2720        cache_mutation(
2721            "add_option_greeks",
2722            CacheMutationRecoveryClass::MissingLiveRecovery,
2723            &[],
2724        ),
2725        cache_mutation(
2726            "add_yield_curve",
2727            CacheMutationRecoveryClass::MissingLiveRecovery,
2728            &[],
2729        ),
2730        cache_mutation(
2731            "add_currency",
2732            CacheMutationRecoveryClass::SnapshotOwned,
2733            &[],
2734        ),
2735        cache_mutation(
2736            "add_instrument",
2737            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2738            &[
2739                PAYLOAD_TYPE_INSTRUMENT_RESPONSE,
2740                PAYLOAD_TYPE_INSTRUMENTS_RESPONSE,
2741            ],
2742        ),
2743        cache_mutation(
2744            "add_synthetic",
2745            CacheMutationRecoveryClass::SnapshotOwned,
2746            &[],
2747        ),
2748        cache_mutation(
2749            "add_account",
2750            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2751            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2752        ),
2753        cache_mutation(
2754            "add_venue_order_id",
2755            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2756            &[PAYLOAD_TYPE_ORDER_ACCEPTED, PAYLOAD_TYPE_ORDER_UPDATED],
2757        ),
2758        cache_mutation(
2759            // Replay restores the current generation only; superseded reverse aliases are
2760            // re-registered by live mass-status reconciliation.
2761            "index_venue_order_id",
2762            CacheMutationRecoveryClass::MissingLiveRecovery,
2763            &[],
2764        ),
2765        cache_mutation(
2766            "add_order",
2767            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2768            &[PAYLOAD_TYPE_ORDER_INITIALIZED],
2769        ),
2770        cache_mutation(
2771            // Cache databases persist the resolved client index, but current EventStore
2772            // command payloads do not carry the client selected by runtime routing.
2773            "claim_order_clients",
2774            CacheMutationRecoveryClass::MissingLiveRecovery,
2775            &[],
2776        ),
2777        cache_mutation(
2778            "add_order_list",
2779            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2780            &[PAYLOAD_TYPE_SUBMIT_ORDER_LIST],
2781        ),
2782        cache_mutation(
2783            "add_position_id",
2784            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2785            &[
2786                PAYLOAD_TYPE_ORDER_FILLED,
2787                PAYLOAD_TYPE_POSITION_OPENED,
2788                PAYLOAD_TYPE_POSITION_CHANGED,
2789                PAYLOAD_TYPE_POSITION_CLOSED,
2790            ],
2791        ),
2792        cache_mutation(
2793            "add_position",
2794            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2795            &[PAYLOAD_TYPE_ORDER_FILLED],
2796        ),
2797        cache_mutation(
2798            "add_position_without_order",
2799            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2800            &[PAYLOAD_TYPE_ORDER_FILLED],
2801        ),
2802        cache_mutation(
2803            "replace_position",
2804            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2805            &[PAYLOAD_TYPE_ORDER_FILLED],
2806        ),
2807        cache_mutation(
2808            "update_account",
2809            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2810            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2811        ),
2812        cache_mutation(
2813            "take_account",
2814            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2815            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2816        ),
2817        cache_mutation(
2818            "cache_account_owned",
2819            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2820            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2821        ),
2822        cache_mutation(
2823            "update_account_owned",
2824            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2825            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2826        ),
2827        cache_mutation(
2828            "update_account_state",
2829            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2830            &[PAYLOAD_TYPE_ACCOUNT_STATE],
2831        ),
2832        cache_mutation(
2833            "replace_order",
2834            CacheMutationRecoveryClass::ForensicOnly,
2835            &[
2836                PAYLOAD_TYPE_ORDER_STATUS_REPORT,
2837                PAYLOAD_TYPE_ORDER_WITH_FILLS,
2838                PAYLOAD_TYPE_EXECUTION_MASS_STATUS,
2839            ],
2840        ),
2841        cache_mutation(
2842            "update_order",
2843            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2844            &[
2845                PAYLOAD_TYPE_ORDER_DENIED,
2846                PAYLOAD_TYPE_ORDER_EMULATED,
2847                PAYLOAD_TYPE_ORDER_RELEASED,
2848                PAYLOAD_TYPE_ORDER_SUBMITTED,
2849                PAYLOAD_TYPE_ORDER_ACCEPTED,
2850                PAYLOAD_TYPE_ORDER_REJECTED,
2851                PAYLOAD_TYPE_ORDER_CANCELED,
2852                PAYLOAD_TYPE_ORDER_EXPIRED,
2853                PAYLOAD_TYPE_ORDER_TRIGGERED,
2854                PAYLOAD_TYPE_ORDER_PENDING_UPDATE,
2855                PAYLOAD_TYPE_ORDER_PENDING_CANCEL,
2856                PAYLOAD_TYPE_ORDER_MODIFY_DENIED,
2857                PAYLOAD_TYPE_ORDER_MODIFY_REJECTED,
2858                PAYLOAD_TYPE_ORDER_CANCEL_DENIED,
2859                PAYLOAD_TYPE_ORDER_CANCEL_REJECTED,
2860                PAYLOAD_TYPE_ORDER_UPDATED,
2861                PAYLOAD_TYPE_ORDER_FILLED,
2862                PAYLOAD_TYPE_ORDER_FILL_VOIDED,
2863            ],
2864        ),
2865        cache_mutation(
2866            "update_order_pending_cancel_local",
2867            CacheMutationRecoveryClass::MissingLiveRecovery,
2868            &[],
2869        ),
2870        cache_mutation(
2871            "update_position",
2872            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2873            &[
2874                PAYLOAD_TYPE_ORDER_FILLED,
2875                PAYLOAD_TYPE_ORDER_FILL_VOIDED,
2876                PAYLOAD_TYPE_POSITION_OPENED,
2877                PAYLOAD_TYPE_POSITION_CHANGED,
2878                PAYLOAD_TYPE_POSITION_CLOSED,
2879                PAYLOAD_TYPE_POSITION_ADJUSTED,
2880            ],
2881        ),
2882        cache_mutation(
2883            "update_position_from_fill",
2884            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2885            &[PAYLOAD_TYPE_ORDER_FILLED],
2886        ),
2887        cache_mutation(
2888            "update_position_from_instrument_close",
2889            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2890            &[PAYLOAD_TYPE_INSTRUMENT_CLOSE],
2891        ),
2892        cache_mutation(
2893            "update_position_from_adjustment",
2894            CacheMutationRecoveryClass::EventStoreCapturedAndReplayed,
2895            &[PAYLOAD_TYPE_POSITION_ADJUSTED],
2896        ),
2897        cache_mutation(
2898            // Rolls back an adjustment whose event was never published, so replay never applies it
2899            "revert_position_adjustment",
2900            CacheMutationRecoveryClass::MissingLiveRecovery,
2901            &[],
2902        ),
2903        cache_mutation(
2904            "snapshot_position",
2905            CacheMutationRecoveryClass::SnapshotOwned,
2906            &[],
2907        ),
2908        cache_mutation(
2909            "snapshot_position_encoded",
2910            CacheMutationRecoveryClass::SnapshotOwned,
2911            &[],
2912        ),
2913        cache_mutation(
2914            "snapshot_position_state",
2915            CacheMutationRecoveryClass::SnapshotOwned,
2916            &[],
2917        ),
2918        cache_mutation(
2919            "load_snapshot_blob",
2920            CacheMutationRecoveryClass::SnapshotOwned,
2921            &[],
2922        ),
2923        cache_mutation(
2924            "restore_snapshot_blob",
2925            CacheMutationRecoveryClass::SnapshotOwned,
2926            &[],
2927        ),
2928        cache_mutation(
2929            "mark_orders_dispatched",
2930            CacheMutationRecoveryClass::MissingLiveRecovery,
2931            &[],
2932        ),
2933        cache_mutation(
2934            "clear_order_dispatch",
2935            CacheMutationRecoveryClass::MissingLiveRecovery,
2936            &[],
2937        ),
2938        cache_mutation(
2939            "order_mut",
2940            CacheMutationRecoveryClass::MissingLiveRecovery,
2941            &[],
2942        ),
2943        cache_mutation(
2944            "position_mut",
2945            CacheMutationRecoveryClass::MissingLiveRecovery,
2946            &[],
2947        ),
2948        cache_mutation(
2949            "order_book_mut",
2950            CacheMutationRecoveryClass::ForensicOnly,
2951            &[
2952                PAYLOAD_TYPE_BOOK_DELTAS_RESPONSE,
2953                PAYLOAD_TYPE_BOOK_DEPTH_RESPONSE,
2954            ],
2955        ),
2956        cache_mutation(
2957            "own_order_book_mut",
2958            CacheMutationRecoveryClass::SnapshotOwned,
2959            &[],
2960        ),
2961        cache_mutation(
2962            "set_mark_xrate",
2963            CacheMutationRecoveryClass::MissingLiveRecovery,
2964            &[],
2965        ),
2966        cache_mutation(
2967            "clear_mark_xrate",
2968            CacheMutationRecoveryClass::MissingLiveRecovery,
2969            &[],
2970        ),
2971        cache_mutation(
2972            "clear_mark_xrates",
2973            CacheMutationRecoveryClass::MissingLiveRecovery,
2974            &[],
2975        ),
2976        cache_mutation(
2977            "account_mut",
2978            CacheMutationRecoveryClass::MissingLiveRecovery,
2979            &[],
2980        ),
2981        cache_mutation(
2982            "update_own_order_book",
2983            CacheMutationRecoveryClass::SnapshotOwned,
2984            &[],
2985        ),
2986        cache_mutation(
2987            "force_remove_from_own_order_book",
2988            CacheMutationRecoveryClass::SnapshotOwned,
2989            &[],
2990        ),
2991        cache_mutation(
2992            "audit_own_order_books",
2993            CacheMutationRecoveryClass::SnapshotOwned,
2994            &[],
2995        ),
2996    ];
2997
2998    const CACHE_MUTATION_EXCLUSIONS: &[&str] = &["check_integrity"];
2999
3000    const fn cache_mutation(
3001        method: &'static str,
3002        class: CacheMutationRecoveryClass,
3003        payload_types: &'static [&'static str],
3004    ) -> CacheMutationCoverage {
3005        CacheMutationCoverage {
3006            method,
3007            class,
3008            payload_types,
3009        }
3010    }
3011
3012    fn cache_public_methods() -> AHashSet<&'static str> {
3013        collect_cache_public_methods(false)
3014    }
3015
3016    fn cache_public_mutable_methods() -> AHashSet<&'static str> {
3017        collect_cache_public_methods(true)
3018    }
3019
3020    /// Every file carrying an `impl Cache` block, since `include_str!` cannot glob a directory.
3021    /// Add a file here when the cache module is split further, or its methods drop out of this
3022    /// classification guard.
3023    const CACHE_IMPL_SOURCES: &[&str] = &[
3024        include_str!("../../common/src/cache/mod.rs"),
3025        include_str!("../../common/src/cache/position.rs"),
3026    ];
3027
3028    fn collect_cache_public_methods(require_mut_self: bool) -> AHashSet<&'static str> {
3029        let mut methods = AHashSet::new();
3030        let mut pending_name: Option<&'static str> = None;
3031        let mut pending_signature = String::new();
3032
3033        for line in CACHE_IMPL_SOURCES.iter().flat_map(|source| source.lines()) {
3034            let trimmed = line.trim_start();
3035
3036            if pending_name.is_none() {
3037                let Some(rest) = trimmed
3038                    .strip_prefix("pub fn ")
3039                    .or_else(|| trimmed.strip_prefix("pub async fn "))
3040                else {
3041                    continue;
3042                };
3043                pending_name = rest.split('(').next();
3044                pending_signature.clear();
3045                pending_signature.push_str(trimmed);
3046            } else {
3047                pending_signature.push(' ');
3048                pending_signature.push_str(trimmed);
3049            }
3050
3051            if trimmed.contains('{') {
3052                if let Some(name) = pending_name.take()
3053                    && (!require_mut_self || pending_signature.contains("&mut self"))
3054                {
3055                    methods.insert(name);
3056                }
3057                pending_signature.clear();
3058            }
3059        }
3060
3061        methods
3062    }
3063
3064    fn sorted_missing_methods<'a>(
3065        actual: &'a AHashSet<&'static str>,
3066        classified: &'a AHashSet<&'static str>,
3067    ) -> Vec<&'static str> {
3068        let mut missing: Vec<_> = actual
3069            .iter()
3070            .copied()
3071            .filter(|method| !classified.contains(method))
3072            .collect();
3073        missing.sort_unstable();
3074        missing
3075    }
3076
3077    fn sorted_stale_methods<'a>(
3078        classified: &'a AHashSet<&'static str>,
3079        actual: &'a AHashSet<&'static str>,
3080    ) -> Vec<&'static str> {
3081        let mut stale: Vec<_> = classified
3082            .iter()
3083            .copied()
3084            .filter(|method| !actual.contains(method))
3085            .collect();
3086        stale.sort_unstable();
3087        stale
3088    }
3089
3090    #[rstest]
3091    fn catalog_replay_inputs_join_event_entries_with_selected_catalog_slice() {
3092        let reader = reader_with_entries(
3093            "run-catalog",
3094            &[
3095                append_payload_with_ts(1, 120, "RunStarted", Bytes::from_static(b"started")),
3096                append_payload_with_ts(2, 100, "SubmitOrder", Bytes::from_static(b"submit")),
3097            ],
3098        );
3099        let record = catalog_quote_record(110);
3100        let mut catalog = FakeReplayCatalog::new(
3101            CatalogSliceCoverage::from_files(vec!["quotes/AUDUSD.SIM/100_120.parquet".into()]),
3102            vec![record.clone()],
3103        );
3104
3105        let plan = plan_catalog_replay_inputs(
3106            &reader,
3107            &mut catalog,
3108            ReplaySeqRange::new(1, 2),
3109            &[CatalogSliceSelector::new("quotes").with_identifier("AUD/USD.SIM")],
3110        )
3111        .expect("plan catalog replay");
3112
3113        assert_eq!(plan.event_range, Some(ReplaySeqRange::new(1, 2)));
3114        assert_eq!(plan.event_count, 2);
3115        assert_eq!(
3116            plan.event_time_range,
3117            Some(ReplayTimeRange::new(
3118                UnixNanos::from(100),
3119                UnixNanos::from(120),
3120            )),
3121        );
3122        assert!(!plan.catalog_slices[0].is_missing());
3123        assert_eq!(catalog.plan_queries.len(), 1);
3124        assert_eq!(catalog.plan_queries[0].data_cls, "quotes");
3125        assert_eq!(
3126            catalog.plan_queries[0].identifiers,
3127            vec!["AUD/USD.SIM".to_string()],
3128        );
3129        assert_eq!(catalog.plan_queries[0].start, UnixNanos::from(100));
3130        assert_eq!(catalog.plan_queries[0].end, UnixNanos::from(120));
3131
3132        let loaded =
3133            load_catalog_replay_inputs(&reader, &mut catalog, &plan).expect("load catalog");
3134        let seqs: Vec<_> = loaded.entries.iter().map(|entry| entry.seq).collect();
3135
3136        assert_eq!(seqs, vec![1, 2]);
3137        assert_eq!(loaded.catalog_slices.len(), 1);
3138        assert_eq!(loaded.catalog_slices[0].records, vec![record]);
3139        assert_eq!(catalog.load_plans.len(), 1);
3140    }
3141
3142    #[rstest]
3143    fn catalog_plan_marks_missing_catalog_slice() {
3144        let reader = reader_with_entries(
3145            "run-missing-catalog",
3146            &[append_payload_with_ts(
3147                1,
3148                1_000,
3149                "RunStarted",
3150                Bytes::from_static(b"started"),
3151            )],
3152        );
3153        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3154
3155        let plan = plan_catalog_replay_inputs(
3156            &reader,
3157            &mut catalog,
3158            ReplaySeqRange::new(1, 1),
3159            &[CatalogSliceSelector::new("trades").with_identifier("AUD/USD.SIM")],
3160        )
3161        .expect("plan catalog replay");
3162        let missing = plan.missing_catalog_slices();
3163
3164        assert_eq!(missing.len(), 1);
3165        assert_eq!(missing[0].query.data_cls, "trades");
3166        assert_eq!(
3167            missing[0].query.identifiers,
3168            vec!["AUD/USD.SIM".to_string()],
3169        );
3170        assert_eq!(missing[0].query.start, UnixNanos::from(1_000));
3171        assert_eq!(missing[0].query.end, UnixNanos::from(1_000));
3172    }
3173
3174    #[rstest]
3175    fn required_missing_catalog_slice_rejects_load() {
3176        let reader = reader_with_entries(
3177            "run-required-missing",
3178            &[append_payload_with_ts(
3179                1,
3180                1_000,
3181                "RunStarted",
3182                Bytes::from_static(b"started"),
3183            )],
3184        );
3185        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3186        let plan = plan_catalog_replay_inputs(
3187            &reader,
3188            &mut catalog,
3189            ReplaySeqRange::new(1, 1),
3190            &[CatalogSliceSelector::new("quotes")
3191                .with_identifier("AUD/USD.SIM")
3192                .require_coverage()],
3193        )
3194        .expect("plan missing slice");
3195
3196        let err = load_catalog_replay_inputs(&reader, &mut catalog, &plan)
3197            .expect_err("required missing slice must fail");
3198
3199        match err {
3200            ReplayInputError::MissingCatalogSlice {
3201                data_cls,
3202                identifiers,
3203            } => {
3204                assert_eq!(data_cls, "quotes");
3205                assert_eq!(identifiers, vec!["AUD/USD.SIM".to_string()]);
3206            }
3207            other => panic!("expected MissingCatalogSlice, was {other:?}"),
3208        }
3209    }
3210
3211    #[rstest]
3212    fn optional_missing_catalog_slice_loads_as_empty_without_catalog_load() {
3213        let reader = reader_with_entries(
3214            "run-optional-missing",
3215            &[append_payload_with_ts(
3216                1,
3217                1_000,
3218                "RunStarted",
3219                Bytes::from_static(b"started"),
3220            )],
3221        );
3222        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3223        let plan = plan_catalog_replay_inputs(
3224            &reader,
3225            &mut catalog,
3226            ReplaySeqRange::new(1, 1),
3227            &[CatalogSliceSelector::new("quotes").with_identifier("AUD/USD.SIM")],
3228        )
3229        .expect("plan optional missing slice");
3230
3231        let loaded =
3232            load_catalog_replay_inputs(&reader, &mut catalog, &plan).expect("load optional");
3233
3234        assert_eq!(loaded.catalog_slices.len(), 1);
3235        assert!(loaded.catalog_slices[0].plan.is_missing());
3236        assert!(loaded.catalog_slices[0].records.is_empty());
3237        assert!(catalog.load_plans.is_empty());
3238    }
3239
3240    #[rstest]
3241    fn catalog_joined_planner_rejects_empty_catalog_selection() {
3242        let reader = reader_with_entries(
3243            "run-empty-selection",
3244            &[append_payload_with_ts(
3245                1,
3246                1_000,
3247                "RunStarted",
3248                Bytes::from_static(b"started"),
3249            )],
3250        );
3251        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3252
3253        let err = plan_catalog_replay_inputs(&reader, &mut catalog, ReplaySeqRange::new(1, 1), &[])
3254            .expect_err("empty catalog selection must fail");
3255
3256        match err {
3257            ReplayInputError::EmptyCatalogSelection => {}
3258            other => panic!("expected EmptyCatalogSelection, was {other:?}"),
3259        }
3260        assert!(catalog.plan_queries.is_empty());
3261    }
3262
3263    #[rstest]
3264    fn catalog_selector_explicit_time_bounds_override_event_span() {
3265        let reader = reader_with_entries(
3266            "run-explicit-bounds",
3267            &[append_payload_with_ts(
3268                1,
3269                1_000,
3270                "RunStarted",
3271                Bytes::from_static(b"started"),
3272            )],
3273        );
3274        let mut catalog = FakeReplayCatalog::new(
3275            CatalogSliceCoverage::from_files(vec!["bars/AUDUSD.SIM/900_950.parquet".into()]),
3276            Vec::new(),
3277        );
3278
3279        let plan = plan_catalog_replay_inputs(
3280            &reader,
3281            &mut catalog,
3282            ReplaySeqRange::new(1, 1),
3283            &[CatalogSliceSelector::new("bars")
3284                .with_identifier("AUD/USD.SIM-1-MINUTE-BID-EXTERNAL")
3285                .with_time_bounds(UnixNanos::from(900), UnixNanos::from(950))],
3286        )
3287        .expect("plan explicit bounds");
3288
3289        assert_eq!(plan.catalog_slices[0].query.start, UnixNanos::from(900));
3290        assert_eq!(plan.catalog_slices[0].query.end, UnixNanos::from(950));
3291        assert_eq!(catalog.plan_queries[0].start, UnixNanos::from(900));
3292        assert_eq!(catalog.plan_queries[0].end, UnixNanos::from(950));
3293    }
3294
3295    #[rstest]
3296    fn catalog_replay_inputs_load_catalog_records() {
3297        let reader = reader_with_entries(
3298            "run-catalog-load",
3299            &[
3300                append_payload_with_ts(1, 100, "RunStarted", Bytes::from_static(b"started")),
3301                append_payload_with_ts(2, 110, "OrderFilled", Bytes::from_static(b"filled")),
3302            ],
3303        );
3304        let record = catalog_trade_record(105);
3305        let mut catalog = FakeReplayCatalog::new(
3306            CatalogSliceCoverage::from_files(vec!["trades/AUDUSD.SIM/100_110.parquet".into()]),
3307            vec![record.clone()],
3308        );
3309        let plan = plan_catalog_replay_inputs(
3310            &reader,
3311            &mut catalog,
3312            ReplaySeqRange::new(1, 2),
3313            &[CatalogSliceSelector::new("trades").with_identifier("AUD/USD.SIM")],
3314        )
3315        .expect("plan catalog replay");
3316
3317        assert_eq!(
3318            plan.catalog_slices[0].query.identifiers_option(),
3319            Some(vec!["AUD/USD.SIM".to_string()]),
3320        );
3321
3322        let loaded =
3323            load_catalog_replay_inputs(&reader, &mut catalog, &plan).expect("load catalog");
3324        let seqs: Vec<_> = loaded.entries.iter().map(|entry| entry.seq).collect();
3325
3326        assert_eq!(seqs, vec![1, 2]);
3327        assert_eq!(loaded.catalog_slices[0].records, vec![record]);
3328        assert_eq!(catalog.load_plans.len(), 1);
3329    }
3330
3331    #[rstest]
3332    fn unbounded_catalog_selector_rejects_empty_event_scan() {
3333        let reader = reader_with_entries("run-empty", &[]);
3334        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3335
3336        let err = plan_catalog_replay_inputs(
3337            &reader,
3338            &mut catalog,
3339            ReplaySeqRange::new(1, 10),
3340            &[CatalogSliceSelector::new("quotes")],
3341        )
3342        .expect_err("empty replay scan must need explicit bounds");
3343
3344        match err {
3345            ReplayInputError::MissingCatalogTimeBounds { data_cls } => {
3346                assert_eq!(data_cls, "quotes");
3347            }
3348            other => panic!("expected MissingCatalogTimeBounds, was {other:?}"),
3349        }
3350    }
3351
3352    #[rstest]
3353    fn invalid_catalog_time_bounds_are_rejected_before_catalog_access() {
3354        let reader = reader_with_entries(
3355            "run-invalid-bounds",
3356            &[append_payload_with_ts(
3357                1,
3358                1_000,
3359                "RunStarted",
3360                Bytes::from_static(b"started"),
3361            )],
3362        );
3363        let mut catalog = FakeReplayCatalog::new(CatalogSliceCoverage::default(), Vec::new());
3364
3365        let err = plan_catalog_replay_inputs(
3366            &reader,
3367            &mut catalog,
3368            ReplaySeqRange::new(1, 1),
3369            &[CatalogSliceSelector::new("quotes")
3370                .with_time_bounds(UnixNanos::from(200), UnixNanos::from(100))],
3371        )
3372        .expect_err("invalid catalog bounds must fail");
3373
3374        match err {
3375            ReplayInputError::InvalidCatalogTimeRange {
3376                data_cls,
3377                start,
3378                end,
3379            } => {
3380                assert_eq!(data_cls, "quotes");
3381                assert_eq!(start, 200);
3382                assert_eq!(end, 100);
3383            }
3384            other => panic!("expected InvalidCatalogTimeRange, was {other:?}"),
3385        }
3386        assert!(catalog.plan_queries.is_empty());
3387    }
3388
3389    #[rstest]
3390    fn forensics_replay_inputs_do_not_require_catalog_source() {
3391        let reader = reader_with_entries(
3392            "run-forensics",
3393            &[append_payload_with_ts(
3394                1,
3395                500,
3396                "RunStarted",
3397                Bytes::from_static(b"started"),
3398            )],
3399        );
3400
3401        let plan = plan_forensics_replay_inputs(&reader, ReplaySeqRange::new(1, 1))
3402            .expect("plan forensics");
3403        let loaded = load_forensics_replay_inputs(&reader, &plan).expect("load forensics");
3404
3405        assert!(plan.catalog_slices.is_empty());
3406        assert_eq!(loaded.entries.len(), 1);
3407        assert!(loaded.catalog_slices.is_empty());
3408    }
3409
3410    #[rstest]
3411    #[case::zero_start(ReplaySeqRange::new(0, 1), "seq is 1-based")]
3412    #[case::from_after_to(ReplaySeqRange::new(2, 1), "from_seq exceeds to_seq")]
3413    fn invalid_replay_seq_range_rejected(
3414        #[case] range: ReplaySeqRange,
3415        #[case] expected_message: &str,
3416    ) {
3417        let reader = reader_with_entries("run-invalid-seq", &[]);
3418
3419        let err =
3420            plan_forensics_replay_inputs(&reader, range).expect_err("invalid seq range must fail");
3421
3422        match err {
3423            ReplayInputError::InvalidSeqRange {
3424                from_seq,
3425                to_seq,
3426                message,
3427            } => {
3428                assert_eq!(from_seq, range.from_seq);
3429                assert_eq!(to_seq, range.to_seq);
3430                assert_eq!(message, expected_message);
3431            }
3432            other => panic!("expected InvalidSeqRange, was {other:?}"),
3433        }
3434    }
3435
3436    #[rstest]
3437    fn replay_restores_snapshot_before_applying_tail() {
3438        let (reader, replayed) = reader_with_anchor(1);
3439        let mut cache = Cache::default();
3440        let restored = cash_account_state_million_usd("100 USD", "0 USD", "100 USD");
3441        let restored_id = restored.account_id;
3442
3443        let report =
3444            restore_cache_snapshot_and_replay_tail(&mut cache, &reader, |cache, anchor| {
3445                assert_eq!(anchor.expect("anchor").high_watermark, 1);
3446                let account = AccountAny::from_events(std::slice::from_ref(&restored))
3447                    .map_err(|e| CacheReplayError::snapshot_restore(anchor.unwrap(), e))?;
3448                cache
3449                    .add_account(account)
3450                    .map_err(|e| CacheReplayError::snapshot_restore(anchor.unwrap(), e))
3451            })
3452            .expect("replay");
3453
3454        let account = cache.account_owned(&restored_id).expect("account restored");
3455        let events = account.events();
3456
3457        assert_eq!(report.plan.from_seq, 2);
3458        assert_eq!(report.applied_entries, 1);
3459        assert_eq!(report.ignored_entries, 0);
3460        assert_eq!(events, vec![restored, replayed]);
3461    }
3462
3463    #[rstest]
3464    fn replay_does_not_apply_entries_at_or_below_anchor_watermark() {
3465        let (reader, _) = reader_with_anchor(2);
3466        let mut cache = Cache::default();
3467        let restored = cash_account_state_million_usd("100 USD", "0 USD", "100 USD");
3468        let restored_id = restored.account_id;
3469
3470        let report =
3471            restore_cache_snapshot_and_replay_tail(&mut cache, &reader, |cache, anchor| {
3472                assert_eq!(anchor.expect("anchor").high_watermark, 2);
3473                let account = AccountAny::from_events(std::slice::from_ref(&restored))
3474                    .map_err(|e| CacheReplayError::snapshot_restore(anchor.unwrap(), e))?;
3475                cache
3476                    .add_account(account)
3477                    .map_err(|e| CacheReplayError::snapshot_restore(anchor.unwrap(), e))
3478            })
3479            .expect("replay");
3480
3481        let account = cache.account_owned(&restored_id).expect("account restored");
3482
3483        assert!(report.plan.is_empty());
3484        assert_eq!(report.applied_entries, 0);
3485        assert_eq!(report.ignored_entries, 0);
3486        assert_eq!(account.events(), vec![restored]);
3487    }
3488
3489    #[rstest]
3490    fn replay_from_start_applies_account_state_without_bus_publish() {
3491        let state = cash_account_state_million_usd("100 USD", "0 USD", "100 USD");
3492        let account_id = AccountId::from("SIM-001");
3493        let bus_calls = Rc::new(Cell::new(0));
3494        msgbus::set_bus_tap(Rc::new(CountingTap::new(Rc::clone(&bus_calls))));
3495        let _guard = BusTapGuard;
3496        let mut backend = MemoryBackend::new();
3497        backend.open_run(manifest("run-replay")).expect("open");
3498        backend
3499            .append_batch(&[append_account_state(1, &state)])
3500            .expect("append");
3501        let reader = EventStoreReader::new(backend);
3502        let mut cache = Cache::default();
3503
3504        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
3505        let account = cache.account_owned(&account_id).expect("account replayed");
3506
3507        assert_eq!(report.plan.anchor, None);
3508        assert_eq!(report.plan.from_seq, 1);
3509        assert_eq!(report.applied_entries, 1);
3510        assert_eq!(bus_calls.get(), 0);
3511        assert_eq!(account.last_event(), Some(state));
3512        assert_eq!(account.base_currency(), Some(Currency::USD()));
3513    }
3514
3515    #[rstest]
3516    fn unsupported_payload_is_ignored() {
3517        let mut backend = MemoryBackend::new();
3518        backend.open_run(manifest("run-replay")).expect("open");
3519        backend
3520            .append_batch(&[append_payload(
3521                1,
3522                "RunStarted",
3523                Bytes::copy_from_slice(UUID4::new().to_string().as_bytes()),
3524            )])
3525            .expect("append");
3526        let reader = EventStoreReader::new(backend);
3527        let mut cache = Cache::default();
3528
3529        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
3530
3531        assert_eq!(report.applied_entries, 0);
3532        assert_eq!(report.ignored_entries, 1);
3533    }
3534
3535    #[rstest]
3536    fn historical_envelope_replays_payload_without_actor_completion_state() {
3537        use nautilus_common::messages::data::{DataResponse, DataResponseEnvelope};
3538        let instrument_id = InstrumentId::from("AUD/USD.SIM");
3539
3540        let quote = QuoteTick::new(
3541            instrument_id,
3542            Price::from("1.00000"),
3543            Price::from("1.00010"),
3544            Quantity::from("11"),
3545            Quantity::from("13"),
3546            UnixNanos::from(17),
3547            UnixNanos::from(19),
3548        );
3549        let root = UUID4::new();
3550
3551        let response = QuotesResponse::new(
3552            root,
3553            ClientId::from("SOURCE"),
3554            instrument_id,
3555            vec![quote],
3556            None,
3557            None,
3558            UnixNanos::from(23),
3559            None,
3560        );
3561        let envelope =
3562            DataResponseEnvelope::new(DataResponse::Quotes(response), false, Some(UUID4::new()));
3563        let registry = crate::capture::builtins::default_registry();
3564        let (tag, encoded) = registry.encode(&envelope).unwrap().unwrap();
3565        let entry = append_payload(1, tag.as_str(), encoded.payload).entry;
3566        let mut cache = Cache::default();
3567        assert!(apply_cache_replay_entry(&mut cache, &entry).unwrap());
3568        let terminal = DataResponseEnvelope::terminal(root, Some("later source failed".to_owned()));
3569        let (tag, encoded) = registry.encode(&terminal).unwrap().unwrap();
3570        let entry = append_payload(2, tag.as_str(), encoded.payload).entry;
3571        assert!(!apply_cache_replay_entry(&mut cache, &entry).unwrap());
3572        assert_eq!(cache.quote(&instrument_id), Some(&quote));
3573    }
3574
3575    #[rstest]
3576    fn default_capture_payload_types_are_classified_for_cache_replay() {
3577        let mut classified = AHashSet::new();
3578        let mut overlap = Vec::new();
3579
3580        for payload_type in CACHE_REPLAY_CAPTURE_PAYLOAD_TYPES {
3581            classified.insert(*payload_type);
3582        }
3583
3584        for payload_type in FORENSIC_ONLY_CAPTURE_PAYLOAD_TYPES {
3585            if !classified.insert(*payload_type) {
3586                overlap.push(*payload_type);
3587            }
3588        }
3589
3590        let mut seen_defaults = AHashSet::new();
3591        let duplicate_defaults: Vec<_> = DEFAULT_CAPTURE_PAYLOAD_TYPES
3592            .iter()
3593            .copied()
3594            .filter(|payload_type| !seen_defaults.insert(*payload_type))
3595            .collect();
3596        let unclassified: Vec<_> = DEFAULT_CAPTURE_PAYLOAD_TYPES
3597            .iter()
3598            .copied()
3599            .filter(|payload_type| !classified.contains(payload_type))
3600            .collect();
3601        let extra: Vec<_> = classified
3602            .iter()
3603            .copied()
3604            .filter(|payload_type| !seen_defaults.contains(payload_type))
3605            .collect();
3606
3607        assert!(
3608            duplicate_defaults.is_empty(),
3609            "default capture payload types must be unique: {duplicate_defaults:?}",
3610        );
3611        assert!(
3612            overlap.is_empty(),
3613            "cache replay and forensic-only classes must not overlap: {overlap:?}",
3614        );
3615        assert!(
3616            unclassified.is_empty(),
3617            "default capture payload types must be cache replayed or forensic-only: {unclassified:?}",
3618        );
3619        assert!(
3620            extra.is_empty(),
3621            "cache replay classification must not list uncaptured payload types: {extra:?}",
3622        );
3623    }
3624
3625    #[rstest]
3626    fn cache_replay_capture_payload_types_have_replay_rules() {
3627        for payload_type in CACHE_REPLAY_CAPTURE_PAYLOAD_TYPES {
3628            let entry = append_payload(1, payload_type, Bytes::from_static(&[0xc1])).entry;
3629            let mut cache = Cache::default();
3630
3631            let err = apply_cache_replay_entry(&mut cache, &entry)
3632                .expect_err("cache replay payload type must have a decode rule");
3633
3634            match err {
3635                CacheReplayError::Decode {
3636                    payload_type: actual,
3637                    ..
3638                } => {
3639                    assert_eq!(actual, *payload_type);
3640                }
3641                other => panic!("expected Decode for {payload_type}, was {other:?}"),
3642            }
3643        }
3644    }
3645
3646    #[rstest]
3647    fn forensic_only_capture_payload_types_are_not_cache_replayed() {
3648        for payload_type in FORENSIC_ONLY_CAPTURE_PAYLOAD_TYPES {
3649            let entry = append_payload(1, payload_type, Bytes::from_static(&[0xc1])).entry;
3650            let mut cache = Cache::default();
3651
3652            let applied = apply_cache_replay_entry(&mut cache, &entry)
3653                .expect("forensic-only payload type must not be decoded by cache replay");
3654
3655            assert!(
3656                !applied,
3657                "forensic-only payload type must be ignored by cache replay: {payload_type}",
3658            );
3659        }
3660    }
3661
3662    #[rstest]
3663    fn legacy_forward_prices_response_is_ignored_by_cache_replay() {
3664        let entry = append_payload(1, "ForwardPricesResponse", Bytes::from_static(&[0xc1])).entry;
3665        let mut cache = Cache::default();
3666
3667        let applied = apply_cache_replay_entry(&mut cache, &entry)
3668            .expect("legacy forensic payload must not be decoded by cache replay");
3669
3670        assert!(!applied);
3671    }
3672
3673    #[rstest]
3674    fn cache_public_mutators_have_recovery_classification() {
3675        let mut classified = AHashSet::new();
3676        let mut duplicates = Vec::new();
3677
3678        for row in CACHE_MUTATION_COVERAGE {
3679            if !classified.insert(row.method) {
3680                duplicates.push(row.method);
3681            }
3682        }
3683
3684        for method in CACHE_MUTATION_EXCLUSIONS {
3685            if !classified.insert(*method) {
3686                duplicates.push(*method);
3687            }
3688        }
3689
3690        let public_methods = cache_public_methods();
3691        let mutable_methods = cache_public_mutable_methods();
3692        let missing = sorted_missing_methods(&mutable_methods, &classified);
3693        let stale = sorted_stale_methods(&classified, &public_methods);
3694
3695        assert!(
3696            duplicates.is_empty(),
3697            "cache mutation recovery classifications must be unique: {duplicates:?}",
3698        );
3699        assert!(
3700            missing.is_empty(),
3701            "public Cache mutators must be classified for recovery: {missing:?}",
3702        );
3703        assert!(
3704            stale.is_empty(),
3705            "cache mutation recovery classifications reference missing methods: {stale:?}",
3706        );
3707    }
3708
3709    #[rstest]
3710    fn cache_mutation_replay_classification_matches_payload_buckets() {
3711        for row in CACHE_MUTATION_COVERAGE {
3712            match row.class {
3713                CacheMutationRecoveryClass::EventStoreCapturedAndReplayed => {
3714                    assert!(
3715                        !row.payload_types.is_empty(),
3716                        "cache-replayed mutation must cite captured payloads: {}",
3717                        row.method,
3718                    );
3719
3720                    for payload_type in row.payload_types {
3721                        assert!(
3722                            CACHE_REPLAY_CAPTURE_PAYLOAD_TYPES.contains(payload_type),
3723                            "cache mutation {} cites non-replayed payload {payload_type}",
3724                            row.method,
3725                        );
3726                    }
3727                }
3728                CacheMutationRecoveryClass::ForensicOnly => {
3729                    assert!(
3730                        !row.payload_types.is_empty(),
3731                        "forensic-only mutation must cite forensic payloads: {}",
3732                        row.method,
3733                    );
3734
3735                    for payload_type in row.payload_types {
3736                        assert!(
3737                            FORENSIC_ONLY_CAPTURE_PAYLOAD_TYPES.contains(payload_type),
3738                            "cache mutation {} cites non-forensic payload {payload_type}",
3739                            row.method,
3740                        );
3741                    }
3742                }
3743                CacheMutationRecoveryClass::SnapshotOwned
3744                | CacheMutationRecoveryClass::MissingLiveRecovery => {
3745                    assert!(
3746                        row.payload_types.is_empty(),
3747                        "non-event-store cache mutation {} should not cite payloads",
3748                        row.method,
3749                    );
3750                }
3751            }
3752        }
3753    }
3754
3755    #[rstest]
3756    fn submit_order_list_replay_restores_order_list() {
3757        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
3758        let instrument_id = instrument.id();
3759        let first_init = OrderInitializedSpec::builder()
3760            .instrument_id(instrument_id)
3761            .client_order_id(ClientOrderId::from("O-LIST-001"))
3762            .build();
3763        let second_init = OrderInitializedSpec::builder()
3764            .instrument_id(instrument_id)
3765            .client_order_id(ClientOrderId::from("O-LIST-002"))
3766            .build();
3767        let order_list = OrderList::new(
3768            OrderListId::from("OL-001"),
3769            instrument_id,
3770            first_init.strategy_id,
3771            vec![first_init.client_order_id, second_init.client_order_id],
3772            UnixNanos::from(1),
3773        );
3774        let command = SubmitOrderList::new(
3775            first_init.trader_id,
3776            Some(ClientId::from("SIM")),
3777            first_init.strategy_id,
3778            order_list.clone(),
3779            vec![first_init, second_init],
3780            None,
3781            None,
3782            None,
3783            UUID4::new(),
3784            UnixNanos::from(2),
3785            None,
3786        );
3787        let entry = append_serde_payload(1, PAYLOAD_TYPE_SUBMIT_ORDER_LIST, &command).entry;
3788        let mut cache = Cache::default();
3789
3790        let applied = apply_cache_replay_entry(&mut cache, &entry).expect("apply order list");
3791        let replayed = cache
3792            .order_list(&order_list.id)
3793            .expect("order list replayed");
3794
3795        assert!(applied);
3796        assert_eq!(replayed, &order_list);
3797    }
3798
3799    #[rstest]
3800    fn data_response_replay_restores_instruments_and_market_data() {
3801        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
3802        let instrument_id = instrument.id();
3803        let client_id = ClientId::from("DATA");
3804        let quote = QuoteTick::new(
3805            instrument_id,
3806            Price::from("1.00000"),
3807            Price::from("1.00010"),
3808            Quantity::from("100000"),
3809            Quantity::from("100000"),
3810            UnixNanos::from(10),
3811            UnixNanos::from(11),
3812        );
3813        let trade = TradeTick::new(
3814            instrument_id,
3815            Price::from("1.00005"),
3816            Quantity::from("50000"),
3817            AggressorSide::Buy,
3818            TradeId::from("T-DATA-001"),
3819            UnixNanos::from(12),
3820            UnixNanos::from(13),
3821        );
3822        let funding_rate = FundingRateUpdate::new(
3823            instrument_id,
3824            "0.0001".parse().expect("funding rate"),
3825            Some(480),
3826            Some(UnixNanos::from(60)),
3827            UnixNanos::from(14),
3828            UnixNanos::from(15),
3829        );
3830        let bar_type = BarType::new(
3831            instrument_id,
3832            BarSpecification::new(1, BarAggregation::Minute, PriceType::Last),
3833            AggregationSource::External,
3834        );
3835        let bar = Bar::new(
3836            bar_type,
3837            Price::from("1.00000"),
3838            Price::from("1.00020"),
3839            Price::from("0.99990"),
3840            Price::from("1.00010"),
3841            Quantity::from("150000"),
3842            UnixNanos::from(16),
3843            UnixNanos::from(17),
3844        );
3845        let reader = reader_with_entries(
3846            "run-data-response-replay",
3847            &[
3848                append_serde_payload(
3849                    1,
3850                    PAYLOAD_TYPE_INSTRUMENT_RESPONSE,
3851                    &InstrumentResponse::new(
3852                        UUID4::new(),
3853                        client_id,
3854                        instrument_id,
3855                        instrument.clone(),
3856                        None,
3857                        None,
3858                        UnixNanos::from(1),
3859                        None,
3860                    ),
3861                ),
3862                append_serde_payload(
3863                    2,
3864                    PAYLOAD_TYPE_INSTRUMENTS_RESPONSE,
3865                    &InstrumentsResponse::new(
3866                        UUID4::new(),
3867                        client_id,
3868                        instrument_id.venue,
3869                        vec![instrument],
3870                        None,
3871                        None,
3872                        UnixNanos::from(2),
3873                        None,
3874                    ),
3875                ),
3876                append_serde_payload(
3877                    3,
3878                    PAYLOAD_TYPE_QUOTES_RESPONSE,
3879                    &QuotesResponse::new(
3880                        UUID4::new(),
3881                        client_id,
3882                        instrument_id,
3883                        vec![quote],
3884                        None,
3885                        None,
3886                        UnixNanos::from(3),
3887                        None,
3888                    ),
3889                ),
3890                append_serde_payload(
3891                    4,
3892                    PAYLOAD_TYPE_TRADES_RESPONSE,
3893                    &TradesResponse::new(
3894                        UUID4::new(),
3895                        client_id,
3896                        instrument_id,
3897                        vec![trade],
3898                        None,
3899                        None,
3900                        UnixNanos::from(4),
3901                        None,
3902                    ),
3903                ),
3904                append_serde_payload(
3905                    5,
3906                    PAYLOAD_TYPE_FUNDING_RATES_RESPONSE,
3907                    &FundingRatesResponse::new(
3908                        UUID4::new(),
3909                        client_id,
3910                        instrument_id,
3911                        vec![funding_rate],
3912                        None,
3913                        None,
3914                        UnixNanos::from(5),
3915                        None,
3916                    ),
3917                ),
3918                append_serde_payload(
3919                    6,
3920                    PAYLOAD_TYPE_BARS_RESPONSE,
3921                    &BarsResponse::new(
3922                        UUID4::new(),
3923                        client_id,
3924                        bar_type,
3925                        vec![bar],
3926                        None,
3927                        None,
3928                        UnixNanos::from(6),
3929                        None,
3930                    ),
3931                ),
3932            ],
3933        );
3934        let mut cache = Cache::default();
3935
3936        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
3937
3938        assert_eq!(report.applied_entries, 6);
3939        assert_eq!(report.ignored_entries, 0);
3940        assert_eq!(
3941            cache.instrument(&instrument_id).map(Instrument::id),
3942            Some(instrument_id)
3943        );
3944        assert_eq!(cache.quotes(&instrument_id), Some(vec![quote]));
3945        assert_eq!(cache.trades(&instrument_id), Some(vec![trade]));
3946        assert_eq!(
3947            cache.funding_rates(&instrument_id),
3948            Some(vec![funding_rate])
3949        );
3950        assert_eq!(cache.bars(&bar_type), Some(vec![bar]));
3951    }
3952
3953    #[rstest]
3954    #[case::quotes(true)]
3955    #[case::trades(false)]
3956    fn narrowed_response_envelope_capture_replays_only_visible_rows(
3957        #[case] quotes: bool,
3958        #[values(false, true)] empty: bool,
3959    ) {
3960        use nautilus_common::messages::data::{DataResponse, DataResponseEnvelope};
3961
3962        use crate::capture::builtins::{
3963            PAYLOAD_TYPE_DATA_RESPONSE_ENVELOPE, ResponseEnvelopeCapture, default_registry,
3964        };
3965
3966        let id = InstrumentId::from("AUD/USD.SIM");
3967        let root = UUID4::new();
3968        let child = UUID4::new();
3969
3970        let quote = QuoteTick {
3971            instrument_id: id,
3972            ts_init: UnixNanos::from(23),
3973            ..Default::default()
3974        };
3975
3976        let trade = TradeTick {
3977            instrument_id: id,
3978            ts_init: UnixNanos::from(29),
3979            ..Default::default()
3980        };
3981
3982        let end = if empty { 1 } else { 2 };
3983
3984        let response = if quotes {
3985            DataResponse::Quotes(QuotesResponse::new(
3986                child,
3987                ClientId::from("HISTORY"),
3988                id,
3989                BatchView::new(Arc::new(vec![quote, quote, quote]), 1..end),
3990                Some(UnixNanos::from(11)),
3991                Some(UnixNanos::from(37)),
3992                UnixNanos::from(41),
3993                None,
3994            ))
3995        } else {
3996            DataResponse::Trades(TradesResponse::new(
3997                child,
3998                ClientId::from("HISTORY"),
3999                id,
4000                BatchView::new(Arc::new(vec![trade, trade, trade]), 1..end),
4001                Some(UnixNanos::from(11)),
4002                Some(UnixNanos::from(37)),
4003                UnixNanos::from(43),
4004                None,
4005            ))
4006        };
4007
4008        let envelope =
4009            DataResponseEnvelope::new(response, true, Some(child)).with_correlation_id(root);
4010        let registry = default_registry();
4011        let (tag, encoded) = registry.encode(&envelope).unwrap().unwrap();
4012        let captured: ResponseEnvelopeCapture = rmp_serde::from_slice(&encoded.payload).unwrap();
4013        let reader = reader_with_entries(
4014            "narrowed-response-envelope",
4015            &[append_payload(1, tag.as_str(), encoded.payload)],
4016        );
4017        let mut cache = Cache::default();
4018
4019        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4020
4021        assert_eq!(tag.as_str(), PAYLOAD_TYPE_DATA_RESPONSE_ENVELOPE);
4022        assert_eq!(captured.correlation_id, root);
4023        assert_eq!(captured.sub_correlation_id, Some(child));
4024        assert!(captured.completed);
4025        assert_eq!(captured.failure_reason, None);
4026        assert_eq!(report.applied_entries, 1);
4027        assert_eq!(report.ignored_entries, 0);
4028        assert_eq!(cache.quotes(&id), (quotes && !empty).then(|| vec![quote]));
4029        assert_eq!(cache.trades(&id), (!quotes && !empty).then(|| vec![trade]));
4030    }
4031
4032    #[rstest]
4033    fn scalar_tick_response_replay_restores_previous_payload_schema() {
4034        #[derive(Serialize)]
4035        struct ScalarResponse<T> {
4036            correlation_id: UUID4,
4037            client_id: ClientId,
4038            instrument_id: InstrumentId,
4039            data: Vec<T>,
4040            start: Option<UnixNanos>,
4041            end: Option<UnixNanos>,
4042            ts_init: UnixNanos,
4043            params: Option<nautilus_core::Params>,
4044        }
4045
4046        let id = InstrumentId::from("AUD/USD.SIM");
4047
4048        let quote = QuoteTick::new(
4049            id,
4050            Price::from("1.00001"),
4051            Price::from("1.00023"),
4052            Quantity::from(17),
4053            Quantity::from(31),
4054            UnixNanos::from(43),
4055            UnixNanos::from(47),
4056        );
4057
4058        let trade = TradeTick::new(
4059            id,
4060            Price::from("1.00019"),
4061            Quantity::from(23),
4062            AggressorSide::Buy,
4063            TradeId::from("OLD-TRADE"),
4064            UnixNanos::from(53),
4065            UnixNanos::from(59),
4066        );
4067
4068        let quotes = ScalarResponse {
4069            correlation_id: UUID4::new(),
4070            client_id: ClientId::from("DATA"),
4071            instrument_id: id,
4072            data: vec![quote],
4073            start: Some(UnixNanos::from(37)),
4074            end: Some(UnixNanos::from(61)),
4075            ts_init: UnixNanos::from(67),
4076            params: None,
4077        };
4078
4079        let trades = ScalarResponse {
4080            correlation_id: UUID4::new(),
4081            client_id: ClientId::from("DATA"),
4082            instrument_id: id,
4083            data: vec![trade],
4084            start: Some(UnixNanos::from(41)),
4085            end: Some(UnixNanos::from(71)),
4086            ts_init: UnixNanos::from(73),
4087            params: None,
4088        };
4089
4090        let reader = reader_with_entries(
4091            "scalar-tick-responses",
4092            &[
4093                append_serde_payload(1, PAYLOAD_TYPE_QUOTES_RESPONSE, &quotes),
4094                append_serde_payload(2, PAYLOAD_TYPE_TRADES_RESPONSE, &trades),
4095            ],
4096        );
4097        let mut cache = Cache::default();
4098
4099        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4100
4101        assert_eq!(report.applied_entries, 2);
4102        assert_eq!(report.ignored_entries, 0);
4103        assert_eq!(cache.quotes(&id), Some(vec![quote]));
4104        assert_eq!(cache.trades(&id), Some(vec![trade]));
4105    }
4106
4107    #[rstest]
4108    fn scalar_tick_response_replay_rejects_incomplete_metadata() {
4109        #[derive(Serialize)]
4110        struct IncompleteResponse {
4111            instrument_id: InstrumentId,
4112            data: Vec<QuoteTick>,
4113        }
4114
4115        let id = InstrumentId::from("AUD/USD.SIM");
4116
4117        let response = IncompleteResponse {
4118            instrument_id: id,
4119            data: vec![QuoteTick {
4120                instrument_id: id,
4121                ..Default::default()
4122            }],
4123        };
4124
4125        let reader = reader_with_entries(
4126            "incomplete-scalar-response",
4127            &[append_serde_payload(
4128                1,
4129                PAYLOAD_TYPE_QUOTES_RESPONSE,
4130                &response,
4131            )],
4132        );
4133        let mut cache = Cache::default();
4134
4135        let error = replay_cache_snapshot_tail(&mut cache, &reader).unwrap_err();
4136
4137        let CacheReplayError::Decode {
4138            seq,
4139            payload_type,
4140            message,
4141        } = error
4142        else {
4143            panic!("Expected invalid response metadata");
4144        };
4145
4146        assert_eq!(seq, 1);
4147        assert_eq!(payload_type, PAYLOAD_TYPE_QUOTES_RESPONSE);
4148        assert_eq!(message, "missing field `correlation_id`");
4149        assert_eq!(cache.quotes(&id), None);
4150    }
4151
4152    #[rstest]
4153    fn empty_data_response_replay_is_noop() {
4154        let instrument_id = InstrumentAny::CurrencyPair(audusd_sim()).id();
4155        let client_id = ClientId::from("DATA");
4156        let bar_type = BarType::new(
4157            instrument_id,
4158            BarSpecification::new(1, BarAggregation::Minute, PriceType::Last),
4159            AggregationSource::External,
4160        );
4161        let reader = reader_with_entries(
4162            "run-empty-data-response-replay",
4163            &[
4164                append_serde_payload(
4165                    1,
4166                    PAYLOAD_TYPE_INSTRUMENTS_RESPONSE,
4167                    &InstrumentsResponse::new(
4168                        UUID4::new(),
4169                        client_id,
4170                        instrument_id.venue,
4171                        Vec::new(),
4172                        None,
4173                        None,
4174                        UnixNanos::from(1),
4175                        None,
4176                    ),
4177                ),
4178                append_serde_payload(
4179                    2,
4180                    PAYLOAD_TYPE_QUOTES_RESPONSE,
4181                    &QuotesResponse::new(
4182                        UUID4::new(),
4183                        client_id,
4184                        instrument_id,
4185                        Vec::new(),
4186                        None,
4187                        None,
4188                        UnixNanos::from(2),
4189                        None,
4190                    ),
4191                ),
4192                append_serde_payload(
4193                    3,
4194                    PAYLOAD_TYPE_TRADES_RESPONSE,
4195                    &TradesResponse::new(
4196                        UUID4::new(),
4197                        client_id,
4198                        instrument_id,
4199                        Vec::new(),
4200                        None,
4201                        None,
4202                        UnixNanos::from(3),
4203                        None,
4204                    ),
4205                ),
4206                append_serde_payload(
4207                    4,
4208                    PAYLOAD_TYPE_FUNDING_RATES_RESPONSE,
4209                    &FundingRatesResponse::new(
4210                        UUID4::new(),
4211                        client_id,
4212                        instrument_id,
4213                        Vec::new(),
4214                        None,
4215                        None,
4216                        UnixNanos::from(4),
4217                        None,
4218                    ),
4219                ),
4220                append_serde_payload(
4221                    5,
4222                    PAYLOAD_TYPE_BARS_RESPONSE,
4223                    &BarsResponse::new(
4224                        UUID4::new(),
4225                        client_id,
4226                        bar_type,
4227                        Vec::new(),
4228                        None,
4229                        None,
4230                        UnixNanos::from(5),
4231                        None,
4232                    ),
4233                ),
4234            ],
4235        );
4236        let mut cache = Cache::default();
4237
4238        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4239
4240        assert_eq!(report.applied_entries, 5);
4241        assert_eq!(report.ignored_entries, 0);
4242        assert!(cache.instrument(&instrument_id).is_none());
4243        assert_eq!(cache.quotes(&instrument_id), None);
4244        assert_eq!(cache.trades(&instrument_id), None);
4245        assert_eq!(cache.funding_rates(&instrument_id), None);
4246        assert_eq!(cache.bars(&bar_type), None);
4247    }
4248
4249    #[rstest]
4250    #[case(false)]
4251    #[case(true)]
4252    fn command_denial_replay_does_not_create_missing_order(#[case] cancel: bool) {
4253        let event = if cancel {
4254            OrderEventAny::CancelDenied(
4255                OrderCancelDeniedSpec::builder()
4256                    .causation_id(UUID4::new())
4257                    .build(),
4258            )
4259        } else {
4260            OrderEventAny::ModifyDenied(
4261                OrderModifyDeniedSpec::builder()
4262                    .causation_id(UUID4::new())
4263                    .build(),
4264            )
4265        };
4266
4267        let reader = reader_with_entries("run-command-only", &[append_order_event(1, &event)]);
4268        let mut cache = Cache::default();
4269        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4270        assert!(!cache.order_exists(&event.client_order_id()));
4271        assert_eq!(report.applied_entries, 0);
4272        assert_eq!(report.ignored_entries, 1);
4273    }
4274
4275    #[rstest]
4276    #[case(false)]
4277    #[case(true)]
4278    fn command_denial_replay_restores_correlated_pending_state(#[case] cancel_first: bool) {
4279        let initialized = OrderInitializedSpec::builder()
4280            .instrument_id(audusd_sim().id())
4281            .order_type(OrderType::Limit)
4282            .quantity(Quantity::from(5))
4283            .price(Price::from("0.90000"))
4284            .build();
4285        let client_order_id = initialized.client_order_id;
4286        let submitted = OrderSubmittedSpec::builder()
4287            .instrument_id(initialized.instrument_id)
4288            .client_order_id(client_order_id)
4289            .build();
4290        let accepted = OrderAcceptedSpec::builder()
4291            .instrument_id(initialized.instrument_id)
4292            .client_order_id(client_order_id)
4293            .account_id(submitted.account_id)
4294            .build();
4295        let modify = UUID4::new();
4296        let cancel = UUID4::new();
4297        let mut pending_modify = OrderPendingUpdateSpec::builder()
4298            .instrument_id(initialized.instrument_id)
4299            .client_order_id(client_order_id)
4300            .account_id(submitted.account_id)
4301            .venue_order_id(accepted.venue_order_id)
4302            .build();
4303        pending_modify.causation_id = Some(modify);
4304        let mut pending_cancel = OrderPendingCancelSpec::builder()
4305            .instrument_id(initialized.instrument_id)
4306            .client_order_id(client_order_id)
4307            .account_id(submitted.account_id)
4308            .venue_order_id(accepted.venue_order_id)
4309            .build();
4310        pending_cancel.causation_id = Some(cancel);
4311        let modify_denied = OrderEventAny::ModifyDenied(
4312            OrderModifyDeniedSpec::builder()
4313                .instrument_id(initialized.instrument_id)
4314                .client_order_id(client_order_id)
4315                .account_id(submitted.account_id)
4316                .venue_order_id(accepted.venue_order_id)
4317                .causation_id(modify)
4318                .build(),
4319        );
4320        let cancel_denied = OrderEventAny::CancelDenied(
4321            OrderCancelDeniedSpec::builder()
4322                .instrument_id(initialized.instrument_id)
4323                .client_order_id(client_order_id)
4324                .account_id(submitted.account_id)
4325                .venue_order_id(accepted.venue_order_id)
4326                .causation_id(cancel)
4327                .build(),
4328        );
4329
4330        let (first, second) = if cancel_first {
4331            (cancel_denied, modify_denied)
4332        } else {
4333            (modify_denied, cancel_denied)
4334        };
4335
4336        let events = [
4337            OrderEventAny::Initialized(initialized),
4338            OrderEventAny::Submitted(submitted),
4339            OrderEventAny::Accepted(accepted),
4340            OrderEventAny::PendingUpdate(pending_modify),
4341            OrderEventAny::PendingCancel(pending_cancel),
4342            first,
4343        ];
4344        let entries: Vec<_> = events
4345            .iter()
4346            .enumerate()
4347            .map(|(index, event)| append_order_event(index as u64 + 1, event))
4348            .collect();
4349        let reader = reader_with_entries("run-correlated-denials", &entries);
4350        let mut cache = Cache::default();
4351        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4352        let restored = cache.order_owned(&client_order_id).unwrap();
4353        assert_eq!(report.applied_entries, 6);
4354        assert_eq!(report.ignored_entries, 0);
4355        assert_eq!(
4356            restored.status(),
4357            if cancel_first {
4358                OrderStatus::PendingUpdate
4359            } else {
4360                OrderStatus::PendingCancel
4361            }
4362        );
4363        assert_eq!(restored.has_pending_cancel_command(), !cancel_first);
4364        assert_eq!(restored.has_pending_update_command(), cancel_first);
4365        assert_eq!(restored.quantity(), Quantity::from(5));
4366        assert_eq!(restored.price(), Some(Price::from("0.90000")));
4367        assert_eq!(restored.filled_qty(), Quantity::from(0));
4368        let tail = reader_with_entries("run-remaining-denial", &[append_order_event(1, &second)]);
4369        let report = replay_cache_snapshot_tail(&mut cache, &tail).unwrap();
4370        let restored = cache.order_owned(&client_order_id).unwrap();
4371        assert_eq!(report.applied_entries, 1);
4372        assert_eq!(report.ignored_entries, 0);
4373        assert_eq!(restored.status(), OrderStatus::Accepted);
4374        assert!(!restored.has_pending_cancel_command());
4375        assert!(!restored.has_pending_update_command());
4376        assert_eq!(restored.quantity(), Quantity::from(5));
4377        assert_eq!(restored.price(), Some(Price::from("0.90000")));
4378        assert_eq!(restored.filled_qty(), Quantity::from(0));
4379        assert_eq!(restored.last_event(), &second);
4380    }
4381
4382    #[rstest]
4383    fn order_fill_replay_updates_order_and_creates_position() {
4384        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4385        let position_id = PositionId::from("P-001");
4386        let initialized = OrderInitializedSpec::builder()
4387            .instrument_id(instrument.id())
4388            .build();
4389        let client_order_id = initialized.client_order_id;
4390        let submitted = OrderSubmittedSpec::builder()
4391            .instrument_id(instrument.id())
4392            .client_order_id(client_order_id)
4393            .build();
4394        let accepted = OrderAcceptedSpec::builder()
4395            .instrument_id(instrument.id())
4396            .client_order_id(client_order_id)
4397            .account_id(submitted.account_id)
4398            .build();
4399        let filled = OrderFilledSpec::builder()
4400            .instrument_id(instrument.id())
4401            .client_order_id(client_order_id)
4402            .venue_order_id(accepted.venue_order_id)
4403            .account_id(submitted.account_id)
4404            .position_id(position_id)
4405            .commission(Money::from("1 USD"))
4406            .build();
4407        let filled_event = OrderEventAny::Filled(filled.clone());
4408        let reader = reader_with_entries(
4409            "run-order-replay",
4410            &[
4411                append_order_event(1, &OrderEventAny::Initialized(initialized)),
4412                append_order_event(2, &OrderEventAny::Submitted(submitted)),
4413                append_order_event(3, &OrderEventAny::Accepted(accepted)),
4414                append_order_event(4, &filled_event),
4415            ],
4416        );
4417        let mut cache = Cache::default();
4418        cache.add_instrument(instrument).expect("add instrument");
4419
4420        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4421        let order = cache.order_owned(&client_order_id).expect("order replayed");
4422        let position = cache
4423            .position_owned(&position_id)
4424            .expect("position replayed");
4425
4426        assert_eq!(report.applied_entries, 4);
4427        assert_eq!(report.ignored_entries, 0);
4428        assert_eq!(order.status(), OrderStatus::Filled);
4429        assert_eq!(order.event_count(), 4);
4430        assert_eq!(order.last_event(), &filled_event);
4431        assert_eq!(position.event_count(), 1);
4432        assert_eq!(position.last_event(), Some(filled.clone()));
4433        assert_eq!(position.trade_ids(), vec![filled.trade_id]);
4434        assert_eq!(position.commissions(), vec![Money::from("1 USD")]);
4435    }
4436
4437    #[rstest]
4438    fn orderless_leg_fill_replay_creates_position_without_order_mapping() {
4439        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4440        let client_order_id = ClientOrderId::from("SPREAD-LEG-AUDUSD");
4441        let position_id = PositionId::from("P-ORDERLESS-LEG");
4442        let filled = OrderFilledSpec::builder()
4443            .instrument_id(instrument.id())
4444            .client_order_id(client_order_id)
4445            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-AUDUSD"))
4446            .position_id(position_id)
4447            .commission(Money::from("1 USD"))
4448            .build();
4449        let reader = reader_with_entries(
4450            "run-orderless-leg-fill-replay",
4451            &[append_order_event(
4452                1,
4453                &OrderEventAny::Filled(filled.clone()),
4454            )],
4455        );
4456        let mut cache = Cache::default();
4457        cache.add_instrument(instrument).expect("add instrument");
4458
4459        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4460        let position = cache
4461            .position_owned(&position_id)
4462            .expect("orderless leg position replayed");
4463
4464        assert_eq!(report.applied_entries, 1);
4465        assert_eq!(report.ignored_entries, 0);
4466        assert!(cache.order_owned(&client_order_id).is_none());
4467        assert_eq!(cache.position_id(&client_order_id), None);
4468        assert_eq!(position.event_count(), 1);
4469        assert_eq!(position.last_event(), Some(filled.clone()));
4470        assert_eq!(position.trade_ids(), vec![filled.trade_id]);
4471        assert_eq!(position.commissions(), vec![Money::from("1 USD")]);
4472        assert!(cache.check_integrity());
4473    }
4474
4475    #[rstest]
4476    #[case::netting(OmsType::Netting)]
4477    #[case::hedging(OmsType::Hedging)]
4478    fn order_backed_flip_replay_preserves_closed_and_opened_accounting(
4479        #[case] oms_type: OmsType,
4480        #[values(false, true)] empty_cache: bool,
4481    ) {
4482        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4483        let strategy_id = StrategyId::from("S-REPLAY-001");
4484
4485        let position_id = if oms_type == OmsType::Netting && empty_cache {
4486            PositionId::new(format!("{}-{strategy_id}", instrument.id()))
4487        } else {
4488            PositionId::from("P-REPLAY-FLIP")
4489        };
4490
4491        let replacement_id = if oms_type == OmsType::Netting {
4492            position_id
4493        } else {
4494            PositionId::from("P-REPLAY-REPLACEMENT")
4495        };
4496
4497        let opening = OrderFilledSpec::builder()
4498            .strategy_id(strategy_id)
4499            .instrument_id(instrument.id())
4500            .client_order_id(ClientOrderId::from("O-REPLAY-OPEN"))
4501            .venue_order_id(VenueOrderId::from("V-REPLAY-OPEN"))
4502            .position_id(position_id)
4503            .last_qty(Quantity::from(1))
4504            .last_px(Price::from("1.00000"))
4505            .commission(Money::from("0 USD"))
4506            .build();
4507        let original = Position::new(&instrument, opening.clone());
4508        let reversal = OrderFilledSpec::builder()
4509            .strategy_id(strategy_id)
4510            .instrument_id(instrument.id())
4511            .client_order_id(ClientOrderId::from("O-REPLAY-REVERSE"))
4512            .venue_order_id(VenueOrderId::from("V-REPLAY-REVERSE"))
4513            .trade_id(TradeId::from("T-REPLAY-REVERSE"))
4514            .position_id(position_id)
4515            .order_side(OrderSide::Sell)
4516            .last_qty(Quantity::from(2))
4517            .last_px(Price::from("2.00000"))
4518            .commission(Money::from_str_exact("0.006 USD").unwrap())
4519            .build();
4520        let (closing, opening_fragment) = reversal
4521            .split_for_position_flip(original.quantity, Some(replacement_id), UUID4::new())
4522            .unwrap();
4523        let mut closed = original.clone();
4524        closed.try_apply(&closing).unwrap();
4525        let closed_event = PositionClosed::create(&closed, &closing, UUID4::new(), closing.ts_init);
4526        let replacement = Position::new(&instrument, opening_fragment.clone());
4527        let opened_event = PositionOpened::create(
4528            &replacement,
4529            &opening_fragment,
4530            UUID4::new(),
4531            opening_fragment.ts_init,
4532        );
4533        let mut entries = Vec::new();
4534        if empty_cache {
4535            entries.extend(
4536                filled_order_events(&opening)
4537                    .iter()
4538                    .enumerate()
4539                    .map(|(index, event)| append_order_event(index as u64 + 1, event)),
4540            );
4541            let opened = PositionOpened::create(&original, &opening, UUID4::new(), opening.ts_init);
4542            entries.push(append_position_event(
4543                5,
4544                &PositionEvent::PositionOpened(opened),
4545            ));
4546        }
4547
4548        let offset = entries.len() as u64;
4549        entries.extend(
4550            filled_order_events(&reversal)
4551                .iter()
4552                .enumerate()
4553                .map(|(index, event)| append_order_event(offset + index as u64 + 1, event)),
4554        );
4555        entries.push(append_position_event(
4556            offset + 5,
4557            &PositionEvent::PositionClosed(closed_event),
4558        ));
4559        entries.push(append_position_event(
4560            offset + 6,
4561            &PositionEvent::PositionOpened(opened_event),
4562        ));
4563        let reader = reader_with_entries("run-order-backed-flip", &entries);
4564        let mut cache = Cache::default();
4565        cache.add_instrument(instrument).unwrap();
4566
4567        if !empty_cache {
4568            let order = OrderAny::from_events(filled_order_events(&opening).to_vec()).unwrap();
4569            cache
4570                .add_order(order, Some(position_id), None, false)
4571                .unwrap();
4572            cache.add_position(&original, oms_type).unwrap();
4573            cache.build_index();
4574        }
4575
4576        assert!(cache.check_integrity());
4577
4578        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4579        let replayed = cache.position_owned(&replacement_id).unwrap();
4580        let predecessor = if oms_type == OmsType::Netting {
4581            let mut snapshots = cache.position_snapshots(Some(&position_id), None);
4582            assert_eq!(snapshots.len(), 1);
4583            snapshots.remove(0)
4584        } else {
4585            cache.position_owned(&position_id).unwrap()
4586        };
4587
4588        assert_eq!(report.applied_entries, entries.len());
4589        assert_eq!(report.ignored_entries, 0);
4590        assert_eq!(predecessor.side, PositionSide::Flat);
4591        assert_eq!(
4592            predecessor.realized_pnl,
4593            Some(Money::from_str_exact("0.997 USD").unwrap())
4594        );
4595        assert_eq!(predecessor.cost_open, 0.into());
4596        assert_eq!(
4597            predecessor.commissions(),
4598            vec![Money::from_str_exact("0.003 USD").unwrap()]
4599        );
4600        assert_eq!(replayed.side, PositionSide::Short);
4601        assert_eq!(replayed.quantity, Quantity::from(1));
4602        assert_eq!(replayed.avg_px_open, 2.into());
4603        assert_eq!(replayed.cost_open, 2.into());
4604        assert_eq!(
4605            replayed.realized_pnl,
4606            Some(Money::from_str_exact("-0.003 USD").unwrap())
4607        );
4608        assert_eq!(
4609            replayed.commissions(),
4610            vec![Money::from_str_exact("0.003 USD").unwrap()]
4611        );
4612        assert_eq!(cache.oms_type(&replacement_id), Some(oms_type));
4613        assert_eq!(
4614            cache.position_id(&reversal.client_order_id),
4615            Some(&replacement_id)
4616        );
4617        assert_eq!(
4618            replayed.replay_events.len(),
4619            if oms_type == OmsType::Netting { 3 } else { 1 }
4620        );
4621        assert!(cache.check_integrity());
4622    }
4623
4624    #[rstest]
4625    #[case::matching_quantity("2", true, "9.47", "5.53 USD")]
4626    #[case::changed_quantity("1", false, "12", "3 USD")]
4627    fn price_restatement_replay_preserves_journal_accounting(
4628        #[case] restated_qty: &str,
4629        #[case] applied: bool,
4630        #[case] expected_px: &str,
4631        #[case] expected_pnl: &str,
4632    ) {
4633        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4634        let position_id = PositionId::from("P-REPLAY-RESTATEMENT");
4635        let opening = OrderFilledSpec::builder()
4636            .instrument_id(instrument.id())
4637            .client_order_id(ClientOrderId::from("O-REPLAY-RESTATEMENT"))
4638            .trade_id(TradeId::from("T-REPLAY-RESTATEMENT"))
4639            .position_id(position_id)
4640            .last_qty(Quantity::from(2))
4641            .last_px(Price::from("12.00000"))
4642            .commission(Money::from("0 USD"))
4643            .build();
4644        let mut live = Position::new(&instrument, opening.clone());
4645        let opened = PositionOpened::create(&live, &opening, UUID4::new(), opening.ts_init);
4646
4647        let restatement = OrderFilled {
4648            last_qty: Quantity::from(restated_qty),
4649            last_px: Price::from("9.47000"),
4650            event_id: UUID4::new(),
4651            ..opening.clone()
4652        };
4653
4654        let mut entries: Vec<_> = filled_order_events(&opening)
4655            .iter()
4656            .enumerate()
4657            .map(|(index, event)| append_order_event(index as u64 + 1, event))
4658            .collect();
4659        entries.push(append_position_event(
4660            5,
4661            &PositionEvent::PositionOpened(opened),
4662        ));
4663        entries.push(append_order_event(
4664            6,
4665            &OrderEventAny::Filled(restatement.clone()),
4666        ));
4667
4668        if applied {
4669            live.try_apply(&restatement).unwrap();
4670            let changed =
4671                PositionChanged::create(&live, &restatement, UUID4::new(), restatement.ts_init);
4672            entries.push(append_position_event(
4673                7,
4674                &PositionEvent::PositionChanged(changed),
4675            ));
4676        }
4677
4678        let reducing = OrderFilledSpec::builder()
4679            .instrument_id(instrument.id())
4680            .client_order_id(ClientOrderId::from("O-REPLAY-REDUCE"))
4681            .venue_order_id(VenueOrderId::from("V-REPLAY-REDUCE"))
4682            .trade_id(TradeId::from("T-REPLAY-REDUCE"))
4683            .position_id(position_id)
4684            .order_side(OrderSide::Sell)
4685            .last_qty(Quantity::from(1))
4686            .last_px(Price::from("15.00000"))
4687            .commission(Money::zero(Currency::USD()))
4688            .build();
4689        live.try_apply(&reducing).unwrap();
4690        let changed = PositionChanged::create(&live, &reducing, UUID4::new(), reducing.ts_init);
4691        let offset = entries.len() as u64;
4692        entries.extend(
4693            filled_order_events(&reducing)
4694                .iter()
4695                .enumerate()
4696                .map(|(index, event)| append_order_event(offset + index as u64 + 1, event)),
4697        );
4698        entries.push(append_position_event(
4699            offset + 5,
4700            &PositionEvent::PositionChanged(changed),
4701        ));
4702        let reader = reader_with_entries("run-price-restatement", &entries);
4703        let mut cache = Cache::default();
4704        cache.add_instrument(instrument).unwrap();
4705
4706        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
4707        let replayed = cache.position_owned(&position_id).unwrap();
4708
4709        assert_eq!(report.applied_entries, entries.len());
4710        assert_eq!(report.ignored_entries, 0);
4711        assert_eq!(replayed.quantity, Quantity::from(1));
4712        assert_eq!(replayed.avg_px_open, Price::from(expected_px).as_decimal());
4713        assert_eq!(replayed.cost_open, Price::from(expected_px).as_decimal());
4714        assert_eq!(replayed.realized_pnl, Some(Money::from(expected_pnl)));
4715        assert_eq!(replayed.event_count(), 2);
4716        assert_eq!(replayed.replay_events.len(), if applied { 3 } else { 2 });
4717        assert_eq!(
4718            rmp_serde::to_vec_named(&replayed).unwrap(),
4719            rmp_serde::to_vec_named(&live).unwrap()
4720        );
4721        assert!(cache.check_integrity());
4722    }
4723
4724    fn filled_order_events(fill: &OrderFilled) -> [OrderEventAny; 4] {
4725        let initialized = OrderInitializedSpec::builder()
4726            .strategy_id(fill.strategy_id)
4727            .instrument_id(fill.instrument_id)
4728            .client_order_id(fill.client_order_id)
4729            .order_side(fill.order_side)
4730            .quantity(fill.last_qty)
4731            .build();
4732        let submitted = OrderSubmittedSpec::builder()
4733            .strategy_id(fill.strategy_id)
4734            .instrument_id(fill.instrument_id)
4735            .client_order_id(fill.client_order_id)
4736            .account_id(fill.account_id)
4737            .build();
4738        let accepted = OrderAcceptedSpec::builder()
4739            .strategy_id(fill.strategy_id)
4740            .instrument_id(fill.instrument_id)
4741            .client_order_id(fill.client_order_id)
4742            .venue_order_id(fill.venue_order_id)
4743            .account_id(fill.account_id)
4744            .build();
4745
4746        [
4747            OrderEventAny::Initialized(initialized),
4748            OrderEventAny::Submitted(submitted),
4749            OrderEventAny::Accepted(accepted),
4750            OrderEventAny::Filled(fill.clone()),
4751        ]
4752    }
4753
4754    #[rstest]
4755    fn orderless_netting_reopen_replay_does_not_treat_closed_position_as_flip() {
4756        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4757        let client_order_id = ClientOrderId::from("SPREAD-LEG-AUDUSD");
4758        let position_id = PositionId::from("P-ORDERLESS-NETTING");
4759        let opening_fill = OrderFilledSpec::builder()
4760            .instrument_id(instrument.id())
4761            .client_order_id(client_order_id)
4762            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-1"))
4763            .trade_id(TradeId::from("T-SPREAD-LEG-1"))
4764            .order_side(OrderSide::Buy)
4765            .last_qty(Quantity::from(1))
4766            .position_id(position_id)
4767            .build();
4768        let closing_fill = OrderFilledSpec::builder()
4769            .instrument_id(instrument.id())
4770            .client_order_id(client_order_id)
4771            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-2"))
4772            .trade_id(TradeId::from("T-SPREAD-LEG-2"))
4773            .order_side(OrderSide::Sell)
4774            .last_qty(Quantity::from(1))
4775            .position_id(position_id)
4776            .build();
4777        let mut closed_position = Position::new(&instrument, opening_fill);
4778        closed_position.apply(&closing_fill);
4779        assert!(closed_position.is_closed());
4780
4781        let reopening_fill = OrderFilledSpec::builder()
4782            .instrument_id(instrument.id())
4783            .client_order_id(client_order_id)
4784            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-3"))
4785            .trade_id(TradeId::from("T-SPREAD-LEG-3"))
4786            .order_side(OrderSide::Sell)
4787            .last_qty(Quantity::from(1))
4788            .position_id(position_id)
4789            .build();
4790        let mut reopened_position = closed_position.clone();
4791        reopened_position.apply(&reopening_fill);
4792        let reopened = PositionOpened::create(
4793            &reopened_position,
4794            &reopening_fill,
4795            UUID4::new(),
4796            reopening_fill.ts_init,
4797        );
4798        let reader = reader_with_entries(
4799            "run-orderless-netting-reopen-replay",
4800            &[
4801                append_order_event(1, &OrderEventAny::Filled(reopening_fill.clone())),
4802                append_position_event(2, &PositionEvent::PositionOpened(reopened)),
4803            ],
4804        );
4805        let mut cache = Cache::default();
4806        cache.add_instrument(instrument).expect("add instrument");
4807        cache
4808            .add_position_without_order(&closed_position, OmsType::Netting)
4809            .expect("seed closed orderless position");
4810
4811        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4812        let position = cache
4813            .position_owned(&position_id)
4814            .expect("netting position reopened");
4815
4816        assert_eq!(report.applied_entries, 2);
4817        assert_eq!(report.ignored_entries, 0);
4818        assert!(position.is_open());
4819        assert_eq!(position.side, PositionSide::Short);
4820        assert_eq!(position.entry, OrderSide::Sell);
4821        assert_eq!(position.quantity, Quantity::from(1));
4822        assert_eq!(position.opening_order_id, client_order_id);
4823        assert_eq!(position.closing_order_id, None);
4824        assert_eq!(position.event_count(), 1);
4825        assert_eq!(position.trade_ids(), vec![reopening_fill.trade_id]);
4826        assert_eq!(position.last_event(), Some(reopening_fill));
4827        assert_eq!(cache.oms_type(&position_id), Some(OmsType::Netting));
4828        assert!(cache.orders_for_position(&position_id).is_empty());
4829        assert_eq!(cache.position_id(&client_order_id), None);
4830        assert!(cache.check_integrity());
4831    }
4832
4833    #[rstest]
4834    fn orderless_hedging_flip_replay_recreates_replacement_position() {
4835        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4836        let client_order_id = ClientOrderId::from("SPREAD-LEG-AUDUSD");
4837        let first_position_id = PositionId::from("P-ORDERLESS-LEG-1");
4838        let replacement_position_id = PositionId::from("P-ORDERLESS-LEG-2");
4839        let opening_fill = OrderFilledSpec::builder()
4840            .instrument_id(instrument.id())
4841            .client_order_id(client_order_id)
4842            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-1"))
4843            .trade_id(TradeId::from("T-SPREAD-LEG-1"))
4844            .order_side(OrderSide::Buy)
4845            .last_qty(Quantity::from(1))
4846            .last_px(Price::from("1.00000"))
4847            .position_id(first_position_id)
4848            .commission(Money::from("1 USD"))
4849            .build();
4850        let first_position = Position::new(&instrument, opening_fill.clone());
4851        let first_opened = PositionOpened::create(
4852            &first_position,
4853            &opening_fill,
4854            UUID4::new(),
4855            opening_fill.ts_init,
4856        );
4857
4858        let flip_fill = OrderFilledSpec::builder()
4859            .instrument_id(instrument.id())
4860            .client_order_id(client_order_id)
4861            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-2"))
4862            .trade_id(TradeId::from("T-SPREAD-LEG-2"))
4863            .order_side(OrderSide::Sell)
4864            .last_qty(Quantity::from(2))
4865            .last_px(Price::from("1.10000"))
4866            .position_id(first_position_id)
4867            .commission(Money::from("2 USD"))
4868            .build();
4869        let mut closing_fragment = flip_fill.clone();
4870        closing_fragment.last_qty = Quantity::from(1);
4871        closing_fragment.commission = Some(Money::from("1 USD"));
4872        let mut closed_position = first_position;
4873        closed_position.apply(&closing_fragment);
4874        let first_closed = PositionClosed::create(
4875            &closed_position,
4876            &closing_fragment,
4877            UUID4::new(),
4878            flip_fill.ts_init,
4879        );
4880
4881        let mut opening_fragment = flip_fill.clone();
4882        opening_fragment.last_qty = Quantity::from(1);
4883        opening_fragment.position_id = Some(replacement_position_id);
4884        opening_fragment.commission = Some(Money::from("1 USD"));
4885        opening_fragment.event_id = UUID4::new();
4886        opening_fragment.causation_id = Some(flip_fill.event_id);
4887        let mut replacement_position = Position::new(&instrument, opening_fragment.clone());
4888        let replacement_opened = PositionOpened::create(
4889            &replacement_position,
4890            &opening_fragment,
4891            UUID4::new(),
4892            opening_fragment.ts_init,
4893        );
4894
4895        let subsequent_fill = OrderFilledSpec::builder()
4896            .instrument_id(instrument.id())
4897            .client_order_id(client_order_id)
4898            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-3"))
4899            .trade_id(TradeId::from("T-SPREAD-LEG-3"))
4900            .order_side(OrderSide::Sell)
4901            .last_qty(Quantity::from(1))
4902            .last_px(Price::from("1.20000"))
4903            .position_id(replacement_position_id)
4904            .commission(Money::from("1 USD"))
4905            .build();
4906        replacement_position.apply(&subsequent_fill);
4907        let replacement_changed = PositionChanged::create(
4908            &replacement_position,
4909            &subsequent_fill,
4910            UUID4::new(),
4911            subsequent_fill.ts_init,
4912        );
4913        let reader = reader_with_entries(
4914            "run-orderless-hedging-flip-replay",
4915            &[
4916                append_order_event(1, &OrderEventAny::Filled(opening_fill)),
4917                append_position_event(2, &PositionEvent::PositionOpened(first_opened)),
4918                append_order_event(3, &OrderEventAny::Filled(flip_fill.clone())),
4919                append_position_event(4, &PositionEvent::PositionClosed(first_closed)),
4920                append_position_event(5, &PositionEvent::PositionOpened(replacement_opened)),
4921                append_order_event(6, &OrderEventAny::Filled(subsequent_fill.clone())),
4922                append_position_event(7, &PositionEvent::PositionChanged(replacement_changed)),
4923            ],
4924        );
4925        let mut cache = Cache::default();
4926        cache.add_instrument(instrument).expect("add instrument");
4927
4928        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
4929
4930        assert_eq!(report.applied_entries, 7);
4931        assert_eq!(report.ignored_entries, 0);
4932        let closed = cache
4933            .position_owned(&first_position_id)
4934            .expect("closed predecessor replayed");
4935        assert!(closed.is_closed());
4936        assert_eq!(closed.event_count(), 2);
4937        let closing_fragments = closed.fill_fragments(client_order_id, flip_fill.trade_id);
4938        assert_eq!(closing_fragments.len(), 1);
4939        assert_eq!(closing_fragments[0].last_qty, Quantity::from(1));
4940        assert_eq!(closing_fragments[0].commission, Some(Money::from("1 USD")));
4941        assert_eq!(closing_fragments[0].event_id, flip_fill.event_id);
4942
4943        let replacement = cache
4944            .position_owned(&replacement_position_id)
4945            .expect("open replacement replayed");
4946        assert!(replacement.is_open());
4947        assert_eq!(replacement.side, PositionSide::Short);
4948        assert_eq!(replacement.quantity, Quantity::from(2));
4949        assert_eq!(replacement.event_count(), 2);
4950        assert_eq!(
4951            cache.oms_type(&replacement_position_id),
4952            Some(OmsType::Hedging)
4953        );
4954        assert!(replacement.trade_ids().contains(&flip_fill.trade_id));
4955        assert!(replacement.trade_ids().contains(&subsequent_fill.trade_id));
4956        let opening_fragments = replacement.fill_fragments(client_order_id, flip_fill.trade_id);
4957        assert_eq!(opening_fragments.len(), 1);
4958        assert_eq!(opening_fragments[0].last_qty, Quantity::from(1));
4959        assert_eq!(opening_fragments[0].commission, Some(Money::from("1 USD")));
4960        assert_eq!(opening_fragments[0].causation_id, Some(flip_fill.event_id));
4961
4962        assert!(cache.orders_for_position(&first_position_id).is_empty());
4963        assert!(
4964            cache
4965                .orders_for_position(&replacement_position_id)
4966                .is_empty()
4967        );
4968        assert_eq!(cache.position_id(&client_order_id), None);
4969        assert!(cache.check_integrity());
4970    }
4971
4972    #[rstest]
4973    fn single_entry_orderless_flip_is_rejected_before_mutating_position() {
4974        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
4975        let position_id = PositionId::from("P-ORDERLESS-SINGLE-ENTRY");
4976        let opening_fill = OrderFilledSpec::builder()
4977            .instrument_id(instrument.id())
4978            .client_order_id(ClientOrderId::from("SPREAD-LEG-SINGLE"))
4979            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-SINGLE-1"))
4980            .trade_id(TradeId::from("T-SPREAD-LEG-SINGLE-1"))
4981            .order_side(OrderSide::Buy)
4982            .last_qty(Quantity::from(1))
4983            .position_id(position_id)
4984            .build();
4985        let original = Position::new(&instrument, opening_fill.clone());
4986        let flip_fill = OrderFilledSpec::builder()
4987            .instrument_id(instrument.id())
4988            .client_order_id(opening_fill.client_order_id)
4989            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-SINGLE-2"))
4990            .trade_id(TradeId::from("T-SPREAD-LEG-SINGLE-2"))
4991            .order_side(OrderSide::Sell)
4992            .last_qty(Quantity::from(2))
4993            .position_id(position_id)
4994            .build();
4995        let entry = append_order_event(1, &OrderEventAny::Filled(flip_fill)).entry;
4996        let mut cache = Cache::default();
4997        cache
4998            .add_instrument(instrument)
4999            .expect("add replay instrument");
5000        cache
5001            .add_position_without_order(&original, OmsType::Hedging)
5002            .expect("seed orderless position");
5003
5004        let error = apply_cache_replay_entry(&mut cache, &entry)
5005            .expect_err("single-entry API cannot defer the opening fragment");
5006        let after = cache
5007            .position_owned(&position_id)
5008            .expect("position retained");
5009
5010        assert!(error.to_string().contains("snapshot-tail replay context"));
5011        assert_eq!(after.side, original.side);
5012        assert_eq!(after.quantity, original.quantity);
5013        assert_eq!(after.event_count(), original.event_count());
5014        assert_eq!(after.trade_ids(), original.trade_ids());
5015    }
5016
5017    #[rstest]
5018    fn duplicate_orderless_reducing_fill_is_not_replayed_as_flip() {
5019        // A replayed duplicate of an earlier reducing fill can exceed the remaining
5020        // quantity; its trade ID is already in the open episode, so it must be the
5021        // idempotent no-op rather than a flip.
5022        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5023        let position_id = PositionId::from("P-ORDERLESS-DUPLICATE");
5024        let opening_fill = OrderFilledSpec::builder()
5025            .instrument_id(instrument.id())
5026            .client_order_id(ClientOrderId::from("SPREAD-LEG-DUPLICATE"))
5027            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-DUPLICATE-1"))
5028            .trade_id(TradeId::from("T-SPREAD-LEG-DUPLICATE-1"))
5029            .order_side(OrderSide::Buy)
5030            .last_qty(Quantity::from(3))
5031            .position_id(position_id)
5032            .build();
5033        let reducing_fill = OrderFilledSpec::builder()
5034            .instrument_id(instrument.id())
5035            .client_order_id(opening_fill.client_order_id)
5036            .venue_order_id(VenueOrderId::from("V-SPREAD-LEG-DUPLICATE-2"))
5037            .trade_id(TradeId::from("T-SPREAD-LEG-DUPLICATE-2"))
5038            .order_side(OrderSide::Sell)
5039            .last_qty(Quantity::from(2))
5040            .position_id(position_id)
5041            .build();
5042        let mut original = Position::new(&instrument, opening_fill);
5043        original.apply(&reducing_fill);
5044        let entry = append_order_event(1, &OrderEventAny::Filled(reducing_fill)).entry;
5045        let mut cache = Cache::default();
5046        cache
5047            .add_instrument(instrument)
5048            .expect("add replay instrument");
5049        cache
5050            .add_position_without_order(&original, OmsType::Hedging)
5051            .expect("seed orderless position");
5052
5053        let applied = apply_cache_replay_entry(&mut cache, &entry)
5054            .expect("duplicate reducing fill is the idempotent no-op");
5055        let after = cache
5056            .position_owned(&position_id)
5057            .expect("position retained");
5058
5059        assert!(applied);
5060        assert_eq!(after.side, PositionSide::Long);
5061        assert_eq!(after.quantity, original.quantity);
5062        assert_eq!(after.event_count(), original.event_count());
5063        assert_eq!(after.trade_ids(), original.trade_ids());
5064    }
5065
5066    #[rstest]
5067    fn order_fill_replay_without_instrument_counts_fill_as_ignored() {
5068        // The position side cannot open without the instrument; the fill must count
5069        // as ignored rather than claim a full apply.
5070        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5071        let position_id = PositionId::from("P-NO-INSTR");
5072        let initialized = OrderInitializedSpec::builder()
5073            .instrument_id(instrument.id())
5074            .build();
5075        let client_order_id = initialized.client_order_id;
5076        let submitted = OrderSubmittedSpec::builder()
5077            .instrument_id(instrument.id())
5078            .client_order_id(client_order_id)
5079            .build();
5080        let accepted = OrderAcceptedSpec::builder()
5081            .instrument_id(instrument.id())
5082            .client_order_id(client_order_id)
5083            .account_id(submitted.account_id)
5084            .build();
5085        let filled = OrderFilledSpec::builder()
5086            .instrument_id(instrument.id())
5087            .client_order_id(client_order_id)
5088            .venue_order_id(accepted.venue_order_id)
5089            .account_id(submitted.account_id)
5090            .position_id(position_id)
5091            .build();
5092        let reader = reader_with_entries(
5093            "run-fill-no-instrument",
5094            &[
5095                append_order_event(1, &OrderEventAny::Initialized(initialized)),
5096                append_order_event(2, &OrderEventAny::Submitted(submitted)),
5097                append_order_event(3, &OrderEventAny::Accepted(accepted)),
5098                append_order_event(4, &OrderEventAny::Filled(filled)),
5099            ],
5100        );
5101        let mut cache = Cache::default();
5102
5103        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
5104
5105        assert_eq!(report.applied_entries, 3);
5106        assert_eq!(report.ignored_entries, 1);
5107        assert!(cache.position_owned(&position_id).is_none());
5108    }
5109
5110    #[rstest]
5111    fn order_fill_void_replay_updates_order_and_position() {
5112        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5113        let position_id = PositionId::from("P-VOID-001");
5114        let initialized = OrderInitializedSpec::builder()
5115            .instrument_id(instrument.id())
5116            .build();
5117        let client_order_id = initialized.client_order_id;
5118        let submitted = OrderSubmittedSpec::builder()
5119            .instrument_id(instrument.id())
5120            .client_order_id(client_order_id)
5121            .build();
5122        let accepted = OrderAcceptedSpec::builder()
5123            .instrument_id(instrument.id())
5124            .client_order_id(client_order_id)
5125            .account_id(submitted.account_id)
5126            .build();
5127        let filled = OrderFilledSpec::builder()
5128            .instrument_id(instrument.id())
5129            .client_order_id(client_order_id)
5130            .venue_order_id(accepted.venue_order_id)
5131            .account_id(submitted.account_id)
5132            .position_id(position_id)
5133            .commission(Money::from("1 USD"))
5134            .build();
5135        let fill_voided = OrderFillVoidedSpec::builder()
5136            .trader_id(filled.trader_id)
5137            .strategy_id(filled.strategy_id)
5138            .instrument_id(filled.instrument_id)
5139            .client_order_id(filled.client_order_id)
5140            .venue_order_id(filled.venue_order_id)
5141            .account_id(filled.account_id)
5142            .trade_id(filled.trade_id)
5143            .voided_qty(Quantity::from(50_000))
5144            .commission_voided(Money::from("0.40 USD"))
5145            .order_side(filled.order_side)
5146            .order_type(filled.order_type)
5147            .last_px(filled.last_px)
5148            .currency(filled.currency)
5149            .liquidity_side(filled.liquidity_side)
5150            .position_id(position_id)
5151            .is_reopened(true)
5152            .build();
5153        let reader = reader_with_entries(
5154            "run-fill-void-replay",
5155            &[
5156                append_order_event(1, &OrderEventAny::Initialized(initialized)),
5157                append_order_event(2, &OrderEventAny::Submitted(submitted)),
5158                append_order_event(3, &OrderEventAny::Accepted(accepted)),
5159                append_order_event(4, &OrderEventAny::Filled(filled)),
5160                append_order_event(5, &OrderEventAny::FillVoided(fill_voided.clone())),
5161            ],
5162        );
5163        let mut cache = Cache::default();
5164        cache.add_instrument(instrument).expect("add instrument");
5165
5166        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
5167        let order = cache.order_owned(&client_order_id).expect("order replayed");
5168        let position = cache
5169            .position_owned(&position_id)
5170            .expect("position replayed");
5171
5172        assert_eq!(report.applied_entries, 5);
5173        assert_eq!(report.ignored_entries, 0);
5174        assert_eq!(order.status(), OrderStatus::PartiallyFilled);
5175        assert_eq!(order.filled_qty(), Quantity::from(50_000));
5176        assert_eq!(order.voided_qty(), Quantity::from(50_000));
5177        assert_eq!(position.quantity, Quantity::from(50_000));
5178        assert_eq!(position.commissions(), vec![Money::from("0.60 USD")]);
5179        assert_eq!(position.fill_voids.len(), 1);
5180        assert_eq!(position.fill_voids[0].event, fill_voided);
5181    }
5182
5183    fn binary_order_events(
5184        instrument: &InstrumentAny,
5185        order_id: &str,
5186        quantity: &str,
5187        price: &str,
5188    ) -> [OrderEventAny; 4] {
5189        let position_id = PositionId::from("P-SETTLED");
5190        let filled = OrderFilledSpec::builder()
5191            .instrument_id(instrument.id())
5192            .client_order_id(ClientOrderId::from(order_id))
5193            .venue_order_id(VenueOrderId::from(format!("V-{order_id}").as_str()))
5194            .trade_id(TradeId::from(format!("T-{order_id}").as_str()))
5195            .last_qty(Quantity::from(quantity))
5196            .last_px(Price::from(price))
5197            .currency(Currency::USDC())
5198            .position_id(position_id)
5199            .build();
5200
5201        filled_order_events(&filled)
5202    }
5203
5204    #[rstest]
5205    fn instrument_close_replay_settles_position_and_keeps_later_changes_off_it() {
5206        let instrument = InstrumentAny::BinaryOption(binary_option());
5207        let opening = binary_order_events(&instrument, "O-OPEN", "10.00", "0.400");
5208        let late = binary_order_events(&instrument, "O-LATE", "5.00", "0.500");
5209
5210        let OrderEventAny::Filled(opening_fill) = &opening[3] else {
5211            unreachable!();
5212        };
5213
5214        let close = InstrumentClose::new(
5215            instrument.id(),
5216            Price::from("1.000"),
5217            InstrumentCloseType::ContractExpired,
5218            UnixNanos::from(300),
5219            UnixNanos::from(301),
5220        );
5221        let fill_voided = OrderFillVoidedSpec::builder()
5222            .trader_id(opening_fill.trader_id)
5223            .strategy_id(opening_fill.strategy_id)
5224            .instrument_id(opening_fill.instrument_id)
5225            .client_order_id(opening_fill.client_order_id)
5226            .venue_order_id(opening_fill.venue_order_id)
5227            .account_id(opening_fill.account_id)
5228            .trade_id(opening_fill.trade_id)
5229            .voided_qty(Quantity::from("4.00"))
5230            .order_side(opening_fill.order_side)
5231            .order_type(opening_fill.order_type)
5232            .last_px(opening_fill.last_px)
5233            .currency(opening_fill.currency)
5234            .liquidity_side(opening_fill.liquidity_side)
5235            .position_id(PositionId::from("P-SETTLED"))
5236            .build();
5237        let encoded_close = encode_instrument_close(&close).expect("encode instrument close");
5238        let mut entries: Vec<AppendEntry> = opening
5239            .iter()
5240            .enumerate()
5241            .map(|(index, event)| append_order_event(index as u64 + 1, event))
5242            .collect();
5243        entries.push(append_payload(
5244            5,
5245            PAYLOAD_TYPE_INSTRUMENT_CLOSE,
5246            encoded_close.payload,
5247        ));
5248        entries.extend(
5249            late.iter()
5250                .enumerate()
5251                .map(|(index, event)| append_order_event(index as u64 + 6, event)),
5252        );
5253        entries.push(append_order_event(
5254            10,
5255            &OrderEventAny::FillVoided(fill_voided),
5256        ));
5257        let reader = reader_with_entries("run-settlement-replay", &entries);
5258        let mut cache = Cache::default();
5259        cache.add_instrument(instrument).expect("add instrument");
5260
5261        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
5262        let position = cache
5263            .position_owned(&PositionId::from("P-SETTLED"))
5264            .expect("position replayed");
5265        let late_order = cache
5266            .order_owned(&ClientOrderId::from("O-LATE"))
5267            .expect("late order replayed");
5268        let opening_order = cache
5269            .order_owned(&ClientOrderId::from("O-OPEN"))
5270            .expect("opening order replayed");
5271
5272        assert_eq!(report.applied_entries, 10);
5273        assert_eq!(report.ignored_entries, 0);
5274        assert!(position.is_settled());
5275        assert!(position.is_closed());
5276        assert_eq!(position.quantity, Quantity::from("0.00"));
5277        assert_eq!(position.buy_qty, Quantity::from("10.00"));
5278        assert_eq!(position.realized_pnl, Some(Money::from("6.00 USDC")));
5279        assert!(position.fill_voids.is_empty());
5280        assert_eq!(late_order.status(), OrderStatus::Filled);
5281        assert_eq!(late_order.filled_qty(), Quantity::from("5.00"));
5282        assert_eq!(opening_order.voided_qty(), Quantity::from("4.00"));
5283        assert_eq!(cache.instrument_close(&close.instrument_id), Some(&close));
5284    }
5285
5286    #[rstest]
5287    fn order_fill_void_replay_updates_order_without_position() {
5288        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5289        let initialized = OrderInitializedSpec::builder()
5290            .instrument_id(instrument.id())
5291            .build();
5292        let client_order_id = initialized.client_order_id;
5293        let submitted = OrderSubmittedSpec::builder()
5294            .instrument_id(instrument.id())
5295            .client_order_id(client_order_id)
5296            .build();
5297        let accepted = OrderAcceptedSpec::builder()
5298            .instrument_id(instrument.id())
5299            .client_order_id(client_order_id)
5300            .account_id(submitted.account_id)
5301            .build();
5302        let filled = OrderFilledSpec::builder()
5303            .instrument_id(instrument.id())
5304            .client_order_id(client_order_id)
5305            .venue_order_id(accepted.venue_order_id)
5306            .account_id(submitted.account_id)
5307            .build();
5308        let fill_voided = OrderFillVoidedSpec::builder()
5309            .trader_id(filled.trader_id)
5310            .strategy_id(filled.strategy_id)
5311            .instrument_id(filled.instrument_id)
5312            .client_order_id(filled.client_order_id)
5313            .venue_order_id(filled.venue_order_id)
5314            .account_id(filled.account_id)
5315            .trade_id(filled.trade_id)
5316            .voided_qty(Quantity::from(50_000))
5317            .order_side(filled.order_side)
5318            .order_type(filled.order_type)
5319            .last_px(filled.last_px)
5320            .currency(filled.currency)
5321            .liquidity_side(filled.liquidity_side)
5322            .is_reopened(true)
5323            .build();
5324        let reader = reader_with_entries(
5325            "run-order-only-fill-void-replay",
5326            &[
5327                append_order_event(1, &OrderEventAny::Initialized(initialized)),
5328                append_order_event(2, &OrderEventAny::Submitted(submitted)),
5329                append_order_event(3, &OrderEventAny::Accepted(accepted)),
5330                append_order_event(4, &OrderEventAny::Filled(filled)),
5331                append_order_event(5, &OrderEventAny::FillVoided(fill_voided)),
5332            ],
5333        );
5334        let mut cache = Cache::default();
5335        cache.add_instrument(instrument).expect("add instrument");
5336
5337        let report = replay_cache_snapshot_tail(&mut cache, &reader).expect("replay");
5338        let order = cache.order_owned(&client_order_id).expect("order replayed");
5339
5340        assert_eq!(report.applied_entries, 5);
5341        assert_eq!(report.ignored_entries, 0);
5342        assert_eq!(order.status(), OrderStatus::PartiallyFilled);
5343        assert_eq!(order.filled_qty(), Quantity::from(50_000));
5344        assert_eq!(order.voided_qty(), Quantity::from(50_000));
5345        assert_eq!(cache.positions_total_count(None, None, None, None, None), 0);
5346    }
5347
5348    #[cfg(feature = "defi")]
5349    #[rstest]
5350    #[case::native_instrument(0, "1.000000000000000001", "0.500000000000000001")]
5351    #[case::wei_instrument(18, "1", "0.5")]
5352    #[case::large_native(0, "1000000000000", "999999999999.5")]
5353    fn fill_void_replay_accepts_mixed_qty_scales(
5354        #[case] precision: u8,
5355        #[case] qty: &str,
5356        #[case] remaining: &str,
5357    ) {
5358        let mut instrument = audusd_sim();
5359        instrument.size_precision = precision;
5360        let instrument = InstrumentAny::CurrencyPair(instrument);
5361        let events = binary_order_events(&instrument, "O-MIXED-VOID", qty, "1");
5362
5363        let OrderEventAny::Filled(fill) = &events[3] else {
5364            panic!("Expected fill");
5365        };
5366
5367        let voided_qty =
5368            Quantity::from_decimal_dp("0.5".parse().unwrap(), fill.last_qty.precision.max(1))
5369                .unwrap();
5370        let voided = OrderFillVoidedSpec::builder()
5371            .trader_id(fill.trader_id)
5372            .strategy_id(fill.strategy_id)
5373            .instrument_id(fill.instrument_id)
5374            .client_order_id(fill.client_order_id)
5375            .venue_order_id(fill.venue_order_id)
5376            .account_id(fill.account_id)
5377            .trade_id(fill.trade_id)
5378            .voided_qty(voided_qty)
5379            .order_side(fill.order_side)
5380            .order_type(fill.order_type)
5381            .last_px(fill.last_px)
5382            .currency(fill.currency)
5383            .liquidity_side(fill.liquidity_side)
5384            .maybe_position_id(fill.position_id)
5385            .is_reopened(true)
5386            .build();
5387        let entries = [
5388            append_order_event(1, &events[0]),
5389            append_order_event(2, &events[1]),
5390            append_order_event(3, &events[2]),
5391            append_order_event(4, &events[3]),
5392            append_order_event(5, &OrderEventAny::FillVoided(voided.clone())),
5393        ];
5394        let reader = reader_with_entries("run-mixed-fill-void", &entries);
5395        let mut cache = Cache::default();
5396        cache.add_instrument(instrument).unwrap();
5397
5398        let report = replay_cache_snapshot_tail(&mut cache, &reader).unwrap();
5399
5400        let position = cache.position_owned(&fill.position_id.unwrap()).unwrap();
5401        let order = cache.order_owned(&fill.client_order_id).unwrap();
5402        assert_eq!(report.applied_entries, 5);
5403        assert_eq!(report.ignored_entries, 0);
5404        assert_eq!(position.quantity, Quantity::from(remaining));
5405        assert_eq!(position.signed_qty, Quantity::from(remaining).as_decimal());
5406        assert_eq!(position.realized_pnl, Some(Money::zero(Currency::USD())));
5407        assert_eq!(position.fill_voids.len(), 1);
5408        assert_eq!(position.fill_voids[0].event, voided);
5409        assert_eq!(order.filled_qty(), Quantity::from(remaining));
5410        assert_eq!(order.voided_qty(), voided_qty);
5411    }
5412
5413    #[cfg(feature = "defi")]
5414    #[rstest]
5415    #[case::covered("2", true)]
5416    #[case::uncovered("3", false)]
5417    fn fill_void_fragment_allocation_aligns_native_and_wei_scales(
5418        #[case] voided_qty: &str,
5419        #[case] covered: bool,
5420    ) {
5421        let closing_id = PositionId::from("P-CLOSING");
5422        let opening_id = PositionId::from("P-OPENING");
5423
5424        let fragments = [
5425            FillVoidFragment {
5426                position_id: closing_id,
5427                split_rank: 0,
5428                quantity: Quantity::from("1.00"),
5429                commission: None,
5430            },
5431            FillVoidFragment {
5432                position_id: opening_id,
5433                split_rank: 1,
5434                quantity: Quantity::from("1.000000000000000001"),
5435                commission: None,
5436            },
5437        ];
5438
5439        let event = OrderFillVoidedSpec::builder()
5440            .voided_qty(Quantity::from(voided_qty))
5441            .build();
5442        let entry = append_order_event(1, &OrderEventAny::FillVoided(event.clone())).entry;
5443
5444        let result = allocate_fill_void_fragments(&entry, &event, &fragments);
5445
5446        if covered {
5447            assert_eq!(
5448                result.unwrap(),
5449                IndexMap::from([
5450                    (opening_id, (Quantity::from("1.000000000000000001"), None)),
5451                    (closing_id, (Quantity::from("0.999999999999999999"), None)),
5452                ])
5453            );
5454        } else {
5455            assert!(
5456                matches!(result.unwrap_err(), CacheReplayError::Apply { message, .. } if message.contains("do not cover voided quantity"))
5457            );
5458        }
5459    }
5460
5461    #[rstest]
5462    fn position_lifecycle_replay_preserves_journal_accounting() {
5463        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5464        let position_id = PositionId::from("P-001");
5465        let opened_fill = OrderFilledSpec::builder()
5466            .instrument_id(instrument.id())
5467            .client_order_id(ClientOrderId::from("O-OPEN"))
5468            .venue_order_id(VenueOrderId::from("V-OPEN"))
5469            .trade_id(TradeId::from("T-OPEN"))
5470            .position_id(position_id)
5471            .last_qty(Quantity::from("1"))
5472            .last_px(Price::from("1.00000"))
5473            .build();
5474        let mut live_position = Position::new(&instrument, opened_fill.clone());
5475        let opened_position = live_position.clone();
5476        let opened = PositionOpened::create(
5477            &live_position,
5478            &opened_fill,
5479            UUID4::new(),
5480            UnixNanos::from(10),
5481        );
5482
5483        let changed_fill = OrderFilledSpec::builder()
5484            .instrument_id(instrument.id())
5485            .client_order_id(ClientOrderId::from("O-CHANGE"))
5486            .venue_order_id(VenueOrderId::from("V-CHANGE"))
5487            .trade_id(TradeId::from("T-CHANGE"))
5488            .position_id(position_id)
5489            .last_qty(Quantity::from("2"))
5490            .last_px(Price::from("1.10000"))
5491            .build();
5492        live_position.apply(&changed_fill);
5493        let changed_position = live_position.clone();
5494        let changed = PositionChanged::create(
5495            &live_position,
5496            &changed_fill,
5497            UUID4::new(),
5498            UnixNanos::from(20),
5499        );
5500
5501        let closed_fill = OrderFilledSpec::builder()
5502            .instrument_id(instrument.id())
5503            .client_order_id(ClientOrderId::from("O-CLOSE"))
5504            .venue_order_id(VenueOrderId::from("V-CLOSE"))
5505            .trade_id(TradeId::from("T-CLOSE"))
5506            .order_side(OrderSide::Sell)
5507            .position_id(position_id)
5508            .last_qty(Quantity::from("3"))
5509            .last_px(Price::from("1.20000"))
5510            .build();
5511        live_position.apply(&closed_fill);
5512        let closed = PositionClosed::create(
5513            &live_position,
5514            &closed_fill,
5515            UUID4::new(),
5516            UnixNanos::from(30),
5517        );
5518
5519        let mut cache = Cache::default();
5520        cache
5521            .add_position(&opened_position, OmsType::Unspecified)
5522            .expect("seed opened position");
5523
5524        let opened_entry =
5525            append_position_event(1, &PositionEvent::PositionOpened(opened.clone())).entry;
5526        let changed_entry =
5527            append_position_event(2, &PositionEvent::PositionChanged(changed.clone())).entry;
5528        let closed_entry =
5529            append_position_event(3, &PositionEvent::PositionClosed(closed.clone())).entry;
5530
5531        assert!(apply_cache_replay_entry(&mut cache, &opened_entry).expect("apply opened"));
5532        let replayed = cache
5533            .position_owned(&position_id)
5534            .expect("position after opened");
5535        assert_eq!(replayed.signed_qty, opened.signed_qty);
5536        assert_eq!(replayed.quantity, opened.quantity);
5537        assert_eq!(replayed.ts_last, opened.ts_event);
5538
5539        let fill_entry = append_order_event(2, &OrderEventAny::Filled(changed_fill.clone())).entry;
5540        assert!(apply_fill_to_position(&mut cache, &fill_entry, &changed_fill, false).unwrap());
5541        assert!(apply_cache_replay_entry(&mut cache, &changed_entry).expect("apply changed"));
5542        let replayed = cache
5543            .position_owned(&position_id)
5544            .expect("position after changed");
5545        assert_eq!(replayed.signed_qty, changed.signed_qty);
5546        assert_eq!(replayed.quantity, changed.quantity);
5547        assert_eq!(replayed.peak_qty, changed.peak_quantity);
5548        assert_eq!(replayed.avg_px_open, changed.avg_px_open);
5549        assert!(replayed.is_open());
5550
5551        assert_eq!(
5552            rmp_serde::to_vec_named(&replayed).unwrap(),
5553            rmp_serde::to_vec_named(&changed_position).unwrap()
5554        );
5555        let fill_entry = append_order_event(3, &OrderEventAny::Filled(closed_fill.clone())).entry;
5556        assert!(apply_fill_to_position(&mut cache, &fill_entry, &closed_fill, false).unwrap());
5557        assert!(apply_cache_replay_entry(&mut cache, &closed_entry).expect("apply closed"));
5558        let replayed = cache
5559            .position_owned(&position_id)
5560            .expect("position after closed");
5561        assert_eq!(replayed.signed_qty, closed.signed_qty);
5562        assert_eq!(replayed.quantity, closed.quantity);
5563        assert_eq!(replayed.closing_order_id, closed.closing_order_id);
5564        assert_eq!(replayed.duration_ns, closed.duration);
5565        assert!(replayed.is_closed());
5566        assert!(cache.is_position_closed(&position_id));
5567        assert_eq!(
5568            rmp_serde::to_vec_named(&replayed).unwrap(),
5569            rmp_serde::to_vec_named(&live_position).unwrap()
5570        );
5571    }
5572
5573    #[rstest]
5574    #[case::opened_quantity("opened", "quantity")]
5575    #[case::opened_average("opened", "average")]
5576    #[case::opened_pnl("opened", "pnl")]
5577    #[case::changed_quantity("changed", "quantity")]
5578    #[case::changed_average("changed", "average")]
5579    #[case::changed_pnl("changed", "pnl")]
5580    #[case::closed_quantity("closed", "quantity")]
5581    #[case::closed_average("closed", "average")]
5582    #[case::closed_pnl("closed", "pnl")]
5583    fn position_lifecycle_replay_rejects_inconsistent_accounting(
5584        #[case] kind: &str,
5585        #[case] field: &str,
5586    ) {
5587        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5588        let position_id = PositionId::from("P-001");
5589        let mut fill = OrderFilledSpec::builder()
5590            .instrument_id(instrument.id())
5591            .position_id(position_id)
5592            .last_qty(Quantity::from("1"))
5593            .last_px(Price::from("1.00000"))
5594            .commission(Money::from_str_exact("0.000001 USD").unwrap())
5595            .build();
5596        let mut position = Position::new(&instrument, fill.clone());
5597        if kind == "closed" {
5598            fill.event_id = UUID4::new();
5599            fill.trade_id = TradeId::from("T-CLOSE");
5600            fill.order_side = OrderSide::Sell;
5601            fill.last_px = Price::from("1.00001");
5602            position.try_apply(&fill).unwrap();
5603        }
5604
5605        let mut event = match kind {
5606            "opened" => PositionEvent::PositionOpened(PositionOpened::create(
5607                &position,
5608                &fill,
5609                UUID4::new(),
5610                UnixNanos::from(10),
5611            )),
5612            "changed" => PositionEvent::PositionChanged(PositionChanged::create(
5613                &position,
5614                &fill,
5615                UUID4::new(),
5616                UnixNanos::from(10),
5617            )),
5618            "closed" => PositionEvent::PositionClosed(PositionClosed::create(
5619                &position,
5620                &fill,
5621                UUID4::new(),
5622                UnixNanos::from(10),
5623            )),
5624            _ => unreachable!(),
5625        };
5626
5627        let (quantity, average, pnl) = match &mut event {
5628            PositionEvent::PositionOpened(event) => (
5629                &mut event.signed_qty,
5630                &mut event.avg_px_open,
5631                &mut event.realized_pnl,
5632            ),
5633            PositionEvent::PositionChanged(event) => (
5634                &mut event.signed_qty,
5635                &mut event.avg_px_open,
5636                &mut event.realized_pnl,
5637            ),
5638            PositionEvent::PositionClosed(event) => (
5639                &mut event.signed_qty,
5640                &mut event.avg_px_open,
5641                &mut event.realized_pnl,
5642            ),
5643            PositionEvent::PositionAdjusted(_) => unreachable!(),
5644        };
5645
5646        match field {
5647            "quantity" => *quantity = 9.into(),
5648            "average" => *average = 2.into(),
5649            "pnl" => *pnl = None,
5650            _ => unreachable!(),
5651        }
5652
5653        let mut cache = Cache::default();
5654        cache.add_position(&position, OmsType::Unspecified).unwrap();
5655        let before = rmp_serde::to_vec_named(&position).unwrap();
5656        let entry = append_position_event(1, &event).entry;
5657
5658        let error = apply_cache_replay_entry(&mut cache, &entry).unwrap_err();
5659        let restored = cache.position_owned(&position_id).unwrap();
5660
5661        assert!(
5662            matches!(error, CacheReplayError::Apply { message, .. } if message.contains("accounting differs from journal"))
5663        );
5664        assert_eq!(rmp_serde::to_vec_named(&restored).unwrap(), before);
5665    }
5666
5667    #[rstest]
5668    fn position_adjustment_replay_updates_existing_position() {
5669        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5670        let position_id = PositionId::from("P-001");
5671        let fill = OrderFilledSpec::builder()
5672            .instrument_id(instrument.id())
5673            .position_id(position_id)
5674            .build();
5675        let position = Position::new(&instrument, fill.clone());
5676        let adjustment = PositionAdjusted::new(
5677            fill.trader_id,
5678            fill.strategy_id,
5679            fill.instrument_id,
5680            position_id,
5681            fill.account_id,
5682            PositionAdjustmentType::Funding,
5683            None,
5684            Some(Money::from("2 USD")),
5685            Some(Ustr::from("funding")),
5686            UUID4::new(),
5687            UnixNanos::from(10),
5688            UnixNanos::from(11),
5689        );
5690        let entry = append_position_event(1, &PositionEvent::PositionAdjusted(adjustment)).entry;
5691        let mut cache = Cache::default();
5692        cache
5693            .add_position(&position, OmsType::Unspecified)
5694            .expect("seed position");
5695
5696        let applied = apply_cache_replay_entry(&mut cache, &entry).expect("apply");
5697        let position = cache
5698            .position_owned(&position_id)
5699            .expect("position updated");
5700
5701        assert!(applied);
5702        assert_eq!(position.adjustments, vec![adjustment]);
5703        assert_eq!(position.realized_pnl, Some(Money::from("2 USD")));
5704        assert_eq!(position.ts_last, adjustment.ts_event);
5705    }
5706
5707    #[rstest]
5708    fn position_event_for_unknown_position_is_counted_as_ignored() {
5709        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5710        let position_id = PositionId::from("P-MISSING");
5711        let fill = OrderFilledSpec::builder()
5712            .instrument_id(instrument.id())
5713            .position_id(position_id)
5714            .build();
5715        let position = Position::new(&instrument, fill.clone());
5716        let opened = PositionOpened::create(&position, &fill, UUID4::new(), UnixNanos::from(10));
5717        let entry = append_position_event(1, &PositionEvent::PositionOpened(opened)).entry;
5718        let mut cache = Cache::default();
5719
5720        let applied = apply_cache_replay_entry(&mut cache, &entry).expect("apply");
5721
5722        assert!(
5723            !applied,
5724            "missing position must count as ignored, not applied"
5725        );
5726    }
5727
5728    #[rstest]
5729    fn order_filled_with_no_order_side_is_an_apply_error_not_a_panic() {
5730        // The entry hash proves the stored bytes match what was written, not that the
5731        // producer wrote a valid fill; the legacy sentinel deserializes cleanly and
5732        // without the guard panics deep inside Position/Order application.
5733        let payload = IndexMap::from([("order_side", "NO_ORDER_SIDE")]);
5734        let entry = append_serde_payload(1, PAYLOAD_TYPE_ORDER_FILLED, &payload).entry;
5735        let mut cache = Cache::default();
5736
5737        let err = apply_cache_replay_entry(&mut cache, &entry).expect_err("must reject");
5738
5739        match err {
5740            CacheReplayError::Apply { seq, message, .. } => {
5741                assert_eq!(seq, 1);
5742                assert!(message.contains("NoOrderSide"), "message was: {message}");
5743            }
5744            other => panic!("expected Apply, was {other:?}"),
5745        }
5746    }
5747
5748    #[rstest]
5749    fn duplicate_position_fill_is_not_applied_twice() {
5750        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5751        let position_id = PositionId::from("P-001");
5752        let fill = OrderFilledSpec::builder()
5753            .instrument_id(instrument.id())
5754            .position_id(position_id)
5755            .commission(Money::from("1 USD"))
5756            .build();
5757        let position = Position::new(&instrument, fill.clone());
5758        let entry = append_order_event(1, &OrderEventAny::Filled(fill.clone())).entry;
5759        let mut cache = Cache::default();
5760        cache
5761            .add_position(&position, OmsType::Unspecified)
5762            .expect("seed position");
5763
5764        let applied = apply_fill_to_position(&mut cache, &entry, &fill, false).expect("apply fill");
5765        let position = cache
5766            .position_owned(&position_id)
5767            .expect("position updated");
5768
5769        assert!(
5770            applied,
5771            "duplicate trade within an open episode is the idempotent no-op and counts as applied"
5772        );
5773        assert_eq!(position.event_count(), 1);
5774        assert_eq!(position.trade_ids(), vec![fill.trade_id]);
5775        assert_eq!(position.commissions(), vec![Money::from("1 USD")]);
5776    }
5777
5778    #[rstest]
5779    fn flat_position_with_reused_trade_id_is_ignored_like_live() {
5780        // Live `Position::apply_fill` ignores a fill whose trade id already sits in
5781        // the position's carried replay history, so replay must not skip it early or
5782        // reopen the position either: `apply` ignores it and state matches live.
5783        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5784        let position_id = PositionId::from("P-REOPEN");
5785        let open_fill = OrderFilledSpec::builder()
5786            .instrument_id(instrument.id())
5787            .position_id(position_id)
5788            .order_side(OrderSide::Buy)
5789            .trade_id(TradeId::from("T-1"))
5790            .commission(Money::from("2 USD"))
5791            .build();
5792        let close_fill = OrderFilledSpec::builder()
5793            .instrument_id(instrument.id())
5794            .position_id(position_id)
5795            .order_side(OrderSide::Sell)
5796            .trade_id(TradeId::from("T-2"))
5797            .build();
5798        let mut position = Position::new(&instrument, open_fill);
5799        position.apply(&close_fill);
5800        assert_eq!(position.side, PositionSide::Flat);
5801
5802        let dup_fill = OrderFilledSpec::builder()
5803            .instrument_id(instrument.id())
5804            .position_id(position_id)
5805            .order_side(OrderSide::Buy)
5806            .trade_id(TradeId::from("T-1"))
5807            .commission(Money::from("1 USD"))
5808            .build();
5809        let entry = append_order_event(3, &OrderEventAny::Filled(dup_fill.clone())).entry;
5810        let mut cache = Cache::default();
5811        cache
5812            .add_position(&position, OmsType::Unspecified)
5813            .expect("seed position");
5814
5815        let applied = apply_fill_to_position(&mut cache, &entry, &dup_fill, false).expect("apply");
5816        let position = cache
5817            .position_owned(&position_id)
5818            .expect("position updated");
5819
5820        assert!(
5821            applied,
5822            "a historical duplicate is the idempotent no-op and counts as applied"
5823        );
5824        assert_eq!(position.side, PositionSide::Flat);
5825        assert_eq!(position.event_count(), 2);
5826        assert_eq!(position.trade_ids().len(), 2);
5827        assert_eq!(position.commissions(), vec![Money::from("2 USD")]);
5828    }
5829
5830    #[rstest]
5831    fn fill_for_missing_instrument_is_counted_as_ignored() {
5832        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5833        let position_id = PositionId::from("P-NO-INSTR");
5834        let fill = OrderFilledSpec::builder()
5835            .instrument_id(instrument.id())
5836            .position_id(position_id)
5837            .build();
5838        let entry = append_order_event(1, &OrderEventAny::Filled(fill.clone())).entry;
5839        let mut cache = Cache::default();
5840
5841        let applied = apply_fill_to_position(&mut cache, &entry, &fill, false).expect("apply");
5842
5843        assert!(
5844            !applied,
5845            "a position that cannot open must count as ignored, was claimed applied"
5846        );
5847        assert!(cache.position_owned(&position_id).is_none());
5848    }
5849
5850    #[rstest]
5851    fn corrupt_supported_payload_returns_decode_error() {
5852        let reader = reader_with_entries(
5853            "run-decode-error",
5854            &[append_payload(
5855                1,
5856                PAYLOAD_TYPE_ACCOUNT_STATE,
5857                Bytes::copy_from_slice(&[0xc1]),
5858            )],
5859        );
5860        let mut cache = Cache::default();
5861
5862        let err = replay_cache_snapshot_tail(&mut cache, &reader).expect_err("decode error");
5863
5864        match err {
5865            CacheReplayError::Decode {
5866                seq, payload_type, ..
5867            } => {
5868                assert_eq!(seq, 1);
5869                assert_eq!(payload_type, PAYLOAD_TYPE_ACCOUNT_STATE);
5870            }
5871            other => panic!("expected Decode, was {other:?}"),
5872        }
5873    }
5874
5875    #[rstest]
5876    fn missing_order_event_returns_apply_error() {
5877        let submitted = OrderSubmittedSpec::builder().build();
5878        let reader = reader_with_entries(
5879            "run-apply-error",
5880            &[append_order_event(1, &OrderEventAny::Submitted(submitted))],
5881        );
5882        let mut cache = Cache::default();
5883
5884        let err = replay_cache_snapshot_tail(&mut cache, &reader).expect_err("apply error");
5885
5886        match err {
5887            CacheReplayError::Apply {
5888                seq,
5889                payload_type,
5890                message,
5891            } => {
5892                assert_eq!(seq, 1);
5893                assert_eq!(payload_type, PAYLOAD_TYPE_ORDER_SUBMITTED);
5894                assert!(
5895                    message.contains("not found"),
5896                    "message should include cache apply failure: {message}",
5897                );
5898            }
5899            other => panic!("expected Apply, was {other:?}"),
5900        }
5901    }
5902
5903    #[rstest]
5904    fn restore_cache_from_sealed_run_restores_snapshot_and_tail() {
5905        let tmp = TempDir::new().expect("tempdir");
5906        let run_id = "sealed-replay";
5907        let instance_id = "trader-001";
5908        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5909        let fill = OrderFilledSpec::builder()
5910            .instrument_id(instrument.id())
5911            .position_id(PositionId::from("P-SEALED-REPLAY-1"))
5912            .build();
5913        let position = Position::new(&instrument, fill);
5914        let mut snapshot_cache = Cache::default();
5915        let snapshot_ref = snapshot_cache
5916            .snapshot_position_encoded(&position)
5917            .expect("snapshot position");
5918        let anchored_state = cash_account_state_million_usd("100 USD", "0 USD", "100 USD");
5919        let replayed_state = cash_account_state_million_usd("200 USD", "0 USD", "200 USD");
5920
5921        {
5922            let mut backend = RedbBackend::new(tmp.path().to_path_buf());
5923            backend.open_run(manifest(run_id)).expect("open run");
5924            backend
5925                .append_batch(&[append_account_state(1, &anchored_state)])
5926                .expect("append anchored state");
5927            backend
5928                .record_snapshot_anchor(SnapshotAnchor::new(
5929                    1,
5930                    snapshot_ref.blob_ref.clone(),
5931                    compute_snapshot_content_hash(snapshot_ref.blob.as_ref()),
5932                ))
5933                .expect("record snapshot anchor");
5934            backend
5935                .append_batch(&[append_account_state(2, &replayed_state)])
5936                .expect("append replay tail");
5937            backend.seal(RunStatus::Ended).expect("seal run");
5938        }
5939
5940        let mut cache = Cache::default();
5941        cache
5942            .add(&snapshot_ref.blob_ref, snapshot_ref.blob.clone())
5943            .expect("seed snapshot blob");
5944
5945        let report = restore_cache_from_sealed_run(
5946            &mut cache,
5947            tmp.path().to_path_buf(),
5948            instance_id,
5949            run_id,
5950        )
5951        .expect("restore sealed run");
5952
5953        let frames = cache
5954            .position_snapshot_bytes(&position.id)
5955            .expect("restored position snapshot");
5956        let account = cache
5957            .account_owned(&replayed_state.account_id)
5958            .expect("replayed account");
5959
5960        assert_eq!(report.manifest.run_id, run_id);
5961        assert_eq!(report.manifest.status, RunStatus::Ended);
5962        assert_eq!(report.cache.plan.from_seq, 2);
5963        assert_eq!(report.cache.applied_entries, 1);
5964        assert_eq!(report.cache.ignored_entries, 0);
5965        assert_eq!(frames.len(), 1);
5966        assert_eq!(frames[0].as_slice(), snapshot_ref.blob.as_ref());
5967        assert_eq!(account.events(), vec![replayed_state]);
5968    }
5969
5970    #[rstest]
5971    fn restore_cache_from_sealed_run_rejects_snapshot_hash_mismatch() {
5972        let tmp = TempDir::new().expect("tempdir");
5973        let run_id = "sealed-replay-bad-snapshot";
5974        let instance_id = "trader-001";
5975        let instrument = InstrumentAny::CurrencyPair(audusd_sim());
5976        let fill = OrderFilledSpec::builder()
5977            .instrument_id(instrument.id())
5978            .position_id(PositionId::from("P-SEALED-REPLAY-BAD-SNAPSHOT-1"))
5979            .build();
5980        let position = Position::new(&instrument, fill);
5981        let mut snapshot_cache = Cache::default();
5982        let snapshot_ref = snapshot_cache
5983            .snapshot_position_encoded(&position)
5984            .expect("snapshot position");
5985
5986        {
5987            let mut backend = RedbBackend::new(tmp.path().to_path_buf());
5988            backend.open_run(manifest(run_id)).expect("open run");
5989            backend
5990                .record_snapshot_anchor(SnapshotAnchor::new(
5991                    0,
5992                    snapshot_ref.blob_ref.clone(),
5993                    compute_snapshot_content_hash(snapshot_ref.blob.as_ref()),
5994                ))
5995                .expect("record snapshot anchor");
5996            backend.seal(RunStatus::Ended).expect("seal run");
5997        }
5998
5999        let mut cache = Cache::default();
6000        cache
6001            .add(
6002                &snapshot_ref.blob_ref,
6003                Bytes::from_static(b"tampered snapshot"),
6004            )
6005            .expect("seed tampered snapshot blob");
6006
6007        let err = restore_cache_from_sealed_run(
6008            &mut cache,
6009            tmp.path().to_path_buf(),
6010            instance_id,
6011            run_id,
6012        )
6013        .expect_err("hash mismatch");
6014
6015        match err {
6016            CacheReplayError::SnapshotRestore { blob_ref, message } => {
6017                assert_eq!(blob_ref, snapshot_ref.blob_ref);
6018                assert!(
6019                    message.contains("content_hash mismatch"),
6020                    "message should explain hash mismatch: {message}",
6021                );
6022            }
6023            other => panic!("expected SnapshotRestore, was {other:?}"),
6024        }
6025    }
6026
6027    #[rstest]
6028    fn open_event_store_replay_source_rejects_running_run() {
6029        let tmp = TempDir::new().expect("tempdir");
6030        let run_id = "running-replay";
6031        {
6032            let mut backend = RedbBackend::new(tmp.path().to_path_buf());
6033            backend.open_run(manifest(run_id)).expect("open run");
6034        }
6035
6036        let err = open_event_store_replay_source(tmp.path().to_path_buf(), "trader-001", run_id)
6037            .expect_err("running source must fail");
6038
6039        assert!(
6040            err.to_string().contains("not sealed"),
6041            "error should name sealed-run requirement: {err}",
6042        );
6043    }
6044
6045    #[rstest]
6046    fn validate_event_store_replay_source_rejects_quarantined_run() {
6047        let tmp = TempDir::new().expect("tempdir");
6048        let run_id = "quarantined-replay";
6049        {
6050            let mut backend = RedbBackend::new(tmp.path().to_path_buf());
6051            backend.open_run(manifest(run_id)).expect("open run");
6052            backend
6053                .append_batch(&[append_payload(1, "RunStarted", Bytes::new())])
6054                .expect("append");
6055            backend.seal(RunStatus::Quarantined).expect("seal run");
6056        }
6057
6058        let err =
6059            validate_event_store_replay_source(tmp.path().to_path_buf(), "trader-001", run_id)
6060                .expect_err("quarantined source must fail");
6061
6062        assert!(
6063            err.to_string().contains("quarantined"),
6064            "error should reject quarantined replay sources: {err}",
6065        );
6066    }
6067}