# 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