build 039: complete Quotes Feed migration foundation

docs/market_intelligence/builds/build-014-1-engine-protocol.md

@@ -0,0 +1,243 @@
+# Build 014.1 — Engine Base Contracts / Engine Protocol
+
+**Engineering Build Document**
+
+---
+
+# Контроль документа
+
+| Свойство | Значение |
+|----------|-----------|
+| Build | 014.1 |
+| Название | Engine Base Contracts / Engine Protocol |
+| Статус | **Accepted** |
+| Подсистема | Market Intelligence |
+| Layer | Engine |
+| Тип | Architecture + Implementation |
+| Версия | 1.0 |
+| Язык | Русский |
+
+---
+
+# Причина появления Build
+
+После завершения проектирования **Engine Layer Architecture** началась разработка Runtime Layer.
+
+Во время проектирования было выявлено, что Runtime не может зависеть от конкретных аналитических движков.
+
+Для обеспечения независимости Runtime требуется единый официальный контракт любого Engine.
+
+Настоящий Build вводит данный контракт.
+
+---
+
+# Цель Build
+
+Создать минимальный контракт любого аналитического движка платформы **Market Intelligence**.
+
+Контракт должен позволять Runtime взаимодействовать с любым Engine без знания его внутренней реализации.
+
+---
+
+# Architecture
+
+Каждый Engine обязан предоставлять два обязательных элемента:
+
+```text
+EngineProtocol
+├── get_metadata()
+└── analyze(context)
+```
+
+Назначение методов:
+
+- `get_metadata()` — предоставляет описание Engine без создания экземпляра.
+- `analyze()` — выполняет анализ рыночного контекста и возвращает единый результат.
+
+Engine не содержит Runtime-инфраструктуры и не определяет порядок выполнения других Engine.
+
+---
+
+# Architecture Review
+
+Проверка показала соответствие архитектурным принципам проекта.
+
+Подтверждено:
+
+- Engine остаются независимыми друг от друга.
+- Metadata полностью отделена от аналитической логики.
+- Runtime сможет работать исключительно через контракт.
+- Coordinator не зависит от реализации Engine.
+- AutoTrade не затрагивается.
+
+Build признан архитектурно корректным.
+
+---
+
+# Architecture Decision (ADR)
+
+## Решение
+
+Ввести единый контракт:
+
+```text
+EngineProtocol
+```
+
+## Статус
+
+**Accepted**
+
+## Обоснование
+
+Runtime и будущий Coordinator должны работать с любым аналитическим движком посредством единого интерфейса.
+
+Описание Engine должно быть доступно без создания экземпляра.
+
+Поэтому контракт включает:
+
+- `get_metadata()`;
+- `analyze(context)`.
+
+## Последствия
+
+После принятия решения:
+
+- Runtime зависит только от `EngineProtocol`;
+- новые Engine могут свободно добавляться в платформу;
+- архитектурные зависимости остаются однонаправленными;
+- Engine Layer получает единый официальный контракт.
+
+---
+
+# Build Design
+
+Создан файл:
+
+```text
+app/src/trading/market_intelligence/engine/protocol.py
+```
+
+Файл содержит исключительно Protocol.
+
+Он не содержит:
+
+- реализации;
+- аналитической логики;
+- Runtime;
+- Coordinator;
+- Registry;
+- инфраструктуры исполнения.
+
+---
+
+# Implementation
+
+Реализован следующий контракт:
+
+```python
+class EngineProtocol(Protocol):
+
+    @classmethod
+    def get_metadata(cls) -> EngineMetadata:
+        ...
+
+    async def analyze(
+        self,
+        context: EngineContext,
+    ) -> EngineResult:
+        ...
+```
+
+Контракт использует только общие модели Common Layer:
+
+- EngineContext;
+- EngineMetadata;
+- EngineResult.
+
+---
+
+# Compile Check
+
+Проверено:
+
+- файл успешно импортируется;
+- отсутствуют циклические зависимости;
+- используются только модели Common Layer;
+- контракт не зависит от Runtime;
+- контракт не зависит от Coordinator.
+
+Build успешно проходит Compile Check.
+
+---
+
+# Domain Review
+
+Проверено соответствие предметной области.
+
+EngineProtocol:
+
+- описывает исключительно контракт аналитического Engine;
+- не содержит аналитической логики;
+- не содержит Runtime;
+- не содержит Coordinator;
+- не содержит торговой логики;
+- не зависит от конкретных Engine.
+
+Контракт признан соответствующим архитектуре платформы.
+
+---
+
+# Documentation
+
+В рамках Build обновлены:
+
+- Build History;
+- Runtime Contract;
+- Engine Layer Architecture;
+- Common Models Documentation.
+
+---
+
+# Acceptance
+
+Build считается завершённым.
+
+Выполнены:
+
+- ✅ Architecture
+- ✅ Architecture Review
+- ✅ Architecture Decision (ADR)
+- ✅ Build Design
+- ✅ Implementation
+- ✅ Compile Check
+- ✅ Domain Review
+- ✅ Documentation
+- ✅ Acceptance
+
+Статус Build:
+
+**Accepted**
+
+---
+
+# Итоги Build
+
+В результате Build 014.1:
+
+- создан официальный контракт Engine Layer;
+- Runtime получил стабильную точку зависимости;
+- завершён фундамент для создания BaseEngine;
+- архитектура стала полностью соответствовать принципу Dependency Inversion.
+
+---
+
+# Следующий Build
+
+```text
+Build 014.2
+
+Engine Base
+
+engine/base.py
+```