# Build 015.3 — Common Models Extension / EngineRegistration

**Engineering Build Document**

---

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

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

---

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

Во время проектирования `RuntimeRegistry` было установлено, что хранение только класса Engine недостаточно.

Runtime Registry постоянно работает с двумя сущностями:

- типом Engine;
- его Metadata.

Постоянный вызов `Engine.get_metadata()` привёл бы к дублированию логики и усложнил бы реализацию Registry.

Для устранения этой проблемы введена единая модель регистрации Engine.

---

# Цель Build

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

```text
EngineRegistration
```

Модель описывает зарегистрированный аналитический движок и является единицей хранения Runtime Registry.

---

# Architecture

`EngineRegistration` представляет собой атомарную запись регистрации Engine.

Модель не является:

- Engine;
- Runtime;
- Registry;
- Runtime Contract.

Это исключительно модель Common Layer.

---

# Architecture Review

Проверка подтвердила:

- модель относится к Common Layer;
- Runtime Registry использует одну запись регистрации вместо двух независимых сущностей;
- отсутствует дублирование Metadata;
- сохраняется разделение Metadata и Logic;
- сохраняется однонаправленная архитектура зависимостей.

Архитектура Build признана корректной.

---

# Architecture Decision (ADR)

## Решение

Добавить модель:

```text
EngineRegistration
```

в `common.models`.

## Статус

**Accepted**

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

Во время проектирования Runtime Registry подтверждено, что регистрация Engine является самостоятельной архитектурной сущностью.

Модель объединяет:

- тип Engine;
- его Metadata.

При этом сама Metadata остаётся единственным источником информации об Engine.

## Главное правило

`EngineRegistration` не должен дублировать информацию, уже содержащуюся в `EngineMetadata`.

Запрещается добавлять отдельные поля:

```text
engine_name
engine_version
dependencies
priority
enabled_by_default
registered_at
```

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

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

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

---

# Build Design

В файл

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

добавлены:

```text
EngineTypeProtocol
EngineRegistration
```

`EngineTypeProtocol` используется как минимальный контракт класса Engine и позволяет избежать запрещённой зависимости:

```text
Common → Engine
```

---

# Implementation

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

```text
EngineTypeProtocol
```

```text
EngineRegistration
```

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

```text
EngineRegistration
├── engine_type
└── metadata
```

Модель не содержит дополнительных полей.

---

# Compile Check

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

```bash
python -m compileall src/trading/market_intelligence
```

Результат:

- успешно скомпилирован `common/models.py`;
- синтаксические ошибки отсутствуют;
- циклические зависимости отсутствуют.

**Статус:** ✅ Passed

---

# Domain Review

Проверено соответствие предметной области.

Подтверждено:

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

**Статус:** ✅ Passed

---

# Documentation

В рамках Build должны быть обновлены:

- Build History;
- Runtime Architecture;
- Engine Layer Architecture;
- Common Models Documentation.

---

# Acceptance

Build считается завершённым.

Выполнены:

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

Статус Build:

**Accepted**

---

# Итоги Build

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

- Common Layer получил модель `EngineRegistration`;
- Runtime Registry получил единицу хранения зарегистрированных Engine;
- устранено дублирование вызовов `Engine.get_metadata()`;
- сохранён принцип единственного источника истины;
- сохранена однонаправленная архитектура зависимостей между слоями.

---

# Архитектурные принципы, закреплённые Build

В рамках Build официально закреплены следующие правила.

### EngineRegistration не дублирует Metadata

Если информация уже содержится в `EngineMetadata`, она не должна повторяться в `EngineRegistration`.

### Один источник истины

Описание Engine хранится исключительно в `EngineMetadata`.

`EngineRegistration` только связывает тип Engine с его Metadata.

### Common Layer не зависит от Engine Layer

Для хранения типа Engine используется минимальный локальный протокол:

```text
EngineTypeProtocol
```

Это позволяет избежать запрещённой зависимости:

```text
Common → Engine
```

---

# Следующий Build

```text
Build 015.4

Runtime Registry

runtime/registry.py
```