Deterministic Replay

TRADEOS.tech is designed so that any historical sequence of market events can be replayed to produce byte-for-byte identical trading decisions. This is a foundational correctness guarantee, not an optional feature.

What determinism means

Given the same inputs — the same sequence of market data, the same configuration, the same injected clock — the system must produce:

• The same signals
• The same feasibility verdicts
• The same position sizes
• The same fill simulations

Two independent replay runs of the same event sequence must produce SHA-256-identical outputs. This is verified by the CI acceptance gate on every code change.

Why this matters

Post-incident investigation — when a trade behaves unexpectedly, engineers can replay the exact market data sequence that preceded it and reproduce the decision path step-by-step. No guesswork about what the system saw or when.

Regulatory audit — MiFID II, SEC Rule 17a-4, and CFTC Part 1.31 require that trading records be reproducible for examination. Deterministic replay means any auditor can independently verify that the system behaved as claimed on any specific date and time.

Strategy validation — deterministic pipelines produce reliable test results. The same backtest inputs always produce the same outputs, making performance measurement trustworthy.

Regression detection — the replay test suite catches any code change that accidentally alters trading behavior on historical data. Behavioral changes must be intentional and explicitly acknowledged.

The clock abstraction

The primary source of non-determinism in most trading systems is wall clock time — datetime.now() returns a different value on every call. TRADEOS.tech eliminates this by abstracting time behind a Clock interface:

• WallClock — used in live trading; returns actual UTC time
• ReplayClock — used in backtest and replay; returns timestamps from a pre-recorded event sequence

All services receive a Clock instance at startup via dependency injection. No service calls the system clock directly. When the replay harness runs, it injects a ReplayClock that advances in lockstep with the event sequence — so every timestamp in the system corresponds exactly to the timestamp of the event being processed, not the current wall time.

The five determinism rules

All TRADEOS.tech code follows five rules enforced in code review and the CI gate:

1. No direct wall clock calls — always use the injected clock
2. No unseeded random number generation — any stochastic operation uses a seeded RNG; the seed is recorded in the audit ledger
3. No live database reads during replay — state snapshots are injected by the replay harness
4. No ordering assumptions on concurrent tasks — parallel operations produce results in a deterministic order
5. No floating-point equality comparisons — epsilon-based comparison or Decimal arithmetic throughout

CI acceptance gate

Every pull request must pass the replay gate:

./run-tests.sh replay

This runs the replay harness against the golden dataset, then runs it again and compares SHA-256 hashes of all outputs. Any difference between runs is a test failure. PRs that fail the replay gate are blocked from merge.

Relationship to backtest and paper trading

Deterministic replay is distinct from backtesting and paper trading:

Mode	Purpose	Clock	Fills
Replay	CI gate — verify identical outputs	ReplayClock (pre-recorded sequence)	Simulated identically both runs
Backtest	Strategy evaluation on historical data	ReplayClock (real OHLCV history)	ATR-scaled slippage model
Paper trading	Live market validation, no real money	WallClock	Real fills simulated against live order books
Live trading	Real orders, real capital	WallClock	Real fills from exchange

The same signal pipeline code runs in all four modes. The only differences are the clock source and the fill execution path.