build 039: complete Quotes Feed migration foundation

docs/market_intelligence/decisions/README.md

@@ -0,0 +1,130 @@
+# Architecture Decisions
+
+Каталог **decisions/** содержит архитектурные решения (ADR — Architecture Decision Record), принятые во время разработки подсистемы **Market Intelligence**.
+
+В отличие от технической документации, ADR отвечают не на вопрос:
+
+> **Что реализовано?**
+
+а на вопрос:
+
+> **Почему архитектура построена именно так?**
+
+Каждое решение принимается только после возникновения реальной инженерной необходимости.
+
+Создание ADR "на будущее" не допускается.
+
+---
+
+# Иерархия архитектурных решений
+
+Архитектурные решения разделены на три уровня.
+
+```text
+Философия разработки
+        ↓
+Правила разработки
+        ↓
+Архитектурные ограничения
+```
+
+Каждый следующий уровень основывается на предыдущем.
+
+---
+
+# Level 1 — Философия разработки
+
+Данные решения определяют общий подход к развитию платформы.
+
+| Decision | Назначение |
+|----------|------------|
+| 001 | Architecture First |
+| 002 | Build Lifecycle |
+
+---
+
+## Основная идея
+
+Сначала проектируется архитектура.
+
+Затем архитектура развивается небольшими завершёнными Build.
+
+---
+
+# Level 2 — Правила разработки
+
+Данные решения определяют инженерный процесс разработки.
+
+| Decision | Назначение |
+|----------|------------|
+| 003 | Domain Review |
+| 004 | No Existing Code Assumptions |
+| 005 | Human Readable Comments |
+| 007 | Documentation Is Code |
+
+---
+
+## Основная идея
+
+Каждый Build проходит обязательные проверки качества.
+
+Разработка ведётся только на основе существующего кода проекта.
+
+Комментарии объясняют архитектурный смысл.
+
+Документация развивается одновременно с кодом.
+
+---
+
+# Level 3 — Архитектурные ограничения
+
+Данные решения определяют фундаментальные ограничения архитектуры платформы.
+
+| Decision | Назначение |
+|----------|------------|
+| 006 | Immutable Engine Contract |
+
+---
+
+## Основная идея
+
+Все аналитические движки используют единый неизменяемый контракт результатов.
+
+---
+
+# Правила создания новых Decision
+
+Новый ADR создаётся только при выполнении следующих условий:
+
+- возникла реальная инженерная проблема;
+- принято архитектурное решение, влияющее на развитие платформы;
+- решение невозможно корректно описать только комментариями в коде;
+- решение будет полезно при дальнейшем сопровождении проекта.
+
+Создание ADR "на всякий случай" запрещается.
+
+---
+
+# Жизненный цикл ADR
+
+Каждый Architecture Decision проходит одинаковый цикл.
+
+```text
+Проблема
+        ↓
+Анализ вариантов
+        ↓
+Принятие решения
+        ↓
+Документирование
+        ↓
+Использование в проекте
+```
+
+---
+
+# Главный принцип
+
+Architecture Decision Record являются частью архитектуры Dzentra.
+
+Они сохраняют инженерные знания проекта и позволяют развивать платформу последовательно даже спустя годы после принятия первоначальных решений.

docs/market_intelligence/decisions/decision-001-architecture-first.md

@@ -0,0 +1,157 @@
+# Decision 001 — Architecture First
+
+## Статус
+
+**Accepted**
+
+---
+
+# Дата принятия
+
+Принято во время начала проектирования Stage-08.2 **Engine Runtime Contract**.
+
+---
+
+# Контекст
+
+Проект Dzentra развивается как долгосрочная автономная торговая платформа.
+
+На ранних этапах развития стало очевидно, что традиционный подход:
+
+```text
+Идея
+    ↓
+Написание кода
+    ↓
+Попытка встроить код в архитектуру
+```
+
+со временем приводит к накоплению технического долга, усложнению зависимостей и постепенной деградации структуры проекта.
+
+Для платформы, которая должна развиваться на протяжении многих лет, такой подход признан неприемлемым.
+
+---
+
+# Проблема
+
+При разработке без предварительного архитектурного проектирования обычно возникают следующие последствия:
+
+- смешивание зон ответственности компонентов;
+- появление временных решений, остающихся в проекте навсегда;
+- дублирование логики;
+- циклические зависимости;
+- усложнение сопровождения;
+- постоянный рефакторинг уже написанного кода.
+
+Каждое новое изменение становится дороже предыдущего.
+
+---
+
+# Рассмотренные варианты
+
+## Вариант 1
+
+Сначала писать код, затем при необходимости выполнять рефакторинг.
+
+### Преимущества
+
+- быстрый старт реализации;
+- минимальные затраты на начальном этапе.
+
+### Недостатки
+
+- рост технического долга;
+- потеря целостности архитектуры;
+- постоянные изменения уже работающего кода;
+- усложнение тестирования;
+- снижение предсказуемости развития проекта.
+
+---
+
+## Вариант 2
+
+Сначала проектировать архитектуру, затем реализовывать код.
+
+### Преимущества
+
+- понятные зоны ответственности;
+- отсутствие случайных зависимостей;
+- возможность масштабирования;
+- предсказуемое развитие платформы;
+- уменьшение объёма последующего рефакторинга;
+- единый стиль разработки.
+
+### Недостатки
+
+- увеличение времени подготовки перед реализацией;
+- необходимость поддерживать архитектурную документацию в актуальном состоянии.
+
+---
+
+# Принятое решение
+
+Перед началом реализации любого нового компонента обязательно выполняется архитектурное проектирование.
+
+Минимальный цикл разработки выглядит следующим образом:
+
+```text
+Идея
+        ↓
+Architecture Design
+        ↓
+Architecture Review
+        ↓
+Implementation
+        ↓
+Compile Check
+        ↓
+Domain Review
+        ↓
+Documentation Update
+        ↓
+Build Closed
+```
+
+Переход к написанию кода допускается только после определения места компонента в общей архитектуре платформы.
+
+---
+
+# Причины принятия решения
+
+Использование подхода **Architecture First** позволяет:
+
+- сохранять целостность архитектуры;
+- уменьшать технический долг;
+- заранее определять ответственность компонентов;
+- предотвращать появление случайных зависимостей;
+- упрощать сопровождение проекта;
+- обеспечивать предсказуемое развитие платформы.
+
+---
+
+# Последствия
+
+После принятия данного решения:
+
+- архитектура всегда проектируется раньше реализации;
+- новый код не появляется без заранее определённой роли;
+- каждый компонент имеет понятную область ответственности;
+- архитектурные решения фиксируются документально;
+- развитие платформы становится последовательным и контролируемым.
+
+---
+
+# Связанные документы
+
+- `architecture_principles.md`
+- `runtime_contract.md`
+- `development_process.md`
+- `build_history.md`
+
+---
+
+# История изменений
+
+| Версия | Изменение |
+|---------|-----------|
+| 1.0 | Первое принятие архитектурного решения. |

docs/market_intelligence/decisions/decision-002-build-lifecycle.md

@@ -0,0 +1,209 @@
+# Decision 002 — Build Lifecycle
+
+## Статус
+
+**Accepted**
+
+---
+
+# Дата принятия
+
+Принято во время проектирования Stage-08.2 **Engine Runtime Contract**.
+
+---
+
+# Контекст
+
+После принятия решения **Architecture First** возник вопрос:
+
+> Каким образом должна развиваться архитектура платформы?
+
+Были рассмотрены различные подходы к организации процесса разработки.
+
+Главной целью являлось обеспечение стабильного роста платформы без накопления незавершённых изменений и архитектурной деградации.
+
+---
+
+# Проблема
+
+При длительной разработке больших систем часто возникают следующие проблемы:
+
+- одновременно изменяется большое количество компонентов;
+- невозможно определить момент логического завершения работы;
+- документация перестаёт соответствовать коду;
+- проверки выполняются нерегулярно;
+- ошибки обнаруживаются слишком поздно;
+- архитектурные решения принимаются уже после написания кода.
+
+В результате становится сложно определить, какая часть системы действительно готова.
+
+---
+
+# Рассмотренные варианты
+
+## Вариант 1
+
+Разрабатывать большие функциональные блоки без промежуточных этапов.
+
+### Преимущества
+
+- меньше организационной работы;
+- меньше промежуточной документации.
+
+### Недостатки
+
+- большие объёмы изменений;
+- сложность проверки;
+- высокий риск архитектурных ошибок;
+- длительный цикл обратной связи;
+- увеличение сложности сопровождения.
+
+---
+
+## Вариант 2
+
+Разбивать разработку на небольшие логически завершённые Build.
+
+Каждый Build представляет собой самостоятельный этап разработки.
+
+После завершения Build выполняются все проверки качества.
+
+### Преимущества
+
+- небольшие объёмы изменений;
+- высокая предсказуемость;
+- возможность проверки каждого этапа;
+- документация развивается одновременно с кодом;
+- упрощается поиск ошибок;
+- архитектурные решения принимаются постепенно.
+
+### Недостатки
+
+- требуется сопровождать историю Build;
+- увеличивается объём инженерной документации.
+
+---
+
+# Принятое решение
+
+Разработка Dzentra ведётся исключительно последовательностью небольших логически завершённых Build.
+
+Каждый Build должен иметь:
+
+- понятную цель;
+- ограниченную область изменений;
+- завершённую реализацию;
+- обязательную проверку качества;
+- обновлённую документацию.
+
+Build считается завершённым только после прохождения полного жизненного цикла.
+
+---
+
+# Жизненный цикл Build
+
+Каждый Build проходит следующие этапы:
+
+```text
+Architecture Design
+        ↓
+Implementation
+        ↓
+Compile Check
+        ↓
+Architecture Review
+        ↓
+Domain Review
+        ↓
+Documentation Update
+        ↓
+User Confirmation
+        ↓
+Build Closed
+```
+
+До завершения всех этапов переход к следующему Build не допускается.
+
+---
+
+# Причины принятия решения
+
+Использование небольших Build обеспечивает:
+
+- постепенное развитие архитектуры;
+- раннее обнаружение ошибок;
+- минимизацию технического долга;
+- постоянную актуальность документации;
+- простоту сопровождения;
+- возможность безопасного возврата к предыдущим решениям.
+
+---
+
+# Последствия
+
+После принятия настоящего решения:
+
+- каждая новая функциональность реализуется отдельным Build;
+- Build имеет собственную документацию;
+- Build фиксируется в общей истории разработки;
+- архитектурные решения принимаются постепенно;
+- документация обновляется одновременно с исходным кодом.
+
+---
+
+# Правила Build
+
+Каждый Build должен удовлетворять следующим требованиям.
+
+## Логическая завершённость
+
+Build реализует одну законченную архитектурную задачу.
+
+---
+
+## Независимость
+
+Build должен быть понятен без изучения будущих Build.
+
+---
+
+## Проверяемость
+
+После завершения Build должны существовать все необходимые проверки.
+
+---
+
+## Документирование
+
+Каждый Build сопровождается отдельным документом в каталоге:
+
+```text
+docs/market_intelligence/builds/
+```
+
+---
+
+## История
+
+Каждый завершённый Build регистрируется в:
+
+```text
+build_history.md
+```
+
+---
+
+# Связанные документы
+
+- `development_process.md`
+- `architecture_principles.md`
+- `build_history.md`
+- `runtime_contract.md`
+
+---
+
+# История изменений
+
+| Версия | Изменение |
+|---------|-----------|
+| 1.0 | Первое принятие архитектурного решения. |

docs/market_intelligence/decisions/decision-003-domain-review.md

@@ -0,0 +1,181 @@
+# Decision 003 — Domain Review
+
+## Статус
+
+**Accepted**
+
+---
+
+# Дата принятия
+
+Принято во время проектирования Stage-08.2 **Engine Runtime Contract**.
+
+---
+
+# Контекст
+
+После внедрения обязательного **Architecture Review** стало очевидно, что архитектурной проверки недостаточно.
+
+Компонент может быть:
+
+- технически корректным;
+- соответствовать архитектуре;
+- успешно компилироваться;
+
+но при этом нарушать предметную область Market Intelligence.
+
+Например, аналитический движок может начать принимать торговые решения, рассчитывать размер позиции или управлять открытой сделкой.
+
+Подобные изменения не являются архитектурными ошибками, но полностью нарушают назначение аналитического уровня платформы.
+
+---
+
+# Проблема
+
+Обычная архитектурная проверка отвечает на вопрос:
+
+> **Правильно ли построен компонент?**
+
+Однако она не отвечает на другой вопрос:
+
+> **Правильно ли компонент выполняет свою роль в предметной области?**
+
+Без отдельной проверки постепенно появляются следующие проблемы:
+
+- аналитика начинает принимать торговые решения;
+- смешиваются обязанности разных Engine;
+- появляются термины с разным смыслом;
+- один и тот же объект начинает означать разные вещи;
+- снижается объяснимость результатов анализа.
+
+Подобные изменения сложно обнаружить техническими средствами.
+
+---
+
+# Рассмотренные варианты
+
+## Вариант 1
+
+Использовать только Compile Check и Architecture Review.
+
+### Преимущества
+
+- проще процесс разработки;
+- меньше этапов проверки.
+
+### Недостатки
+
+- отсутствует контроль предметной области;
+- возможно постепенное смешивание аналитики и торговли;
+- ошибки обнаруживаются слишком поздно.
+
+---
+
+## Вариант 2
+
+Ввести отдельный Domain Review.
+
+После проверки архитектуры дополнительно анализируется соответствие предметной области.
+
+### Преимущества
+
+- сохраняется чистота аналитического уровня;
+- исключается смешивание ответственности;
+- поддерживается единая терминология;
+- повышается качество архитектурных решений;
+- сохраняется объяснимость системы.
+
+### Недостатки
+
+- увеличивается время проверки Build;
+- требуется дополнительная инженерная дисциплина.
+
+---
+
+# Принятое решение
+
+Каждый логически завершённый Build проходит обязательный **Domain Review**.
+
+Domain Review выполняется после успешного прохождения:
+
+- Compile Check;
+- Architecture Review.
+
+---
+
+# Цель Domain Review
+
+Domain Review проверяет не качество кода, а корректность поведения компонента относительно предметной области.
+
+Главный вопрос проверки:
+
+> **Соответствует ли данный компонент своей архитектурной роли?**
+
+---
+
+# Что проверяется
+
+Во время Domain Review анализируются:
+
+- корректность используемой терминологии;
+- соответствие названий реальным рыночным процессам;
+- отсутствие торговых решений внутри аналитических компонентов;
+- отсутствие смешивания обязанностей разных Engine;
+- понятность комментариев разработчику;
+- соответствие Engine Runtime Contract;
+- объяснимость результатов анализа;
+- отсутствие скрытых смыслов и неоднозначных терминов.
+
+---
+
+# Что не проверяется
+
+Domain Review не оценивает:
+
+- стиль оформления Python-кода;
+- синтаксис;
+- производительность реализации;
+- качество алгоритмов;
+- оптимизацию вычислений.
+
+Эти вопросы относятся к другим этапам разработки.
+
+---
+
+# Причины принятия решения
+
+Использование Domain Review позволяет:
+
+- сохранить чистоту предметной области;
+- избежать постепенного смешивания анализа рынка и торговли;
+- поддерживать единый словарь терминов;
+- обеспечить объяснимость результатов;
+- сохранить независимость аналитических движков.
+
+---
+
+# Последствия
+
+После принятия настоящего решения:
+
+- каждый Build проходит Domain Review;
+- нарушение предметной области считается архитектурным дефектом;
+- аналитические компоненты остаются независимыми от торговой логики;
+- новые Engine обязаны соответствовать принятой терминологии.
+
+---
+
+# Связанные документы
+
+- `architecture_principles.md`
+- `development_process.md`
+- `runtime_contract.md`
+- `reviews/domain_reviews.md`
+
+---
+
+# История изменений
+
+| Версия | Изменение |
+|---------|-----------|
+| 1.0 | Первое принятие архитектурного решения. |

docs/market_intelligence/decisions/decision-004-no-existing-code-assumptions.md

@@ -0,0 +1,171 @@
+# Decision 004 — No Existing Code Assumptions
+
+## Статус
+
+**Accepted**
+
+---
+
+# Дата принятия
+
+Принято во время реализации первых Build подсистемы **Market Intelligence**.
+
+---
+
+# Контекст
+
+Во время разработки новых компонентов неоднократно возникала ситуация, когда для продолжения работы требовалось знать текущее состояние проекта.
+
+Например:
+
+- существующие модели;
+- типы;
+- контракты;
+- Runtime State;
+- Engine Contract;
+- общие структуры данных.
+
+Использование предположений о содержимом существующих файлов приводило бы к риску расхождения между проектируемым кодом и реальным состоянием проекта.
+
+Для долгоживущей платформы подобный подход признан неприемлемым.
+
+---
+
+# Проблема
+
+Во время проектирования новых компонентов существует соблазн предположить, что существующий файл имеет ожидаемую структуру.
+
+Например:
+
+> «Наверное, эта модель уже существует.»
+
+или
+
+> «Скорее всего, поле называется именно так.»
+
+Подобные предположения могут привести к следующим последствиям:
+
+- дублирование уже существующих сущностей;
+- несовместимые контракты;
+- повторная реализация одинаковой логики;
+- нарушение принципа единого источника истины;
+- увеличение объёма последующего рефакторинга.
+
+---
+
+# Рассмотренные варианты
+
+## Вариант 1
+
+Использовать предположения о текущем состоянии проекта.
+
+### Преимущества
+
+- быстрее писать код;
+- меньше дополнительных запросов.
+
+### Недостатки
+
+- высокий риск ошибок;
+- потеря синхронизации с реальным проектом;
+- появление дублирующих сущностей;
+- снижение качества архитектуры.
+
+---
+
+## Вариант 2
+
+Использовать существующий код как единственный источник истины.
+
+Если для реализации требуется информация о существующем компоненте, соответствующий файл предварительно запрашивается у пользователя.
+
+После получения файла все архитектурные решения принимаются исключительно на основании его фактического содержимого.
+
+### Преимущества
+
+- отсутствие ложных предположений;
+- единый источник истины;
+- отсутствие дублирования;
+- минимизация архитектурных ошибок;
+- синхронное развитие проекта и документации.
+
+### Недостатки
+
+- требуется дополнительный шаг перед началом реализации.
+
+---
+
+# Принятое решение
+
+При реализации новых компонентов запрещается делать предположения о содержимом существующих файлов.
+
+Если новый компонент зависит от уже существующей части проекта, соответствующий файл должен быть предварительно получен и использован как единственный источник истины.
+
+---
+
+# Правило разработки
+
+Перед началом реализации необходимо определить, зависит ли новый компонент от существующего кода.
+
+Если зависимость существует, разработчик обязан запросить соответствующий файл до начала проектирования или написания кода.
+
+После получения файла запрещается создавать альтернативные реализации уже существующих сущностей.
+
+---
+
+# Причины принятия решения
+
+Использование существующего кода как единственного источника истины позволяет:
+
+- исключить дублирование;
+- избежать несовместимых контрактов;
+- сохранить целостность архитектуры;
+- уменьшить объём последующего рефакторинга;
+- обеспечить единое понимание структуры проекта.
+
+---
+
+# Последствия
+
+После принятия настоящего решения:
+
+- архитектурные решения принимаются только на основании реального состояния проекта;
+- существующие модели повторно используются вместо повторной реализации;
+- новые сущности создаются только при их фактическом отсутствии;
+- вероятность архитектурных расхождений существенно снижается.
+
+---
+
+# Практическое применение
+
+Перед созданием любого нового файла выполняется следующий вопрос:
+
+> **Требуется ли для его реализации существующий код проекта?**
+
+Если ответ положительный, необходимые файлы запрашиваются до начала работы.
+
+Данное правило распространяется на:
+
+- модели;
+- контракты;
+- состояния Runtime;
+- общие типы;
+- перечисления;
+- вспомогательные функции;
+- архитектурные ограничения.
+
+---
+
+# Связанные документы
+
+- `architecture_principles.md`
+- `development_process.md`
+- `runtime_contract.md`
+
+---
+
+# История изменений
+
+| Версия | Изменение |
+|---------|-----------|
+| 1.0 | Первое принятие архитектурного решения. |

docs/market_intelligence/decisions/decision-005-human-readable-comments.md

@@ -0,0 +1,198 @@
+# Decision 005 — Human Readable Comments
+
+## Статус
+
+**Accepted**
+
+---
+
+# Дата принятия
+
+Принято во время разработки подсистемы **Market Intelligence**.
+
+---
+
+# Контекст
+
+Во время проектирования первых компонентов Market Intelligence стало очевидно, что большая часть сложности проекта связана не с алгоритмами, а с пониманием их назначения.
+
+Даже технически корректный код может быть труден для сопровождения, если разработчику приходится самостоятельно догадываться:
+
+- зачем существует компонент;
+- какую задачу он решает;
+- какие ограничения необходимо учитывать;
+- почему архитектура построена именно таким образом.
+
+Стандартные комментарии, объясняющие синтаксис Python, практически не помогают решить эти задачи.
+
+---
+
+# Проблема
+
+Большинство комментариев в программных проектах описывают очевидные действия языка программирования.
+
+Например:
+
+```python
+# увеличиваем счётчик
+counter += 1
+```
+
+или
+
+```python
+# проверяем условие
+if value > limit:
+```
+
+Подобные комментарии быстро устаревают и не помогают понять архитектуру системы.
+
+Гораздо более ценными являются ответы на вопросы:
+
+- зачем существует данный объект;
+- почему принято именно такое решение;
+- какие ограничения существуют;
+- что произойдёт при нарушении данного правила.
+
+---
+
+# Рассмотренные варианты
+
+## Вариант 1
+
+Использовать минимальное количество комментариев.
+
+### Преимущества
+
+- меньше текста;
+- проще поддерживать.
+
+### Недостатки
+
+- ухудшается сопровождаемость;
+- сложнее понимать архитектуру;
+- новые разработчики дольше погружаются в проект.
+
+---
+
+## Вариант 2
+
+Комментировать синтаксис Python.
+
+### Преимущества
+
+- большое количество комментариев.
+
+### Недостатки
+
+- комментарии не несут архитектурной ценности;
+- быстро устаревают;
+- отвлекают от действительно важных пояснений.
+
+---
+
+## Вариант 3
+
+Комментарии объясняют назначение компонента и архитектурный смысл.
+
+### Преимущества
+
+- легче сопровождать проект;
+- проще понимать архитектуру;
+- быстрее находить причины существования компонентов;
+- комментарии остаются актуальными значительно дольше.
+
+### Недостатки
+
+- требуется больше внимания при проектировании.
+
+---
+
+# Принятое решение
+
+Комментарии в Dzentra должны объяснять **назначение**, **роль** и **ограничения** компонентов.
+
+Комментарии не должны пересказывать синтаксис языка Python.
+
+---
+
+# Основные правила
+
+Комментарии должны отвечать хотя бы на один из следующих вопросов:
+
+- зачем существует данный компонент;
+- какую задачу он решает;
+- почему используется именно такое решение;
+- какие ограничения необходимо учитывать;
+- где проходит граница ответственности компонента.
+
+---
+
+# Следует избегать
+
+Не рекомендуется писать комментарии, объясняющие очевидные конструкции языка.
+
+Например:
+
+```python
+# складываем два числа
+total = a + b
+```
+
+или
+
+```python
+# возвращаем результат
+return result
+```
+
+Такие комментарии не добавляют полезной информации.
+
+---
+
+# Комментарии в Market Intelligence
+
+При разработке аналитических движков комментарии должны быть понятны разработчику, который не является профессиональным трейдером.
+
+Предпочтительно использовать простые технические формулировки.
+
+Если существует возможность заменить узкоспециализированный термин более понятным описанием без потери смысла, следует использовать более понятное описание.
+
+---
+
+# Причины принятия решения
+
+Использование человекочитаемых комментариев позволяет:
+
+- уменьшить порог входа в проект;
+- повысить сопровождаемость;
+- сделать архитектуру более понятной;
+- уменьшить зависимость от автора исходного кода;
+- сохранить знания внутри проекта.
+
+---
+
+# Последствия
+
+После принятия настоящего решения:
+
+- новые комментарии ориентируются на смысл, а не на синтаксис;
+- архитектурные ограничения описываются непосредственно в коде;
+- комментарии становятся частью инженерной документации проекта;
+- разработчик может понять назначение большинства компонентов без обращения к внешним источникам.
+
+---
+
+# Связанные документы
+
+- `architecture_principles.md`
+- `development_process.md`
+- `runtime_contract.md`
+
+---
+
+# История изменений
+
+| Версия | Изменение |
+|---------|-----------|
+| 1.0 | Первое принятие архитектурного решения. |

docs/market_intelligence/decisions/decision-006-immutable-engine-contract.md

@@ -0,0 +1,157 @@
+# Decision 006 — Immutable Engine Contract
+
+## Статус
+
+**Accepted**
+
+---
+
+# Дата принятия
+
+Принято во время реализации **Build №006 — `common/models.py`**.
+
+---
+
+# Контекст
+
+Во время проектирования единого контракта аналитических движков возник вопрос:
+
+> **Могут ли модели результата изменяться после завершения расчёта?**
+
+Рассматривались два варианта.
+
+---
+
+# Вариант 1
+
+Изменяемые (`mutable`) модели.
+
+После создания объекта любой компонент платформы может изменить его поля.
+
+Например:
+
+```python
+result.score = ...
+result.reason = ...
+result.direction = ...
+```
+
+### Преимущества
+
+- проще писать код;
+- меньше ограничений.
+
+### Недостатки
+
+- невозможно гарантировать целостность результата;
+- результат может измениться после публикации;
+- журнал может содержать значения, отличающиеся от реально использованных;
+- сложнее искать ошибки;
+- возрастает риск скрытых побочных эффектов.
+
+---
+
+# Вариант 2
+
+Неизменяемые (`immutable`) модели.
+
+После создания объекта изменение его полей невозможно.
+
+При необходимости формируется новый объект результата.
+
+### Преимущества
+
+- результат всегда остаётся неизменным;
+- журнал отражает фактическое состояние расчёта;
+- безопасная передача между компонентами;
+- отсутствуют скрытые изменения;
+- упрощается диагностика;
+- упрощается тестирование;
+- повышается предсказуемость поведения платформы.
+
+### Недостатки
+
+- при изменении необходимо создавать новый экземпляр объекта.
+
+---
+
+# Принятое решение
+
+Для всех моделей, описывающих результат работы аналитических движков, используется **неизменяемый контракт**.
+
+Все основные модели объявляются как:
+
+```python
+@dataclass(frozen=True, slots=True)
+```
+
+---
+
+# Область применения
+
+Правило распространяется на:
+
+- `EngineResult`;
+- `EngineContext`;
+- `EngineMetric`;
+- `EngineDiagnostics`;
+- `EngineEvaluationMeta`;
+- `EngineDependencyResult`;
+
+а также на все будущие модели, описывающие результаты работы Engine.
+
+---
+
+# Исключения
+
+Настоящее правило **не распространяется** на:
+
+- Runtime State;
+- AutoTrade State;
+- Position State;
+- Execution Runtime;
+- внутренние рабочие объекты расчёта.
+
+Эти объекты отражают изменяющееся состояние платформы и по своей природе являются изменяемыми.
+
+---
+
+# Причины принятия решения
+
+Использование неизменяемых моделей обеспечивает:
+
+- целостность результатов анализа;
+- безопасную передачу данных между Engine;
+- корректное журналирование;
+- предсказуемость поведения системы;
+- отсутствие скрытых побочных эффектов;
+- упрощение сопровождения проекта в долгосрочной перспективе.
+
+---
+
+# Архитектурные последствия
+
+После принятия настоящего решения:
+
+- результаты Engine не изменяются после создания;
+- каждый новый расчёт формирует новый объект результата;
+- публикация событий всегда выполняется на основе завершённого результата;
+- журнал содержит фактически опубликованные данные;
+- Coordinator работает только с завершёнными результатами анализа.
+
+---
+
+# Связанные документы
+
+- `runtime_contract.md`
+- `architecture_principles.md`
+- `development_process.md`
+- `builds/build-006-common-models.md`
+
+---
+
+# История
+
+| Версия | Изменение |
+|---------|-----------|
+| 1.0 | Первое принятие архитектурного решения. |

docs/market_intelligence/decisions/decision-007-documentation-is-code.md

@@ -0,0 +1,179 @@
+# Decision 007 — Documentation Is Code
+
+## Статус
+
+**Accepted**
+
+---
+
+# Дата принятия
+
+Принято во время разработки Stage-08.2 **Engine Runtime Contract**.
+
+---
+
+# Контекст
+
+Во время разработки первых компонентов Market Intelligence стало очевидно, что исходный код и документация развиваются одновременно.
+
+Если документация обновляется позже кода, очень быстро возникает расхождение между:
+
+- архитектурой;
+- реализацией;
+- инженерными решениями;
+- фактическим состоянием проекта.
+
+В результате документация перестаёт отражать реальное устройство системы.
+
+---
+
+# Проблема
+
+Во многих проектах документация рассматривается как дополнительный материал.
+
+Обычно процесс выглядит следующим образом:
+
+```text
+Написание кода
+        ↓
+Код работает
+        ↓
+Документацию обновим позже
+```
+
+На практике "позже" часто не наступает.
+
+Через некоторое время:
+
+- документация устаревает;
+- архитектурные решения теряются;
+- новые разработчики вынуждены изучать проект только по исходному коду.
+
+---
+
+# Рассмотренные варианты
+
+## Вариант 1
+
+Документация обновляется по мере возможности.
+
+### Преимущества
+
+- меньше работы во время реализации.
+
+### Недостатки
+
+- документация быстро устаревает;
+- теряются архитектурные решения;
+- сложно понять историю развития проекта.
+
+---
+
+## Вариант 2
+
+Документация обновляется одновременно с кодом.
+
+Build считается завершённым только после обновления всей связанной документации.
+
+### Преимущества
+
+- документация всегда соответствует проекту;
+- архитектурные решения сохраняются;
+- упрощается сопровождение;
+- сохраняется история развития платформы;
+- новые разработчики быстрее понимают проект.
+
+### Недостатки
+
+- требуется дополнительное время на оформление документации.
+
+---
+
+# Принятое решение
+
+Документация является частью исходного кода проекта.
+
+Каждый Build считается завершённым только после обновления всей связанной документации.
+
+Документация имеет такую же обязательность, как Compile Check или Architecture Review.
+
+---
+
+# Обязательная документация Build
+
+После завершения каждого Build обязательно обновляются все связанные документы.
+
+Например:
+
+- Build Document;
+- Build History;
+- Architecture Decisions (при необходимости);
+- Runtime Contract (при необходимости);
+- Development Process (при необходимости);
+- README соответствующего раздела (при необходимости).
+
+---
+
+# Правило завершения Build
+
+Build считается завершённым только после прохождения полного цикла:
+
+```text
+Architecture Design
+        ↓
+Implementation
+        ↓
+Compile Check
+        ↓
+Architecture Review
+        ↓
+Domain Review
+        ↓
+Documentation Update
+        ↓
+User Confirmation
+        ↓
+Build Closed
+```
+
+Если документация не обновлена, Build остаётся незавершённым.
+
+---
+
+# Причины принятия решения
+
+Использование данного подхода позволяет:
+
+- сохранять актуальность документации;
+- фиксировать архитектурные решения;
+- поддерживать единый источник знаний;
+- облегчать сопровождение проекта;
+- исключать расхождение между кодом и документацией.
+
+---
+
+# Последствия
+
+После принятия настоящего решения:
+
+- документация развивается одновременно с кодом;
+- архитектурные изменения всегда фиксируются;
+- история развития проекта полностью сохраняется;
+- Build не может считаться завершённым без обновления документации.
+
+---
+
+# Связанные документы
+
+- `development_process.md`
+- `build_history.md`
+- `architecture_principles.md`
+- `runtime_contract.md`
+
+---
+
+# История изменений
+
+| Версия | Изменение |
+|---------|-----------|
+| 1.0 | Первое принятие архитектурного решения. |

docs/market_intelligence/decisions/decision-008-engine-metadata-separation.md

@@ -0,0 +1,257 @@
+# 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.