Historical Data Foundation V2 + M12/M13 Shared Repository Schritt 1: Meilenstein-Doku (Architecture-Closeout) - Geändert von Rain Ocampo, 22.08.2026

notes/trading/system-docs/historical-v2-foundation-milestone.md

@@ -0,0 +1,146 @@
+---
+type: Trading-Modul-System
+_organized: true
+---
+
+# Historical Data Foundation V2 + M12/M13 Shared Repository — Meilenstein
+
+> **Meilenstein:** Historical Data Foundation V2 + M12/M13 Shared Repository Schritt 1
+> **Stand:** 22.08.2026 | **Autor:** Rain Ocampo (Hermes)
+> **Status:** ✅ Schritt 1 fachlich abgeschlossen + verifiziert. Phase 2 NICHT begonnen.
+
+---
+
+## 1. Architektur-Überblick
+
+Zwei getrennte Systeme, die über eine gemeinsame Repository-Schicht verbunden sind:
+
+- **Historical-Service V2** (`/opt/historical-v2/`, Container `historical-service` + `historical-db`): Dukascopy-basierte historische Marktdaten mit Dataset-Versionierung, Quality-/Session-/Eligibility-Modellen, Fixture-Trennung.
+- **M12/M13** (`Modul-12-Backtesting`, `Modul-13-Optimization`): Backtesting + Optimization, lesen Marktdaten über die gemeinsame `HistoricalRepository`-Schicht.
+
+**Netzwerk-Grenze (aktuell):** historical-db (10.0.8.2, Netz `f2afda69`) und M12/M13 (10.0.13.x, Netz `c17337ef`) liegen in **verschiedenen Docker-Netzwerken** — die Produktiv-Container erreichen die historical-db NICHT. Für Schritt 1 korrekt: Produktiv bleibt auf Legacy. V2 wurde lokal via SSH-Port-Forward gegen die echte DB getestet.
+
+---
+
+## 2. Dataset-Versioning
+
+- `dataset_version`-Tabelle: `dataset_version_id`, `version_label`, `dataset_version_hash`, `feed_type`, `provider_id`, `instrument_id`, `timeframe`, `start_utc`, `end_utc`, `raw_source`, `normalization_version`, `aggregation_version`, `quality_version`, `data_as_of`, `quality_model_version`, `stale_model_version`, `session_model_version`, `calendar_version`, `eligibility_model_version`, `is_fixture`.
+- **`dataset_version_hash`** = deterministischer SHA-256 über die vollständige DatasetSpec (provider, feed, instrument, timeframe, start, end, raw_source, norm_version, quality_version, aggregation_version, raw_or_derived, raw_source_hash, quality_model_version, stale_model_version, session_model_version, calendar_version, eligibility_model_version).
+- Gleiche Spec → identischer Hash; andere Version → anderer Hash. **Hash-Identität** (kryptografisch) und **Auditierbarkeit** (menschenlesbare Versionen als Run-Metadaten) sind getrennt zu betrachten.
+
+---
+
+## 3. Dukascopy-Befunde
+
+- Nur EURUSD, nur Dukascopy, nur Historical-V2-Stack.
+- Bid+Ask-OHLC, H4 = HOUR_4 nativ.
+- Range > ~5000 → 0 (Datenlücke).
+- Historical-Allowance zählt Datenpunkte wöchentlich (~10k).
+
+---
+
+## 4. Session / Quality / Eligibility
+
+- `historical_bar` trägt pro Bar: quality_status, quality_flags, session_state, session_phase, eligibility, exclusion_reason, technical_quality, market_quality.
+- `dataset_version` trägt die Modell-Versionen (quality_model_version, session_model_version, calendar_version, eligibility_model_version, stale_model_version).
+- **Aktuell (Schritt 1):** Diese Felder werden von der Repository-Schicht **noch NICHT** an M12/M13 propagiert (nur OHLCV + Dataset-Metadaten). → Phase-2-Requirement R5.
+
+---
+
+## 5. Fixture-Trennung
+
+- `is_fixture`-Marker auf `dataset_version`-Ebene (Migration 06).
+- Repository-V2-Query filtert hart `AND dv.is_fixture = FALSE`.
+- **Lücke:** Kein explizites Config-Gate `ALLOW_FIXTURE_DATA` (Default `false`). → Phase-2-Requirement R4.
+
+---
+
+## 6. Daily Quality
+
+- Daily-Quality-Report-Pipeline vorhanden (Foundation-Suite).
+- Quality-/Coverage-Status wird pro Bar erfasst, aber noch nicht bis zum Backtest propagiert.
+
+---
+
+## 7. Shared Repository (M12/M13 Schritt 1)
+
+- **Befund:** `historical_repository.py` existiert als **zwei physisch getrennte Kopien** (M12 + M13, identischer Hash `bc64638b…`). Kein gemeinsames Paket/Volume.
+- **Drift-Risiko:** Kein Mechanismus erzwingt Identität → künftige Änderungen können auseinanderlaufen.
+- **Zielstruktur (Phase-2-Requirement R1):** Gemeinsames `shared/historical`-Paket als EINE Quelle, beide Module importieren daraus. Keine neue Kopierlösung.
+- Interface `load_candles(symbol, timeframe, start_date, end_date, provider, asset_class)` unverändert; M12 `data_hash()` erhalten.
+
+---
+
+## 8. Legacy/V2 Gate
+
+- `HISTORICAL_DATA_SOURCE` (env), **Default = `legacy`** (liest `ohlcv` aus trading-DB, Modul-01).
+- `historical_v2` nur explizit aktivierbar. Kein stiller Wechsel.
+- FAIL-CLOSED: unbekannte Quelle → Fehler, kein stiller Fallback.
+
+---
+
+## 9. M13 Hash
+
+- `compute_run_hash` erweitert um `dataset_version_id`, `dataset_version_hash`, `provider`, `feed_type` (nur bei V2).
+- Bei Legacy (Default) → unverändert, keine Cache-Invalidierung bestehender Runs.
+- **Hash-Audit:** `dataset_version_hash` deckt kryptografisch alle Versionen ab (bewiesen über Code + Tests). Entscheidung: **A** — Hash reicht für Identität, Versionen zusätzlich als Run-Metadaten (Phase-2-Requirement R3).
+
+---
+
+## 10. Aktuelle Netzwerkgrenze
+
+- historical-db (10.0.8.2) und M12/M13 (10.0.13.x) in verschiedenen Docker-Netzwerken.
+- Produktiv-Container erreichen historical-db NICHT (timeout, verifiziert).
+- **Empfohlene Service Boundary (Phase-2-Requirement R2):** B — M12/M13 → Historical-Service API → historical-db. Dedizierter Bulk-Bars-Endpoint mit Dataset-Version + Quality/Eligibility-Metadaten. Kein direkter DB-Zugriff aus M12/M13.
+
+---
+
+## 11. Bekannte offene Punkte
+
+- Shared-Repository als EINE Quelle (R1) — noch 2 Kopien.
+- Service-Boundary B (R2) — noch direkte DB-Logik.
+- Run-Metadaten-Persistenz (R3) — noch nicht.
+- Fixture-Safety-Gate (R4) — noch nicht.
+- Quality/Coverage-Propagation (R5) — noch nicht.
+- Bid/Ask-Fill, Spread, Slippage, Kosten — Phase 2.
+
+---
+
+## 12. Phase-2-Plan
+
+Phase 2 wird getrennt behandeln (NICHT implementiert):
+
+| ID | Thema |
+|----|-------|
+| A | Run-Metadaten-Persistenz |
+| B | echte Bid/Ask-Bar-Verarbeitung |
+| C | Fill-Modell |
+| D | variable reale Spreads |
+| E | Slippage-Modell |
+| F | Broker-/Trading-Kosten |
+| G | Intrabar-Ambiguität M1 |
+| H | Feed-Type BROKER vs REFERENCE |
+| I | Fixture-Safety |
+| J | Quality/Coverage-Safety |
+| K | M13-Reproduzierbarkeit |
+| L | Legacy-Kompatibilität |
+
+**Reihenfolge-Vorschlag:** I → J → A → B/C/D/E/F → G → H → K → L.
+
+---
+
+## 13. Status / Freigaben
+
+- **M12/M13 Schritt 1:** ✅ fachlich abgeschlossen + verifiziert (Tests A–J grün, M12 12/12 grün, Foundation-Suite 21/21 zweimal).
+- **Deploy:** Code-Identität lokal = VPS = Container (sha256 identisch), Container-Restart, Smoke-Tests grün.
+- **Phase 2:** ⛔ NICHT begonnen (explizite Freigabe erforderlich).
+- **Grenzen:** nur EURUSD, nur Dukascopy, nur Historical-V2-Stack; keine Produktivmodule M03–M19; keine IG-Calls/Orders; kein Jahresbackfill; M20–M25 nicht beginnen.
+
+---
+
+## Geändert
+```
+Geändert von: Rain Ocampo
+Datum: 22.08.2026
+Grund: Meilenstein-Doku Historical Data Foundation V2 + M12/M13 Shared Repository Schritt 1 angelegt (Architecture-Closeout).
+```