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

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 вводится единая иерархия исключений.

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

Создан файл:

app/src/trading/market_intelligence/engine/exceptions.py

Также обновлён файл:

app/src/trading/market_intelligence/engine/base.py

BaseEngine переведён на использование новых исключений.

---

Implementation

Реализованы классы:

EngineError
├── EngineConfigurationError
├── EngineContractError
├── EngineContextError
└── EngineExecutionError

В BaseEngine выполнены следующие изменения:

• отсутствие ENGINE_METADATA приводит к EngineConfigurationError;
• отсутствие обязательных полей EngineContext приводит к EngineContextError;
• возврат объекта, отличного от EngineResult, приводит к EngineContractError.

---

Compile Check

Проверка выполнена командой:

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

Build 015

Runtime Layer

runtime/protocol.py