# Исходный подробный контракт этапа 5 Снимок локального плана `_bmad-output/planning-artifacts/epics.md`. Исходная ревизия: `78dc060b8a5086b1cc7a1bec77385a0f2471fbf3`. Дата переноса: 2026-10-04. Технический текст ниже сохранён дословно, чтобы перенос не изменял обязательные критерии. Основные описания этапов и задач в Gitea написаны на русском языке. ## Epic 5: Полная эксплуатационная видимость Оператор прослеживает любой запрос по `trace_id` в UI и GlitchTip, видит технические и бизнесовые метрики, Grafana dashboards, SLO и alerts. ### Story 5.1: Провести Request ID и Trace ID через весь runtime **Depends on:** Story 4.10 **Work type:** implementation **Deliverable:** Провести Request ID и Trace ID через весь runtime. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор поддержки, I want иметь устойчивую correlation identity для каждого запроса и выполнения, So that я могу восстановить его путь через все компоненты. **Requirements:** FR-27 **Acceptance Criteria:** **Given** UI, Admin API или MCP ingress **When** поступает запрос без доверенных identifiers либо с malformed/oversized values **Then** создаются отдельные typed UUIDv7 Request ID и canonical W3C Trace ID **And** входные значения валидируются по trust policy, а response и boundary error содержат локальные safe IDs. **Given** валидный ingress context **When** запрос проходит service, PostgreSQL, cache и outbound REST **Then** TraceContext распространяется по стандартным headers/spans, а Request ID остаётся product correlation key **And** untrusted upstream не может подменить системную identity. **Given** synchronous Execution **When** создаётся execution record и outbound attempt **Then** оба ID сохраняются независимо от sampling, а attempt продолжает canonical parent trace **And** history связывает ingress, execution и upstream без high-cardinality metric labels. **Given** structured logs и audit events **When** они создаются на любом boundary **Then** они содержат разрешённые correlation fields и stable stage/error code **And** raw credentials, sensitive payloads и arbitrary headers отсутствуют. **Given** trace propagation contract suite **When** выполняются success, validation, auth, retry и upstream failure paths существующего runtime **Then** 100% проверенных requests и Execution records имеют оба ID **And** propagation API, malformed context и sampling-off cases проходят `just verify`; Task/runner cross-process completion закрепляется в их stories. ### Story 5.2: Искать запросы и открывать trace из Admin UI **Depends on:** Story 5.1 **Work type:** implementation **Deliverable:** Искать запросы и открывать trace из Admin UI. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор поддержки, I want видеть, копировать и искать Request ID и Trace ID, So that диагностика начинается с любого сообщения об ошибке или history record. **Requirements:** FR-28 **Acceptance Criteria:** **Given** boundary error, Invocation History, Task, approval или Load Run entry **When** UI показывает outcome **Then** Request ID и Trace ID визуально различимы, копируются отдельно и не заменяются внутренним database ID **And** все пользовательские тексты и состояния доступны на RU/EN. **Given** точный Request ID либо Trace ID **When** оператор выполняет global correlation search **Then** API возвращает scoped bounded timeline связанных requests, executions, tasks и attempts **And** чужой workspace/Agent metadata не раскрывается, pagination opaque. **Given** configured trace backend URL template **When** оператор нажимает «Открыть trace» **Then** UI строит allowlisted HTTPS deep link только из validated Trace ID и configured tenant/project values **And** произвольный URL, script scheme или credential interpolation невозможны. **Given** trace backend недоступен либо telemetry ещё не доставлена **When** deep link не даёт результата **Then** локальные IDs, timeline и диагностическое сообщение остаются доступны **And** product response/readiness не меняются. **Given** concurrent searches и смена workspace/filter **When** ответы приходят не по порядку **Then** identity/revision guard отбрасывает stale response **And** UI имеет loading, empty, validation, partial и error states. **Given** real-stack E2E **When** тестовый MCP call проходит до stub upstream **Then** один Trace ID находится в UI/history и открывает соответствующий backend trace **And** outage, authorization и safe DOM negative cases покрыты Playwright. ### Story 5.3: Безопасно собирать browser observability **Depends on:** Story 5.2 **Work type:** implementation **Deliverable:** Безопасно собирать browser observability. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор поддержки, I want получать связанные browser errors и navigation/API spans, So that проблемы интерфейса диагностируются вместе с server-side trace. **Requirements:** FR-30 **Acceptance Criteria:** **Given** browser observability enabled **When** происходят navigation, API call, handled/unhandled error **Then** frontend создаёт bounded scrubbed event, продолжает server Trace ID из разрешённого response header и показывает support IDs пользователю **And** direct browser DSN или отправка во внешний backend отсутствуют. **Given** event содержит URL, headers, cookies, form fields, stack либо response preview **When** он проходит shared browser redaction contract **Then** secrets, query values, tokens, credentials и sensitive content удалены или детерминированно masked **And** message, frames и breadcrumbs ограничены по размеру и cardinality. **Given** scrubbed event **When** browser отправляет его same-origin Admin API relay **Then** действуют session auth, CSRF, rate/body limits и workspace scope **And** server повторно валидирует schema и redacts до durable export. **Given** observability disabled оператором либо invalid config **When** загружается Admin UI **Then** browser hooks и network relay полностью выключены **And** основной UI работает без ошибки и без phone-home. **Given** redaction/E2E suite **When** инъецируются secrets в headers, cookies, query, JSON, YAML, DOM, stack и errors **Then** ни один canary не попадает в relay, spool или exported event **And** correlation, disable switch и RU/EN support message проходят Playwright. ### Story 5.4: Надёжно экспортировать traces и errors в GlitchTip **Depends on:** Story 5.3 **Work type:** implementation **Deliverable:** Надёжно экспортировать traces и errors в GlitchTip. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want направлять redacted telemetry в GlitchTip-совместимый endpoint, So that production errors и performance traces доступны в привычном backend. **Requirements:** FR-29 **Acceptance Criteria:** **Given** production profile с observability enabled **When** конфигурация проходит typed validation **Then** endpoint, project/auth reference, timeouts, retention expectations и 100% default trace sampling заданы явно **And** invalid or secret-bearing inline config блокирует readiness безопасной диагностикой. **Given** server/browser error либо completed trace **When** telemetry формируется **Then** только `crank-observability` применяет общий redaction и сериализует bounded vendor-compatible envelope **And** Request ID/Trace ID, release, component и stable error stage сохранены без raw payloads. **Given** per-destination exporter adapter **When** backend доступен **Then** он отправляет envelopes bounded batches с timeout/backoff и классифицирует acknowledgement, retryable и permanent rejection **And** delivery queue port сохраняет envelope identity для безопасного duplicate delivery и последующего replay. **Given** GlitchTip endpoint медленный, ошибочный или недоступный **When** выполняется product request **Then** export изолирован от request path, не меняет response и readiness продукта **And** состояние exporter наблюдаемо локально. **Given** representative errors и traces **When** проходит integration test с GlitchTip-compatible receiver **Then** они находятся по Trace ID, сохраняют правильную parent/child topology и release metadata **And** redaction, protocol response classification, duplicate ack и invalid-config tests проходят. ### Story 5.5: Надёжно буферизовать telemetry на диске **Depends on:** Story 5.4 **Work type:** implementation **Deliverable:** Надёжно буферизовать telemetry на диске. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want сохранять telemetry при сбое backend и restart, So that временная недоступность GlitchTip не приводит к потере наблюдаемости. **Requirements:** FR-31 **Acceptance Criteria:** **Given** validated telemetry budget **When** процесс стартует **Then** для каждой destination создан bounded encrypted spool с отдельным filesystem quota и зарезервированным запасом для PostgreSQL/artifacts **And** процессы не разделяют mutable spool state, ownership/permissions проверяются до readiness. **Given** redacted envelope **When** он принимается spool **Then** bounded content и metadata записываются atomic append/fsync contract до acknowledgement producer **And** partial/corrupt tail обнаруживается и изолируется без повреждения ранее подтверждённых records. **Given** exporter acknowledgement **When** envelope подтверждён backend **Then** запись удаляется/компактируется только после durable checkpoint **And** retry либо process restart не теряет unacknowledged data, duplicate delivery остаётся безопасной. **Given** backend медленный или недоступный **When** spool накапливает backlog **Then** export не блокирует product request path и использует bounded concurrency/backoff **And** quota pressure не расходует PostgreSQL/artifact reserve. **Given** shutdown или restart **When** admission прекращён **Then** exporter flushes в bounded timeout, сохраняет остаток на disk и безопасно продолжает после запуска **And** product graceful shutdown остаётся в пределах 30 секунд. **Given** spool fault suite **When** моделируются crash during append/ack/compaction, corrupt tail, duplicate record и permission failure **Then** acknowledged/unacknowledged accounting детерминировано восстанавливается без secret leakage **And** integration tests проходят для каждого secret-using process. ### Story 5.6: Учитывать telemetry loss и подтвердить capacity envelope **Depends on:** Story 5.5 **Work type:** qualification **Deliverable:** Учитывать telemetry loss и подтвердить capacity envelope. **Completion:** accepted evidence всех AC на указанном build/RC и среде; harness-only и внешний handoff не являются pass. As an оператор, I want видеть точную полноту telemetry и доказанный запас spool, So that потеря наблюдаемости не остаётся скрытой. **Requirements:** FR-29, FR-31 **Acceptance Criteria:** **Given** фактический p95 serialized trace size и configured production traffic **When** рассчитывается telemetry budget **Then** каждая destination выдерживает 30-hour spool envelope без eviction **And** невозможный envelope блокирует production readiness с required/available bytes. **Given** backend outage до 24 часов **When** telemetry продолжает генерироваться и backend восстанавливается **Then** 100% сохранённых envelopes доставляются в пределах 25 часов **And** ≥99.99% envelopes при здоровом backend подтверждённо доставляются за 60 секунд. **Given** corruption, quota exhaustion, permanent rejection или forced drop **When** envelope не может быть сохранён/доставлен **Then** атомарно создаётся локальный immutable Telemetry Loss Record с count, bytes, reason и time range **And** record не содержит sensitive payload и сам не зависит от failed exporter. **Given** telemetry health API/metrics **When** оператор проверяет систему **Then** видны backlog count/bytes/age, delivery latency, retries, rejects, loss и capacity forecast **And** saturation/loss создают actionable alert без ID в labels. **Given** 30-hour spool и fault-injection suites **When** моделируются outage, restart, disk-full, corrupt tail и backend recovery **Then** delivery/loss accounting сходится до каждого envelope, product SLO не ухудшается **And** observability overhead ≤5% p95 latency и ≤10% CPU подтверждён evidence artifact. ### Story 5.7: Завершить production technical metrics coverage **Depends on:** Story 5.6 **Work type:** implementation **Deliverable:** Завершить production technical metrics coverage. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want получать стабильные low-cardinality Prometheus metrics, So that могу измерять health, traffic, latency и saturation всех компонентов. **Requirements:** FR-32 **Acceptance Criteria:** **Given** typed registry из Story 1.6 и реализованные production subsystems **When** завершается technical metrics contract **Then** каждая metric имеет name, type, unit, help, label enum и documented histogram buckets **And** произвольные URL, IDs, error text, Agent/Tool names и user values не принимаются как labels. **Given** runtime traffic **When** выполняются Admin/MCP/upstream requests **Then** counters/histograms отражают rate, outcome class, duration, platform overhead, retries, response limits и saturation **And** labels используют только bounded route/method/stage enums. **Given** новый subsystem, queue, Task, spool или delivery adapter **When** его owning story добавляет instrumentation **Then** metric names/types/labels/buckets сначала регистрируются через typed `crank-metrics` contract и schema snapshot **And** capability не считается завершённой без применимых traffic/error/duration/saturation metrics и bounded-cardinality tests. **Given** MCP catalog и capability operations **When** клиенты выполняют negotiation/list/get/call **Then** доступны typed metrics по protocol family, capability, outcome и change signals **And** stable/experimental paths не смешиваются. **Given** metric-to-trace correlation **When** sampled observation имеет Trace ID **Then** correlation использует exemplar, а не label **And** отсутствие exemplar не влияет на aggregate. **Given** cardinality/contract tests **When** подаются миллионы distinct user values и malformed outcomes **Then** series count остаётся в documented budget, неизвестные enums нормализуются безопасно **And** metric schema snapshot, buckets и overhead benchmark проходят `just verify`. ### Story 5.8: Считать локальные бизнес-события и DAU **Depends on:** Story 5.7 **Work type:** implementation **Deliverable:** Считать локальные бизнес-события и DAU. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an владелец self-hosted установки, I want видеть adoption и activation без передачи usage наружу, So that могу оценивать ценность продукта внутри закрытого контура. **Requirements:** FR-33 **Acceptance Criteria:** **Given** успешные domain transitions **When** создаются/публикуются/call-ятся Operations, Agents, Resources, Prompts и Tasks **Then** PostgreSQL сохраняет typed idempotent ProductEvent с UTC timestamp, actor class и bounded dimensions **And** sensitive payload, secret, arbitrary name и raw identifier не входят в analytics dimensions. **Given** retry либо duplicate delivery одного domain transition **When** event записывается повторно **Then** idempotency key предотвращает double count **And** audit/event authority остаётся согласованной после restart. **Given** UTC rollup job **When** день закрывается или пересчитывается **Then** activation funnel, capability adoption, success outcomes и local usage агрегируются идемпотентно **And** DAU считается как уникальный Agent с валидным MCP request за UTC-день, admin activity показывается отдельно. **Given** последовательность first login/import/create, first publication, Agent binding и first successful MCP call **When** activation rollups пересчитываются **Then** локально доступны time-to-first-value, import-to-publish и Agent-to-first-call distributions с явными eligible denominators **And** повторные события, незавершённый onboarding и cross-day transitions не искажают SM-11…SM-13. **Given** funnel/dashboard query **When** выбран период **Then** bounded API возвращает documented denominators, exclusions и late-event watermark **And** empty/partial/stale states не представляются как нулевой usage. **Given** default Community configuration **When** продукт работает offline **Then** events и rollups остаются локальными, phone-home отсутствует **And** любой egress требует отдельного явного admin opt-in с preview и audit. **Given** event/rollup tests **When** проверяются duplicates, UTC boundary, late events, deleted/archived entities и 1M history scale **Then** результаты детерминированы и privacy contract соблюдён **And** golden aggregate fixtures проходят. ### Story 5.9: Поставлять защищённую Prometheus integration **Depends on:** Story 5.8 **Work type:** implementation **Deliverable:** Поставлять защищённую Prometheus integration. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want подключить Prometheus готовой конфигурацией, So that получаю защищённый bounded scrape без ручного восстановления contract. **Requirements:** FR-34 **Acceptance Criteria:** **Given** Community minimal profile **When** запускается Crank **Then** loopback metrics endpoint доступен health tooling без proprietary dependency **And** production profile может включить versioned Prometheus service одной командой. **Given** metrics endpoint на non-loopback interface **When** конфигурация валидируется **Then** обязательна отдельная machine authentication и TLS/trusted-proxy policy **And** Admin session/MCP key не используется как неявная замена. **Given** authorized scrape **When** Prometheus читает endpoint **Then** выдаётся bounded OpenMetrics payload из typed registry **And** unauthorized, slow-client и concurrent scrape paths не истощают runtime. **Given** packaged Prometheus assets **When** профиль развёрнут **Then** scrape config, recording rules и alert rules versioned, CI-validated и заменяемы совместимым endpoint **And** labels/buckets совпадают с shipped metric contract. **Given** config reload либо service outage **When** сбор временно прекращается **Then** product requests/readiness не зависят от Prometheus **And** локальная диагностика показывает scrape/auth configuration без secrets. **Given** integration/security suite **When** проверяются auth, TLS proxy, cardinality, rule syntax и Prometheus restart **Then** все supported deployment modes проходят **And** artifacts привязаны к build/config fingerprint. ### Story 5.10: Поставлять сменный notification gateway с Apprise adapter **Depends on:** Story 5.9 **Work type:** implementation **Deliverable:** Поставлять сменный notification gateway с Apprise adapter. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want отправлять provider-neutral уведомления через Apprise adapter, So that могу сменить delivery provider без изменения producers. **Requirements:** FR-35 **Acceptance Criteria:** **Given** оператор включает application alert delivery **When** выбирается packaged Apprise API profile либо operator-managed gateway endpoint **Then** поставляются versioned configuration и проверенный HTTP payload adapter к выбранному alert evaluator, secrets подключаются через refs/OpenBao, endpoint приватен и защищён authentication/TLS policy **And** gateway configuration key не считается authentication, Rust не получает embedded Python, внешние каналы выключены без opt-in, а profile smoke подтверждает отправку в контролируемый test receiver без реальных получателей. **Given** application producer либо alert evaluator ingress **When** создаётся уведомление **Then** используются общий versioned `NotificationMessage`, логический route reference и `NotificationSink` port; Apprise URLs/tags/keys/payload/HTTP codes изолированы в `AppriseNotificationSink` и provider configuration **And** общие bounded queue/retry/expiry, redaction и delivery accounting не зависят от provider; MCP protocol notifications не перенаправляются в этот gateway. **Given** Apprise sink и независимый recording/fault-injection test sink **When** composition/configuration переключает реализацию общего port **Then** одни и те же contract tests проходят без изменения producers, alert rules, UI и common dispatch policies, проверяя accepted/retryable/permanent/uncertain outcomes и отсутствие secret leakage **And** queued envelopes остаются provider-neutral, versioned route bindings предотвращают silent rerouting при изменении конфигурации; второй production provider или отдельный gateway process для доказательства не требуются. ### Story 5.11: Предоставить готовые Grafana dashboards и trace links **Depends on:** Story 5.10 **Work type:** implementation **Deliverable:** Предоставить готовые Grafana dashboards и trace links. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want открыть готовые dashboards с переходом от симптома к trace, So that могу быстро локализовать деградацию. **Requirements:** FR-34 **Acceptance Criteria:** **Given** production observability profile **When** Grafana стартует **Then** datasource provisioning и dashboards загружаются автоматически без proprietary plugin **And** credentials передаются refs/secrets, не входят в committed JSON/config. **Given** shipped dashboard set **When** оператор открывает Grafana **Then** доступны Overview, MCP/runtime, upstream, Tasks, DB/cache и funnel views, а Load Runs view имеет provisioned schema и явное состояние «capability ещё не реализована» до Story 6.6 **And** каждый panel использует versioned recording rules и документированные units. **Given** latency/error observation с exemplar **When** оператор выбирает точку или временной диапазон **Then** Grafana формирует validated link в GlitchTip по Trace ID **And** без exemplar сохраняется aggregate investigation path. **Given** selected release/component/environment **When** применяются dashboard variables **Then** queries bounded и не требуют user-controlled high-cardinality values **And** empty, missing datasource и stale-data states явно обозначены. **Given** dashboards на production-size metrics **When** выполняется provisioning/render smoke suite **Then** JSON schema, PromQL и links валидны, ключевые panels реализованных capabilities возвращают данные; реальные Load Runs series и полный render acceptance принадлежат Story 6.6 **And** snapshots/UIDs стабильны между совместимыми upgrades. ### Story 5.12: Измерять SLO через recording rules и dashboards **Depends on:** Story 5.9, Story 5.11 **Work type:** implementation **Deliverable:** Измерять SLO через recording rules и dashboards. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want видеть SLI, error budgets и burn-rate rules, So that оцениваю SLO по воспроизводимым series и denominators. **Requirements:** FR-35 **Acceptance Criteria:** **Given** versioned SLO specification **When** она публикуется **Then** заданы 30-day availability ≥99.95%, control-plane ≥99.9%, latency/platform overhead, execution success и Task-deadline objectives **And** для каждого SLI документированы numerator, denominator, exclusions, maintenance и missing-data behavior. **Given** recording rules **When** Prometheus вычисляет SLIs **Then** product-caused failures, safe saturation rejection, upstream failures и client errors классифицируются раздельно **And** classification совпадает со stable runtime outcome codes. **Given** 30-day window **When** Grafana отображает service level **Then** видны objective, current compliance, remaining/consumed error budget и trend **And** Task deadline и telemetry delivery/loss имеют отдельные panels. **Given** fast либо slow burn **When** multi-window thresholds превышены **Then** alert содержит severity, affected SLO, burn rate, dashboard и versioned runbook link **And** Critical alert не зависит от внешнего trace backend для базовой диагностики. **Given** synthetic good/bad series и missing scrapes **When** rule tests выполняются в CI **Then** alerts срабатывают/восстанавливаются в ожидаемых окнах без divide-by-zero или false green **And** alert/runbook coverage machine-checkable. ### Story 5.13: Доставлять application alerts через notification gateway **Depends on:** Story 5.10, Story 5.12 **Work type:** implementation **Deliverable:** Доставлять application alerts через notification gateway. **Completion:** outcome этой story и все её AC проверены; будущая qualification не выполняется попутно. As an оператор, I want получать firing/resolved application alerts, So that реагирую на сбои без notification storm и зависимости product requests от gateway. **Requirements:** FR-35 **Acceptance Criteria:** **Given** каталог application alerts **When** определяются сигналы и runbooks **Then** покрываются API/MCP/runtime errors и latency, Tasks/queues, telemetry loss и application SLO; хосты/LXC/VM, сеть, диски и инфраструктурные сервисы остаются ответственностью владельца инфраструктуры **And** application-visible dependency failures диагностируются без изменения SLI exclusions; независимая проверка полной недоступности Crank/notification stack явно передана владельцу инфраструктуры, а не обещана самим остановленным приложением. **Given** firing, repeated и resolved состояния одного application alert **When** alert evaluator и notification adapter передают событие в Apprise API **Then** stable fingerprint, grouping, bounded repeat rate и silence policy предотвращают notification storm; уведомление содержит severity, component, безопасное summary и runbook/dashboard links, trace link только при наличии релевантного trace **And** configured receiver получает проверяемые firing/resolved уведомления; grouping/deduplication принадлежат явно указанному evaluator/adapter, а не неявной гарантии Apprise. **Given** slow/unavailable gateway, partial channel failure, timeout после отправки либо restart dispatcher **When** доставка не подтверждена **Then** queue, retry/backoff, attempts и expiry ограничены; rejected/accepted/uncertain outcomes различимы, возможные повторы не скрываются, ошибки и исчерпание budget видны в локальных logs/metrics без рекурсивного alert loop **And** notification I/O не блокирует product requests/readiness, API acceptance не выдаётся за human receipt и exactly-once delivery не обещается. **Given** real-stack notification suite и canary secrets **When** проверяются routing, firing/resolved, duplicates/silence, outage/recovery, unauthorized ingress, redaction и disabled external egress **Then** контролируемый receiver подтверждает expected messages, секреты и raw payload не попадают в уведомления/diagnostics, arbitrary targets/attachments отклоняются **And** tests не отправляют реальные сообщения операторам; evidence связывает rules, adapter и pinned gateway/config versions с тем же candidate. **Given** завершение Epic 5 **When** correlation, telemetry, metrics и dashboards проходят real-stack validation **Then** FR-27…FR-35 и NFR-O1…O5 имеют linked evidence **And** любой test request находится по Trace ID локально и в GlitchTip.