Build 060.21: integrate acquisition runtime protocols

2026-07-26 09:20:24 +03:00
parent ad6631f773
commit 433ac5d375
4 changed files with 1914 additions and 2 deletions
--- a/docs/migrations/build_060_21.md
+++ b/docs/migrations/build_060_21.md
@@ -0,0 +1,841 @@
+# Build 060.21 — Runtime Protocol Integration
+
+**Engineering Migration Report**
+
+---
+
+# Контроль документа
+
+| Свойство | Значение |
+|----------|----------|
+| Build | 060.21 |
+| Название | Runtime Protocol Integration |
+| Статус | Completed |
+| Проект | Dzentra |
+| Подсистема | Market Data Acquisition |
+| Компонент | Acquisition Runtime Protocol Layer |
+| Версия | 1.0 |
+
+---
+
+# Связанные документы
+
+- `build_060_21_architecture.md` — архитектурная спецификация Build.
+- `build_060_20_1.md` — Engineering Migration Report предыдущего корректирующего Build.
+- `build_060_20_1_architecture.md` — спецификация переноса владельца состояния Trade Stream.
+
+---
+
+# Цель Build
+
+Build 060.20.1 завершил архитектурную корректировку подсистемы **Trades Feed (Time & Sales)** и окончательно закрепил владельца состояния проверки согласованности потока сделок.
+
+После предыдущего этапа архитектура сопровождения состояния приняла следующий вид.
+
+```text
+TradeStreamConsistencyController
+            │
+            ▼
+TradeStreamStateStore
+            │
+            ▼
+TradeStreamState
+```
+
+Runtime перестал владеть состоянием предметной области и сохранил только инфраструктурную ответственность.
+
+К началу Build 060.21 в проекте уже существовали:
+
+- транспортные WebSocket-протоколы;
+- типизированные Runtime-команды;
+- типизированные Runtime-события;
+- модели транспортных сообщений;
+- независимые подсистемы Trade Stream Consistency и Trade Recovery.
+
+Однако отсутствовали публичные контракты, связывающие типизированные команды и события с будущей реализацией Runtime Service.
+
+Главной задачей Build 060.21 стало расширение существующего Runtime Protocol Layer двумя узкими инфраструктурными контрактами:
+
+```text
+AcquisitionRuntimeCommandDispatcherProtocol
+AcquisitionRuntimeEventPublisherProtocol
+```
+
+Одновременно были введены точные типовые объединения:
+
+```text
+AcquisitionRuntimeCommand
+AcquisitionRuntimeEvent
+```
+
+Build сознательно не создаёт Runtime Service и не меняет поведение существующих компонентов.
+
+---
+
+# Предпосылки
+
+К началу настоящего Build Runtime Layer уже содержал базовые контракты:
+
+```text
+WebSocketTransportProtocol
+WebSocketSessionProtocol
+WebSocketSubscriptionManagerProtocol
+```
+
+Они описывали:
+
+- открытие и закрытие WebSocket-соединения;
+- отправку и получение транспортных сообщений;
+- жизненный цикл WebSocket-сессии;
+- восстановление и очистку подписок.
+
+Также существовали отдельные модели команд:
+
+```text
+ConnectCommand
+DisconnectCommand
+SubscribeCommand
+UnsubscribeCommand
+SendTextCommand
+SendBinaryCommand
+```
+
+и модели событий:
+
+```text
+ConnectedEvent
+DisconnectedEvent
+ConnectFailedEvent
+MessageReceivedEvent
+MessageSentEvent
+ReconnectStartedEvent
+ReconnectCompletedEvent
+ReconnectFailedEvent
+HeartbeatTimeoutEvent
+```
+
+Несмотря на наличие всех перечисленных сущностей, в системе отсутствовал формальный контракт их передачи.
+
+Не было определено:
+
+- каким образом команда поступает в Runtime;
+- каким образом Runtime публикует инфраструктурное событие;
+- какие типы команд допустимы;
+- какие типы событий допустимы;
+- как сохранить независимость Runtime от бизнес-логики Acquisition.
+
+Именно эту контрактную границу формализует Build 060.21.
+
+---
+
+# Результаты архитектурного аудита
+
+Перед началом реализации был выполнен аудит следующих компонентов:
+
+```text
+src/market_data/acquisition/runtime/websocket_protocol.py
+src/market_data/acquisition/runtime/runtime_commands.py
+src/market_data/acquisition/runtime/runtime_events.py
+src/market_data/acquisition/runtime/transport_messages.py
+```
+
+Дополнительно были проанализированы:
+
+- Runtime unit-тесты;
+- Trades Feed;
+- WebSocket Trade Adapter;
+- Trade Stream Consistency;
+- Trade Recovery;
+- Acquisition Service и Registry;
+- repository-wide зависимости Runtime Protocol Layer.
+
+Аудит подтвердил, что текущие команды и события уже достаточны для настоящего этапа.
+
+Следовательно:
+
+- новые команды не требуются;
+- новые события не требуются;
+- существующие WebSocket Protocol не должны изменять ответственность;
+- Runtime Service не должен создаваться преждевременно;
+- Consistency и Recovery не должны получать Runtime-зависимости.
+
+---
+
+# Отказ от общего RuntimeServiceProtocol в Build 060.21
+
+На раннем этапе проектирования рассматривалось создание единого контракта:
+
+```text
+RuntimeServiceProtocol
+```
+
+Предполагалось включить в него операции жизненного цикла, подписок, отправки сообщений и состояния соединения.
+
+После аудита данный шаг был признан преждевременным.
+
+В утверждённой дорожной карте следующий этап определён отдельно:
+
+```text
+060.22 Runtime Service Integration
+```
+
+Создание полноценного сервисного контракта в Build 060.21 фактически перенесло бы часть ответственности Build 060.22 в текущий этап.
+
+Поэтому Build 060.21 ограничен только недостающими инфраструктурными контрактами:
+
+- dispatcher команд;
+- publisher событий.
+
+Такое решение сохраняет строгую границу между этапами.
+
+---
+
+# Архитектурное решение
+
+После завершения Build Runtime Protocol Layer имеет следующий вид.
+
+```text
+Acquisition Runtime Commands
+            │
+            ▼
+AcquisitionRuntimeCommandDispatcherProtocol
+            │
+            ▼
+Future Runtime Service
+            │
+            ▼
+AcquisitionRuntimeEventPublisherProtocol
+            │
+            ▼
+Acquisition Runtime Events
+```
+
+Новые Protocol не реализуют поведение.
+
+Они только формализуют допустимый интерфейс будущих компонентов.
+
+---
+
+# AcquisitionRuntimeCommand
+
+В `websocket_protocol.py` введён типовой alias:
+
+```text
+AcquisitionRuntimeCommand
+```
+
+Он объединяет все допустимые инфраструктурные команды Acquisition Runtime:
+
+- `ConnectCommand`;
+- `DisconnectCommand`;
+- `SubscribeCommand`;
+- `UnsubscribeCommand`;
+- `SendTextCommand`;
+- `SendBinaryCommand`.
+
+Таким образом будущая реализация dispatcher получает строго ограниченный тип входных данных.
+
+Она не может принимать:
+
+- `Trade`;
+- `Quote`;
+- `Candle`;
+- Recovery Request;
+- произвольный объект приложения.
+
+Это закрепляет независимость Runtime от предметной области.
+
+---
+
+# AcquisitionRuntimeEvent
+
+Также введён типовой alias:
+
+```text
+AcquisitionRuntimeEvent
+```
+
+Он объединяет все допустимые инфраструктурные события Acquisition Runtime:
+
+- `ConnectedEvent`;
+- `DisconnectedEvent`;
+- `ConnectFailedEvent`;
+- `MessageReceivedEvent`;
+- `MessageSentEvent`;
+- `ReconnectStartedEvent`;
+- `ReconnectCompletedEvent`;
+- `ReconnectFailedEvent`;
+- `HeartbeatTimeoutEvent`.
+
+Alias сознательно получил префикс `Acquisition`.
+
+В проекте уже существует отдельная глобальная система событий:
+
+```text
+src/runtime_events/
+```
+
+с собственной моделью `RuntimeEvent`.
+
+Использование общего имени внутри Acquisition создало бы неоднозначность и риск ошибочных импортов.
+
+Поэтому итоговые имена были уточнены:
+
+```text
+AcquisitionRuntimeCommand
+AcquisitionRuntimeEvent
+```
+
+Это решение полностью устраняет терминологический конфликт.
+
+---
+
+# AcquisitionRuntimeCommandDispatcherProtocol
+
+Добавлен новый публичный контракт:
+
+```text
+AcquisitionRuntimeCommandDispatcherProtocol
+```
+
+Protocol определяет одну операцию:
+
+```text
+dispatch(command: AcquisitionRuntimeCommand) -> None
+```
+
+Метод является асинхронным.
+
+Dispatcher отвечает только за передачу одной типизированной инфраструктурной команды в Runtime.
+
+Он не определяет:
+
+- внутреннюю маршрутизацию;
+- порядок исполнения;
+- повторные попытки;
+- обработку ошибок;
+- жизненный цикл сессии;
+- реакцию бизнес-компонентов.
+
+Все перечисленные обязанности относятся к будущей реализации Runtime Service.
+
+---
+
+# AcquisitionRuntimeEventPublisherProtocol
+
+Добавлен второй публичный контракт:
+
+```text
+AcquisitionRuntimeEventPublisherProtocol
+```
+
+Protocol определяет одну операцию:
+
+```text
+publish(event: AcquisitionRuntimeEvent) -> None
+```
+
+Метод также является асинхронным.
+
+Publisher отвечает исключительно за публикацию уже произошедшего инфраструктурного факта.
+
+Он не определяет:
+
+- список подписчиков;
+- механизм доставки;
+- очередь событий;
+- обработку ошибок потребителей;
+- реакцию Trades Feed;
+- запуск Recovery;
+- правила reconnect.
+
+Эти вопросы относятся к последующим Build.
+
+---
+
+# Почему Protocol расположены в websocket_protocol.py
+
+В рамках настоящего Build новые контракты добавлены в существующий файл:
+
+```text
+src/market_data/acquisition/runtime/websocket_protocol.py
+```
+
+Причины данного решения:
+
+- файл уже является центральной точкой Runtime Protocol Layer;
+- все текущие Protocol относятся к WebSocket Runtime;
+- Build ограничен двумя небольшими контрактами;
+- создание нового каталога или дополнительной иерархии файлов было бы преждевременным;
+- существующая структура проекта сохраняется без реорганизации.
+
+При дальнейшем расширении Runtime Protocol Layer отдельный файл может быть введён отдельным согласованным Build, если объём контрактов действительно потребует этого.
+
+Настоящий Build не выполняет структурную реорганизацию каталогов.
+
+---
+
+# Разделение ответственности
+
+После завершения Build окончательно закреплены следующие границы.
+
+## Runtime Commands
+
+Команды являются неизменяемыми инфраструктурными намерениями.
+
+Они описывают, что необходимо выполнить.
+
+Они не выполняют операцию самостоятельно.
+
+---
+
+## Command Dispatcher
+
+Dispatcher принимает команду и передаёт её будущей реализации Runtime.
+
+Он не содержит бизнес-логики.
+
+---
+
+## Runtime Events
+
+События являются неизменяемыми инфраструктурными фактами.
+
+Они описывают уже произошедшее состояние транспорта.
+
+---
+
+## Event Publisher
+
+Publisher передаёт событие заинтересованным потребителям.
+
+Он не определяет реакцию потребителя.
+
+---
+
+## WebSocket Transport
+
+Transport продолжает отвечать только за низкоуровневое соединение и транспортные сообщения.
+
+---
+
+## WebSocket Session
+
+Session продолжает отвечать за жизненный цикл WebSocket-сессии.
+
+---
+
+## Subscription Manager
+
+Subscription Manager продолжает отвечать за восстановление и очистку активных подписок.
+
+---
+
+# Изменённые файлы
+
+В рамках Build изменены только два файла.
+
+## Runtime Protocol Layer
+
+```text
+src/market_data/acquisition/runtime/websocket_protocol.py
+```
+
+Добавлены:
+
+- `AcquisitionRuntimeCommand`;
+- `AcquisitionRuntimeEvent`;
+- `AcquisitionRuntimeCommandDispatcherProtocol`;
+- `AcquisitionRuntimeEventPublisherProtocol`.
+
+Существующие Protocol сохранены без изменения поведения:
+
+- `WebSocketTransportProtocol`;
+- `WebSocketSessionProtocol`;
+- `WebSocketSubscriptionManagerProtocol`.
+
+---
+
+## Unit-тесты Runtime Protocol
+
+```text
+tests/unit/market_data/acquisition/runtime/test_websocket_protocol.py
+```
+
+Добавлены тестовые реализации:
+
+- `FakeRuntimeCommandDispatcher`;
+- `FakeRuntimeEventPublisher`.
+
+Добавлены проверки:
+
+- полная реализация dispatcher соответствует Protocol;
+- полная реализация publisher соответствует Protocol;
+- неполная реализация dispatcher не соответствует Protocol;
+- неполная реализация publisher не соответствует Protocol.
+
+Все существующие тесты WebSocket Protocol сохранены.
+
+---
+
+# Файлы, которые не изменялись
+
+Аудит подтвердил отсутствие необходимости менять:
+
+```text
+src/market_data/acquisition/runtime/runtime_commands.py
+src/market_data/acquisition/runtime/runtime_events.py
+src/market_data/acquisition/runtime/transport_messages.py
+```
+
+Их существующее поведение полностью соответствует новому Protocol Layer.
+
+Также не изменялись:
+
+- Runtime Supervisor;
+- Reconnect;
+- Scheduler;
+- Heartbeat;
+- Trades Feed;
+- WebSocket Adapters;
+- Trade Stream Consistency;
+- Trade Recovery;
+- Acquisition Service;
+- Acquisition Registry.
+
+---
+
+# Unit-тестирование
+
+Новый Runtime Protocol Layer был покрыт структурными unit-тестами.
+
+Проверялись следующие сценарии:
+
+- реализация WebSocket Transport удовлетворяет Protocol;
+- реализация WebSocket Session удовлетворяет Protocol;
+- реализация Subscription Manager удовлетворяет Protocol;
+- реализация Command Dispatcher удовлетворяет Protocol;
+- реализация Event Publisher удовлетворяет Protocol;
+- неполный Transport отклоняется;
+- неполный Command Dispatcher отклоняется;
+- неполный Event Publisher отклоняется.
+
+Результат локального теста:
+
+```text
+8 passed
+```
+
+---
+
+# Регрессионное тестирование Runtime Layer
+
+После добавления новых контрактов выполнен полный прогон тестов каталога Runtime.
+
+Проверены:
+
+- Runtime Commands;
+- Runtime Events;
+- Transport Messages;
+- WebSocket Protocols;
+- новые dispatcher и publisher Protocol.
+
+Результат:
+
+```text
+34 passed
+```
+
+Это подтверждает, что расширение Protocol Layer не изменило существующее поведение Runtime.
+
+---
+
+# Расширенное регрессионное тестирование
+
+Дополнительно выполнен совместный прогон трёх связанных подсистем:
+
+```text
+Runtime
+Consistency
+Recovery
+```
+
+Результат:
+
+```text
+136 passed
+```
+
+Тем самым подтверждено:
+
+- Runtime Protocol Layer работает корректно;
+- Trade Stream Consistency не затронута;
+- Trade Stream State Store не затронут;
+- Trade Recovery не затронута;
+- новые контракты не создали циклических или скрытых зависимостей.
+
+---
+
+# Repository-wide аудит имён
+
+После первоначальной реализации был выполнен поиск по репозиторию.
+
+Аудит выявил существующую глобальную модель:
+
+```text
+src.runtime_events.models.RuntimeEvent
+```
+
+Поэтому первоначальные общие имена:
+
+```text
+RuntimeCommand
+RuntimeEvent
+RuntimeCommandDispatcherProtocol
+RuntimeEventPublisherProtocol
+```
+
+были уточнены.
+
+Итоговые имена:
+
+```text
+AcquisitionRuntimeCommand
+AcquisitionRuntimeEvent
+AcquisitionRuntimeCommandDispatcherProtocol
+AcquisitionRuntimeEventPublisherProtocol
+```
+
+Это разделяет:
+
+- Acquisition Runtime transport events;
+- глобальные application runtime events.
+
+Терминологическая неоднозначность полностью устранена.
+
+---
+
+# Обратная совместимость
+
+Build сохраняет полную обратную совместимость.
+
+Не изменились:
+
+- сигнатуры существующих WebSocket Protocol;
+- модели Runtime Commands;
+- модели Runtime Events;
+- модели Transport Messages;
+- алгоритмы Stream Consistency;
+- State Store;
+- Recovery Pipeline;
+- Trades Feed;
+- каноническая модель `Trade`.
+
+Новые контракты являются исключительно расширением публичного Protocol Layer.
+
+Существующие реализации не обязаны реализовывать новые Protocol до момента их подключения в последующих Build.
+
+---
+
+# Производительность
+
+Build не добавляет runtime-операций и не влияет на производительность системы.
+
+Типовые alias существуют только на уровне статической типизации.
+
+Protocol также не создают дополнительного runtime-поведения, за исключением стандартной structural runtime-проверки через `@runtime_checkable`, уже применявшейся в существующем коде.
+
+Следовательно Build не влияет на:
+
+- задержку обработки сообщений;
+- пропускную способность WebSocket;
+- использование памяти;
+- обработку Trade Stream;
+- Recovery Pipeline.
+
+---
+
+# Подтверждённые архитектурные инварианты
+
+## Runtime не знает предметную область
+
+Новые контракты принимают только Acquisition Runtime Commands и Events.
+
+Они не используют модели Trade, Quote, Candle или Order Book.
+
+---
+
+## Consistency не зависит от Runtime
+
+`TradeStreamConsistencyController` продолжает зависеть только от собственного State Store.
+
+---
+
+## Recovery не зависит от Runtime
+
+`TradeRecoveryController` продолжает использовать только `TradeStreamConsistencyProtocol`.
+
+---
+
+## Команды отделены от исполнения
+
+Command-модели описывают намерение.
+
+Dispatcher предоставляет контракт передачи команды.
+
+Реализация выполнения отсутствует в настоящем Build.
+
+---
+
+## События отделены от реакции
+
+Event-модели описывают инфраструктурный факт.
+
+Publisher предоставляет контракт публикации.
+
+Реакция потребителей отсутствует в настоящем Build.
+
+---
+
+## Runtime Service не входит в Scope
+
+Настоящий Build не создаёт сервисную реализацию и не определяет полный сервисный API.
+
+Эта ответственность закреплена за Build 060.22.
+
+---
+
+# Что не входит в Scope Build
+
+Настоящий Build сознательно ограничен расширением Runtime Protocol Layer.
+
+В него не входят:
+
+- реализация Command Dispatcher;
+- реализация Event Publisher;
+- Runtime Service;
+- Runtime Supervisor;
+- запуск и остановка Runtime;
+- обработка команд;
+- доставка событий подписчикам;
+- очередь событий;
+- Reconnect orchestration;
+- Heartbeat orchestration;
+- Scheduler;
+- интеграция Trades Feed;
+- интеграция Acquisition Service;
+- автоматический запуск Recovery;
+- восстановление подписок после reconnect;
+- Composition Root.
+
+Отсутствие перечисленных компонентов является осознанной границей Build.
+
+---
+
+# Архитектурное значение Build
+
+Несмотря на небольшой объём изменения production-кода, Build 060.21 является важным контрактным этапом.
+
+До него Runtime Layer обладал моделями команд и событий, но не имел формального интерфейса их передачи.
+
+После завершения Build появляются две стабильные точки расширения:
+
+```text
+AcquisitionRuntimeCommandDispatcherProtocol
+AcquisitionRuntimeEventPublisherProtocol
+```
+
+Именно через них последующие реализации смогут:
+
+- принимать инфраструктурные команды;
+- публиковать инфраструктурные события;
+- сохранять независимость от конкретного транспорта;
+- оставаться изолированными от предметной области Market Data Acquisition.
+
+Это создаёт основу для Build 060.22 без преждевременного внедрения сервисной реализации.
+
+---
+
+# Связь с последующими Build
+
+## Build 060.22 — Runtime Service Integration
+
+Будущая реализация Runtime Service должна использовать новые Protocol как публичные границы передачи команд и событий.
+
+---
+
+## Build 060.23 — Acquisition Integration
+
+Acquisition Layer сможет использовать Runtime Service через утверждённые контракты без прямой зависимости от внутренней реализации Runtime.
+
+---
+
+## Build 060.24 — Reconnect & Runtime Recovery
+
+Reconnect, resubscribe и запуск Recovery смогут строиться на типизированных командах и событиях без изменения существующих контрактов Consistency и Recovery.
+
+---
+
+## Build 060.25 — Integration & Regression
+
+Будет выполнена полная проверка взаимодействия Runtime, Acquisition, Consistency и Recovery.
+
+---
+
+# Заключение
+
+Build 060.21 завершает формирование базового Runtime Protocol Layer внутри подсистемы **Market Data Acquisition**.
+
+В рамках этапа не создавалась новая реализация и не менялось функциональное поведение системы.
+
+Вместо этого были введены две узкие инфраструктурные границы:
+
+```text
+AcquisitionRuntimeCommandDispatcherProtocol
+AcquisitionRuntimeEventPublisherProtocol
+```
+
+Они дополняют уже существующие:
+
+```text
+WebSocketTransportProtocol
+WebSocketSessionProtocol
+WebSocketSubscriptionManagerProtocol
+```
+
+и создают полный контрактный фундамент для будущего Runtime Service.
+
+Build сохранил независимость:
+
+- Runtime от бизнес-моделей;
+- Consistency от Runtime;
+- Recovery от Runtime;
+- Feed от внутренней реализации транспорта.
+
+Все изменения подтверждены unit- и regression-тестами.
+
+---
+
+# Итог Build
+
+После завершения Build 060.21 система обладает следующими возможностями.
+
+✓ Определён полный типовой набор Acquisition Runtime Commands.
+
+✓ Определён полный типовой набор Acquisition Runtime Events.
+
+✓ Введён публичный Protocol передачи Runtime-команд.
+
+✓ Введён публичный Protocol публикации Runtime-событий.
+
+✓ Устранён терминологический конфликт с глобальной подсистемой `src/runtime_events`.
+
+✓ Существующие Runtime Commands и Events сохранены без изменений.
+
+✓ Consistency и Recovery сохранены без изменений.
+
+✓ Runtime regression завершён результатом `34 passed`.
+
+✓ Расширенный regression завершён результатом `136 passed`.
+
+Build **060.21 — Runtime Protocol Integration** считается полностью завершённым и готовым к фиксации в Git.