# Build 060.30 — Market Data Acquisition Final Documentation **Engineering Migration Report** --- ## Контроль документа | Свойство | Значение | |---|---| | Build | 060.30 | | Статус | Completed | | Подсистема | Market Data / Trades Feed (Time & Sales) | | Компонент | Final Documentation and Production Safety | | Дата завершения | 2026-08-03 | | Версия | 1.0 | --- ## Связанные документы - [Build 060.30 Architecture](build_060_30_architecture.md) — границы, ADR и подробное evidence подэтапов 060.30.0–060.30.8; - [Текущая архитектура Trades Feed](../architecture/trades_feed.md) — фактический dependency graph и lifecycle; - [Эксплуатация Trade Stream Runtime](../operations/trades_feed_runtime.md) — settings, startup, recovery, PostgreSQL и verification procedures; - [Целевая архитектура Dzentra](../architecture/dzentra_target_architecture.md) — место Market Data в целевой системе; - [Master Roadmap](../roadmap/master-roadmap.md) — фактические статусы и следующий Build; - [Build 060.29 Engineering Migration Report](build_060_29.md) — Historical Access and Replay. --- ## 1. Назначение Build Build 060.30 завершил документационный цикл Trades Feed Builds 060.20–060.30. Новое поведение Trade Runtime, Market Data SQL, Storage, Historical Access или Replay в Build не добавлялось. Результат Build — согласованный набор источников истины: ```text production code + SQL migrations + tests + settings ↓ docs/architecture/trades_feed.md ↓ docs/operations/trades_feed_runtime.md ↓ overview + target architecture + master roadmap ↓ historические architecture и Build reports ``` Текущая архитектура и operations guide описывают фактическую систему. Исторические Build-документы сохраняют принятые на соответствующем этапе решения и test evidence без широкого переписывания задним числом. --- ## 2. Завершённые подэтапы | Подэтап | Название | Статус | |---|---|---| | 060.30.0 | Documentation Baseline | Accepted | | 060.30.1 | As-Built Trades Feed Architecture | Accepted | | 060.30.2 | Production Operations Guide | Accepted | | 060.30.3 | Project Entry Documentation | Accepted | | 060.30.4 | Target Architecture Alignment | Accepted | | 060.30.5 | Navigation and Historical Normalization | Accepted | | 060.30.6 | Documentation Integrity Gate | Accepted | | 060.30.7 | Final Documentation Verification | Accepted | | 060.30.8 | Closure | Accepted | Перед 060.30.3 отдельно реализован и принят corrective gate Docker Production Safety Hardening по ADR-060.30-008. Каждый основной подэтап и corrective gate проходили отдельный read-only review. Воспроизведённые findings исправлялись до принятия. --- ## 3. Зафиксированная архитектура Trades Feed ### 3.1. Production vertical slice Production Runtime завершён только для Trades и поддерживает два режима включённого Trade Stream. При `TRADE_STREAM_ENABLED=true` и `MARKET_DATA_STORAGE_ENABLED=true` действует полная durable-цепочка: ```text Dzengi WebSocket / REST Recovery ↓ Trade validation + Consistency ↓ atomic PostgreSQL Trade + checkpoint ↓ in-memory state advance ↓ Runtime Event publication ``` Live и Recovery в обоих режимах используют один Consistency owner. В durable-режиме Canonical Trade и persistent checkpoint фиксируются одной транзакцией; in-memory state продвигается только после успешного commit. При включённом Storage Startup выполняет Hydration до первого сетевого I/O, получает subscription ACK, держит Live gate закрытым во время Startup REST Recovery и разбирает buffered Live FIFO только после восстановления. Без Storage первоначальный startup подписывается без persistent Hydration, ожидания startup ACK и Startup REST Recovery; Live, in-memory Consistency и reconnect Recovery остаются доступными без restart persistence. ### 3.2. Storage, Checkpoint, Access и Replay Границы подсистем разделены: - Storage владеет долговременной записью Canonical Market Data; - persistent checkpoint хранит подтверждённую позицию Trade Stream; - Historical Access только читает сохранённые данные; - Replay строит bounded immutable plan и запускается явным caller; - Retention и partition maintenance не запускаются автоматически. Historical Access и Replay не являются частью automatic Bootstrap, не записывают воспроизводимые события обратно и не продвигают operational checkpoint. ### 3.3. Quotes и Candles Quotes и Candle revisions имеют Canonical models, PostgreSQL repositories, Historical Access и Replay contracts. Они не подключены как Production Runtime consumers и не являются завершёнными production feeds. --- ## 4. Production Operations Guide Создан единый runbook, который согласован с `config.py`, `.env.example`, Compose, Dockerfiles и test harness: - host и Compose startup; - feature flags и явные URL/symbols; - PostgreSQL pool, migrations и lifecycle; - startup recovery, reconnect и graceful shutdown; - file-backed secrets и запрет repository `.env` для production; - backup, restore и blocking migration 9; - Retention, Historical Access и Replay procedures; - unit, integration, stress и opt-in live verification; - диагностика типовых startup и database failures. Migration 9 остаётся блокирующей. Перед применением к большой базе обязательны backup, benchmark на сопоставимом объёме и maintenance window. Online staged migration не реализована. --- ## 5. Docker Production Safety Hardening ADR-060.30-008 устранил обнаруженный pre-production blocker: прежний Docker context мог включить `app/.env` в image layer. Принятые меры: - корневой `.dockerignore` ограничивает build context; - Dockerfile копирует только production requirements и `app/src`; - production dependencies закреплены hash-lock; - bot работает как non-root с read-only root filesystem; - capabilities удалены, включён `no-new-privileges`; - secrets передаются через явные file-backed contracts; - Compose требует явный project namespace и закрывает PostgreSQL port; - PostgreSQL bootstrap-admin отделён от application-role; - healthcheck отклоняет privileged или неправильно настроенную role; - shutdown использует явные budgets и ожидает blocking lifecycle work. Images, собранные до появления проверенного `.dockerignore`, считаются потенциально скомпрометированными и не должны публиковаться. Удаление старых images и rotation реальных credentials требуют отдельного операционного разрешения. --- ## 6. PostgreSQL version policy Единственный поддерживаемый production deployment baseline: ```text PostgreSQL 16.14 hardened image, закреплённый tag + digest ``` Изолированная verification matrix подтвердила application compatibility с PostgreSQL 17.10 для migrations 1–9, repositories, checkpoint, Historical Access, Replay, Trade Runtime integration и restart. Этот результат не принимает hardened PostgreSQL 17 image, Compose cutover или upgrade существующего volume. Production-переход на PostgreSQL 17 требует отдельного infrastructure gate. Major version нельзя переключать на существующем data volume без проверенной процедуры `pg_dump/restore` либо `pg_upgrade`. --- ## 7. Documentation Integrity Gate Добавлен локальный offline gate: ```text scripts/check_documentation_integrity.py app/tests/static/test_documentation_integrity_gate.py ``` Gate проверяет обязательные документы, относительные Markdown-ссылки, выход path за repository root, URI safety и переносимость path rules. Он не обращается к сети и входит в default offline regression и Pyright scope. Историческая навигация нормализована без изменения старых test counts и принятых решений. Stage roadmaps явно обозначены как архивные и больше не определяют следующий Build. --- ## 8. Финальная verification matrix 060.30.7 и Closure подтвердили: ```text Documentation integrity gate: 366 documents, 259 links, 0 issues Полный static-набор: 332 passed Pyright: 0 errors, 0 warnings Dependency integrity: pip check clean Compileall во временном cache: 618 files, clean Полная offline-регрессия: 3054 passed, 95 deselected Target config/Docker tests: 73 passed Compose base + exchange-auth config: clean Shell syntax затронутых scripts: clean PostgreSQL application compatibility: 17.10 / 170010 PostgreSQL official image digest: sha256:8189a1f6e40904781fc9e2612687877791d21679866db58b1de996b31fc312e4 Application-role dangerous flags: 5/5 disabled Полный PostgreSQL 17 integration: 90 passed Критические PG17 race/restart repeats: 10 x 6 = 60 passed Durable restart probe: preserved Test-only PostgreSQL 17 resources: removed PostgreSQL 16.14 deployment baseline: unchanged Git diff --check: clean Text hygiene tracked/untracked: 61 Build files, clean Staging candidates: 61 paths, .gitignore excluded Git index: empty Три независимых финальных review: clean ``` Test-only PG17 container, network, volume, derived image и временные password-файлы удалены. Существующие Docker resources не изменялись. Stress/soak и Dzengi live в 060.30.7 повторно не запускались: Runtime behavior Build 060.30 не менял, а соответствующее acceptance evidence зафиксировано в Build 060.26. --- ## 9. Границы завершённого Build Build 060.30 не реализует: - новую Market Data feed; - Production Runtime consumers для Quotes или Candles; - initial historical backfill и completeness metadata; - automatic Retention Scheduler; - Replay Bootstrap или automatic startup; - Backtesting, Analytics API или exchange simulator; - online replacement migration 9; - PostgreSQL 17 production deployment; - Production deployment, backup automation или monitoring program. Доступная история начинается с наиболее ранней Canonical записи, которая фактически находится в PostgreSQL. Обычно это момент успешного включения Storage, но история может включать ранее импортированные durable rows. Нижняя граница сдвигается только после явно применённой Retention Policy. Документация не обещает полную биржевую историю за более ранний период. Пользовательское изменение `.gitignore` не относится к Build 060.30 и не должно входить в staging. --- ## 10. Git и выпуск Closure подготавливает точный список файлов Build без `.gitignore`, но не выполняет `git add`, commit или push. Локальный `main` до фиксации 060.30 опережает remote на 58 commits. После отдельного commit Build 060.30 требуется отдельный read-only аудит этих 58 прежних commits и нового commit, затем согласованное исправление истории Build 045/046 и повторная проверка итоговой цепочки. Push разрешается только отдельным поручением после этого аудита. --- ## 11. Итог Build 060.30 завершён и принят. Trades Feed получил согласованную текущую архитектуру, единый production runbook, безопасный Docker baseline, offline documentation gate и финальное verification evidence. Документационный цикл Builds 060.20–060.30 закрыт без скрытого изменения Market Data Runtime или SQL. Следующий Build — 061.00 Validation and Canonicalization Boundary Refactoring. Он начинается с отдельного read-only анализа фактического ownership validation, parsing, normalization, mapping, consistency и data-quality границ.