# Architecture Decision Record 008

# Engine Metadata Separation

Статус: **Accepted**

Версия: **1.0**

---

# Контекст

Подсистема **Market Intelligence** строится как долгосрочная аналитическая платформа, состоящая из множества независимых специализированных Engine.

Ожидается, что со временем количество Engine будет постепенно увеличиваться.

Каждый Engine должен быть независимым компонентом, который можно:

- зарегистрировать;
- проверить;
- документировать;
- подключить к Runtime;
- использовать Coordinator;
- заменить новой реализацией.

До начала реализации Runtime было необходимо определить единый способ описания любого Engine.

---

# Проблема

Наивная реализация предполагает, что Runtime работает непосредственно с экземпляром Engine.

Например:

```python
engine.run(context)
```

При таком подходе Runtime ничего не знает о самом Engine до его создания.

Это приводит к нескольким проблемам.

Runtime не может заранее определить:

- имя Engine;
- назначение Engine;
- зависимости Engine;
- поддерживаемые таймфреймы;
- минимальные требования к данным;
- совместимость версии;
- возможность регистрации Engine.

В результате описание Engine смешивается с его логикой.

По мере роста количества Engine подобная архитектура становится всё менее масштабируемой.

---

# Решение

Каждый Engine разделяется на две полностью независимые части.

```text
Engine

├── Metadata
└── Logic
```

Metadata описывает Engine.

Logic реализует анализ рынка.

Runtime работает с Metadata.

Engine выполняет только аналитический алгоритм.

---

# Engine Metadata

Metadata представляет собой неизменяемое описание Engine.

Metadata должна содержать всю информацию, необходимую инфраструктуре платформы.

Например:

- имя Engine;
- версия Engine;
- отображаемое имя;
- краткое описание;
- зависимости;
- поддерживаемые таймфреймы;
- минимальные требования к входным данным;
- дополнительные возможности Engine.

Metadata не содержит вычисляемых значений.

Metadata не зависит от состояния рынка.

Metadata не изменяется во время выполнения Engine.

---

# Engine Logic

Logic содержит исключительно алгоритм анализа.

Logic получает:

```text
EngineContext
```

и возвращает

```text
EngineResult
```

Logic не должна хранить архитектурную информацию о себе.

Она не отвечает за:

- регистрацию;
- описание возможностей;
- зависимости;
- документацию;
- совместимость.

Эти сведения находятся исключительно в Metadata.

---

# Immutable Metadata

Metadata является полностью неизменяемой структурой.

После создания Metadata запрещается изменять её содержимое.

Runtime рассматривает Metadata как константу.

Engine не имеет права изменять собственное описание во время выполнения.

---

# Metadata Access

Metadata должна быть доступна инфраструктуре платформы без создания экземпляра Engine.

Runtime, Registry и Coordinator должны иметь возможность получить полное описание Engine до начала его выполнения.

Предпочтительной реализацией является хранение Metadata как неизменяемого атрибута класса Engine.

Например:

```python
TrendEngine.metadata
```

или отдельной неизменяемой структуры:

```python
TREND_ENGINE_METADATA
```

Создание экземпляра Engine исключительно для получения Metadata не допускается.

Это позволяет Runtime:

- регистрировать Engine;
- строить граф зависимостей;
- проверять совместимость;
- формировать документацию;
- анализировать архитектуру платформы;

без запуска аналитических алгоритмов.

---

# Причины принятия решения

Разделение Metadata и Logic обеспечивает:

- единый способ описания Engine;
- независимость инфраструктуры от реализации Engine;
- возможность автоматической регистрации Engine;
- возможность построения графа зависимостей;
- возможность автоматического формирования документации;
- возможность проверки совместимости;
- упрощение тестирования;
- упрощение сопровождения.

---

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

После принятия настоящего решения любой новый Engine обязан состоять из двух независимых частей:

```text
Metadata

↓

Logic
```

Создание Engine без Metadata считается нарушением архитектурного стандарта платформы.

---

# Влияние на Runtime

Runtime работает исключительно через Metadata.

Runtime не должен получать архитектурную информацию путём анализа реализации Engine.

Все инфраструктурные механизмы используют Metadata как единственный источник архитектурного описания Engine.

---

# Влияние на Registry

Engine Registry использует Metadata для:

- регистрации Engine;
- проверки уникальности;
- поиска Engine;
- проверки зависимостей;
- формирования списка доступных Engine.

Registry не анализирует реализацию Engine.

---

# Влияние на Coordinator

Coordinator использует Metadata для определения порядка выполнения Engine.

Coordinator не должен знать внутреннее устройство конкретного Engine.

---

# Совместимость

Настоящее решение является обязательным для всех существующих и будущих Engine подсистемы **Market Intelligence**.

Изменение данного правила допускается только посредством нового Architecture Decision Record.

---

# Статус решения

Настоящее решение принято как долгосрочный архитектурный стандарт платформы **Dzentra Market Intelligence**.

Все последующие Runtime и Engine Build должны соответствовать данному ADR.