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