# 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
```