learning_ai_invt_trdg/backend/backtesting.md

Backtesting and Replay v1 (Backend)

Scope

Backtesting v1 is an isolated, read-only simulation pipeline under src/backtest/**. It reuses ProStrategyEngine unchanged and is guarded by feature flag plus mode assertion.

Isolation Guarantees

• Entry path: POST /api/backtest/run only.
• Hard guard: if (mode !== 'backtest') throw.
• No live runtime loop reuse (src/index.ts unchanged).
• No broker order placement (ReplayExchangeConnector.placeOrder() throws).
• No writes to orders, trade_history, or capital_ledgers.
• In-memory virtual ledger only.

Deterministic Replay Rules

• Candles are normalized and strictly sorted by timestamp.
• Timeframes are validated to 15m, 1h, 4h.
• Symbol processing order is lexicographic and stable.
• No randomness in fills/slippage/partials/exit ordering.
• Same input payload produces identical output.

Time-Window Semantics

• Replay window: from_date inclusive to to_date inclusive (UTC).
• Warm-up candles are loaded before from_date where available.
• Trades are evaluated only inside the replay window.
• Default end-of-window behavior: keep open positions as OPEN_AT_END.
• Optional execution override: forceCloseAtWindowEnd=true to close at last candle.

Data Sources

• CSV upload (required in v1): symbol,timeframe,timestamp,open,high,low,close,volume.
• JSON upload (array rows or nested symbol/timeframe maps).
• Replay payload adapter (read-only).
• Kraken historical loader (read-only CCXT OHLC fetch, cached in-memory, no order paths).

API Contract Highlights

BacktestResult includes:

• trades
• summary (netPnlUsd, winRate, maxDrawdownPct, sharpe, totalTrades)
• timeline (equity and drawdown points)
• window (UTC replay window + OPEN_AT_END/FORCE_CLOSE policy)
• warmup
• openPositionsAtEnd
• assumptions
• diagnostics

Feature Flags

• ENABLE_BACKTEST=true
• BACKTEST_CUSTOMER_ENABLED=false (when false, only admins can run backtests)
• BACKTEST_MAX_CSV_BYTES
• BACKTEST_MAX_ROWS

Non-Goals

• Parameter optimization
• ML tuning
• Strategy mutation
• Live/backtest blending
• Broker execution from backtest mode