# Build 006.1 — Common Models Extension / EngineMetadata

**Engineering Build Document**

---

## Контроль документа

| Свойство | Значение |
|----------|-----------|
| Build | 006.1 |
| Название | Common Models Extension / EngineMetadata |
| Статус | **Accepted** |
| Подсистема | Market Intelligence |
| Layer | Common |
| Тип | Architecture Extension |
| Версия | 1.0 |
| Язык | Русский |

---

## Причина появления Build

Во время проектирования **Engine Layer** было обнаружено, что базовый контракт Engine требует наличия модели, описывающей сам Engine как архитектурный компонент.

Первоначально предполагалось, что данная модель относится к Engine Layer.

Однако архитектурный анализ показал, что она используется значительно шире.

Модель необходима для:

- Engine Layer;
- Runtime Layer;
- будущего Registry;
- будущего Coordinator;
- построения графа зависимостей;
- диагностики;
- документации.

Следовательно, данная модель является частью **Common Layer**, а не Engine Layer.

Для сохранения чистоты архитектуры было принято решение выпустить отдельный Build 006.1 вместо изменения уже принятого Build 006.

---

## Цель Build

Добавить в Common Layer новую базовую модель:

```text
EngineMetadata
```

которая описывает Engine как компонент платформы, а не результат его работы.

---

## Архитектурное решение

Модель размещается в:

```text
app/src/trading/market_intelligence/common/models.py
```

а не в:

```text
app/src/trading/market_intelligence/engine/
```

поскольку является общим контрактом платформы.

---

## Architecture Decision (ADR)

### Решение

Добавить модель `EngineMetadata` в Common Layer.

### Статус

**Accepted**

### Обоснование

Во время проектирования Engine Layer было установлено, что описание Engine используется не только самим Engine, но и Runtime, Registry, Coordinator и другими архитектурными компонентами.

Следовательно, `EngineMetadata` является общим контрактом платформы и должна располагаться в `common.models`.

Размещение модели в Engine Layer привело бы к неправильному направлению архитектурных зависимостей и нарушило бы принцип повторного использования общих моделей.

### Последствия

После принятия решения:

- Engine Layer использует `EngineMetadata` из Common Layer;
- Runtime зависит только от общих контрактов;
- Coordinator сможет получать описание Engine без знания его реализации;
- архитектурные зависимости остаются однонаправленными.

---

## Состав модели

```python
@dataclass(frozen=True, slots=True)
class EngineMetadata:
    # Описание Engine как компонента платформы.
    # Metadata не содержит аналитической логики и не является результатом анализа.
    # Она используется Runtime, Registry, Coordinator и документацией.
    name: EngineName
    version: EngineVersion
    description: str = ""
    supported_timeframes: tuple[TimeframeName, ...] = ()
    required_dependencies: tuple[EngineName, ...] = ()
    optional_dependencies: tuple[EngineName, ...] = ()
    enabled_by_default: bool = True
```

---

## Обоснование полей

### name

Уникальное имя Engine.

Используется Registry, Coordinator и журналированием.

---

### version

Версия реализации Engine.

Позволяет определять, какая именно версия логики сформировала результат анализа.

---

### description

Краткое описание назначения Engine.

Используется документацией, диагностикой и интерфейсами разработчика.

---

### supported_timeframes

Перечень поддерживаемых таймфреймов.

Позволяет Coordinator определить применимость Engine для конкретного анализа.

---

### required_dependencies

Перечень обязательных зависимостей.

Если хотя бы один требуемый Engine недоступен, выполнение данного Engine невозможно.

---

### optional_dependencies

Перечень необязательных зависимостей.

Их отсутствие не запрещает выполнение Engine, но может снизить качество анализа.

---

### enabled_by_default

Признак регистрации Engine по умолчанию.

Позволяет включать или отключать Engine без изменения Runtime.

---

## Что Build НЕ добавляет

Build сознательно не включает:

- Runtime;
- Registry;
- Coordinator;
- Dependency Graph;
- порядок запуска Engine;
- приоритеты выполнения;
- настройки Runtime;
- timeout;
- retry;
- cache policy;
- аналитическую логику.

Эти возможности относятся к следующим Build.

---

## Архитектурные последствия

После появления `EngineMetadata` становится возможным построение базового контракта Engine Layer.

Новая зависимость архитектуры выглядит следующим образом:

```text
Common Layer
│
├── EngineContext
├── EngineResult
├── EngineDependencyResult
└── EngineMetadata

        ▲

Engine Layer
│
├── EngineProtocol
└── Engine Implementation

        ▲

Runtime Layer

        ▲

Coordinator Layer
```

---

## Итоги Build

В результате Build 006.1:

- Common Layer получил новый общий контракт платформы;
- устранён архитектурный пробел, обнаруженный при проектировании Engine Layer;
- подготовлена основа для реализации `EngineProtocol`;
- Runtime сможет использовать единый контракт Engine без знания конкретных реализаций.

---

## Acceptance

Build считается завершённым после выполнения:

- ✅ Architecture Review
- ✅ Architecture Decision (ADR)
- ✅ Build Design
- ✅ Implementation
- ✅ Compile Check
- ✅ Domain Review
- ✅ Documentation
- ✅ Acceptance

---

## Следующий Build

```text
Build 014

Engine Base Contracts

engine/protocol.py
```