build 039: complete Quotes Feed migration foundation

docs/market_intelligence/builds/build-015-2-runtime-protocol.md

@@ -0,0 +1,284 @@
+# Build 015.2 — Runtime Protocol
+
+**Engineering Build Document**
+
+---
+
+# Контроль документа
+
+| Свойство | Значение |
+|----------|-----------|
+| Build | 015.2 |
+| Название | Runtime Protocol |
+| Статус | **Accepted** |
+| Подсистема | Market Intelligence |
+| Layer | Runtime |
+| Тип | Architecture + Implementation |
+| Версия | 1.0 |
+| Язык | Русский |
+
+---
+
+# Причина появления Build
+
+После появления `RuntimeResult` стало возможно определить официальный контракт Runtime Layer.
+
+Runtime должен взаимодействовать с аналитическими Engine через единый стабильный интерфейс и не зависеть от конкретных реализаций Engine.
+
+---
+
+# Цель Build
+
+Создать файл:
+
+```text
+app/src/trading/market_intelligence/runtime/protocol.py
+```
+
+и определить в нём официальный контракт Runtime Layer.
+
+---
+
+# Architecture
+
+`RuntimeProtocol` описывает только внешний интерфейс Runtime.
+
+Runtime отвечает за:
+
+- регистрацию Engine;
+- удаление Engine;
+- получение зарегистрированного Engine;
+- выполнение анализа;
+- возврат агрегированного `RuntimeResult`.
+
+Runtime не отвечает за:
+
+- аналитику;
+- торговые решения;
+- порядок стратегий;
+- пользовательский интерфейс;
+- работу с биржей;
+- работу с БД;
+- журналирование.
+
+---
+
+# Architecture Review
+
+Проверка подтвердила:
+
+- Runtime работает через `EngineProtocol`;
+- Runtime регистрирует классы Engine, а не экземпляры;
+- Runtime возвращает `RuntimeResult`;
+- Runtime не знает конкретных Engine;
+- Runtime не содержит аналитики;
+- Runtime не содержит Coordinator-логики;
+- AutoTrade не изменяется.
+
+Архитектура Build признана корректной.
+
+---
+
+# Architecture Decision (ADR)
+
+## Решение
+
+Runtime Layer регистрирует классы Engine, а не экземпляры Engine.
+
+Официальный контракт:
+
+```python
+register_engine(
+    engine_type: type[EngineProtocol],
+) -> None
+```
+
+## Статус
+
+**Accepted**
+
+## Обоснование
+
+`EngineMetadata` доступна без создания экземпляра Engine через `get_metadata()`.
+
+Поэтому Runtime не обязан создавать объект Engine на этапе регистрации.
+
+Регистрация класса позволяет Runtime самостоятельно управлять жизненным циклом экземпляров Engine.
+
+## Обязательное правило
+
+Все Engine обязаны иметь конструктор без пользовательских параметров.
+
+Всё изменяемое состояние и конфигурация анализа передаются через:
+
+```text
+EngineContext
+```
+
+## Запрещено
+
+```python
+register_engine(engine: EngineProtocol)
+```
+
+Регистрация экземпляров Engine запрещена.
+
+## Последствия
+
+После принятия решения:
+
+- Runtime контролирует жизненный цикл Engine;
+- Engine не сохраняют состояние между запусками;
+- Runtime готов к параллельному выполнению;
+- Registry сможет хранить типы Engine;
+- добавление новых Engine не требует изменения Runtime.
+
+---
+
+# Build Design
+
+Реализуется контракт:
+
+```text
+RuntimeProtocol
+├── register_engine(engine_type)
+├── unregister_engine(engine_name)
+├── get_engine(engine_name)
+└── analyze(context)
+```
+
+Файл не содержит реализации Runtime.
+
+---
+
+# Implementation
+
+Реализован файл:
+
+```text
+app/src/trading/market_intelligence/runtime/protocol.py
+```
+
+Содержимое контракта:
+
+```python
+class RuntimeProtocol(Protocol):
+    def register_engine(
+        self,
+        engine_type: type[EngineProtocol],
+    ) -> None:
+        ...
+
+    def unregister_engine(
+        self,
+        engine_name: EngineName,
+    ) -> None:
+        ...
+
+    def get_engine(
+        self,
+        engine_name: EngineName,
+    ) -> type[EngineProtocol] | None:
+        ...
+
+    async def analyze(
+        self,
+        context: EngineContext,
+    ) -> RuntimeResult:
+        ...
+```
+
+---
+
+# Compile Check
+
+Проверка выполнена командой:
+
+```bash
+python -m compileall src/trading/market_intelligence
+```
+
+Результат:
+
+- успешно скомпилирован `runtime/protocol.py`;
+- синтаксические ошибки отсутствуют;
+- циклические зависимости отсутствуют.
+
+**Статус:** ✅ Passed
+
+---
+
+# Domain Review
+
+Проверено соответствие предметной области.
+
+`RuntimeProtocol`:
+
+- работает через `EngineProtocol`;
+- регистрирует классы Engine;
+- возвращает `RuntimeResult`;
+- не знает конкретных Engine;
+- не содержит аналитики;
+- не содержит Coordinator-логики;
+- не зависит от AutoTrade;
+- не обращается к бирже, БД, Telegram или EventBus;
+- получает изменяемые данные анализа только через `EngineContext`.
+
+**Статус:** ✅ Passed
+
+---
+
+# Documentation
+
+В рамках Build должны быть обновлены:
+
+- Build History;
+- Runtime Contract;
+- Engine Layer Architecture;
+- Runtime Architecture.
+
+---
+
+# Acceptance
+
+Build считается завершённым.
+
+Выполнены:
+
+- ✅ Architecture
+- ✅ Architecture Review
+- ✅ Architecture Decision (ADR)
+- ✅ Build Design
+- ✅ Implementation
+- ✅ Compile Check
+- ✅ Domain Review
+- ✅ Documentation
+- ✅ Acceptance
+
+Статус Build:
+
+**Accepted**
+
+---
+
+# Итоги Build
+
+В результате Build 015.2:
+
+- создан официальный контракт Runtime Layer;
+- Runtime получил стабильную зависимость от `EngineProtocol`;
+- закреплена регистрация классов Engine вместо экземпляров;
+- Runtime возвращает агрегированный `RuntimeResult`;
+- подготовлена основа для реализации Runtime Registry.
+
+---
+
+# Следующий Build
+
+```text
+Build 015.3
+
+Runtime Registry
+
+runtime/registry.py
+```