Validate Live Decisions with Replay

Replay evaluates a named deployment over historical closed candles. Use it to reproduce the decisions of the exact strategies, versions, configurations, timeframes, accounts, and symbol selections declared for live operation.

Replay is a diagnostic tool. It does not place orders or change the deployment.

Replay a Deployment

Run from the project that contains tradejs.config.ts:

npx @tradejs/cli replay \
  --user root \
  --deployment production \
  --days 7 \
  --cacheOnly

Useful options:

• --startTime and --endTime select an exact Unix timestamp window;
• --tickers, --exclude, and --tickersLimit temporarily change the symbols;
• --cacheOnly prevents a market-history refresh;
• --showTickersList prints the resolved symbols without running replay;
• --chart stores compact charts for the strategies page.

Without a temporary symbol override, replay applies the deployment's symbol selection and any strategy-level selection.tickers limits.

Build a Cached Portfolio Report

Use portfolio-backtest to evaluate the complete configured deployment as one historical portfolio. The command uses the production declaration, cached history, the complete available candle range, and MAX_LOSS_VALUE=10 by default:

npx @tradejs/cli portfolio-backtest --user root

The command processes symbols in bounded batches and then merges completed trades in timestamp order. Use --portfolioBatchSize to change the default batch size of four symbols. You can also pass --tickers to use an explicit symbol set or --portfolioOutputSuffix to keep parallel report files separate.

Reports are written under data/replay/output as HTML, Markdown, JSON, and SVG files. They include full-period and trailing 365, 180, 90, 30, and 7 day metrics. Portfolio rows are split into ALL, LONG, and SHORT, and the report also shows each strategy separately. The command records the source and research composition identifiers, effective strategy configurations, selected symbols, cached candle coverage, and the risk override in its lineage.

Portfolio mode skips live runtime and exchange comparison, and it does not keep detailed signal or skip records. Use normal replay with runtime evidence when you need parity diagnosis.

Capture a Live Runtime Record

For exact comparison, collect a timestamped record on the host where live evaluation ran:

npx @tradejs/cli runtime-evidence \
  --daily \
  --user root \
  --deployment production \
  --publishDir output/runtime-evidence

--daily selects the latest complete 21:00–21:00 Moscow-time window. You can also set --startTime and --endTime, or use --hours for a trailing window. The bundle contains recorded decisions and version metadata, plus a manifest and checksums for integrity verification.

Runtime evidence has one accepted runtime contract:

• the embedded deployment snapshot uses schema v2 and declares the deployment, account, enabled strategies, exact strategy revisions, package versions, and immutable strategy configuration;
• every evaluation, signal, trade, and persisted lineage scope uses runtime lineage schema v3 and matches that embedded composition;
• mutable strategyConfigs and lineage-less evaluationStatsBuckets are not part of the record. Aggregate debug telemetry cannot be attributed to an immutable composition.

The publisher, sync, replay, and scorecard commands reject a record that does not satisfy this contract. They do not translate older runtime formats or infer missing identity from Redis, current source code, or evaluation names.

If the selected window spans more than one deployment composition, publishing resolves every row against the current or a previously published verified snapshot and creates a separate immutable bundle for each deploymentCompositionId. A missing or conflicting snapshot stops publication instead of assigning historical rows to the current composition.

These records can contain sensitive operational information. Restrict access, exclude credentials, and do not commit them to the application repository.

Transfer and Verify a Record

To analyze a record in another project environment:

npx @tradejs/cli runtime-evidence-sync \
  --source user@runtime-host:/path/to/ready/production \
  --deployment production

The command verifies the manifest, payload hashes, and current runtime contract before storing the bundle. Use the project revision with strategy and runtime package versions matching the record. Do not edit the record to work around a mismatch.

Replay the Recorded Setup

npx @tradejs/cli replay \
  --user root \
  --runtimeEvidence <bundle>/runtime-evidence.json \
  --startTime <ms> \
  --endTime <ms> \
  --cacheOnly

Then create a comparison input from the replay result and live record:

npx @tradejs/cli replay-runtime-evidence \
  --runtimeEvidence <bundle>/runtime-evidence.json \
  --startTime <ms> \
  --endTime <ms> \
  --out output/replay-runtime-evidence.json

Use --replayKey if several replay results cover the same window.

The comparison keeps compact runs of closed-candle skip reasons and lists backtest entries excluded by lineage or window scope. This distinguishes a strategy that evaluated and skipped from an entry that was not comparable to the recorded runtime composition.

Compare Execution

Execution calibration compares signal time, market arrival, and fills with the reconstructed decisions:

npx @tradejs/cli execution-calibration \
  --runtimeEvidence <bundle>/runtime-evidence.json \
  --replayEvidence output/replay-runtime-evidence.json \
  --out output/execution-calibration.json

runtime-scorecard combines the live record, replay comparison, and execution calibration into JSON and Markdown diagnostics. Use the report to investigate data gaps, configuration or version differences, gate decisions, timing drift, rejections, and fill quality.

For a quicker entry-only comparison, see Compare live and replayed entries. For the live evaluation lifecycle, see How signals work.