Build 060.30: finalize Market Data Acquisition documentation

docs/architecture/dzentra_target_architecture.md

@@ -6,8 +6,8 @@
 |---|---|
 | Тип | Target Architecture |
 | Статус | Active Baseline |
-| Версия | 1.0 |
-| Дата | 2026-07-31 |
+| Версия | 1.1 |
+| Дата | 2026-08-03 |
 | Проект | Dzentra |
 
 ---
@@ -51,6 +51,12 @@ Dzentra является работающим modular monolith, который
 Любое изменение ownership или направления зависимостей выполняется
 отдельным Build после анализа фактических consumers.
 
+Вертикаль Trades Feed принята от Production Runtime до persistent
+Storage, Startup Recovery, Historical Access и deterministic Replay в
+Builds 060.25–060.29. Build 060.30 актуализировал документацию этого
+состояния. Завершение одной вертикали не означает готовность остальных
+Market Data feeds или всей торговой платформы.
+
 ---
 
 ## 3. Верхнеуровневая карта
@@ -150,7 +156,8 @@ app/src/market_data/acquisition/
 ```
 
 **Текущий активный результат:** Production Runtime для Trades Feed
-завершён в Build 060.25.
+завершён в Build 060.25, а network/fault/stress/soak/live verification —
+в Build 060.26.
 
 ### 4.2. Validation, Canonicalization and Data Quality
 
@@ -195,6 +202,10 @@ Missing Data Recovery не должны смешиваться в один ун
 `TradeStreamState` принадлежит Consistency Layer, а не общему Market
 Data Storage и не WebSocket Transport.
 
+Подтверждённая durable точка восстановления хранится отдельно как
+Persistent Checkpoint. Она восстанавливает operational state после
+перезапуска, но не заменяет долговременную историю рынка.
+
 ### 4.4. Persistent Market Data Storage
 
 **Назначение:** долговременно хранить Canonical Market Data для:
@@ -206,31 +217,106 @@ Data Storage и не WebSocket Transport.
 - backtesting;
 - аудита качества данных.
 
-Хранилище должно определить:
+Build 060.27 реализовал два явно разных слоя:
 
-- raw и canonical retention policy;
-- ключи идемпотентности;
-- порядок и уникальность событий;
-- партиционирование по типу данных, символу и времени;
-- правила исправления и повторной загрузки;
-- provenance и версию Canonical schema.
+```text
+app/src/storage/
+    общий/исторический PostgreSQL foundation, pool и migrations
 
-Существующий `app/src/storage/` нельзя автоматически считать готовым
-Market Data Storage. Его фактические контракты проверяются в
-Build 060.27.
+app/src/market_data/storage/
+    канонические contracts и repositories Market Data
+```
 
-### 4.5. Historical Access and Replay
+Канонический слой содержит idempotent PostgreSQL repositories для
+Trades, Quotes и Candle revisions, provenance, schema versions,
+write-only `MarketDataStorage`, Partition Manager и Retention Service.
+Production writer wiring подключён только для Trades. Существующие REST
+Quotes/Candles обслуживают Trading/UI, но не записываются этими
+persistent repositories автоматически.
 
-**Назначение:**
+Физическое partitioning реализовано отдельным parent/default family для
+каждого типа данных:
 
-- исторические запросы;
-- последовательное воспроизведение Canonical Market Data;
-- управляемые виртуальные часы;
-- одинаковые контракты данных для production и replay consumers;
-- основа backtesting и воспроизводимой диагностики.
+```text
+market_data.trades
+    RANGE (executed_at)
+    ├── trades_default
+    └── trades_YYYY_MM
 
-Replay должен воспроизводить порядок событий и не обходить Canonical
-Models или validation guarantees.
+market_data.quotes
+    RANGE (received_at)
+    ├── quotes_default
+    └── quotes_YYYY_MM
+
+market_data.candle_revisions
+    RANGE (open_time)
+    ├── candle_revisions_default
+    └── candle_revisions_YYYY_MM
+```
+
+`venue` и `symbol` участвуют в identity и queries, но не являются
+уровнями физического partitioning. Месячный child имеет UTC-границы для
+всех venue/symbol соответствующего parent. Partition Manager вызывается
+явно, сериализует создание advisory lock, переносит подходящие строки из
+default partition и регистрирует управляемый child в
+`market_data.partition_registry` в одной транзакции.
+
+Retention также запускается только явно. Он не является Scheduler-задачей
+Production Runtime. Raw storage, automatic partition creation,
+historical backfill и гарантия полноты истории пока не реализованы.
+
+### 4.5. Persistent Checkpoint and Startup Recovery
+
+Build 060.28 реализовал постоянный operational checkpoint Trades:
+
+- identity checkpoint — `(venue, symbol)`;
+- checkpoint ссылается на точную durable Trade;
+- Trade и checkpoint продвигаются в одной PostgreSQL-транзакции;
+- optimistic CAS revision защищает конкурентное продвижение;
+- in-memory state изменяется только после durable commit;
+- Hydration восстанавливает checkpoint и bounded deduplication tail;
+- Startup Recovery заполняет разрыв при закрытом Live gate;
+- buffered live data выпускаются только после успешного Recovery.
+
+Checkpoint существует только для Trades. Он не является второй копией
+истории, не доказывает полноту Storage и не имеет отдельного feature
+flag: persistent checkpoint включается вместе с Market Data Storage.
+
+### 4.6. Historical Access
+
+Build 060.29 создал отдельный synchronous read-side:
+
+```text
+app/src/market_data/access/
+```
+
+Trade, Quote и Candle revision history читаются forward keyset pages.
+Каждый вызов Historical query читает одну текущую committed page;
+единый snapshot между последовательными страницами не гарантируется.
+Access не изменяет durable data или operational checkpoint, вызывается
+явным consumer и не запускается из Bootstrap автоматически.
+
+### 4.7. Deterministic Replay
+
+Replay использует те же Canonical Models, что live processing, и не
+обходит validation guarantees. Migration 9 добавила общий immutable
+`replay_sequence` для Trades, Quotes и Candle revisions. Миграция
+блокирующая и перед большой production-базой требует maintenance window,
+backup и предварительного замера длительности.
+
+Replay Plan Builder материализует bounded snapshot в транзакции
+`READ ONLY REPEATABLE READ`. Превышение `max_records` завершается явной
+ошибкой. Смешанный порядок событий равен
+`(replay_at, replay_sequence)`.
+
+`DeterministicReplayClock` принимает timezone-aware `datetime`,
+канонизирует его в UTC, допускает равное время и запрещает движение
+назад; naive `datetime` запрещён. `ReplaySession` — caller-owned one-shot
+lifecycle с новым графом зависимостей для каждого запуска.
+
+Автоматический Replay startup, default consumer, отдельный Replay
+endpoint, hidden task и historical backfill не реализованы. Backtesting
+может использовать этот фундамент, но сам не входит в Build 060.29.
 
 ---
 
@@ -436,6 +522,11 @@ Backtesting является отдельной capability, но переисп
 
 Отдельная копия торговой логики только для backtest не допускается.
 
+Persistent Storage, Historical Access, Replay Plan, deterministic clock
+и Replay Session уже создают необходимые data/time prerequisites.
+Backtesting engine, exchange/OMS simulator и автоматическая composition
+этой capability пока не реализованы.
+
 ---
 
 ## 8. Правила зависимостей
@@ -485,7 +576,10 @@ order, account и runtime events, а не через обратные импор
 | Market Data Acquisition | `app/src/market_data/acquisition/` |
 | Application Runtime Composition | `app/src/bootstrap/` |
 | Runtime Events | `app/src/runtime_events/` и локальные runtime events |
-| Storage foundation | `app/src/storage/` |
+| Общий/исторический Storage foundation | `app/src/storage/` |
+| Canonical Market Data Storage | `app/src/market_data/storage/` |
+| Historical Market Data Access | `app/src/market_data/access/` |
+| Deterministic Replay | `app/src/market_data/replay/` |
 | Market Intelligence | `app/src/trading/market_intelligence/` |
 | Trading Decision | `app/src/trading/decision/` |
 | Execution | `app/src/trading/execution/` |
@@ -501,9 +595,11 @@ order, account и runtime events, а не через обратные импор
 4. подготовлен отдельный migration plan;
 5. проверено направление импортов.
 
-Предложенные имена вроде `analytics/features`,
-`market_data/normalization` или `market_data/storage` являются
-логическими ориентирами, а не заранее утверждённой файловой структурой.
+Предложенные имена вроде `analytics/features` или
+`market_data/normalization` являются логическими ориентирами, а не
+заранее утверждённой файловой структурой. Каталоги
+`market_data/storage`, `market_data/access` и `market_data/replay` уже
+являются принятыми фактическими boundaries.
 
 ---
 
@@ -511,18 +607,19 @@ order, account и runtime events, а не через обратные импор
 
 | Область | Состояние |
 |---|---|
-| Market Data Acquisition foundation | Реализуется Build-by-Build |
+| Market Data Acquisition foundation | Trades vertical slice завершён; остальные feeds развиваются Build-by-Build |
 | Trades Feed production runtime | Completed — Build 060.25 |
-| Runtime integration/stress verification | Next — Build 060.26 |
-| Persistent Market Data Storage | Planned — Build 060.27 |
-| Persistent Checkpoint / Startup Recovery | Planned — Build 060.28 |
-| Historical Access / Replay | Planned — Build 060.29 |
+| Runtime integration/stress/live verification | Completed — Build 060.26 |
+| Persistent Market Data Storage | Completed — Build 060.27 |
+| Persistent Checkpoint / Startup Recovery | Completed — Build 060.28 |
+| Historical Access / Replay | Completed — Build 060.29 |
+| Market Data Acquisition Final Documentation | Completed — Build 060.30 |
 | Validation ownership audit/refactoring | Planned — Build 061.00 |
 | Market Intelligence | Существующая активная подсистема |
 | Decision / Execution / Position | Существующие подсистемы, требуют будущих boundary audits |
 | OMS / Reconciliation | Целевая ответственность, отдельный план не утверждён |
-| Backtesting | Целевая capability после Storage и Replay |
-| Operations / Deployment | Целевая cross-cutting программа |
+| Backtesting | Storage/Replay prerequisites готовы; capability не реализована |
+| Operations / Deployment | Docker hardening принят; deployment остаётся отдельной cross-cutting программой |
 
 `Completed` означает завершение утверждённого Build, а не окончательную
 сертификацию всей подсистемы для любой production-нагрузки.