# Runtime Architecture

Версия документа: **1.0**

Статус: **Architecture Specification**

---

# Назначение документа

Настоящий документ определяет архитектуру Runtime Layer подсистемы **Market Intelligence**.

Runtime Layer является инфраструктурным уровнем платформы и обеспечивает единый механизм выполнения аналитических Engine.

Документ описывает:

- место Runtime в архитектуре;
- обязанности Runtime;
- жизненный цикл выполнения Engine;
- взаимодействие Runtime с Common;
- взаимодействие Runtime с Coordinator;
- устройство Runtime Layer.

Настоящий документ является официальной спецификацией Runtime.

---

# Назначение Runtime

Runtime существует для того, чтобы каждый аналитический Engine выполнялся одинаковым способом.

Любой Engine должен:

- получать одинаковый входной объект;
- проходить одинаковые проверки;
- возвращать одинаковый результат;
- безопасно обрабатывать ошибки;
- одинаково взаимодействовать с Coordinator.

Именно Runtime обеспечивает эту унификацию.

---

# Место Runtime в архитектуре

Архитектура Market Intelligence имеет многоуровневую структуру.

```text
Common Layer
        ↓
Runtime Layer
        ↓
Engine Layer
        ↓
Coordinator Layer
        ↓
Execution Layer
```

Каждый уровень знает только о соседнем уровне.

Это исключает прямые зависимости между аналитическими движками и системой исполнения сделок.

---

# Основная ответственность Runtime

Runtime отвечает исключительно за инфраструктуру выполнения Engine.

В его обязанности входят:

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

---

# Что Runtime никогда не делает

Runtime никогда не:

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

Runtime является исключительно инфраструктурным уровнем.

---

# Структура Runtime

Runtime состоит из следующих компонентов.

```text
runtime/

├── protocol.py
├── metadata.py
├── registry.py
├── dependencies.py
├── runner.py
├── validation.py
└── base.py
```

Каждый компонент имеет единственную область ответственности.

---

---

## Общая архитектура Engine

Каждый аналитический Engine подсистемы **Market Intelligence** состоит из двух независимых частей.

```text
Engine

├── Metadata
└── Logic
```

Разделение Metadata и Logic является обязательным архитектурным стандартом платформы.

Обе части имеют разные зоны ответственности и не должны смешиваться между собой.

---

# Engine Metadata

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

Metadata существует независимо от выполнения аналитического алгоритма.

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

Metadata используется инфраструктурой платформы.

---

## Metadata содержит

Metadata может включать:

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

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

---

# Immutable Metadata

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

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

Metadata должна быть реализована как immutable-объект.

Например:

```text
EngineMetadata

↓

frozen dataclass
```

Во время выполнения Engine Metadata никогда не изменяется.

---

# Engine Logic

Logic представляет собой реализацию аналитического алгоритма.

Logic отвечает исключительно за анализ рынка.

Logic получает:

```text
EngineContext
```

и возвращает:

```text
EngineResult
```

Logic не должна:

- хранить описание Engine;
- выполнять регистрацию;
- объявлять собственные зависимости во время выполнения;
- изменять Metadata;
- принимать инфраструктурные решения Runtime.

---

# Runtime использует Metadata

Runtime взаимодействует с Engine через Metadata.

До запуска Engine Runtime может определить:

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

Runtime не должен получать эти сведения путём анализа реализации Engine.

---

# Registry использует Metadata

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

Registry отвечает за:

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

Registry не анализирует алгоритм работы Engine.

---

# Coordinator использует Metadata

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

Metadata позволяет определить зависимости между Engine ещё до начала анализа рынка.

Благодаря этому Coordinator не зависит от внутреннего устройства конкретного Engine.

---

# Разделение ответственности

Зоны ответственности распределяются следующим образом.

```text
Metadata

↓

Описание Engine

↓

Runtime / Registry / Coordinator


Logic

↓

Анализ рынка

↓

EngineResult
```

Metadata отвечает за архитектурное описание.

Logic отвечает за вычисления.

Runtime отвечает за выполнение.

Coordinator отвечает за оркестрацию.

---

# Архитектурное правило

Каждый новый Engine обязан состоять из двух независимых частей:

```text
Metadata

↓

Logic
```

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

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

---

# protocol.py

Определяет единый контракт аналитического Engine.

Любой Engine обязан реализовывать данный контракт.

Минимальный контракт включает:

- имя Engine;
- версию Engine;
- метод выполнения анализа;
- тип результата.

Наличие общего протокола позволяет Runtime запускать любой Engine одинаковым способом.

---

# base.py

Содержит базовую реализацию Engine.

Базовый класс предоставляет:

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

Базовый класс не содержит аналитических алгоритмов.

---

# runner.py

Runner отвечает за выполнение одного Engine.

Последовательность работы Runner:

```text
получение Engine

↓

валидация EngineContext

↓

запуск Engine

↓

получение EngineResult

↓

валидация результата

↓

возврат результата Coordinator
```

Runner является главным защитным механизмом Runtime.

---

# registry.py

Registry хранит перечень зарегистрированных Engine.

Основные задачи Registry:

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

Registry не выполняет Engine.

---

# dependencies.py

Dependency Layer описывает связи между Engine.

Он определяет:

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

На первом этапе Runtime выполняет только описание зависимостей.

---

# validation.py

Runtime Validation отвечает за проверку выполнения Engine.

Проверяются:

- корректность EngineContext;
- корректность EngineResult;
- соблюдение Runtime Contract;
- отсутствие запрещённых полей;
- полнота результата.

Runtime Validation использует Common Validation и не дублирует её.

---

# Жизненный цикл выполнения Engine

Каждый Engine проходит одинаковый цикл.

```text
EngineContext
        ↓
Runtime Validation
        ↓
Engine Runner
        ↓
Engine Execution
        ↓
Engine Result
        ↓
Runtime Validation
        ↓
Coordinator
```

Ни один этап не должен пропускаться.

---

# Обработка ошибок

Любое исключение должно оставаться внутри Runtime.

Runtime обязан вернуть корректный EngineResult даже при ошибке Engine.

Типичная схема выглядит следующим образом.

```text
Engine

↓

Exception

↓

Runner

↓

Diagnostics

↓

EngineResult(ERROR)

↓

Coordinator
```

Ошибка одного Engine не должна останавливать выполнение остальных.

---

# Работа с зависимостями

Engine никогда не обращается напрямую к другому Engine.

Вместо этого Runtime передаёт результаты зависимых Engine через EngineContext.

Таким образом достигаются:

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

---

# Взаимодействие с Common

Runtime использует Common как единственный источник базовых сущностей.

Используются:

- EngineContext;
- EngineResult;
- EngineScore;
- EngineConfidence;
- EngineDiagnostics;
- Validation;
- Checks;
- Payload Builder;
- Snapshot Builder;
- Event Builder.

Runtime не создаёт собственные версии этих моделей.

---

# Взаимодействие с Coordinator

Coordinator никогда не запускает Engine напрямую.

Вместо этого он использует Runtime.

```text
Coordinator

↓

Runner

↓

Engine

↓

EngineResult

↓

Coordinator
```

Это позволяет сохранить единый жизненный цикл выполнения.

---

# Масштабируемость

Архитектура Runtime должна позволять:

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

При этом существующие Engine не должны изменяться.

---

# Основной архитектурный принцип

Runtime развивается независимо от Engine.

Добавление нового Engine не должно требовать изменения Runtime.

Изменение Runtime допускается только при изменении самого механизма выполнения Engine.

---

# Заключение

Runtime Layer является центральным инфраструктурным компонентом подсистемы **Market Intelligence**.

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

Настоящий документ является официальной архитектурной спецификацией Runtime Layer.