feat: add market data architecture and complete migration through build 039

docs/market_intelligence/build_history.md

@@ -0,0 +1,296 @@
+# Build History
+
+Данный документ является общей историей разработки подсистемы **Market Intelligence**.
+
+Каждый Build представляет собой логически завершённый этап развития архитектуры.
+
+Подробное описание каждого Build хранится в каталоге:
+
+```text
+docs/market_intelligence/builds/
+```
+
+---
+
+# Статусы Build
+
+| Статус | Значение |
+|--------|----------|
+| ⏳ Planned | Build ещё не начат |
+| 🚧 In Progress | Build находится в разработке |
+| ✅ Accepted | Build полностью завершён |
+| 🔄 Replaced | Build заменён более новой реализацией |
+| ❌ Rejected | Build отклонён |
+
+---
+
+# История Build
+
+| Build | Компонент | Статус | Документ |
+|------:|-----------|:------:|----------|
+| 001 | Common / Enums | ✅ | `build-001-common-enums.md` |
+| 002 | Common / Types | ✅ | `build-002-common-types.md` |
+| 003 | Common / Constants | ✅ | `build-003-common-constants.md` |
+| 004 | Common / Reasons | ✅ | `build-004-common-reasons.md` |
+| 005 | Common / Scores | ✅ | `build-005-common-scores.md` |
+| 006 | Common / Models | ✅ | `build-006-common-models.md` |
+| 006.1 | Common / Models Extension (EngineMetadata) | ✅ | `build-006-1-common-models-engine-metadata.md` |
+| 007 | Common / Validation | ✅ | `build-007-common-validation.md` |
+| 008 | Common / Checks | ✅ | `build-008-common-checks.md` |
+| 009 | Common / Payloads | ✅ | `build-009-common-payloads.md` |
+| 010 | Common / Snapshots | ✅ | `build-010-common-snapshots.md` |
+| 011 | Common / Events | ✅ | `build-011-common-events.md` |
+| 012 | Common / Timeframes | ✅ | `build-012-common-timeframes.md` |
+| 013 | Engine Layer Architecture | ✅ | `build-013-engine-layer-architecture.md` |
+| 014.1 | Engine Base Contracts / Engine Protocol | ✅ | `build-014-1-engine-protocol.md` |
+| 014.2 | Engine Base / BaseEngine | ✅ | `build-014-2-engine-base.md` |
+| 014.3 | Engine Exceptions | ✅ | `build-014-3-engine-exceptions.md` |
+| 015.1 | Common Models Extension / RuntimeResult | ✅ | `build-015-1-common-models-runtime-result.md` |
+| 015.2 | Runtime Layer / Runtime Protocol | ✅ | `build-015-2-runtime-protocol.md` |
+| 015.3 | Common Models Extension / EngineRegistration | ✅ | `build-015-3-common-models-engine-registration.md` |
+| 015.4 | Runtime Layer / Runtime Registry | ✅ | `build-015-4-runtime-registry.md` |
+| 015.5 | Runtime Layer / Runtime Core | ✅ | `build-015-5-runtime-core.md` |
+| 015.6 | Runtime Layer / Runtime Dependencies | ✅ | `build-015-6-runtime-dependencies.md` |
+| 015.7 | Runtime Layer / Runtime Validation | ✅ | `build-015-7-runtime-validation.md` |
+| 015.8 | Runtime Layer / Runtime Service | ✅ | `build-015-8-runtime-service.md` |
+| 016 | Coordinator Layer Architecture | ✅ | `build-016-coordinator-layer-architecture.md` |
+| 016.1 | Common Models Extension / CoordinatorResult | ✅ | `build-016-1-common-models-coordinator-result.md` |
+| 016.2 | Coordinator Layer / Coordinator Protocol | ✅ | `build-016-2-coordinator-protocol.md` |
+| 016.3 | Coordinator Layer / Coordinator Exceptions | ✅ | `build-016-3-coordinator-exceptions.md` |
+| 016.4 | Coordinator Layer / Coordinator Validation | ✅ | `build-016-4-coordinator-validation.md` |
+| 016.5 | Coordinator Layer / Coordinator Rules | ✅ | `build-016-5-coordinator-rules.md` |
+| 016.6 | Coordinator Layer / Coordinator Service | ✅ | `build-016-6-coordinator-service.md` |
+| 017 | Trading Layer Architecture | ✅ | `build-017-trading-layer-architecture.md` |
+| 017.1 | Trading Layer / Trading Models | ✅ | `build-017-1-trading-models.md` |
+| 017.2 | Trading Layer / Trading Protocol | ✅ | `build-017-2-trading-protocol.md` |
+| 017.3 | Trading Layer / Trading Exceptions | ✅ | `build-017-3-trading-exceptions.md` |
+| 017.4 | Trading Layer / Trading Validation | ✅ | `build-017-4-trading-validation.md` |
+| 017.5 | Trading Layer / Trading Rules | ✅ | `build-017-5-trading-rules.md` |
+| 017.6 | Trading Layer / Trading Service | ✅ | `build-017-6-trading-service.md` |
+| 017.7 | Trading Boundary Correction | ✅ | `build-017-7-trading-boundary-correction.md` |
+
+---
+
+# Текущий прогресс Common
+
+| Компонент | Готовность |
+|-----------|-----------:|
+| Enums | 100% |
+| Types | 100% |
+| Constants | 100% |
+| Reasons | 100% |
+| Scores | 100% |
+| Models | 100% |
+| Validation | 100% |
+| Checks | 100% |
+| Payloads | 100% |
+| Snapshots | 100% |
+| Events | 100% |
+| Timeframes | 100% |
+
+> Build 015.1 расширил Common Layer новой моделью RuntimeResult без изменения его архитектурной структуры.
+> Build 015.3 расширил Common Layer новой моделью `EngineRegistration`, необходимой для реализации Runtime Registry, без изменения архитектуры Common Layer.
+
+**Common Layer завершён полностью.**
+
+---
+
+# Текущий прогресс Runtime
+
+| Компонент | Готовность |
+|-----------|-----------:|
+| Runtime Architecture | 100% |
+| Runtime Models | ✅ Completed |
+| Protocol | ✅ Completed |
+| Registry | ✅ Completed |
+| Runner | ✅ Completed |
+| Runtime Exceptions | ✅ Completed |
+| Dependencies | ✅ Completed |
+| Runtime Validation | ✅ Completed |
+| Runtime Service | ✅ Completed |
+
+> Build 015.5 реализовал `RuntimeRunner` — компонент Runtime Layer, отвечающий исключительно за создание экземпляра зарегистрированного Engine и вызов его метода `analyze()`.
+>
+> Во время Code Review Build 015.5 обнаружено частичное дублирование контрактов `EngineProtocol` и `EngineTypeProtocol`. Для обеспечения корректной статической типизации в `EngineTypeProtocol` добавлен метод `analyze()`. Архитектурное объединение контрактов не входит в Build 015.5 и может быть рассмотрено отдельным Build после завершения Runtime Layer.
+>
+> Build 015.6 реализовал `RuntimeDependencies`, отвечающий за проверку обязательных зависимостей Engine и построение порядка их выполнения посредством топологической сортировки. Компонент не выполняет Engine и не содержит аналитической логики.
+
+> Build 015.7 реализовал `RuntimeValidation` — централизованный компонент проверки готовности Runtime Layer. Компонент валидирует Registry и Metadata зарегистрированных Engine, а проверку зависимостей делегирует `RuntimeDependencies`, сохраняя принцип единственной ответственности.
+>
+> Во время Code Review подтверждено, что проверка повторной регистрации Engine в текущей реализации `RuntimeRegistry` практически недостижима из-за хранения регистраций в словаре. Тем не менее данная проверка сохранена как часть публичного контракта `RuntimeValidation` для обеспечения устойчивости архитектуры при возможном изменении внутренней реализации Registry.
+
+---
+
+# Текущий прогресс Coordinator
+
+| Компонент | Готовность |
+|-----------|-----------:|
+| Coordinator Architecture | ✅ Completed |
+| Coordinator Models | ✅ Completed |
+| Protocol | ✅ Completed |
+| Exceptions | ✅ Completed |
+| Validation | ✅ Completed |
+| Rules | ✅ Completed |
+| Service | ✅ Completed |
+
+
+> Build 016 утвердил архитектуру Coordinator Layer и определил его место между Runtime Layer и будущим Trading Layer.
+> Build не содержит реализации компонентов и фиксирует только архитектурные решения.
+
+> Build 016.1 расширил Common Layer новой межслойной моделью `CoordinatorResult`, а также моделями `CoordinatorDiagnostics` и `CoordinatorEvaluationMeta`. Coordinator Layer получил официальный выходной контракт без нарушения архитектурных границ Common Layer.
+
+> Build 016.2 добавил официальный публичный контракт `CoordinatorProtocol`, завершив формирование базового интерфейса Coordinator Layer. Контракт определяет единственную точку входа Coordinator и отделяет внешний API слоя от его будущей реализации.
+
+> Build 016.3 добавил собственную иерархию исключений Coordinator Layer (`CoordinatorError`, `InvalidCoordinatorResultError`, `CoordinatorValidationError`, `CoordinatorExecutionError`). Coordinator окончательно отделён от Runtime Layer в части обработки ошибок и получил собственное пространство исключений.
+
+> Build 016.4 добавил компонент `CoordinatorValidation`, выполняющий предварительную проверку входного `RuntimeResult`. Validation отделён от правил согласования и обеспечивает корректность входных данных до начала работы Coordinator Layer.
+
+> Build 016.5 реализовал компонент `CoordinatorRules`, отвечающий за преобразование `RuntimeResult` в `CoordinatorResult`. На текущем этапе создан базовый каркас согласования результатов Engine без реализации сложных механизмов весов, разрешения конфликтов и вероятностных моделей. Архитектура подготовлена к постепенному развитию правил согласования по мере появления специализированных Engine.
+
+> Build 016.6 завершил построение Coordinator Foundation, реализовав `CoordinatorService` — единую публичную точку входа Coordinator Layer. Service инкапсулирует `CoordinatorValidation` и `CoordinatorRules`, обеспечивая единый жизненный цикл обработки `RuntimeResult` и формирование итогового `CoordinatorResult`.
+
+---
+
+# Текущий прогресс Decision
+
+| Компонент | Готовность |
+|-----------|-----------:|
+| Decision Architecture | ✅ Completed |
+| Models | ✅ Completed |
+| Protocol | ✅ Completed |
+| Exceptions | ✅ Completed |
+| Validation | ✅ Completed |
+| Rules | ✅ Completed |
+| Service | ✅ Completed |
+
+> Build 017 утвердил архитектуру Trading Layer как самостоятельной подсистемы платформы Dzentra. Trading Layer использует `CoordinatorResult` как единственный аналитический вход и формирует `TradingDecision` — независимый объект, описывающий итоговое торговое решение. Реализация компонентов Trading Layer начинается с Build 017.1.
+
+> Build 017.1 расширил Common Layer моделями Trading Layer. Добавлены `TradingDiagnostics`, `TradingEvaluationMeta` и `TradingDecision`. `TradingDecision` становится официальным выходным контрактом Trading Layer и одновременно входным контрактом для будущих слоёв Execution, Risk и Portfolio. Модель намеренно содержит только общие характеристики торгового решения без конкретных торговых действий, размеров позиции или планов исполнения.
+
+> Build 017.2 реализовал `TradingProtocol` — официальный публичный контракт Trading Layer. Trading Layer теперь имеет единый интерфейс взаимодействия: принимает `CoordinatorResult` и возвращает `TradingDecision`. Контракт полностью изолирован от Runtime, Coordinator internals, биржевой инфраструктуры и содержит исключительно описание публичного API без реализации.
+
+> Build 017.3 сформировал собственое пространство исключений Trading Layer. Добавлены `TradingError`, `InvalidTradingDecisionError`, `TradingValidationError` и `TradingExecutionError`. Иерархия полностью изолирована от Runtime Layer и Coordinator Layer и станет единым механизмом обработки ошибок для будущих компонентов Validation, Rules и Service.
+
+> Build 017.4 реализовал `TradingValidation` — компонент предварительной проверки входного `CoordinatorResult`. Validation использует только публичный контракт Coordinator (`is_usable` и `has_errors`), не зависит от внутренних статусов Coordinator и отделяет проверку входных данных от бизнес-логики Trading Layer. Это стало первым архитектурным улучшением по сравнению с Coordinator Foundation, усилив слабую связанность между слоями.
+
+> Build 017.5 реализовал `TradingRules` — центральный компонент Trading Layer, отвечающий за преобразование `CoordinatorResult` в `TradingDecision`. На этапе Foundation Rules формирует только базовый объект `TradingDecision` без реализации торговых стратегий, расчёта риска, управления позицией или исполнения сделок. Это обеспечивает стабильный публичный контракт и позволяет в дальнейшем расширять бизнес-логику без изменения архитектуры слоя.
+
+> Build 017.6 завершил построение Trading Foundation. Реализован `TradingService` — единая публичная точка входа Trading Layer, объединяющая `TradingValidation` и `TradingRules`. Внешние компоненты платформы взаимодействуют с Trading Layer исключительно через `TradingProtocol`, что завершает формирование единого архитектурного стандарта для слоя.
+
+---
+
+## Архитектурная коррекция
+
+| Build | Описание | Статус |
+|-------:|----------|:------:|
+| 017.7 | Перенос Trading Foundation из `market_intelligence` в самостоятельный слой `decision` | ✅ |
+
+---
+
+# Общий прогресс архитектуры Dzentra
+
+| Layer | Состояние |
+|--------|----------|
+| Common Foundation | ✅ Completed |
+| Engine Foundation | ✅ Completed |
+| Runtime Foundation | ✅ Completed |
+| Coordinator Foundation | ✅ Completed |
+| Decision Foundation | ✅ Completed |
+| Execution Architecture | ⏳ Planned |
+
+> Build 017 сформировал фундамент будущего Decision Layer. Build 017.7 завершил архитектурную декомпозицию, выделив Decision в самостоятельную подсистему, полностью отделённую от Market Intelligence.
+
+> Начиная с Build 017.4 в Dzentra закрепляется принцип взаимодействия между слоями исключительно через публичные контракты. Trading Layer использует свойства `CoordinatorResult.is_usable` и `CoordinatorResult.has_errors`, не анализируя внутренние статусы Coordinator. Это снижает связанность подсистем и позволяет изменять внутреннюю реализацию Coordinator без изменения Trading Layer.
+
+> Build 017.6 завершил формирование Trading Foundation. Платформа Dzentra теперь имеет три полностью реализованных базовых слоя: Runtime Foundation, Coordinator Foundation и Trading Foundation. Все они построены по единому архитектурному шаблону (`Protocol → Validation → Rules → Service`), что обеспечивает единообразие разработки, тестирования и дальнейшего развития системы.
+
+> Build 017.7 завершил архитектурную декомпозицию платформы. Trading Foundation был выделен в самостоятельный слой `src/trading/decision`, полностью отделённый от `market_intelligence`. Это восстановило принцип единственной ответственности: Market Intelligence отвечает исключительно за анализ рынка, а Decision Layer — за принятие торгового решения.
+
+---
+
+# Итоговая схема платформы
+
+После Build 017.7 верхнеуровневая архитектура Dzentra выглядит следующим образом:
+
+```text
+Market Data
+        │
+        ▼
+Market Intelligence
+        │
+        ├── Common
+        ├── Engine
+        ├── Runtime
+        └── Coordinator
+        │
+        ▼
+Decision
+        │
+        ├── Models
+        ├── Protocol
+        ├── Validation
+        ├── Rules
+        └── Service
+        │
+        ▼
+Execution
+        │
+        ▼
+Exchange
+```
+
+Данная схема отражает окончательное разделение ответственности между анализом рынка, принятием торгового решения и будущим слоем исполнения.
+
+---
+
+# Архитектурная веха
+
+Build 017.7 завершает первый крупный этап разработки Dzentra.
+
+Полностью реализованы фундаментальные слои платформы:
+
+• Common Foundation
+• Engine Foundation
+• Runtime Foundation
+• Coordinator Foundation
+• Decision Foundation
+
+Во всех слоях используется единый архитектурный стандарт:
+
+Protocol
+↓
+Validation
+↓
+Rules
+↓
+Service
+
+Это означает, что дальнейшие подсистемы (Execution, Risk, Portfolio и другие) будут строиться по уже утверждённому шаблону, без изменения существующих публичных контрактов.
+
+Следующий этап развития платформы — построение Execution Layer, который станет первым потребителем `TradingDecision` и будет отвечать за преобразование торгового решения в конкретные действия по исполнению.
+
+---
+
+# Следующий Build
+
+```text
+Build 018
+
+Execution Layer Architecture
+```
+
+---
+
+# Правило сопровождения
+
+После завершения каждого Build обязательно выполняются следующие этапы:
+
+1. Compile Check (если есть исходный код).
+2. Architecture Review.
+3. Domain Review.
+4. Documentation Review.
+5. Обновление документации Build.
+6. Обновление Build History.
+7. Подтверждение пользователем завершения Build.
+
+Только после завершения полного жизненного цикла допускается переход к следующему Build.