# Исходный подробный контракт этапа 7 Снимок локального плана `_bmad-output/planning-artifacts/epics.md`. Исходная ревизия: `78dc060b8a5086b1cc7a1bec77385a0f2471fbf3`. Дата переноса: 2026-10-04. Технический текст ниже сохранён дословно, чтобы перенос не изменял обязательные критерии. Основные описания этапов и задач в Gitea написаны на русском языке. ## Epic 7: Автономное production-развёртывание и восстановление Оператор устанавливает Crank одной командой, в том числе offline, безопасно обновляет, создаёт backup и доказывает восстановление реальным MCP-вызовом. ### Story 7.1: Завершить production configuration contract **Depends on:** Story 6.6 **Work type:** implementation **Deliverable:** Завершить production configuration contract. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want настраивать все процессы через один проверяемый contract, So that deployment не зависит от скрытых или противоречивых параметров. **Requirements:** FR-45 **Acceptance Criteria:** **Given** `crank-config` foundation из Story 1.3 и все реализованные processes **When** инвентаризируется production configuration field **Then** заданы type, unit-bearing name, default, bounds, sensitivity, required profile, reload policy и cross-field validation **And** application crates получают только validated config, libraries не читают environment напрямую. **Given** canonical schema **When** генерируются environment examples, Compose settings, docs и Admin read-only configuration view **Then** они используют один versioned source и одинаковые defaults/bounds **And** sensitive values показываются только как configured/unconfigured и source class. **Given** startup config **When** поле unknown, malformed, out-of-range или небезопасно сочетается с другим **Then** процесс fail fast/fail safe со stable code, field path и bounded RU/EN message **And** secret value не отражается в log/diagnostics. **Given** legacy environment aliases **When** они ещё находятся в compatibility window **Then** mapping явный, precedence deterministic и deprecation observable **And** конфликт legacy/canonical values блокирует startup вместо silent choice. **Given** config diagnostics/export **When** оператор собирает support bundle **Then** выдаётся redacted effective config fingerprint и provenance без raw secrets **And** fingerprint связывается с trace/load/release evidence. **Given** CI config audit **When** код, docs, examples и Compose проверяются **Then** undocumented, unused, duplicate и divergent parameters вызывают failure **And** default/min/max/invalid golden tests проходят для каждого field. ### Story 7.2: Квалифицировать schema evolution и N/N-1 compatibility **Depends on:** Story 7.1 **Work type:** implementation **Deliverable:** Квалифицировать schema evolution и N/N-1 compatibility. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want предсказуемые и совместимые database migrations, So that startup и upgrade не повреждают durable state. **Requirements:** FR-43 **Acceptance Criteria:** **Given** canonical authority из Story 1.4 и существующие migration ledgers **When** выполняется production reconciliation **Then** `crank-registry` остаётся единственной authority, legacy sequences сопоставлены без повторного применения **And** reconciliation report перечисляет checksum/version conflicts до mutation. **Given** canonical migration sequence **When** добавляется migration **Then** она append-only, immutable, checksummed и имеет explicit compatibility window **And** изменение уже опубликованного checksum блокирует CI/startup. **Given** service startup **When** database version совместима N/N-1 **Then** сервис только проверяет compatibility, а migration выполняет отдельная controlled command/job **And** одновременно стартующие instances не применяют DDL конкурентно. **Given** schema evolution **When** change затрагивает wire/durable records **Then** используется expand → migrate/backfill → contract с resumable bounded batches **And** old и new application versions безопасно работают в заявленном window. **Given** incompatible, partial либо failed migration **When** preflight/startup обнаруживает состояние **Then** readiness fail closed с actionable diagnostics и recovery command **And** автоматический destructive rollback отсутствует. **Given** PostgreSQL 16 migration suite **When** проверяются empty, current, N-1, legacy, partial и large-dataset states **Then** repeated apply idempotent, checksums/audit корректны, данные сохранены **And** Gitea-compatible CI gate проходит. ### Story 7.3: Поставлять minimal и production deployment profiles **Depends on:** Story 7.2 **Work type:** implementation **Deliverable:** Поставлять minimal и production deployment profiles. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an self-hosted пользователь, I want запустить Crank одной командой в подходящем профиле, So that установка воспроизводима без proprietary dependencies. **Requirements:** FR-41 **Acceptance Criteria:** **Given** canonical `deploy/community` **When** пользователь запускает documented minimal command **Then** поднимаются required correctness components с PostgreSQL и shared artifacts **And** выполняется automated health/readiness и реальный MCP smoke call. **Given** production command **When** запускается profile **Then** дополнительно доступны task-worker и versioned optional Prometheus/Grafana/GlitchTip services **And** каждый optional backend заменяем совместимым endpoint без изменения core behavior. **Given** Reference Deployment sizing **When** применяются documented CPU/RAM/disk/IO limits **Then** отдельно учтены runtime, PostgreSQL, artifacts, telemetry spool и observability **And** при qualified workload остаётся ≥30% measured headroom. **Given** Valkey disabled or unavailable **When** профиль работает в PG-only mode **Then** correctness сохраняется, acceleration rebuildable, readiness честно отражает optional degradation **And** mandatory safety dependency никогда не отключается silently. **Given** first startup **When** secrets/config отсутствуют или defaults небезопасны для выбранного exposure **Then** production profile не становится ready и показывает exact setup steps **And** committed examples не содержат reusable passwords/keys. **Given** fresh-host CI smoke **When** minimal и production profiles проходят install/start/restart/stop **Then** команды, health checks, MCP probe, persistence и resource budgets подтверждены **And** canonical/legacy deployment divergence вызывает gate failure. ### Story 7.4: Защитить non-loopback production exposure **Depends on:** Story 7.3 **Work type:** implementation **Deliverable:** Защитить non-loopback production exposure. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want безопасно публиковать Admin и MCP endpoints, So that deployment не становится уязвимым из-за опасного сетевого default. **Requirements:** FR-41 **Acceptance Criteria:** **Given** web listener на non-loopback interface **When** production config валидируется **Then** обязательны TLS termination policy, explicit public origins/hosts и documented trusted proxy chain **And** wildcard host/origin либо ambiguous forwarded-header trust блокируют readiness. **Given** request через reverse proxy **When** определяется client address, scheme и host **Then** forwarded headers принимаются только от allowlisted proxy hops с bounded chain **And** spoofed headers не обходят secure cookies, redirects, rate limit или audit. **Given** Admin session **When** UI работает через HTTPS **Then** Secure/HttpOnly/SameSite cookie, CSRF и deny-by-default CORS применяются совместно **And** downgrade/mixed-origin attempts отклоняются stable error. **Given** MCP и metrics machine endpoints **When** они exposed externally **Then** каждый имеет отдельный explicit auth/TLS policy и bounded admission **And** Admin session не расширяет machine scope, recovery endpoint остаётся local-only. **Given** production diagnostics **When** оператор проверяет exposure **Then** UI/CLI показывает redacted effective listeners, proxy/TLS/auth posture и warnings **And** raw certificate keys/tokens не выводятся. **Given** deployment security suite **When** проверяются direct, trusted/untrusted proxy, host-header, CORS, CSRF, insecure cookie и TLS cases **Then** safe topology работает, unsafe topology fail closed **And** regression evidence связано с profile/config digest. ### Story 7.5: Собирать подписанный offline production bundle **Depends on:** Story 7.4 **Work type:** implementation **Deliverable:** Собирать подписанный offline production bundle. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор закрытого контура, I want установить и обновить Crank без доступа к интернету, So that данные и supply chain остаются под моим контролем. **Requirements:** FR-42 **Acceptance Criteria:** **Given** release build **When** создаётся offline bundle **Then** он содержит digest-pinned runtime/worker/runner/PG/optional observability images, Compose/config, migrations, docs, SBOM и licenses **And** manifest перечисляет размер и SHA-256 каждого файла. **Given** bundle завершён **When** release signer его публикует **Then** manifest и archive signature проверяются documented offline trust root **And** missing, extra, modified или unpinned artifact вызывает fail-closed verification. **Given** air-gapped fresh host **When** оператор выполняет documented import/install command **Then** ни один component не обращается к network registry, package service, CDN или telemetry endpoint **And** default-deny egress test подтверждает полный startup и MCP call. **Given** third-party notices **When** SBOM/license policy проверяется **Then** каждый shipped package/image сопоставлен component/version/license/source metadata **And** forbidden/unknown license либо Critical/High vulnerability блокирует bundle. **Given** reproducibility check **When** один source/tag/toolchain собирается повторно **Then** artifact provenance и material digests сравнимы, отклонения объяснены **And** bundle digest связывается с Release Candidate evidence. ### Story 7.6: Усилить production containers и process boundaries **Depends on:** Story 7.5 **Work type:** implementation **Deliverable:** Усилить production containers и process boundaries. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор безопасности, I want контейнеры с минимальными привилегиями и ресурсными границами, So that компрометация или перегрузка одного процесса не захватывает установку. **Requirements:** FR-44 **Acceptance Criteria:** **Given** каждый production image **When** container запускается **Then** он работает non-root с dropped capabilities, no-new-privileges и read-only root filesystem где возможно **And** writable mounts перечислены, минимальны и имеют explicit ownership/size policy. **Given** process role **When** Compose применяет network/storage/secrets **Then** runtime, task-worker, load-runner, DB и observability получают только необходимые access paths **And** load-runner не имеет direct DB/artifact-admin access. **Given** health lifecycle **When** process стартует, деградирует или завершается **Then** liveness и readiness различимы, admission прекращается до shutdown, accepted work flush/checkpoint укладывается в 30 секунд **And** orchestrator restart не создаёт duplicate terminal outcomes. **Given** resource/log policy **When** container работает длительно **Then** заданы CPU/memory/PID/file limits, log rotation и bounded diagnostics/core-dump policy **And** OOM/disk-full одного optional component не забирает reserved product capacity. **Given** secret injection **When** image/build/runtime diagnostics проверяются **Then** secrets поступают через mounted provider/reference, отсутствуют в layers, env examples, dumps и support bundle **And** master-key material никогда не входит в image или manifest. **Given** container security gate **When** выполняются image config, filesystem, privilege, network, secret и vulnerability tests **Then** известных Critical/High findings нет **And** results pinned к exact image digests. **Given** hardened image digest отличается от image в offline bundle Story 7.5 **When** container hardening принимается **Then** bundle manifest/signature пересобираются и air-gapped startup/MCP smoke повторяются **And** Story не считается завершённой с устаревшим bundle digest. ### Story 7.7: Создавать согласованный backup с BackupManifest **Depends on:** Story 7.6 **Work type:** implementation **Deliverable:** Создавать согласованный backup с BackupManifest. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want создавать проверяемую точку восстановления всей установки, So that durable configuration и artifacts восстанавливаются согласованно. **Requirements:** FR-43 **Acceptance Criteria:** **Given** configured backup destination **When** запускается backup **Then** preflight проверяет PostgreSQL WAL/PITR, artifact store, effective config snapshot и protected opaque key reference **And** raw master key/credentials никогда не входят в backup. **Given** online product **When** фиксируется backup cut **Then** создаётся consistent database recovery target и согласованный content-addressed artifact inventory **And** новые writes могут продолжаться в пределах documented performance envelope. **Given** завершённый cut **When** формируется BackupManifest **Then** он immutable, checksummed и содержит schema/app versions, WAL range, artifact/config digests, key fingerprint/epoch reference и timestamps **And** missing/incomplete component помечает backup unusable. **Given** backup retention **When** очищаются старые data **Then** policies раздельны для WAL, artifacts, telemetry, history и release evidence **And** Published Versions, active Task/Load Run dependencies и audit/evidence не становятся dangling. **Given** encrypted backup **When** он передаётся или хранится **Then** confidentiality/integrity keys заданы refs и rotation policy документирована **And** verification возможна без раскрытия application secrets. **Given** backup verification suite **When** моделируются interrupted upload, missing WAL, altered artifact, wrong key epoch и repeated run **Then** only complete manifest становится restorable, failures observable/audited **And** backup cadence способен обеспечить RPO ≤5 минут. ### Story 7.8: Доказывать restore и безопасную key recovery **Depends on:** Story 7.7 **Work type:** implementation **Deliverable:** Доказывать restore и безопасную key recovery. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор аварийного восстановления, I want восстановить установку и проверить её реальным вызовом, So that backup является доказанным, а не номинальным. **Requirements:** FR-43 **Acceptance Criteria:** **Given** fresh compatible host и BackupManifest **When** запускается restore preflight **Then** проверяются signature/checksums, app/schema compatibility, required disk, artifact/WAL completeness и supplied master-key fingerprint/epoch **And** mismatch блокирует mutation с actionable diagnostics. **Given** valid backup and protected key material supplied out of band **When** выполняется restore **Then** PostgreSQL восстанавливается к declared recovery target, artifacts/config reconciled по manifest **And** missing bytes или ciphertext that cannot decrypt не скрываются. **Given** restore completed **When** процессы проходят readiness **Then** проверяются catalog revisions, Published Versions, keys, approvals, Tasks и artifact references **And** Valkey rebuilds from authority вместо восстановления stale correctness state. **Given** restored installation **When** выполняется probe **Then** новый MCP client authenticates, discovers pinned Tool и делает реальный successful call **And** Request ID/Trace ID находятся в restored history/observability. **Given** valid recovered old key epoch **When** оператор инициирует post-restore rotation **Then** re-encryption transactional/resumable, mixed epoch observable, old key отзывается только после verification **And** crash не теряет decryptability принятого state. **Given** три независимых Reference Deployment restore runs **When** измеряются data cut и recovery completion **Then** каждый доказывает RPO ≤5 минут и RTO ≤30 минут реальным MCP probe **And** immutable reports связаны с backup, build и config digests. ### Story 7.9: Выполнять безопасный single-instance upgrade и rollback **Depends on:** Story 7.8 **Work type:** implementation **Deliverable:** Выполнять безопасный single-instance upgrade и rollback. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want обновлять Community installation с preflight и drain, So that accepted work и Published contracts сохраняются при смене версии. **Requirements:** FR-43 **Acceptance Criteria:** **Given** current N-1 installation и target N artifact **When** выполняется upgrade preflight **Then** проверяются signatures/digests, config/schema window, capacity, backup freshness, disk и known blockers **And** несовместимый state не мутируется. **Given** preflight pass **When** upgrade начинается **Then** admission прекращается, active synchronous work получает bounded drain, Tasks/Load Runs checkpoint or safely interrupt по contract **And** durable accepted state не теряется. **Given** validated backup **When** controlled migration применяется **Then** используется canonical migration command и expand/migrate compatibility **And** application N не стартует ready до schema/config/master-key checks. **Given** new version ready **When** post-upgrade validation выполняется **Then** Admin login, MCP negotiation/discovery/call, Task resume, metrics и trace probe проходят **And** Agent catalog/Published schemas сохраняют immutable revisions. **Given** failure до contract migration boundary **When** оператор выбирает rollback **Then** documented N-1 rollback восстанавливает compatible app/config без data loss **And** после irreversible boundary требуется manifest restore, что явно показано preflight до start. **Given** restart without version change **When** service останавливается и запускается **Then** admission/drain ≤30 секунд, stuck leases recover ≤60 секунд, telemetry flushes bounded **And** no duplicate terminal outcomes или lost accepted Tasks. **Given** fresh/N-1 online и offline upgrade matrix **When** suites выполняются на fixed artifacts **Then** success/rollback/failure evidence machine-readable и reproducible **And** завершение Epic 7 подтверждает FR-41…FR-45 и NFR-R2/R3/R4. **Given** air-gapped N-1 installation **When** применяется новый bundle **Then** preflight, backup, migration и upgrade используют только bundled artifacts **And** post-upgrade real MCP probe проходит без внешней сети.