State Machine

The core principle is that an order can only exist in one state at a time and can only transition to another state via a predefined, valid path. This eliminates ambiguous order statuses. For example:

• A PENDING order can transition to WORKING or REJECTED.
• A WORKING order can transition to PARTIALLY_FILLED or CANCELLED.
• A PARTIALLY_FILLED order can transition to FILLED or CANCELLED.
• A FILLED or CANCELLED order is a terminal state and cannot transition further. This strict logic prevents an order from, for example, being cancelled after it has already been fully filled, a common source of simulation bugs.

Transitions are not arbitrary; they are triggered by specific events within the simulation loop. A state machine listens for these events and executes the corresponding transition logic. Key triggers include:

• New Order Request: Initializes the state machine in the PENDING state.
• Order Accepted by Exchange: Transitions from PENDING to WORKING.
• Trade Notification: Transitions from WORKING to PARTIALLY_FILLED or FILLED, depending on the executed quantity versus the total order quantity.
• Cancel Request: Transitions from WORKING or PARTIALLY_FILLED to CANCELLED.
• Rejection Notice: Transitions from PENDING to REJECTED.

Each state is not just a label; it's an object that encapsulates the data and behavior relevant to that specific phase of the order's life. This follows the State Pattern from object-oriented design. For instance:

• The WORKING state object holds the logic for handling a partial fill and calculating the remaining quantity.
• The FILLED state object holds the final average execution price and the complete list of fill timestamps.
• The CANCELLED state object stores the timestamp of the cancellation confirmation and the reason code. This encapsulation keeps the order object clean and avoids complex, monolithic conditional logic.

A state machine creates a complete, immutable audit trail of an order's lifecycle. Every state transition is logged with a timestamp and the triggering event. This is critical for:

• Debugging: A developer can replay the exact sequence of events that led to an unexpected order state.
• Compliance: The log provides a regulatory-grade record of order handling, proving that no look-ahead or other biases were introduced.
• Deterministic Replay: By re-feeding the same sequence of events, the state machine will produce the exact same state transitions, ensuring that backtests are perfectly reproducible.

In a high-fidelity, event-driven backtest, multiple events for the same order can arrive in the same simulated time step. The state machine's design must be thread-safe and handle these potential race conditions deterministically. For example, if a Cancel Request and a Trade Notification arrive simultaneously for a WORKING order, the engine must have a predefined rule (e.g., exchange priority rules) to decide which event is processed first. The state machine enforces this by processing events from a priority queue and locking the order object during a transition, ensuring a consistent and correct final state.

The state machine pattern elegantly extends to model the lifecycle of complex, multi-leg orders. A parent order (e.g., a 'Bracket Order' with a take-profit and stop-loss) can be modeled as a composite state machine. Its states (INACTIVE, WORKING, ONE_LEG_FILLED, COMPLETED) manage the creation, cancellation, and state monitoring of its child orders. When one child leg is filled, it triggers an event that transitions the parent state machine, which in turn cancels the other child leg. This hierarchical state management is essential for accurately simulating sophisticated execution algorithms.

The computational paradigm underlying event-driven backtesting where the system state changes instantaneously at discrete points in time. A state machine governs how entities react to these events.

• Processes events chronologically from a priority queue
• Eliminates look-ahead bias by only processing information available at that timestamp
• Each event triggers a state transition in the affected order or portfolio object

A high-fidelity simulation technique that reconstructs the historical limit order book at every price level. The state machine uses this depth to determine fill probability and queue position.

• Tracks bid/ask volumes across multiple price levels
• Models price-time priority for realistic queue mechanics
• Essential for testing execution algorithms against authentic liquidity dynamics

The deterministic logic within a backtesting engine that decides if a simulated order transitions from PENDING to FILLED or PARTIALLY_FILLED. The state machine evaluates available volume, order book depth, and aggressor-vs-resting classification.

• Matches market orders against resting limit orders
• Applies pro-rata or price-time matching algorithms
• Generates synthetic fill prices based on bid-ask spread at event time

A strategy characteristic where the current trading decision depends on the exact sequence of prior state transitions. The state machine must preserve order history precisely.

• A partially filled order changes the remaining quantity for subsequent decisions
• Cancellation of a parent order must cascade to child bracket orders
• Requires immutable event sourcing for audit trail reconstruction

The ability to reproduce an identical backtest result by fixing random seeds and event timestamps. The state machine must be purely functional with no external side effects.

• All randomness is seeded and logged
• Event timestamps are sourced from a single synchronized clock
• Enables full debugging reproducibility and regulatory audit compliance

An initial segment of historical data excluded from performance metrics, used to populate the state machine with valid indicator values and portfolio positions before the official evaluation window.

• Prevents cold-start artifacts in moving averages and volatility estimates
• Allows the state machine to reach a steady operational state
• Typically 10-20% of the total historical dataset length