# Replay data quality and read-only tournament dashboard

Use this reference when extending paper/backtest strategy tournaments for API trading bots.

## Durable lessons

- Historical replay is only as good as its candle coverage. Long-horizon runs must report per-coin data quality: loaded, missing, fresh cache, stale cache, and fetch warnings.
- Exchange candle APIs can rate-limit during multi-coin sweeps. Implement bounded retry with exponential backoff and a stale-cache fallback. Treat stale-cache use as a reportable data-quality flag, not as a silent success.
- Keep replay fetchers dependency-injectable for tests: inject `request_post`, `sleep_fn`, `max_attempts`, and `allow_stale_cache` so 429/retry behavior is unit-tested without network calls.
- A strategy that wins mostly because of one coin is a leakage risk. Add coin-slice reports: all coins, without top contributor, majors only, alts only, and per-coin attribution.
- Parameter sweep winners are paper-only candidates. Register them as challenger presets and keep them in parallel paper tournaments; never promote to live based on replay alone.
- Build a read-only dashboard only after journals/reports exist. It should inspect runtime state and report PIDs, logs, journal counts, closed trades, PnL, replay/sweep/leakage reports, and safety state. It must not include order buttons, config mutation, restarts, or hidden side effects.
- If live paper signals are rare, continue improving replay/data-quality tooling rather than loosening live criteria prematurely.

## Suggested TDD slices

1. Fetcher retry tests: 429 twice then success; network failure falls back to stale cache; no stale cache raises.
2. Coin leakage tests: excluding a top-contributor coin changes ranking/sample counts.
3. Parameter sweep tests: deterministic grid returns ranked variants and preserves base preset metadata.
4. Dashboard tests: temp runtime with fake PID/log/journal/report renders read-only HTML and never contains action language such as order controls.

## Verification

- Run focused tests for each slice, then full suite.
- Compile Python files.
- Scan for `verify=False`, `except Exception: pass`, stale OpenClaw paths, and token-bearing remotes.
- Keep runtime reports/journals under `~/.local/state/<Bot>/`, not Git.