AI trading deterministic replay reconstructs one historical workflow run using its recorded external responses, starting state, event order and software revision. It reuses the model and tool outputs the run actually received, then checks whether the same decisions follow. Calling the model or fetching account data again creates a new experiment. A successful replay explains repeatability under preserved conditions; it does not establish that the original decision was correct.
A trader investigating an unexpected order needs a narrower question than “would this strategy work again?” The useful question is: “Given what this run received and the rules it used, why did it take this branch?” That requires preserving the environment around the decision, including failures and pending work.
Define what replay will repeat
Separate three operations before investigating a run:
- Historical replay: use the original code, state and recorded responses to reproduce the recorded path.
- Frozen-input regression: change a specific rule or parser while holding the recorded evidence fixed. This tests a proposed repair.
- Fresh-data fork: change an input, request a new model response or query current account state. This explores a different situation.
These labels describe this article's investigation method, rather than universal framework terminology. Temporal's workflow documentation describes rebuilding state from ordered event history and reusing recorded Activity results. Its workflow logic must avoid unrecorded changes from clocks, randomness and external calls.
By contrast, LangGraph's time-travel documentation says nodes after a selected checkpoint re-execute, including model calls and API requests, and may return different results. A checkpoint can preserve earlier state while later evidence changes. Check the actual behavior behind a replay button before interpreting the result.
A random seed cannot replace captured responses from outside the workflow. The backtest random-seed guide covers repeatable simulation scenarios; this investigation concerns one observed AI workflow execution.
Package the run as recoverable evidence
Use a replay bundle: an immutable collection of the objects needed to reconstruct the run. A directory of final reports is insufficient if the parser inputs or initial account state are missing.
| Bundle component | Preserve for the historical run | Comparison it enables |
|---|---|---|
| Run identity | Run ID, trigger payload, trigger receipt time, workflow graph and code revision | Confirm the same starting event and branch structure |
| Starting state | Balances used, local reservations, positions, pending work and cached state | Rebuild the decision context before the first step |
| External calls | Ordered request-response pairs, request arguments, response bytes, status, timeout or error, attempt number | Supply the same answer to the same tool call |
| AI boundary | Assembled messages, supplied evidence, tool definitions, model settings and exact returned response | Identify what the model received and what downstream code consumed |
| Execution context | Clock values read, event sequence, configuration, dependency versions and rounding rules | Detect hidden inputs outside the recorded payloads |
| Expected trace | Intermediate state changes, gate outcomes, proposed action and recorded acknowledgements | Locate the first divergence |
Exclude credentials from the bundle and protect account records with access controls and an explicit retention policy. Save recoverable objects alongside hashes. A matching hash can check byte identity, but a hash without the underlying response cannot supply that response during replay. The data-provenance guide covers the separate task of tracing evidence back to its source.
Preserve the exact assembled model input, not just the source documents from which it was built. Retrieval, summarization and truncation can change which passages reach the model; context-window evidence loss explains that boundary. For strict historical replay, return the saved model response rather than asking the model to regenerate it.
Keep schema and parser versions with the payload. A saved response decoded by today's parser may produce a different state even when its bytes match. Use the schema-migration guide when testing compatibility; retain the original decoder for historical reproduction.
A balance-reader bug that a fresh run conceals
Consider a fictional spot-trading workflow with a proposed 300 USDT purchase and a 20 USDT local reservation for another pending action. Its budget rule requires proposed purchase + local reservation ≤ available funds, so it needs 320 USDT. These invented fields and values are a teaching fixture, not an exchange API schema or a KLINEO execution record.
The saved account response contains total: 1000 and available: 200. The original reader mistakenly supplies total funds to the budget gate. During a later investigation, a fresh response shows 600 USDT available. All other fixture rules and state remain unchanged.
| Investigation | Reader and evidence | Funds supplied to gate | Gate result |
|---|---|---|---|
| Original run | Buggy reader; historical response | 1,000 USDT total | Pass: 320 ≤ 1,000 |
| Strict historical replay | Same reader; same historical response | 1,000 USDT total | Same pass reproduced |
| Frozen-input regression | Corrected reader; historical response | 200 USDT available | Reject: 320 > 200 |
| Fresh-data fork | Corrected reader; new response | 600 USDT available | Pass: 320 ≤ 600 |
The original run lacked 320 − 200 = 120 USDT under its stated budget rule. Reproducing the pass confirms that the original implementation repeats its mistake. The frozen-input regression shows that the corrected reader rejects this particular case. The fresh-data fork passes legitimately under different evidence and therefore cannot demonstrate that the historical mistake was repaired.
Compare the response bytes first, then the parsed funds value, then the budget operands, then the gate result. Here the first meaningful difference between original and corrected code is the parsed field. Starting with the final order outcome would obscure that cause.
This fixture tests a gate only. A pass does not establish exchange acceptance, a fill, adequate collateral for another product or profitable execution.
Stop at an unrecorded boundary
Match recorded calls using stable identities that include the workflow step, request arguments and attempt. Matching only an endpoint can return the wrong response when two branches request different symbols, or when a retry follows a timeout. Preserve the timeout and its place in the sequence: replacing it with the later successful response changes the path.
If a response is missing, halt the strict replay with an explicit incomplete-record result. Quietly calling the live endpoint substitutes new evidence. Similarly, preserve concurrent-event ordering and state-merge rules; identical responses arriving in a different order can alter a reservation or branch outcome.
Run the investigation with external writes disabled. Reproduce proposed order requests and compare them with the historical trace; supply saved acknowledgements as evidence. Do not resend an order, cancellation, notification or withdrawal to recreate its history. If the original acknowledgement is missing, preserve that uncertainty. This historical check supplies no new authorization; human approval concerns an exact actionable plan.
Compare identities and discrete decisions exactly. Declare any tolerance for calculated numbers before the check, and reject a tolerance that changes whether a threshold passes. Store the expected trace separately from the new result so a failed comparison cannot overwrite its reference.
What the result can support
A useful investigation receipt names the run, bundle hash, replay mode, code revision, comparisons performed and first divergence. Record missing responses and suppressed writes. A changed-code regression or fresh-data fork gets its own identity and points back to the historical run.
The defensible conclusion is bounded: this preserved run repeated, or it diverged at this recorded step. Replay cannot recover an input that was never captured, prove a source was truthful, or validate the trading idea. It provides a controlled way to inspect the decision that actually happened.
This AI-assisted article uses the linked primary framework documentation. The balance fixture and replay worksheet are original educational examples. No trading run or KLINEO replay feature was tested; the worksheet describes a general investigation method under the editorial policy.