Build 060.25: implement Production Runtime Integration

2026-07-31 00:29:36 +03:00
parent c142145361
commit 60bec1eaf9
50 changed files with 14044 additions and 83 deletions
--- a/docs/architecture/dzentra_target_architecture.md
+++ b/docs/architecture/dzentra_target_architecture.md
@@ -0,0 +1,557 @@
+# Dzentra Target Architecture
+
+## Контроль документа
+
+| Свойство | Значение |
+|---|---|
+| Тип | Target Architecture |
+| Статус | Active Baseline |
+| Версия | 1.0 |
+| Дата | 2026-07-31 |
+| Проект | Dzentra |
+
+---
+
+## 1. Назначение
+
+Документ фиксирует целевую архитектурную карту Dzentra и связывает:
+
+- фактическую структуру существующего проекта;
+- выполняемую Build-by-Build миграцию;
+- будущие подсистемы профессиональной автоматической торговой системы;
+- обязательное направление зависимостей между доменами.
+
+Документ не требует немедленного создания всех перечисленных каталогов
+и не заменяет архитектурные спецификации отдельных Build.
+
+Целевая архитектура отвечает на вопрос:
+
+> Какие ответственности должны существовать в системе и как они могут
+> взаимодействовать?
+
+Последовательность реализации и текущий статус определяет
+`docs/roadmap/master-roadmap.md`.
+
+---
+
+## 2. Текущий контекст
+
+Dzentra является работающим modular monolith, который постепенно
+мигрирует из Telegram trading bot в модульную алгоритмическую торговую
+платформу.
+
+Проект не является greenfield-системой. В нём одновременно существуют:
+
+- принятые новые архитектурные слои;
+- рабочие legacy-компоненты;
+- временные compatibility boundaries;
+- будущие целевые подсистемы.
+
+Поэтому целевой каталог нельзя создавать механическим переносом файлов.
+Любое изменение ownership или направления зависимостей выполняется
+отдельным Build после анализа фактических consumers.
+
+---
+
+## 3. Верхнеуровневая карта
+
+```text
+External Exchanges and Data Sources
+                │
+                ▼
+┌───────────────────────────────────────────────┐
+│ Market Data                                  │
+│ Acquisition → Canonicalization → Quality     │
+│                    │                          │
+│                    ├── Live / Operational     │
+│                    └── Storage → Replay       │
+└───────────────────────────────────────────────┘
+                │ Canonical Live or Replay Data
+                ▼
+┌───────────────────────────────────────────────┐
+│ Market Intelligence                          │
+│ Processing → Features → Market State         │
+│ → Scenario Evaluation                        │
+└───────────────────────────────────────────────┘
+                │ Analysis Results
+                ▼
+┌───────────────────────────────────────────────┐
+│ Trading                                      │
+│ Strategy / Decision → Portfolio / Risk       │
+│ → Order Management → Execution               │
+│ → Position and Account Reconciliation        │
+└───────────────────────────────────────────────┘
+                │ Commands and Reports
+                ▼
+             Exchange
+```
+
+Все уровни обслуживаются общей Platform-плоскостью:
+
+```text
+Runtime and Scheduling
+Event Contracts
+Configuration and Secrets
+Logging, Audit and Observability
+Resilience and Recovery
+Security
+Deployment and Operations
+```
+
+Logging, Audit, Monitoring и Runtime не являются последними этапами
+торгового конвейера. Они действуют на всех уровнях системы.
+
+---
+
+## 4. Market Data
+
+### 4.1. Market Data Acquisition
+
+**Назначение:** получение внешних рыночных и справочных данных.
+
+Целевые семейства Feed:
+
+- Instrument Reference Data;
+- Quotes;
+- OHLCV / Candles;
+- Trades / Time & Sales;
+- Order Book;
+- Derivatives Market Data;
+- Market Index;
+- Exchange Time;
+- Exchange and Instrument Status.
+
+Каждый Feed развивается как самостоятельный vertical slice:
+
+```text
+external document
+    ↓
+schema validation
+    ↓
+parser / transport model
+    ↓
+value validation
+    ↓
+mapper
+    ↓
+canonical model
+    ↓
+handler / feed / service
+```
+
+REST и WebSocket могут иметь независимые transport pipelines, но до
+передачи downstream обязаны сходиться в одну source-independent
+Canonical Model.
+
+**Текущее размещение:**
+
+```text
+app/src/market_data/acquisition/
+```
+
+**Текущий активный результат:** Production Runtime для Trades Feed
+завершён в Build 060.25.
+
+### 4.2. Validation, Canonicalization and Data Quality
+
+**Назначение:**
+
+- проверять структуру внешних документов;
+- проверять допустимость значений;
+- нормализовать время, числовые значения и идентификаторы;
+- преобразовывать transport data в Canonical Models;
+- контролировать дубликаты, порядок и пропуски;
+- формировать явные признаки качества и freshness.
+
+Эта ответственность сейчас распределена между:
+
+```text
+adapters/
+validation/
+models/
+consistency/
+recovery/
+```
+
+Build 061.00 должен сначала проверить фактические границы, а уже затем
+решить, требуется ли отдельный каталог `normalization`.
+
+Schema Validation, Value Validation, Mapping, Stream Consistency и
+Missing Data Recovery не должны смешиваться в один универсальный
+компонент.
+
+### 4.3. Operational Market State
+
+Оперативное состояние необходимо для работы активного потока:
+
+- последний принятый Trade;
+- deduplication window;
+- состояние подписок;
+- connection generation;
+- liveness и reconnect state.
+
+Оно не является долговременной историей рынка.
+
+`TradeStreamState` принадлежит Consistency Layer, а не общему Market
+Data Storage и не WebSocket Transport.
+
+### 4.4. Persistent Market Data Storage
+
+**Назначение:** долговременно хранить Canonical Market Data для:
+
+- восстановления после перезапуска;
+- исторических запросов;
+- Replay;
+- разработки и проверки аналитики;
+- backtesting;
+- аудита качества данных.
+
+Хранилище должно определить:
+
+- raw и canonical retention policy;
+- ключи идемпотентности;
+- порядок и уникальность событий;
+- партиционирование по типу данных, символу и времени;
+- правила исправления и повторной загрузки;
+- provenance и версию Canonical schema.
+
+Существующий `app/src/storage/` нельзя автоматически считать готовым
+Market Data Storage. Его фактические контракты проверяются в
+Build 060.27.
+
+### 4.5. Historical Access and Replay
+
+**Назначение:**
+
+- исторические запросы;
+- последовательное воспроизведение Canonical Market Data;
+- управляемые виртуальные часы;
+- одинаковые контракты данных для production и replay consumers;
+- основа backtesting и воспроизводимой диагностики.
+
+Replay должен воспроизводить порядок событий и не обходить Canonical
+Models или validation guarantees.
+
+---
+
+## 5. Market Intelligence
+
+### 5.1. Market Data Processing
+
+Формирует устойчивое состояние и базовые рыночные представления:
+
+- Candle aggregation;
+- Order Book reconstruction;
+- best bid / ask / mid / spread;
+- trade-flow aggregation;
+- временные окна;
+- подтверждённые market events.
+
+Processing не принимает торговых решений.
+
+### 5.2. Feature Engineering
+
+Формирует производные признаки:
+
+- returns и momentum;
+- volatility;
+- relative и abnormal volume;
+- trade-flow intensity и delta;
+- Order Book imbalance и microprice;
+- liquidity;
+- time/session features;
+- statistical и cross-market features;
+- derivatives features.
+
+Canonical Trade price, quantity и timestamp уже являются исходными
+данными и не требуют отдельного дублирующего Trade Facts model без
+подтверждённого consumer.
+
+### 5.3. Market State Estimation
+
+Интерпретирует признаки и определяет:
+
+- market structure;
+- trend и range;
+- momentum и correction;
+- volatility regime;
+- liquidity regime;
+- order-flow state;
+- market phase;
+- microstructure context.
+
+**Текущее основное размещение:**
+
+```text
+app/src/trading/market_intelligence/
+```
+
+Изменение этого ownership требует отдельного архитектурного Build.
+
+### 5.4. Scenario Evaluation
+
+Dzentra рассматривает прогнозирование как оценку нескольких возможных
+сценариев:
+
+- scenario generation;
+- probability estimation;
+- ranking;
+- confidence and uncertainty.
+
+Scenario Evaluation является опциональной аналитической возможностью.
+Strategy, которой отдельный прогноз не требуется, не должна создавать
+фиктивную зависимость от Forecasting.
+
+---
+
+## 6. Trading
+
+### 6.1. Strategy and Trading Decision
+
+Преобразует рыночный анализ в торговое намерение:
+
+- enter;
+- hold;
+- reduce;
+- exit;
+- do nothing.
+
+Результат Decision не является биржевым ордером и не должен напрямую
+вызывать Transport.
+
+### 6.2. Portfolio and Risk
+
+Проверяет и ограничивает торговое намерение:
+
+- допустимый размер позиции;
+- leverage и margin;
+- общий капитал под риском;
+- концентрацию по символам;
+- drawdown и loss limits;
+- pre-trade, continuous и emergency risk controls.
+
+Risk не является только одним последовательным шагом после Strategy.
+Он может запрещать вход, изменять размер позиции и останавливать уже
+активное исполнение.
+
+### 6.3. Order Management System
+
+Отвечает за внутренний жизненный цикл собственных заявок:
+
+- создание client order identity;
+- переходы состояния заявки;
+- amend / cancel;
+- partial fills;
+- deduplication;
+- reconciliation с биржей;
+- восстановление после reconnect и restart.
+
+OMS не следует смешивать с Market Trades Feed: рыночная сделка и
+исполнение собственной заявки являются разными предметными сущностями.
+
+### 6.4. Execution Management
+
+Отвечает за:
+
+- преобразование одобренного намерения в execution command;
+- выбор цены и способа исполнения;
+- маршрутизацию на биржу;
+- контроль slippage, liquidity и freshness;
+- обработку transport и exchange errors.
+
+**Текущее основное размещение:**
+
+```text
+app/src/trading/execution/
+```
+
+### 6.5. Position and Account Reconciliation
+
+Сопоставляет локальное состояние с биржей:
+
+- позиции;
+- balances;
+- fills;
+- open orders;
+- fees;
+- realized и unrealized PnL.
+
+Биржевое состояние является внешним фактом и должно периодически
+сверяться, а не только вычисляться из локальных событий.
+
+---
+
+## 7. Platform and Governance
+
+### Runtime and Scheduling
+
+- явные владельцы задач и ресурсов;
+- конечные timeouts;
+- детерминированные startup и shutdown;
+- controlled retry/reconnect;
+- отсутствие скрытого fire-and-forget.
+
+### Event Contracts
+
+- типизированные и версионируемые события;
+- явная граница между market, runtime, execution и audit events;
+- контролируемое ordering;
+- отсутствие чувствительных transport payload в логах.
+
+### Configuration and Secrets
+
+- feature flags безопасны по умолчанию;
+- URL, symbols и credentials задаются явно;
+- production secrets не попадают в код, документацию и события.
+
+### Logging, Audit and Observability
+
+- технические логи;
+- domain audit trail;
+- Trade Journal;
+- metrics, latency и data freshness;
+- health и liveness;
+- alerting;
+- объяснение причин торгового решения.
+
+### Resilience
+
+- idempotency;
+- reconnect;
+- Recovery;
+- persistent checkpoint;
+- startup reconciliation;
+- controlled degradation;
+- failure isolation.
+
+### Backtesting and Simulation
+
+Backtesting является отдельной capability, но переиспользует:
+
+- Canonical Market Data;
+- Replay;
+- deterministic clock;
+- production Feature, Decision и Risk contracts;
+- exchange/OMS simulator.
+
+Отдельная копия торговой логики только для backtest не допускается.
+
+---
+
+## 8. Правила зависимостей
+
+Разрешённое основное направление:
+
+```text
+Market Data
+    ↓
+Market Intelligence
+    ↓
+Trading Decision
+    ↓
+Portfolio / Risk
+    ↓
+OMS / Execution
+    ↓
+Exchange Integration
+```
+
+Обязательные ограничения:
+
+- Market Data не импортирует Trading;
+- Canonical Models не зависят от Dzengi transport schema;
+- Market Intelligence не управляет WebSocket lifecycle;
+- Strategy не отправляет биржевую заявку напрямую;
+- Execution не изменяет правила Market Data Consistency;
+- Telegram UI не является владельцем domain state;
+- Storage не вызывает торговые решения;
+- Backtesting использует те же domain contracts, что production;
+- Platform-компоненты не получают лишнюю предметную ответственность.
+
+Обратная информация от Exchange возвращается через явные execution,
+order, account и runtime events, а не через обратные импорты между
+слоями.
+
+---
+
+## 9. Политика каталогов
+
+Логический домен и физический каталог не обязаны иметь одинаковое имя.
+
+Текущее соответствие:
+
+| Ответственность | Фактическое размещение |
+|---|---|
+| 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/` |
+| Market Intelligence | `app/src/trading/market_intelligence/` |
+| Trading Decision | `app/src/trading/decision/` |
+| Execution | `app/src/trading/execution/` |
+| Position | `app/src/trading/position/` |
+| Trade Journal | `app/src/trading/journal/` |
+| Exchange Integration | `app/src/integrations/exchange/` |
+
+Новый каталог создаётся только когда:
+
+1. ответственность подтверждена фактическими consumers;
+2. определён публичный контракт;
+3. существующее ownership признано неверным;
+4. подготовлен отдельный migration plan;
+5. проверено направление импортов.
+
+Предложенные имена вроде `analytics/features`,
+`market_data/normalization` или `market_data/storage` являются
+логическими ориентирами, а не заранее утверждённой файловой структурой.
+
+---
+
+## 10. Current-to-target status
+
+| Область | Состояние |
+|---|---|
+| Market Data Acquisition foundation | Реализуется 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 |
+| 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 программа |
+
+`Completed` означает завершение утверждённого Build, а не окончательную
+сертификацию всей подсистемы для любой production-нагрузки.
+
+---
+
+## 11. Управление изменениями
+
+Этот документ изменяется только когда меняется:
+
+- ownership домена;
+- публичная архитектурная граница;
+- разрешённое направление зависимостей;
+- целевая карта подсистем.
+
+Статус конкретного Build изменяется в `master-roadmap.md` и его
+migration report.
+
+Детали реализации, тестовые evidence и локальные решения фиксируются в:
+
+```text
+docs/migrations/build_<number>_architecture.md
+docs/migrations/build_<number>.md
+docs/decisions/
+```
+
+При конфликте:
+
+1. фактический код и тесты определяют текущее поведение;
+2. принятый Build architecture document определяет локальное решение;
+3. настоящий документ определяет целевую границу;
+4. roadmap определяет порядок дальнейшей миграции.
--- a/docs/migrations/build_060_25.md
+++ b/docs/migrations/build_060_25.md
@@ -0,0 +1,419 @@
+# Build 060.25 — Production Runtime Integration
+
+**Engineering Migration Report**
+
+---
+
+## Контроль документа
+
+| Свойство | Значение |
+|---|---|
+| Build | 060.25 |
+| Статус | Completed |
+| Подсистема | Market Data Acquisition |
+| Компонент | Trades Feed / Trade Stream Runtime |
+| Дата завершения | 2026-07-31 |
+| Версия | 1.0 |
+
+---
+
+## Связанные документы
+
+- `build_060_24.md` — итог внутренней Runtime Recovery Architecture;
+- `build_060_24_architecture.md` — архитектурные границы Recovery Runtime;
+- `build_060_25_architecture.md` — полная спецификация Production Runtime
+  Integration и принятые ADR;
+- `dzentra_target_architecture.md` — место Trade Stream в целевой
+  архитектуре Dzentra;
+- `master-roadmap.md` — дальнейшая последовательность Build.
+
+---
+
+## 1. Назначение Build
+
+Build 060.24 создал внутренний граф компонентов Trade Stream Runtime,
+но не подключал его к реальному жизненному циклу приложения.
+
+Цель Build 060.25 — превратить этот граф в один управляемый production
+Runtime:
+
+```text
+Application Bootstrap
+        │
+        ▼
+Production Trade Stream Factory
+        │
+        ▼
+WebSocket connect and subscribe
+        │
+        ▼
+Trade receive loop
+        │
+        ├── ACK / control routing
+        ├── Canonical Trade pipeline
+        ├── Consistency checkpoint
+        └── Runtime Events
+        │
+        ▼
+Heartbeat / Supervisor / Scheduler
+        │
+        ▼
+reconnect → subscription restore → recovery
+        │
+        ▼
+resume buffered live processing
+```
+
+Build сохраняет границы Transport, Acquisition, Consistency, Recovery
+и Runtime. Внешний WebSocket документ становится Canonical Trade только
+после прохождения существующего Acquisition pipeline.
+
+---
+
+## 2. Завершённые подэтапы
+
+| Подэтап | Название | Статус |
+|---|---|---|
+| 060.25.0 | Static Contract Cleanup | Accepted |
+| 060.25.1 | Dzengi WebSocket Transport | Accepted |
+| 060.25.2 | WebSocket Session and Subscription Manager | Accepted |
+| 060.25.3 | Async Runtime Event Publisher | Accepted |
+| 060.25.4 | Trade Stream Production Runtime | Accepted |
+| 060.25.5 | Reconnect and Recovery Integration | Accepted |
+| 060.25.6 | Heartbeat and Scheduler Integration | Accepted |
+| 060.25.7 | Settings, Bootstrap and Graceful Shutdown | Accepted |
+| 060.25.8 | Targeted Runtime Verification | Accepted |
+
+Каждый подэтап прошёл отдельный архитектурный review. Обнаруженные
+findings исправлялись до принятия соответствующего этапа.
+
+---
+
+## 3. Итоговая ответственность компонентов
+
+### DzengiWebSocketTransport
+
+- открывает и закрывает WebSocket connection;
+- отправляет и получает только `str | bytes`;
+- выполняет конечный Ping/Pong liveness probe;
+- не знает JSON, Trade, подписки и Recovery;
+- использует отключённый встроенный WebSocket keepalive.
+
+### WebSocketSession
+
+- идемпотентно запускает и останавливает Transport;
+- повторный `start()` не заменяет исправное OPEN-соединение;
+- принудительная замена выполняется только явным reconnect.
+
+### WebSocketSubscriptionManager
+
+- разделяет желаемые и фактически активные подписки;
+- сохраняет намерение подписаться после временной ошибки send;
+- восстанавливает подписки после reconnect;
+- не имитирует неподдерживаемый Dzengi unsubscribe.
+
+### Async Runtime Event Publisher
+
+- последовательно и с `await` доставляет событие всем Consumer;
+- не создаёт скрытых background tasks;
+- изолирует обычную ошибку Consumer от Runtime lifecycle;
+- распространяет cancellation;
+- защищён от прямой и child-task reentrancy;
+- не включает чувствительный payload в аварийную диагностику.
+
+### TradeStreamProductionRuntime
+
+- является единственным владельцем startup, receive и Scheduler tasks;
+- маршрутизирует control и market сообщения;
+- передаёт Trade document в общий Acquisition/Consistency pipeline;
+- связывает transport failure с reconnect и Recovery;
+- выполняет полный cleanup при остановке, ошибке и cancellation.
+
+### RuntimeReconnectRecoveryCoordinator
+
+- обеспечивает single-flight для одного поколения соединения;
+- закрывает общий live-processing gate;
+- выполняет reconnect;
+- восстанавливает подписки;
+- запускает REST Recovery вне event loop;
+- открывает live processing только после завершения Recovery;
+- оставляет gate в failed state после terminal Recovery error.
+
+### Heartbeat, Supervisor и Scheduler
+
+- используют состояние Transport, а не частоту рыночных сделок;
+- выполняют Ping/Pong с конечным timeout;
+- объединяют одновременные heartbeat и receive failures в одну
+  reconnect/recovery operation;
+- создают ровно одну Scheduler task;
+- останавливаются в порядке Scheduler → Supervisor → receive loop.
+
+### Application Runner
+
+- владеет Telegram polling и опциональным Trade Stream Runtime;
+- считает ошибку включённого Trade Stream фатальной;
+- ожидает завершение обеих корневых задач;
+- не позволяет повторной cancellation прервать cleanup;
+- закрывает Bot session ровно один раз.
+
+---
+
+## 4. Production lifecycle
+
+### Запуск
+
+```text
+load settings
+    ↓
+feature flag disabled
+    └── Runtime graph не создаётся
+
+feature flag enabled
+    ↓
+build concrete dependency graph
+    ↓
+start WebSocket session
+    ↓
+send Trade subscription
+    ↓
+start Supervisor
+    ↓
+start receive loop and Scheduler
+```
+
+Фабрика только собирает граф зависимостей. Сетевые действия начинаются
+только из `TradeStreamProductionRuntime.run()`.
+
+### Reconnect и Recovery
+
+```text
+transport failure or failed liveness probe
+    ↓
+capture connection generation
+    ↓
+acquire single-flight operation
+    ↓
+close live-processing gate
+    ↓
+disconnect old connection
+    ↓
+connect new connection
+    ↓
+restore desired subscriptions
+    ↓
+recover missing Trades through REST
+    ↓
+process buffered live Trades
+```
+
+Recovery и live processing используют один экземпляр Consistency Layer
+и не изменяют checkpoint параллельно.
+
+### Остановка
+
+```text
+stop Scheduler
+    ↓
+await Scheduler task
+    ↓
+stop Supervisor
+    ↓
+cancel and await receive loop
+    ↓
+stop WebSocket session
+    ↓
+clear subscriptions
+    ↓
+close Bot session at Application boundary
+```
+
+---
+
+## 5. Конфигурация
+
+Trade Stream управляется отдельным безопасным feature flag:
+
+```text
+TRADE_STREAM_ENABLED
+```
+
+При включённом Runtime обязательны явные:
+
+- WebSocket URL;
+- список символов;
+- transport timeouts;
+- heartbeat timeout;
+- Scheduler interval;
+- максимальный размер Recovery Window.
+
+Legacy WebSocket URL и `default_symbol` не используются как fallback.
+Наличие `EXCHANGE_ENABLED` само по себе не включает Trade Stream.
+
+---
+
+## 6. Ключевые архитектурные гарантии
+
+После Build 060.25 выполняются следующие правила:
+
+```text
+exactly one production receive loop
+```
+
+```text
+exactly one scheduler task
+```
+
+```text
+at most one reconnect/recovery sequence per generation
+```
+
+```text
+reconnect =
+    disconnect
+    → connect
+    → restore subscriptions
+```
+
+```text
+recovery precedes buffered live processing
+```
+
+```text
+disabled Trade Stream creates no Runtime graph
+```
+
+```text
+construction has no network side effects
+```
+
+```text
+all owned tasks are cancelled or completed and awaited
+```
+
+---
+
+## 7. Реализованные файлы
+
+### Добавленные production-файлы
+
+```text
+app/src/bootstrap/
+    application.py
+    trade_stream_runtime.py
+
+app/src/market_data/acquisition/adapters/dzengi/
+    websocket_control_message_handler.py
+    websocket_inbound_message_classifier.py
+    websocket_transport.py
+
+app/src/market_data/acquisition/runtime/
+    acquisition_runtime_event_logging_consumer.py
+    acquisition_runtime_event_publisher.py
+    live_processing_gate.py
+    runtime_liveness_probe.py
+    runtime_reconnect_recovery_coordinator.py
+    trade_stream_production_runtime.py
+    websocket_inbound_message.py
+    websocket_session.py
+    websocket_subscription_manager.py
+```
+
+### Изменённые production-файлы
+
+```text
+app/.env.example
+app/src/bootstrap/app_factory.py
+app/src/core/config.py
+app/src/integrations/exchange/rest_client.py
+app/src/main.py
+app/src/market_data/acquisition/exceptions.py
+app/src/market_data/acquisition/runtime/reconnect.py
+app/src/market_data/acquisition/runtime/scheduler.py
+app/src/market_data/acquisition/runtime/supervisor.py
+app/src/market_data/acquisition/trade_stream_runtime_composition.py
+```
+
+### Тесты
+
+Добавлено или расширено покрытие:
+
+```text
+app/tests/unit/bootstrap/
+app/tests/unit/core/
+app/tests/unit/market_data/acquisition/adapters/dzengi/
+app/tests/unit/market_data/acquisition/runtime/
+app/tests/unit/market_data/acquisition/
+app/tests/unit/test_main.py
+```
+
+Постороннее пользовательское изменение `.gitignore` не относится к
+Build 060.25.
+
+---
+
+## 8. Targeted Runtime Verification
+
+060.25.8 добавил только тестовый код и не менял production-поведение.
+
+Через реальную production factory и реальные компоненты Runtime graph,
+но с управляемыми WebSocket и REST boundaries, проверены:
+
+1. выключенный feature flag не создаёт Runtime graph;
+2. subscribe → ACK → Trade обновляет общий checkpoint;
+3. ошибка connect фатальна и не оставляет задач;
+4. ошибка первой subscription send полностью откатывает startup;
+5. reconnect заменяет connection и восстанавливает подписку до Recovery;
+6. recovered Trade обрабатывается раньше buffered live Trade;
+7. Recovery error запрещает обработку buffered live Trade;
+8. одновременные ошибки корневых задач наблюдаются детерминированно;
+9. повторная cancellation не прерывает cleanup;
+10. Bot session закрывается один раз, owned tasks всегда await-ятся.
+
+Итоговый read-only review 060.25.8 новых findings не выявил.
+
+---
+
+## 9. Результаты тестирования
+
+Повторная проверка выполнена 2026-07-31:
+
+```text
+Expanded Production Runtime target:    445 passed
+Full project regression:              1869 passed
+```
+
+Тесты не используют реальную сеть, production credentials или
+недетерминированные внешние задержки.
+
+---
+
+## 10. Что не входит в Build
+
+Build 060.25 не реализует:
+
+- длительные live exchange и network fault scenarios;
+- production stress certification;
+- persistent market data storage;
+- persistent checkpoint;
+- startup recovery после перезапуска процесса;
+- historical query и Replay API;
+- аналитические вычисления поверх исторических данных.
+
+Эти задачи относятся к следующим Build и зафиксированы в
+`master-roadmap.md`.
+
+---
+
+## 11. Итог
+
+Build 060.25 завершён.
+
+Trade Stream подключён к bootstrap приложения как отдельный,
+отключённый по умолчанию production Runtime. Он управляет реальным
+WebSocket lifecycle, восстанавливает подписки и пропущенные сделки,
+сохраняет порядок Recovery и Live processing и детерминированно
+освобождает принадлежащие ему ресурсы.
+
+Следующий этап — Build 060.26, посвящённый интеграционным, fault,
+reconnect, recovery и stress-сценариям за пределами детерминированного
+in-process unit harness.
--- a/docs/migrations/build_060_25_architecture.md
+++ b/docs/migrations/build_060_25_architecture.md
--- a/docs/roadmap/master-roadmap.md
+++ b/docs/roadmap/master-roadmap.md
@@ -1,12 +1,245 @@
-# Master Roadmap — Dzentra Bot
+# Master Roadmap — Dzentra
+
+## Контроль документа
+
+| Свойство | Значение |
+|---|---|
+| Тип | Master Delivery Roadmap |
+| Статус | Active |
+| Версия | 2.0 |
+| Дата актуализации | 2026-07-31 |
+| Текущий завершённый Build | 060.25 |
+| Следующий Build | 060.26 |
+
+---

 ## Цель проекта
-Создать Telegram-бота для:
- ручной торговли;
- мониторинга рынка;
- автоторговли;
- аналитики;
- управления стратегиями.
+
+Dzentra развивается из работающего Telegram trading bot в модульную
+алгоритмическую торговую платформу, которая поддерживает:
+
+- получение и хранение рыночных данных;
+- Market Intelligence и объяснимую аналитику;
+- ручные и автоматические торговые решения;
+- управление риском, исполнением и позициями;
+- аудит и воспроизводимость решений;
+- безопасный production runtime;
+- исторический Replay и Backtesting.
+
+Целевая карта доменов и направление зависимостей определены в:
+
+```text
+docs/architecture/dzentra_target_architecture.md
+```
+
+Настоящий roadmap определяет порядок реализации. Подробные решения и
+test evidence находятся в документах конкретных Build.
+
+---
+
+# Текущая контрольная точка
+
+```text
+Market Data Acquisition
+        ↓
+Trades Feed / Time & Sales
+        ↓
+Build 060.25 — Production Runtime Integration
+        ↓
+Completed
+```
+
+060.25.0–060.25.8 приняты. Trade Stream:
+
+- подключён к application bootstrap через отдельный feature flag;
+- владеет WebSocket lifecycle;
+- восстанавливает подписки и пропущенные Trades;
+- сохраняет порядок Recovery → buffered Live;
+- использует transport Ping/Pong liveness;
+- детерминированно останавливает и ожидает owned tasks;
+- прошёл 445 целевых тестов и полную регрессию из 1869 тестов.
+
+Подробности:
+
+```text
+docs/migrations/build_060_25_architecture.md
+docs/migrations/build_060_25.md
+```
+
+---
+
+# Активная программа — Market Data Acquisition
+
+## Завершённая ветка Trades Feed
+
+| Build | Результат | Статус |
+|---|---|---|
+| 060.1–060.19 | Canonical Trade, REST/WS pipelines, Consistency и Recovery foundation | Completed |
+| 060.20 | Trade Runtime Architecture | Completed |
+| 060.20.1 | Trade Stream State Ownership Alignment | Completed |
+| 060.21 | Runtime Protocol Integration | Completed |
+| 060.22 | Runtime Service Integration | Completed |
+| 060.23 | Trade Stream Acquisition Integration | Completed |
+| 060.24 | Runtime Recovery Architecture | Completed |
+| 060.25 | Production Runtime Integration | Completed |
+
+## Следующие Build
+
+### Build 060.26 — Integration and Regression
+
+**Статус:** Next
+
+Назначение:
+
+- live exchange integration checks;
+- длительные reconnect scenarios;
+- recovery при реальных сетевых задержках;
+- network fault injection;
+- stress и soak testing;
+- проверка отсутствия утечек задач и ресурсов;
+- финальная verification Runtime documentation.
+
+Build не должен превращать сетевые сценарии в обязательную часть
+обычного unit suite.
+
+### Build 060.27 — Persistent Market Data Storage
+
+**Статус:** Planned
+
+Назначение:
+
+- долговременное хранение Canonical Trades;
+- подготовка хранения Quotes и Candles;
+- ключи идемпотентности и ordering;
+- raw/canonical retention policy;
+- Storage API;
+- партиционирование, retention и data provenance.
+
+Результат: история рынка сохраняется независимо от торгового цикла и
+времени жизни процесса.
+
+### Build 060.28 — Persistent Checkpoint and Startup Recovery
+
+**Статус:** Planned
+
+Назначение:
+
+- Checkpoint Service;
+- сохранение runtime checkpoint;
+- восстановление после перезапуска;
+- сверка checkpoint с durable Market Data;
+- Startup Recovery;
+- защита от повторной обработки и пропусков.
+
+Persistent checkpoint не заменяет Market Data Storage и не должен
+считаться более достоверным, чем подтверждённая сохранённая история.
+
+### Build 060.29 — Market Data Access and Replay
+
+**Статус:** Planned
+
+Назначение:
+
+- Data Access Layer;
+- Historical Queries;
+- Replay API;
+- детерминированные replay-часы;
+- одинаковые Canonical contracts для live и replay consumers.
+
+Полноценные аналитические вычисления не входят автоматически в этот
+Build. Они принадлежат Market Data Processing и Feature Engineering и
+получат отдельный scope после появления устойчивого Storage/Replay.
+
+### Build 060.30 — Market Data Acquisition Final Documentation
+
+**Статус:** Planned
+
+Назначение:
+
+- итоговый аудит ветки Trades Feed;
+- проверка контрактов и направления импортов;
+- сверка фактической структуры файлов;
+- эксплуатационная документация Runtime;
+- обновление architecture overview и project structure;
+- фиксация известных ограничений и следующей Feed-ветки.
+
+### Build 061.00 — Validation and Canonicalization Boundary Refactoring
+
+**Статус:** Planned
+
+Сначала выполняется read-only аудит фактического ownership:
+
+```text
+schema validation
+parser
+value validation
+normalization
+mapper
+canonical model
+consistency
+data quality
+missing data recovery
+```
+
+Только после аудита определяется, нужен ли отдельный каталог
+`market_data/normalization`. Механический перенос существующих
+валидаторов не является целью Build.
+
+---
+
+# Дальнейшие программы
+
+После 061.00 следующая Feed-ветка выбирается на основании фактических
+production consumers и доступных данных Dzengi.
+
+Кандидаты:
+
+- Quotes lifecycle consolidation;
+- OHLCV/Candles production integration;
+- Order Book snapshot and delta reconciliation;
+- Derivatives Market Data;
+- Market Index;
+- Exchange Time;
+- Exchange and Instrument Status.
+
+Нумерация и точный scope этих Build утверждаются только после отдельного
+read-only архитектурного анализа. Старый ориентировочный план из
+`build_044.md` сохраняет историческую ценность, но больше не является
+актуальной нумерацией.
+
+Следующие верхнеуровневые программы пока не имеют утверждённых Build:
+
+- Market Data Processing;
+- Feature Engineering;
+- Market Intelligence consolidation;
+- Scenario Evaluation;
+- Portfolio and Risk boundary;
+- Order Management System;
+- Position and Account Reconciliation;
+- Backtesting and Simulation;
+- Production Deployment and Operations.
+
+---
+
+# Правила ведения roadmap
+
+1. Один Build изменяет одну подтверждённую архитектурную область.
+2. Перед Build выполняется read-only анализ фактического кода и тестов.
+3. Дальние номера являются ориентиром до утверждения architecture plan.
+4. Каждый Build имеет критерии завершения и проверяемый test evidence.
+5. Архитектурные findings исправляются до статуса Accepted.
+6. Итоговый migration report создаётся после завершения Build.
+7. Master roadmap хранит только последовательность и статус, а не
+   дублирует подробную архитектурную спецификацию.
+8. Посторонние изменения рабочего каталога не включаются в Build.
+
+---
+
+# Исторический roadmap Stage 01–09
+
+Раздел ниже сохраняет историю развития первоначального Telegram bot.
+Его локальные пометки `в работе`, `не начат` и прежняя нумерация
+являются историческим снимком, а не текущим источником следующего шага.

 ---

@@ -135,7 +368,7 @@
 ✔ minimal trading layout  
 ✔ duplicate info removal  

-#### 07.4.3.2 — Engine Decoupling (NEXT) ✅
+#### 07.4.3.2 — Engine Decoupling ✅
 ✔ split analysis / UI refresh  
 ✔ fast price polling (1s)  
 ✔ slow UI updates (event-driven / 60s)  
@@ -1491,5 +1724,12 @@

 ## Текущий статус проекта

-👉 Завершён: 07.4.3.1  
-👉 Следующий шаг: 07.4.3.2 — Engine Decoupling + Price Polling
+Этот блок исторического Stage-roadmap больше не определяет текущий
+следующий шаг.
+
+Актуальная контрольная точка:
+
+```text
+Завершён: Build 060.25 — Production Runtime Integration
+Следующий: Build 060.26 — Integration and Regression
+```