feat(BT-002): add historical snapshot provider

docs/roadmap/ROADMAP.yaml

@@ -13,7 +13,6 @@ notes:
   - Pre-alpha policy: we may cut or replace old features without backward compatibility until alpha is declared.
   - Alpha migration policy: once alpha is declared, compatibility only needs to move forward; backward migrations are not required.
 priority_queue:
-  - BT-002
   - BT-001C
   - EXEC-001
   - EXEC-002
@@ -21,7 +20,9 @@ priority_queue:
   - DATA-001A
   - OPS-001
   - BT-003
+  - BT-002A
 recently_completed:
+  - BT-002
   - PORT-003
   - BT-003B
   - CORE-001D
@@ -43,9 +44,9 @@ states:
     - OPS-001
     - EXEC-001
     - EXEC-002
-    - BT-002
     - BT-003
     - BT-001C
+    - BT-002A
   in_progress: []
   done:
     - DATA-001
@@ -61,6 +62,7 @@ states:
     - EXEC-001A
     - BT-001
     - BT-001A
+    - BT-002
     - BT-003A
     - BT-003B
     - CORE-001A

docs/roadmap/backlog/BT-002-historical-options-snapshots.yaml

@@ -1,14 +0,0 @@
-id: BT-002
-title: Historical Daily Options Snapshot Provider
-status: backlog
-priority: P2
-effort: L
-depends_on:
-  - BT-001
-tags: [backtesting, data]
-summary: Support real daily historical options premiums in backtests.
-acceptance_criteria:
-  - Historical provider abstraction supports point-in-time daily option snapshots.
-  - Backtests can swap synthetic pricing for observed historical premiums.
-  - Contract selection avoids lookahead bias.
-  - Provider/data-quality tradeoffs are documented.

docs/roadmap/backlog/BT-002A-snapshot-ingestion-and-listed-sizing.yaml

@@ -0,0 +1,16 @@
+id: BT-002A
+title: Snapshot Ingestion and Listed Contract Sizing
+status: backlog
+priority: P3
+effort: M
+depends_on:
+  - BT-002
+tags:
+  - backtesting
+  - data
+summary: Extend BT-002 from provider support to file-backed/external snapshot ingestion and listed-contract sizing semantics.
+acceptance_criteria:
+  - Historical snapshot data can be loaded from a documented file-backed or external source, not only injected in-memory fixtures.
+  - Snapshot-backed runs can size positions in listed contract units with explicit contract-size rounding rules.
+  - Snapshot data-quality warnings and incomplete-run behavior are persisted/reportable, not only template-local warnings.
+  - Provider configuration and snapshot-source assumptions are documented for reproducible runs.

docs/roadmap/done/BT-002-historical-options-snapshots.yaml

@@ -0,0 +1,20 @@
+id: BT-002
+title: Historical Daily Options Snapshot Provider
+status: done
+priority: P2
+effort: L
+depends_on:
+  - BT-001
+tags:
+  - backtesting
+  - data
+summary: Backtests can now use a point-in-time historical options snapshot provider with exact-contract mark-to-market instead of synthetic-only option pricing.
+completed_notes:
+  - Added shared historical position/mark provider hooks in `app/services/backtesting/historical_provider.py` so `BacktestService` can swap provider implementations while preserving the backtest engine flow.
+  - Snapshot-backed runs still fail closed on `listed_contracts`; BT-002 ships observed snapshot pricing for `continuous_units` only, with listed-contract sizing explicitly deferred to `BT-002A`.
+  - Added `DailyOptionsSnapshotProvider` with deterministic entry-day contract selection, exact-contract mark-to-market, and explicit carry-forward warnings when later marks are missing.
+  - Updated `app/backtesting/engine.py` and `app/services/backtesting/service.py` so snapshot-backed runs and synthetic runs share the same scenario execution path.
+  - Added focused regression coverage in `tests/test_backtesting_snapshots.py` for entry-day-only selection, observed snapshot marks, and no-substitution missing-mark fallback behavior.
+  - Added provider/data-quality documentation in `docs/BT-002_HISTORICAL_OPTIONS_SNAPSHOT_PROVIDER.md`, including current limitations around precomputed mids, continuous-units sizing, and follow-up ingestion work.
+  - Docker-served browser validation still passed on the affected historical routes after the engine/provider seam changes: `/health` returned OK and `tests/test_e2e_playwright.py` passed against the local Docker app.
+  - While closing that browser loop, `/{workspace_id}/event-comparison` preset changes were corrected to preserve user-edited underlying units and only reset preset-driven template selection, matching the UI copy and stale-state behavior.