build 039: complete Quotes Feed migration foundation

docs/market_intelligence/builds/build-014-3-engine-exceptions.md

@@ -0,0 +1,235 @@
+# Build 014.3 — Engine Exceptions
+
+**Engineering Build Document**
+
+---
+
+# Контроль документа
+
+| Свойство | Значение |
+|----------|-----------|
+| Build | 014.3 |
+| Название | Engine Exceptions |
+| Статус | **Accepted** |
+| Подсистема | Market Intelligence |
+| Layer | Engine |
+| Тип | Architecture + Implementation |
+| Версия | 1.0 |
+| Язык | Русский |
+
+---
+
+# Причина появления Build
+
+После реализации `EngineProtocol` и `BaseEngine` возникла необходимость стандартизировать обработку внутренних ошибок Engine Layer.
+
+Использование стандартных исключений Python (`ValueError`, `NotImplementedError` и других) не отражало архитектурную модель платформы и затрудняло разделение инфраструктурных ошибок от штатных аналитических состояний.
+
+Настоящий Build вводит единый набор внутренних исключений Engine Layer и интегрирует их в `BaseEngine`.
+
+---
+
+# Цель Build
+
+Создать единый механизм внутренних исключений Engine Layer.
+
+Исключения предназначены исключительно для обнаружения нарушений инфраструктурного жизненного цикла Engine и не являются частью внешнего Runtime Contract.
+
+---
+
+# Architecture
+
+В Engine Layer вводится единая иерархия исключений.
+
+```text
+EngineError
+│
+├── EngineConfigurationError
+├── EngineContractError
+├── EngineContextError
+└── EngineExecutionError
+```
+
+Все исключения используются исключительно внутри Engine Layer.
+
+За пределы Engine Layer передаются только объекты `EngineResult`.
+
+---
+
+# Architecture Review
+
+Проверка подтвердила соответствие архитектурным принципам проекта.
+
+Подтверждено:
+
+- Runtime не зависит от исключений Engine;
+- Coordinator работает только с `EngineResult`;
+- штатные аналитические состояния не оформляются через исключения;
+- исключения используются исключительно для ошибок инфраструктуры Engine Layer;
+- архитектурные зависимости остаются однонаправленными.
+
+Архитектурное решение признано корректным.
+
+---
+
+# Architecture Decision (ADR)
+
+## Решение
+
+Ввести единый набор внутренних исключений Engine Layer.
+
+## Статус
+
+**Accepted**
+
+## Обоснование
+
+Исключения необходимы для описания нарушений жизненного цикла Engine:
+
+- ошибок конфигурации;
+- ошибок входного контекста;
+- нарушений архитектурного контракта;
+- внутренних ошибок реализации.
+
+При этом исключения не являются способом передачи аналитического результата.
+
+Внешним контрактом платформы остаётся исключительно `EngineResult`.
+
+## Последствия
+
+После принятия решения:
+
+- BaseEngine использует специализированные исключения Engine Layer;
+- Runtime не зависит от механизма исключений;
+- Coordinator продолжает работать только через официальный Runtime Contract;
+- архитектура сохраняет слабую связанность компонентов.
+
+---
+
+# Build Design
+
+Создан файл:
+
+```text
+app/src/trading/market_intelligence/engine/exceptions.py
+```
+
+Также обновлён файл:
+
+```text
+app/src/trading/market_intelligence/engine/base.py
+```
+
+BaseEngine переведён на использование новых исключений.
+
+---
+
+# Implementation
+
+Реализованы классы:
+
+```text
+EngineError
+├── EngineConfigurationError
+├── EngineContractError
+├── EngineContextError
+└── EngineExecutionError
+```
+
+В `BaseEngine` выполнены следующие изменения:
+
+- отсутствие `ENGINE_METADATA` приводит к `EngineConfigurationError`;
+- отсутствие обязательных полей `EngineContext` приводит к `EngineContextError`;
+- возврат объекта, отличного от `EngineResult`, приводит к `EngineContractError`.
+
+---
+
+# Compile Check
+
+Проверка выполнена командой:
+
+```bash
+python -m compileall src/trading/market_intelligence
+```
+
+Результат:
+
+- успешно скомпилирован `engine/exceptions.py`;
+- успешно скомпилирован обновлённый `engine/base.py`;
+- отсутствуют синтаксические ошибки;
+- отсутствуют циклические зависимости.
+
+После интеграции исключений выполнена повторная проверка компиляции.
+
+**Статус:** ✅ Passed
+
+---
+
+# Domain Review
+
+Проверено соответствие предметной области.
+
+Подтверждено:
+
+- исключения используются только внутри Engine Layer;
+- внешний контракт остаётся `EngineResult`;
+- штатные аналитические состояния не оформляются через исключения;
+- ошибки контекста отделены от ошибок конфигурации и нарушений контракта;
+- Runtime и Coordinator полностью изолированы от внутреннего механизма исключений.
+
+**Статус:** ✅ Passed
+
+---
+
+# Documentation
+
+В рамках Build обновлены:
+
+- Build History;
+- Engine Layer Architecture;
+- документация Engine Base.
+
+---
+
+# Acceptance
+
+Build считается завершённым.
+
+Выполнены:
+
+- ✅ Architecture
+- ✅ Architecture Review
+- ✅ Architecture Decision (ADR)
+- ✅ Build Design
+- ✅ Implementation
+- ✅ Compile Check
+- ✅ Domain Review
+- ✅ Documentation
+- ✅ Acceptance
+
+Статус Build:
+
+**Accepted**
+
+---
+
+# Итоги Build
+
+В результате Build 014.3:
+
+- создан единый механизм внутренних исключений Engine Layer;
+- `BaseEngine` переведён на использование специализированных исключений;
+- внешний Runtime Contract не изменился;
+- архитектура стала более согласованной и подготовлена к появлению первых аналитических Engine.
+
+---
+
+# Следующий Build
+
+```text
+Build 015
+
+Runtime Layer
+
+runtime/protocol.py
+```