--- id: object/90957134-8e8b-021b-717c-e9c7ca6cd887 type: arch role: history representation: canonical state: historical knowledge_schema: 1 _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). ```